@oar-sh/oar 0.9.4 → 0.9.6

package/shared/claude-usage-limit.mjs

@@ -0,0 +1,257 @@
+// The Claude subscription's usage limit, as the CLI reports it.
+//
+// The CLI sends a `rate_limit_event` at the start of every turn of a
+// claude.ai subscription session. At the limit it refuses the request without
+// waiting or retrying (captured live, CLI 2.1.283 / SDK 0.3.283):
+//
+//   rate_limit_event   { status: 'rejected', rateLimitType: 'five_hour',
+//                        resetsAt: <unix seconds>, unifiedWindows: {...} }
+//   assistant          { model: '<synthetic>', error: 'rate_limit',
+//                        is_api_error_message: true, text: "You've hit your
+//                        session limit · resets 10pm (UTC)" }
+//   result             { is_error: true, subtype: 'success',
+//                        api_error_status: 429, terminal_reason: 'api_error' }
+//
+// Shared by the Claude worker (which sees the stream) and the relay (which
+// pauses the turn and resumes it at the reset).
+
+export const USAGE_LIMIT_CODE = 'usage-limit';
+export const USAGE_LIMIT_STABLE_CODE = `claude.${USAGE_LIMIT_CODE}`;
+export const USAGE_LIMIT_KIND = 'claude-usage-limit';
+
+// A wait up to this long resumes by itself. A longer one (a weekly window can
+// be days away) stays paused until the user resumes it.
+export const USAGE_LIMIT_AUTO_RESUME_MAX_MS = 6 * 60 * 60 * 1000;
+
+// The reset time is the server's; the first request after it must not race
+// the window's own bookkeeping.
+export const USAGE_LIMIT_RESUME_MARGIN_MS = 60 * 1000;
+
+// A rejected report that names no reset still ahead counts for this long
+// after it arrived. Right after a reset the CLI can refuse once more and name
+// the reset that has just passed.
+export const USAGE_LIMIT_REPORT_FRESH_MS = 10 * 60 * 1000;
+
+const STATUSES = new Set(['allowed', 'allowed_warning', 'rejected']);
+
+const WINDOW_LABELS = Object.freeze({
+  five_hour: '5-hour limit',
+  seven_day: 'weekly limit',
+  seven_day_opus: 'weekly Opus limit',
+  seven_day_sonnet: 'weekly Sonnet limit',
+  seven_day_overage_included: 'weekly limit',
+  overage: 'extra usage limit',
+});
+
+const LIMIT_TEXT = /\b(?:hit|reached)\s+your\s+(?:\w+\s+){0,3}limit\b|\busage limit\b/i;
+
+function toFraction(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.min(n, 1);
+}
+
+// Unix seconds (what the CLI sends), milliseconds or an ISO string.
+function toIso(value) {
+  if (value === null || value === undefined || value === '') return null;
+  let ms = NaN;
+  if (typeof value === 'number' || /^\d+(\.\d+)?$/.test(String(value).trim())) {
+    const n = Number(value);
+    ms = n < 1e11 ? n * 1000 : n;
+  } else {
+    ms = Date.parse(String(value));
+  }
+  return Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : null;
+}
+
+function normalizeWindows(raw) {
+  if (!raw || typeof raw !== 'object') return [];
+  return Object.entries(raw)
+    .map(([id, window]) => ({
+      id: String(id),
+      utilization: toFraction(window?.utilization),
+      resetsAt: toIso(window?.resetsAt ?? window?.resets_at),
+    }))
+    .filter((window) => window.utilization !== null || window.resetsAt);
+}
+
+export function usageLimitWindowLabel(rateLimitType) {
+  return WINDOW_LABELS[String(rateLimitType || '').trim()] || 'usage limit';
+}
+
+/**
+ * The `rate_limit_info` of a `rate_limit_event`, in the shape the relay keeps.
+ * Returns null for anything that is not one.
+ */
+export function normalizeRateLimitInfo(raw, { now = Date.now() } = {}) {
+  if (!raw || typeof raw !== 'object') return null;
+  const status = String(raw.status || '').trim();
+  if (!STATUSES.has(status)) return null;
+  const rateLimitType = String(raw.rateLimitType || '').trim() || null;
+  const windows = normalizeWindows(raw.unifiedWindows);
+  const own = windows.find((window) => window.id === rateLimitType) || null;
+  return {
+    status,
+    rateLimitType,
+    resetsAt: toIso(raw.resetsAt) || own?.resetsAt || null,
+    // A rejected event carries no utilization of its own: the window is full.
+    utilization: toFraction(raw.utilization) ?? own?.utilization ?? (status === 'rejected' ? 1 : null),
+    surpassedThreshold: toFraction(raw.surpassedThreshold),
+    overageStatus: STATUSES.has(String(raw.overageStatus || '')) ? String(raw.overageStatus) : null,
+    isUsingOverage: raw.isUsingOverage === true || raw.overageInUse === true,
+    windows,
+    observedAt: new Date(now).toISOString(),
+  };
+}
+
+export function isRateLimitEvent(sdkMessage) {
+  return String(sdkMessage?.type || '') === 'rate_limit_event';
+}
+
+/** What makes two reports the same to a reader: a repeat is not published. */
+export function rateLimitInfoKey(info) {
+  if (!info) return '';
+  const percent = info.utilization === null ? '' : Math.round(info.utilization * 100);
+  return [info.status, info.rateLimitType || '', info.resetsAt || '', percent, info.isUsingOverage ? 'overage' : ''].join('|');
+}
+
+/**
+ * Did the CLI refuse this turn because the usage limit is reached?
+ *
+ * The ONE place that decides it. Returns null, or what the relay needs to
+ * pause the turn: `{ rateLimitType, resetsAt, text }`. `resetsAt` is null
+ * when the report names no reset still ahead; the relay then tries again
+ * shortly.
+ *
+ * - `rateLimit`: the latest normalized `rate_limit_info` of the process.
+ * - `result`: the raw SDK `result` message the turn ended with, if any.
+ * - `assistantError`: the `error` field of the turn's last assistant message.
+ * - `errorText`: the text of an exception, when the stream threw instead.
+ *
+ * A refusal needs both halves: the turn ended in an error that names the
+ * limit, and the CLI reported a rejected window, with its reset still ahead
+ * or just now. Without a rejected report (the limit reached in the middle of
+ * a long turn, under the report the turn began with) the error has to name
+ * the limit twice over: by its kind and in its words. A plain API 429 (an
+ * API key's requests per minute) comes with no report at all and stays the
+ * failure it is; a rejected window the account's extra usage covers ends no
+ * turn.
+ */
+export function classifyUsageLimitRefusal({
+  rateLimit = null,
+  result = null,
+  assistantError = '',
+  errorText = '',
+  now = Date.now(),
+} = {}) {
+  if (!rateLimit) return null;
+  const resultText = String(result?.result || '').trim();
+  const thrownText = String(errorText || '').trim();
+  const endedInError = result ? result.is_error === true || String(result.subtype || '') !== 'success' : Boolean(thrownText);
+  if (!endedInError) return null;
+
+  const byKind = String(assistantError || '') === 'rate_limit' || Number(result?.api_error_status) === 429;
+  const inWords = LIMIT_TEXT.test(resultText) || LIMIT_TEXT.test(thrownText);
+  const rejected = rateLimit.status === 'rejected';
+  const resetsAtMs = Date.parse(rateLimit.resetsAt || '');
+  const resetAhead = Number.isFinite(resetsAtMs) && resetsAtMs > now;
+
+  if (rejected) {
+    if (!byKind && !inWords) return null;
+    if (!resetAhead) {
+      const observedAtMs = Date.parse(rateLimit.observedAt || '');
+      if (!Number.isFinite(observedAtMs) || now - observedAtMs > USAGE_LIMIT_REPORT_FRESH_MS) return null;
+    }
+  } else if (!byKind || !inWords) {
+    return null;
+  }
+
+  // A warning names the window that was about to run out; a report that
+  // allowed everything says nothing about which reset to wait for.
+  const namesTheReset = resetAhead && (rejected || rateLimit.status === 'allowed_warning');
+  return {
+    rateLimitType: rejected || namesTheReset ? rateLimit.rateLimitType : null,
+    resetsAt: namesTheReset ? rateLimit.resetsAt : null,
+    text: resultText || thrownText,
+  };
+}
+
+/** When a paused turn is sent again: the reset plus a margin. */
+export function usageLimitResumeAt(resetsAt, { marginMs = USAGE_LIMIT_RESUME_MARGIN_MS } = {}) {
+  const ms = Date.parse(resetsAt || '');
+  return Number.isFinite(ms) ? new Date(ms + marginMs).toISOString() : null;
+}
+
+/** Whether a pause ends by itself, or waits for the user (a reset days away). */
+export function usageLimitResumesByItself(resetsAt, { now = Date.now(), maxWaitMs = USAGE_LIMIT_AUTO_RESUME_MAX_MS } = {}) {
+  const ms = Date.parse(resetsAt || '');
+  return Number.isFinite(ms) && ms - now <= maxWaitMs;
+}
+
+/**
+ * What the worker reports for a refused turn, inside the response's
+ * `terminalError`. A relay that knows the kind pauses the row; an older one
+ * fails the turn with this message, as before.
+ */
+export function buildUsageLimitFailure(message, refusal) {
+  const label = usageLimitWindowLabel(refusal?.rateLimitType);
+  return {
+    kind: USAGE_LIMIT_KIND,
+    code: USAGE_LIMIT_CODE,
+    stableCode: USAGE_LIMIT_STABLE_CODE,
+    message: String(refusal?.text || '').trim() || `The Claude ${label} is reached.`,
+    guidance: 'The turn carries on by itself after the reset.',
+    rateLimitType: refusal?.rateLimitType || null,
+    resetsAt: refusal?.resetsAt || null,
+    failedAt: new Date().toISOString(),
+    queueMessageId: String(message?.id || '') || null,
+  };
+}
+
+/**
+ * Per-process bookkeeping for the worker: the latest report, what the turn's
+ * last assistant message said, and which reports are worth publishing.
+ */
+export function createUsageLimitTracker({ now = () => Date.now() } = {}) {
+  let latest = null;
+  let publishedKey = '';
+  let assistantError = '';
+
+  /** Returns the normalized report when it is news to the relay, else null. */
+  function observe(sdkMessage) {
+    const type = String(sdkMessage?.type || '');
+    if (type === 'rate_limit_event') {
+      const info = normalizeRateLimitInfo(sdkMessage.rate_limit_info, { now: now() });
+      if (!info) return null;
+      latest = info;
+      const key = rateLimitInfoKey(info);
+      if (key === publishedKey) return null;
+      publishedKey = key;
+      return info;
+    }
+    if (type === 'assistant' && !sdkMessage.parent_tool_use_id) {
+      assistantError = String(sdkMessage.error || '').trim();
+    }
+    return null;
+  }
+
+  function classifyResult(sdkResult) {
+    return classifyUsageLimitRefusal({ rateLimit: latest, result: sdkResult, assistantError, now: now() });
+  }
+
+  function classifyException(error) {
+    return classifyUsageLimitRefusal({
+      rateLimit: latest,
+      assistantError,
+      errorText: String(error?.message || error || ''),
+      now: now(),
+    });
+  }
+
+  return {
+    observe,
+    classifyResult,
+    classifyException,
+    get latest() { return latest; },
+  };
+}

package/shared/control-poller.mjs

@@ -23,7 +23,10 @@ export function createControlPoller({
   onAbortSubagent = null,
   dbg = () => {},
 } = {}) {
-  let active = null;
+  // The turns a Stop is polled for, oldest first, and whether the one loop
+  // that serves them all is running.
+  const registrations = new Set();
+  let polling = false;
 
   async function checkOnce({ queueMessageId, onAbortTurn }) {
     const ownerSessionId = String(sdkSessionId || '').trim();
@@ -81,37 +84,83 @@ export function createControlPoller({
     }
   }
 
-  function start({ queueMessageId, onAbortTurn }) {
-    stop();
-    const state = { stopped: false };
-    active = state;
-    (async () => {
-      while (!state.stopped) {
-        await sleep(pollMs);
-        if (state.stopped) return;
+  /**
+   * Hand a Stop to the turns that polled for it, newest first, until one of
+   * them takes it. The candidates were chosen before the request went out and
+   * are not re-checked here: the relay has claimed the control for this worker
+   * by now, so a turn that finished meanwhile still has to answer it.
+   */
+  async function offerAbort(candidates, control) {
+    let failure = null;
+    for (const registration of candidates) {
+      try {
+        await registration.onAbortTurn(control);
+        return;
+      } catch (error) {
+        failure = error;
+      }
+    }
+    throw failure || new Error('abort failed');
+  }
+
+  async function pollLoop() {
+    while (registrations.size) {
+      await sleep(pollMs);
+      // One request per row filter, however many turns share it, asked in the
+      // order of the newest turn that uses it.
+      const byFilter = new Map();
+      for (const registration of [...registrations].reverse()) {
+        const candidates = byFilter.get(registration.queueMessageId) || [];
+        candidates.push(registration);
+        byFilter.set(registration.queueMessageId, candidates);
+      }
+      for (const [queueMessageId, candidates] of byFilter) {
+        // Every turn behind this filter ended while an earlier one was asked.
+        if (candidates.every((registration) => registration.stopped)) continue;
         try {
-          const aborted = await checkOnce({ queueMessageId, onAbortTurn });
-          if (aborted) return;
+          await checkOnce({ queueMessageId, onAbortTurn: (control) => offerAbort(candidates, control) });
         } catch (error) {
           dbg('control poll failed', error?.message || String(error));
         }
       }
-    })();
-    return state;
+    }
+    polling = false;
+  }
+
+  /**
+   * Poll for a Stop on behalf of one turn, until `stop(handle)`. Turns overlap
+   * (a settled turn still waiting on a question card or publishing, beside the
+   * one that runs), so a new registration never displaces an older one, and a
+   * handled Stop does not end the polling: the Stop may have been for another
+   * turn's row, and the turns that remain still need theirs.
+   */
+  function start({ queueMessageId, onAbortTurn }) {
+    const registration = {
+      stopped: false,
+      queueMessageId: String(queueMessageId || ''),
+      onAbortTurn,
+    };
+    registrations.add(registration);
+    if (!polling) {
+      polling = true;
+      void pollLoop();
+    }
+    return registration;
   }
 
   function stop(handle) {
-    // Handle-scoped stop: a caller finishing an old turn must only stop that
-    // turn's poller. Without the scoping, a late finalize for a previous
-    // context would kill the poller of the turn currently running — leaving
-    // its Stop button dead. A bare stop() still stops whatever is active.
+    // Handle-scoped stop: a caller finishing a turn ends that turn's
+    // registration and no other. Without the scoping, a late finalize for a
+    // previous context would end the polling for the turn currently running,
+    // leaving its Stop button dead. A bare stop() ends every registration (the
+    // worker is shutting down).
     if (handle) {
       handle.stopped = true;
-      if (active === handle) active = null;
+      registrations.delete(handle);
       return;
     }
-    if (active) active.stopped = true;
-    active = null;
+    for (const registration of registrations) registration.stopped = true;
+    registrations.clear();
   }
 
   return { start, stop, checkOnce };

package/shared/failure-note-text.mjs

@@ -0,0 +1,38 @@
+// What makes a text a failure note of the relay.
+//
+// A failed turn is reported as a record. Where only text is there (a sender
+// that reports a failure as text, a reply read from another relay), the note
+// is known by its shape: one paragraph that leads up to "Error code:
+// relay.<code>" within a few sentences. A reply that quotes or describes such
+// a note, in a report on a failed test for example, is a reply.
+//
+// One rule for every reader: the relay's response route and the remote-relay
+// dispatcher must not disagree about what a failure is.
+
+export const FAILURE_NOTE_LEAD_MAX = 600;
+
+const CODE_PATTERN = /error code:\s*(relay\.[a-z0-9-]+)/i;
+// Somebody is talking about a note: the code stands in quotation marks, in a
+// code span or a table cell, or the paragraph is a list item, a heading or a
+// quotation.
+const QUOTED_LEAD = /["“”'`|>]\s*$/;
+const MARKUP_LEAD = /^\s*(?:#+|[>|*-]|\d+\.)\s/;
+
+/**
+ * `{ stableCode, index, lead }` when `text` is a failure note, else null.
+ * `index` is where "Error code" begins, `lead` the text before it.
+ */
+export function matchFailureNote(text) {
+  const raw = String(text ?? '').trim();
+  if (!raw) return null;
+  const match = CODE_PATTERN.exec(raw);
+  if (!match) return null;
+  const lead = raw.slice(0, match.index);
+  if (lead.length > FAILURE_NOTE_LEAD_MAX || /[\r\n]/.test(lead)) return null;
+  if (QUOTED_LEAD.test(lead) || MARKUP_LEAD.test(lead)) return null;
+  return { stableCode: match[1].toLowerCase(), index: match.index, lead };
+}
+
+export function isFailureNoteText(text) {
+  return matchFailureNote(text) !== null;
+}

package/shared/question-wait.mjs

@@ -0,0 +1,108 @@
+// Waiting for the answer to a question card, and creating the card, through
+// a relay that is briefly not there.
+//
+// A card may be open for hours and is polled every 1.5 s. One poll that failed
+// — the relay restarting, a reset connection, a 502 from a proxy in front of
+// it — used to end the wait with an error, and the callers turn an error into
+// an answer: "continue with your best judgement" for a question, a rejection
+// for an approval. The card itself stayed open, so the user later answered a
+// question nobody was waiting on any more. The relay keeps its cards across a
+// restart; the wait only has to outlast it.
+
+import { QUESTION_TIMEOUT_CONTINUATION_TEXT } from './question-timeout.mjs';
+import { isRelayUnreachableError, isTransientRelayError } from './worker-runtime/relay-errors.mjs';
+
+const DEFAULT_POLL_MS = 1500;
+/** The spacing between polls grows to this while the relay does not answer. */
+const MAX_OUTAGE_POLL_MS = 10_000;
+/** Attempts to create a card while the relay refuses connections (~16 s). */
+const DEFAULT_CREATE_RETRY_DELAYS_MS = Object.freeze([500, 1_000, 2_000, 4_000, 8_000]);
+
+function sleepDefault(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Create a question card. Retried only while the relay refuses the
+ * connection: any other failure may have created the card, and a second
+ * request would put a second one in front of the user.
+ */
+export async function createRelayQuestion({
+  api, payload, sleep = sleepDefault, retryDelaysMs = DEFAULT_CREATE_RETRY_DELAYS_MS, signal = null, dbg = () => {},
+} = {}) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      const created = await api('POST', '/api/relay-question', payload);
+      const questionId = created?.question?.id;
+      if (!questionId) throw new Error('Relay question could not be created');
+      return questionId;
+    } catch (error) {
+      if (!isRelayUnreachableError(error) || attempt >= retryDelaysMs.length || signal?.aborted) throw error;
+      dbg('relay unreachable while creating a question; trying again', error?.message || String(error));
+      await sleep(retryDelaysMs[attempt]);
+    }
+  }
+}
+
+/**
+ * Poll a card until it is answered, times out, is cancelled, or `signal`
+ * aborts the wait. Resolves `{ answer, structuredAnswer, timedOut, aborted? }`.
+ * Rejects only on the relay's own refusal (a 4xx, a card that does not exist).
+ */
+export async function waitForRelayQuestion({
+  api,
+  questionId,
+  deadlineMs,
+  pollMs = DEFAULT_POLL_MS,
+  sleep = sleepDefault,
+  signal = null,
+  trimAnswer = true,
+  now = Date.now,
+  dbg = () => {},
+} = {}) {
+  const started = now();
+  const expired = { answer: QUESTION_TIMEOUT_CONTINUATION_TEXT, structuredAnswer: null, timedOut: true };
+  let failedPolls = 0;
+  while (true) {
+    if (signal?.aborted) {
+      await api('POST', `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
+      return { ...expired, aborted: true };
+    }
+    let question = null;
+    let outage = null;
+    try {
+      ({ question } = await api('GET', `/api/relay-question/${questionId}`));
+      if (!question) throw Object.assign(new Error('Relay question missing'), { status: 404 });
+    } catch (error) {
+      if (!isTransientRelayError(error)) throw error;
+      outage = error;
+    }
+    if (outage) {
+      failedPolls += 1;
+      if (failedPolls === 1) dbg('relay did not answer the question poll; the card stays open', questionId, outage?.message || String(outage));
+    } else {
+      if (failedPolls) dbg('relay answers the question poll again', questionId, `after ${failedPolls} failed poll(s)`);
+      failedPolls = 0;
+      if (question.status === 'answered') {
+        const answer = String(question.answer || '');
+        return {
+          answer: trimAnswer ? answer.trim() : answer,
+          // The validated structured submission, when the card carried a
+          // `requestedSchema` and the relay stored one. Null otherwise — flat
+          // consumers read `answer` and never see a shape change.
+          structuredAnswer: question.structuredAnswer && typeof question.structuredAnswer === 'object'
+            && !Array.isArray(question.structuredAnswer)
+            ? question.structuredAnswer
+            : null,
+          timedOut: false,
+        };
+      }
+      if (question.status === 'timed_out' || question.status === 'cancelled') return { ...expired };
+    }
+    if (now() - started >= deadlineMs) {
+      await api('POST', `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
+      return { ...expired };
+    }
+    await sleep(failedPolls ? Math.min(MAX_OUTAGE_POLL_MS, pollMs * 2 ** Math.min(failedPolls, 6)) : pollMs);
+  }
+}

package/shared/remote-relay-contract.mjs

@@ -54,12 +54,19 @@ export const REMOTE_RELAY_ACTION_PERMISSION = Object.freeze({
 // the calling session runs in ask or plan mode.
 export const REMOTE_RELAY_WRITE_ACTIONS = Object.freeze(['send', 'create_session', 'answer_question', 'stop', 'archive']);
 
+// The write actions that carry an agent's words to another relay's agent.
+export const REMOTE_RELAY_PROMPT_ACTIONS = Object.freeze(['send', 'create_session', 'answer_question']);
+
 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']);
 export const REMOTE_RELAY_MODES = Object.freeze(['plan', 'ask', 'agent', 'autopilot']);
 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
+// value: the remote relay decides whether its model takes it.
+export const REMOTE_RELAY_EFFORT_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
 
 export const REMOTE_RELAY_RESULT_STATUSES = Object.freeze([
   'queued',
@@ -83,7 +90,12 @@ export const REMOTE_RELAY_LIMITS = Object.freeze({
   maxCharsMax: 50000,
   perMessageChars: 4000,
   textMax: 100000,
+  // Only toward a relay the user did not unlock and that is not the one the
+  // prompt came from: a third relay.
   hopLimit: 2,
+  // Prompts a conversation's agent may send to other relays' agents without a
+  // message from the user in between, before the user is asked.
+  agentPromptsBeforeAsking: 30,
   callsPerMinute: 60,
   writesPerMinute: 10,
   healthIntervalMs: 60_000,
@@ -135,8 +147,10 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   'Work with sessions on other OAR relays this relay is paired with ("remote relays"): '
   + 'list the relays, list or read their sessions, prompt a session, start a new one, '
   + 'wait for its reply, and answer or stop it. Use it only when the user asks for work '
-  + 'on another relay or mentions one. Start with {action:"list_relays"}. A relay stays '
-  + 'locked until the user mentions it in this conversation (for example @name); a '
+  + 'on another relay or mentions one, or to answer an agent on another relay that wrote '
+  + 'to this conversation. Start with {action:"list_relays"}. A relay stays locked until '
+  + 'the user mentions it in this conversation (for example @name) or an agent on that '
+  + 'relay writes to it; from then on it stays open for the whole conversation. A '
   + 'locked relay refuses everything except list_relays, so ask the user to mention it. '
   + 'send and create_session queue the prompt and wait up to wait_seconds (default 120, '
   + 'max 600) for the reply. If the remote turn is still running you get status '
@@ -203,6 +217,12 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
       enum: [...REMOTE_RELAY_MODES],
       description: 'send / create_session: relay mode for the remote turn (default: this session\'s mode).',
     },
+    effort: {
+      type: 'string',
+      description: 'send / create_session: reasoning effort for the remote turn, e.g. low, medium, high (relay_info lists '
+        + 'what each model takes). create_session default: this session\'s effort when the remote model supports it, '
+        + 'else the remote\'s default. send default: the remote session keeps its own.',
+    },
     title: { type: 'string', description: 'create_session: session title (default: from the prompt).' },
     question_id: { type: 'string', description: 'answer_question: id from pendingQuestions.' },
     answer: { type: 'string', description: 'answer_question: free-text answer.' },
@@ -312,6 +332,13 @@ export function validateRemoteRelayToolInput(input = {}) {
     optionalText('model', 200);
     const modeCheck = optionalEnum('mode', REMOTE_RELAY_MODES);
     if (!modeCheck.ok) return modeCheck;
+    const effort = toText(input?.effort).toLowerCase();
+    if (effort) {
+      if (!REMOTE_RELAY_EFFORT_PATTERN.test(effort)) {
+        return invalid('effort must be a short word such as low, medium or high (letters, digits and dashes, at most 32 characters)');
+      }
+      args.effort = effort;
+    }
     if (action === 'send') {
       const busyCheck = optionalEnum('if_busy', REMOTE_RELAY_IF_BUSY);
       if (!busyCheck.ok) return busyCheck;
@@ -356,6 +383,10 @@ export function isRemoteRelayWriteAction(action) {
   return REMOTE_RELAY_WRITE_ACTIONS.includes(action);
 }
 
+export function isRemoteRelayPromptAction(action) {
+  return REMOTE_RELAY_PROMPT_ACTIONS.includes(action);
+}
+
 // ─── Approval cards ──────────────────────────────────────────────────────────
 
 // The Allow / Deny card a relay puts on its own turn before a write action on

package/shared/steer-settle-failure.mjs

@@ -41,6 +41,28 @@ const VARIANTS = Object.freeze({
     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.',
   }),
+  // Steered into a turn that then failed.
+  turnFailed: (label) => ({
+    message: `This message was sent to ${label} in a turn that then failed, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+  // Not a steer: the message was answered, and the answer reached the relay
+  // neither as a reply nor as a requeue.
+  replyLost: (label) => ({
+    message: `${sentenceCase(label)} answered this message, but the answer could not be saved to the relay.`,
+    guidance: 'Ask for the answer again: the session still has it, and nothing is run a second time.',
+  }),
+  // Not a steer: the turn failed, and its failure note could not be saved.
+  failureLost: (label) => ({
+    message: `The turn ${label} ran for this message failed, and what went wrong could not be saved to the relay.`,
+    guidance: 'Send the message again to retry.',
+  }),
+  // Not a steer: delivered between turns and answered on a background
+  // continuation row (ANSWERED_ELSEWHERE_KIND in steer-settle-markers.mjs).
+  answeredElsewhere: (label) => ({
+    message: `${sentenceCase(label)} answered this message in a reply marked “background continuation” — check the replies next to it.`,
+    guidance: 'Resend it only if it went unanswered.',
+  }),
   // 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) => ({

package/shared/steer-settle-markers.mjs

@@ -16,3 +16,27 @@ export const STEER_FOLDED_TEXT = '_(Handled together with the previous reply —
  * kind='stopped' — the stable handle the client keys its Resend on.
  */
 export const STEER_STOPPED_TEXT = '_(Stopped with the turn — not answered.)_';
+
+/**
+ * A steer folded into a turn that then failed: never answered, and the
+ * failure itself is told once, on the reply of the turn. Stamped
+ * kind='stopped' like the steer of a stopped turn, so the client offers the
+ * same Resend.
+ */
+export const STEER_TURN_FAILED_TEXT = '_(Steered into the turn above, which failed — not answered.)_';
+
+/**
+ * Not a steer: a message delivered between turns whose answer the worker
+ * published on a background-continuation row, because it took the turn for one
+ * the CLI had opened by itself. Stamped with a kind of its own: it is a
+ * marker, not a reply (no completion push, muted in the transcript, never
+ * handed to a calling relay as the answer), and not a steer marker either,
+ * which would label the message "steered mid-turn".
+ *
+ * The wording names the reply by its badge, not by its position: a live
+ * append puts the marker below that reply, a reload anchors it under its own
+ * message and so above it. The worker infers all this from silence, hence the
+ * way out at the end.
+ */
+export const ANSWERED_ELSEWHERE_KIND = 'answered-elsewhere';
+export const DELIVERY_ANSWERED_ELSEWHERE_TEXT = '_(Answered in the reply marked “background continuation” next to this message. Resend the message if that reply does not answer it.)_';