@oar-sh/oar 0.9.16 → 0.9.18

package/README.md

@@ -17,7 +17,7 @@ On Windows, run `irm oar.sh/install.ps1 | iex` in PowerShell. Other ways to inst
 
 ## What OAR does
 
-Coding agents such as GitHub Copilot, Claude Code, Cursor and Grok usually live in a terminal. OAR puts them into a chat you can open anywhere: start a task at your desk, follow it from the sofa, answer the agent's question from your phone. The agents keep running on your own computer, with your files and your logins; OAR passes the conversation back and forth.
+Coding agents such as GitHub Copilot, Claude Code, Cursor, Grok and DeepSeek usually live in a terminal. OAR puts them into a chat you can open anywhere: start a task at your desk, follow it from the sofa, answer the agent's question from your phone. The agents keep running on your own computer, with your files and your logins; OAR passes the conversation back and forth.
 
 ```mermaid
 flowchart LR
@@ -27,7 +27,7 @@ flowchart LR
   end
   subgraph host["Your computer"]
     relay["OAR relay<br/>chats, queue, history, files"]
-    agents["Copilot · OpenAI · Claude<br/>Cursor · Grok"]
+    agents["Copilot · OpenAI · Claude · Claude API<br/>Cursor · Grok · DeepSeek"]
   end
   cloud["☁️ Claude Cloud<br/>sandbox at Anthropic"]
   phone <--> relay
@@ -36,7 +36,7 @@ flowchart LR
   relay <--> cloud
 ```
 
-- **Seven runtimes, one chat**: you pick the agent per conversation, and all of them share the same chat, queue, history, file browser, and question cards ([Runtimes](#runtimes)).
+- **Eight runtimes, one chat**: you pick the agent per conversation, and all of them share the same chat, queue, history, file browser, and question cards ([Runtimes](#runtimes)).
 - **Yours**: the relay runs on your hardware, answers only on this machine until you change that, and collects no telemetry ([Security notes](#security-notes)).
 - **Under active development**: expect occasional rough edges, and some provider SDK features that are missing or incomplete.
 
@@ -45,29 +45,29 @@ flowchart LR
 <table>
 <tr>
 <td width="42%" rowspan="4" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.16" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.18" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
 <br><sub>On a phone: the same conversations, installable as an app.</sub>
 </td>
 <td width="58%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.16" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.18" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
 <br><sub>Agents working in parallel, each with live token counts and its own Stop.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.16" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.18" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
 <br><sub>When the agent needs a decision, it asks, and waits for your answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.16" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
+<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.18" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
 <br><sub>Read the reasoning, not just the answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.16" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
+<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.18" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
 <br><sub>Agents that watch agents: woken by events, approving nothing.</sub>
 </td>
 </tr>
@@ -102,9 +102,11 @@ The runtime (the *provider* in the UI) is chosen in **New Chat** and stays fixed
 | [**OpenAI (BYOK)**](docs/providers.md#openai-byok-and-openai-image) | Copilot's agent against OpenAI or a compatible endpoint | Your own API key |
 | [**OpenAI Image**](docs/providers.md#openai-byok-and-openai-image) | A chat whose replies are images | The same key |
 | [**Claude**](docs/providers.md#claude-agent-sdk) | Claude Code on your machine | A Claude login, made from **⚙️ Settings** |
+| [**Claude API**](docs/providers.md#claude-api) | Claude Code on your machine, billed to a Claude Console API key; a Claude chat can switch between the two | A Claude Console API key |
 | [**Claude Cloud**](docs/providers.md#claude-cloud) (experimental) | Claude Code in a sandbox at Anthropic, on a GitHub repository | A claude.ai account with GitHub connected |
 | [**Cursor**](docs/providers.md#cursor-agent-sdk) | Cursor's agent | A Cursor API key |
 | [**Grok**](docs/providers.md#grok-cli-acp) | xAI's Grok CLI | A Grok sign-in, made from **⚙️ Settings** |
+| [**DeepSeek**](docs/providers.md#deepseek) | Claude Code on your machine, thinking with DeepSeek's models | A DeepSeek API key |
 
 API keys are entered in **⚙️ Settings** and stay on the relay host. The Claude and Grok CLIs can be [installed and signed in to from the browser](docs/providers.md#installing-a-provider-cli-from-the-relay), so no shell on the host is needed. Each runtime discovers its own [models](docs/providers.md#models). The full picture of each runtime is in [Providers](docs/providers.md).
 
@@ -116,11 +118,11 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 <table>
 <tr>
 <td width="62%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.16" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.18" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
 <br><sub>Send a message while the agent works, and it steers the running turn.</sub>
 </td>
 <td width="38%" valign="top">
-<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.16" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
+<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.18" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
 <br><sub>What each plan has left, in one place.</sub>
 </td>
 </tr>
@@ -132,12 +134,12 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Background work**: a task panel lists the commands and sub-agents that outlive a reply, each with its own **Stop** and its full record; a command's console shows its output live, says when it has gone quiet and counts a test run's passes and failures; the panel and its consoles come back after a relay restart, and a queued restart shows what it waits for and asks after a maximum wait ([Background tasks](docs/web-ui.md#background-tasks), [After a relay restart](docs/web-ui.md#after-a-relay-restart)).
 - **Choose how the agent works**: `ask`, `plan`, `agent` or `autopilot`, plus model and reasoning effort, per message ([Relay modes](docs/web-ui.md#relay-modes)).
 - **Files and git**: browse the workspace, preview files, review git changes in a diff viewer, and publish a dev server as a preview link ([Files, git, and previews](docs/web-ui.md#files-git-and-previews), [preview servers](docs/preview-servers.md)).
-- **Usage and context**: plan limits and credits of every provider, and what fills the model's context window ([Usage and context](docs/web-ui.md#usage-and-context)).
+- **Usage and context**: plan limits and credits of every provider, the estimated spend of DeepSeek and Claude API keys, and what fills the model's context window ([Usage and context](docs/web-ui.md#usage-and-context)).
 - **Your conversations everywhere**: the history lives on the relay, drafts follow you from device to device, and conversations can be searched, archived, grouped and pinned ([The conversation list](docs/web-ui.md#the-conversation-list), [drafts](docs/web-ui.md#drafts-across-devices), [session groups](docs/web-ui.md#session-groups), [pins](docs/web-ui.md#pinned-messages)).
 - **Share** a conversation as a read-only link, hide single messages and the host's paths from it, and see when it was opened ([Sharing](docs/web-ui.md#sharing)).
 - **On your phone**: install OAR as an app and get push notifications ([Notifications and the app](docs/web-ui.md#notifications-and-the-app)).
 
-The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.16](CHANGELOG.md#0916--2026-10-24) as the latest.
+The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.18](CHANGELOG.md#0918--2026-10-26) as the latest.
 
 ## Remote access
 
@@ -188,7 +190,7 @@ flowchart LR
 
 You stay in charge: per paired relay you decide whether agents may only read, also prompt, or do everything, and in the `ask` and `plan` modes every write asks you first. A subscription only notifies; it approves nothing.
 
-<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.16"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.16"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.16" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
+<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.18"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.18"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.18" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
 
 How pairing, permissions and limits work is in [Agents working together](docs/agents-together.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "setup:git": "node scripts/setup-git.mjs",
     "land": "node scripts/land.mjs",
     "prune:local": "node scripts/prune-local.mjs",
+    "deepseek:import": "node server/services/deepseek-usage-import.mjs",
     "test:e2e:raw": "node ./node_modules/@playwright/test/cli.js test --config tests/playwright.config.mjs"
   },
   "dependencies": {

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

@@ -0,0 +1,345 @@
+// The Claude API backend of the Claude session runner: Claude Code on the
+// Anthropic API, billed to the API key saved in Settings → Providers → Claude
+// API instead of the host's Claude login.
+//
+// - The CLI's environment: the key as ANTHROPIC_API_KEY, the Anthropic API as
+//   ANTHROPIC_BASE_URL, and nothing of the host's Claude login, another
+//   Anthropic configuration or another provider's switch. The host's Claude
+//   Code state directory stays (CLAUDE_CONFIG_DIR is left as the relay set
+//   it): the chats are Claude chats, with the Claude provider's sessions,
+//   transcripts, resume and task output.
+// - The flag settings layer: the user's settings and the chat folder's
+//   (.claude/settings.json, .claude/settings.local.json) can set `env`
+//   (another ANTHROPIC_BASE_URL, an ANTHROPIC_API_KEY that replaces the key,
+//   an ANTHROPIC_AUTH_TOKEN that beats it, a proxy, another provider, custom
+//   headers, a CA) and `apiKeyHelper` (a script whose output beats it). The
+//   flag layer outranks them all, so it pins the base URL and the key, blanks
+//   the bearer token and the helper, and holds every other variable that
+//   routes the requests or decides whom the CLI trusts at the CLI's own value
+//   (CLAUDE_CLI_PINNED_ENV, shared with the DeepSeek backend). The spawn's
+//   `--settings` argument, which other users of the host can read, carries
+//   the endpoint and the blanks (claudeApiFlagSettings); the key and the
+//   worker's own proxy and TLS values go into the same layer over the CLI's
+//   stdin before the first message (liveFlagSettings, claude-sdk-adapter.mjs;
+//   scripts/claude-api-cli-proof.mjs shows it).
+// - The check: the CLI's `system/init` names where it took its API key from.
+//   Anything but ANTHROPIC_API_KEY stops the turn as soon as the init is read
+//   (checkInit). The CLI does not wait for that verdict: it sends its first
+//   request some 50 to 90 ms after the init (scripts/claude-api-cli-proof.mjs),
+//   so one request may already be out on the other credential when the stop
+//   lands. The check limits a wrong credential to that one request; it does
+//   not prevent it.
+// - The model, effort, thinking and images: Claude's, exactly as the Claude
+//   worker has them (`claudeModels`).
+// - What it reports: no Claude plan usage (there is no plan) and no Claude
+//   usage limit (the API answers with its own errors, which describeFailure
+//   reads in plain words).
+//
+// - 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 agent's shell inherits the CLI's environment, the key included; the
+// relay takes the saved key out of what the worker posts and logs.
+
+import { resolveAnthropicApiBaseUrl } from '../../shared/anthropic-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';
+
+export const CLAUDE_API_BACKEND_ID = 'claude-api';
+export const CLAUDE_API_BACKEND_LABEL = 'Claude API';
+// Where the relay's launch puts the key (session-worker-launch-service.mjs).
+export const CLAUDE_API_KEY_ENV = 'OAR_CLAUDE_API_KEY';
+// The stable code of a turn stopped because the CLI took another credential.
+export const CLAUDE_API_KEY_SOURCE_CODE = 'claude-api-key-source';
+// The only API key source the check lets through: the key in the CLI's
+// environment, which is this backend's.
+export const EXPECTED_API_KEY_SOURCE = 'ANTHROPIC_API_KEY';
+// The sources the SDK's `system/init` can name (sdk.d.ts, ApiKeySource). A
+// note names one of these, never a text of the CLI's own.
+const KNOWN_API_KEY_SOURCES = Object.freeze([
+  'ANTHROPIC_API_KEY',
+  'apiKeyHelper',
+  '/login managed key',
+  'none',
+  'user',
+  'project',
+  'org',
+  'temporary',
+  'oauth',
+]);
+
+const BILLING_URL = 'https://platform.claude.com/settings/billing';
+const LIMITS_URL = 'https://platform.claude.com/settings/limits';
+const SETTINGS_PLACE = 'Settings → Providers → Claude API';
+const KEY_SOURCE_GUIDANCE = 'Remove the apiKeyHelper or other credential from the host\'s Claude Code settings '
+  + `(settings.json), check the key in ${SETTINGS_PLACE}, then send the message again.`;
+
+// Variables that would hand the CLI another credential or point it at another
+// endpoint or cloud (the bundled CLI, 2026-10-25). Every ANTHROPIC_* is
+// dropped as well (FOREIGN_CLI_PREFIXES).
+const FOREIGN_CLI_VARIABLES = Object.freeze([
+  // The host's Claude login, and the other ways to hand the CLI a login or
+  // a key.
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR',
+  'CLAUDE_CODE_OAUTH_REFRESH_TOKEN',
+  'CLAUDE_CODE_OAUTH_SCOPES',
+  'CLAUDE_CODE_OAUTH_CLIENT_ID',
+  'CLAUDE_CODE_CUSTOM_OAUTH_URL',
+  'CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR',
+  'CLAUDE_CODE_API_KEY_HELPER_TTL_MS',
+  // Another provider for the CLI's requests, and their auth bypasses.
+  '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_GATEWAY',
+  'CLAUDE_CODE_USE_MANTLE',
+  'CLAUDE_CODE_USE_CCR_V2',
+  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
+  'CLAUDE_CODE_SKIP_VERTEX_AUTH',
+  'CLAUDE_CODE_SKIP_FOUNDRY_AUTH',
+  'CLAUDE_CODE_SKIP_MANTLE_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH',
+  'CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH',
+  'CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST',
+  // A host's model and effort pins: the turn's model and effort come from
+  // the relay, which bills them to the key.
+  'CLAUDE_CODE_SUBAGENT_MODEL',
+  'CLAUDE_CODE_SUBAGENT_MODEL_FORCE',
+  'CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL',
+  'CLAUDE_CODE_EFFORT_LEVEL',
+  'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
+  // Never set, and dropped when inherited: it forces the permission mode to
+  // default (plan mode is lost) and sandboxes Bash.
+  '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, 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',
+  'CLAUDE_API_RELAY_MODEL',
+  'CURSOR_RELAY_MODEL',
+  'CURSOR_AGENT_STORE_DIR',
+  'CURSOR_API_KEY',
+  'GROK_RELAY_MODEL',
+  'GROK_CLI_COMMAND',
+  'GROK_ALWAYS_APPROVE',
+  'SESSION_ID',
+  'COPILOT_WORKSPACE_ROOT',
+  'INIT_CWD',
+]);
+// The same by prefix: every Anthropic variable (the two the CLI needs are set
+// again below), the relay's folders, config, tools file, worker kind and log
+// file (COPILOT_WEB_RELAY_*), the Copilot provider settings, the DeepSeek
+// worker's settings, every Claude gateway setting and the relay's own OAR_*
+// switches (the key's own variable among them).
+const FOREIGN_CLI_PREFIXES = Object.freeze([
+  'ANTHROPIC_',
+  'COPILOT_WEB_RELAY_',
+  'COPILOT_PROVIDER_',
+  'DEEPSEEK_',
+  'CLAUDE_GATEWAY_',
+  'OAR_',
+]);
+
+/**
+ * Whether a variable of the worker's stays out of the CLI's environment:
+ * another credential, endpoint or provider, 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, however the worker was
+ * started).
+ */
+function isForeignCliVariable(key) {
+  const name = String(key).toUpperCase();
+  return FOREIGN_CLI_VARIABLES.includes(name)
+    || FOREIGN_CLI_PREFIXES.some((prefix) => name.startsWith(prefix))
+    || isHostClaudeSessionVariable(name);
+}
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+/**
+ * The environment the CLI runs with: the worker's own without anything
+ * foreign, then the key and the endpoint. `OAR_ANTHROPIC_API_BASE_URL` names
+ * a fake API for tests; only a loopback URL is taken from it
+ * (resolveAnthropicApiBaseUrl), anything else is the Anthropic API.
+ */
+export function claudeApiCliEnv(baseEnv = process.env, { apiKey = '', baseUrl = '' } = {}) {
+  const key = text(apiKey);
+  if (!key) throw new Error('claude-api-key-not-configured');
+  const next = {};
+  for (const [name, value] of Object.entries(baseEnv || {})) {
+    if (isForeignCliVariable(name)) continue;
+    next[name] = value;
+  }
+  next.ANTHROPIC_API_KEY = key;
+  next.ANTHROPIC_BASE_URL = text(baseUrl) || resolveAnthropicApiBaseUrl(baseEnv || {});
+  return next;
+}
+
+/**
+ * The flag settings layer every CLI of this backend is spawned with, on its
+ * command line: no key in it. It outranks the user's, the project's and the
+ * local settings, so their `env` cannot send the requests elsewhere or swap
+ * the key for a bearer token, and their `apiKeyHelper` cannot swap it for
+ * its own (nor run at the CLI's startup). No hooks and no statusLine command
+ * run (CLAUDE_CLI_KEY_CHAT_SETTINGS). Skills, plugins and MCP servers are
+ * left as the other layers have them.
+ */
+export function claudeApiFlagSettings(baseUrl) {
+  return {
+    ...CLAUDE_CLI_KEY_CHAT_SETTINGS,
+    env: {
+      ANTHROPIC_BASE_URL: text(baseUrl),
+      ANTHROPIC_AUTH_TOKEN: '',
+    },
+    apiKeyHelper: '',
+  };
+}
+
+/**
+ * The same layer with the key, which the CLI takes over stdin before the
+ * first message (claude-sdk-adapter.mjs): a settings file's
+ * env.ANTHROPIC_API_KEY would otherwise replace the CLI's environment's.
+ * Every other variable that routes the CLI's requests, and with them the key,
+ * or decides whom it trusts on the way (the proxies, the other providers'
+ * switches and endpoints, the custom headers, the CA and TLS settings) holds
+ * the value of `cliEnv`, the environment the CLI was spawned with, or is
+ * blanked (claudeCliPinnedEnv).
+ */
+export function claudeApiLiveFlagSettings(baseUrl, apiKey, cliEnv = {}) {
+  const key = text(apiKey);
+  if (!key) throw new Error('claude-api-key-not-configured');
+  const settings = claudeApiFlagSettings(baseUrl);
+  return { ...settings, env: { ...claudeCliPinnedEnv(cliEnv), ...settings.env, ANTHROPIC_API_KEY: key } };
+}
+
+/** The source the CLI named, as a note may quote it: a known name, or a stand-in. */
+function quotedApiKeySource(value) {
+  const source = typeof value === 'string' ? value : '';
+  if (KNOWN_API_KEY_SOURCES.includes(source)) return `"${source}"`;
+  return source ? 'a source this relay does not know' : 'no source';
+}
+
+/**
+ * Null when the CLI's `system/init` says it took the key from
+ * ANTHROPIC_API_KEY (the backend's), else the Error that stops the turn. Its
+ * message names the source the CLI reported, never a key. `afterTraffic`: the
+ * init came while the turn was already talking to the API, so one request
+ * may have gone out on the other credential.
+ */
+export function checkClaudeApiInit(sdkMessage, { afterTraffic = false } = {}) {
+  if (!sdkMessage || sdkMessage.type !== 'system' || sdkMessage.subtype !== 'init') return null;
+  const source = sdkMessage.apiKeySource;
+  if (source === EXPECTED_API_KEY_SOURCE) return null;
+  const error = new Error(
+    `Claude Code reported ${quotedApiKeySource(source)} as its API key source instead of the saved Claude API key, so the turn was stopped.`
+    + (afterTraffic ? ' At most one request may have gone out on that credential.' : ''),
+  );
+  error.code = CLAUDE_API_KEY_SOURCE_CODE;
+  error.apiKeySource = KNOWN_API_KEY_SOURCES.includes(source) ? source : null;
+  error.guidance = KEY_SOURCE_GUIDANCE;
+  return error;
+}
+
+/**
+ * `{ code, guidance }` for a failed request the Claude API has its own advice
+ * for, or null. Read from the error the runner stopped the turn with, the
+ * HTTP status the result reports, else from the status and the words the CLI
+ * quotes in its error text ("API Error: 401 …"). The account refusals come
+ * first: a spend limit can come as a 429, which is not a rate limit.
+ */
+export function describeClaudeApiFailure(errorText, { status = null, error = null } = {}) {
+  if (error?.code === CLAUDE_API_KEY_SOURCE_CODE) {
+    return { code: CLAUDE_API_KEY_SOURCE_CODE, guidance: error.guidance || KEY_SOURCE_GUIDANCE };
+  }
+  const message = text(errorText);
+  const code = Number(status);
+  if (/credit balance is too low/i.test(message)) {
+    return {
+      code: 'claude-api-credit',
+      guidance: `The Claude API account's credit balance is too low. Add credits in the Claude Console (${BILLING_URL}), then send the message again.`,
+    };
+  }
+  if (/API usage limits|enforced_spend_limit_reached/i.test(message)) {
+    return {
+      code: 'claude-api-spend-limit',
+      guidance: `The Claude API account has reached its spend limit. Raise the limit in the Claude Console (${LIMITS_URL}) or wait until it resets, then send the message again.`,
+    };
+  }
+  if (code === 402 || /\b402\b|billing_error/i.test(message)) {
+    return {
+      code: 'claude-api-billing',
+      guidance: `The Claude API refused the request for a billing reason. Check the payment details in the Claude Console (${BILLING_URL}), then send the message again.`,
+    };
+  }
+  if (
+    code === 401
+    || code === 403
+    || /\b40[13]\b|authentication_error|permission_error|invalid x-api-key|invalid api key/i.test(message)
+  ) {
+    return {
+      code: 'claude-api-key',
+      guidance: `The Claude API did not accept the API key. Check it in ${SETTINGS_PLACE}, then send the message again.`,
+    };
+  }
+  if (code === 429 || code === 529 || /\b(?:429|529)\b|rate_limit_error|overloaded_error/i.test(message)) {
+    return {
+      code: 'claude-api-rate-limit',
+      guidance: `The Claude API is rate-limiting this key or is overloaded. Send the message again in a moment; the key's rate limits are in the Claude Console (${LIMITS_URL}).`,
+    };
+  }
+  return null;
+}
+
+export function createClaudeApiClaudeBackend({ env = process.env } = {}) {
+  const apiKey = text(env[CLAUDE_API_KEY_ENV]);
+  const baseUrl = resolveAnthropicApiBaseUrl(env);
+
+  return {
+    id: CLAUDE_API_BACKEND_ID,
+    providerType: CLAUDE_API_BACKEND_ID,
+    label: CLAUDE_API_BACKEND_LABEL,
+    // Claude's models, effort, thinking, `[1m]`, images and sub-agent models,
+    // exactly as the Claude worker has them: the runner and the adapter take
+    // none of those from this backend.
+    claudeModels: true,
+    // No plan windows and no subscription usage limit on an API key, and no
+    // usage route of its own.
+    reportsPlanUsage: false,
+    reportsUsageLimit: false,
+    usageRoute: null,
+    describeFailure: describeClaudeApiFailure,
+    checkInit: checkClaudeApiInit,
+    /** The settings layer pin, merged into the spawn's `settings` (no key in it). */
+    flagSettings: () => claudeApiFlagSettings(baseUrl),
+    /**
+     * The layer again with the key and the routing and trust pins for a CLI
+     * spawned with `cliEnv`, over stdin before the first message.
+     */
+    liveFlagSettings: (cliEnv = claudeApiCliEnv(env, { apiKey, baseUrl })) => claudeApiLiveFlagSettings(baseUrl, apiKey, cliEnv),
+
+    /**
+     * The CLI's environment, built from the worker's own (which must not
+     * reach the CLI as it is: it carries OAR_CLAUDE_API_KEY and possibly the
+     * host's login or Anthropic settings).
+     */
+    spawnEnv(baseEnv = process.env) {
+      return claudeApiCliEnv(baseEnv, { apiKey, baseUrl });
+    },
+  };
+}

package/server/claude-api-worker/claude-api-session-worker.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Claude API session worker: the Claude session worker with its CLI on the
+// Anthropic API and the key saved in Settings → Providers → Claude API
+// (claude-api-backend.mjs). The relay's launch puts the key in
+// OAR_CLAUDE_API_KEY (through the owner-only secret file under tmux) and the
+// chat's model in CLAUDE_API_RELAY_MODEL. The CLI keeps the host's Claude
+// Code state directory: the chats are Claude chats, resumed and read where
+// the Claude worker reads them.
+import { installWorkerLogFile, installWorkerLogRedaction } from '../../shared/worker-runtime/worker-log-file.mjs';
+import { runClaudeSessionWorker } from '../claude-worker/claude-session-worker-main.mjs';
+import { CLAUDE_API_KEY_ENV, createClaudeApiClaudeBackend } from './claude-api-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[CLAUDE_API_KEY_ENV]] });
+
+const backend = createClaudeApiClaudeBackend({ env: process.env });
+
+runClaudeSessionWorker({
+  logTag: 'claude-api-worker',
+  workerName: 'claude-api-session-worker',
+  // None set: the CLI's own default, as for a Claude chat without a model.
+  defaultModel: String(process.env.CLAUDE_API_RELAY_MODEL || '').trim(),
+  backend,
+}).catch((error) => {
+  console.error('claude-api-session-worker fatal:', error?.stack || error?.message || error);
+  process.exit(1);
+});

package/server/claude-worker/claude-attachments.mjs

@@ -52,6 +52,9 @@ function imageBlockFromDataUrl(att, maxInlineImageBytes) {
 export function buildClaudeAttachmentContent(rawAttachments, {
   fsImpl = fs,
   maxInlineImageBytes = MAX_INLINE_IMAGE_BYTES,
+  // False for a model that takes no image input: an image block would fail
+  // the whole request, so every image goes by its path instead.
+  embedImages = true,
 } = {}) {
   const input = Array.isArray(rawAttachments) ? rawAttachments : [];
   const imageBlocks = [];
@@ -67,7 +70,7 @@ export function buildClaudeAttachmentContent(rawAttachments, {
       // Only media types the Anthropic image block accepts are embedded;
       // everything else (svg, bmp, heic, …) would 400 the whole turn and
       // falls back to a path reference instead.
-      if (filePath && isEmbeddableImageMediaType(mime) && fsImpl.existsSync(filePath)) {
+      if (embedImages && filePath && isEmbeddableImageMediaType(mime) && fsImpl.existsSync(filePath)) {
         try {
           const bytes = fsImpl.readFileSync(filePath);
           if (Buffer.isBuffer(bytes) && bytes.length && bytes.length <= maxInlineImageBytes) {
@@ -85,7 +88,7 @@ export function buildClaudeAttachmentContent(rawAttachments, {
           embedded = false;
         }
       }
-      if (!embedded) {
+      if (!embedded && embedImages) {
         const blockFromDataUrl = imageBlockFromDataUrl(att, maxInlineImageBytes);
         if (blockFromDataUrl) {
           imageBlocks.push(blockFromDataUrl);
@@ -118,9 +121,9 @@ export function buildClaudeAttachmentContent(rawAttachments, {
  * Text first (user text + attachment notes + server-provided attachment
  * context), then inline image blocks.
  */
-export function buildClaudeUserContent(message, { fsImpl = fs, maxInlineImageBytes = MAX_INLINE_IMAGE_BYTES } = {}) {
+export function buildClaudeUserContent(message, { fsImpl = fs, maxInlineImageBytes = MAX_INLINE_IMAGE_BYTES, embedImages = true } = {}) {
   const text = String(message?.text || '').trim();
-  const { imageBlocks, noteLines } = buildClaudeAttachmentContent(message?.attachments, { fsImpl, maxInlineImageBytes });
+  const { imageBlocks, noteLines } = buildClaudeAttachmentContent(message?.attachments, { fsImpl, maxInlineImageBytes, embedImages });
   const attachmentPromptContext = String(message?.attachmentPromptContext || '').trim();
   const textParts = [text];
   if (noteLines.length) textParts.push(noteLines.join('\n'));