Skip to content

Commit 2deff26

Browse files
foxy1402foxy1402
committed
Add tool-calling support and dashboard login
Introduce initial tool-calling support and consolidate dashboard login into the main UI. Highlights: - Add detailed contributor/copilot instructions (.github/copilot-instructions.md). - Document Tool Calling in README and note supported built-in qodercli tools. - Extend src/helpers/format.js: reorder/expand model catalogue; add extractToolCalls, buildToolCallStreamChunk, and buildFullChatResponseWithTools to surface qoder tool-calls in OpenAI-compatible responses. - Update src/helpers/spawn.js: add process debug logging and change stream parsing to accumulate stdout and parse JSON lines on end (with invalid-JSON skipping); improved lifecycle logs and timeout handling. - Update src/routes/chat.js: accept tools/tool_choice fields, emit streaming tool-call chunks, include tool-calls in non-streaming responses, and avoid killing child for non-streaming requests; use merged response builders. - Small change in src/routes/completions.js to not kill child on non-streaming client disconnects. - Merge dashboard login into src/dashboard/public/index.html (remove separate login.html), add login styles and client script to toggle login/dashboard views; route /dashboard/login now serves index.html. - Add child-kill logging in dashboard API and minor server startup tweak in src/server.js. - Remove test-proxy.py and test-stream.ps1 test scripts. Notes: - This commit introduces initial tool-call plumbing but logs indicate tool mapping is not fully implemented; streaming-parsing behavior was changed and may impact realtime SSE semantics.
1 parent f08c7e8 commit 2deff26

12 files changed

Lines changed: 507 additions & 236 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Copilot Instructions - Qoder OpenAI Proxy
2+
3+
## Project Overview
4+
5+
This is an OpenAI-compatible API proxy for Qoder CLI (qodercli). It translates OpenAI-format API requests into qodercli commands, enabling any OpenAI-compatible tool (Cursor, LangChain, Open WebUI) to use Qoder models.
6+
7+
Key responsibilities:
8+
- Accept /v1/chat/completions and /v1/completions requests in OpenAI format
9+
- Spawn qodercli child processes with appropriate model/prompt arguments
10+
- Stream responses back to clients via Server-Sent Events (SSE)
11+
- Provide a web dashboard for testing and monitoring at /dashboard/
12+
13+
## Build, Test, and Run
14+
15+
Start server (development):
16+
npm run dev # Runs with --watch for auto-reload on file changes
17+
18+
Start server (production):
19+
npm start # Runs src/server.js directly
20+
21+
Docker:
22+
docker build -t qoder-proxy .
23+
docker run -p 3000:3000 -e QODER_PERSONAL_ACCESS_TOKEN="..." -e PROXY_API_KEY="..." qoder-proxy
24+
25+
No tests or linters are configured.
26+
27+
## Architecture
28+
29+
### Core Flow
30+
31+
Client → Express → Auth → Routes → spawn.js → qodercli (child process) → Parse stream-json output → SSE/JSON response
32+
33+
1. Routes (src/routes/) receive OpenAI-format requests
34+
2. format.js translates OpenAI model names → Qoder tiers and converts messages[] → single prompt string
35+
3. spawn.js spawns qodercli -p <prompt> -f stream-json --model <tier> as a child process
36+
4. Stream parsing reads line-delimited JSON from stdout, extracts text, and sends SSE chunks
37+
5. Logging (logStore.js) captures all requests/responses in RAM (circular buffer, max 500 entries)
38+
39+
### Key Components
40+
41+
| Component | Purpose |
42+
|-----------|---------|
43+
| src/server.js | Express app setup, route mounting, startup health checks |
44+
| src/config.js | Central config from env vars (PORT, API keys, timeouts) |
45+
| src/helpers/spawn.js | Spawns qodercli, handles stdout/stderr, implements timeout logic |
46+
| src/helpers/format.js | Model mapping (OpenAI aliases → Qoder tiers), message→prompt conversion, response builders |
47+
| src/store/logStore.js | In-memory circular log buffer for requests + system events |
48+
| src/middleware/auth.js | Bearer token validation for /v1/* endpoints |
49+
| src/middleware/dashboardAuth.js | Cookie-based HMAC auth for /dashboard/* |
50+
| src/routes/chat.js | /v1/chat/completions endpoint (supports streaming + non-streaming) |
51+
| src/routes/completions.js | /v1/completions (legacy text completion) |
52+
| src/routes/dashboard.js | Dashboard UI + API endpoints for logs/playground |
53+
54+
## Key Conventions
55+
56+
### 1. Model Mapping Strategy
57+
58+
The proxy accepts OpenAI/Anthropic model names and maps them to Qoder tiers:
59+
60+
gpt-4, gpt-4o, claude-3.5-sonnet → auto (paid)
61+
o1, claude-3-opus → ultimate (paid)
62+
o1-mini, claude-3-sonnet → performance (paid)
63+
claude-3.5-haiku, gemini-flash → efficient (paid)
64+
gpt-3.5-turbo, gpt-4o-mini → lite (free)
65+
66+
- Direct Qoder tier names (auto, lite, etc.) pass through unchanged
67+
- Unknown names pass through as-is (allows custom model IDs)
68+
- Default model is lite if none specified
69+
- Model mapping logic lives in src/helpers/format.js (ALIAS_MAP and getModelMapping)
70+
71+
### 2. Qodercli Integration
72+
73+
Critical details:
74+
- Uses qodercli -p <prompt> -f stream-json --model <tier> for all requests
75+
- Parses line-delimited JSON from stdout (format: {"type":"assistant","subtype":"message","message":{...}})
76+
- Must handle both Windows (cmd.exe /c qodercli.cmd) and Unix (qodercli) spawn paths
77+
- Implements timeout killing (default 120s) to prevent hung processes
78+
- Cleans up child processes on client disconnect (req.on('close'))
79+
80+
Never:
81+
- Buffer full response before sending (breaks streaming)
82+
- Forget to kill child processes on errors or timeouts
83+
- Parse non-JSON lines (some lines may be warnings/errors)
84+
85+
### 3. Message → Prompt Conversion
86+
87+
OpenAI messages array → single prompt string for qodercli (src/helpers/format.js — messagesToPrompt):
88+
89+
- system messages → System: <content>
90+
- user messages → User: <content>
91+
- assistant messages → Assistant: <content>
92+
- Multi-part content [{type:'text', text:'...'}] → flattened to plain text
93+
- Last system message wins if multiple provided
94+
95+
### 4. Response Building
96+
97+
Two response formats:
98+
99+
- Streaming: SSE chunks with delta.content, final chunk with finish_reason, then [DONE]
100+
- Non-streaming: Full response with message.content
101+
102+
All responses follow OpenAI format (id, object, created, model, choices, usage).
103+
Response builders live in src/helpers/format.js (buildStreamChunk, buildDoneChunk, buildFullChatResponse, etc.).
104+
105+
### 5. Logging Architecture
106+
107+
All logging goes through src/store/logStore.js:
108+
109+
- addRequest(entry) — logs API requests with payload, status, duration
110+
- addSystem(message, level, source) — logs system events (startup, errors, auth)
111+
- Circular buffers (max 500 entries each by default)
112+
- Logs are RAM-only (cleared on restart)
113+
- Payloads are truncated to LOG_BODY_MAX_BYTES (default 8KB)
114+
115+
Console output format: [timestamp] METHOD /path → status (duration) [stream]
116+
117+
### 6. Authentication Patterns
118+
119+
Two auth systems:
120+
121+
/v1/* endpoints:
122+
- Bearer token auth (PROXY_API_KEY env var)
123+
- Skips auth entirely if PROXY_API_KEY not set
124+
- Middleware: src/middleware/auth.js
125+
126+
/dashboard/* routes:
127+
- Cookie-based HMAC session tokens
128+
- Login form at /dashboard/login (checks DASHBOARD_PASSWORD)
129+
- Token = base64url(timestamp.random.hmac(timestamp.random))
130+
- 7-day cookie expiry
131+
- Middleware: src/middleware/dashboardAuth.js
132+
133+
### 7. Error Handling
134+
135+
- 400 for invalid requests (missing messages, empty prompt)
136+
- 401 for auth failures
137+
- 500 for qodercli spawn errors or non-zero exit codes
138+
- 501 for unsupported endpoints (/v1/embeddings)
139+
- 504 for timeouts
140+
141+
Return OpenAI-format errors:
142+
{
143+
"error": {
144+
"message": "...",
145+
"type": "invalid_request_error|api_error|timeout_error|not_implemented_error",
146+
"code": "invalid_api_key|endpoint_not_supported|...",
147+
"details": "..." (optional, for debugging)
148+
}
149+
}
150+
151+
### 8. Environment Configuration
152+
153+
All config lives in src/config.js, loaded from .env:
154+
155+
Required for production:
156+
- QODER_PERSONAL_ACCESS_TOKEN — Qoder API credentials
157+
- PROXY_API_KEY — Bearer token for /v1/* auth
158+
- DASHBOARD_PASSWORD — Password for /dashboard/ access
159+
160+
Optional tuning:
161+
- PORT (default 3000)
162+
- QODER_TIMEOUT_MS (default 120000)
163+
- LOG_MAX_ENTRIES (default 500)
164+
- LOG_BODY_MAX_BYTES (default 8192)
165+
- CORS_ORIGIN (default *)
166+
- DASHBOARD_ENABLED (default true)
167+
- DASHBOARD_SECRET (auto-generated if not set)
168+
169+
## Common Tasks
170+
171+
### Adding a New Model Alias
172+
173+
Edit src/helpers/format.js:
174+
175+
1. Add to ALIAS_MAP (maps OpenAI name → qodercli tier)
176+
2. Add to OPENAI_ALIASES in src/routes/misc.js (for /v1/models endpoint)
177+
178+
### Adding a New Qoder Model
179+
180+
Edit src/helpers/format.js:
181+
182+
1. Add to QODER_MODELS array with {id, label, tier, description}
183+
184+
### Modifying Stream Parsing
185+
186+
Edit src/helpers/spawn.js — runQoderRequest():
187+
188+
- Look for data.type === 'assistant' && data.subtype === 'message'
189+
- Extract content via extractTextContent(data.message)
190+
- Handle stop_reason from data.message.stop_reason
191+
192+
### Changing Timeout Behavior
193+
194+
Edit QODER_TIMEOUT_MS in src/config.js or .env file.
195+
Timeout logic lives in src/helpers/spawn.js (setTimeout → child.kill()).
196+
197+
## Important Notes
198+
199+
- **RAM-only design**: All logs/state are in-memory. Restart = data loss.
200+
- **Process cleanup**: Always kill child processes on errors, timeouts, or client disconnects to avoid zombies.
201+
- **SSE headers**: Must set X-Accel-Buffering: no for nginx compatibility.
202+
- **Windows compatibility**: All child_process spawns check process.platform === 'win32' and use cmd.exe wrapper.
203+
- **No token counting**: Qoder CLI doesn't provide token usage — all usage fields return null.
204+
- **Embeddings not supported**: /v1/embeddings returns 501 with explanation.

‎README.md‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Use Qoder through any tool or library designed for OpenAI's API.
77

88
- **🔌 OpenAI-Compatible**: Drop-in API replacement for apps like Cursor, Cline, LangChain, and Open WebUI
99
- **💬 Full Chat Support**: Support for `/v1/chat/completions` (system messages, multi-turn history)
10+
- **🛠 Tool Calling**: Automatic tool execution (file operations, shell commands, code editing) with OpenAI-compatible responses
1011
- **⚡ Streaming**: Real-time SSE streaming responses without lag
1112
- **🔄 Intelligent Tier Mapping**: Seamless translation between OpenAI aliases (gpt-4, claude-3.5) and Qoder tiers (auto, ultimate, lite)
1213
- **📊 Admin Dashboard**: Built-in dark-themed web dashboard for testing, viewing live logs, and monitoring proxy health
@@ -117,10 +118,51 @@ curl http://localhost:3000/v1/chat/completions \
117118
}'
118119
```
119120

121+
## 🛠 Tool Calling
122+
123+
The proxy supports **automatic tool calling** using qodercli's built-in tools. When the AI needs to perform actions like creating files, running commands, or searching code, it will automatically use the appropriate tools and return the results in OpenAI-compatible format.
124+
125+
### Supported Built-in Tools
126+
127+
- **Write**: Create/modify files
128+
- **Read**: Read file contents
129+
- **Bash**: Execute shell commands
130+
- **Edit**: Make targeted file edits
131+
- **Grep**: Search text in files
132+
- **Glob**: Find files by pattern
133+
- **Task**: Delegate to specialized agents
134+
- **WebFetch**: Fetch web content
135+
- **ImageGen**: Generate images
136+
- And more...
137+
138+
### Example Tool Call Response
139+
140+
```json
141+
{
142+
"choices": [{
143+
"message": {
144+
"role": "assistant",
145+
"content": "Created hello.py with the requested code.",
146+
"tool_calls": [{
147+
"id": "call_123",
148+
"type": "function",
149+
"function": {
150+
"name": "Write",
151+
"arguments": "{\"file_path\": \"hello.py\", \"content\": \"print('Hello!')\"}"
152+
}
153+
}]
154+
},
155+
"finish_reason": "tool_calls"
156+
}]
157+
}
158+
```
159+
160+
Tools are automatically invoked based on the user's request—no manual tool definitions required!
161+
120162
## ⚠️ Limitations
121163
- **Embeddings**: Qoder does not support embeddings. Calling `/v1/embeddings` securely returns a `501 Not Implemented`.
122164
- **Token usage limits**: Request token tracking / `usage` payload properties return `null`.
123-
- **Function calling**: Not implemented by the Qoder CLI wrapper yet.
165+
- **Custom Tools**: Only qodercli's built-in tools are supported (Write, Read, Bash, Edit, etc.). Custom OpenAI-style function definitions are not yet supported.
124166

125167
## License
126168
MIT

‎src/dashboard/public/index.html‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,54 @@
66
<link rel="preconnect" href="https://fonts.googleapis.com">
77
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
88
<link rel="stylesheet" href="/dashboard/static/style.css">
9+
<style id="login-styles">
10+
/* Login-specific styles */
11+
.login-body{min-height:100vh;display:flex;align-items:center;justify-content:center;overflow:hidden}
12+
body.login-mode{min-height:100vh;display:flex;align-items:center;justify-content:center;overflow:hidden}
13+
body.login-mode::before{content:'';position:fixed;inset:0;background:radial-gradient(ellipse 80% 60% at 50% -10%,rgba(139,92,246,0.18),transparent);pointer-events:none;z-index:0}
14+
body.login-mode #app{display:none}
15+
body.login-mode #login-container{display:flex}
16+
#login-container{display:none;width:100%;justify-content:center;align-items:center;min-height:100vh}
17+
.login-card{background:var(--card);border:1px solid var(--border);border-radius:16px;padding:40px;width:100%;max-width:380px;box-shadow:0 24px 64px rgba(0,0,0,0.5);position:relative;z-index:1}
18+
.login-logo{display:flex;align-items:center;gap:10px;margin-bottom:28px}
19+
.login-logo-icon{width:38px;height:38px;background:linear-gradient(135deg,var(--accent),var(--accent2));border-radius:10px;display:flex;align-items:center;justify-content:center;font-weight:700;font-size:18px;color:#fff;flex-shrink:0}
20+
.login-logo-text{font-size:15px;font-weight:600;color:var(--text1)}
21+
.login-logo-sub{font-size:12px;color:var(--text2)}
22+
.login-card h1{font-size:22px;font-weight:700;margin-bottom:6px}
23+
.login-subtitle{font-size:13px;color:var(--text2);margin-bottom:28px}
24+
.login-field{margin-bottom:18px}
25+
.login-field label{display:block;font-size:12px;font-weight:500;color:var(--text2);margin-bottom:6px;letter-spacing:.03em;text-transform:uppercase}
26+
.login-field input[type=password]{width:100%;background:var(--surface);border:1px solid var(--border);color:var(--text1);border-radius:8px;padding:11px 14px;font-size:14px;font-family:inherit;outline:none;transition:border-color .2s}
27+
.login-field input[type=password]:focus{border-color:var(--accent)}
28+
.login-field input[type=password]::placeholder{color:var(--text3)}
29+
.login-btn{width:100%;padding:12px;background:linear-gradient(135deg,var(--accent),var(--accent2));color:#fff;border:none;border-radius:8px;font-size:14px;font-weight:600;font-family:inherit;cursor:pointer;transition:opacity .2s,box-shadow .2s;box-shadow:0 0 0 rgba(139,92,246,0)}
30+
.login-btn:hover{opacity:.9;box-shadow:0 0 24px rgba(139,92,246,0.35)}
31+
.login-error{background:rgba(239,68,68,.12);border:1px solid rgba(239,68,68,.3);color:#fca5a5;border-radius:8px;padding:10px 12px;font-size:13px;margin-bottom:16px;display:none}
32+
.login-error.show{display:block}
33+
</style>
934
</head>
1035
<body>
36+
<!-- Login View -->
37+
<div id="login-container">
38+
<div class="login-card">
39+
<div class="login-logo">
40+
<div class="login-logo-icon">Q</div>
41+
<div><div class="login-logo-text">Qoder Proxy</div><div class="login-logo-sub">Dashboard</div></div>
42+
</div>
43+
<h1>Sign In</h1>
44+
<p class="login-subtitle">Enter your dashboard password to continue</p>
45+
<div class="login-error" id="login-err">Incorrect password. Please try again.</div>
46+
<form method="POST" action="/dashboard/login">
47+
<div class="login-field">
48+
<label>Password</label>
49+
<input type="password" name="password" id="pw" autofocus placeholder="••••••••••••" required>
50+
</div>
51+
<button type="submit" class="login-btn">Sign In</button>
52+
</form>
53+
</div>
54+
</div>
55+
56+
<!-- Dashboard View -->
1157
<div id="app">
1258
<!-- Sidebar -->
1359
<aside id="sidebar">
@@ -66,6 +112,24 @@
66112
</main>
67113
</div>
68114
</div>
69-
<script src="/dashboard/static/app.js"></script>
115+
116+
<script>
117+
// Detect if we should show login or dashboard
118+
(function() {
119+
const isLoginPage = window.location.pathname === '/dashboard/login' || new URLSearchParams(location.search).get('error') === '1';
120+
121+
if (isLoginPage) {
122+
document.body.classList.add('login-mode');
123+
if (new URLSearchParams(location.search).get('error') === '1') {
124+
document.getElementById('login-err').classList.add('show');
125+
}
126+
} else {
127+
// Load dashboard app only if not on login page
128+
const script = document.createElement('script');
129+
script.src = '/dashboard/static/app.js';
130+
document.body.appendChild(script);
131+
}
132+
})();
133+
</script>
70134
</body>
71135
</html>

0 commit comments

Comments
 (0)