@oar-sh/oar 0.9.17 → 0.9.19

package/server/services/remote-relay-dispatcher.mjs

@@ -14,6 +14,7 @@ import {
   REMOTE_RELAY_LOCAL_ALIAS,
   REMOTE_RELAY_LOCAL_ID,
   REMOTE_RELAY_PROVIDERS,
+  REMOTE_RELAY_SEND_PROVIDERS,
   REMOTE_RELAY_SESSION_SETTINGS,
   formatSessionGroupList,
   isRemoteRelayApprovalQuestion,
@@ -45,7 +46,7 @@ import {
 import { RELAY_ASK_KIND, relayQuestionKind } from '../../shared/relay-asks.mjs';
 import { RELAY_ASK_REMOTE_PATHS, isMissingRelayAskRoute, relayWithoutAsksText } from './relay-ask-link-service.mjs';
 
-// The one place a `remote_relay` tool call is decided and carried out (plan
+// The one place a `relay_tool` tool call is decided and carried out (plan
 // §5.6). Every provider adapter ends up at POST /api/remote-relays/tool, whose
 // handler calls dispatch(). In order:
 //
@@ -114,7 +115,7 @@ const TITLE_MAX = 80;
 
 // The provider settings routes a relay serves; github (Copilot) has none with
 // models — its catalogue is /api/models plus /api/status defaultModel.
-const SETTINGS_PROVIDERS = Object.freeze(['claude', 'cursor', 'grok', 'openai', 'claude-cloud', 'deepseek']);
+const SETTINGS_PROVIDERS = Object.freeze(['claude', 'cursor', 'grok', 'openai', 'claude-cloud', 'deepseek', 'claude-api']);
 // A Claude Cloud session clones a GitHub repository instead of opening a
 // folder: create_session takes `repo` and `branch` for it.
 const CLOUD_PROVIDER = REMOTE_RELAY_CLOUD_PROVIDER;
@@ -141,6 +142,7 @@ const CATALOG_PROVIDER_LABELS = Object.freeze({
   grok: 'grok',
   'claude-cloud': 'claude-cloud',
   deepseek: 'deepseek',
+  'claude-api': 'claude-api',
 });
 // Worker statuses that mean "working on something right now" (scope active).
 const WORKING_WORKER_STATUSES = new Set(['starting', 'processing']);
@@ -1926,7 +1928,7 @@ export function createRemoteRelayDispatcher({
    * When the replay fails too, nobody knows; the error carries the session
    * and message id so the agent checks with wait instead of sending again.
    */
-  async function postPrompt(ctx, { session, text, origin, model, mode, effort }) {
+  async function postPrompt(ctx, { session, text, origin, model, mode, effort, billing = '' }) {
     const messageId = String(randomUUID());
     const body = {
       conversationId: session,
@@ -1937,13 +1939,18 @@ export function createRemoteRelayDispatcher({
       ...(mode ? { relayMode: mode } : {}),
       ...(effort ? { reasoningEffort: effort } : {}),
     };
+    // A Claude session moved to another billing with this message: one call,
+    // which switches and enqueues together on the target, or does neither.
+    const post = () => (billing
+      ? postBillingSwitch(ctx, session, { to: billing, by: 'agent', message: body })
+      : call(ctx, 'POST', '/api/message', { body }));
     let sent;
     try {
-      sent = await call(ctx, 'POST', '/api/message', { body });
+      sent = await post();
     } catch (error) {
       if (!isTransientRemoteError(error)) throw error;
       try {
-        sent = await call(ctx, 'POST', '/api/message', { body });
+        sent = await post();
       } catch (retryError) {
         if (isOwnDuplicateMessage(retryError, messageId)) return { duplicate: false, messageId };
         if (!isTransientRemoteError(retryError)) throw retryError;
@@ -1969,6 +1976,36 @@ export function createRemoteRelayDispatcher({
     };
   }
 
+  /**
+   * POST /api/conversation/:id/billing with a message. A relay older than the
+   * switch answers 404 without a code: nothing was switched or sent. Its
+   * refusals (the billing not set up there, the model, the cap, the
+   * history) keep the remote's words.
+   */
+  async function postBillingSwitch(ctx, session, body) {
+    try {
+      return await call(ctx, 'POST', sessionPath(session, '/billing'), { body });
+    } catch (error) {
+      if (isTransientRemoteError(error)) throw error;
+      const remoteCode = toText(error?.remoteBody?.code);
+      const label = body.to === 'claude-api' ? 'the API key' : 'the subscription';
+      if (Number(error?.status) === 404 && !remoteCode) {
+        throw new DispatchFailure(409, REMOTE_RELAY_ERROR_CODES.unsupported,
+          `Relay "${ctx.relay.name}" cannot switch a session's billing (it runs an OAR from before the switch); nothing was sent. Send without provider to keep the session's billing.`,
+          { session });
+      }
+      const remoteText = toText(error?.remoteBody?.error) || toText(error?.message);
+      const code = remoteCode === 'CLAUDE_BILLING_MODEL_UNAVAILABLE'
+        ? REMOTE_RELAY_ERROR_CODES.unknownModel
+        : (['CLAUDE_API_NOT_CONFIGURED', 'CLAUDE_NOT_CONFIGURED', 'CLAUDE_API_CAP_REACHED'].includes(remoteCode)
+          ? REMOTE_RELAY_ERROR_CODES.providerUnavailable
+          : (Number(error?.status) === 404 ? REMOTE_RELAY_ERROR_CODES.notFound : REMOTE_RELAY_ERROR_CODES.invalidInput));
+      throw new DispatchFailure(Number(error?.status) || 409, code,
+        `Relay "${ctx.relay.name}" did not switch session ${session} to ${label}: ${remoteText || 'refused'}. Nothing was sent.`,
+        { session, ...(remoteCode ? { remoteCode } : {}) });
+    }
+  }
+
   /**
    * What the remote made of the effort: `reported` is the one it bound (the
    * bootstrap's preferredReasoningEffort, the message's
@@ -2090,10 +2127,19 @@ export function createRemoteRelayDispatcher({
     }
     const runtime = isPlainObject(conversation?.runtimeSession) ? conversation.runtimeSession : {};
     const provider = toText(runtime.providerType).toLowerCase() || 'github';
+    // `provider` on a send is a Claude session's billing: the subscription
+    // or the API key. The other one switches the session with this message.
+    const billing = toText(args.provider).toLowerCase();
+    if (billing && !REMOTE_RELAY_SEND_PROVIDERS.includes(provider)) {
+      throw new DispatchFailure(400, REMOTE_RELAY_ERROR_CODES.invalidInput,
+        `Session ${session} on relay "${ctx.relay.name}" runs on ${provider}: provider on send switches a Claude session's billing only. Nothing was sent.`,
+        { session, provider });
+    }
+    const switchTo = billing && billing !== provider ? billing : '';
     // Checked before any approval card (runRelayAction) when the session
-    // could be read there; here otherwise.
+    // could be read there; here otherwise. Against the billing it moves to.
     const settled = args.model
-      ? (ctx.settledModel || await settleSendModel(ctx, conversation, args.model))
+      ? (ctx.settledModel || await settleSendModel(ctx, conversation, args.model, { provider: billing }))
       : null;
     const requestedModel = settled?.model || '';
     const modelNote = settled?.note || null;
@@ -2110,16 +2156,25 @@ export function createRemoteRelayDispatcher({
     const requested = normalizeEffort(args.effort) || normalizeEffort(settled?.effort);
     const own = requested ? '' : normalizeEffort(conversation?.preferredReasoningEffort);
     const origin = await buildOrigin(ctx);
-    const { sent, choice } = await postPromptWithEffort(ctx, { session, text: args.text, origin, model, mode }, {
+    const { sent, choice } = await postPromptWithEffort(ctx, { session, text: args.text, origin, model, mode, billing: switchTo }, {
       effort: requested || own,
       source: requested ? EFFORT_SOURCES.requested : (own ? EFFORT_SOURCES.remote : ''),
       note: null,
     });
+    const billingNote = switchTo
+      ? `Session ${session} now runs on ${switchTo === 'claude-api' ? 'the API key' : 'the subscription'}, from this message on (a running turn finishes on the old billing).`
+      : '';
     return deliverAndWait('send', ctx, {
       session,
       sent,
       waitSeconds: args.wait_seconds,
-      extra: { ...(modelNote ? { modelNote } : {}), ...effortResult(choice) },
+      extra: {
+        ...(modelNote ? { modelNote } : {}),
+        ...(billing && REMOTE_RELAY_SEND_PROVIDERS.includes(provider) ? { provider: switchTo || provider } : {}),
+        ...(switchTo ? { billingSwitched: true } : {}),
+        ...effortResult(choice),
+        ...(billingNote ? { note: [effortResult(choice).note, billingNote].filter(Boolean).join(' ') } : {}),
+      },
     });
   }
 
@@ -2178,9 +2233,11 @@ export function createRemoteRelayDispatcher({
   }
 
   /** settleRequestedModel for a send to `conversation` (its detail payload); an unread catalogue leaves it unchecked. */
-  async function settleSendModel(ctx, conversation, requested) {
+  async function settleSendModel(ctx, conversation, requested, { provider: billing = '' } = {}) {
     const runtime = isPlainObject(conversation?.runtimeSession) ? conversation.runtimeSession : {};
-    const provider = toText(runtime.providerType).toLowerCase() || 'github';
+    const own = toText(runtime.providerType).toLowerCase() || 'github';
+    // A Claude session moving to its other billing takes that billing's list.
+    const provider = billing && REMOTE_RELAY_SEND_PROVIDERS.includes(own) ? billing : own;
     let catalog = null;
     try {
       catalog = await loadCatalog(ctx);
@@ -2329,10 +2386,29 @@ export function createRemoteRelayDispatcher({
       // From here the new session's queued turn counts toward the cap itself.
       ctx.onPromptQueued?.();
     } catch (error) {
-      if (!choice.effort || !isEffortRejection(error)) throw error;
       // The session exists by now: say so, or the agent starts a second one.
+      const remoteCode = toText(error?.remoteBody?.code);
+      if (!choice.effort || !isEffortRejection(error)) {
+        // The remote's own 4xx is passed on, anything else is a 502, as
+        // mapRemoteError answers them.
+        const code = toText(error?.code);
+        const remoteStatus = Number(error?.status) || 0;
+        const status = error instanceof DispatchFailure
+          ? error.status
+          : (code.startsWith(REMOTE_RELAY_ERROR_CODES.httpPrefix) && remoteStatus >= 400 && remoteStatus < 500 ? remoteStatus : 502);
+        const supportedModels = Array.isArray(error?.remoteBody?.supportedModels) ? error.remoteBody.supportedModels.slice(0, 50) : null;
+        throw new DispatchFailure(status, code || `${REMOTE_RELAY_ERROR_CODES.httpPrefix}${status}`,
+          `${toText(error?.message).replace(/[.\s]+$/, '') || `Relay "${ctx.relay.name}" refused the first prompt`}. The session ${session} was created, but the prompt was not queued.`,
+          {
+            ...(isPlainObject(error?.extra) ? error.extra : {}),
+            session,
+            ...(remoteCode ? { remoteCode } : {}),
+            ...(supportedModels ? { supportedModels } : {}),
+            openUrl: remoteConversationUrl(ctx.relay.url, session) || null,
+            note: 'Use send with this session (update_session to change its model); do not create another session.',
+          });
+      }
       const supported = supportedEffortsOf(error);
-      const remoteCode = toText(error.remoteBody?.code);
       throw new DispatchFailure(400, toText(error.code) || `${REMOTE_RELAY_ERROR_CODES.httpPrefix}400`,
         `${toText(error.message) || `Relay "${ctx.relay.name}" refused effort "${choice.effort}"`}. The session was created, but the prompt was not queued.`,
         {
@@ -3711,7 +3787,7 @@ export function createRemoteRelayDispatcher({
           }
         } else {
           const conversation = await call(early, 'GET', sessionPath(args.session), { query: { limit: 1 } });
-          settledModel = await settleSendModel(early, conversation, args.model);
+          settledModel = await settleSendModel(early, conversation, args.model, { provider: args.provider });
         }
       } catch (error) {
         if (error instanceof DispatchFailure) {
@@ -3722,6 +3798,18 @@ export function createRemoteRelayDispatcher({
         settledModel = null;
       }
     }
+    // The card names a billing switch only when the send makes one: a
+    // provider that is already the session's billing changes nothing. Read
+    // off the target before anyone is asked; a target that cannot be read
+    // keeps the line (the send itself then answers).
+    let cardArgs = args;
+    if (action === 'send' && args.provider) {
+      try {
+        const conversation = await call({ relay, caller, hops, conversationId, signal }, 'GET', sessionPath(args.session), { query: { limit: 1 } });
+        const runtime = isPlainObject(conversation?.runtimeSession) ? conversation.runtimeSession : {};
+        if (toText(runtime.providerType).toLowerCase() === args.provider) cardArgs = { ...args, provider: undefined };
+      } catch {}
+    }
     // What an update_session would change, settled on the target before
     // anyone is asked: an unknown model or group, a busy session or a change
     // to nothing never raises a card.
@@ -3788,7 +3876,7 @@ export function createRemoteRelayDispatcher({
           callerContext: caller,
           relay: relayTarget(relay),
           action,
-          args,
+          args: cardArgs,
           summary: summarizeRemoteRelayCall({ action, ...args, relay: relay.name }),
           signal,
           agentPrompts: agentPrompts(conversationId).count,
@@ -3810,7 +3898,7 @@ export function createRemoteRelayDispatcher({
           callerContext: caller,
           relay: relayTarget(relay),
           action,
-          args,
+          args: cardArgs,
           summary: summarizeRemoteRelayCall({ action, ...args, relay: relay.name }),
           signal,
           ...(group ? { group } : {}),
@@ -3897,7 +3985,13 @@ export function createRemoteRelayDispatcher({
     // wait_seconds is cut to this relay's "longest wait" setting, for every
     // target: the waiting is done here, by polling the target.
     const { maxWaitSeconds } = agentSessions();
-    const validation = validateRemoteRelayToolInput({ ...(isPlainObject(args) ? args : {}), action }, { maxWaitSeconds });
+    // The server must always pass the provider lists: without them the
+    // contract checks a provider's shape only (the worker's path).
+    const validation = validateRemoteRelayToolInput({ ...(isPlainObject(args) ? args : {}), action }, {
+      maxWaitSeconds,
+      providers: REMOTE_RELAY_PROVIDERS,
+      sendProviders: REMOTE_RELAY_SEND_PROVIDERS,
+    });
     const result = await runValidated({ conversationId, req, signal }, validation);
     // The arguments the action does not take, named on the answer (a call
     // that came through a worker's tool had them named there already).

package/server/services/remote-relay-registry-service.mjs

@@ -27,7 +27,7 @@ import { remoteRelayAliases } from '../../shared/remote-relay-mentions.mjs';
 //   remote_relay_inbound_enabled accept prompts from other relays' agents
 //   agent_sessions_enabled       this relay's own agents may start and use
 //                                sessions on it (the local target; off by default)
-//   remote_relay_max_wait_seconds the longest wait of one remote_relay call
+//   remote_relay_max_wait_seconds the longest wait of one relay_tool call
 //
 // Tokens never leave through listPublic(), the socket event or any route; only
 // the outbound client reads them (list()/get()/resolve() are server-internal).

package/server/services/session-worker-launch-service.mjs

@@ -311,6 +311,34 @@ export function applyDeepSeekProviderEnvironment(env = {}, {
   return next;
 }
 
+/**
+ * Claude API: the Claude worker's runner on an API key from the Claude
+ * Console instead of the host's subscription login
+ * (server/claude-api-worker/). The key travels as OAR_CLAUDE_API_KEY, through
+ * the secret file under tmux, and becomes the CLI's ANTHROPIC_API_KEY only
+ * inside its spawn environment (claude-api-backend.mjs). The worker shares the
+ * host's Claude Code state directory with the Claude provider: transcripts,
+ * resume and task output are found where a Claude chat's are.
+ */
+export function applyClaudeApiProviderEnvironment(env = {}, {
+  enabled = false,
+  model = '',
+  apiKey = '',
+} = {}) {
+  const next = { ...env };
+  if (resolveWorkerKind(next) === 'claude-api') delete next.COPILOT_WEB_RELAY_WORKER_KIND;
+  delete next.CLAUDE_API_RELAY_MODEL;
+  delete next.OAR_CLAUDE_API_KEY;
+  if (!enabled) return next;
+  const normalizedApiKey = normalizeText(apiKey);
+  if (!normalizedApiKey) throw new Error('claude-api-key-not-configured');
+  next.COPILOT_WEB_RELAY_WORKER_KIND = 'claude-api';
+  next.OAR_CLAUDE_API_KEY = normalizedApiKey;
+  const normalizedModel = normalizeText(model);
+  if (normalizedModel) next.CLAUDE_API_RELAY_MODEL = normalizedModel;
+  return next;
+}
+
 /**
  * The Copilot SDK engine: the same `github`/`openai` providers the extension
  * serves, run as a plain Node worker against the CLI's headless runtime.
@@ -404,6 +432,10 @@ export function isDeepSeekWorkerEnvironment(env = {}) {
   return resolveWorkerKind(env) === 'deepseek';
 }
 
+export function isClaudeApiWorkerEnvironment(env = {}) {
+  return resolveWorkerKind(env) === 'claude-api';
+}
+
 export function isCopilotSdkWorkerEnvironment(env = {}) {
   return resolveWorkerKind(env) === 'copilot-sdk';
 }
@@ -458,6 +490,16 @@ export function resolveDeepSeekWorkerScriptPath(env = {}) {
   return path.join(process.cwd(), 'server', 'deepseek-worker', 'deepseek-session-worker.mjs');
 }
 
+export function resolveClaudeApiWorkerScriptPath(env = {}) {
+  const explicit = normalizeText(env?.COPILOT_WEB_RELAY_CLAUDE_API_WORKER_PATH);
+  if (explicit) return explicit;
+  const repoRoot = normalizeText(env?.COPILOT_WEB_RELAY_ROOT);
+  if (repoRoot) return path.join(repoRoot, 'server', 'claude-api-worker', 'claude-api-session-worker.mjs');
+  const serverDir = normalizeText(env?.COPILOT_WEB_RELAY_SERVER_DIR);
+  if (serverDir) return path.join(serverDir, 'claude-api-worker', 'claude-api-session-worker.mjs');
+  return path.join(process.cwd(), 'server', 'claude-api-worker', 'claude-api-session-worker.mjs');
+}
+
 export function resolveCopilotSdkWorkerScriptPath(env = {}) {
   const explicit = normalizeText(env?.COPILOT_WEB_RELAY_COPILOT_SDK_WORKER_PATH);
   if (explicit) return explicit;
@@ -487,6 +529,10 @@ const NODE_WORKER_DESCRIPTORS = Object.freeze({
     windowsTitle: 'Copilot SDK Worker',
   }),
   deepseek: Object.freeze({ resolveScriptPath: resolveDeepSeekWorkerScriptPath, windowsTitle: 'DeepSeek Worker' }),
+  'claude-api': Object.freeze({
+    resolveScriptPath: resolveClaudeApiWorkerScriptPath,
+    windowsTitle: 'Claude API Worker',
+  }),
 });
 
 function resolveNodeWorkerDescriptor(env = {}) {
@@ -525,7 +571,7 @@ function buildPosixWorkerLaunchCommand(targetSessionId, env = {}, extraCliArgs =
 // Server entry shape (the CLI's own `copilot mcp add` writes the same):
 // `{ type: 'local', command, args, env, tools: ['*'], timeout }`. `timeout` is
 // the per-call limit in ms; without it the CLI cuts a tool call off at 180 s,
-// shorter than one remote_relay wait.
+// shorter than one relay_tool wait.
 
 export function resolveOarMcpServerScriptPath(env = {}, { pathImpl = path } = {}) {
   const repoRoot = normalizeText(env?.COPILOT_WEB_RELAY_ROOT);
@@ -662,6 +708,7 @@ export const WORKER_SECRET_ENV_VARS = Object.freeze([
   'CURSOR_API_KEY',
   'CLAUDE_CODE_OAUTH_TOKEN',
   'DEEPSEEK_API_KEY',
+  'OAR_CLAUDE_API_KEY',
   'ANTHROPIC_API_KEY',
   'ANTHROPIC_AUTH_TOKEN',
 ]);
@@ -682,6 +729,11 @@ export const WORKER_SECRET_ENV_VARS = Object.freeze([
 // - The DeepSeek key is put there by its own applier, but the same name could
 //   also sit in the relay's environment (a shell that exports it); it is the
 //   DeepSeek worker's alone either way.
+// - The Claude API key is the Claude API worker's alone, the same way. It
+//   travels under a name of the relay's (OAR_CLAUDE_API_KEY), never as
+//   ANTHROPIC_API_KEY: the worker's CLI is the only process that gets it under
+//   that name (claude-api-backend.mjs), and a host's ANTHROPIC_API_KEY stays
+//   what it is below, no worker's.
 // - A host's ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are no worker's (an
 //   empty list): Claude Code prefers either to the Claude login, so a Claude
 //   chat would run, and be billed, on a key nobody chose for it, and every
@@ -691,6 +743,7 @@ export const WORKER_SECRET_ENV_VARS = Object.freeze([
 const WORKER_SECRET_ENV_VAR_KINDS = Object.freeze({
   CLAUDE_CODE_OAUTH_TOKEN: Object.freeze(['claude', 'claude-cloud']),
   DEEPSEEK_API_KEY: Object.freeze(['deepseek']),
+  OAR_CLAUDE_API_KEY: Object.freeze(['claude-api']),
   ANTHROPIC_API_KEY: Object.freeze([]),
   ANTHROPIC_AUTH_TOKEN: Object.freeze([]),
 });
@@ -867,6 +920,12 @@ export const TMUX_WORKER_EXPORTED_ENV_VARS = Object.freeze([
   'DEEPSEEK_RELAY_MODEL',
   'DEEPSEEK_BASE_URL',
   'DEEPSEEK_CLAUDE_CONFIG_DIR',
+  // The Claude API worker's model; its key comes through the file like
+  // DeepSeek's. Tests point the worker's CLI at a fake Anthropic API on this
+  // machine the way they point the cloud client (shared/anthropic-api.mjs
+  // takes a loopback URL only, and so does the worker).
+  'CLAUDE_API_RELAY_MODEL',
+  'OAR_ANTHROPIC_API_BASE_URL',
   'GROK_RELAY_MODEL',
   'GROK_CLI_COMMAND',
   'GROK_ALWAYS_APPROVE',
@@ -1128,7 +1187,7 @@ export async function launchSessionCli({
   // Set per launch below, never inherited: a relay started from inside a
   // worker session would otherwise hand its workers that session's log.
   delete launchSessionEnv[WORKER_LOG_FILE_ENV];
-  // The extension engine gets the OAR MCP server (remote_relay + preview) the
+  // The extension engine gets the OAR MCP server (relay_tool + preview) the
   // node workers carry in-process; every launch path appends the same args.
   const extensionCliArgs = resolveNodeWorkerDescriptor(launchSessionEnv)
     ? []

package/server/services/session-worker-registry-service.mjs

@@ -61,6 +61,16 @@ function normalizeStatus(value) {
 }
 
 const STEERING_HOLD_REASONS = new Set(['question', 'compaction', 'adoption', 'delivery', 'tool', 'other']);
+// What keeps a Claude worker's CLI from being released for a billing swap.
+const STEERING_RELEASE_HOLDS = new Set(['question', 'compaction', 'turn', 'background']);
+const WORKER_KIND_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+
+// The kind a worker says it is ("claude", "claude-api", "deepseek", ...):
+// lower case, short, or null when it did not say.
+export function normalizeWorkerKind(value) {
+  const kind = String(value || '').trim().toLowerCase();
+  return WORKER_KIND_PATTERN.test(kind) ? kind : null;
+}
 const STEERING_MESSAGE_ID_MAX_LENGTH = 64;
 const STEERING_CANCELLABLE_IDS_MAX = 50;
 
@@ -122,6 +132,15 @@ export function normalizeWorkerSteeringSnapshot(raw) {
   // Only a snapshot that reports a running CLI carries the key.
   const autoCompactWindow = normalizeSteeringAutoCompactWindow(raw.autoCompactWindow);
   if (autoCompactWindow) snapshot.autoCompactWindow = autoCompactWindow;
+  // Whether the relay may replace the worker now (a Claude billing swap), and
+  // what holds it when not. Only a worker that reports it carries the keys.
+  if (typeof raw.releasable === 'boolean') {
+    snapshot.releasable = raw.releasable;
+    const hold = String(raw.releaseHold || '').trim().toLowerCase();
+    snapshot.releaseHold = !raw.releasable && STEERING_RELEASE_HOLDS.has(hold) ? hold : null;
+    const tasks = Number(raw.backgroundTaskCount);
+    snapshot.backgroundTaskCount = Number.isInteger(tasks) && tasks > 0 ? Math.min(tasks, 999) : 0;
+  }
   return snapshot;
 }
 
@@ -140,6 +159,7 @@ function sanitizeState(raw = null) {
     retryCount: toNonNegativeInt(base.retryCount, 0),
     lastError: String(base.lastError || '').trim() || null,
     steering: normalizeWorkerSteeringSnapshot(base.steering),
+    kind: normalizeWorkerKind(base.kind),
     updatedAt: normalizeTimestamp(base.updatedAt, nowIso),
     createdAt,
   };
@@ -244,7 +264,14 @@ export function createSessionWorkerRegistry() {
     // the old entry into every upsert, so without this a crashed worker's
     // hold outlived it and the composer showed it until a replacement
     // heartbeated — indefinitely, if none ever did.
-    if (existing && isWorkerReplacedOrGone(existing, next)) next.steering = null;
+    // The kind is the same: a process's own word. An upsert that does not
+    // state it keeps the known one, unless the process it described is gone.
+    const statesKind = Object.prototype.hasOwnProperty.call(rawState, 'kind');
+    if (!statesKind) next.kind = existing?.kind || null;
+    if (existing && isWorkerReplacedOrGone(existing, next)) {
+      next.steering = null;
+      if (!statesKind) next.kind = null;
+    }
     clearIndexesForSession(existing);
     bySession.set(state.sdkSessionId, next);
     updateIndexesForSession(next);

package/server/services/session-worker-websocket-service.mjs

@@ -108,6 +108,9 @@ export function createSessionWorkerWebSocketService({
   onDeliverySendFailed = async () => {},
   onWorkerSocketClosed = async () => {},
   requestWork = async () => null,
+  // A worker stated its kind ("claude", "claude-api", ...) in a hello or a
+  // ready: (sessionId, kind, pid). The registry keeps it.
+  onWorkerKind = () => {},
   // Liveness probe for a socket's worker process. A killed worker's socket
   // survives its process by an event-loop turn (the kill path blocks the loop,
   // so this service's timer runs before the socket close lands), and asking for
@@ -233,6 +236,15 @@ export function createSessionWorkerWebSocketService({
     }
   }
 
+  // The kind a hello or ready states, kept on the socket (a process does not
+  // change kind) and reported once per change.
+  function noteWorkerKind(meta, payload) {
+    const kind = String(payload?.kind || '').trim().toLowerCase();
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(kind) || meta.workerKind === kind) return;
+    meta.workerKind = kind;
+    try { onWorkerKind(meta.sessionId, kind, meta.pid); } catch {}
+  }
+
   function noteHeartbeat(meta, reason = 'worker-message') {
     if (!meta?.sessionId) return;
     try {
@@ -258,6 +270,9 @@ export function createSessionWorkerWebSocketService({
         sessionId: meta.sessionId,
         pid: meta.pid,
         reason,
+        // What this socket's worker said it is: a Claude chat's row goes only
+        // to a worker of its billing.
+        workerKind: meta.workerKind || null,
       });
       touchCli();
       if (!pending || typeof pending !== 'object') return false;
@@ -404,6 +419,7 @@ export function createSessionWorkerWebSocketService({
       if (payload.type === 'worker.hello') {
         if (!bindSocketIdentity(ws, meta, payload)) return;
         meta.lastSeenAtMs = nowMsSafe();
+        noteWorkerKind(meta, payload);
         // A worker holding deliveries (open question card, compaction) binds
         // its identity with hello but must not be handed work.
         meta.ready = payload.ready !== false;
@@ -423,6 +439,7 @@ export function createSessionWorkerWebSocketService({
       if (payload.type === 'worker.ready') {
         if (!bindSocketIdentity(ws, meta, payload)) return;
         meta.lastSeenAtMs = nowMsSafe();
+        noteWorkerKind(meta, payload);
         meta.ready = true;
         meta.lastReadyAt = nowIso();
         noteHeartbeat(meta, String(payload.reason || 'worker-ready'));

package/server/services/usage-limit-pause-service.mjs

@@ -175,10 +175,11 @@ export function createUsageLimitPauseService({
    * Decide whether a refused turn is paused. Returns the plan, or null when
    * the response is to be handled as the terminal failure it says it is.
    */
-  function planPause({ terminalError, conversationId, providerType, queueRow = null, partialText = '' } = {}) {
+  function planPause({ terminalError, conversationId, providerType, chatProviderType = null, queueRow = null, partialText = '' } = {}) {
     if (!isUsageLimitTerminalError(terminalError)) return null;
     // Claude sessions, local and in the cloud: both run Claude Code on the
-    // same account and report the same limit.
+    // same account and report the same limit. `providerType` is what the
+    // refused turn ran on.
     if (!['claude', 'claude-cloud'].includes(String(providerType || '').trim().toLowerCase())) return null;
     if (!String(conversationId || '').trim()) return null;
     const at = now();
@@ -187,6 +188,21 @@ export function createUsageLimitPauseService({
     // What the turn had written before the refusal stays above the note.
     const written = String(partialText || '').trim();
     const withWritten = (note) => (written ? `${written}\n\n${note}` : note);
+    // The chat moved to the API key while this subscription turn ran: its
+    // follow-up is not held for the subscription's reset, it runs on the key
+    // at once (a row on the key is never held for the usage limit).
+    if (String(chatProviderType || '').trim().toLowerCase() === 'claude-api') {
+      return {
+        conversationId: String(conversationId),
+        rateLimitType,
+        resetsAt: null,
+        resumeAt: null,
+        auto: false,
+        retries: 0,
+        onApiKey: true,
+        noteText: withWritten(`⏸ Stopped at the Claude ${label}. This chat now runs on the Claude API key, so the turn carries on there.`),
+      };
+    }
     const resetsAtMs = Date.parse(String(terminalError.resetsAt || ''));
     if (!Number.isFinite(resetsAtMs) || resetsAtMs <= at) {
       // Counted along the follow-ups: the refused row is one itself when the
@@ -232,7 +248,8 @@ export function createUsageLimitPauseService({
   function schedulePause(plan, { queueRow = null } = {}) {
     if (!plan?.conversationId) return null;
     const at = new Date(now()).toISOString();
-    const heldUntil = plan.auto ? plan.resumeAt : HELD_UNTIL_RESUMED;
+    // On the key: due now, never held.
+    const heldUntil = plan.onApiKey ? null : (plan.auto ? plan.resumeAt : HELD_UNTIL_RESUMED);
     // What this refusal cut off. A refused follow-up stands for what it
     // quoted; a turn of the CLI's own has no prompt.
     const refusedFollowUp = parseJson(queueRow?.usage_limit_pause);
@@ -251,6 +268,7 @@ export function createUsageLimitPauseService({
         resetsAt: plan.resetsAt,
         auto: plan.auto,
         retries: Number(plan.retries || 0),
+        ...(plan.onApiKey ? { onApiKey: true, resumedAt: at, resumedBy: 'billing-switch' } : {}),
         pausedAt: at,
         refusedMessageId: queueRow?.id ? String(queueRow.id) : null,
         prompts,
@@ -345,8 +363,15 @@ export function createUsageLimitPauseService({
       } catch {}
     }
     const state = getPause(plan.conversationId);
-    try { logger.log?.(`[usage-limit] conv=${plan.conversationId.slice(0, 8)} paused at the ${usageLimitWindowLabel(plan.rateLimitType)}; ${plan.auto ? `resumes ${plan.resumeAt}` : `resets ${plan.resetsAt}, waits for the user`}`); } catch {}
+    try {
+      logger.log?.(`[usage-limit] conv=${plan.conversationId.slice(0, 8)} ${plan.onApiKey
+        ? `stopped at the ${usageLimitWindowLabel(plan.rateLimitType)}; carries on on the API key`
+        : `paused at the ${usageLimitWindowLabel(plan.rateLimitType)}; ${plan.auto ? `resumes ${plan.resumeAt}` : `resets ${plan.resetsAt}, waits for the user`}`}`);
+    } catch {}
     emitPause(plan.conversationId, state);
+    if (plan.onApiKey) {
+      try { onQueueChanged('usage-limit-on-api-key'); } catch {}
+    }
     return { messageId, created: Boolean(created), state };
   }
 
@@ -375,6 +400,31 @@ export function createUsageLimitPauseService({
     return { resumed: true, messageId: String(row.id), state: null };
   }
 
+  /**
+   * Release the held follow-up because the chat moved to the API key: it
+   * runs now, on the key (the billing switch re-stamped it). Called inside
+   * the switch's transaction; `announce()` tells the clients once that has
+   * committed. Null when nothing is held.
+   */
+  function releaseForBillingSwitch({ conversationId, by = 'billing-switch' } = {}) {
+    const id = String(conversationId || '').trim();
+    const row = id ? findPausedRowForConversation.get(id) : null;
+    if (!row || !stateFromRow(row)) return null;
+    const pause = parseJson(row.usage_limit_pause) || {};
+    const at = new Date(now()).toISOString();
+    setPause.run(null, JSON.stringify({ ...pause, resumedAt: at, resumedBy: String(by || 'billing-switch') }), row.id);
+    const messageId = String(row.id);
+    return {
+      messageId,
+      announce() {
+        try { logger.log?.(`[usage-limit] conv=${id.slice(0, 8)} released by the switch to the API key`); } catch {}
+        emitPause(id, null);
+        try { emit('message_status', { messageId, conversationId: id, status: 'pending' }); } catch {}
+        try { onQueueChanged('usage-limit-billing-switch'); } catch {}
+      },
+    };
+  }
+
   /** Drop the held follow-up: the paused turn is not carried on. */
   function cancel({ conversationId } = {}) {
     const id = String(conversationId || '').trim();
@@ -436,6 +486,7 @@ export function createUsageLimitPauseService({
     getPause,
     listPauses,
     resumeNow,
+    releaseForBillingSwitch,
     cancel,
     recordReport,
     getAccountState: accountState,

package/server/services/worker-secret-redaction.mjs

@@ -45,6 +45,7 @@
 // A provider registers its key by one entry in SAVED_PROVIDER_KEY_SETTINGS.
 
 import { DEEPSEEK_PROVIDER_TYPE } from '../../shared/deepseek-models.mjs';
+import { CLAUDE_API_KEY_SETTING_KEY, CLAUDE_API_PROVIDER_TYPE } from './claude-api-settings-service.mjs';
 import { DEEPSEEK_API_KEY_SETTING_KEY } from './deepseek-settings-service.mjs';
 
 export const REDACTED_SECRET_TEXT = '[redacted]';
@@ -64,6 +65,7 @@ export const WORKER_SESSION_HEADER = 'x-relay-session-id';
 /** The providers whose workers get a key saved in the relay's settings. */
 export const SAVED_PROVIDER_KEY_SETTINGS = Object.freeze([
   Object.freeze({ provider: DEEPSEEK_PROVIDER_TYPE, settingKey: DEEPSEEK_API_KEY_SETTING_KEY }),
+  Object.freeze({ provider: CLAUDE_API_PROVIDER_TYPE, settingKey: CLAUDE_API_KEY_SETTING_KEY }),
 ]);
 
 // JSON bodies are shallow in practice; a deeper one is left as it is below