codeep 1.3.42 → 2.0.1

package/dist/acp/protocol.d.ts

@@ -61,9 +61,18 @@ export interface InitializeResult {
 }
 export interface McpServer {
     name: string;
-    command: string;
-    args: string[];
+    /** Spawn command (stdio transport). Mutually exclusive with `url`. */
+    command?: string;
+    args?: string[];
     env?: Record<string, string>;
+    /**
+     * If set, the client uses MCP Streamable HTTP transport against this URL
+     * instead of spawning a child process. Per spec, the same endpoint
+     * accepts POST (request) and GET (server-side SSE stream).
+     */
+    url?: string;
+    /** Optional headers for the HTTP transport (Authorization etc.). */
+    headers?: Record<string, string>;
 }
 export interface SessionMode {
     id: string;

package/dist/acp/server.js

@@ -6,6 +6,10 @@ import { readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import { StdioTransport } from './transport.js';
 import { runAgentSession } from './session.js';
+import { loadCustomCommands } from '../utils/customCommands.js';
+import { registerSessionServers, disposeSession as disposeMcpSession, disposeAllSessions as disposeAllMcpSessions } from '../utils/mcpRegistry.js';
+import { loadMcpServerConfig, mergeMcpServers } from '../utils/mcpConfig.js';
+import { handleMcpSamplingRequest } from '../utils/mcpSamplingBridge.js';
 import { executeCommandAsync } from '../utils/shell.js';
 import { initWorkspace, loadWorkspace, handleCommand } from './commands.js';
 import { autoSaveSession, config, setProvider, setApiKey, listSessionsWithInfo, deleteSession as deleteSessionFile } from '../config/index.js';
@@ -22,6 +26,7 @@ const AVAILABLE_COMMANDS = [
     { name: 'help', description: 'Show available commands' },
     { name: 'status', description: 'Show current config and session info' },
     { name: 'version', description: 'Show version and current model' },
+    { name: 'provider', description: 'List or switch provider', input: { hint: '<provider-id>' } },
     { name: 'model', description: 'List or switch model', input: { hint: '<model-id>' } },
     { name: 'login', description: 'Set API key for a provider', input: { hint: '<providerId> <apiKey>' } },
     { name: 'apikey', description: 'Show or set API key for current provider', input: { hint: '<key>' } },
@@ -38,13 +43,24 @@ const AVAILABLE_COMMANDS = [
     { name: 'undo', description: 'Undo last agent action' },
     { name: 'undo-all', description: 'Undo all agent actions in session' },
     { name: 'changes', description: 'Show all changes made in session' },
+    { name: 'cost', description: 'Show per-session token usage and estimated cost' },
+    { name: 'compact', description: 'Summarize older messages to free up context', input: { hint: '[keepN]' } },
+    { name: 'checkpoint', description: 'Save a named snapshot of the current session (or `delete <id>`)', input: { hint: '[name] | delete <id>' } },
+    { name: 'checkpoints', description: 'List saved checkpoints in this workspace' },
+    { name: 'rewind', description: 'Restore a session checkpoint by id', input: { hint: '<id>' } },
+    { name: 'hooks', description: 'List installed lifecycle hooks in .codeep/hooks/' },
+    { name: 'mcp', description: 'Manage MCP servers, marketplace, resources, prompts', input: { hint: '[browse | install <id> | add | remove | reload | resources | read <uri> | prompts | prompt <server> <name>]' } },
+    { name: 'openrouter', description: 'OpenRouter routing preferences (prefer/ignore/fallbacks/privacy/clear)', input: { hint: '[show | prefer <p,...> | ignore <p,...> | fallbacks on|off | privacy strict|allow | clear]' } },
     { name: 'export', description: 'Export conversation', input: { hint: 'json | md | txt' } },
     // Project intelligence
     { name: 'scan', description: 'Scan project structure and generate summary' },
     { name: 'review', description: 'Run code review on project or specific files', input: { hint: '[file…]' } },
     { name: 'learn', description: 'Learn coding preferences from project files' },
-    // Skills
-    { name: 'skills', description: 'List all available skills', input: { hint: '[query]' } },
+    { name: 'memory', description: 'Project memory notes — add / list / remove / clear', input: { hint: '<note> | list | remove <n> | clear' } },
+    { name: 'profile', description: 'Save / load / delete provider+model presets', input: { hint: 'save | load | delete | list | <name>' } },
+    // Skills + custom commands
+    { name: 'skills', description: 'List/create/share skill bundles. Subcommands: bundles, create-bundle, show, publish, install, browse, unpublish', input: { hint: '[query] | bundles | create-bundle <name> | show <name> | publish <slug> [--public] | install <owner>/<slug> | browse [q] | unpublish <owner>/<slug>' } },
+    { name: 'commands', description: 'List user-authored commands from .codeep/commands/*.md' },
     { name: 'commit', description: 'Generate commit message and commit' },
     { name: 'fix', description: 'Fix bugs or issues' },
     { name: 'test', description: 'Write or run tests' },
@@ -313,6 +329,29 @@ export function startAcpServer() {
     const transport = new StdioTransport();
     // ACP sessionId → full AcpSession (includes history + codeep session tracking)
     const sessions = new Map();
+    // Tear down all MCP child processes when the CLI dies. Without this,
+    // killing `codeep acp` with Ctrl+C orphans any servers we spawned —
+    // they keep running until the user hunts them down with `ps`.
+    // Register only once per process; if the user starts multiple ACP servers
+    // in the same process (we don't but be defensive) the second listener
+    // would double-fire.
+    const shutdownSignals = ['SIGINT', 'SIGTERM'];
+    let shuttingDown = false;
+    const onShutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        disposeAllMcpSessions().finally(() => {
+            // Mimic default Node exit behaviour after our cleanup runs.
+            process.exit(signal === 'SIGINT' ? 130 : 143);
+        });
+    };
+    for (const sig of shutdownSignals) {
+        // Only attach if nothing else has claimed the signal — Node prints
+        // a warning when listener count > 10 per signal.
+        if (process.listenerCount(sig) === 0)
+            process.on(sig, onShutdown);
+    }
     transport.start((msg) => {
         // Notifications have no id — handle separately
         if (!('id' in msg)) {
@@ -325,6 +364,9 @@ export function startAcpServer() {
                 handleInitialize(req);
                 break;
             case 'initialized': /* no-op acknowledgment */ break;
+            case 'authenticate':
+                handleAuthenticate(req);
+                break;
             case 'session/new':
                 handleSessionNew(req);
                 break;
@@ -397,10 +439,31 @@ export function startAcpServer() {
                 name: 'codeep',
                 version: getCurrentVersion(),
             },
-            authMethods: [],
+            // We advertise a single "agent"-typed auth method even though Codeep
+            // authenticates out-of-band (env var, `codeep` CLI `/login`, or the
+            // VS Code "Codeep: Set API Key" command). The acp-registry CI check
+            // requires at least one method with type `agent` or `terminal` — and
+            // having an entry here also gives Zed something to render in its
+            // "agent settings" surface so users discover where to put their key.
+            authMethods: [
+                {
+                    id: 'codeep-cli',
+                    name: 'Codeep CLI',
+                    description: 'Authenticate via the codeep CLI: run `codeep` and use `/login <provider> <key>`, ' +
+                        'set the provider\'s env var (e.g. ZAI_API_KEY), or use "Codeep: Set API Key" in VS Code.',
+                },
+            ],
         };
         transport.respond(msg.id, result);
     }
+    // ── authenticate ────────────────────────────────────────────────────────────
+    // We don't actually run anything here — auth is handled out-of-band (env
+    // var, CLI /login, VS Code command). But per ACP spec the client may still
+    // dispatch authenticate after reading our advertised methods. Reply with
+    // empty success so the client unblocks and proceeds to session/new.
+    function handleAuthenticate(msg) {
+        transport.respond(msg.id, {});
+    }
     // ── helpers ──────────────────────────────────────────────────────────────────
     // Title hint to the client. The ACP spec does NOT define a
     // `session_info_update` variant — sending it caused Zed's internally-tagged
@@ -414,10 +477,51 @@ export function startAcpServer() {
     function sendSessionTitle(_sessionId, _history, _fallback) {
         // intentionally empty — see comment above
     }
+    /**
+     * Background-spawn MCP servers for a session, merging two sources:
+     *
+     *   1. On-disk config (`.codeep/mcp_servers.json` project + global) —
+     *      so a user who just runs `codeep acp` (no Zed-style settings UI)
+     *      can still drive MCP setup by editing a file.
+     *   2. `mcpServers` passed in the session/* params — clients that have
+     *      their own config (Zed, Claude Desktop) keep using that. ACP-
+     *      provided servers override file entries with the same name.
+     *
+     * Don't block the session/* response on process startup (a hung MCP
+     * server would otherwise keep the chat from opening). Errors are logged
+     * + cached for /mcp display. `mcpRegistry.callSessionTool` awaits the
+     * in-flight registration so tool calls don't race the startup.
+     */
+    function spawnMcpServersForSession(acpSessionId, cwd, acpServers, label) {
+        const fromConfig = loadMcpServerConfig(cwd);
+        const merged = mergeMcpServers(fromConfig, acpServers);
+        if (merged.length === 0)
+            return;
+        registerSessionServers(acpSessionId, merged, {
+            workspaceRoot: cwd,
+            // Servers that opted into the `sampling` capability can ask us to
+            // run a completion on their behalf. We bridge to chat() through
+            // mcpSamplingBridge — using the user's currently active provider
+            // and key. The bridge enforces a per-server rate limit + budget cap
+            // so a misbehaving server can't drain the user's API credits.
+            onSamplingRequest: (params, serverName) => handleMcpSamplingRequest(params, serverName),
+        })
+            .then(({ registered, errors }) => {
+            if (registered.length > 0) {
+                process.stderr.write(`[codeep-acp] MCP (${label}): registered ${registered.length} tool(s) from ${merged.length} server(s)\n`);
+            }
+            for (const e of errors) {
+                process.stderr.write(`[codeep-acp] MCP server "${e.server}" failed (${label}): ${e.error}\n`);
+            }
+        })
+            .catch(err => process.stderr.write(`[codeep-acp] MCP registration crashed (${label}): ${err.message}\n`));
+    }
     // ── session/new ─────────────────────────────────────────────────────────────
     function handleSessionNew(msg) {
         const params = msg.params;
         const acpSessionId = randomUUID();
+        // Spin up MCP servers in the background. Errors surface via /mcp.
+        spawnMcpServersForSession(acpSessionId, params.cwd, params.mcpServers, 'session/new');
         const { codeepSessionId, history, welcomeText } = initWorkspace(params.cwd, params.fresh);
         sessions.set(acpSessionId, {
             sessionId: acpSessionId,
@@ -443,7 +547,7 @@ export function startAcpServer() {
         // in a separate task). Without the delay the notification arrives ~1 ms
         // after the response and gets lost, which manifests as
         // "Available commands: none" in the slash menu.
-        sendCommandsDelayed(acpSessionId);
+        sendCommandsDelayed(acpSessionId, params.cwd);
         // Send title immediately so Zed "Recent" panel shows something useful
         sendSessionTitle(acpSessionId, history, pathBasename(params.cwd));
         // Send welcome message
@@ -459,13 +563,36 @@ export function startAcpServer() {
     // 200 ms is comfortably above the observed ~1 ms race window without
     // making the slash menu feel laggy on first paint.
     const COMMANDS_DELAY_MS = Number(process.env.CODEEP_ACP_COMMANDS_DELAY_MS ?? 200);
-    function sendCommandsDelayed(sessionId) {
+    /**
+     * Build the autocomplete catalog for a session: built-in commands plus any
+     * user-authored Markdown templates under `.codeep/commands/`. Custom ones
+     * are tagged in the description so the user can tell them apart from
+     * built-ins in Zed / VS Code dropdowns.
+     */
+    function getAvailableCommandsForSession(workspaceRoot) {
+        try {
+            const custom = loadCustomCommands(workspaceRoot).map(c => ({
+                name: c.name,
+                description: `[${c.scope === 'project' ? 'project' : 'global'}] ${c.description}`,
+                input: { hint: '[args]' },
+            }));
+            // Custom commands can't override built-ins (would break /help, /status etc.)
+            const builtinNames = new Set(AVAILABLE_COMMANDS.map(c => c.name));
+            const safeCustom = custom.filter(c => !builtinNames.has(c.name));
+            return [...AVAILABLE_COMMANDS, ...safeCustom];
+        }
+        catch {
+            // Custom-command loading must never block the autocomplete catalog.
+            return AVAILABLE_COMMANDS;
+        }
+    }
+    function sendCommandsDelayed(sessionId, workspaceRoot) {
         setTimeout(() => {
             transport.notify('session/update', {
                 sessionId,
                 update: {
                     sessionUpdate: 'available_commands_update',
-                    availableCommands: AVAILABLE_COMMANDS,
+                    availableCommands: getAvailableCommandsForSession(workspaceRoot),
                 },
             });
         }, COMMANDS_DELAY_MS);
@@ -478,6 +605,9 @@ export function startAcpServer() {
         if (existing) {
             // Session already in memory — update cwd if changed
             existing.workspaceRoot = params.cwd;
+            // Re-spawn any MCP servers the client passed in (they may have changed
+            // since session/new; old ones get disposed by registerSessionServers).
+            spawnMcpServersForSession(params.sessionId, params.cwd, params.mcpServers, 'session/load (warm)');
             const result = {
                 modes: AGENT_MODES,
                 configOptions: buildConfigOptions(),
@@ -488,6 +618,7 @@ export function startAcpServer() {
         // Session not in memory — try to load from disk
         const { codeepSessionId, history, welcomeText } = loadWorkspace(params.cwd, params.sessionId);
         const acpSessionId = randomUUID();
+        spawnMcpServersForSession(acpSessionId, params.cwd, params.mcpServers, 'session/load (cold)');
         sessions.set(acpSessionId, {
             sessionId: acpSessionId,
             workspaceRoot: params.cwd,
@@ -508,7 +639,7 @@ export function startAcpServer() {
         transport.respond(msg.id, result);
         // Re-advertise commands (delayed for the same race-condition reason as
         // session/new — see sendCommandsDelayed comment).
-        sendCommandsDelayed(acpSessionId);
+        sendCommandsDelayed(acpSessionId, params.cwd);
         // Send title immediately so Zed "Recent" panel shows something useful
         sendSessionTitle(params.sessionId, history, pathBasename(params.cwd));
         // Send restored session welcome
@@ -530,6 +661,9 @@ export function startAcpServer() {
         const existing = sessions.get(params.sessionId);
         if (existing) {
             existing.workspaceRoot = params.cwd;
+            // Resume can carry an updated mcpServers list (e.g. workspace switched
+            // config) — re-register so old servers are torn down and new ones spawn.
+            spawnMcpServersForSession(params.sessionId, params.cwd, params.mcpServers, 'session/resume (warm)');
             const result = {
                 sessionId: params.sessionId,
                 modes: AGENT_MODES,
@@ -537,13 +671,14 @@ export function startAcpServer() {
             };
             transport.respond(msg.id, result);
             // Delayed — see sendCommandsDelayed comment for the race-condition rationale.
-            sendCommandsDelayed(params.sessionId);
+            sendCommandsDelayed(params.sessionId, params.cwd);
             return;
         }
         // Session not in memory — load from disk but skip the welcome banner and
         // the history echo (resume contract: client already has history).
         const { codeepSessionId, history } = loadWorkspace(params.cwd, params.sessionId);
         const acpSessionId = randomUUID();
+        spawnMcpServersForSession(acpSessionId, params.cwd, params.mcpServers, 'session/resume (cold)');
         sessions.set(acpSessionId, {
             sessionId: acpSessionId,
             workspaceRoot: params.cwd,
@@ -561,7 +696,7 @@ export function startAcpServer() {
             configOptions: buildConfigOptions(),
         };
         transport.respond(msg.id, result);
-        sendCommandsDelayed(acpSessionId);
+        sendCommandsDelayed(acpSessionId, params.cwd);
     }
     // ── session/set_mode ────────────────────────────────────────────────────────
     function handleSetMode(msg) {
@@ -672,6 +807,9 @@ export function startAcpServer() {
         const { sessionId, cwd } = (msg.params ?? {});
         // Remove from in-memory sessions map if present
         sessions.delete(sessionId);
+        // Tear down any MCP server processes attached to this session — leaks
+        // children otherwise. Fire-and-forget; client doesn't wait on stop().
+        disposeMcpSession(sessionId).catch(() => { });
         // Try project dir first, then global
         const deleted = deleteSessionFile(sessionId, cwd || undefined);
         if (!deleted && cwd)
@@ -707,12 +845,13 @@ export function startAcpServer() {
         // `available_commands_update` from session/new because the thread_view
         // isn't registered yet on Zed's side (race against the session/new
         // response). Re-sending here guarantees `/` autocomplete works by the
-        // time the user could plausibly type the next prompt.
+        // time the user could plausibly type the next prompt. Also picks up any
+        // custom command Markdown files the user added since session start.
         transport.notify('session/update', {
             sessionId: params.sessionId,
             update: {
                 sessionUpdate: 'available_commands_update',
-                availableCommands: AVAILABLE_COMMANDS,
+                availableCommands: getAvailableCommandsForSession(session.workspaceRoot),
             },
         });
         // Extract text from ContentBlock[]
@@ -927,6 +1066,35 @@ export function startAcpServer() {
                         return result.outcome.optionId;
                     }
                     : undefined,
+                // Per ACP spec, `fs/read_text_file` and `fs/write_text_file` are
+                // CLIENT methods — only safe to call when the client advertised
+                // the capability in `initialize`. Routing through the client
+                // means the editor's dirty buffers + undo history stay correct
+                // (otherwise an in-editor unsaved change would be invisible to
+                // the agent, or worse, silently overwritten).
+                fs: {
+                    readTextFile: clientSupportsFsRead
+                        ? async (absolutePath) => {
+                            const result = await transport.request('fs/read_text_file', {
+                                sessionId: params.sessionId,
+                                path: absolutePath,
+                            });
+                            if (!result || typeof result.content !== 'string') {
+                                throw new Error('fs/read_text_file returned no content');
+                            }
+                            return result.content;
+                        }
+                        : undefined,
+                    writeTextFile: clientSupportsFsWrite
+                        ? async (absolutePath, content) => {
+                            await transport.request('fs/write_text_file', {
+                                sessionId: params.sessionId,
+                                path: absolutePath,
+                                content,
+                            });
+                        }
+                        : undefined,
+                },
                 onExecuteCommand: async (command, args, cwd) => {
                     // Per ACP spec, only call terminal/* if the client advertised the
                     // capability in initialize. Otherwise execute locally.

package/dist/acp/session.d.ts

@@ -1,6 +1,7 @@
 import { PermissionOutcome } from '../utils/agent.js';
 import { ProjectContext } from '../utils/project.js';
 import { ToolCall } from '../utils/tools.js';
+import type { FsCallbacks } from '../utils/toolExecution.js';
 export interface AgentSessionOptions {
     prompt: string;
     workspaceRoot: string;
@@ -15,6 +16,8 @@ export interface AgentSessionOptions {
         stderr: string;
         exitCode: number;
     }>;
+    /** Optional fs delegation when the ACP client advertises `fs` capability. */
+    fs?: FsCallbacks;
 }
 /**
  * Build a ProjectContext from a workspace root directory.

package/dist/acp/session.js

@@ -146,6 +146,11 @@ export async function runAgentSession(opts) {
         },
         onRequestPermission: opts.onRequestPermission,
         onExecuteCommand: opts.onExecuteCommand,
+        fs: opts.fs,
+        // Route MCP-prefixed tool calls through the per-session registry.
+        // `conversationId` is the ACP session id, which is what
+        // registerSessionServers keyed by in server.ts handleSessionNew.
+        mcpSessionId: opts.conversationId,
     });
     // result.finalResponse is already emitted via onChunk streaming above;
     // only emit it here if nothing was streamed (e.g. non-streaming fallback path)

package/dist/api/index.js

@@ -7,6 +7,19 @@ import { logApiRequest, logApiResponse } from '../utils/logger.js';
 import { loadProjectIntelligence, generateContextFromIntelligence } from '../utils/projectIntelligence.js';
 import { loadProjectRules } from '../utils/agent.js';
 import { recordTokenUsage, extractOpenAIUsage, extractAnthropicUsage } from '../utils/tokenTracker.js';
+/**
+ * OpenRouter returns the authoritative per-call USD in `usage.cost` when
+ * the request opts in via `usage: { include: true }`. Pull it here so
+ * every chat() / streamChat() / etc. path records the real cost instead
+ * of our local pricing estimate. Returns undefined for non-OpenRouter
+ * providers or when the field is missing (older OpenRouter API responses).
+ */
+function openRouterReportedCost(providerId, data) {
+    if (providerId !== 'openrouter')
+        return undefined;
+    const cost = data?.usage?.cost;
+    return typeof cost === 'number' && Number.isFinite(cost) ? cost : undefined;
+}
 import { getTaskContextPrompt } from '../utils/taskContext.js';
 // Error messages by language
 const ERROR_MESSAGES = {
@@ -331,6 +344,21 @@ async function chatOpenAI(message, history, model, apiKey, onChunk, abortSignal)
     else {
         headers['x-api-key'] = apiKey;
     }
+    // OpenRouter: branding headers + opt in to `usage.cost` so the
+    // chat path reports authoritative per-call cost just like agentChat
+    // does. Kept identical to the agentChat block so the two paths stay
+    // in lockstep.
+    if (providerId === 'openrouter') {
+        headers['HTTP-Referer'] = 'https://codeep.dev';
+        headers['X-Title'] = 'Codeep';
+    }
+    // Lazy-loaded preferences object — only attached for openrouter so we
+    // never send the field to providers that don't understand it.
+    let openRouterProvider = undefined;
+    if (providerId === 'openrouter') {
+        const { readOpenRouterPreferences } = await import('../utils/openrouterPrefs.js');
+        openRouterProvider = readOpenRouterPreferences() ?? undefined;
+    }
     const requestBody = JSON.stringify({
         model,
         messages,
@@ -338,6 +366,8 @@ async function chatOpenAI(message, history, model, apiKey, onChunk, abortSignal)
         ...(stream ? { stream_options: { include_usage: true } } : {}),
         ...(omitTemperature ? {} : { temperature }),
         ...(useCompletionTokens ? { max_completion_tokens: maxTokens } : { max_tokens: maxTokens }),
+        ...(providerId === 'openrouter' ? { usage: { include: true } } : {}),
+        ...(openRouterProvider ? { provider: openRouterProvider } : {}),
     });
     try {
         // Use node:http for Ollama — bypasses undici connection pooling (AggregateError in Node v24)
@@ -358,7 +388,7 @@ async function chatOpenAI(message, history, model, apiKey, onChunk, abortSignal)
                 const parsed = JSON.parse(text);
                 const usage = extractOpenAIUsage(parsed);
                 if (usage)
-                    recordTokenUsage(usage, model, providerId);
+                    recordTokenUsage(usage, model, providerId, openRouterReportedCost(providerId, parsed));
                 return stripThinkTags(parsed.choices[0]?.message?.content || '');
             }
         }
@@ -373,13 +403,13 @@ async function chatOpenAI(message, history, model, apiKey, onChunk, abortSignal)
             throw new ApiError(`${getErrorMessage('apiError')}: ${parseApiError(response.status, body)}`, response.status);
         }
         if (stream && response.body) {
-            return handleOpenAIStream(response.body, onChunk);
+            return handleOpenAIStream(response.body, onChunk, providerId, model);
         }
         else {
             const data = await response.json();
             const usage = extractOpenAIUsage(data);
             if (usage)
-                recordTokenUsage(usage, model, config.get('provider'));
+                recordTokenUsage(usage, model, providerId, openRouterReportedCost(providerId, data));
             const content = data.choices[0]?.message?.content || '';
             return stripThinkTags(content);
         }
@@ -450,8 +480,9 @@ async function handleNodeStream(nodeStream, onChunk, model) {
                     }
                     if (parsed.usage) {
                         const usage = extractOpenAIUsage(parsed);
+                        const provider = config.get('provider');
                         if (usage)
-                            recordTokenUsage(usage, parsed.model || model, config.get('provider'));
+                            recordTokenUsage(usage, parsed.model || model, provider, openRouterReportedCost(provider, parsed));
                     }
                 }
                 catch { /* ignore parse errors */ }
@@ -466,7 +497,7 @@ async function handleNodeStream(nodeStream, onChunk, model) {
         });
     });
 }
-async function handleOpenAIStream(body, onChunk) {
+async function handleOpenAIStream(body, onChunk, providerId, modelOverride) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     const chunks = [];
@@ -494,8 +525,10 @@ async function handleOpenAIStream(body, onChunk) {
                         // Capture usage from final chunk (stream_options: include_usage)
                         if (parsed.usage) {
                             const usage = extractOpenAIUsage(parsed);
+                            const provider = providerId ?? config.get('provider');
+                            const m = parsed.model || modelOverride || 'unknown';
                             if (usage)
-                                recordTokenUsage(usage, parsed.model || 'unknown', config.get('provider'));
+                                recordTokenUsage(usage, m, provider, openRouterReportedCost(provider, parsed));
                         }
                     }
                     catch {

package/dist/config/index.d.ts

@@ -49,6 +49,14 @@ interface ConfigSchema {
     githubUsername: string;
     syncToken: string;
     deviceId: string;
+    /** OpenRouter provider-routing preferences (see utils/openrouterPrefs.ts). */
+    openrouterPreferences?: {
+        order?: string[];
+        allow_fallbacks?: boolean;
+        ignore?: string[];
+        data_collection?: 'allow' | 'deny';
+        require_parameters?: boolean;
+    };
 }
 export type { AgentMode };
 export type { LanguageCode };
@@ -105,6 +113,11 @@ export declare function getCurrentProvider(): {
 };
 export declare function setProvider(providerId: string): boolean;
 export declare function getModelsForCurrentProvider(): Record<string, string>;
+export declare function fetchOpenRouterModels(apiKey?: string): Promise<{
+    id: string;
+    name: string;
+    description: string;
+}[] | null>;
 export declare function fetchOllamaModels(baseUrl?: string): Promise<{
     id: string;
     name: string;

package/dist/config/index.js

@@ -466,6 +466,51 @@ export function getModelsForCurrentProvider() {
     }
     return models;
 }
+let openRouterCache = null;
+const OPENROUTER_CACHE_TTL_MS = 5 * 60 * 1000;
+export async function fetchOpenRouterModels(apiKey) {
+    if (openRouterCache && Date.now() - openRouterCache.fetchedAt < OPENROUTER_CACHE_TTL_MS) {
+        return openRouterCache.models;
+    }
+    try {
+        const headers = { 'Accept': 'application/json' };
+        if (apiKey)
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        const res = await fetch('https://openrouter.ai/api/v1/models', {
+            headers,
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        if (!Array.isArray(data.data))
+            return null;
+        // Format pricing for the dropdown description so users can pick cheap
+        // models without leaving the picker. OpenRouter returns USD-per-token
+        // as strings like "0.000003" — multiply by 1M for the per-1M figure
+        // most users think in.
+        const models = data.data
+            .filter(m => typeof m.id === 'string')
+            .map(m => {
+            const inPrice = m.pricing?.prompt ? Number(m.pricing.prompt) * 1_000_000 : null;
+            const outPrice = m.pricing?.completion ? Number(m.pricing.completion) * 1_000_000 : null;
+            const priceStr = inPrice !== null && outPrice !== null
+                ? ` · $${inPrice.toFixed(2)} in / $${outPrice.toFixed(2)} out per 1M`
+                : '';
+            const ctxStr = m.context_length ? ` · ${Math.round(m.context_length / 1000)}K ctx` : '';
+            return {
+                id: m.id,
+                name: m.name ?? m.id,
+                description: (m.description?.slice(0, 80) ?? 'OpenRouter model') + priceStr + ctxStr,
+            };
+        });
+        openRouterCache = { fetchedAt: Date.now(), models };
+        return models;
+    }
+    catch {
+        return null;
+    }
+}
 export async function fetchOllamaModels(baseUrl) {
     const url = (baseUrl || config.get('ollamaUrl') || 'http://localhost:11434').replace(/\/$/, '');
     try {