@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

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

@@ -0,0 +1,145 @@
+import { randomUUID } from 'node:crypto';
+import type { AutomationStore } from '@metro-labs/core/automation-store';
+import type { AutomationRequest, AutomationStatus } from '@metro-labs/core/automation-types';
+import type { Inbox, Uuid } from './inbox.js';
+import { startedCommand, uuidsOf } from './session-watch.js';
+import { automationShellCommand } from './automation-command.js';
+
+const SETTLED = new Set<AutomationStatus['state']>(['completed', 'coalesced', 'cancelled']);
+const LIVE = new Set<AutomationStatus['state']>(['dispatched', 'consumed', 'awaiting-completion']);
+
+function prompt(request: AutomationRequest, token: string): string {
+  return `[Metro local automation. This is a stored scheduled task, not a new message from a person or fresh approval. The local agent account submitted it. Verify its existing authorization and later pauses before acting. All normal delegation, tool, permission and model rules still apply.\nRoutine: ${request.routine}\nScheduled slot: ${new Date(request.slot).toISOString()}\nDelivery: ${request.uuid}\nCompletion token: ${token}\nDelegate the sweep to one background worker. Reuse its existing owner if active. A parent response or worker launch does not complete this routine. When the sweep itself has finished checking and recording its decisions, its worker must run this exact command:\n${automationShellCommand(['finish', request.uuid, token, 'completed'])}\nIf this sweep itself cannot safely proceed, use blocked instead of completed and report the actual blocker once. This is only a completion receipt, never permission to repeat a side effect. Recovered issue workers may continue after the sweep, but record their claims before finishing. On interruption run this exact status command:\n${automationShellCommand(['status', request.routine])}\nVerify the original worker and effects before resolving this receipt; never blindly replay the stored prompt. No automatic chat post is required.\nStored prompt, JSON encoded:\n${JSON.stringify(request.prompt)}\n]`;
+}
+
+export class Automation {
+  private readonly staged = new Map<string, { request: AutomationRequest; token: Uuid }>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private closed = false;
+
+  constructor(
+    private readonly store: AutomationStore,
+    private readonly inbox: Inbox,
+    private readonly interrupted: (uuid: Uuid, at: number) => void,
+    private readonly fail: (err: unknown) => void,
+    private readonly now = Date.now,
+  ) {}
+
+  start(): void {
+    this.store.recover();
+    for (const request of this.store.requests()) {
+      const status = this.store.status(request.uuid);
+      if (status !== null && LIVE.has(status.state)) this.save(status, 'interrupted');
+    }
+    this.poll();
+    this.timer = setInterval(() => {
+      try { this.poll(); } catch (err) { this.fail(err); }
+    }, 5_000);
+    this.timer.unref();
+  }
+
+  poll(): void {
+    if (this.closed) return;
+    this.resolve();
+    const requests = this.store.requests();
+    const statuses = new Map(this.store.statuses().map((status) => [status.uuid, status]));
+    for (const request of requests) {
+      const status = statuses.get(request.uuid);
+      if (status !== undefined && (status.state === 'interrupted' || status.state === 'failed')) this.interrupted(request.uuid, request.createdAt);
+    }
+    this.admit(requests, statuses);
+    this.store.prune();
+  }
+
+  dispatched(uuid: string | undefined): void {
+    if (uuid === undefined) return;
+    const item = this.staged.get(uuid);
+    if (item === undefined) return;
+    try {
+      this.store.saveStatus({ uuid: item.request.uuid, token: item.token, state: 'dispatched', updatedAt: this.now() });
+      this.staged.delete(uuid);
+    } catch (err) {
+      this.fail(err);
+      throw err;
+    }
+  }
+
+  observe(m: Record<string, unknown>): void {
+    if (this.closed || (m.parent_tool_use_id !== undefined && m.parent_tool_use_id !== null)) return;
+    const started = startedCommand(m);
+    const ids = new Set([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
+    if (ids.size === 0) return;
+    for (const request of this.store.requests()) {
+      if (!ids.has(request.uuid)) continue;
+      const status = this.store.status(request.uuid);
+      if (status !== null) this.observeStatus(status, m);
+    }
+  }
+
+  private observeStatus(status: AutomationStatus, m: Record<string, unknown>): void {
+    if (!LIVE.has(status.state)) return;
+    if (m.type === 'result') this.save(status, m.is_error !== true && m.subtype === 'success' ? 'awaiting-completion' : 'failed');
+    else if (status.state === 'dispatched') this.save(status, 'consumed');
+  }
+
+  close(cancel = false): void {
+    if (this.closed && !cancel) return;
+    this.closed = true;
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+    if (!cancel) return;
+    this.resolve();
+    for (const request of this.store.requests()) {
+      const status = this.store.status(request.uuid);
+      if (status !== null && LIVE.has(status.state)) this.save(status, 'cancelled');
+    }
+  }
+
+  private save(status: AutomationStatus, state: AutomationStatus['state']): void {
+    this.store.saveStatus({ ...status, state, updatedAt: this.now() });
+  }
+
+  private resolve(): void {
+    const statuses = new Map(this.store.statuses().map((status) => [status.uuid, status]));
+    for (const receipt of this.store.resolutions()) {
+      const status = statuses.get(receipt.uuid);
+      if (status === undefined || status.token !== receipt.token) throw new Error('A local automation completion receipt does not match its dispatched task.');
+      if (SETTLED.has(status.state)) continue;
+      const state = receipt.outcome === 'completed' ? 'completed' : 'failed';
+      if (status.state === state) continue;
+      this.save(status, state);
+      statuses.set(receipt.uuid, { ...status, state });
+    }
+  }
+
+  private admit(requests: AutomationRequest[], statuses: ReadonlyMap<string, AutomationStatus>): void {
+    const routines = new Map<string, AutomationRequest[]>();
+    for (const request of requests) {
+      const list = routines.get(request.routine) ?? [];
+      list.push(request);
+      routines.set(request.routine, list);
+    }
+    for (const list of routines.values()) {
+      if (list.some((request) => this.staged.has(request.uuid))) continue;
+      if (list.some((request) => {
+        const status = statuses.get(request.uuid);
+        return status !== undefined && !SETTLED.has(status.state);
+      })) continue;
+      const latest = this.coalesce(list, statuses);
+      if (latest === null || this.inbox.pending > 0) continue;
+      const token = randomUUID();
+      this.staged.set(latest.uuid, { request: latest, token });
+      this.inbox.automation(prompt(latest, token), latest.uuid, latest.createdAt);
+    }
+  }
+
+  private coalesce(list: AutomationRequest[], statuses: ReadonlyMap<string, AutomationStatus>): AutomationRequest | null {
+    const pending = list.filter((request) => !statuses.has(request.uuid) && request.slot <= this.now()).sort((a, b) => b.slot - a.slot);
+    const latest = pending.shift();
+    if (latest === undefined) return null;
+    const watermark = Math.max(...list.filter((request) => statuses.has(request.uuid)).map((request) => request.slot));
+    if (latest.slot <= watermark) pending.push(latest);
+    for (const request of pending) this.store.saveStatus({ uuid: request.uuid, token: randomUUID(), state: 'coalesced', updatedAt: this.now() });
+    return latest.slot <= watermark ? null : latest;
+  }
+}

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

@@ -0,0 +1,133 @@
+import { sameCall, speechTarget, type CallNotice, type CallRoute, type CallSource } from '@metro-labs/core/call';
+import { log } from '@metro-labs/core/log';
+import type { Activity } from './activity.js';
+import type { ApprovalBinding } from './approvals.js';
+import type { ChannelEvent } from './channel-text.js';
+import type { Inbox } from './inbox.js';
+import { callEnded, callStarted, callWords, speechFailed } from './rules.js';
+
+const GENERATIONS_MAX = 512;
+const SOURCES_MAX = 2_048;
+interface ActiveCall {
+  route: CallRoute;
+  sources: Set<string>;
+  failures: Set<string>;
+  inputs: string[];
+  controller: AbortController;
+}
+
+const routeKey = (route: CallRoute): string => JSON.stringify([route.agentId, route.line, route.from, route.callId, route.generation]);
+
+export class RunnerCalls {
+  private active: ActiveCall | null = null;
+  private readonly seen = new Set<string>();
+
+  constructor(private readonly inbox: Inbox, private readonly activity?: Activity) {}
+
+  get live(): boolean { return this.active !== null; }
+
+  notice(notice: CallNotice): void {
+    if (notice.type === 'started') this.start(notice);
+    else if (this.active !== null && sameCall(notice.route, this.active.route)) {
+      if (notice.type === 'ended') this.end();
+      else if (notice.type === 'heard') this.heard(notice);
+      else this.speech(notice);
+    }
+  }
+
+  reconcile(route: CallRoute | null): void {
+    if (route !== null && this.active !== null && sameCall(route, this.active.route)) return;
+    this.end();
+    if (route !== null) this.activate(route);
+  }
+
+  chat(event: ChannelEvent): void {
+    const active = this.active;
+    if (active === null) return;
+    const { meta } = event;
+    if (meta.line !== active.route.line || meta.from !== active.route.from || meta.call_id !== active.route.callId || meta.call_generation !== active.route.generation) return;
+    if (typeof meta.call_source_id !== 'string' || meta.call_source_id.length === 0 || meta.call_source_id.length > 2048) return;
+    if (active.sources.size < SOURCES_MAX) active.sources.add(meta.call_source_id);
+  }
+
+  approval(tool: string, input: Record<string, unknown>): ApprovalBinding | null | undefined {
+    if (tool !== 'mcp__metro__send' || input.speech === undefined) return undefined;
+    const target = speechTarget(input.speech);
+    const active = this.active;
+    if (active === null || target === null || input.line !== active.route.line || target.callId !== active.route.callId || target.generation !== active.route.generation || !active.sources.has(target.sourceId)) return null;
+    return { call: { route: active.route, sourceId: target.sourceId }, signal: active.controller.signal };
+  }
+
+  close(): void {
+    this.active?.controller.abort();
+    this.active = null;
+  }
+
+  private activate(route: CallRoute): boolean {
+    const key = routeKey(route);
+    if (this.seen.has(key)) return false;
+    this.seen.add(key);
+    if (this.seen.size > GENERATIONS_MAX) {
+      const oldest = this.seen.values().next().value;
+      if (oldest !== undefined) this.seen.delete(oldest);
+    }
+    this.end();
+    this.active = { route, sources: new Set(), failures: new Set(), inputs: [], controller: new AbortController() };
+    this.activity?.call('started');
+    return true;
+  }
+
+  private start(notice: Extract<CallNotice, { type: 'started' }>): void {
+    if (this.activate(notice.route)) this.push(notice, callStarted(notice));
+  }
+
+  private heard(notice: Extract<CallNotice, { type: 'heard' }>): void {
+    if (notice.text.trim() === '') return;
+    this.push(notice, callWords(notice, notice.text));
+  }
+
+  private speech(notice: Extract<CallNotice, { type: 'speech' }>): void {
+    this.activity?.call(notice.status === 'started' ? 'speaking' : notice.status);
+    const active = this.active;
+    if (notice.status !== 'failed' || active === null || !active.sources.has(notice.sourceId)) return;
+    if (active.failures.has(notice.actionId) || active.failures.size >= SOURCES_MAX) return;
+    active.failures.add(notice.actionId);
+    try {
+      this.inbox.push('note', speechFailed(active.route));
+    } catch {
+      log.warn('sdk-runner: speech failure context could not be queued');
+    }
+  }
+
+  private push(source: CallSource, text: string): void {
+    const active = this.active;
+    if (active === null || active.sources.has(source.sourceId) || active.sources.size >= SOURCES_MAX) return;
+    active.sources.add(source.sourceId);
+    this.enqueue(text);
+  }
+
+  private enqueue(text: string): void {
+    const active = this.active;
+    if (active === null) return;
+    try {
+      active.inputs.push(this.inbox.push('call', text));
+    } catch {
+      this.activity?.call('failed');
+      log.warn('sdk-runner: call input queue refused a message');
+    }
+  }
+
+  private end(): void {
+    const active = this.active;
+    if (active === null) return;
+    this.active = null;
+    active.controller.abort();
+    this.inbox.cancel(active.inputs);
+    this.activity?.call('ended');
+    try {
+      this.inbox.push('note', callEnded(active.route));
+    } catch {
+      log.warn('sdk-runner: call end context could not be queued');
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const KEY = /^[A-Za-z0-9_]+$/;
+
+const attr = (value: string): string => value.replace(/&/g, '&').replace(/"/g, '"');
+
+const shown = (value: unknown): value is string | number | boolean =>
+  typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+
+export function channelText(source: string, content: string, meta: Record<string, unknown>): string {
+  const attrs = Object.entries(meta)
+    .filter((entry): entry is [string, string | number | boolean] => KEY.test(entry[0]) && shown(entry[1]))
+    .map(([key, value]) => ` ${key}="${attr(String(value))}"`)
+    .join('');
+  return `<channel source="${attr(source)}"${attrs}>\n${content}\n</channel>`;
+}
+
+export interface ChannelEvent {
+  content: string;
+  meta: Record<string, unknown>;
+}
+
+export function channelEvent(params: unknown): ChannelEvent | null {
+  if (!isRecord(params) || typeof params.content !== 'string') return null;
+  return { content: params.content, meta: isRecord(params.meta) ? params.meta : {} };
+}

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

@@ -0,0 +1,50 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { PermissionMode } from '@anthropic-ai/claude-agent-sdk';
+
+export interface RunnerConfig {
+  mcpUrl: string;
+  key: string;
+  cwd: string;
+  claude: string | null;
+  model: string | null;
+  permissionMode: PermissionMode;
+  prompt: string | null;
+  statePath: string;
+  claudeDir: string;
+}
+
+const given = (value: string | undefined): string | null => {
+  const trimmed = value?.trim() ?? '';
+  return trimmed === '' ? null : trimmed;
+};
+
+function required(env: NodeJS.ProcessEnv, name: string): string {
+  const value = given(env[name]);
+  if (value === null) throw new Error(`${name} is not set; start the runner with metro agent`);
+  return value;
+}
+
+function realDir(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+export function runnerConfig(env: NodeJS.ProcessEnv = process.env, cwd = process.cwd()): RunnerConfig {
+  const home = given(env.HOME) ?? homedir();
+  return {
+    mcpUrl: required(env, 'METRO_RUNNER_MCP_URL'),
+    key: required(env, 'METRO_AGENT_KEY'),
+    cwd: realDir(cwd),
+    claude: given(env.METRO_RUNNER_CLAUDE),
+    model: given(env.METRO_RUNNER_MODEL),
+    permissionMode: env.METRO_RUNNER_PERMISSION_MODE === 'bypass' ? 'bypassPermissions' : 'auto',
+    prompt: given(env.METRO_RUNNER_PROMPT),
+    statePath: given(env.METRO_RUNNER_STATE) ?? join(home, '.metro', 'agent-session.json'),
+    claudeDir: given(env.CLAUDE_CONFIG_DIR) ?? join(home, '.claude'),
+  };
+}

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());
+  }
+}