@oar-sh/oar 0.9.2 → 0.9.4

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

@@ -0,0 +1,314 @@
+// The provider-facing side of the `remote_relay` 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
+// and the Copilot extension engine reach) registers the SAME name, description
+// and schema from the contract and forwards every call to the one local relay
+// endpoint. The relay does the gating, the approval, the forwarding and the
+// waiting; nothing here knows about remote relays beyond the wire shape.
+//
+// SDK-free and dependency-injected, following preview-tool-core.mjs: all relay
+// traffic goes through the worker's injected `api(method, path, body, options)`
+// helper (shared/worker-runtime/api-client.mjs).
+
+import {
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_ENDPOINT,
+  REMOTE_RELAY_TOOL_INPUT_SCHEMA,
+  REMOTE_RELAY_TOOL_NAME,
+  summarizeRemoteRelayCall,
+  validateRemoteRelayToolInput,
+} from './remote-relay-contract.mjs';
+
+export {
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_ENDPOINT,
+  REMOTE_RELAY_TOOL_INPUT_SCHEMA,
+  REMOTE_RELAY_TOOL_NAME,
+  summarizeRemoteRelayCall,
+};
+
+// The adapters' crisp early check; the relay validates again authoritatively.
+export const validateRemoteRelayTool = validateRemoteRelayToolInput;
+
+/**
+ * A private deep copy of the contract schema for SDKs that take ownership of
+ * the object they are handed (the contract's is frozen at the top level, and
+ * an SDK that annotates its input would throw on it).
+ */
+export function cloneRemoteRelayToolInputSchema() {
+  return JSON.parse(JSON.stringify(REMOTE_RELAY_TOOL_INPUT_SCHEMA));
+}
+
+// How many remotes this relay knows (`{ count }`): the registration decision.
+export const REMOTE_RELAY_SUMMARY_PATH = '/api/remote-relays/summary';
+// Calls of one conversation the relay is still working on (`{ inflight }`):
+// the Grok inactivity hold, which cannot see the tool call itself.
+export const REMOTE_RELAY_INFLIGHT_PATH = '/api/remote-relays/inflight';
+
+// The local relay could not be asked at all, or answered without a body the
+// model could read (a transport error, a crash page). Distinct from every
+// contract code, which describe a refusal the relay itself made.
+export const REMOTE_RELAY_CALL_FAILED = 'REMOTE_RELAY_CALL_FAILED';
+
+// The provider cancelled the call (the user's Stop, a host's cancel, a
+// runtime going away) before the relay answered. The relay sees the request
+// close and stops too: it withdraws an open approval card and stops waiting
+// on the remote. A prompt already handed over is NOT taken back.
+export const REMOTE_RELAY_CANCELLED = 'REMOTE_RELAY_CANCELLED';
+
+// How long the registration probe may take before the tool is left out.
+export const REMOTE_RELAY_DECISION_TIMEOUT_MS = 5_000;
+
+// A hard ceiling for one tool call on the providers that impose their own
+// (MCP clients). The relay already bounds the wait (wait_seconds ≤ 600) but not
+// the time an approval card may sit unanswered, so this only has to outlast a
+// human, never a remote turn.
+export const REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS = 8 * 60 * 60_000;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function withTimeout(promise, timeoutMs, label) {
+  if (!(Number(timeoutMs) > 0)) return promise;
+  let timer = null;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      timer.unref?.();
+    }),
+  ]).finally(() => { if (timer) clearTimeout(timer); });
+}
+
+function errorBodyOf(error) {
+  // `body` is the parsed JSON error body when the api client kept it; a
+  // client that parsed it into `detail` instead is tolerated too.
+  for (const candidate of [error?.body, error?.detail]) {
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Maps an api-client failure onto the result shape the model reads. The relay
+ * answers a refusal with `{ ok:false, code, error }` and a 4xx/5xx status; that
+ * body IS the answer (LOCKED, FORBIDDEN, OFFLINE, …), so it is passed through
+ * as-is. Anything without such a body becomes REMOTE_RELAY_CALL_FAILED.
+ */
+export function remoteRelayErrorResult(error) {
+  const status = Number(error?.status) || 0;
+  const body = errorBodyOf(error);
+  const detail = typeof error?.detail === 'string' ? toText(error.detail) : '';
+  if (body && (body.code || body.error)) {
+    return {
+      ...body,
+      ok: false,
+      code: toText(body.code) || REMOTE_RELAY_CALL_FAILED,
+      error: toText(body.error || body.message) || detail || `HTTP ${status}`,
+    };
+  }
+  if (status === 404) {
+    // A relay that predates the feature (or runs without its routes).
+    return {
+      ok: false,
+      code: REMOTE_RELAY_ERROR_CODES.unsupported,
+      error: 'This relay does not offer remote relays (the tool endpoint is missing). Tell the user.',
+    };
+  }
+  return {
+    ok: false,
+    code: REMOTE_RELAY_CALL_FAILED,
+    ...(status ? { status } : {}),
+    error: detail || toText(error?.message || error) || 'The relay could not be reached',
+  };
+}
+
+function isAbortError(error) {
+  return error?.name === 'AbortError' || error?.code === 'ABORT_ERR';
+}
+
+/** The answer for a call its provider cancelled before the relay answered. */
+export function remoteRelayCancelledResult() {
+  return {
+    ok: false,
+    code: REMOTE_RELAY_CANCELLED,
+    error: 'The call was cancelled before the relay answered. A message it had already handed over may still run on the remote.',
+  };
+}
+
+/**
+ * Executes one `remote_relay` 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.
+ *
+ * The call goes out as a long call (`{ longCall: true }`): no client-side
+ * timeout at all, because the relay bounds the wait itself (wait_seconds plus
+ * approval time) and fetch's 300 s header limit would cut both short.
+ * `signal` (the provider's cancellation) is the only way to end it early.
+ */
+export async function executeRemoteRelayTool(input, { api, conversationId = '', signal = null } = {}) {
+  if (typeof api !== 'function') {
+    return { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: 'Remote relay API unavailable in this worker' };
+  }
+  const conversation = toText(conversationId);
+  if (!conversation) {
+    return { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: 'No conversation is bound to this call' };
+  }
+  const parsed = validateRemoteRelayToolInput(input);
+  if (!parsed.ok) return parsed;
+  if (signal?.aborted) return remoteRelayCancelledResult();
+  try {
+    const response = await api('POST', REMOTE_RELAY_TOOL_ENDPOINT, {
+      conversationId: conversation,
+      action: parsed.action,
+      args: parsed.args,
+    }, { longCall: true, ...(signal ? { signal } : {}) });
+    if (response && typeof response === 'object' && !Array.isArray(response)) return response;
+    return { ok: true, result: response ?? null };
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) return remoteRelayCancelledResult();
+    return remoteRelayErrorResult(error);
+  }
+}
+
+/**
+ * Whether a worker should register the tool: at least one remote is paired.
+ * Fails closed — any error, a malformed answer or a slow relay leaves the tool
+ * out, and the next worker start asks again.
+ */
+export async function shouldRegisterRemoteRelayTool({ api, timeoutMs = REMOTE_RELAY_DECISION_TIMEOUT_MS } = {}) {
+  if (typeof api !== 'function') return false;
+  try {
+    const response = await withTimeout(
+      Promise.resolve().then(() => api('GET', REMOTE_RELAY_SUMMARY_PATH)),
+      timeoutMs,
+      'remote relay summary',
+    );
+    return Number(response?.count) > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The registration decision as a worker holds it: asked once when the worker
+ * starts (`refresh()`), read synchronously where a tool set is fixed
+ * (`isEnabled()`), and awaitable where the first build may wait for it
+ * (`ready()`, which never rejects). `fixed` pins the answer (tests, kill
+ * switches) without asking the relay.
+ */
+export function createRemoteRelayToolGate({
+  api,
+  fixed = undefined,
+  decide = shouldRegisterRemoteRelayTool,
+  timeoutMs = REMOTE_RELAY_DECISION_TIMEOUT_MS,
+} = {}) {
+  if (typeof fixed === 'boolean') {
+    return {
+      isEnabled: () => fixed,
+      isSettled: () => true,
+      refresh: () => Promise.resolve(fixed),
+      ready: () => Promise.resolve(fixed),
+    };
+  }
+  let enabled = false;
+  let settledOnce = false;
+  let pending = null;
+  function refresh() {
+    if (!pending) {
+      pending = Promise.resolve()
+        .then(() => decide({ api, timeoutMs }))
+        .then((value) => { enabled = value === true; }, () => { enabled = false; })
+        .then(() => {
+          settledOnce = true;
+          pending = null;
+          return enabled;
+        });
+    }
+    return pending;
+  }
+  return {
+    isEnabled: () => enabled,
+    // True once an answer is in and no refresh is running: a caller can then
+    // read isEnabled() without awaiting ready().
+    isSettled: () => settledOnce && !pending,
+    refresh,
+    ready: () => (settledOnce && !pending ? Promise.resolve(enabled) : (pending || refresh())),
+  };
+}
+
+/**
+ * How many remote_relay 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.
+ */
+export async function fetchRemoteRelayInflight({ api, conversationId = '', timeoutMs = 10_000 } = {}) {
+  const conversation = toText(conversationId);
+  if (typeof api !== 'function' || !conversation) return 0;
+  try {
+    const response = await withTimeout(
+      Promise.resolve().then(() => api(
+        'GET',
+        `${REMOTE_RELAY_INFLIGHT_PATH}?conversationId=${encodeURIComponent(conversation)}`,
+      )),
+      timeoutMs,
+      'remote relay inflight',
+    );
+    const count = Number(response?.inflight);
+    return Number.isFinite(count) && count > 0 ? count : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** The text every adapter hands the model: the relay's JSON, pretty-printed. */
+export function formatRemoteRelayToolResult(result) {
+  try {
+    const text = JSON.stringify(result ?? null, null, 2);
+    return text === undefined ? 'null' : text;
+  } catch {
+    return String(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');
+
+export function isRemoteRelayToolName(name) {
+  return REMOTE_RELAY_NAME_PATTERN.test(toText(name));
+}
+
+/**
+ * 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.
+ */
+export function remoteRelayCallInput(rawInput) {
+  let input = rawInput;
+  if (typeof input === 'string') {
+    try {
+      input = JSON.parse(input);
+    } catch {
+      return null;
+    }
+  }
+  return input && typeof input === 'object' && !Array.isArray(input) ? input : null;
+}
+
+/**
+ * The summary part of the activity line (`send → linux-test session 01234567:
+ * “…”`), or '' when the call carries no action yet (a streaming frame before
+ * its arguments arrived) so the caller keeps its generic line.
+ */
+export function remoteRelayActivitySummary(rawInput) {
+  const input = remoteRelayCallInput(rawInput);
+  if (!input || !toText(input.action)) return '';
+  return summarizeRemoteRelayCall(input);
+}

package/shared/slash-command-guard.mjs

@@ -0,0 +1,76 @@
+// Keeps a "/x" message the relay delivers to the Claude CLI plain text.
+//
+// The relay itself runs only /compact and /preview as commands, and neither
+// reaches a worker as text: the composer (and the /api/message route, for
+// /compact) intercept them. Any other "/x" the composer sends only after its
+// warn-once guard ("press send again to send as text"), and the API accepts
+// it as-is — so it must reach the model as the text the user typed. The Claude
+// CLI, however, runs a prompt as a slash command when the string, or its LAST
+// text block trimmed, starts with "/". Between turns that ran "/help what is
+// 3 + 4?" as the CLI's /help (a `local_command` with "isn't available in this
+// environment" as its output): the model never saw the question, and the
+// relay attributed the next turn's reply to that row (live, 2026-09-26).
+//
+// The guard is a zero-width space in front of the "/". JavaScript's trim()
+// does not strip U+200B, so neither the CLI's command check nor its queue's
+// "is this a command" check fires, and the message is handled exactly like
+// any other plain-text prompt (live probe, CLI 2.1.283: no local_command, the
+// model answered the question, the transcript keeps the character). The
+// relay stores and shows the user's own text; only the CLI sees the guard.
+//
+// A steered message needs none: the steer note (shared/steer-note.mjs) already
+// leads its text, so the guard only applies where the text itself starts
+// with "/".
+//
+// Not the SDK's per-message `client_composed: true`: that suppresses the
+// dispatch too (same probe), but older CLIs ignore the field, it also turns
+// off `@path` expansion and drops part of the turn-start context for that
+// message (the probe lost the token-budget reminder), and per the CLI bundle
+// its queue still classifies the text by the leading "/" (e.g. never merges
+// it with other queued prompts) — the guard makes it plain text everywhere.
+
+export const SLASH_COMMAND_GUARD = '\u200B';
+
+function readsAsSlashCommand(text) {
+  return typeof text === 'string' && text.trim().startsWith('/');
+}
+
+/** Prefix the guard when the CLI would read the text as a slash command. */
+export function withSlashCommandGuard(text) {
+  return readsAsSlashCommand(text) ? `${SLASH_COMMAND_GUARD}${text}` : text;
+}
+
+/**
+ * The guard applied to Claude user content: a string, or every text block of a
+ * content-block array (the CLI inspects the last block; guarding each keeps
+ * that true whatever the block order). Returns the input itself when nothing
+ * needed a guard; never mutates it.
+ */
+export function withSlashCommandGuardContent(content) {
+  if (typeof content === 'string') return withSlashCommandGuard(content);
+  if (!Array.isArray(content)) return content;
+  if (!content.some((block) => block?.type === 'text' && readsAsSlashCommand(block.text))) return content;
+  return content.map((block) => (block?.type === 'text' && readsAsSlashCommand(block.text)
+    ? { ...block, text: withSlashCommandGuard(block.text) }
+    : block));
+}
+
+/**
+ * The user's own text from a guarded prompt: the leading guard is dropped only
+ * where it stands in front of a "/", so other text is returned unchanged.
+ */
+export function stripSlashCommandGuard(text) {
+  const value = String(text ?? '');
+  return value.startsWith(SLASH_COMMAND_GUARD) && readsAsSlashCommand(value.slice(SLASH_COMMAND_GUARD.length))
+    ? value.slice(SLASH_COMMAND_GUARD.length)
+    : value;
+}
+
+/** stripSlashCommandGuard over a string or each text block of a content array. */
+export function stripSlashCommandGuardContent(content) {
+  if (typeof content === 'string') return stripSlashCommandGuard(content);
+  if (!Array.isArray(content)) return content;
+  return content.map((block) => (block?.type === 'text' && typeof block.text === 'string'
+    ? { ...block, text: stripSlashCommandGuard(block.text) }
+    : block));
+}

package/shared/steer-note.mjs

@@ -0,0 +1,66 @@
+// The hidden note a steered message carries to the model.
+//
+// A message the user sends while a turn is running is pushed into that turn
+// (steering). When it lands before the model has produced anything, the model
+// sees two user messages at once — and in the 2026-09-25 burn-in gpt-5.4-mini
+// answered only the newest and silently dropped the original request (the
+// runtime's own event log confirmed nothing was lost by the relay). The note
+// tells the model the new message is an addition, not a replacement, unless
+// the user says otherwise. Only the model sees it: the relay stores and shows
+// the user's own text.
+//
+// Shared by the Claude and Copilot SDK workers (maintainer decision, 2026-09-25: both).
+
+// Worded to stay true whether the runtime folds the message into the running
+// turn or runs it as a turn of its own after that one finished: "if not
+// finished yet" never asks the model to redo work it already completed. The
+// opening words are the stable handle the prompt sanitizers match on
+// (services/relay-prompt-sanitizer.mjs and its browser copy).
+export const STEERED_MESSAGE_NOTE = '[Sent while you were still working on my previous message. '
+  + 'If that request is not finished yet, finish it too; do not drop it unless this message says so.]';
+
+// The note LEADS the user's text, inside the same text block, and that
+// position is load-bearing beyond the replay's shape. The Claude CLI runs a
+// prompt as a slash command when the string, or its LAST text block trimmed,
+// starts with "/" — and one dequeued mid-turn is deferred to a turn of its
+// own, whose output the relay would misattribute. The relay itself runs only
+// /compact and /preview as commands (any other "/x" is confirmed as text
+// first), so a steered "/cmd …" must reach the model as plain text folded
+// into the running turn, which the leading note guarantees. Appended, the
+// prompt would still start with "/" and run as a command whose arguments
+// include the note; as a separate leading block, the last block would still
+// start with "/". A "/x" that is not steered (or is pushed into a continuation,
+// which gets no note) is kept text by the Claude worker's slash-command guard
+// instead (shared/slash-command-guard.mjs).
+
+/** Prefix a plain-text prompt with the steer note. */
+export function withSteerNote(text) {
+  const body = String(text ?? '');
+  return body.trim() ? `${STEERED_MESSAGE_NOTE}\n\n${body}` : STEERED_MESSAGE_NOTE;
+}
+
+/**
+ * Prefix a content-block array (Claude's user message content) with the note:
+ * into the first text block when there is one, so the block structure — and
+ * with it the replay the CLI echoes back — keeps its shape; otherwise as a new
+ * leading text block. Returns a new array; the input is not mutated.
+ */
+export function withSteerNoteContent(content) {
+  if (typeof content === 'string') return withSteerNote(content);
+  if (!Array.isArray(content)) return content;
+  const index = content.findIndex((block) => block?.type === 'text');
+  if (index < 0) return [{ type: 'text', text: STEERED_MESSAGE_NOTE }, ...content];
+  return content.map((block, i) => (i === index ? { ...block, text: withSteerNote(block.text) } : block));
+}
+
+/**
+ * The user's own text from a prompt that may carry the steer note — what a
+ * worker compares a replayed message against. Note-agnostic matching: the
+ * replay the CLI echoes back carries the note, the relay row does not.
+ */
+export function stripSteerNote(text) {
+  const value = String(text ?? '');
+  if (value === STEERED_MESSAGE_NOTE) return '';
+  const prefix = `${STEERED_MESSAGE_NOTE}\n\n`;
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}

package/shared/steer-settle-failure.mjs

@@ -0,0 +1,89 @@
+// The terminal failure for a message whose prompt the agent already consumed
+// but whose outcome could not be recorded. At-most-once: such a row is never
+// requeued (a re-delivery would run the prompt a second time), so it fails for
+// good with wording that tells the user where the answer went. Shared by the
+// session workers (their own settle paths) and the relay (recovery paths that
+// meet a row marked consumed).
+//
+// Provider-neutral: the wording names `agentLabel` ("the agent" unless the
+// caller knows better — the Claude worker passes 'Claude').
+
+export const STEER_SETTLE_FAILED_CODE = 'steer-settle-failed';
+export const STEER_SETTLE_FAILED_STABLE_CODE = `relay.${STEER_SETTLE_FAILED_CODE}`;
+export const DEFAULT_STEER_AGENT_LABEL = 'the agent';
+
+function normalizeAgentLabel(value) {
+  const text = String(value || '').trim();
+  return text || DEFAULT_STEER_AGENT_LABEL;
+}
+
+// "the agent" → "The agent" at the start of a sentence; a proper name is
+// left as it is.
+function sentenceCase(label) {
+  return label.charAt(0).toUpperCase() + label.slice(1);
+}
+
+const VARIANTS = Object.freeze({
+  // Folded into a turn whose reply answered it (or the path is unknown — the
+  // relay's recovery paths cannot tell which).
+  folded: (label) => ({
+    message: `This message was already sent to ${label} — check the reply above.`,
+    guidance: 'Resend it only if it went unanswered.',
+  }),
+  // Handed off mid-reply: its own partial reply stands, and the rest of the
+  // answer continued on the next message.
+  handoff: (label) => ({
+    message: `${sentenceCase(label)} started answering this message, then carried on with your next one — check both replies.`,
+    guidance: 'Resend it only if something went unanswered.',
+  }),
+  // Steered into a turn the user stopped.
+  stopped: (label) => ({
+    message: `This message was sent to ${label} just before you stopped the turn, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+  // Pulled back out of the runtime's queue by the user (un-steer) — the
+  // prompt never ran — but the relay could not be told in time.
+  cancelled: (label) => ({
+    message: `This message was cancelled before ${label} started on it, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+});
+
+/**
+ * The name a provider's runtime goes by in the settle wording, for callers
+ * that only know the conversation's provider type (the relay's recovery
+ * paths). Workers that know exactly which runtime took the prompt pass the
+ * label themselves.
+ */
+export function steerAgentLabelForProvider(providerType) {
+  switch (String(providerType || '').trim().toLowerCase()) {
+    case 'claude': return 'Claude';
+    case 'github':
+    case 'openai': return 'Copilot';
+    case 'cursor': return 'Cursor';
+    case 'grok': return 'Grok';
+    default: return DEFAULT_STEER_AGENT_LABEL;
+  }
+}
+
+function wordingFor(variant, agentLabel) {
+  const build = VARIANTS[variant] || VARIANTS.folded;
+  return build(normalizeAgentLabel(agentLabel));
+}
+
+export function steerSettleFailureText(variant = 'folded', agentLabel = DEFAULT_STEER_AGENT_LABEL) {
+  return wordingFor(variant, agentLabel).message;
+}
+
+export function buildSteerSettleFailure(message, { variant = 'folded', agentLabel = DEFAULT_STEER_AGENT_LABEL } = {}) {
+  const wording = wordingFor(variant, agentLabel);
+  return {
+    kind: STEER_SETTLE_FAILED_CODE,
+    code: STEER_SETTLE_FAILED_CODE,
+    stableCode: STEER_SETTLE_FAILED_STABLE_CODE,
+    message: wording.message,
+    guidance: wording.guidance,
+    failedAt: new Date().toISOString(),
+    queueMessageId: String(message?.id || '') || null,
+  };
+}

package/shared/steer-settle-markers.mjs

@@ -0,0 +1,18 @@
+// The settle stubs of steered messages the Claude CLI consumed without opening
+// a turn of their own. Each is stamped with its own message kind, which is
+// what the client renders from; the texts are shared so the relay's migration
+// can recognise stubs saved before the kind existed.
+
+/**
+ * A steer folded into the running turn and answered by that turn's reply.
+ * Stamped kind='folded' (before 0.9.3: kind='absorbed', which the client read
+ * as "the reply continues through the next message" and mis-merged the next
+ * ordinary message on reload).
+ */
+export const STEER_FOLDED_TEXT = '_(Handled together with the previous reply — this message was steered into that turn.)_';
+
+/**
+ * A steer pushed into a turn the user then stopped: never answered. Stamped
+ * kind='stopped' — the stable handle the client keys its Resend on.
+ */
+export const STEER_STOPPED_TEXT = '_(Stopped with the turn — not answered.)_';

package/shared/worker-crash-guard.mjs

@@ -11,6 +11,45 @@
  * The requeue is strictly bounded: a crash handler that hangs is worse than
  * no handler at all.
  */
+/**
+ * Post a bounded, fenced requeue for each owed row. Entries are plain ids or
+ * { id, attemptId, terminalError } objects: the attempt id fences the requeue
+ * (a row that has moved on to another attempt must not be yanked back by a
+ * dying predecessor), and a `terminalError` makes the requeue route fail the
+ * row outright — for a row whose prompt was already consumed, which must not
+ * be requeued and run a second time. Never waits longer than `timeoutMs`.
+ */
+export async function requeueOwedRows({ api, entries = [], timeoutMs = 2_000 } = {}) {
+  const seen = new Set();
+  const owed = (Array.isArray(entries) ? entries : [])
+    .map((entry) => (entry && typeof entry === 'object'
+      ? {
+        id: String(entry.id || '').trim(),
+        attemptId: String(entry.attemptId || '').trim() || null,
+        terminalError: entry.terminalError && typeof entry.terminalError === 'object' ? entry.terminalError : null,
+      }
+      : { id: String(entry || '').trim(), attemptId: null, terminalError: null }))
+    .filter((entry) => {
+      if (!entry.id || seen.has(entry.id)) return false;
+      seen.add(entry.id);
+      return true;
+    });
+  if (!owed.length || typeof api !== 'function') return;
+  let timer = null;
+  await Promise.race([
+    Promise.allSettled(owed.map((entry) => api('POST', '/api/requeue', {
+      messageId: entry.id,
+      ...(entry.attemptId ? { attemptId: entry.attemptId } : {}),
+      ...(entry.terminalError ? { terminalError: entry.terminalError } : {}),
+    }))),
+    new Promise((resolve) => {
+      timer = setTimeout(resolve, Math.max(0, Number(timeoutMs) || 0));
+      timer.unref?.();
+    }),
+  ]);
+  clearTimeout(timer);
+}
+
 export function installWorkerCrashGuard({
   api,
   workerName = 'session-worker',
@@ -28,31 +67,7 @@ export function installWorkerCrashGuard({
     logError(`${workerName} ${kind}:`, error?.stack || error?.message || error);
     (async () => {
       try {
-        // Entries are plain ids or { id, attemptId } objects. The attempt id,
-        // when known, fences the requeue: a row that has already moved on to
-        // another attempt must not be yanked back by a dying predecessor.
-        const seen = new Set();
-        const entries = (getActiveQueueMessageIds() || [])
-          .map((entry) => (entry && typeof entry === 'object'
-            ? { id: String(entry.id || '').trim(), attemptId: String(entry.attemptId || '').trim() || null }
-            : { id: String(entry || '').trim(), attemptId: null }))
-          .filter((entry) => {
-            if (!entry.id || seen.has(entry.id)) return false;
-            seen.add(entry.id);
-            return true;
-          });
-        if (entries.length && typeof api === 'function') {
-          await Promise.race([
-            Promise.allSettled(entries.map((entry) => api('POST', '/api/requeue', {
-              messageId: entry.id,
-              ...(entry.attemptId ? { attemptId: entry.attemptId } : {}),
-            }))),
-            new Promise((resolve) => {
-              const timer = setTimeout(resolve, Math.max(0, Number(requeueTimeoutMs) || 0));
-              timer.unref?.();
-            }),
-          ]);
-        }
+        await requeueOwedRows({ api, entries: getActiveQueueMessageIds() || [], timeoutMs: requeueTimeoutMs });
       } catch {}
       try { onBeforeExit(); } catch {}
       exit(1);