@stage-labs/metro 0.1.0-beta.260 → 0.1.0-beta.262

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.260",
+  "version": "0.1.0-beta.262",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.260",
+  "version": "0.1.0-beta.262",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

package/runtime/node_modules/@metro-labs/core/src/runner-activity.ts

@@ -7,6 +7,36 @@ export type RunnerPhase = (typeof PHASES)[number];
 export type RunnerTaskState = (typeof TASK_STATES)[number];
 export type RunnerEventKind = (typeof EVENTS)[number];
 
+const FAILURE = {
+  authentication: 'The provider refused authentication. Check the Model page.',
+  billing: 'The provider refused billing. Check the Model page.',
+  rate_limit: 'The provider rate limit was reached. Retry later or check the Model page.',
+  provider_unavailable: 'The provider is unavailable. Retry later or check the Model page.',
+  invalid_request: 'The provider rejected the request. Check Conversations and the Model page.',
+  output_limit: 'The model reached its output token limit. Check Conversations.',
+  provider_error: 'SDK turn failed (provider_error). Check Conversations and the Model page.',
+  error_during_execution: 'SDK turn failed (error_during_execution). Check Conversations and the Model page.',
+  error_max_turns: 'SDK turn failed (error_max_turns). Check Conversations and the Model page.',
+  error_max_budget_usd: 'SDK turn failed (error_max_budget_usd). Check Conversations and the Model page.',
+  error_max_structured_output_retries: 'SDK turn failed (error_max_structured_output_retries). Check Conversations and the Model page.',
+  read_token_limit: 'Read exceeded its token limit. Read a smaller range with offset and limit, or search the file.',
+  tool_error: 'A tool failed. See its result in Conversations.',
+  task_error: 'A background task failed. See Conversations and Terminal.',
+  compact_error: 'Conversation compaction failed.',
+  status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
+  saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
+  executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  connection: 'The SDK connection failed. Check the server and provider connection.',
+  session_ended: 'The Agent SDK session ended unexpectedly.',
+  interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
+  session_error: 'The Agent SDK session failed. Check Terminal and the Model page.',
+} as const;
+export type RunnerFailureCode = keyof typeof FAILURE;
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null): string {
+  return code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+}
+
 export interface RunnerTask {
   id: string;
   kind: string | null;
@@ -30,10 +60,18 @@ export interface RunnerTool {
 }
 
 export interface RunnerEvent {
+  id?: string;
   at: number;
   kind: RunnerEventKind;
   tool: string | null;
+  toolUseId?: string;
   taskId: string | null;
+  code?: RunnerFailureCode;
+}
+
+export interface RunnerFailure extends RunnerEvent {
+  id: string;
+  code: RunnerFailureCode;
 }
 
 export interface RunnerActivity {
@@ -53,6 +91,8 @@ export interface RunnerActivity {
   tasks: RunnerTask[];
   events: RunnerEvent[];
   lastError: string | null;
+  activeFailure?: RunnerFailure | null;
+  lastFailure?: RunnerFailure | null;
 }
 
 const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -76,9 +116,30 @@ function tool(raw: unknown): RunnerTool | null {
   return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
 }
 
+const failureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
+
 function event(raw: unknown): RunnerEvent | null {
   if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
-  return { at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId) };
+  return {
+    at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
+    ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
+    ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
+    ...(failureKind(raw.kind) && failureCode(raw.code) ? { code: raw.code } : {}),
+  };
+}
+
+function failure(raw: unknown): RunnerFailure | null {
+  const parsed = event(raw);
+  return parsed?.id !== undefined && parsed.code !== undefined ? { ...parsed, id: parsed.id, code: parsed.code } : null;
+}
+
+function safeError(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const known = Object.values(FAILURE).find((text) => text === raw);
+  if (known !== undefined) return known;
+  const tool = /^([A-Za-z0-9_.:-]{1,128}) failed\. See its result in Conversations\.$/.exec(raw)?.[1];
+  return tool === undefined ? FAILURE.session_error : runnerFailureSummary('tool_error', tool);
 }
 
 function list<T>(raw: unknown, parse: (item: unknown) => T | null, max: number): T[] {
@@ -90,6 +151,15 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
   return typeof value === 'string' && /^\d{1,32}$/.test(value) ? { procStart: value } : {};
 }
 
+function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
+  const activeFailure = failure(raw.activeFailure);
+  return {
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool) : safeError(raw.lastError),
+    ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
+    ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
+  };
+}
+
 export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
   if (!isRecord(raw) || raw.runner !== 'sdk' || !phase(raw.phase) || count(raw.pid) === 0 || count(raw.updatedAt) === 0) return null;
   return {
@@ -98,6 +168,6 @@ export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
     pending: count(raw.pending), workers: count(raw.workers), approvals: count(raw.approvals),
     tools: list(raw.tools, name, 20), activeTools: list(raw.activeTools, tool, 20),
     tasks: list(raw.tasks, task, 30), events: list(raw.events, event, 40),
-    lastError: typeof raw.lastError === 'string' ? raw.lastError.slice(0, 300) : null,
+    ...failureFields(raw),
   };
 }

package/runtime/node_modules/@metro-labs/daemon/src/claude/session-continuity.ts

@@ -18,12 +18,21 @@ function sdkSavedSession(home: string): Record<string, unknown> | null {
   }
 }
 
+const inputState = (value: unknown): boolean => value === undefined || value === 'queued' || value === 'started';
+
+function sdkInput(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return typeof value.text === 'string' && typeof value.at === 'number' && Number.isFinite(value.at) && (value.uuid === undefined || sessionId(value.uuid) !== null) && inputState(value.state);
+}
+
+const sdkInputs = (value: unknown): value is unknown[] | undefined => value === undefined || (Array.isArray(value) && value.every(sdkInput));
+
 export function sdkPending(home: string): number | null {
   const state = sdkSavedSession(home);
   if (state === null) return null;
   if (state.sessionId !== undefined && state.sessionId !== null && sessionId(state.sessionId) === null) return null;
-  if (state.unanswered === undefined) return 0;
-  return Array.isArray(state.unanswered) ? state.unanswered.length : null;
+  if (!sdkInputs(state.unanswered) || !sdkInputs(state.interrupted)) return null;
+  return state.unanswered?.length ?? 0;
 }
 
 function projectFolder(home: string, dir: string): string {

package/runtime/node_modules/@metro-labs/daemon/src/gateway/model-api.ts

@@ -25,6 +25,7 @@ import { asApiError, BODY_MAX, claudeLoginDeps, connectionFor, settingsBody, typ
 import { dropUnusedClaudeLogins } from './claude-logins.js';
 import { CODEX_ROUTES, codexDeviceRoute, GEMINI_ROUTES } from './model-signin.js';
 import { refreshUsage } from './usage-refresh.js';
+import { handleOpenRouterSignIn } from './openrouter-signin.js';
 
 const PATH = '/api/model';
 const CONNECTIONS = '/api/model/connections';
@@ -230,11 +231,6 @@ export function handleModelRequest(req: IncomingMessage, res: ServerResponse, de
     res.writeHead(204, cors(req)).end();
     return true;
   }
-  const route = routeFor(path, req.method);
-  if (typeof route === 'number') {
-    sendJson(req, res, route, { error: route === 404 ? 'not found' : 'method not allowed' });
-    return true;
-  }
   const store: Store = {
     read: deps.read ?? readModelConfig,
     write: (cfg) => {
@@ -242,6 +238,12 @@ export function handleModelRequest(req: IncomingMessage, res: ServerResponse, de
       (deps.write ?? writeModelConfig)(cfg);
     },
   };
+  if (handleOpenRouterSignIn(req, res, deps, store)) return true;
+  const route = routeFor(path, req.method);
+  if (typeof route === 'number') {
+    sendJson(req, res, route, { error: route === 404 ? 'not found' : 'method not allowed' });
+    return true;
+  }
   apiSession(req)
     .then(async (session) => {
       if (!session) throw new ApiError('unauthorized', 401);

package/runtime/node_modules/@metro-labs/daemon/src/gateway/model-store.ts

@@ -21,6 +21,9 @@ export interface ModelApiDeps {
   geminiUserBase?: string;
   geminiBase?: string;
   openrouterBase?: string;
+  owner?: () => string | null;
+  openrouterPublicBase?: () => string | null;
+  openrouterNow?: () => number;
   anthropicBase?: string;
   bedrockControlBase?: string;
   setup?: SetupDeps;

package/runtime/node_modules/@metro-labs/daemon/src/gateway/openrouter-login.ts

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+import { pkcePair, newState } from '@metro-labs/core/stations/oauth';
+import { ticketStore } from '@metro-labs/core/tickets';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import { ApiError } from '@metro-labs/http/api-error';
+import { addConnection, connectionOf, updateConnection } from './model-config.js';
+import { asApiError, type Store } from './model-store.js';
+import { forgetReported } from './usage.js';
+
+export const OPENROUTER_CALLBACK = '/api/model/openrouter/callback';
+const TTL = 10 * 60_000;
+const MAX_ATTEMPTS = 100;
+const STALE = 'This OpenRouter sign-in expired or was cancelled. Start again.';
+const FAILED = 'OpenRouter sign-in did not finish. Try again or use an API key. Manage any unused key in OpenRouter.';
+
+type Result = { status: 'pending' } | { status: 'done'; connection: string } | { status: 'failed'; error: string };
+
+interface Attempt {
+  owner: string;
+  connection: string;
+  keyHash: string;
+  expiresAt: number;
+  state: string;
+  verifier: string;
+  result: Result;
+  abort: AbortController;
+}
+
+interface LoginDeps {
+  store: Store;
+  owner: () => string | null;
+  publicBase: () => string | null;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+}
+
+const hash = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+function callbackUrl(base: string | null): string {
+  let url: URL;
+  try {
+    url = new URL(base ?? '');
+  } catch {
+    throw new ApiError('This box needs a public HTTPS address for OpenRouter sign-in. Use an API key instead.', 409);
+  }
+  if (url.protocol !== 'https:' || url.username !== '' || url.password !== '' || url.pathname !== '/' || url.search !== '' || url.hash !== '')
+    throw new ApiError('This box needs a public HTTPS origin for OpenRouter sign-in. Use an API key instead.', 409);
+  return `${url.origin}${OPENROUTER_CALLBACK}`;
+}
+
+async function exchange(code: string, verifier: string, signal: AbortSignal, fetchImpl: typeof fetch): Promise<string> {
+  const res = await fetchImpl('https://openrouter.ai/api/v1/auth/keys', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ code, code_verifier: verifier, code_challenge_method: 'S256' }),
+    redirect: 'manual',
+    signal: AbortSignal.any([signal, AbortSignal.timeout(15_000)]),
+  });
+  if (!res.ok) {
+    await res.body?.cancel();
+    throw new ApiError(FAILED, 502);
+  }
+  const body: unknown = await res.json();
+  if (!isRecord(body) || typeof body.key !== 'string' || body.key.trim() === '' || body.key.length > 512)
+    throw new ApiError(FAILED, 502);
+  return body.key.trim();
+}
+
+function authorizationCode(params: URLSearchParams): string {
+  const code = params.get('code') ?? '';
+  if (params.has('error') || code === '' || code.length > 4096 || params.getAll('code').length !== 1 || params.getAll('state').length !== 1)
+    throw new ApiError('OpenRouter did not approve this sign-in. Try again or use an API key.', 400);
+  return code;
+}
+
+export class OpenRouterLogins {
+  private readonly states = ticketStore<Attempt>(TTL, MAX_ATTEMPTS);
+  private readonly attempts = new Map<string, Attempt>();
+
+  constructor(private readonly deps: LoginDeps) {}
+
+  private now(): number {
+    return (this.deps.now ?? Date.now)();
+  }
+
+  private discard(attempt: Attempt): void {
+    this.states.take(attempt.state, this.now());
+    attempt.verifier = '';
+    attempt.abort.abort();
+  }
+
+  private prune(): void {
+    for (const [id, attempt] of this.attempts) {
+      if (attempt.expiresAt > this.now()) continue;
+      this.discard(attempt);
+      this.attempts.delete(id);
+    }
+  }
+
+  private checkOwner(owner: string): void {
+    if (this.deps.owner() !== owner) throw new ApiError('This sign-in belongs to another organization.', 403);
+  }
+
+  private target(connection: string): string {
+    const cfg = this.deps.store.read();
+    if (connection === '') {
+      try {
+        addConnection(cfg, { provider: 'openrouter' });
+      } catch (err) {
+        asApiError(err);
+      }
+      return '';
+    }
+    const found = connectionOf(cfg, connection);
+    if (found?.provider !== 'openrouter') throw new ApiError('This OpenRouter connection no longer exists.', 404);
+    return hash(found.apiKey);
+  }
+
+  begin(owner: string, connection: string): { id: string; url: string; expiresAt: number } {
+    this.checkOwner(owner);
+    const callback = callbackUrl(this.deps.publicBase());
+    const keyHash = this.target(connection);
+    this.prune();
+    if (this.attempts.size >= MAX_ATTEMPTS) throw new ApiError('Too many OpenRouter sign-ins. Try again later.', 429);
+    const { verifier, challenge } = pkcePair();
+    const attempt: Attempt = { owner, connection, keyHash, verifier, state: '', expiresAt: this.now() + TTL, result: { status: 'pending' }, abort: new AbortController() };
+    attempt.state = this.states.mint(attempt, this.now()).ticket;
+    const id = newState();
+    this.attempts.set(id, attempt);
+    const url = new URL('https://openrouter.ai/auth');
+    url.search = new URLSearchParams({ callback_url: callback, code_challenge: challenge, code_challenge_method: 'S256', state: attempt.state, key_label: 'Metro' }).toString();
+    return { id, url: url.href, expiresAt: attempt.expiresAt };
+  }
+
+  private find(owner: string, id: string): Attempt {
+    this.checkOwner(owner);
+    this.prune();
+    const attempt = this.attempts.get(id);
+    if (attempt?.owner !== owner) throw new ApiError(STALE, 410);
+    return attempt;
+  }
+
+  status(owner: string, id: string): Result {
+    return this.find(owner, id).result;
+  }
+
+  cancel(owner: string, id: string): Result {
+    const attempt = this.find(owner, id);
+    if (attempt.result.status === 'pending') {
+      attempt.result = { status: 'failed', error: 'OpenRouter sign-in cancelled.' };
+      this.discard(attempt);
+    }
+    return attempt.result;
+  }
+
+  private checkPending(attempt: Attempt): void {
+    if (attempt.expiresAt <= this.now() || attempt.result.status !== 'pending') throw new ApiError(STALE, 410);
+    this.checkOwner(attempt.owner);
+    if (this.target(attempt.connection) !== attempt.keyHash)
+      throw new ApiError('This connection changed during sign-in. Start again.', 409);
+  }
+
+  private save(attempt: Attempt, key: string): void {
+    this.checkPending(attempt);
+    const current = this.deps.store.read();
+    const next = attempt.connection === '' ? addConnection(current, { provider: 'openrouter', apiKey: key }) : updateConnection(current, attempt.connection, { apiKey: key });
+    const id = attempt.connection === '' ? (next.connections.at(-1)?.id ?? '') : attempt.connection;
+    this.deps.store.write(next);
+    forgetReported(id);
+    attempt.result = { status: 'done', connection: id };
+    log.info({ connection: id }, 'model-api: OpenRouter connected');
+  }
+
+  async complete(params: URLSearchParams): Promise<void> {
+    const state = params.get('state') ?? '';
+    const attempt = this.states.take(state, this.now());
+    if (attempt === undefined) throw new ApiError(STALE, 410);
+    const verifier = attempt.verifier;
+    attempt.verifier = '';
+    try {
+      this.checkPending(attempt);
+      const key = await exchange(authorizationCode(params), verifier, attempt.abort.signal, this.deps.fetchImpl ?? fetch);
+      this.save(attempt, key);
+    } catch (err) {
+      if (attempt.result.status === 'pending') attempt.result = { status: 'failed', error: err instanceof ApiError ? err.message : FAILED };
+      throw new ApiError(attempt.result.status === 'failed' ? attempt.result.error : FAILED, 400);
+    } finally {
+      this.discard(attempt);
+    }
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/gateway/openrouter-signin.ts

@@ -0,0 +1,64 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { sendJson, sessionRoute } from '@metro-labs/http/api-http';
+import { log } from '@metro-labs/core/log';
+import { publicBaseUrl } from '../files/attach-serve.js';
+import { askedConnection, type ModelApiDeps, type Store } from './model-store.js';
+import { OPENROUTER_CALLBACK, OpenRouterLogins } from './openrouter-login.js';
+
+const LOGIN = '/api/model/openrouter/login';
+const ID_RE = /^[A-Za-z0-9_-]{32}$/;
+const logins = new WeakMap<ModelApiDeps, OpenRouterLogins>();
+const CALLBACK_HEADERS = {
+  'cache-control': 'no-store',
+  'referrer-policy': 'no-referrer',
+  'content-security-policy': "default-src 'none'; frame-ancestors 'none'; base-uri 'none'",
+  'x-content-type-options': 'nosniff',
+};
+
+function loginFor(deps: ModelApiDeps, store: Store): OpenRouterLogins {
+  let login = logins.get(deps);
+  if (login === undefined) {
+    login = new OpenRouterLogins({
+      store,
+      owner: () => deps.owner?.() ?? null,
+      publicBase: deps.openrouterPublicBase ?? publicBaseUrl,
+      fetchImpl: deps.fetchImpl,
+      now: deps.openrouterNow,
+    });
+    logins.set(deps, login);
+  }
+  return login;
+}
+
+function callback(req: IncomingMessage, res: ServerResponse, login: OpenRouterLogins): void {
+  if (req.method !== 'GET') {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return;
+  }
+  const url = new URL(req.url ?? '', 'https://metro');
+  if (url.search === '') {
+    res.writeHead(200, { ...CALLBACK_HEADERS, 'content-type': 'text/html; charset=utf-8' });
+    res.end('<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>OpenRouter sign-in</title><h1>Return to Metro</h1><p>Check your connection in Metro. You can close this tab.</p><p>If you declined access, cancel the sign-in in Metro or use an API key.</p></html>');
+    return;
+  }
+  const finish = (): void => { res.writeHead(303, { ...CALLBACK_HEADERS, location: OPENROUTER_CALLBACK }).end(); };
+  login.complete(url.searchParams).then(finish, finish).catch(() => {
+    log.warn('openrouter-signin: callback response closed');
+    if (!res.writableEnded) res.end();
+  });
+}
+
+export function handleOpenRouterSignIn(req: IncomingMessage, res: ServerResponse, deps: ModelApiDeps, store: Store): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path === OPENROUTER_CALLBACK) {
+    callback(req, res, loginFor(deps, store));
+    return true;
+  }
+  const id = path.startsWith(`${LOGIN}/`) ? path.slice(LOGIN.length + 1) : '';
+  if (path !== LOGIN && !ID_RE.test(id)) return false;
+  return sessionRoute(req, res, { methods: { [path]: path === LOGIN ? ['POST'] : ['GET', 'DELETE'] }, admin: false, label: 'openrouter-signin' }, (session) => {
+    const login = loginFor(deps, store);
+    if (path === LOGIN) return Promise.resolve(login.begin(session.subject, askedConnection(req)));
+    return Promise.resolve(req.method === 'DELETE' ? login.cancel(session.subject, id) : login.status(session.subject, id));
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/routes/local-mode.ts

@@ -202,7 +202,7 @@ export function localSessionApis(deps: LocalModeDeps): SessionApis {
     controlApi: { restart: deps.restart, stop: deps.stop },
     ownerApi: { setOwner: (owner) => setLocalOwner(owner) },
     machineApi: {},
-    modelApi: { switchModel: deps.switchModel },
+    modelApi: { switchModel: deps.switchModel, owner: localOwner },
     gateway: { config: readModelConfig },
     terminalApi: {},
     mode: localModeInfo,

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.260"
+  "version": "0.1.0-beta.262"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/runner-activity.ts

@@ -7,6 +7,36 @@ export type RunnerPhase = (typeof PHASES)[number];
 export type RunnerTaskState = (typeof TASK_STATES)[number];
 export type RunnerEventKind = (typeof EVENTS)[number];
 
+const FAILURE = {
+  authentication: 'The provider refused authentication. Check the Model page.',
+  billing: 'The provider refused billing. Check the Model page.',
+  rate_limit: 'The provider rate limit was reached. Retry later or check the Model page.',
+  provider_unavailable: 'The provider is unavailable. Retry later or check the Model page.',
+  invalid_request: 'The provider rejected the request. Check Conversations and the Model page.',
+  output_limit: 'The model reached its output token limit. Check Conversations.',
+  provider_error: 'SDK turn failed (provider_error). Check Conversations and the Model page.',
+  error_during_execution: 'SDK turn failed (error_during_execution). Check Conversations and the Model page.',
+  error_max_turns: 'SDK turn failed (error_max_turns). Check Conversations and the Model page.',
+  error_max_budget_usd: 'SDK turn failed (error_max_budget_usd). Check Conversations and the Model page.',
+  error_max_structured_output_retries: 'SDK turn failed (error_max_structured_output_retries). Check Conversations and the Model page.',
+  read_token_limit: 'Read exceeded its token limit. Read a smaller range with offset and limit, or search the file.',
+  tool_error: 'A tool failed. See its result in Conversations.',
+  task_error: 'A background task failed. See Conversations and Terminal.',
+  compact_error: 'Conversation compaction failed.',
+  status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
+  saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
+  executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  connection: 'The SDK connection failed. Check the server and provider connection.',
+  session_ended: 'The Agent SDK session ended unexpectedly.',
+  interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
+  session_error: 'The Agent SDK session failed. Check Terminal and the Model page.',
+} as const;
+export type RunnerFailureCode = keyof typeof FAILURE;
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null): string {
+  return code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+}
+
 export interface RunnerTask {
   id: string;
   kind: string | null;
@@ -30,10 +60,18 @@ export interface RunnerTool {
 }
 
 export interface RunnerEvent {
+  id?: string;
   at: number;
   kind: RunnerEventKind;
   tool: string | null;
+  toolUseId?: string;
   taskId: string | null;
+  code?: RunnerFailureCode;
+}
+
+export interface RunnerFailure extends RunnerEvent {
+  id: string;
+  code: RunnerFailureCode;
 }
 
 export interface RunnerActivity {
@@ -53,6 +91,8 @@ export interface RunnerActivity {
   tasks: RunnerTask[];
   events: RunnerEvent[];
   lastError: string | null;
+  activeFailure?: RunnerFailure | null;
+  lastFailure?: RunnerFailure | null;
 }
 
 const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -76,9 +116,30 @@ function tool(raw: unknown): RunnerTool | null {
   return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
 }
 
+const failureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
+
 function event(raw: unknown): RunnerEvent | null {
   if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
-  return { at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId) };
+  return {
+    at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
+    ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
+    ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
+    ...(failureKind(raw.kind) && failureCode(raw.code) ? { code: raw.code } : {}),
+  };
+}
+
+function failure(raw: unknown): RunnerFailure | null {
+  const parsed = event(raw);
+  return parsed?.id !== undefined && parsed.code !== undefined ? { ...parsed, id: parsed.id, code: parsed.code } : null;
+}
+
+function safeError(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const known = Object.values(FAILURE).find((text) => text === raw);
+  if (known !== undefined) return known;
+  const tool = /^([A-Za-z0-9_.:-]{1,128}) failed\. See its result in Conversations\.$/.exec(raw)?.[1];
+  return tool === undefined ? FAILURE.session_error : runnerFailureSummary('tool_error', tool);
 }
 
 function list<T>(raw: unknown, parse: (item: unknown) => T | null, max: number): T[] {
@@ -90,6 +151,15 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
   return typeof value === 'string' && /^\d{1,32}$/.test(value) ? { procStart: value } : {};
 }
 
+function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
+  const activeFailure = failure(raw.activeFailure);
+  return {
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool) : safeError(raw.lastError),
+    ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
+    ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
+  };
+}
+
 export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
   if (!isRecord(raw) || raw.runner !== 'sdk' || !phase(raw.phase) || count(raw.pid) === 0 || count(raw.updatedAt) === 0) return null;
   return {
@@ -98,6 +168,6 @@ export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
     pending: count(raw.pending), workers: count(raw.workers), approvals: count(raw.approvals),
     tools: list(raw.tools, name, 20), activeTools: list(raw.activeTools, tool, 20),
     tasks: list(raw.tasks, task, 30), events: list(raw.events, event, 40),
-    lastError: typeof raw.lastError === 'string' ? raw.lastError.slice(0, 300) : null,
+    ...failureFields(raw),
   };
 }

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.260",
+  "version": "0.1.0-beta.262",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/runtime/sdk-runner/src/activity.ts

@@ -1,8 +1,9 @@
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
 import { isRecord } from '@metro-labs/core/is-record';
 import { log } from '@metro-labs/core/log';
-import type { RunnerActivity, RunnerEventKind, RunnerPhase, RunnerTool } from '@metro-labs/core/runner-activity';
+import { runnerFailureSummary, type RunnerActivity, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerPhase, type RunnerTool } from '@metro-labs/core/runner-activity';
 import { writeAtomic } from '@metro-labs/core/secure-fs';
 import { ActivityTasks, activityName } from './activity-tasks.js';
 import type { ApprovalAsk } from './approvals.js';
@@ -16,14 +17,34 @@ type System = Extract<SDKMessage, { type: 'system' }>;
 interface TrackedTool extends RunnerTool { parent: string | null }
 interface Approval { tool: string | null; taskId: string | null; worker: boolean }
 
-export function failureSummary(err: unknown): string {
+function sessionFailureCode(err: unknown): RunnerFailureCode {
   const text = err instanceof Error ? err.message : String(err);
-  if (text === STATUS_UNAVAILABLE) return STATUS_UNAVAILABLE;
-  if (/saved Agent SDK state/i.test(text)) return 'The saved Agent SDK state cannot be read. Restore it before starting.';
-  if (/unauthorized|authentication|invalid.*key|401|403/i.test(text)) return 'The provider refused authentication. Check the Model page.';
-  if (/ENOENT|not found|executable|spawn/i.test(text)) return 'The SDK executable could not start. Prepare the SDK runtime again.';
-  if (/ECONN|network|fetch failed|timed? ?out/i.test(text)) return 'The SDK connection failed. Check the server and provider connection.';
-  return 'The Agent SDK session failed. Check Terminal and the Model page.';
+  for (const code of ['status_unavailable', 'session_ended', 'interrupted', 'saved_state', 'authentication', 'executable', 'connection'] as const)
+    if (text === runnerFailureSummary(code)) return code;
+  if (/saved Agent SDK state/i.test(text)) return 'saved_state';
+  if (/unauthorized|authentication|invalid.*key|\b40[13]\b/i.test(text)) return 'authentication';
+  if (/ENOENT|not found|executable|spawn/i.test(text)) return 'executable';
+  if (/ECONN|network|fetch failed|timed? ?out/i.test(text)) return 'connection';
+  return 'session_error';
+}
+
+export function failureSummary(err: unknown): string { return runnerFailureSummary(sessionFailureCode(err)); }
+
+const PROVIDER_ERRORS: Record<NonNullable<Extract<SDKMessage, { type: 'assistant' }>['error']>, RunnerFailureCode> = {
+  authentication_failed: 'authentication', oauth_org_not_allowed: 'authentication', cloud_credential_error: 'authentication', account_on_hold: 'authentication', verification_required: 'authentication',
+  billing_error: 'billing', rate_limit: 'rate_limit', overloaded: 'provider_unavailable', server_error: 'provider_unavailable',
+  max_output_tokens: 'output_limit', invalid_request: 'invalid_request', model_not_found: 'invalid_request', unknown: 'provider_error',
+};
+
+function providerFailure(status: number | null | undefined): RunnerFailureCode {
+  const codes: Record<number, RunnerFailureCode | undefined> = { 400: 'invalid_request', 401: 'authentication', 402: 'billing', 403: 'authentication', 404: 'invalid_request', 429: 'rate_limit' };
+  if (status === null || status === undefined) return 'provider_error';
+  return codes[status] ?? (status >= 500 && status <= 599 ? 'provider_unavailable' : 'provider_error');
+}
+
+function readTokenLimit(content: unknown): boolean {
+  if (typeof content === 'string') return /File content \([\d,]+ tokens\) exceeds maximum allowed tokens \([\d,]+\)/.test(content.slice(0, 2_048));
+  return Array.isArray(content) && content.slice(0, 8).some((block: unknown) => isRecord(block) && block.type === 'text' && typeof block.text === 'string' && readTokenLimit(block.text));
 }
 
 function processIdentity(): Pick<RunnerActivity, 'procStart'> {
@@ -44,6 +65,8 @@ export class Activity {
   private readonly approvals = new Map<string, Approval>();
   private busy = false;
   private failed = false;
+  private providerCode: RunnerFailureCode | null = null;
+  private interrupted: RunnerFailure | null = null;
   private compacting = false;
   private ready = false;
   private timer: ReturnType<typeof setInterval> | null = null;
@@ -51,7 +74,7 @@ export class Activity {
   private writeFailed = false;
   private readonly state: RunnerActivity = {
     pid: process.pid, ...processIdentity(), runner: 'sdk', phase: 'starting', mainPhase: 'starting', mainStartedAt: null, sessionId: null, updatedAt: Date.now(),
-    pending: 0, workers: 0, approvals: 0, tools: [], activeTools: [], tasks: [], events: [], lastError: null,
+    pending: 0, workers: 0, approvals: 0, tools: [], activeTools: [], tasks: [], events: [], lastError: null, activeFailure: null, lastFailure: null,
   };
 
   constructor(private readonly path: string) {}
@@ -68,6 +91,7 @@ export class Activity {
     return {
       ...s, tools: [...s.tools], activeTools: s.activeTools.map((tool) => ({ ...tool })),
       tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map((event) => ({ ...event })),
+      activeFailure: s.activeFailure ? { ...s.activeFailure } : null, lastFailure: s.lastFailure ? { ...s.lastFailure } : null,
     };
   }
 
@@ -97,11 +121,11 @@ export class Activity {
 
   fail(message: string): void {
     this.failed = true;
-    this.state.lastError = message;
-    this.event('session_failed');
+    const failure = this.failure('session_failed', sessionFailureCode(message), true);
+    if (failure.code === 'interrupted') this.interrupted = failure;
     this.state.phase = 'error';
     this.state.mainPhase = 'error';
-    log.error({ reason: message }, 'sdk-runner: activity error');
+    log.error({ reason: failure.code }, 'sdk-runner: activity error');
     this.flush();
   }
 
@@ -155,8 +179,7 @@ export class Activity {
     this.compacting = compacting;
     if (message.compact_result === 'success') this.event('compacted');
     else if (message.compact_result === 'failed') {
-      this.state.lastError = 'Conversation compaction failed.';
-      this.event('compact_failed');
+      this.failure('compact_failed', 'compact_error', false, null, null, { id: message.uuid });
     }
   }
 
@@ -171,6 +194,8 @@ export class Activity {
   private turn(): void {
     this.busy = true;
     if (this.state.mainStartedAt !== null) return;
+    this.clearFailure();
+    this.providerCode = null;
     this.state.mainStartedAt = Date.now();
     this.event('turn_started');
   }
@@ -189,8 +214,8 @@ export class Activity {
   }
 
   private taskEvent(kind: RunnerEventKind, tool: string | null, taskId: string | null): void {
-    if (kind === 'task_failed') this.state.lastError = 'A background task failed. See Conversations and Terminal.';
-    this.event(kind, tool, taskId);
+    if (kind === 'task_failed') this.failure(kind, 'task_error', false, tool, taskId);
+    else this.event(kind, tool, taskId);
   }
 
   private result(message: Extract<SDKMessage, { type: 'result' }>): void {
@@ -200,25 +225,30 @@ export class Activity {
     for (const [id, tool] of this.tools) if (tool.parent === null) this.tools.delete(id);
     this.failed = message.is_error || message.subtype !== 'success';
     if (!this.failed) {
+      this.clearFailure();
+      this.providerCode = null;
       this.event('turn_finished');
       return;
     }
-    const code = message.subtype === 'success' ? 'provider_error' : message.subtype;
-    this.state.lastError = `SDK turn failed (${code}). Check Conversations and the Model page.`;
-    this.event('turn_failed');
+    const code = message.subtype === 'success' ? this.providerCode ?? providerFailure(message.api_error_status) : message.subtype;
+    this.providerCode = null;
+    this.failure('turn_failed', code, true, null, null, { id: message.uuid });
     log.error({ reason: code }, 'sdk-runner: turn failed');
   }
 
   private content(message: Extract<SDKMessage, { type: 'assistant' | 'user' }>): void {
     const content = message.message.content;
     const parent = message.parent_tool_use_id ?? null;
+    if (parent === null && message.type === 'assistant') {
+      this.turn();
+      if (message.error !== undefined) this.providerCode = message.error === 'unknown' ? null : PROVIDER_ERRORS[message.error];
+    }
     if (Array.isArray(content)) for (const block of content) if (isRecord(block)) this.block(block, parent);
-    if (parent === null && message.type === 'assistant') this.turn();
   }
 
   private block(block: Record<string, unknown>, parent: string | null): void {
     if (block.type === 'tool_use' && typeof block.id === 'string') this.tool(block.id, block.name, parent);
-    else if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') this.finish(block.tool_use_id, block.is_error === true, parent);
+    else if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') this.finish(block.tool_use_id, block.is_error === true, parent, block.content);
   }
 
   private tool(id: string, rawName: unknown, parent: string | null): void {
@@ -231,14 +261,13 @@ export class Activity {
     log.info({ tool: name, worker: taskId }, 'sdk-runner: tool started');
   }
 
-  private finish(id: string, failed: boolean, parent: string | null): void {
+  private finish(id: string, failed: boolean, parent: string | null, content: unknown): void {
     const tool = this.tools.get(id);
     if (tool === undefined && this.tasks.isHidden(parent)) return;
     this.tools.delete(id);
     const name = tool?.name ?? 'tool';
     if (failed) {
-      this.state.lastError = `${name} failed. See its result in Conversations.`;
-      this.event('tool_failed', name, tool?.taskId ?? null);
+      this.toolFailure(id, tool, parent, content);
       log.warn({ tool: name }, 'sdk-runner: tool failed');
       return;
     }
@@ -246,8 +275,35 @@ export class Activity {
     log.info({ tool: name }, 'sdk-runner: tool finished');
   }
 
+  private toolFailure(id: string, tool: TrackedTool | undefined, parent: string | null, content: unknown): void {
+    const name = tool?.name ?? 'tool';
+    const code = name === 'Read' && readTokenLimit(content) ? 'read_token_limit' : 'tool_error';
+    this.failure('tool_failed', code, false, name, tool?.taskId ?? this.tasks.taskFor(parent), { toolUseId: id });
+  }
+
+  private clearFailure(): void {
+    this.failed = false;
+    this.state.activeFailure = this.interrupted;
+    this.state.lastError = this.interrupted === null ? null : runnerFailureSummary(this.interrupted.code);
+  }
+
+  private failure(kind: RunnerEventKind, code: RunnerFailureCode, active: boolean, tool: string | null = null, taskId: string | null = null, identity: Pick<RunnerEvent, 'id' | 'toolUseId'> = {}): RunnerFailure {
+    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }) };
+    this.state.lastFailure = failure;
+    if (active) {
+      this.state.activeFailure = failure;
+      this.state.lastError = runnerFailureSummary(code, tool);
+    }
+    this.record(failure);
+    return failure;
+  }
+
   private event(kind: RunnerEventKind, tool: string | null = null, taskId: string | null = null): void {
-    this.state.events.unshift({ at: Date.now(), kind, tool, taskId });
+    this.record({ id: randomUUID(), at: Date.now(), kind, tool, taskId });
+  }
+
+  private record(event: RunnerEvent): void {
+    this.state.events.unshift(event);
     if (this.state.events.length > MAX_EVENTS) this.state.events.length = MAX_EVENTS;
   }
 

package/runtime/sdk-runner/src/app.ts

@@ -14,7 +14,7 @@ export interface RunningAgent {
   runner: Runner;
   link: MetroLink;
   done: Promise<void>;
-  stop(): Promise<void>;
+  stop(cancelActive?: boolean): Promise<void>;
 }
 
 export interface AppHooks {
@@ -42,10 +42,10 @@ async function connected(cfg: RunnerConfig, hooks: AppHooks, release: () => Prom
     lost: (reason) => { hooks.lost(reason); },
   });
   let stopped = false;
-  const stop = async (): Promise<void> => {
+  const stop = async (cancelActive = true): Promise<void> => {
     if (stopped) return;
     stopped = true;
-    runner.close();
+    runner.close(cancelActive);
     await link.close().catch(() => { log.debug('sdk-runner: closing the metro link failed'); });
     hooks.activity?.stop();
     await release();
@@ -57,7 +57,7 @@ async function connected(cfg: RunnerConfig, hooks: AppHooks, release: () => Prom
     runner.start(runnerOptions(cfg, tools, approvalsThrough(link, (id, ask) => { hooks.activity?.approval(id, ask); }), resume, hooks.env));
     return { runner, link, done: runner.run(hooks.observe), stop };
   } catch (err) {
-    runner.close();
+    runner.close(false);
     await link.close().catch(() => { log.debug('sdk-runner: closing the metro link failed'); });
     throw err;
   }

package/runtime/sdk-runner/src/inbox.ts

@@ -8,6 +8,8 @@ export type Priority = 'now' | 'next' | 'later';
 export interface Unanswered {
   text: string;
   at: number;
+  uuid?: Uuid;
+  state?: 'queued' | 'started';
 }
 
 const KINDS_MAX = 2_000;
@@ -20,6 +22,7 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
   private readonly ledger = new Map<string, Unanswered>();
   private wake: (() => void) | null = null;
   private closed = false;
+  private restoring = false;
 
   constructor(private readonly changed: (unanswered: Unanswered[]) => void = () => undefined) {}
 
@@ -49,14 +52,29 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
     return this.kinds.get(uuid);
   }
 
-  consumed(uuids: readonly string[]): void {
+  started(uuids: readonly string[]): void {
+    let changed = false;
+    for (const uuid of uuids) {
+      const entry = this.ledger.get(uuid);
+      if (entry === undefined || entry.state === 'started') continue;
+      this.ledger.set(uuid, { ...entry, state: 'started' });
+      changed = true;
+    }
+    if (changed) this.changed(this.unanswered());
+  }
+
+  finished(uuids = this.startedUuids()): void {
     let changed = false;
     for (const uuid of uuids) changed = this.ledger.delete(uuid) || changed;
     if (changed) this.changed(this.unanswered());
   }
 
+  startedUuids(): string[] {
+    return [...this.ledger].filter(([, entry]) => entry.state === 'started').map(([uuid]) => uuid);
+  }
+
   unanswered(now = Date.now()): Unanswered[] {
-    return [...this.ledger.values()].filter((entry) => now - entry.at < LEDGER_AGE_MS);
+    return [...this.ledger.values()].filter((entry) => entry.state === 'started' || now - entry.at < LEDGER_AGE_MS);
   }
 
   close(): void {
@@ -79,16 +97,23 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
   }
 
   again(left: readonly Unanswered[]): void {
-    for (const entry of left) this.push('chat', entry.text, undefined, randomUUID(), entry.at);
+    if (left.length === 0) return;
+    this.restoring = true;
+    try {
+      for (const entry of left) this.push('chat', entry.text, undefined, entry.uuid ?? randomUUID(), entry.at);
+    } finally {
+      this.restoring = false;
+    }
+    this.changed(this.unanswered());
   }
 
-  private remember(uuid: string, text: string, at: number): void {
-    this.ledger.set(uuid, { text, at });
+  private remember(uuid: Uuid, text: string, at: number): void {
+    this.ledger.set(uuid, { text, at, uuid, state: 'queued' });
     while (this.ledger.size > LEDGER_MAX) {
-      const oldest = this.ledger.keys().next().value;
+      const oldest = [...this.ledger].find(([, entry]) => entry.state !== 'started')?.[0];
       if (oldest === undefined) break;
       this.ledger.delete(oldest);
     }
-    this.changed(this.unanswered());
+    if (!this.restoring) this.changed(this.unanswered());
   }
 }

package/runtime/sdk-runner/src/link.ts

@@ -79,6 +79,7 @@ export class MetroLink implements Asker {
   }
 
   ask(ask: PermissionAsk, signal: AbortSignal): Promise<Behavior> {
+    if (signal.aborted) return Promise.resolve('deny');
     return new Promise((resolve) => {
       const settle = (behavior: Behavior): void => {
         this.waiting.delete(ask.request_id);

package/runtime/sdk-runner/src/main.ts

@@ -8,7 +8,7 @@ let agent: RunningAgent | null = null;
 let activity: Activity | null = null;
 
 async function exit(code: number): Promise<never> {
-  await agent?.stop();
+  await agent?.stop(code === 0);
   process.exit(code);
 }
 

package/runtime/sdk-runner/src/recovery.ts

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, openSync, readSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { Unanswered } from './inbox.js';
+
+export const INTERRUPTED_NOTICE = 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.';
+
+function scanTranscript(fd: number, wanted: ReadonlySet<string>): Set<string> {
+  const found = new Set<string>();
+  const chunk = Buffer.alloc(64 * 1024);
+  let overlap = '';
+  for (let size = readSync(fd, chunk); size > 0; size = readSync(fd, chunk)) {
+    const text = overlap + chunk.toString('latin1', 0, size);
+    for (const uuid of wanted) if (text.includes(`"${uuid}"`)) found.add(uuid);
+    if (found.size === wanted.size) break;
+    overlap = text.slice(-37);
+  }
+  return found;
+}
+
+function transcriptUuids(path: string | null, inputs: readonly Unanswered[]): Set<string> {
+  const wanted = new Set(inputs.flatMap((input) => input.state !== 'started' && input.uuid !== undefined ? [input.uuid] : []));
+  if (path === null || wanted.size === 0) return new Set();
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, 'r');
+    return scanTranscript(fd, wanted);
+  } catch (err) {
+    if (isRecord(err) && err.code === 'ENOENT') return new Set();
+    throw new Error('The saved Agent SDK transcript cannot be checked. Restore it before starting.');
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function recoverInputs(inputs: readonly Unanswered[], transcript: string | null): { unanswered: Unanswered[]; interrupted: Unanswered[] } {
+  const seen = transcriptUuids(transcript, inputs);
+  const unanswered: Unanswered[] = [];
+  const interrupted: Unanswered[] = [];
+  for (const input of inputs) {
+    const entry = { ...input, uuid: input.uuid ?? randomUUID(), state: input.state ?? 'queued' };
+    if (entry.state === 'started' || seen.has(entry.uuid)) interrupted.push({ ...entry, state: 'started' });
+    else unanswered.push(entry);
+  }
+  return { unanswered, interrupted };
+}

package/runtime/sdk-runner/src/runner.ts

@@ -6,6 +6,7 @@ import { channelText, type ChannelEvent } from './channel-text.js';
 import type { RunnerConfig } from './config.js';
 import { Inbox, type Unanswered, type Uuid } from './inbox.js';
 import { CALL_ENDED, callStarted, callWords, FRONT_RULES } from './rules.js';
+import { INTERRUPTED_NOTICE } from './recovery.js';
 import type { SessionStore } from './session-store.js';
 import { SessionWatch, startedCommand, uuidsOf } from './session-watch.js';
 import { SpeechRouter, type SpeechSink } from './speech.js';
@@ -79,6 +80,9 @@ export class Runner {
   private stall: ReturnType<typeof setTimeout> | null = null;
   private model: string | null = null;
   private switching: Promise<void> = Promise.resolve();
+  private ended = false;
+  private readonly interrupted: number;
+  private interruptionReported = false;
 
   constructor(private readonly parts: RunnerParts) {
     this.inbox = new Inbox((unanswered) => {
@@ -94,7 +98,8 @@ export class Runner {
       },
     });
     this.watch = new SessionWatch(parts.readOnly);
-    const again = parts.store.unanswered();
+    const { unanswered: again, interrupted } = parts.store.recover();
+    this.interrupted = interrupted.length;
     this.inbox.again(again);
     if (again.length > 0) log.info({ count: again.length }, 'sdk-runner: chat messages the last session never read go in again');
   }
@@ -118,20 +123,33 @@ export class Runner {
 
   async run(observe?: (message: SDKMessage) => void): Promise<void> {
     if (this.session === null) throw new Error('the runner was not started');
-    for await (const message of this.session) {
-      const m: Record<string, unknown> = { ...message };
-      const started = startedCommand(m);
-      this.inbox.consumed([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
-      this.watch.observe(m);
-      this.speech.observe(message);
-      this.note(m);
-      this.parts.activity?.observe(message);
-      observe?.(message);
+    try {
+      for await (const message of this.session) {
+        const m: Record<string, unknown> = { ...message };
+        this.trackInput(m);
+        this.watch.observe(m);
+        this.speech.observe(message);
+        this.note(m);
+        this.parts.activity?.observe(message);
+        observe?.(message);
+      }
+    } finally {
+      this.ended = true;
     }
   }
 
   chat(event: ChannelEvent): Uuid {
-    return this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
+    try {
+      return this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
+    } catch (err) {
+      log.error('sdk-runner: could not save incoming chat; stopping before further work');
+      try {
+        this.parts.activity?.fail(INTERRUPTED_NOTICE);
+      } finally {
+        this.close(false);
+      }
+      throw err;
+    }
   }
 
   callStarted(where: string): Uuid {
@@ -149,10 +167,14 @@ export class Runner {
     return this.inbox.push('note', CALL_ENDED);
   }
 
-  close(): void {
+  close(cancelActive = true): void {
     this.clearStall();
-    this.inbox.close();
-    this.session?.close();
+    try {
+      if (cancelActive && !this.ended) this.inbox.finished();
+    } finally {
+      this.inbox.close();
+      this.session?.close();
+    }
   }
 
   private callPush(text: string): Uuid {
@@ -199,6 +221,11 @@ export class Runner {
     if (session === null) return;
     await session.applyFlagSettings(allowedOnly(model));
     this.parts.activity?.connected();
+    if (this.interrupted > 0 && !this.interruptionReported) {
+      this.interruptionReported = true;
+      this.parts.activity?.fail(INTERRUPTED_NOTICE);
+      log.warn({ count: this.interrupted }, INTERRUPTED_NOTICE);
+    }
     if (model === this.model) return;
     const was = this.model;
     await session.setModel(model ?? undefined);
@@ -206,13 +233,20 @@ export class Runner {
     log.info({ was, now: model }, 'sdk-runner: the session thinks with the new model from now on, with no restart');
   }
 
-  private keep(unanswered: Unanswered[]): void {
-    this.parts.activity?.pending(unanswered.length);
-    try {
-      this.parts.store.saveUnanswered(unanswered);
-    } catch (err) {
-      log.warn({ err: errMsg(err) }, 'sdk-runner: could not keep the unanswered chat messages');
+  private trackInput(m: Record<string, unknown>): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    if (m.type === 'result') {
+      const uuids = uuidsOf(m);
+      if (uuids !== null) this.inbox.finished(uuids);
+      return;
     }
+    const started = startedCommand(m);
+    this.inbox.started([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
+  }
+
+  private keep(unanswered: Unanswered[]): void {
+    this.parts.store.saveUnanswered(unanswered);
+    this.parts.activity?.pending(unanswered.filter((entry) => entry.state !== 'started').length);
   }
 
   private note(m: Record<string, unknown>): void {

package/runtime/sdk-runner/src/session-store.ts

@@ -2,7 +2,8 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isRecord } from '@metro-labs/core/is-record';
 import { writeAtomic } from '@metro-labs/core/secure-fs';
-import type { Unanswered } from './inbox.js';
+import type { Unanswered, Uuid } from './inbox.js';
+import { recoverInputs } from './recovery.js';
 
 const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
@@ -11,10 +12,26 @@ export const projectFolder = (cwd: string): string => cwd.replace(/[^A-Za-z0-9]/
 interface Stored {
   sessionId: string | null;
   unanswered: Unanswered[];
+  interrupted: Unanswered[];
 }
 
-const entry = (raw: unknown): Unanswered | null =>
-  isRecord(raw) && typeof raw.text === 'string' && typeof raw.at === 'number' ? { text: raw.text, at: raw.at } : null;
+function inputId(raw: unknown): Uuid | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string' || !SESSION_ID.test(raw)) throw new Error(UNREADABLE);
+  return raw as Uuid;
+}
+
+function inputState(raw: unknown): Unanswered['state'] {
+  if (raw === undefined || raw === 'queued' || raw === 'started') return raw;
+  throw new Error(UNREADABLE);
+}
+
+function entry(raw: unknown): Unanswered | null {
+  if (!isRecord(raw) || typeof raw.text !== 'string' || typeof raw.at !== 'number') return null;
+  const uuid = inputId(raw.uuid);
+  const state = inputState(raw.state);
+  return { text: raw.text, at: raw.at, ...(uuid === undefined ? {} : { uuid }), ...(state === undefined ? {} : { state }) };
+}
 
 const UNREADABLE = 'The saved Agent SDK state cannot be read. Restore it before starting.';
 
@@ -22,11 +39,15 @@ function stored(raw: unknown): Stored {
   if (!isRecord(raw)) throw new Error(UNREADABLE);
   const id = raw.sessionId ?? null;
   if (id !== null && (typeof id !== 'string' || !SESSION_ID.test(id))) throw new Error(UNREADABLE);
-  const list = raw.unanswered === undefined ? [] : raw.unanswered;
-  if (!Array.isArray(list)) throw new Error(UNREADABLE);
-  const unanswered = list.map(entry);
-  if (!unanswered.every((e): e is Unanswered => e !== null)) throw new Error(UNREADABLE);
-  return { sessionId: id, unanswered };
+  return { sessionId: id, unanswered: entries(raw.unanswered), interrupted: entries(raw.interrupted) };
+}
+
+function entries(raw: unknown): Unanswered[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) throw new Error(UNREADABLE);
+  const list = raw.map(entry);
+  if (!list.every((e): e is Unanswered => e !== null)) throw new Error(UNREADABLE);
+  return list;
 }
 
 export class SessionStore {
@@ -46,6 +67,15 @@ export class SessionStore {
     return this.read().unanswered;
   }
 
+  recover(): Stored {
+    const stored = this.read();
+    const transcript = stored.sessionId === null ? null : join(this.claudeDir, 'projects', projectFolder(this.cwd), `${stored.sessionId}.jsonl`);
+    const recovered = recoverInputs(stored.unanswered, transcript);
+    const next = { ...stored, unanswered: recovered.unanswered, interrupted: [...stored.interrupted, ...recovered.interrupted] };
+    if (stored.unanswered.length > 0) this.write(next);
+    return next;
+  }
+
   save(id: string): void {
     const stored = this.read();
     if (!SESSION_ID.test(id) || stored.sessionId === id) return;
@@ -60,7 +90,7 @@ export class SessionStore {
     try {
       return stored(JSON.parse(readFileSync(this.path, 'utf8')));
     } catch (err) {
-      if (isRecord(err) && err.code === 'ENOENT') return { sessionId: null, unanswered: [] };
+      if (isRecord(err) && err.code === 'ENOENT') return { sessionId: null, unanswered: [], interrupted: [] };
       throw new Error(UNREADABLE);
     }
   }

package/runtime/sdk-runner/src/session-watch.ts

@@ -40,6 +40,7 @@ export class SessionWatch {
   private readonly compacted: (() => void)[] = [];
   private compactingNow = false;
   private lastContext = 0;
+  private streamUsage: Record<string, unknown> = {};
 
   constructor(private readonly readOnly: (tool: string) => boolean) {}
 
@@ -60,6 +61,7 @@ export class SessionWatch {
     else if (m.type === 'result') this.settle();
     if (m.parent_tool_use_id !== null) return;
     if (m.type === 'assistant' && isRecord(m.message)) this.assistant(m.message);
+    else if (m.type === 'stream_event' && isRecord(m.event)) this.stream(m.event);
     else if (m.type === 'user') for (const id of toolResultIds(m.message)) this.done(id);
   }
 
@@ -77,9 +79,19 @@ export class SessionWatch {
     else if (m.subtype === 'compact_boundary') {
       this.setCompacting(false);
       this.lastContext = 0;
+      this.streamUsage = {};
     }
   }
 
+  private stream(event: Record<string, unknown>): void {
+    if (event.type === 'message_start' && isRecord(event.message)) {
+      this.streamUsage = isRecord(event.message.usage) ? event.message.usage : {};
+    } else if (event.type === 'message_delta' && isRecord(event.usage)) {
+      this.streamUsage = { ...this.streamUsage, ...event.usage };
+    } else return;
+    this.lastContext = contextOf(this.streamUsage) || this.lastContext;
+  }
+
   private setCompacting(on: boolean): void {
     this.compactingNow = on;
     if (!on) for (const resume of this.compacted.splice(0)) resume();