@oar-sh/oar 0.9.16 → 0.9.18

package/shared/deepseek-api.mjs

@@ -0,0 +1,137 @@
+// A small client for the two DeepSeek endpoints the relay calls itself:
+// `GET /models` (model discovery) and `GET /user/balance` (the usage card).
+// Turns do not go through here: the session worker runs Claude Code against
+// DeepSeek's Anthropic-compatible endpoint (`deepseekAnthropicBaseUrl`).
+//
+// The API key is sent to the configured base URL and nowhere else, and it is
+// in no error this module produces: a response body is quoted only after the
+// key has been taken out of it.
+
+import { DEFAULT_DEEPSEEK_BASE_URL } from './deepseek-models.mjs';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', '[::1]', 'localhost']);
+
+/**
+ * The base URL as stored: `https:` on any host, or `http:` on a loopback host
+ * (a local proxy, a capture tool, the tests' fake API). No credentials, query
+ * or fragment; trailing slashes are dropped. An empty value is the default.
+ */
+export function normalizeDeepSeekBaseUrl(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return { ok: true, baseUrl: DEFAULT_DEEPSEEK_BASE_URL };
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, error: 'The DeepSeek base URL is not a valid URL' };
+  }
+  if (url.username || url.password) return { ok: false, error: 'The DeepSeek base URL must not contain credentials' };
+  if (url.search || url.hash) return { ok: false, error: 'The DeepSeek base URL must not contain a query or fragment' };
+  const loopback = LOOPBACK_HOSTS.has(url.hostname.toLowerCase());
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    return { ok: false, error: 'The DeepSeek base URL must use https (http only on a loopback address)' };
+  }
+  const baseUrl = `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, '')}`;
+  return { ok: true, baseUrl };
+}
+
+/** Where Claude Code is pointed for DeepSeek turns. */
+export function deepseekAnthropicBaseUrl(baseUrl = DEFAULT_DEEPSEEK_BASE_URL) {
+  const normalized = normalizeDeepSeekBaseUrl(baseUrl);
+  return `${normalized.ok ? normalized.baseUrl : DEFAULT_DEEPSEEK_BASE_URL}/anthropic`;
+}
+
+export class DeepSeekApiError extends Error {
+  constructor(message, { code = 'error', status = null } = {}) {
+    super(message);
+    this.name = 'DeepSeekApiError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+function codeForStatus(status) {
+  if (status === 401 || status === 403) return 'unauthorized';
+  if (status === 402) return 'insufficient_balance';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'transient';
+  return 'error';
+}
+
+function redact(text, apiKey) {
+  const value = String(text ?? '');
+  const key = String(apiKey ?? '').trim();
+  return key ? value.split(key).join('[redacted]') : value;
+}
+
+function toAmount(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+export function createDeepSeekApiClient({
+  baseUrl = DEFAULT_DEEPSEEK_BASE_URL,
+  apiKey = '',
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const normalized = normalizeDeepSeekBaseUrl(baseUrl);
+  const key = String(apiKey ?? '').trim();
+
+  async function getJson(pathname, what) {
+    if (!normalized.ok) throw new DeepSeekApiError(normalized.error, { code: 'invalid_base_url' });
+    if (!key) throw new DeepSeekApiError('DeepSeek API key is not configured', { code: 'not_configured' });
+    let response;
+    try {
+      response = await fetchImpl(`${normalized.baseUrl}${pathname}`, {
+        headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (error) {
+      throw new DeepSeekApiError(`DeepSeek ${what} failed: ${redact(error?.message || error, key)}`, { code: 'network' });
+    }
+    if (!response.ok) {
+      const detail = redact(String(await response.text().catch(() => '')).trim(), key).slice(0, 240);
+      throw new DeepSeekApiError(
+        `DeepSeek ${what} failed (${response.status})${detail ? `: ${detail}` : ''}`,
+        { code: codeForStatus(response.status), status: response.status },
+      );
+    }
+    try {
+      return await response.json();
+    } catch {
+      throw new DeepSeekApiError(`DeepSeek ${what} returned invalid JSON`, { code: 'invalid_response' });
+    }
+  }
+
+  return {
+    baseUrl: normalized.ok ? normalized.baseUrl : '',
+
+    /** The model ids `GET /models` lists, in its order, without duplicates. */
+    async listModels() {
+      const payload = await getJson('/models', 'model discovery');
+      const ids = (Array.isArray(payload?.data) ? payload.data : [])
+        .map((entry) => String(entry?.id ?? '').trim())
+        .filter(Boolean);
+      return Array.from(new Set(ids));
+    },
+
+    /**
+     * `GET /user/balance`: `{ isAvailable, balances: [{ currency, total,
+     * granted, toppedUp }] }`, amounts as numbers (DeepSeek sends strings).
+     */
+    async getBalance() {
+      const payload = await getJson('/user/balance', 'balance check');
+      const balances = (Array.isArray(payload?.balance_infos) ? payload.balance_infos : [])
+        .map((entry) => ({
+          currency: String(entry?.currency ?? '').trim().toUpperCase(),
+          total: toAmount(entry?.total_balance),
+          granted: toAmount(entry?.granted_balance),
+          toppedUp: toAmount(entry?.topped_up_balance),
+        }))
+        .filter((entry) => entry.currency);
+      return { isAvailable: payload?.is_available === true, balances };
+    },
+  };
+}

package/shared/deepseek-models.mjs

@@ -0,0 +1,114 @@
+// What OAR knows about DeepSeek without asking it: the provider id, the
+// default endpoint, the models to offer when discovery has not run or failed,
+// and the effort levels DeepSeek's thinking mode takes.
+//
+// Source: api-docs.deepseek.com (pricing, list-models and thinking-mode pages,
+// built 2026-10-19). `deepseek-chat` and `deepseek-reasoner` were retired on
+// 2026-07-24; thinking is a request parameter now, not a model of its own.
+
+export const DEEPSEEK_PROVIDER_TYPE = 'deepseek';
+export const DEEPSEEK_PROVIDER_LABEL = 'DeepSeek';
+
+export const DEFAULT_DEEPSEEK_BASE_URL = 'https://api.deepseek.com';
+export const DEFAULT_DEEPSEEK_MODEL = 'deepseek-flash';
+
+// Context window and output ceiling are the same for both today (1M / 384K).
+export const DEEPSEEK_CONTEXT_WINDOW_TOKENS = 1_048_576;
+export const DEEPSEEK_MAX_OUTPUT_TOKENS = 393_216;
+// When a DeepSeek session compacts unless the conversation pins a window: far
+// below the 1M window, so a turn after the cache has expired does not re-send
+// most of a million tokens at the cache-miss price.
+export const DEEPSEEK_DEFAULT_AUTO_COMPACT_WINDOW = 400_000;
+
+export const DEFAULT_DEEPSEEK_MODELS = Object.freeze(['deepseek-flash', 'deepseek-v4-pro']);
+
+const KNOWN_MODELS = Object.freeze({
+  'deepseek-flash': Object.freeze({ label: 'DeepSeek Flash', imageInput: true }),
+  'deepseek-v4-pro': Object.freeze({ label: 'DeepSeek V4 Pro', imageInput: false }),
+  // Aliases DeepSeek still accepts; both are served by the Flash model.
+  'deepseek-v4-flash': Object.freeze({ label: 'DeepSeek V4 Flash', imageInput: true }),
+  'deepseek-v4-flash-vision-exp': Object.freeze({ label: 'DeepSeek V4 Flash Vision', imageInput: true }),
+});
+
+// The levels a DeepSeek chat offers. DeepSeek folds medium and xhigh into
+// high, so they are not offered. Its `none` (thinking off) is not offered
+// either: Claude Code, which runs DeepSeek turns, never sends
+// `thinking: {type: disabled}` for a DeepSeek model (requests captured
+// 2026-10-24), and DeepSeek thinks unless told not to.
+export const DEEPSEEK_REASONING_EFFORTS = Object.freeze(['low', 'high', 'max']);
+export const DEFAULT_DEEPSEEK_REASONING_EFFORT = 'high';
+
+// The levels DeepSeek itself maps other names to (thinking-mode guide), so an
+// agent asking for "medium" gets what DeepSeek would run, not thinking off.
+const DEEPSEEK_EFFORT_ALIASES = Object.freeze({
+  none: 'low',
+  minimal: 'low',
+  medium: 'high',
+  xhigh: 'high',
+  ultra: 'max',
+  ultracode: 'max',
+});
+
+/** A requested effort in DeepSeek's terms: one of DEEPSEEK_REASONING_EFFORTS, or '' for unknown. */
+export function deepseekReasoningEffortFor(value) {
+  const effort = String(value ?? '').trim().toLowerCase();
+  if (!effort) return '';
+  if (DEEPSEEK_REASONING_EFFORTS.includes(effort)) return effort;
+  return DEEPSEEK_EFFORT_ALIASES[effort] || '';
+}
+
+// Commit attribution in DeepSeek chats: OAR's trailer or none. Claude Code's
+// own ("vanilla") lines would credit Claude for DeepSeek's work.
+export const DEEPSEEK_ATTRIBUTION_MODES = Object.freeze(['oar', 'off']);
+export const DEFAULT_DEEPSEEK_ATTRIBUTION = 'oar';
+
+function modelKey(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+/** Whether a model id is one of DeepSeek's (its ids all carry the prefix). */
+export function isDeepSeekModelId(value) {
+  return modelKey(value).startsWith('deepseek-');
+}
+
+// What DeepSeek's Anthropic-compatible endpoint serves a Claude model id
+// with (api-docs.deepseek.com, guides/anthropic_api): the Opus ids run on V4
+// Pro, the Sonnet and Haiku ids on Flash. Claude Code sends such an id when
+// an alias ("opus") has no ANTHROPIC_DEFAULT_*_MODEL pin, so a report or a
+// badge may name a Claude model DeepSeek never ran.
+const CLAUDE_FAMILIES_SERVED_AS = Object.freeze([
+  ['claude-opus', 'deepseek-v4-pro'],
+  ['claude-sonnet', 'deepseek-flash'],
+  ['claude-haiku', 'deepseek-flash'],
+]);
+
+/**
+ * The DeepSeek model a model name stands for, without Claude Code's `[1m]`
+ * suffix: a DeepSeek id as given, a Claude id by the model DeepSeek serves it
+ * with, '' for a name DeepSeek is not known to serve (an alias, another
+ * vendor's id).
+ */
+export function deepseekServedModel(value) {
+  const id = String(value ?? '').trim().replace(/\[1m\]$/i, '');
+  const key = id.toLowerCase();
+  if (key.startsWith('deepseek-')) return id;
+  for (const [family, model] of CLAUDE_FAMILIES_SERVED_AS) {
+    if (key.startsWith(family)) return model;
+  }
+  return '';
+}
+
+/** The display name of a DeepSeek model id: "DeepSeek Flash", or the id itself. */
+export function deepseekModelLabel(value) {
+  const id = String(value ?? '').trim();
+  return KNOWN_MODELS[modelKey(id)]?.label || id;
+}
+
+/**
+ * Whether the model takes image input. A model this module does not know is
+ * treated as text-only: sending images to one that refuses them fails the
+ * whole request, while passing an image as a file path still works.
+ */
+export function deepseekModelAcceptsImages(value) {
+  return KNOWN_MODELS[modelKey(value)]?.imageInput === true;
+}

package/shared/deepseek-pricing.mjs

@@ -0,0 +1,146 @@
+// DeepSeek's published prices, for the usage card's estimate of what this
+// relay's DeepSeek turns cost. DeepSeek reports no cost per request, and
+// Claude Code's own `total_cost_usd` is computed at Claude's prices, so the
+// estimate is tokens times this table.
+//
+// Source: api-docs.deepseek.com/quick_start/pricing (USD) and its zh-cn page
+// (CNY), built 2026-10-19. Prices are per 1M tokens: a cache hit, a cache
+// miss (input DeepSeek had not cached) and output. Peak hours cost exactly
+// twice the off-peak price. Peak is Monday to Friday 01:00–04:00 and
+// 06:00–10:00 UTC (09:00–12:00 and 14:00–18:00 Beijing time); everything else
+// is off-peak. On Chinese public holidays DeepSeek charges off-peak prices all
+// day; the estimate doesn't know those dates, so turns at peak hours on a
+// holiday are counted at double the real price.
+//
+// A model the table does not know gets no estimate (null), never a guess.
+//
+// Claude Code's WebSearch runs on DeepSeek's Search API. Source:
+// api-docs.deepseek.com/guides/search (USD) and its zh-cn page (CNY), read
+// 2026-10-24: $0.75 / ¥5 per 1,000 successful requests for each of Search
+// and Fetch, charged from 2026-11-01 00:00 Beijing time (2026-10-31 16:00
+// UTC), no peak or off-peak. Requests before that are counted but cost 0.
+// Claude Code's WebFetch is not a Fetch request: it reads the page on the
+// relay host and sends the text to the model (plain tokens), and DeepSeek's
+// API refuses the server-side fetch tool (422, checked 2026-10-25). The Fetch
+// price stays for a fetch DeepSeek might report one day.
+
+export const DEEPSEEK_PRICING_SOURCE = Object.freeze({
+  url: 'https://api-docs.deepseek.com/quick_start/pricing',
+  date: '2026-10-19',
+});
+
+export const DEEPSEEK_SEARCH_PRICING = Object.freeze({
+  url: 'https://api-docs.deepseek.com/guides/search',
+  date: '2026-10-24',
+  chargedFrom: '2026-10-31T16:00:00.000Z',
+  // Per 1,000 successful requests, the same for a search and a fetch.
+  perThousand: Object.freeze({ USD: 0.75, CNY: 5 }),
+});
+
+export const DEEPSEEK_PRICE_CURRENCIES = Object.freeze(['USD', 'CNY']);
+
+const TOKENS_PER_PRICE_UNIT = 1_000_000;
+
+function prices(hit, miss, output) {
+  return Object.freeze({ hit, miss, output });
+}
+
+const PRICE_TABLE = Object.freeze({
+  'deepseek-flash': Object.freeze({
+    offPeak: Object.freeze({ USD: prices(0.003, 0.15, 0.60), CNY: prices(0.02, 1, 4) }),
+    peak: Object.freeze({ USD: prices(0.006, 0.30, 1.20), CNY: prices(0.04, 2, 8) }),
+  }),
+  'deepseek-v4-pro': Object.freeze({
+    offPeak: Object.freeze({ USD: prices(0.022, 0.66, 1.98), CNY: prices(0.15, 4.5, 13.5) }),
+    peak: Object.freeze({ USD: prices(0.044, 1.32, 3.96), CNY: prices(0.30, 9, 27) }),
+  }),
+});
+
+// Ids DeepSeek still accepts and serves with the Flash model.
+const PRICE_ALIASES = Object.freeze({
+  'deepseek-v4-flash': 'deepseek-flash',
+  'deepseek-v4-flash-vision-exp': 'deepseek-flash',
+});
+
+// [start, end) hours in UTC, Monday to Friday. The card shows them in the
+// browser's time zone (plan-usage-view.mjs).
+export const DEEPSEEK_PEAK_HOURS_UTC = Object.freeze([Object.freeze([1, 4]), Object.freeze([6, 10])]);
+const PEAK_HOURS_UTC = DEEPSEEK_PEAK_HOURS_UTC;
+
+function toDate(value) {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (typeof value === 'number') {
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  const text = String(value ?? '').trim();
+  if (!text) return null;
+  const date = new Date(text);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/** The id the table prices a model under ("deepseek-v4-flash[1m]" → "deepseek-flash"), or '' when unknown. */
+export function deepseekPricedModel(value) {
+  const id = String(value ?? '').trim().toLowerCase().replace(/\[1m\]$/, '');
+  if (PRICE_TABLE[id]) return id;
+  return PRICE_ALIASES[id] || '';
+}
+
+/** Whether DeepSeek bills an instant at its peak price; null for an unreadable time. */
+export function isDeepSeekPeakTime(at) {
+  const date = toDate(at);
+  if (!date) return null;
+  const day = date.getUTCDay();
+  if (day === 0 || day === 6) return false;
+  const minutes = date.getUTCHours() * 60 + date.getUTCMinutes();
+  return PEAK_HOURS_UTC.some(([start, end]) => minutes >= start * 60 && minutes < end * 60);
+}
+
+/**
+ * The prices per 1M tokens for a model at an instant: `{ hit, miss, output,
+ * peak }`, or null for an unknown model, currency or time.
+ */
+export function deepseekPriceFor({ model, at, currency = 'USD' } = {}) {
+  const entry = PRICE_TABLE[deepseekPricedModel(model)];
+  const unit = String(currency ?? '').trim().toUpperCase();
+  const peak = isDeepSeekPeakTime(at);
+  if (!entry || !DEEPSEEK_PRICE_CURRENCIES.includes(unit) || peak === null) return null;
+  return { ...entry[peak ? 'peak' : 'offPeak'][unit], peak };
+}
+
+function tokenCount(value) {
+  const number = Number(value ?? 0);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+/**
+ * What the tokens of one request (or one turn) cost at DeepSeek's price for
+ * its time, in `currency` (USD or CNY). A missing count is 0. Null when the
+ * model, the currency or the time is unknown.
+ */
+export function estimateCost({ model, at, hitTokens = 0, missTokens = 0, outputTokens = 0, currency = 'USD' } = {}) {
+  const price = deepseekPriceFor({ model, at, currency });
+  if (!price) return null;
+  const cost = (
+    tokenCount(hitTokens) * price.hit
+    + tokenCount(missTokens) * price.miss
+    + tokenCount(outputTokens) * price.output
+  ) / TOKENS_PER_PRICE_UNIT;
+  // Ten decimals: enough for a single token, and no binary-float tails.
+  return Math.round(cost * 1e10) / 1e10;
+}
+
+/**
+ * What the web searches and fetches of one turn cost at the time `at`, in
+ * `currency`: 0 before DeepSeek started charging for them, null for an
+ * unreadable time or an unknown currency. Flat per request, peak or not.
+ */
+export function estimateSearchCost({ at, searchRequests = 0, fetchRequests = 0, currency = 'USD' } = {}) {
+  const date = toDate(at);
+  const unit = String(currency ?? '').trim().toUpperCase();
+  const price = DEEPSEEK_SEARCH_PRICING.perThousand[unit];
+  if (!date || price === undefined) return null;
+  if (date.getTime() < Date.parse(DEEPSEEK_SEARCH_PRICING.chargedFrom)) return 0;
+  const cost = (tokenCount(searchRequests) + tokenCount(fetchRequests)) * price / 1000;
+  return Math.round(cost * 1e10) / 1e10;
+}

package/shared/host-claude-session-env.mjs

@@ -0,0 +1,101 @@
+// The variables of a Claude Code session the relay was started from.
+//
+// A relay started from inside a Claude Code session (an agent's shell, a
+// `claude` run that starts it, a test relay an agent starts from a relay
+// worker) carries that session's variables, and so would every worker: the
+// Claude and DeepSeek workers' CLI would take itself for a child of the host's
+// session (messaging socket and token, session id, entrypoint, effort), and a
+// Copilot or Cursor worker has no use for them either. The launcher drops
+// them for every kind and on every path (session-worker-launch-service.mjs),
+// and the DeepSeek backend drops them again from its CLI's environment.
+//
+// A fixed list misses what the next CLI version adds, so the session's
+// variables are matched by family as well:
+// - the names Claude Code gives its child shells and MCP servers, those it
+//   sets on its own process (entrypoint, executable path), the markers an
+//   SDK host sets (its version and its app's name, which the CLI sends as
+//   `x-client-app`), and the per-spawn Bash cap a relay's Claude worker
+//   gives its CLI (HOST_CLAUDE_SESSION_ENV_VARS);
+// - every `CLAUDE_CODE_SESSION_*` (id, attended, access token, kind, name,
+//   origin, ...), every `CLAUDE_CODE_*_SESSION_ID` (host, remote, bridge,
+//   cloud) and every `CLAUDE_CODE_MESSAGING_*`
+//   (HOST_CLAUDE_SESSION_ENV_PATTERNS).
+// What stays is configuration: the relay's own (`CLAUDE_CONFIG_DIR`,
+// `CLAUDE_CODE_EXECUTABLE`, a login token, which the launcher hands only to
+// the Claude kinds) and the user's settings: `CLAUDE_CODE_*` ones (a
+// provider such as `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_GIT_BASH_PATH` on
+// Windows, the `DISABLE_*`/`ENABLE_*` switches) and the SDK's
+// `CLAUDE_AGENT_SDK_*` switches (`DISABLE_BUILTIN_AGENTS`, `MCP_NO_PREFIX`,
+// `DISABLE_MCP_MANIFESTS`), which no family reaches. The settings that fall
+// in a family stay through HOST_CLAUDE_SESSION_KEEP_ENV_VARS. Every
+// `CLAUDE_AGENT_SDK_*` and family name the bundled CLI and SDK read was
+// sorted this way (2026-10-25).
+
+export const HOST_CLAUDE_SESSION_ENV_VARS = Object.freeze([
+  'CLAUDECODE',
+  'CLAUDE_CODE_SESSION_ID',
+  'CLAUDE_CODE_MESSAGING_SOCKET',
+  'CLAUDE_CODE_MESSAGING_TOKEN',
+  'CLAUDE_CODE_CHILD_SESSION',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_SESSION_ATTENDED',
+  'CLAUDE_CODE_EXECPATH',
+  'CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS',
+  'CLAUDE_AGENT_SDK_VERSION',
+  'CLAUDE_AGENT_SDK_CLIENT_APP',
+  'CLAUDE_PID',
+  'CLAUDE_EFFORT',
+  'CLAUDE_PROJECT_DIR',
+  'CLAUDE_ENV_FILE',
+]);
+
+// Shell `case` patterns, matched against the upper-cased name in JavaScript.
+export const HOST_CLAUDE_SESSION_ENV_PATTERNS = Object.freeze([
+  'CLAUDE_CODE_SESSION_*',
+  'CLAUDE_CODE_*_SESSION_ID',
+  'CLAUDE_CODE_MESSAGING_*',
+]);
+
+// Settings inside a family: a behaviour switch and a debug log switch.
+export const HOST_CLAUDE_SESSION_KEEP_ENV_VARS = Object.freeze([
+  'CLAUDE_CODE_SESSION_START_ANNOUNCEMENTS_BEFORE_PROMPT',
+  'CLAUDE_CODE_SESSION_LOG',
+]);
+
+const EXACT = new Set(HOST_CLAUDE_SESSION_ENV_VARS);
+const KEEP = new Set(HOST_CLAUDE_SESSION_KEEP_ENV_VARS);
+const PATTERNS = HOST_CLAUDE_SESSION_ENV_PATTERNS.map((pattern) => new RegExp(
+  `^${pattern.split('*').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`,
+));
+
+/**
+ * Whether a variable is the host Claude Code session's. Upper-cased first:
+ * Windows names are case-insensitive.
+ */
+export function isHostClaudeSessionVariable(name) {
+  const key = String(name ?? '').toUpperCase();
+  if (!key || KEEP.has(key)) return false;
+  return EXACT.has(key) || PATTERNS.some((pattern) => pattern.test(key));
+}
+
+/** The environment without the host Claude Code session's variables. */
+export function withoutHostClaudeSessionVariables(env = {}) {
+  const next = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (!isHostClaudeSessionVariable(key)) next[key] = value;
+  }
+  return next;
+}
+
+/**
+ * A POSIX sh statement that unsets, in the shell it runs in, every variable
+ * of the host session the environment holds: the families as well as the
+ * names, for an environment the launcher never saw (a tmux server's). Names
+ * only; a value is never read.
+ */
+export function hostClaudeSessionUnsetStatement() {
+  const keep = HOST_CLAUDE_SESSION_KEEP_ENV_VARS.length ? `${HOST_CLAUDE_SESSION_KEEP_ENV_VARS.join('|')}) ;; ` : '';
+  const drop = [...HOST_CLAUDE_SESSION_ENV_VARS, ...HOST_CLAUDE_SESSION_ENV_PATTERNS].join('|');
+  return `for oar_host_var in $(env | sed -n 's/^\\([A-Za-z_][A-Za-z0-9_]*\\)=.*/\\1/p'); do `
+    + `case "$oar_host_var" in ${keep}${drop}) unset "$oar_host_var";; esac; done; unset oar_host_var;`;
+}

package/shared/model-id.mjs

@@ -77,6 +77,13 @@ export function isSafeGrokModelId(value) {
   return isSafeProviderModelId(value);
 }
 
+// DeepSeek model ids ("deepseek-flash", "deepseek-v4-pro") follow the same
+// safe-token rules; that they are DeepSeek's is checked by the provider
+// (shared/deepseek-models.mjs).
+export function isSafeDeepSeekModelId(value) {
+  return isSafeProviderModelId(value);
+}
+
 // The "[1m]" suffix marks the 1M-context variant of a Claude model. The UI
 // treats it as a context tier of the base model, not a separate model.
 export const CLAUDE_LONG_CONTEXT_SUFFIX = '[1m]';

package/shared/preview-tool-core.mjs

@@ -173,7 +173,7 @@ export async function executePreviewTool(input, { api, conversationId = '' } = {
     const response = await api('POST', '/api/previews', body);
     const existing = response?.existing === true;
     const hint = parsed.port
-      ? `Serve the app under ${response?.basePath} (the proxy strips the prefix and sends X-Forwarded-Prefix). Tell the user the URL and that the link is public.`
+      ? `Serve the app under ${response?.basePath} (the proxy strips the prefix and sends X-Forwarded-Prefix). Bind the dev server to 127.0.0.1, not 0.0.0.0: the relay's proxy reaches it there and nothing else should. Tell the user the URL and that the link is public.`
       : 'The directory is served as-is; relative asset paths work, root-absolute ones do not. Tell the user the URL and that the link is public.';
     return {
       ok: true,

package/shared/provider-routing.mjs

@@ -12,8 +12,10 @@
 export const LEGACY_RELAY_PROVIDER_TYPES = Object.freeze(['github', 'openai']);
 
 // `claude-cloud` is its own provider, never an alias of `claude`: its worker
-// drives a session in Anthropic's cloud and spawns no CLI.
-export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok', 'claude-cloud']);
+// drives a session in Anthropic's cloud and spawns no CLI. `claude-api` is
+// its own too: the Claude worker on a Console API key instead of the host's
+// subscription login.
+export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok', 'claude-cloud', 'deepseek', 'claude-api']);
 
 export function isLegacyRelayProviderType(value) {
   const normalized = String(value || '').trim().toLowerCase();
@@ -25,7 +27,7 @@ export function isSessionWorkerProviderType(value) {
   return SESSION_WORKER_PROVIDER_TYPES.includes(String(value || '').trim().toLowerCase());
 }
 
-/** `'claude', 'cursor', 'grok', 'claude-cloud'` — for interpolation into SQL NOT IN (...) lists. */
+/** `'claude', 'cursor', 'grok', 'claude-cloud', 'deepseek', 'claude-api'` — for interpolation into SQL NOT IN (...) lists. */
 export function sessionWorkerProviderSqlList() {
   return SESSION_WORKER_PROVIDER_TYPES.map((provider) => `'${provider}'`).join(', ');
 }

package/shared/relay-asks.mjs

@@ -1,4 +1,4 @@
-// Questions that don't block: remote_relay's `ask` puts a question for the
+// Questions that don't block: relay_tool's `ask` puts a question for the
 // owner into a session (a card there and in the Inbox) and returns at once;
 // the asking session keeps working and is told the answer later, as a relay
 // event (question_answered).
@@ -11,14 +11,20 @@
 // Every text of an ask is written by an agent, possibly on another relay:
 // whoever shows it shows it as plain text.
 //
-// SDK-free and side-effect free: imported by the server, the remote_relay
+// SDK-free and side-effect free: imported by the server, the relay_tool
 // contract and the browser.
 
 // The kind a question card carries in /api/relay-questions and the Inbox:
 // `ask` (this feature), `approval` (a relay's Allow / Deny card on its own
-// agent's call, context.source 'remote_relay'), `ask_user` (every other card a
-// turn waits on).
+// agent's call, context.source REMOTE_RELAY_APPROVAL_SOURCE), `ask_user`
+// (every other card a turn waits on).
 export const RELAY_QUESTION_KINDS = Object.freeze(['ask', 'ask_user', 'approval']);
+
+// The approval card's `context.source`, re-exported by the contract, which
+// imports this module (defined here so neither import goes in a circle).
+// Stored and sent between relays, so it kept the tool's name from before
+// 0.9.18.
+export const REMOTE_RELAY_APPROVAL_SOURCE = 'remote_relay';
 export const RELAY_ASK_KIND = 'ask';
 
 export const RELAY_ASK_URGENCIES = Object.freeze(['normal', 'now']);
@@ -141,5 +147,5 @@ export function relayQuestionKind(question) {
   const kind = toText(question?.kind);
   if (RELAY_QUESTION_KINDS.includes(kind)) return kind;
   const context = question && typeof question.context === 'object' && question.context ? question.context : {};
-  return toText(context.source) === 'remote_relay' ? 'approval' : 'ask_user';
+  return toText(context.source) === REMOTE_RELAY_APPROVAL_SOURCE ? 'approval' : 'ask_user';
 }

package/shared/relay-events.mjs

@@ -8,7 +8,7 @@
 // then start with the relay's name). `replayed: true` marks an event a paired
 // relay kept while the link to it was down.
 //
-// SDK-free and side-effect free: imported by the server, the remote_relay
+// SDK-free and side-effect free: imported by the server, the relay_tool
 // contract and the browser (which renders the event rows).
 
 import { RELAY_SCHEDULE_MESSAGE_KIND } from './relay-schedules.mjs';
@@ -22,7 +22,7 @@ export const RELAY_EVENT_MESSAGE_KIND = 'relay-event';
 
 export const RELAY_EVENT_TYPES = Object.freeze([
   'question_asked',
-  // The owner answered or dismissed a question that does not block (remote_relay
+  // The owner answered or dismissed a question that does not block (relay_tool
   // `ask`). The asking session is always told, without a subscription; a
   // subscription that takes question_asked takes it too.
   'question_answered',

package/shared/relay-schedules.mjs

@@ -1,5 +1,5 @@
 // Relay schedules: a prompt the relay queues into a session at a set time,
-// once or every N minutes. An agent sets one with remote_relay's `schedule`
+// once or every N minutes. An agent sets one with relay_tool's `schedule`
 // (its own conversation by default, or another session of this relay); the
 // relay keeps it in its database, so it outlives a restart that the agent's
 // own timers would not.
@@ -8,7 +8,7 @@
 // = 'relay-schedule'`) whose first line says what it is: automated, never the
 // user's, and it approves nothing.
 //
-// SDK-free and side-effect free: imported by the server and the remote_relay
+// SDK-free and side-effect free: imported by the server and the relay_tool
 // contract (the browser keeps its own copy of what it needs:
 // server/public/app/relay-schedule-view.mjs).