@oar-sh/oar 0.9.17 → 0.9.18

package/shared/anthropic-api.mjs

@@ -0,0 +1,202 @@
+// A small client for the one Anthropic endpoint the relay calls itself with a
+// Claude API key: `GET /v1/models`, the model discovery of the Claude API
+// provider (Settings → Providers → Claude API). Turns do not go through here:
+// the session worker runs Claude Code on the key.
+//
+// The key goes to the Anthropic API and nowhere else. The only other target
+// is a fake API on the loopback interface, named by OAR_ANTHROPIC_API_BASE_URL
+// for tests; any other value of that variable is ignored (the rule of
+// shared/claude-cloud/base-url.mjs, which this module reuses). There is no
+// base-URL setting and no parameter that takes one.
+//
+// The key is in no error this module produces: a response body is quoted only
+// after the key has been taken out of it.
+
+import { loopbackBaseUrlOrNull } from './claude-cloud/base-url.mjs';
+
+export const ANTHROPIC_API_BASE_URL = 'https://api.anthropic.com';
+export const ANTHROPIC_API_BASE_URL_ENV = 'OAR_ANTHROPIC_API_BASE_URL';
+export const ANTHROPIC_API_VERSION = '2023-06-01';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+// The largest page `GET /v1/models` serves.
+const MODELS_PAGE_LIMIT = 1000;
+// One page holds every model today; the cap keeps a cursor that never ends
+// from turning into an endless walk.
+const MAX_MODEL_PAGES = 20;
+const MAX_DETAIL_CHARS = 240;
+// The effort levels the Models API reports per model, in ladder order.
+const EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
+
+/**
+ * The base URL for the client: the loopback URL named by
+ * OAR_ANTHROPIC_API_BASE_URL, else the Anthropic API.
+ */
+export function resolveAnthropicApiBaseUrl(env = process.env) {
+  return loopbackBaseUrlOrNull(env?.[ANTHROPIC_API_BASE_URL_ENV]) || ANTHROPIC_API_BASE_URL;
+}
+
+export class AnthropicApiError extends Error {
+  constructor(message, { code = 'error', status = null } = {}) {
+    super(message);
+    this.name = 'AnthropicApiError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+function codeForStatus(status) {
+  if (status === 401) return 'unauthorized';
+  if (status === 403) return 'forbidden';
+  if (status === 402) return 'billing';
+  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 toText(value) {
+  return String(value ?? '').trim();
+}
+
+function positiveInteger(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.trunc(number) : null;
+}
+
+/**
+ * A capability as the API writes it (`{ supported: true }`) or as a plain
+ * boolean; null when it is missing or of another shape.
+ */
+function capabilitySupported(value) {
+  if (typeof value === 'boolean') return value;
+  if (value && typeof value === 'object' && typeof value.supported === 'boolean') return value.supported;
+  return null;
+}
+
+/** `{ type: 'error', error: { type, message } }` as one line, or the raw text. */
+function errorDetail(text) {
+  const raw = toText(text);
+  if (!raw) return '';
+  try {
+    const parsed = JSON.parse(raw);
+    const type = toText(parsed?.error?.type);
+    const message = toText(parsed?.error?.message);
+    if (type || message) return [type, message].filter(Boolean).join(': ');
+  } catch {
+    // Not JSON: the text as it came.
+  }
+  return raw;
+}
+
+/**
+ * One entry of `GET /v1/models` in OAR's terms, or null without an id:
+ * `{ id, displayName, contextWindow, maxOutput, imageInput, effort,
+ * effortLevels, thinking, thinkingTypes }`. Every field but the id may be
+ * missing in an answer, so each one is null (or an empty list) then.
+ */
+export function mapAnthropicModel(entry) {
+  const id = toText(entry?.id);
+  if (!id) return null;
+  const capabilities = entry?.capabilities && typeof entry.capabilities === 'object' ? entry.capabilities : {};
+  const effort = capabilities.effort;
+  const effortObject = effort && typeof effort === 'object' ? effort : {};
+  const thinking = capabilities.thinking;
+  const thinkingTypesObject = thinking && typeof thinking === 'object' && thinking.types && typeof thinking.types === 'object'
+    ? thinking.types
+    : {};
+  return {
+    id,
+    displayName: toText(entry?.display_name) || id,
+    contextWindow: positiveInteger(entry?.max_input_tokens),
+    maxOutput: positiveInteger(entry?.max_tokens),
+    imageInput: capabilitySupported(capabilities.image_input),
+    effort: capabilitySupported(effort),
+    effortLevels: EFFORT_LEVELS.filter((level) => capabilitySupported(effortObject[level]) === true),
+    thinking: capabilitySupported(thinking),
+    thinkingTypes: Object.keys(thinkingTypesObject)
+      .filter((type) => capabilitySupported(thinkingTypesObject[type]) === true)
+      .map((type) => type.toLowerCase()),
+  };
+}
+
+export function createAnthropicApiClient({
+  apiKey = '',
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const baseUrl = resolveAnthropicApiBaseUrl(env);
+  const key = toText(apiKey);
+
+  async function getJson(pathname, what) {
+    if (!key) throw new AnthropicApiError('Claude API key is not configured', { code: 'not_configured' });
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}${pathname}`, {
+        headers: {
+          'x-api-key': key,
+          'anthropic-version': ANTHROPIC_API_VERSION,
+          accept: 'application/json',
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (error) {
+      const timedOut = error?.name === 'TimeoutError' || error?.name === 'AbortError';
+      throw new AnthropicApiError(
+        timedOut
+          ? `Anthropic ${what} timed out after ${timeoutMs} ms`
+          : `Anthropic ${what} failed: ${redact(error?.message || error, key)}`,
+        { code: timedOut ? 'timeout' : 'network' },
+      );
+    }
+    if (!response.ok) {
+      const detail = redact(errorDetail(await response.text().catch(() => '')), key).slice(0, MAX_DETAIL_CHARS);
+      throw new AnthropicApiError(
+        `Anthropic ${what} failed (${response.status})${detail ? `: ${detail}` : ''}`,
+        { code: codeForStatus(response.status), status: response.status },
+      );
+    }
+    try {
+      return await response.json();
+    } catch {
+      throw new AnthropicApiError(`Anthropic ${what} returned invalid JSON`, { code: 'invalid_response' });
+    }
+  }
+
+  return {
+    baseUrl,
+
+    /**
+     * Every model the key may use (mapAnthropicModel), in the API's order,
+     * without duplicates. Follows `has_more` / `last_id` page by page.
+     */
+    async listModels() {
+      const models = [];
+      const seen = new Set();
+      const cursors = new Set();
+      let afterId = '';
+      for (let page = 0; page < MAX_MODEL_PAGES; page += 1) {
+        const query = new URLSearchParams({ limit: String(MODELS_PAGE_LIMIT) });
+        if (afterId) query.set('after_id', afterId);
+        const payload = await getJson(`/v1/models?${query.toString()}`, 'model discovery');
+        for (const entry of Array.isArray(payload?.data) ? payload.data : []) {
+          const model = mapAnthropicModel(entry);
+          if (!model || seen.has(model.id)) continue;
+          seen.add(model.id);
+          models.push(model);
+        }
+        const lastId = toText(payload?.last_id);
+        if (payload?.has_more !== true || !lastId || cursors.has(lastId)) break;
+        cursors.add(lastId);
+        afterId = lastId;
+      }
+      return models;
+    },
+  };
+}

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', 'deepseek']);
+// 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', 'deepseek'` — 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).
 

package/shared/remote-relay-contract.mjs

@@ -29,9 +29,20 @@ import {
   normalizeRelayScheduleAt,
   normalizeRelayScheduleTitle,
 } from './relay-schedules.mjs';
-import { RELAY_ASK_LIMITS, RELAY_ASK_URGENCIES, normalizeRelayAskInput } from './relay-asks.mjs';
-
-export const REMOTE_RELAY_TOOL_NAME = 'remote_relay';
+import {
+  RELAY_ASK_LIMITS,
+  RELAY_ASK_URGENCIES,
+  REMOTE_RELAY_APPROVAL_SOURCE,
+  normalizeRelayAskInput,
+} from './relay-asks.mjs';
+
+// The one name every provider lists the tool under. Up to 0.9.17 it was
+// `remote_relay`; that name is still accepted where a runtime dispatches a
+// call by name without having listed it (the OAR MCP server's tools/call),
+// and recognised in transcripts and holds, but never listed: a second
+// definition would cost every turn its context.
+export const REMOTE_RELAY_TOOL_NAME = 'relay_tool';
+export const REMOTE_RELAY_LEGACY_TOOL_NAME = 'remote_relay';
 
 // Bumped when a relay starts relying on a newer inbound behaviour of its peers.
 // 0 = a relay without this feature (reachable read/prompt only, no pairing).
@@ -154,8 +165,11 @@ export const REMOTE_RELAY_PROMPT_ACTIONS = Object.freeze(['send', 'create_sessio
 export const REMOTE_RELAY_APPROVAL_MODES = Object.freeze(['ask', 'plan']);
 
 export const REMOTE_RELAY_SESSION_SCOPES = Object.freeze(['active', 'recent', 'all']);
-export const REMOTE_RELAY_PROVIDERS = Object.freeze(['github', 'openai', 'claude', 'cursor', 'grok', 'claude-cloud', 'deepseek']);
+export const REMOTE_RELAY_PROVIDERS = Object.freeze(['github', 'openai', 'claude', 'cursor', 'grok', 'claude-cloud', 'deepseek', 'claude-api']);
 export const REMOTE_RELAY_MODES = Object.freeze(['plan', 'ask', 'agent', 'autopilot']);
+// What `send` may name as `provider`: a Claude session's billing, the
+// subscription or the API key. Naming the other one switches the session.
+export const REMOTE_RELAY_SEND_PROVIDERS = Object.freeze(['claude', 'claude-api']);
 export const REMOTE_RELAY_IF_BUSY = Object.freeze(['queue', 'fail']);
 // Reasoning efforts differ per provider and model (none, low, medium, high,
 // xhigh, max, ultracode, ...), so the contract only checks the shape of the
@@ -447,13 +461,15 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     provider: {
       type: 'string',
       enum: [...REMOTE_RELAY_PROVIDERS],
-      description: 'create_session: provider (default: the same provider as this session).',
+      description: 'create_session: provider (default: the same provider as this session). '
+        + 'send to a Claude session: "claude" (the subscription) or "claude-api" (the API key) switches its billing from the next turn, '
+        + 'together with this message; the other billing must be set up there. Omit it to keep the session\'s billing.',
     },
     model: {
       type: 'string',
       description: 'create_session: model id (default: this session\'s model when the remote offers it, else the remote\'s default). '
         + 'send: switch the remote session to this model (default: it keeps its own). update_session: the session\'s model from now on. '
-        + 'Must be an id relay_info lists for the provider (Claude also takes "opus", "sonnet", "haiku"): '
+        + 'Must be an id relay_info lists for the provider (Claude and Claude API also take "opus", "sonnet", "haiku"): '
         + 'an unknown id is refused with the close matches, nothing created or sent.',
     },
     cwd: {
@@ -660,7 +676,7 @@ export const REMOTE_RELAY_ACTION_ARGUMENTS = Object.freeze({
   read_session: Object.freeze(['session', 'last', 'before', 'include_activity', 'max_chars']),
   read_task_output: Object.freeze(['session', 'task_id', 'lines']),
   wait: Object.freeze(['session', 'message_id', 'wait_seconds']),
-  send: Object.freeze(['session', 'text', 'wait_seconds', 'model', 'mode', 'effort', 'if_busy']),
+  send: Object.freeze(['session', 'text', 'wait_seconds', 'model', 'mode', 'effort', 'if_busy', 'provider']),
   create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds']),
   update_session: Object.freeze(['session', ...REMOTE_RELAY_SESSION_SETTINGS]),
   answer_question: Object.freeze(['question_id', 'answer', 'choices']),
@@ -867,6 +883,10 @@ function validateToolInput(input, { maxWaitSeconds, now } = {}) {
       const busyCheck = optionalEnum('if_busy', REMOTE_RELAY_IF_BUSY);
       if (!busyCheck.ok) return busyCheck;
       args.if_busy = args.if_busy || 'queue';
+      const providerCheck = optionalEnum('provider', REMOTE_RELAY_SEND_PROVIDERS);
+      if (!providerCheck.ok) {
+        return invalid('send takes provider "claude" (the subscription) or "claude-api" (the API key), for a Claude session only');
+      }
     } else {
       const providerCheck = optionalEnum('provider', REMOTE_RELAY_PROVIDERS);
       if (!providerCheck.ok) return providerCheck;
@@ -1222,8 +1242,8 @@ export function formatSessionGroupList(groups, max = REMOTE_RELAY_GROUP_LIMITS.r
 // another relay (ask / plan mode) is an ordinary relay question whose
 // `context.source` is this. Only that relay's user may answer it: its question
 // routes hide the card from other relays' agents and refuse their answers, and
-// a dispatcher never offers one to its agent.
-export const REMOTE_RELAY_APPROVAL_SOURCE = 'remote_relay';
+// a dispatcher never offers one to its agent. Defined in relay-asks.mjs.
+export { REMOTE_RELAY_APPROVAL_SOURCE };
 
 /** True for such a card: a formatted question, or a stored request envelope (both carry `context`). */
 export function isRemoteRelayApprovalQuestion(question) {

package/shared/remote-relay-tool-core.mjs

@@ -1,4 +1,4 @@
-// The provider-facing side of the `remote_relay` tool, in one place.
+// The provider-facing side of the `relay_tool` tool, in one place.
 //
 // Every adapter (Claude's in-process MCP server, Cursor's customTools, the
 // Copilot SDK engine's session tools, and the OAR stdio MCP server that Grok
@@ -16,12 +16,14 @@ import {
   REMOTE_RELAY_TOOL_DESCRIPTION,
   REMOTE_RELAY_TOOL_ENDPOINT,
   REMOTE_RELAY_TOOL_INPUT_SCHEMA,
+  REMOTE_RELAY_LEGACY_TOOL_NAME,
   REMOTE_RELAY_TOOL_NAME,
   summarizeRemoteRelayCall,
   validateRemoteRelayToolInput,
 } from './remote-relay-contract.mjs';
 
 export {
+  REMOTE_RELAY_LEGACY_TOOL_NAME,
   REMOTE_RELAY_TOOL_DESCRIPTION,
   REMOTE_RELAY_TOOL_ENDPOINT,
   REMOTE_RELAY_TOOL_INPUT_SCHEMA,
@@ -141,7 +143,7 @@ export function remoteRelayCancelledResult() {
 }
 
 /**
- * Executes one `remote_relay` call: validate, then forward
+ * Executes one `relay_tool` call: validate, then forward
  * `{ conversationId, action, args }` to the local relay and hand back its JSON.
  * Never throws — a refusal reads as an answer the model can act on, the same
  * contract as executePreviewTool.
@@ -256,7 +258,7 @@ export function createRemoteRelayToolGate({
 }
 
 /**
- * How many remote_relay calls of this conversation the relay is still working
+ * How many relay_tool calls of this conversation the relay is still working
  * on. 0 on any failure: the caller's watchdog then does what it would have
  * done without the question.
  */
@@ -292,14 +294,29 @@ export function formatRemoteRelayToolResult(result) {
 // ─── Activity lines ──────────────────────────────────────────────────────────
 
 // A provider may report the tool under its bare name or namespaced by the MCP
-// server that carries it (`mcp__relay__remote_relay`, `oar__remote_relay`,
-// `oar/remote_relay`, `oar-remote_relay`); all of them are this tool.
-const REMOTE_RELAY_NAME_PATTERN = new RegExp(`(?:^|__|[^A-Za-z0-9_])${REMOTE_RELAY_TOOL_NAME}$`, 'i');
+// server that carries it (`mcp__relay__relay_tool`, `oar__relay_tool`,
+// `oar/relay_tool`, `oar-relay_tool`); all of them are this tool. So is the
+// name it had before, `remote_relay`, in every spelling: transcripts and
+// sessions from before the rename still render and hold the same way.
+const REMOTE_RELAY_NAME_PATTERN = new RegExp(
+  `(?:^|__|[^A-Za-z0-9_])(?:${REMOTE_RELAY_TOOL_NAME}|${REMOTE_RELAY_LEGACY_TOOL_NAME})$`,
+  'i',
+);
 
 export function isRemoteRelayToolName(name) {
   return REMOTE_RELAY_NAME_PATTERN.test(toText(name));
 }
 
+/**
+ * The tool's listed name for a bare call name that means it: `relay_tool`
+ * itself, or the legacy `remote_relay` a dispatcher still accepts without
+ * listing it. Any other name comes back unchanged.
+ */
+export function canonicalRemoteRelayToolCallName(name) {
+  const text = toText(name);
+  return text === REMOTE_RELAY_LEGACY_TOOL_NAME ? REMOTE_RELAY_TOOL_NAME : text;
+}
+
 /**
  * The arguments of a tool call as an object, whether the provider delivered
  * them parsed or as a JSON string. Null when there is nothing usable.

package/shared/steer-settle-failure.mjs

@@ -86,6 +86,7 @@ export function steerAgentLabelForProvider(providerType) {
     case 'grok': return 'Grok';
     case 'claude-cloud': return 'Claude Cloud';
     case 'deepseek': return 'DeepSeek';
+    case 'claude-api': return 'Claude API';
     default: return DEFAULT_STEER_AGENT_LABEL;
   }
 }

package/shared/worker-runtime/api-client.mjs

@@ -19,7 +19,7 @@ function httpError(status, routePath, text) {
   error.status = status;
   error.detail = detail;
   // The parsed error body, for callers that pass the relay's answer on as
-  // is (a refused remote_relay call carries its code there).
+  // is (a refused relay_tool call carries its code there).
   error.body = payload && typeof payload === "object" ? payload : null;
   return error;
 }
@@ -89,7 +89,7 @@ function requestWithoutTimeout({ url, method, headers, payload, signal }) {
 export function createApiClient({ serverUrl, token, getHeaders }) {
   /**
    * `options.longCall`: a call the relay may legitimately hold open for many
-   * minutes (the remote_relay tool) — it goes over node:http without any
+   * minutes (the relay_tool) — it goes over node:http without any
    * timeout instead of fetch. `options.signal` aborts either kind; an aborted
    * call rejects with an AbortError.
    */

package/shared/worker-runtime/heartbeat.mjs

@@ -33,6 +33,10 @@ export function createHeartbeatController({
   // Optional: called after every beat the relay answered, for work that
   // waits for a reachable relay (posts kept after a failure).
   onAnswered = () => {},
+  // Optional: the kind of worker this is ("claude", "claude-api", ...). The
+  // relay hands a Claude chat's row only to a worker of the row's billing,
+  // and knows a worker's kind from what it says here and in its hello.
+  workerKind = null,
   // requestPulse's window: one turn transition can flip the steering
   // snapshot several times in quick succession, and each flip only needs to
   // reach the relay once.
@@ -66,6 +70,7 @@ export function createHeartbeatController({
         ...(steering && typeof steering === "object" ? { steering } : {}),
         ...(settleFailed.length ? { settleFailed } : {}),
         ...(Array.isArray(backgroundTaskIds) ? { backgroundTasks: backgroundTaskDigest(backgroundTaskIds) } : {}),
+        ...(workerKind ? { workerKind: String(workerKind) } : {}),
       };
       const response = await api("POST", "/api/heartbeat", body);
       // Failed by the relay, or skipped because this worker has no claim on

package/shared/worker-runtime/worker-websocket-link.mjs

@@ -66,6 +66,10 @@ export function createWorkerWebSocketLink({
   onServerHello = () => {},
   getSessionId = () => null,
   getPid = () => null,
+  // The kind of worker this is ("claude", "claude-api", ...), stated in
+  // every hello and ready: the relay hands a Claude chat's row only to a
+  // worker of the row's billing.
+  workerKind = null,
   minBackoffMs = 1000,
   maxBackoffMs = 8_000,
   jitterMs = 250,
@@ -170,6 +174,7 @@ export function createWorkerWebSocketLink({
       reason,
       sessionId: normalizeText(getSessionId()),
       pid: normalizePositiveInt(getPid()),
+      ...(normalizeText(workerKind) ? { kind: normalizeText(workerKind) } : {}),
       ...(held ? { ready: false } : {}),
     });
     if (sent) lastHelloSentAt = getNowMs();
@@ -197,6 +202,7 @@ export function createWorkerWebSocketLink({
       reason,
       sessionId: normalizeText(getSessionId()),
       pid: normalizePositiveInt(getPid()),
+      ...(normalizeText(workerKind) ? { kind: normalizeText(workerKind) } : {}),
     });
     if (sent) lastReadySentAt = getNowMs();
     return sent;