@oar-sh/oar 0.9.16 → 0.9.17

package/server/copilot-worker/copilot-sdk-session-process.mjs

@@ -114,6 +114,11 @@ import { shouldEmitStreamUpdate } from '../../shared/stream-emit-gating.mjs';
 import { withSteerNote } from '../../shared/steer-note.mjs';
 import { isRelayAutomatedDelivery } from '../../shared/relay-events.mjs';
 import { isTransientRelayError } from '../../shared/worker-runtime/relay-errors.mjs';
+import {
+  isOpenAIImageTerminalError,
+  runDirectOpenAIImageTurn,
+  shouldUseDirectOpenAIImageApi,
+} from '../../shared/worker-runtime/direct-openai-image.mjs';
 import {
   createTurnLiveness,
   createTurnStalledError,
@@ -556,6 +561,12 @@ export function createCopilotSdkSessionRunner({
   // terminal error until the publish lands, so recovery can never re-run them
   // (see publishSettleMarker).
   const settlingMessages = new Map();
+  // Image-model rows running on the relay's image routes (id → message). They
+  // never reach the runtime, so no turn owns them; the heartbeat and the crash
+  // guard still have to.
+  const directImageMessages = new Map();
+  // `openai` on a BYOK worker; the failure notes name the provider.
+  const workerProvider = String(env.COPILOT_PROVIDER_TYPE || '').trim().toLowerCase();
   // Settle markers that could not be posted even terminally; the heartbeat
   // hands them to the relay to fail (id → terminalError).
   const settleFailedTerminals = new Map();
@@ -3728,7 +3739,7 @@ export function createCopilotSdkSessionRunner({
     // afterwards: a runtime that died or went silent under a Stop used to put
     // the watchdog's failure on every row instead.
     if (failure && !turn.aborted) {
-      const classified = classifyCopilotTurnException(failure);
+      const classified = classifyCopilotTurnException(failure, { provider: workerProvider });
       dbg('copilot turn failed', turn.message?.id || '(continuation)', classified.detail);
       const running = turn.currentOwner || turn.primaryEntry;
       for (const entry of pending) {
@@ -3747,7 +3758,7 @@ export function createCopilotSdkSessionRunner({
       return;
     }
     if (result?.isError) {
-      const classified = classifyCopilotSessionError(result.errorData || { message: result.errorMessage });
+      const classified = classifyCopilotSessionError(result.errorData || { message: result.errorMessage }, { provider: workerProvider });
       dbg('turn failed', turn.message?.id || '(continuation)', classified.stableCode);
       const running = turn.currentOwner || turn.primaryEntry;
       for (const entry of pending) {
@@ -4117,6 +4128,7 @@ export function createCopilotSdkSessionRunner({
           dbg('continuation output dropped (no relay row)');
           const classified = classifyCopilotTurnException(
             turn.failure || new Error('the relay refused a continuation row for this turn'),
+            { provider: workerProvider },
           );
           for (const entry of turn.entries) {
             if (entry.settled || entry.turn !== turn) continue;
@@ -4821,6 +4833,9 @@ export function createCopilotSdkSessionRunner({
   async function handlePendingPayload(pending) {
     const message = pending?.message || null;
     if (!message) return false;
+    // An image model is no chat model: its row goes to the relay's image
+    // routes, whatever the runtime is doing, and never into the runtime.
+    if (shouldUseDirectOpenAIImageApi(message)) return runDirectImageTurn(message);
     // Held (a card is open, a compaction is running, a tool of the main agent
     // is running, the turn-opening prompt is not sent yet): hand the row back
     // with no retry penalty; the relay re-delivers it when the hold ends. An
@@ -4850,7 +4865,7 @@ export function createCopilotSdkSessionRunner({
         if (outcome !== NOT_STEERED) return outcome;
       } catch (error) {
         dbg('steering failed', message.id, error?.message || String(error));
-        const classified = classifyCopilotTurnException(error);
+        const classified = classifyCopilotTurnException(error, { provider: workerProvider });
         await publishResponse(message, {
           text: classified.text,
           model: null,
@@ -4863,6 +4878,54 @@ export function createCopilotSdkSessionRunner({
     return runTurn(turn);
   }
 
+  /**
+   * One image-model row (shared/worker-runtime/direct-openai-image.mjs). With
+   * an image operation the relay's execute route publishes the reply, the
+   * failure or the requeue itself; without one the shared helper publishes
+   * the reply, and a refusal by the provider is published here as the row's
+   * failure. Anything else requeues the row, as on the extension engine.
+   */
+  async function runDirectImageTurn(message) {
+    const id = String(message.id || '');
+    directImageMessages.set(id, message);
+    touch();
+    try {
+      const result = await runDirectOpenAIImageTurn({
+        api,
+        message,
+        // An edit can take minutes, longer than fetch waits for headers.
+        requestOptions: { longCall: true },
+        responseFields: attemptFields(message),
+      });
+      dbg('image turn', message.id, result.via, result.outcome);
+    } catch (error) {
+      if (isOpenAIImageTerminalError(error)) {
+        dbg('image turn refused by OpenAI', message.id, error.message);
+        await publishResponse(message, {
+          text: error.message,
+          model: null,
+          terminalError: {
+            kind: 'openai-image-failed',
+            // The code the relay's image operation uses for the same refusal.
+            code: 'image-provider-rejected',
+            stableCode: 'image-provider-rejected',
+            message: error.message,
+            ...(error.detail ? { detail: String(error.detail) } : {}),
+            failedAt: new Date().toISOString(),
+            queueMessageId: id || null,
+          },
+        });
+      } else {
+        dbg('image turn failed; requeueing', message.id, error?.message || String(error));
+        await api('POST', '/api/requeue', { messageId: message.id, ...attemptFields(message) }).catch(() => {});
+      }
+    } finally {
+      directImageMessages.delete(id);
+      touch();
+    }
+    return true;
+  }
+
   // --------------------------------------------------------------- teardown --
 
   function getActiveQueueMessageId() {
@@ -4872,6 +4935,7 @@ export function createCopilotSdkSessionRunner({
       const id = String(entry.message?.id || '');
       if (id && !entry.released) return id;
     }
+    for (const id of directImageMessages.keys()) return id;
     return '';
   }
 
@@ -4911,6 +4975,7 @@ export function createCopilotSdkSessionRunner({
     for (const { message, variant } of settlingMessages.values()) {
       push(message, buildSteerSettleFailure(message, { variant, agentLabel: SETTLE_AGENT_LABEL }));
     }
+    for (const message of directImageMessages.values()) push(message);
     return entries;
   }
 
@@ -4949,8 +5014,9 @@ export function createCopilotSdkSessionRunner({
     // registry and refuses ids it does not know.
     stopBackgroundTask,
     // "Active" spans both ownerships: a settled turn still publishing must
-    // keep the worker's idle/shutdown gates closed just like a running one.
-    isTurnActive: () => !!activeTurn || publishingTurns.size > 0,
+    // keep the worker's idle/shutdown gates closed just like a running one,
+    // and so must an image row on the relay's image routes.
+    isTurnActive: () => !!activeTurn || publishingTurns.size > 0 || directImageMessages.size > 0,
     dispose,
     // The turn's tokens/cost/TTFT, as posted to `/api/copilot-plan-usage`.
     getLastTurnUsage: () => lastTurnUsage,

package/server/db-schema.mjs

@@ -29,6 +29,13 @@ import { migrateConversationMayCreateSessions } from './migrations/0020-conversa
 import { migrateConversationGroupAgentMarks } from './migrations/0021-conversation-group-agent-marks.mjs';
 import { migrateRelaySchedules } from './migrations/0022-relay-schedules.mjs';
 import { migrateRelayAsks } from './migrations/0023-relay-asks.mjs';
+import { migrateDeepSeekUsageTotals } from './migrations/0024-deepseek-usage-totals.mjs';
+import { migrateDeepSeekUsageRequestsDaily } from './migrations/0025-deepseek-usage-requests-daily.mjs';
+import { migrateDeepSeekUsageServedModels } from './migrations/0026-deepseek-usage-served-models.mjs';
+import { migrateDeepSeekUsageCheckpointRuns } from './migrations/0027-deepseek-usage-checkpoint-runs.mjs';
+import { migrateDeepSeekUsageCheckpointRequestRuns } from './migrations/0028-deepseek-usage-checkpoint-request-runs.mjs';
+import { migrateDeepSeekBalanceRises } from './migrations/0029-deepseek-balance-rises.mjs';
+import { migrateDeepSeekUsageActuals } from './migrations/0030-deepseek-usage-actuals.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -907,6 +914,62 @@ try {
   console.warn(`[relay-asks] migration 0023 failed; retrying on next boot: ${error?.message || error}`);
 }
 
+// DeepSeek usage totals: one new table. The plan usage service creates it
+// itself as well, so a failure here is logged and retried next boot like 0023.
+try {
+  migrateDeepSeekUsageTotals(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0024 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// DeepSeek search/fetch counts, daily spend and balance reference: four
+// columns on 0024's table and two tables, handled like 0024.
+try {
+  migrateDeepSeekUsageRequestsDaily(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0025 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// DeepSeek usage booked under a Claude model name is folded into the DeepSeek
+// model that served it, handled like 0024.
+try {
+  migrateDeepSeekUsageServedModels(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0026 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// The DeepSeek usage checkpoint learns the worker process's run id and its
+// search and fetch counts: three columns on 0024's table, handled like 0024.
+try {
+  migrateDeepSeekUsageCheckpointRuns(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0027 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// The checkpoint's search and fetch counts get a run id of their own: one
+// column on 0024's table, handled like 0024.
+try {
+  migrateDeepSeekUsageCheckpointRequestRuns(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0028 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// The balance reference notes when the balance last rose: one column on
+// 0025's table, handled like 0025.
+try {
+  migrateDeepSeekBalanceRises(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0029 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// The imported figures of DeepSeek's usage export: a table of its own, handled
+// like 0024.
+try {
+  migrateDeepSeekUsageActuals(db);
+} catch (error) {
+  console.warn(`[deepseek-usage] migration 0030 failed; retrying on next boot: ${error?.message || error}`);
+}
+
 const runtimeSessionColumns = db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((c) => c.name);
 if (runtimeSessionColumns.length) {
   if (!runtimeSessionColumns.includes('strategy')) {

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

@@ -0,0 +1,433 @@
+// 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 (DEEPSEEK_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.
+// - 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 {
+  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_']);
+
+/**
+ * Every variable through which the env of the chat folder's settings
+ * (.claude/settings.json, settings.local.json) could send the CLI's requests,
+ * and with them the key, somewhere else, or change whom the CLI trusts on the
+ * way: the endpoints, the provider switches, the credentials, the proxies and
+ * the TLS trust. liveFlagSettings pins each one in the flag settings layer,
+ * which the CLI applies over the folder's, to the value the CLI was spawned
+ * with: the worker's own, else the other case's for a proxy variable, else ''.
+ * '' is unset to the CLI for each of these (truthy or trimmed reads), except
+ * SSL_CERT_FILE and SSL_CERT_DIR: '' empties OpenSSL's and Node's system
+ * store, so those two are pinned only when the worker sets them.
+ *
+ * Source: the names Claude Code 2.1.304 (the bundled CLI) reads, by a grep
+ * of the binary; the CLI's own lists of endpoints (with their selection
+ * switches and companions) and credentials are in it as they are there. A
+ * deny-list, because a settings layer can only pin names known in advance.
+ * Left out, each for its reason: the model variables (same endpoint, same
+ * key), what the CLI already drops from a folder's settings or from all
+ * settings (CLAUDE_CONFIG_DIR, CLAUDE_CODE_CUSTOM_OAUTH_URL, the OTEL
+ * exporter endpoints, ANTHROPIC_UNIX_SOCKET, the host-managed provider
+ * switches, the file-descriptor credentials), a provider's own SDK settings
+ * (AWS_*, GOOGLE_*, AZURE_*, read only for the provider the switches here
+ * turn off), NODE_OPTIONS (at runtime the CLI reads only its system-CA
+ * flags, which add no CA), and what routes only other programs' traffic
+ * (NPM_CONFIG_*, GIT_*, the resolver's variables).
+ */
+export const DEEPSEEK_CLI_PINNED_ENV = Object.freeze([
+  // Endpoints: the CLI's list, its fallback and the headers sent with them.
+  'ANTHROPIC_BASE_URL',
+  '_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL',
+  'ANTHROPIC_CUSTOM_HEADERS',
+  'ANTHROPIC_BEDROCK_BASE_URL',
+  'ANTHROPIC_VERTEX_BASE_URL',
+  'ANTHROPIC_FOUNDRY_BASE_URL',
+  'ANTHROPIC_AWS_BASE_URL',
+  'ANTHROPIC_GOOGLE_CLOUD_BASE_URL',
+  'ANTHROPIC_BEDROCK_MANTLE_BASE_URL',
+  'CLAUDE_CODE_API_BASE_URL',
+  'CLAUDE_CODE_ARTIFACTS_API_BASE_URL',
+  'CLAUDE_CODE_ARTIFACTS_API_TOKEN',
+  'CLAUDE_CODE_ARTIFACT_ASSET_BASE_URL',
+  'CLAUDE_CODE_ARTIFACT_LIVE_BASE_URL',
+  'CLAUDE_CODE_ARTIFACT_SYNC_BASE_URL',
+  'CLAUDE_CODE_ARTIFACT_VIEWER_BASE_URL',
+  'CLAUDE_CODE_MEMORY_API_BASE_URL',
+  'CLAUDE_CODE_MEMORY_API_TOKEN',
+  // Provider switches.
+  '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',
+  // Credentials: the CLI's list, the OAuth login, the federation profile and
+  // the proxy credential helper.
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'AWS_BEARER_TOKEN_BEDROCK',
+  'ANTHROPIC_FOUNDRY_API_KEY',
+  'ANTHROPIC_FOUNDRY_AUTH_TOKEN',
+  'ANTHROPIC_AWS_API_KEY',
+  'CLAUDE_CODE_OAUTH_REFRESH_TOKEN',
+  'CLAUDE_CODE_OAUTH_SCOPES',
+  'CLAUDE_CODE_OAUTH_CLIENT_ID',
+  'ANTHROPIC_PROFILE',
+  'ANTHROPIC_IDENTITY_TOKEN',
+  'ANTHROPIC_IDENTITY_TOKEN_FILE',
+  'ANTHROPIC_FEDERATION_RULE_ID',
+  'ANTHROPIC_ORGANIZATION_ID',
+  'ANTHROPIC_SERVICE_ACCOUNT_ID',
+  'ANTHROPIC_SCOPE',
+  'ANTHROPIC_WORKSPACE_ID',
+  'CLAUDE_CODE_ENABLE_PROXY_AUTH_HELPER',
+  // Proxies: the CLI reads both cases, the lower one first.
+  'HTTPS_PROXY',
+  'https_proxy',
+  'HTTP_PROXY',
+  'http_proxy',
+  'ALL_PROXY',
+  'all_proxy',
+  'NO_PROXY',
+  'no_proxy',
+  'CLAUDE_CODE_HTTPS_PROXY',
+  'CLAUDE_CODE_HTTP_PROXY',
+  // TLS trust and the client certificate.
+  'NODE_TLS_REJECT_UNAUTHORIZED',
+  'NODE_EXTRA_CA_CERTS',
+  'CLAUDE_CODE_CERT_STORE',
+  'CLAUDE_CODE_CLIENT_CERT',
+  'CLAUDE_CODE_CLIENT_KEY',
+  'CLAUDE_CODE_CLIENT_KEY_PASSPHRASE',
+  'SSL_CERT_FILE',
+  'SSL_CERT_DIR',
+]);
+// The two of DEEPSEEK_CLI_PINNED_ENV for which '' is not unset (see there).
+const PINNED_ONLY_WHEN_SET = new Set(['SSL_CERT_FILE', 'SSL_CERT_DIR']);
+// The proxy variables the CLI and the tools it runs read in either case.
+const OTHER_CASE = new Map(
+  ['HTTPS_PROXY', 'HTTP_PROXY', 'ALL_PROXY', 'NO_PROXY'].flatMap((name) => [
+    [name, name.toLowerCase()],
+    [name.toLowerCase(), name],
+  ]),
+);
+
+/**
+ * The pins of DEEPSEEK_CLI_PINNED_ENV for a CLI spawned with `cliEnv`: the
+ * value it was spawned with, else the other case's (a proxy the worker sets
+ * as https_proxy holds for HTTPS_PROXY as well), else ''.
+ */
+export function deepseekPinnedEnv(cliEnv = {}) {
+  const pins = {};
+  for (const name of DEEPSEEK_CLI_PINNED_ENV) {
+    const own = cliEnv[name] ?? cliEnv[OTHER_CASE.get(name)];
+    if (own !== undefined) pins[name] = String(own);
+    else if (!PINNED_ONLY_WHEN_SET.has(name)) pins[name] = '';
+  }
+  return pins;
+}
+
+/**
+ * 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 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 DEEPSEEK_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: { ...deepseekPinnedEnv(cliEnv), ANTHROPIC_BASE_URL: anthropicBaseUrl, ANTHROPIC_AUTH_TOKEN: apiKey },
+        apiKeyHelper: '',
+      };
+    },
+  };
+}