@oar-sh/oar 0.9.16 → 0.9.18

package/server/deepseek-worker/deepseek-claude-backend.mjs

@@ -0,0 +1,317 @@
+// The DeepSeek backend of the Claude session runner: everything that differs
+// when the CLI the runner drives talks to DeepSeek's Anthropic-compatible
+// endpoint instead of Anthropic.
+//
+// - The CLI's environment: the endpoint and the key as Claude Code's
+//   documented ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN, a Claude Code state
+//   directory of its own, no nonessential traffic, and nothing of the host's
+//   Claude login or of another Anthropic configuration. The endpoint, the
+//   key and everything else that routes the CLI's requests or decides whom
+//   it trusts (CLAUDE_CLI_PINNED_ENV: provider switches, credentials,
+//   proxies, TLS) are pinned again in the CLI's flag settings
+//   (liveFlagSettings), over the settings of the chat's folder.
+// - Hooks: none run, neither the user's nor the chat folder's, and no
+//   statusLine command (CLAUDE_CLI_KEY_CHAT_SETTINGS, on the command line).
+// - The model: DeepSeek's ids, with Claude Code's `[1m]` suffix so the CLI
+//   plans with the 1M window; helper calls (titles, summaries) go to flash.
+//   Claude Code's model aliases are pinned to the session's model
+//   (ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS/SONNET/FABLE_MODEL,
+//   CLAUDE_CODE_SUBAGENT_MODEL, CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL), so a
+//   sub-agent asked for as "opus" runs on it and not, by DeepSeek's mapping
+//   of a Claude id, on V4 Pro; a model switch respawns the CLI for the pins.
+//   A Claude id the CLI still names (a session spawned before the pins) is
+//   read as the DeepSeek model DeepSeek serves it with (deepseekServedModel).
+// - The effort: DeepSeek's low/high/max, which Claude Code sends as
+//   `output_config.effort` with adaptive thinking (captured 2026-10-24). It
+//   is applied at spawn (CLAUDE_CODE_EFFORT_LEVEL), so a change respawns the
+//   CLI between turns on the same session. There is no thinking-off level:
+//   Claude Code never sends `thinking: {type: disabled}` for these models.
+// - What it reports: no Claude plan usage and no Claude usage limit, but the
+//   CLI's token totals per model after each turn (POST
+//   /api/deepseek-plan-usage) for the DeepSeek card's estimated spend; images
+//   only to models that take them; DeepSeek's errors in its own words.
+//
+// Source for the endpoint and the variables: DeepSeek's Claude Code guide
+// (api-docs.deepseek.com, quick_start/agent_integrations/claude_code).
+
+import { deepseekAnthropicBaseUrl } from '../../shared/deepseek-api.mjs';
+import { isHostClaudeSessionVariable } from '../../shared/host-claude-session-env.mjs';
+import { CLAUDE_CLI_KEY_CHAT_SETTINGS, claudeCliPinnedEnv } from '../claude-worker/claude-cli-pinned-env.mjs';
+import {
+  DEEPSEEK_PROVIDER_TYPE,
+  DEFAULT_DEEPSEEK_MODEL,
+  deepseekModelAcceptsImages,
+  deepseekReasoningEffortFor,
+  deepseekServedModel,
+  isDeepSeekModelId,
+} from '../../shared/deepseek-models.mjs';
+
+const LONG_CONTEXT_SUFFIX = '[1m]';
+const LONG_CONTEXT_SUFFIX_PATTERN = /\[1m\]$/i;
+// Claude Code's helper model; DeepSeek's guide points it at flash.
+const HELPER_MODEL = 'deepseek-flash';
+// Claude Code's alias for its helper model. The other aliases ("opus",
+// "sonnet", "fable", and a sub-agent without a model) resolve to the pins
+// spawnEnv sets, that is to the session's model.
+const HELPER_ALIAS = 'haiku';
+// Where Claude Code reads the model behind each of its aliases, and the model
+// of sub-agents and workflow agents (the bundled CLI, 2026-10-24). All pinned
+// to the session's model; CLAUDE_CODE_SUBAGENT_MODEL_FORCE is left unset, so
+// a sub-agent asked for as "haiku" still runs on the helper model.
+const SESSION_MODEL_VARIABLES = Object.freeze([
+  'ANTHROPIC_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL',
+  'CLAUDE_CODE_SUBAGENT_MODEL',
+  'CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL',
+]);
+const HELPER_MODEL_VARIABLES = Object.freeze(['ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_SMALL_FAST_MODEL']);
+
+// Variables that would point the CLI at another Anthropic configuration or
+// hand it another credential. Every ANTHROPIC_* is dropped as well.
+const FOREIGN_CLI_VARIABLES = Object.freeze([
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  'CLAUDE_CODE_USE_ANTHROPIC_AWS',
+  'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD',
+  'CLAUDE_CODE_USE_MANTLE',
+  'CLAUDE_CODE_USE_GATEWAY',
+  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
+  'CLAUDE_CODE_SKIP_VERTEX_AUTH',
+  'CLAUDE_CODE_SKIP_FOUNDRY_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH',
+  'CLAUDE_CODE_SKIP_MANTLE_AUTH',
+  'CLAUDE_CODE_SUBAGENT_MODEL',
+  'CLAUDE_CODE_SUBAGENT_MODEL_FORCE',
+  'CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL',
+  'CLAUDE_CODE_EFFORT_LEVEL',
+  'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
+  // Claude Code's subprocess env scrub, if the host exports it: it forces the
+  // permission mode to default (a chat in plan mode could edit files) and
+  // runs every Bash command in a bubblewrap sandbox.
+  'CLAUDE_CODE_SUBPROCESS_ENV_SCRUB',
+  // What the relay hands its worker (session-worker-launch-service.mjs,
+  // TMUX_WORKER_EXPORTED_ENV_VARS): the worker's own settings, which neither
+  // Claude Code nor anything the agent runs reads. A shell of the agent's
+  // that starts a relay of its own would take the worker's kind, folders and
+  // tools file for its own. The relay's Claude configuration
+  // (CLAUDE_CONFIG_DIR, replaced below; CLAUDE_CODE_EXECUTABLE) is not on it.
+  'COPILOT_ALLOW_ALL',
+  'GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS',
+  'COPILOT_SDK_PATH',
+  'EXTENSION_PATH',
+  'COPILOT_MODEL',
+  'COPILOT_RELAY_MODEL',
+  'CLAUDE_RELAY_MODEL',
+  'CLAUDE_CLOUD_RELAY_MODEL',
+  'CURSOR_RELAY_MODEL',
+  'CURSOR_AGENT_STORE_DIR',
+  'GROK_RELAY_MODEL',
+  'GROK_CLI_COMMAND',
+  'GROK_ALWAYS_APPROVE',
+  'SESSION_ID',
+  'COPILOT_WORKSPACE_ROOT',
+  'INIT_CWD',
+]);
+// The same by prefix: the relay's folders, config, tools file, worker kind
+// and log file (COPILOT_WEB_RELAY_*), the Copilot provider settings, every
+// DeepSeek setting of the worker's (the key included: the CLI gets it as
+// ANTHROPIC_AUTH_TOKEN) and the relay's own OAR_* switches.
+const FOREIGN_CLI_PREFIXES = Object.freeze(['ANTHROPIC_', 'COPILOT_WEB_RELAY_', 'COPILOT_PROVIDER_', 'DEEPSEEK_', 'OAR_']);
+
+/**
+ * Whether a variable of the worker's stays out of the CLI's environment:
+ * another Anthropic configuration or credential, the relay's settings for
+ * its worker, or the host Claude Code session's variables when the relay was
+ * started from inside one (shared/host-claude-session-env.mjs; the launcher
+ * drops those for every worker, the backend again, so a CLI talking to
+ * DeepSeek never reads itself as a child of the host's session, however the
+ * worker was started).
+ */
+function isForeignCliVariable(key) {
+  return FOREIGN_CLI_VARIABLES.includes(key)
+    || FOREIGN_CLI_PREFIXES.some((prefix) => key.startsWith(prefix))
+    || isHostClaudeSessionVariable(key);
+}
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+function withoutSuffix(value) {
+  return text(value).replace(LONG_CONTEXT_SUFFIX_PATTERN, '');
+}
+
+/**
+ * The relay's id of a model the CLI names: "deepseek-flash[1m]" →
+ * "deepseek-flash"; a Claude id ("claude-opus-5-5", from a CLI spawned
+ * without the alias pins) → the DeepSeek model that served it; anything else
+ * as given, without the suffix.
+ */
+export function deepseekRelayModel(value) {
+  return deepseekServedModel(value) || withoutSuffix(value);
+}
+
+/** The id the CLI gets: the relay's id with the 1M suffix. */
+export function deepseekCliModel(value) {
+  const model = deepseekRelayModel(value);
+  return model ? `${model}${LONG_CONTEXT_SUFFIX}` : '';
+}
+
+/**
+ * The DeepSeek model a sub-agent runs on, from what the runner knows of it:
+ * the model its own frames name (a DeepSeek id, or a Claude id DeepSeek
+ * served), else the alias the spawning tool pinned ("haiku" is the helper
+ * model, every other alias the session's model), else the session's model.
+ */
+export function deepseekSubagentModel(value, sessionModel = '') {
+  const served = deepseekServedModel(value);
+  if (served) return served;
+  if (withoutSuffix(value).toLowerCase() === HELPER_ALIAS) return HELPER_MODEL;
+  return deepseekRelayModel(sessionModel);
+}
+
+/** The session model a CLI is pinned to, in the CLI's terms; unknown or none is the default model. */
+function pinnedCliModel(model) {
+  const relayModel = deepseekRelayModel(model);
+  return deepseekCliModel(isDeepSeekModelId(relayModel) ? relayModel : DEFAULT_DEEPSEEK_MODEL);
+}
+
+/**
+ * `{ code, guidance }` for a failed request DeepSeek has its own advice for,
+ * or null. Read from the HTTP status the result reports, else from the
+ * status the CLI quotes in its error text ("API Error: 402 …").
+ */
+export function describeDeepSeekFailure(errorText, { status = null } = {}) {
+  const message = text(errorText);
+  const code = Number(status);
+  if (code === 402 || /\b402\b|insufficient[ _]balance/i.test(message)) {
+    return {
+      code: 'deepseek-balance',
+      guidance: 'The DeepSeek account balance is used up. Top it up at https://platform.deepseek.com/top_up, then send the message again.',
+    };
+  }
+  if (code === 401 || /\b401\b|authentication[_ ]error|invalid api key/i.test(message)) {
+    return {
+      code: 'deepseek-api-key',
+      guidance: 'DeepSeek did not accept the API key. Check it in Settings → Providers → DeepSeek, then send the message again.',
+    };
+  }
+  if (code === 429 || /\b429\b|rate[_ ]limit/i.test(message)) {
+    return {
+      code: 'deepseek-rate-limit',
+      guidance: 'DeepSeek is at its concurrency limit for this account. Send the message again in a moment.',
+    };
+  }
+  return null;
+}
+
+export function createDeepSeekClaudeBackend({ env = process.env } = {}) {
+  const apiKey = text(env.DEEPSEEK_API_KEY);
+  const anthropicBaseUrl = deepseekAnthropicBaseUrl(text(env.DEEPSEEK_BASE_URL));
+  const configDir = text(env.DEEPSEEK_CLAUDE_CONFIG_DIR);
+
+  /** DeepSeek's level for a requested effort; unset and unknown are high. */
+  function effortFor(value) {
+    return deepseekReasoningEffortFor(value) || 'high';
+  }
+
+  /**
+   * The CLI's environment. Built from the worker's own (which must not reach
+   * the CLI as it is: it carries DEEPSEEK_API_KEY and possibly the host's
+   * Anthropic settings), so every Anthropic variable is replaced. `model` is
+   * the session's model, which every alias is pinned to.
+   */
+  function spawnEnv(baseEnv = process.env, { effort = '', model = '' } = {}) {
+    if (!apiKey) throw new Error('deepseek-api-key-not-configured');
+    if (!configDir) throw new Error('deepseek-config-dir-not-configured');
+    const next = {};
+    for (const [key, value] of Object.entries(baseEnv || {})) {
+      if (isForeignCliVariable(key)) continue;
+      next[key] = value;
+    }
+    next.ANTHROPIC_BASE_URL = anthropicBaseUrl;
+    next.ANTHROPIC_AUTH_TOKEN = apiKey;
+    // Every alias Claude Code resolves on its own ("opus", a sub-agent
+    // without a model) lands on the session's model: without a pin the CLI
+    // sends a Claude id, which DeepSeek serves by its own mapping
+    // (claude-opus → V4 Pro), off the model the chat is locked to.
+    const sessionModel = pinnedCliModel(model);
+    for (const key of SESSION_MODEL_VARIABLES) next[key] = sessionModel;
+    for (const key of HELPER_MODEL_VARIABLES) next[key] = HELPER_MODEL;
+    next.CLAUDE_CONFIG_DIR = configDir;
+    next.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = '1';
+    next.CLAUDE_CODE_EFFORT_LEVEL = effortFor(effort);
+    return next;
+  }
+
+  return {
+    id: DEEPSEEK_PROVIDER_TYPE,
+    providerType: DEEPSEEK_PROVIDER_TYPE,
+    label: 'DeepSeek',
+    configDir,
+    defaultModel: DEFAULT_DEEPSEEK_MODEL,
+    // Neither is DeepSeek's: Claude's plan windows and its usage limit.
+    reportsPlanUsage: false,
+    reportsUsageLimit: false,
+    // What it reports instead: the CLI's token totals per model, by the
+    // relay's model ids (relayModel); the relay books what each report adds.
+    // Claude Code's `total_cost_usd` is at Claude's prices and is not sent.
+    usageRoute: '/api/deepseek-plan-usage',
+
+    // A Claude id is not a model of DeepSeek's to request, only one it may
+    // have served (relayModel).
+    isModel: (value) => isDeepSeekModelId(withoutSuffix(value)),
+    cliModel: deepseekCliModel,
+    relayModel: deepseekRelayModel,
+    subagentModel: deepseekSubagentModel,
+    acceptsImages: (model) => deepseekModelAcceptsImages(deepseekRelayModel(model)),
+    describeFailure: describeDeepSeekFailure,
+
+    effortFor,
+    /** The SDK's `effort` option: DeepSeek's level. */
+    effortOption: effortFor,
+    /** DeepSeek always thinks (see the effort note above). */
+    thinkingEnabled: () => true,
+    /**
+     * What only a fresh CLI takes, the effort and the model the aliases are
+     * pinned to: a change respawns it between turns. `model` is the turn's
+     * resolved model (the runner's, not the message's alone).
+     */
+    spawnKey: (message = {}, { model = '' } = {}) => `${effortFor(message.reasoningEffort)} ${pinnedCliModel(model)}`,
+
+    spawnEnv,
+
+    /**
+     * The settings layer every CLI of this backend is spawned with, on its
+     * command line (no key in it): no hooks and no statusLine command, from
+     * the user's settings or the chat folder's. They would run with the key
+     * in their environment, a folder's SessionStart hook before the pins.
+     */
+    flagSettings: () => ({ ...CLAUDE_CLI_KEY_CHAT_SETTINGS }),
+
+    /**
+     * The CLI's routing, trust and credentials once more, in its flag
+     * settings layer, which outranks the settings of the chat's folder: a
+     * .claude/settings.json or settings.local.json there whose
+     * env.ANTHROPIC_BASE_URL, proxy or CA points elsewhere would otherwise
+     * get the DeepSeek key as its bearer token (scripts/deepseek-cli-proof.mjs).
+     * Every variable of CLAUDE_CLI_PINNED_ENV holds the value of `cliEnv`,
+     * the environment the CLI was spawned with (spawnEnv), or is blanked, and
+     * so is an apiKeyHelper of the folder's. The key may not go on the
+     * command line, so the adapter sends these over the control channel
+     * before the first message (startClaudeSession).
+     */
+    liveFlagSettings(cliEnv = spawnEnv(env)) {
+      if (!apiKey) throw new Error('deepseek-api-key-not-configured');
+      return {
+        env: { ...claudeCliPinnedEnv(cliEnv), ANTHROPIC_BASE_URL: anthropicBaseUrl, ANTHROPIC_AUTH_TOKEN: apiKey },
+        apiKeyHelper: '',
+      };
+    },
+  };
+}

package/server/deepseek-worker/deepseek-session-worker.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// DeepSeek session worker: the Claude session worker with its CLI pointed at
+// DeepSeek's Anthropic-compatible endpoint (deepseek-claude-backend.mjs). The
+// relay's launch puts the key in DEEPSEEK_API_KEY (through the owner-only
+// secret file under tmux) and names the worker's own Claude Code state
+// directory in DEEPSEEK_CLAUDE_CONFIG_DIR.
+import fs from 'node:fs';
+
+import { installWorkerLogFile, installWorkerLogRedaction } from '../../shared/worker-runtime/worker-log-file.mjs';
+import { runClaudeSessionWorker } from '../claude-worker/claude-session-worker-main.mjs';
+import { createDeepSeekClaudeBackend } from './deepseek-claude-backend.mjs';
+
+installWorkerLogFile();
+// The key never shows in this worker's console or log, whatever the CLI or
+// the agent prints (installed after the log file, so its copy is redacted too).
+installWorkerLogRedaction({ secrets: [process.env.DEEPSEEK_API_KEY] });
+
+const backend = createDeepSeekClaudeBackend({ env: process.env });
+
+// The worker reads the CLI's state too (the transcript a resume needs, the
+// workflow files): it has to look where its CLI writes, never in the host's
+// ~/.claude. The directory holds sessions, so only this user may open it.
+if (backend.configDir) {
+  fs.mkdirSync(backend.configDir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(backend.configDir, 0o700); } catch {}
+  process.env.CLAUDE_CONFIG_DIR = backend.configDir;
+}
+
+runClaudeSessionWorker({
+  logTag: 'deepseek-worker',
+  workerName: 'deepseek-session-worker',
+  defaultModel: String(process.env.DEEPSEEK_RELAY_MODEL || '').trim() || backend.defaultModel,
+  backend,
+}).catch((error) => {
+  console.error('deepseek-session-worker fatal:', error?.stack || error?.message || error);
+  process.exit(1);
+});

package/server/grok-worker/acp-client.mjs

@@ -358,7 +358,7 @@ export class AcpClient extends EventEmitter {
    * `holdStall` (async, optional) is asked once the inactivity window has run
    * out: `true` re-arms the full window instead of failing the prompt. It is
    * for work the agent is blocked on that this client cannot see — a
-   * remote_relay call the agent runs through its MCP server, which the relay
+   * relay_tool call the agent runs through its MCP server, which the relay
    * reports as in flight. A question that fails or takes longer than
    * `holdCheckTimeoutMs` counts as `false`.
    *

package/server/grok-worker/grok-turn-runner.mjs

@@ -134,7 +134,7 @@ export function createGrokTurnRunner({
 } = {}) {
   const terminalTasks = taskPublisher;
   // The OAR MCP server gives Grok the relay's real tools — `preview`, and
-  // `remote_relay` when remotes are paired — bound to this conversation.
+  // `relay_tool` when remotes are paired — bound to this conversation.
   // `OAR_MCP_SERVER=0` is the operator's way back to the preview instruction
   // block, should an agent build turn out to ignore ACP `mcpServers`.
   const oarMcpLaunch = oarMcpServer !== undefined
@@ -238,7 +238,7 @@ export function createGrokTurnRunner({
   }
 
   /**
-   * The inactivity hold. A remote_relay call runs inside the MCP server, which
+   * The inactivity hold. A relay_tool call runs inside the MCP server, which
    * this worker cannot see: Grok just goes quiet for as long as the relay
    * waits on the remote turn. Before the ACP watchdog calls that a stall, the
    * relay is asked whether a call of this conversation is still in flight.
@@ -247,7 +247,7 @@ export function createGrokTurnRunner({
    */
   async function remoteRelayCallInFlight() {
     const inflight = await fetchRemoteRelayInflight({ api, conversationId: sdkSessionId });
-    if (inflight > 0) dbg('remote_relay call in flight; holding the inactivity watchdog', String(inflight));
+    if (inflight > 0) dbg('relay_tool call in flight; holding the inactivity watchdog', String(inflight));
     return inflight > 0;
   }
 
@@ -447,7 +447,7 @@ export function createGrokTurnRunner({
     // absolute cap: "No limit" (0) must not be silently trimmed to the
     // 30-minute default. The inactivity watchdog stays — it detects a dead
     // transport, not a long turn — but asks the relay before it fires while
-    // Grok may be blocked on a remote_relay call.
+    // Grok may be blocked on a relay_tool call.
     const watchdog = {
       ...(turnCeilingMs !== null ? { maxTurnMs: turnCeilingMs > 0 ? turnCeilingMs : 0 } : {}),
       ...(acpMcpServers.length ? { holdStall: remoteRelayCallInFlight } : {}),

package/server/grok-worker/sdk-message-normalizer.mjs

@@ -64,7 +64,7 @@ export function summarizeToolInput(input) {
 }
 
 export function formatToolActivityText(toolName, input, title = '') {
-  // The OAR MCP server's `remote_relay`, however the agent labels it (bare,
+  // The OAR MCP server's `relay_tool`, however the agent labels it (bare,
   // or namespaced by the server), reads as what it does on which relay.
   if (isRemoteRelayToolName(toolName) || isRemoteRelayToolName(title)) {
     const remoteSummary = remoteRelayActivitySummary(input);

package/server/mcp/oar-mcp-server.mjs

@@ -2,7 +2,7 @@
 // OAR's own stdio MCP server. It gives the agents OAR launches without an
 // in-process tool surface — Grok (ACP `mcpServers`) and the Copilot CLI
 // extension engine (`--additional-mcp-config`) — the relay's real tools:
-// `remote_relay` and `preview`, bound to the one conversation it was started
+// `relay_tool` and `preview`, bound to the one conversation it was started
 // for, so the relay's mention gate and approval apply exactly as they do for
 // the Claude, Cursor and Copilot SDK workers.
 //
@@ -34,6 +34,7 @@ import {
   REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS,
   REMOTE_RELAY_TOOL_DESCRIPTION,
   REMOTE_RELAY_TOOL_NAME,
+  canonicalRemoteRelayToolCallName,
   cloneRemoteRelayToolInputSchema,
   executeRemoteRelayTool,
   formatRemoteRelayToolResult,
@@ -216,10 +217,15 @@ export function createOarMcpServer({
   }
 
   async function callTool(id, params) {
-    const name = toText(params?.name);
+    // `remote_relay`, the tool's name up to 0.9.17, still dispatches while
+    // the tool is on, but is never listed: a second definition would only
+    // cost context. The hosts in use (Grok, the Copilot CLI) call only what
+    // tools/list gave them, so for them the old name is gone; a client that
+    // kept it still works.
+    const name = canonicalRemoteRelayToolCallName(params?.name);
     const tools = await listTools();
     if (!tools.some((tool) => tool.name === name)) {
-      return fail(id, JSON_RPC.invalidParams, `Unknown tool: ${name || '(none)'}`);
+      return fail(id, JSON_RPC.invalidParams, `Unknown tool: ${toText(params?.name) || '(none)'}`);
     }
     const args = params?.arguments && typeof params.arguments === 'object' && !Array.isArray(params.arguments)
       ? params.arguments
@@ -348,7 +354,7 @@ export function createOarMcpServer({
 
 /**
  * The stdio process: parse the arguments, reach the relay like a worker does,
- * decide whether `remote_relay` is listed (asked once, at startup), then serve
+ * decide whether `relay_tool` is listed (asked once, at startup), then serve
  * until stdin closes. Returns the server, or null after a startup failure.
  */
 export async function runOarMcpServer({
@@ -413,7 +419,7 @@ export async function runOarMcpServer({
     remoteRelay: Promise.resolve()
       .then(() => shouldRegisterRemoteRelayToolImpl({ api }))
       .then((enabled) => {
-        log(`serving conversation ${conversationId.slice(0, 8)}; remote_relay ${enabled ? 'on' : 'off'}`);
+        log(`serving conversation ${conversationId.slice(0, 8)}; relay_tool ${enabled ? 'on' : 'off'}`);
         return enabled;
       }),
     version: readPackageVersion(),

package/server/migrations/0024-deepseek-usage-totals.mjs

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * Migration: DeepSeek usage totals (services/plan-usage-service.mjs, the
+ * DeepSeek card in Check Usage).
+ *
+ * `deepseek_usage_totals`: one row per DeepSeek model this relay's DeepSeek
+ * turns used, summed over every turn the workers reported
+ * (POST /api/deepseek-plan-usage). A row only ever grows.
+ *
+ * - `model`: the model's id as the CLI reported it, without Claude Code's
+ *   `[1m]` suffix, lower case.
+ * - `hit_tokens`, `miss_tokens`, `output_tokens`: input DeepSeek served from
+ *   its cache, input it did not, and output.
+ * - `turn_count`: the reports that named the model.
+ * - `cost_usd`, `cost_cny`: the estimate from shared/deepseek-pricing.mjs at
+ *   the price of each turn's own time (peak or off-peak); NULL while no turn
+ *   of the model could be priced (a model the price table does not know).
+ * - `first_seen_at`, `last_seen_at`: the earliest and latest turn time.
+ *
+ * `deepseek_usage_checkpoints`: what a worker last reported per
+ * (conversation, Claude Code session, model). A worker reports the CLI's
+ * running totals, and a CLI resumed on a session starts from that session's
+ * earlier totals, so the relay books only what a report adds to the totals
+ * last reported for the session: a restarted worker or a resumed CLI books
+ * nothing twice, and a new session starts from zero. A total below the
+ * checkpoint is a CLI counting from zero again: that report is booked in
+ * full and the checkpoint starts over from it.
+ *
+ * - `conversation_id`, `native_session_id` (the CLI's session id), `model`.
+ * - `hit_tokens`, `miss_tokens`, `output_tokens`: the totals last reported.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0024-deepseek-usage-totals.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const DEEPSEEK_USAGE_TOTALS_TABLE = 'deepseek_usage_totals';
+export const DEEPSEEK_USAGE_CHECKPOINTS_TABLE = 'deepseek_usage_checkpoints';
+
+export const DEEPSEEK_USAGE_TOTALS_COLUMNS = Object.freeze([
+  'model',
+  'hit_tokens',
+  'miss_tokens',
+  'output_tokens',
+  'turn_count',
+  'cost_usd',
+  'cost_cny',
+  'first_seen_at',
+  'last_seen_at',
+  'updated_at',
+]);
+
+export const DEEPSEEK_USAGE_CHECKPOINT_COLUMNS = Object.freeze([
+  'conversation_id',
+  'native_session_id',
+  'model',
+  'hit_tokens',
+  'miss_tokens',
+  'output_tokens',
+  'updated_at',
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+/** What keeps the service from using the table: '' when nothing does. */
+export function deepseekUsageTotalsTableProblem(db) {
+  for (const [table, columns] of [
+    [DEEPSEEK_USAGE_TOTALS_TABLE, DEEPSEEK_USAGE_TOTALS_COLUMNS],
+    [DEEPSEEK_USAGE_CHECKPOINTS_TABLE, DEEPSEEK_USAGE_CHECKPOINT_COLUMNS],
+  ]) {
+    if (!tableExists(db, table)) return `no ${table} table`;
+    const present = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+    const missing = columns.filter((name) => !present.has(name));
+    if (missing.length) return `${table} lacks ${missing.join(', ')}`;
+  }
+  return '';
+}
+
+export function migrateDeepSeekUsageTotals(db) {
+  let tablesAdded = 0;
+  if (!tableExists(db, DEEPSEEK_USAGE_CHECKPOINTS_TABLE)) {
+    db.exec(`
+      CREATE TABLE ${DEEPSEEK_USAGE_CHECKPOINTS_TABLE} (
+        conversation_id    TEXT NOT NULL,
+        native_session_id  TEXT NOT NULL,
+        model              TEXT NOT NULL,
+        hit_tokens         INTEGER NOT NULL DEFAULT 0,
+        miss_tokens        INTEGER NOT NULL DEFAULT 0,
+        output_tokens      INTEGER NOT NULL DEFAULT 0,
+        updated_at         TEXT NOT NULL,
+        PRIMARY KEY (conversation_id, native_session_id, model)
+      )
+    `);
+    tablesAdded += 1;
+  }
+  if (tableExists(db, DEEPSEEK_USAGE_TOTALS_TABLE)) return { applied: tablesAdded > 0, tablesAdded };
+  db.exec(`
+    CREATE TABLE ${DEEPSEEK_USAGE_TOTALS_TABLE} (
+      model          TEXT PRIMARY KEY,
+      hit_tokens     INTEGER NOT NULL DEFAULT 0,
+      miss_tokens    INTEGER NOT NULL DEFAULT 0,
+      output_tokens  INTEGER NOT NULL DEFAULT 0,
+      turn_count     INTEGER NOT NULL DEFAULT 0,
+      cost_usd       REAL,
+      cost_cny       REAL,
+      first_seen_at  TEXT NOT NULL,
+      last_seen_at   TEXT NOT NULL,
+      updated_at     TEXT NOT NULL
+    )
+  `);
+  tablesAdded += 1;
+  return { applied: true, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekUsageTotals(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0024 on ${dbPath}`);
+    console.log(result.applied ? `  deepseek usage totals: tables added ${result.tablesAdded}` : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0024 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}