@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,142 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { runnerDiagnostic, runnerFailureCode, runnerFailureSummary, type RunnerDiagnostic, type RunnerFailureCode } from '@metro-labs/core/runner-activity';
+
+const SCAN_MAX = 2_048;
+const ERROR_FAILURES: Record<NonNullable<RunnerDiagnostic['errorCode']>, RunnerFailureCode> = {
+  ENOENT: 'executable', EACCES: 'executable', EPERM: 'executable', ENOEXEC: 'executable', ENOMEM: 'executable',
+  ERR_MODULE_NOT_FOUND: 'module', MODULE_NOT_FOUND: 'module', ERR_DLOPEN_FAILED: 'module',
+  ECONNREFUSED: 'connection', ECONNRESET: 'connection', ENOTFOUND: 'connection', EAI_AGAIN: 'connection', ETIMEDOUT: 'connection',
+  CERT_HAS_EXPIRED: 'connection', UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'connection',
+};
+const KNOWN = ['status_unavailable', 'session_ended', 'interrupted', 'saved_state', 'authentication', 'executable', 'connection', 'module', 'configuration', 'process_exit', 'session_error'] as const;
+
+export interface SessionFailure {
+  code: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
+}
+
+function normalizeFailure(raw: unknown): SessionFailure {
+  if (!isRecord(raw) || !runnerFailureCode(raw.code)) return { code: 'session_error' };
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
+  return { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
+
+export class SessionError extends Error {
+  readonly failure: SessionFailure;
+
+  constructor(failure: SessionFailure) {
+    const safe = normalizeFailure(failure);
+    super(runnerFailureSummary(safe.code, null, safe.diagnostic));
+    this.failure = safe;
+  }
+}
+
+function statusFailure(status: number | undefined): RunnerFailureCode | null {
+  if (status === undefined) return null;
+  if (status === 401 || status === 403) return 'authentication';
+  if (status === 402) return 'billing';
+  if (status === 429) return 'rate_limit';
+  return status >= 500 ? 'provider_unavailable' : 'invalid_request';
+}
+
+const TEXT_FAILURES: [RunnerFailureCode, RegExp][] = [
+  ['authentication', /\bunauthorized\b|\bauthentication (?:failed|error)\b|\binvalid(?:[ -]api)?[ -]key\b/i],
+  ['module', /cannot find (?:module|package)|error (?:while )?loading shared libraries|module not found/i],
+  ['configuration', /METRO_(?:RUNNER_MCP_URL|AGENT_KEY) is not set|invalid (?:configuration|settings)|failed to parse (?:configuration|settings)|unknown (?:option|argument)/i],
+  ['executable', /executable|spawn|command not found/i],
+  ['connection', /network|fetch failed|timed? ?out/i],
+];
+
+function errorText(value: unknown): string {
+  if (typeof value === 'string') return value.slice(0, SCAN_MAX);
+  return isRecord(value) && typeof value.message === 'string' ? value.message.slice(0, SCAN_MAX) : '';
+}
+
+function evidence(raw: Record<string, unknown>, message: string, source: RunnerDiagnostic['source']): RunnerDiagnostic | undefined {
+  const errorCodes = message.match(/\b[A-Z][A-Z_]{2,40}\b/g) ?? [];
+  return runnerDiagnostic({
+    source, errorCode: raw.code ?? errorCodes.find((code) => Object.hasOwn(ERROR_FAILURES, code)),
+    httpStatus: raw.status ?? raw.statusCode ?? Number(/(?:^|\bHTTP(?:\/[12](?:\.\d)?)?\s+|\bstatus(?: code)?[:= ]+)([45]\d\d)\b/i.exec(message)?.[1]),
+    exitCode: raw.exitCode ?? Number(/^Claude Code process exited with code (\d{1,3})\b/.exec(message)?.[1]),
+    signal: raw.signal ?? /^Claude Code process terminated by signal (SIG[A-Z]{1,8})\b/.exec(message)?.[1],
+  });
+}
+
+function diagnosticCode(message: string, diagnostic: RunnerDiagnostic | undefined): RunnerFailureCode | null {
+  if (/saved Agent SDK state/i.test(message)) return 'saved_state';
+  if (diagnostic?.errorCode !== undefined) return ERROR_FAILURES[diagnostic.errorCode];
+  return statusFailure(diagnostic?.httpStatus);
+}
+
+function processFailure(diagnostic: RunnerDiagnostic | undefined): RunnerFailureCode | null {
+  return diagnostic?.exitCode !== undefined || diagnostic?.signal !== undefined ? 'process_exit' : null;
+}
+
+function namedFailure(value: unknown, source: RunnerDiagnostic['source']): SessionFailure {
+  const errorName = runnerDiagnostic({ source, errorName: isRecord(value) ? value.name : undefined })?.errorName;
+  return errorName === undefined ? { code: 'session_error' } : { code: 'session_error', diagnostic: { source, errorName } };
+}
+
+export function debugFailure(stage: string, err: unknown): void {
+  if (process.env.METRO_RUNNER_DEBUG !== '1') return;
+  const text = err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : String(err);
+  process.stderr.write(`metro agent debug (${stage}, this terminal only): ${text.slice(0, 4_000)}\n`);
+}
+
+function classify(value: unknown, source: RunnerDiagnostic['source']): SessionFailure {
+  const message = errorText(value);
+  const known = KNOWN.find((code) => message === runnerFailureSummary(code));
+  if (known !== undefined) return { code: known };
+  const diagnostic = evidence(isRecord(value) ? value : {}, message, source);
+  const code = diagnosticCode(message, diagnostic) ?? TEXT_FAILURES.find(([, pattern]) => pattern.test(message))?.[0] ?? processFailure(diagnostic) ?? 'session_error';
+  return code === 'session_error' ? namedFailure(value, source) : { code, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
+
+export function sessionFailure(err: unknown): SessionFailure {
+  try {
+    if (err instanceof SessionError) return normalizeFailure(err.failure);
+    let current = err;
+    let result: SessionFailure = { code: 'session_error' };
+    for (let depth = 0; depth < 4; depth++) {
+      const next = classify(current, 'exception');
+      if (next.code !== 'session_error' || (result.code === 'session_error' && result.diagnostic === undefined)) result = next;
+      if (!isRecord(current) || current.cause === undefined) break;
+      current = current.cause;
+    }
+    return result;
+  } catch {
+    return { code: 'session_error' };
+  }
+}
+
+export const failureSummary = (err: unknown): string => {
+  const failure = sessionFailure(err);
+  return runnerFailureSummary(failure.code, null, failure.diagnostic);
+};
+
+export class StartupDiagnostics {
+  private tail = '';
+  private observed: SessionFailure | null = null;
+
+  stderr(text: string): void {
+    const head = text.slice(0, SCAN_MAX);
+    const candidates = [head, (this.tail + head).slice(-SCAN_MAX), text.length > SCAN_MAX ? text.slice(-SCAN_MAX) : ''];
+    for (const candidate of candidates) {
+      const failure = classify(candidate, 'stderr');
+      if (failure.code !== 'session_error' && (failure.code !== 'process_exit' || this.observed === null)) this.observed = failure;
+    }
+    this.tail = (this.tail + (text.length > SCAN_MAX ? text.slice(-SCAN_MAX) : text)).slice(-SCAN_MAX);
+  }
+
+  failure(err: unknown): SessionFailure {
+    const failure = sessionFailure(err);
+    const observed = this.observed;
+    if (observed === null || !['session_error', 'process_exit'].includes(failure.code)) return failure;
+    return { ...observed, diagnostic: runnerDiagnostic({ ...failure.diagnostic, ...observed.diagnostic }) };
+  }
+
+  clear(): void {
+    this.tail = '';
+    this.observed = null;
+  }
+}

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

@@ -0,0 +1,168 @@
+import { randomUUID } from 'node:crypto';
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RunnerInput } from '@metro-labs/core/runner-activity';
+import { InputQueue } from './input-queue.js';
+import { InputTiming, type InputWatch } from './input-timing.js';
+
+export type Uuid = ReturnType<typeof randomUUID>;
+export type InputKind = RunnerInput['kind'];
+export type Priority = 'now' | 'next' | 'later';
+
+export interface Unanswered {
+  text: string;
+  at: number;
+  uuid?: Uuid;
+  state?: 'queued' | 'started';
+}
+
+interface InboxHooks {
+  ready?(): boolean;
+  dispatch?(message: SDKUserMessage): void;
+  queue?(count: number, oldest: number | null): void;
+  input?: InputWatch;
+}
+
+const KINDS_MAX = 2_000;
+const LEDGER_MAX = 100;
+const LEDGER_AGE_MS = 6 * 60 * 60_000;
+
+export class Inbox implements AsyncIterable<SDKUserMessage> {
+  private readonly queue = new InputQueue();
+  private readonly kinds = new Map<string, InputKind>();
+  private readonly ledger = new Map<string, Unanswered>();
+  private readonly dispatched = new Set<string>();
+  private readonly timing: InputTiming;
+  private wake: (() => void) | null = null;
+  private closed = false;
+  private restoring = false;
+
+  constructor(private readonly changed: (unanswered: Unanswered[]) => void = () => undefined, private readonly hooks: InboxHooks = {}) {
+    this.timing = new InputTiming(hooks.input ?? (() => undefined));
+  }
+
+  get pending(): number { return this.queue.size; }
+
+  accepts(kind: InputKind, text: string): boolean { return !this.closed && this.queue.accepts(kind, text); }
+
+  activeUuids(): Set<string> { return new Set([...this.dispatched, ...this.startedUuids()]); }
+
+  compact(): Uuid {
+    const uuid = this.push('note', '/compact');
+    this.queue.prefer(uuid);
+    return uuid;
+  }
+
+  push(kind: InputKind, text: string, _priority?: Priority, uuid: Uuid = randomUUID(), at = Date.now()): Uuid {
+    return this.enqueue(kind, text, uuid, at, { origin: { kind: 'channel', server: 'metro' } });
+  }
+
+  automation(text: string, uuid: Uuid, at: number): Uuid {
+    return this.enqueue('note', text, uuid, at, { origin: { kind: 'task-notification', subkind: 'scheduled-trigger' }, client_composed: true });
+  }
+
+  private enqueue(kind: InputKind, text: string, uuid: Uuid, at: number, provenance: Pick<SDKUserMessage, 'origin' | 'client_composed'>): Uuid {
+    if (this.closed) throw new Error('The SDK input queue is closed.');
+    this.queue.check(kind, text);
+    if (kind === 'chat') this.remember(uuid, text, at);
+    this.mark(uuid, kind);
+    this.queue.push(kind, {
+      type: 'user', message: { role: 'user', content: text }, parent_tool_use_id: null,
+      uuid, ...provenance,
+    }, text, at);
+    this.timing.accept(uuid, kind, at);
+    this.notify();
+    return uuid;
+  }
+
+  mark(uuid: string, kind: InputKind): void {
+    this.kinds.set(uuid, kind);
+    if (this.kinds.size <= KINDS_MAX) return;
+    const oldest = this.kinds.keys().next().value;
+    if (oldest !== undefined) this.kinds.delete(oldest);
+  }
+
+  kindOf(uuid: string): InputKind | undefined { return this.kinds.get(uuid); }
+
+  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());
+    this.timing.consume(uuids);
+  }
+
+  output(): void { this.timing.output(); }
+  boundary(): void { this.timing.boundary(); }
+
+  finished(uuids = this.startedUuids()): void {
+    let changed = false;
+    for (const uuid of uuids) {
+      this.dispatched.delete(uuid);
+      changed = this.ledger.delete(uuid) || changed;
+    }
+    if (changed) this.changed(this.unanswered());
+    this.timing.finish(uuids);
+  }
+
+  cancel(uuids: readonly string[]): void {
+    const ephemeral = uuids.filter((uuid) => this.kindOf(uuid) !== 'chat');
+    const removed = this.queue.cancel(new Set(ephemeral));
+    this.timing.finish(removed, true);
+    this.notify();
+  }
+
+  startedUuids(): string[] {
+    return [...this.ledger].filter(([, entry]) => entry.state === 'started').map(([uuid]) => uuid);
+  }
+
+  unanswered(now = Date.now()): Unanswered[] {
+    return [...this.ledger.values()].filter((entry) => entry.state === 'started' || now - entry.at < LEDGER_AGE_MS);
+  }
+
+  close(): void {
+    this.closed = true;
+    this.wake?.();
+  }
+
+  notify(): void {
+    this.hooks.queue?.(this.queue.size, this.queue.oldest);
+    this.wake?.();
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<SDKUserMessage> {
+    while (!this.closed) {
+      const next = (this.hooks.ready?.() ?? true) ? this.queue.take() : undefined;
+      if (next !== undefined) {
+        if (next.uuid !== undefined && this.ledger.has(next.uuid)) this.dispatched.add(next.uuid);
+        this.hooks.dispatch?.(next);
+        if (next.uuid !== undefined) this.timing.dispatch(next.uuid);
+        this.notify();
+        yield next;
+        continue;
+      }
+      await new Promise<void>((resolve) => { this.wake = resolve; });
+      this.wake = null;
+    }
+  }
+
+  again(left: readonly Unanswered[]): void {
+    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: Uuid, text: string, at: number): void {
+    if (!this.ledger.has(uuid) && this.ledger.size >= LEDGER_MAX) throw new Error('The SDK input queue is full. Wait for queued work to finish before retrying.');
+    this.ledger.set(uuid, { text, at, uuid, state: 'queued' });
+    if (!this.restoring) this.changed(this.unanswered());
+  }
+}

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

@@ -0,0 +1,77 @@
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RunnerInput } from '@metro-labs/core/runner-activity';
+
+type InputKind = RunnerInput['kind'];
+
+const LANES: readonly InputKind[] = ['chat', 'call', 'note'];
+const CAPS: Record<InputKind, number> = { chat: 100, call: 32, note: 16 };
+const BYTES_MAX = 4 * 1024 * 1024;
+const INPUT_MAX = 256 * 1024;
+
+interface Queued {
+  kind: InputKind;
+  message: SDKUserMessage;
+  bytes: number;
+  at: number;
+}
+
+export class InputQueue {
+  private readonly items: Queued[] = [];
+  private bytes = 0;
+  private lane = 0;
+  private first: string | null = null;
+
+  prefer(uuid: string): void { this.first = uuid; }
+
+  get size(): number { return this.items.length; }
+  get oldest(): number | null { return this.items.reduce<number | null>((at, item) => at === null ? item.at : Math.min(at, item.at), null); }
+
+  accepts(kind: InputKind, text: string): boolean {
+    const bytes = Buffer.byteLength(text);
+    return bytes <= INPUT_MAX && this.bytes + bytes <= BYTES_MAX && this.items.filter((item) => item.kind === kind).length < CAPS[kind];
+  }
+
+  check(kind: InputKind, text: string): void {
+    if (!this.accepts(kind, text)) throw new Error('The SDK input queue is full. Wait for queued work to finish before retrying.');
+  }
+
+  push(kind: InputKind, message: SDKUserMessage, text: string, at: number): void {
+    const bytes = Buffer.byteLength(text);
+    this.items.push({ kind, message, bytes, at });
+    this.bytes += bytes;
+  }
+
+  take(): SDKUserMessage | undefined {
+    if (this.first !== null) {
+      const index = this.items.findIndex((item) => item.message.uuid === this.first);
+      this.first = null;
+      if (index >= 0) return this.remove(index)?.message;
+    }
+    for (let i = 0; i < LANES.length; i += 1) {
+      const lane = (this.lane + i) % LANES.length;
+      const index = this.items.findIndex((item) => item.kind === LANES[lane]);
+      if (index < 0) continue;
+      this.lane = (lane + 1) % LANES.length;
+      return this.remove(index)?.message;
+    }
+    return undefined;
+  }
+
+  cancel(uuids: ReadonlySet<string>): string[] {
+    const removed: string[] = [];
+    for (let index = this.items.length - 1; index >= 0; index -= 1) {
+      const uuid = this.items[index]?.message.uuid;
+      if (uuid !== undefined && uuids.has(uuid)) {
+        this.remove(index);
+        removed.push(uuid);
+      }
+    }
+    return removed;
+  }
+
+  private remove(index: number): Queued | undefined {
+    const [item] = this.items.splice(index, 1);
+    if (item !== undefined) this.bytes -= item.bytes;
+    return item;
+  }
+}

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

@@ -0,0 +1,68 @@
+import type { RunnerInput } from '@metro-labs/core/runner-activity';
+import { log } from '@metro-labs/core/log';
+
+export type InputWatch = (input: RunnerInput) => void;
+
+export class InputTiming {
+  private readonly inputs = new Map<string, RunnerInput>();
+  private readonly active = new Set<string>();
+
+  constructor(private readonly changed: InputWatch) {}
+
+  accept(id: string, kind: RunnerInput['kind'], at: number): void {
+    const input: RunnerInput = { id, kind, state: 'accepted', acceptedAt: at, dispatchedAt: null, consumedAt: null, firstOutputAt: null, completedAt: null };
+    this.inputs.set(id, input);
+    if (this.inputs.size > 2_000) {
+      const oldest = this.inputs.keys().next().value;
+      if (oldest !== undefined) { this.inputs.delete(oldest); this.active.delete(oldest); }
+    }
+    this.note(input);
+  }
+
+  dispatch(id: string): void {
+    const input = this.inputs.get(id);
+    if (input === undefined) return;
+    input.dispatchedAt = Date.now();
+    this.note(input);
+  }
+
+  consume(uuids: readonly string[]): void {
+    for (const id of uuids) {
+      const input = this.inputs.get(id);
+      if (input === undefined || input.consumedAt !== null) continue;
+      input.consumedAt = Date.now();
+      input.state = 'consumed';
+      this.active.add(id);
+      this.note(input);
+    }
+  }
+
+  output(): void {
+    for (const id of this.active) {
+      const input = this.inputs.get(id);
+      if (input === undefined || input.firstOutputAt !== null) continue;
+      input.firstOutputAt = Date.now();
+      input.state = 'output';
+      this.note(input);
+    }
+  }
+
+  finish(uuids: readonly string[], cancelled = false): void {
+    for (const id of uuids) {
+      const input = this.inputs.get(id);
+      if (input === undefined) continue;
+      input.completedAt = Date.now();
+      input.state = cancelled ? 'cancelled' : 'completed';
+      this.inputs.delete(id);
+      this.active.delete(id);
+      this.note(input);
+    }
+  }
+
+  boundary(): void { this.active.clear(); }
+
+  private note(input: RunnerInput): void {
+    this.changed({ ...input });
+    log.info({ input: input.id, kind: input.kind, state: input.state, acceptedAt: input.acceptedAt, dispatchedAt: input.dispatchedAt, consumedAt: input.consumedAt, firstOutputAt: input.firstOutputAt, completedAt: input.completedAt, queueAgeMs: (input.consumedAt ?? Date.now()) - input.acceptedAt }, 'sdk-runner: input lifecycle');
+  }
+}

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

@@ -0,0 +1,154 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { CallToolResultSchema, type CallToolRequest, type CallToolResult, type ListToolsResult, type Notification } from '@modelcontextprotocol/sdk/types.js';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { CALL_NOTICE, CALL_STATE, callNotice, callState, type CallNotice, type CallSource, type CallState } from '@metro-labs/core/call';
+import { channelEvent, type ChannelEvent } from './channel-text.js';
+
+const CHANNEL = 'notifications/claude/channel';
+const ASK = 'notifications/claude/channel/permission_request';
+const ANSWER = 'notifications/claude/channel/permission';
+const TOOLS_CHANGED = 'notifications/tools/list_changed';
+const MODEL = 'notifications/metro/model';
+const TOOL_TIMEOUT_MS = 30 * 60_000;
+const RECONNECT = { initialReconnectionDelay: 500, maxReconnectionDelay: 5_000, reconnectionDelayGrowFactor: 1.5, maxRetries: 60 };
+const GAVE_UP = 'Maximum reconnection attempts';
+
+export type Behavior = 'allow' | 'deny';
+
+const modelIn = (params: Record<string, unknown>): string | null => (typeof params.model === 'string' && params.model !== '' ? params.model : null);
+
+export interface PermissionAsk {
+  request_id: string;
+  tool_name: string;
+  description: string;
+  input_preview: string;
+  call?: CallSource;
+}
+
+export interface LinkEvents {
+  channel(event: ChannelEvent): void;
+  call?(notice: CallNotice): void;
+  callState?(state: CallState): void;
+  toolsChanged(): void;
+  model(model: string | null): void;
+  lost(reason: string): void;
+}
+
+export interface Asker {
+  ask(ask: PermissionAsk, signal: AbortSignal): Promise<Behavior>;
+}
+
+export class MetroLink implements Asker {
+  private readonly waiting = new Map<string, (behavior: Behavior) => void>();
+
+  private constructor(
+    private readonly client: Client,
+    private readonly events: LinkEvents,
+  ) {}
+
+  static async open(url: string, key: string, events: LinkEvents): Promise<MetroLink> {
+    const client = new Client({ name: 'metro-sdk-runner', version: '0.1.0' });
+    const link = new MetroLink(client, events);
+    client.fallbackNotificationHandler = (notification): Promise<void> => {
+      link.notified(notification);
+      return Promise.resolve();
+    };
+    client.onerror = (err): void => {
+      link.failed(err);
+    };
+    const transport = new StreamableHTTPClientTransport(new URL(url), {
+      requestInit: { headers: { authorization: `Bearer ${key}` } },
+      reconnectionOptions: RECONNECT,
+    });
+    await client.connect(transport);
+    return link;
+  }
+
+  get instructions(): string | undefined {
+    return this.client.getInstructions();
+  }
+
+  listTools(): Promise<ListToolsResult> {
+    return this.client.listTools();
+  }
+
+  callTool(params: CallToolRequest['params'], signal: AbortSignal): Promise<CallToolResult> {
+    return this.client.request({ method: 'tools/call', params }, CallToolResultSchema, {
+      signal,
+      timeout: TOOL_TIMEOUT_MS,
+      resetTimeoutOnProgress: true,
+    });
+  }
+
+  ask(ask: PermissionAsk, signal: AbortSignal): Promise<Behavior> {
+    if (signal.aborted) return Promise.resolve('deny');
+    return new Promise((resolve) => {
+      const abort = (): void => {
+        settle('deny');
+        this.client.notification({ method: 'notifications/metro/permission_cancel', params: { request_id: ask.request_id } }).catch(() => {
+          log.warn('sdk-runner: could not cancel a pending approval with metro');
+        });
+      };
+      const settle = (behavior: Behavior): void => {
+        signal.removeEventListener('abort', abort);
+        if (!this.waiting.delete(ask.request_id)) return;
+        resolve(behavior);
+      };
+      this.waiting.set(ask.request_id, settle);
+      signal.addEventListener('abort', abort, { once: true });
+      this.client.notification({ method: ASK, params: { ...ask } }).catch((err: unknown) => {
+        log.warn({ err: errMsg(err), id: ask.request_id }, 'sdk-runner: could not hand an approval to metro');
+        settle('deny');
+      });
+    });
+  }
+
+  async close(): Promise<void> {
+    for (const settle of [...this.waiting.values()]) settle('deny');
+    await this.client.close();
+  }
+
+  private notified(notification: Notification): void {
+    const params = isRecord(notification.params) ? notification.params : {};
+    if (notification.method === CHANNEL) {
+      const event = channelEvent(params);
+      if (event !== null) this.events.channel(event);
+    } else if (notification.method === CALL_NOTICE) {
+      this.callNotified(params);
+    } else if (notification.method === CALL_STATE) {
+      this.reconciled(params);
+    } else if (notification.method === ANSWER) {
+      this.answered(params);
+    } else if (notification.method === TOOLS_CHANGED) {
+      this.events.toolsChanged();
+    } else if (notification.method === MODEL) {
+      this.events.model(modelIn(params));
+    }
+  }
+
+  private callNotified(params: Record<string, unknown>): void {
+    const notice = callNotice(params);
+    if (notice !== null) this.events.call?.(notice);
+  }
+
+  private reconciled(params: Record<string, unknown>): void {
+    const state = callState(params);
+    if (state !== null) this.events.callState?.(state);
+  }
+
+  private answered(params: Record<string, unknown>): void {
+    const id = typeof params.request_id === 'string' ? params.request_id : '';
+    this.waiting.get(id)?.(params.behavior === 'allow' ? 'allow' : 'deny');
+  }
+
+  private failed(err: Error): void {
+    const reason = errMsg(err);
+    if (reason.includes(GAVE_UP)) {
+      this.events.lost(reason);
+      return;
+    }
+    log.debug({ err: reason }, 'sdk-runner: the metro link reported an error');
+  }
+}

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

@@ -0,0 +1,57 @@
+import { dirname, join } from 'node:path';
+import { log } from '@metro-labs/core/log';
+import { Activity, failureSummary } from './activity.js';
+import { startAgent, type RunningAgent } from './app.js';
+import { runnerConfig } from './config.js';
+import { debugFailure, sessionFailure } from './errors.js';
+
+let agent: RunningAgent | null = null;
+let starting: Promise<RunningAgent> | null = null;
+let activity: Activity | null = null;
+let exiting = false;
+let cancelRequested = false;
+
+async function exit(code: number, cancelActive = false): Promise<void> {
+  if (cancelActive && !cancelRequested) {
+    cancelRequested = true;
+    if (exiting && agent !== null) await agent.stop(true);
+  }
+  if (exiting) return;
+  exiting = true;
+  const running = agent ?? await starting?.catch(() => null);
+  await running?.stop(cancelRequested);
+  process.exit(code);
+}
+
+const exitWith = (code: number, cancelActive = false) => (): void => {
+  exit(code, cancelActive).catch(() => process.exit(code));
+};
+
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, exitWith(0));
+process.on('SIGUSR2', exitWith(0, true));
+
+try {
+  const cfg = runnerConfig();
+  activity = new Activity(join(dirname(cfg.statePath), 'agent-status.json'), 'SIGUSR2');
+  starting = startAgent(cfg, {
+    activity,
+    lost: () => {
+      if (exiting) return;
+      activity?.fail('The SDK lost its Metro connection. The session will restart.');
+      exitWith(1)();
+    },
+  });
+  agent = await starting;
+  try {
+    await agent.done;
+    if (!exiting) activity.fail('The Agent SDK session ended unexpectedly.');
+  } catch (err) {
+    debugFailure('session', err);
+    if (!exiting) activity.fail(err);
+  }
+} catch (err) {
+  debugFailure('start', err);
+  const failure = sessionFailure(err);
+  log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
+}
+await exit(1);