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

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

@@ -0,0 +1,194 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { isRecord } from '@metro-labs/core/is-record';
+import { runnerTaskDescription, runnerTaskModel, type RunnerEventKind, type RunnerTask, type RunnerTaskState } from '@metro-labs/core/runner-activity';
+
+export const activityName = (name: unknown): string | null => typeof name === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(name) ? name : null;
+const live = (task: RunnerTask): boolean => ['running', 'pending', 'paused'].includes(task.status);
+const terminal = (status: RunnerTaskState): boolean => ['completed', 'failed', 'stopped'].includes(status);
+type System = Extract<SDKMessage, { type: 'system' }>;
+type Emit = (kind: RunnerEventKind, tool?: string | null, taskId?: string | null) => void;
+type Metadata = Pick<RunnerTask, 'description' | 'lastObservedModel'>;
+
+export class ActivityTasks {
+  private readonly tasks = new Map<string, RunnerTask>();
+  private readonly parents = new Map<string, string>();
+  private readonly hidden = new Map<string, string>();
+  private readonly pending = new Map<string, Metadata>();
+  constructor(private readonly emit: Emit) {}
+
+  snapshot(): RunnerTask[] {
+    return [...this.tasks.values()].sort((a, b) => Number(live(b)) - Number(live(a)) || b.updatedAt - a.updatedAt).slice(0, 30).map((task) => ({ ...task }));
+  }
+
+  restore(tasks: RunnerTask[], parents: [string, string][]): void {
+    for (const task of tasks) this.tasks.set(task.id, task);
+    for (const [parent, id] of parents) this.parents.set(parent, id);
+  }
+
+  get running(): number { return [...this.tasks.values()].filter(live).length; }
+  taskFor(parent: string | null | undefined): string | null { return parent ? this.parents.get(parent) ?? null : null; }
+  known(id: string | null | undefined): string | null { return id && this.tasks.has(id) ? id : null; }
+  isHidden(id: string | null): boolean { return id !== null && this.hidden.has(id); }
+  isFinished(id: string): boolean { const task = this.tasks.get(id); return task !== undefined && !live(task); }
+
+  observe(message: System): void {
+    switch (message.subtype) {
+      case 'task_started': this.start(message); break;
+      case 'task_progress': this.progress(message); break;
+      case 'task_updated': this.patch(message); break;
+      case 'task_notification': this.end(message); break;
+      case 'background_tasks_changed': this.replace(message); break;
+      default: break;
+    }
+  }
+
+  launch(id: string, input: unknown): void {
+    if (!isRecord(input)) return;
+    const description = runnerTaskDescription(input.description);
+    if (description !== null) this.metadata(id, { description });
+  }
+
+  model(parent: string, value: unknown): void {
+    const lastObservedModel = runnerTaskModel(value);
+    if (lastObservedModel !== null) this.metadata(parent, { lastObservedModel });
+  }
+
+  private metadata(parent: string, fields: Metadata): void {
+    if (!activityName(parent) || this.isHidden(parent)) return;
+    const id = this.taskFor(parent);
+    const task = id === null ? undefined : this.tasks.get(id);
+    if (task !== undefined) { Object.assign(task, fields); return; }
+    const known = this.pending.get(parent);
+    this.pending.delete(parent);
+    const oldest = this.pending.keys().next();
+    if (this.pending.size >= 200 && !oldest.done) this.pending.delete(oldest.value);
+    this.pending.set(parent, { ...known, ...fields });
+  }
+
+  private link(parent: string, id: string): void {
+    this.parents.set(parent, id);
+    const task = this.tasks.get(id);
+    if (task !== undefined) Object.assign(task, this.pending.get(parent));
+    this.pending.delete(parent);
+  }
+
+  private describe(task: RunnerTask, value: unknown): void {
+    const description = runnerTaskDescription(value);
+    if (description !== null) task.description = description;
+  }
+
+  stop(): void {
+    for (const task of this.tasks.values()) if (live(task)) this.status(task, 'stopped');
+  }
+
+  private get(id: string): RunnerTask | null {
+    if (!activityName(id) || this.hidden.has(id)) return null;
+    const known = this.tasks.get(id);
+    if (known) return known;
+    if (this.tasks.size >= 200) {
+      const old = [...this.tasks.values()].find((task) => !live(task));
+      if (!old) return null;
+      this.tasks.delete(old.id);
+      for (const [parent, taskId] of this.parents) if (taskId === old.id) this.parents.delete(parent);
+    }
+    const task: RunnerTask = { id, kind: null, agent: null, status: 'unknown', background: false, startedAt: 0, updatedAt: Date.now(), endedAt: null, lastTool: null, toolUses: 0, durationMs: 0 };
+    this.tasks.set(id, task);
+    return task;
+  }
+
+  private hide(id: string, toolUseId?: string): void {
+    this.tasks.delete(id);
+    const parents = [...this.parents].filter(([, task]) => task === id).map(([parent]) => parent);
+    for (const key of [id, toolUseId, ...parents]) {
+      if (key === undefined) continue;
+      const oldest = this.hidden.keys().next();
+      if (this.hidden.size >= 400 && !oldest.done) this.hidden.delete(oldest.value);
+      this.hidden.set(key, id);
+      this.pending.delete(key);
+    }
+  }
+
+  private show(id: string): RunnerTask | null {
+    this.hidden.delete(id);
+    const task = this.get(id);
+    if (!task) return null;
+    for (const [key, taskId] of this.hidden) {
+      if (taskId !== id) continue;
+      this.hidden.delete(key);
+      this.link(key, id);
+    }
+    return task;
+  }
+
+  private start(message: Extract<System, { subtype: 'task_started' }>): void {
+    if (message.ambient || message.skip_transcript) { this.hide(message.task_id, message.tool_use_id); return; }
+    const task = this.get(message.task_id);
+    if (!task) return;
+    task.kind = activityName(message.task_type) ?? task.kind;
+    task.agent = activityName(message.subagent_type) ?? task.agent;
+    task.background = message.is_backgrounded === true;
+    task.startedAt = Date.now();
+    task.firstStartedAt ??= task.startedAt;
+    task.endedAt = null;
+    if (message.tool_use_id) this.link(message.tool_use_id, task.id);
+    this.describe(task, message.description);
+    this.status(task, 'running');
+  }
+
+  private progress(message: Extract<System, { subtype: 'task_progress' }>): void {
+    const task = this.tasks.get(message.task_id);
+    if (!task || terminal(task.status)) return;
+    if (message.tool_use_id) this.link(message.tool_use_id, task.id);
+    task.lastTool = activityName(message.last_tool_name);
+    task.toolUses = message.usage.tool_uses;
+    task.durationMs = message.usage.duration_ms;
+    task.updatedAt = Date.now();
+  }
+
+  private patch(message: Extract<System, { subtype: 'task_updated' }>): void {
+    const task = this.tasks.get(message.task_id);
+    if (!task) return;
+    this.describe(task, message.patch.description);
+    if (message.patch.is_backgrounded !== undefined) task.background = message.patch.is_backgrounded;
+    if (message.patch.status) this.status(task, message.patch.status === 'killed' ? 'stopped' : message.patch.status);
+    task.updatedAt = Date.now();
+  }
+
+  private end(message: Extract<System, { subtype: 'task_notification' }>): void {
+    if (message.ambient || message.skip_transcript) { this.hide(message.task_id, message.tool_use_id); return; }
+    const task = this.get(message.task_id);
+    if (!task) return;
+    if (message.tool_use_id) this.link(message.tool_use_id, task.id);
+    if (message.usage) {
+      task.durationMs = message.usage.duration_ms;
+      task.toolUses = message.usage.tool_uses;
+    }
+    this.status(task, message.reason === 'worker_restart' ? 'unknown' : message.status);
+    if (message.reason === 'worker_restart') this.emit('task_failed', null, task.id);
+  }
+
+  private replace(message: Extract<System, { subtype: 'background_tasks_changed' }>): void {
+    const ids = new Set(message.tasks.map((task) => task.task_id));
+    for (const task of this.tasks.values()) if (task.background && live(task) && !ids.has(task.id)) this.status(task, 'unknown');
+    for (const row of message.tasks) {
+      if (row.ambient) { this.hide(row.task_id); continue; }
+      const task = this.show(row.task_id);
+      if (!task) continue;
+      this.describe(task, row.description);
+      if (terminal(task.status)) continue;
+      task.kind = activityName(row.task_type);
+      task.background = true;
+      this.status(task, 'running');
+    }
+  }
+
+  private status(task: RunnerTask, status: RunnerTaskState): void {
+    const changed = task.status !== status;
+    task.status = status;
+    task.updatedAt = Date.now();
+    task.endedAt = terminal(status) ? task.updatedAt : null;
+    if (!changed) return;
+    const event: Partial<Record<RunnerTaskState, RunnerEventKind>> = { running: 'task_started', completed: 'task_completed', failed: 'task_failed', stopped: 'task_stopped' };
+    this.emit(event[status] ?? 'task_updated', null, task.id);
+  }
+}

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

@@ -0,0 +1,391 @@
+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 { runnerFailureSummary, type RunnerActivity, type RunnerDiagnostic, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerInput, 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';
+import type { SavedTask } from './task-state.js';
+import { sessionFailure } from './errors.js';
+export { failureSummary } from './errors.js';
+
+const HEARTBEAT_MS = 5_000;
+const MAX_TRACKED = 200;
+const MAX_TOOLS = 20;
+const MAX_EVENTS = 40;
+const STATUS_UNAVAILABLE = 'The SDK status file cannot be written. Check its path and permissions before starting.';
+type System = Extract<SDKMessage, { type: 'system' }>;
+interface TrackedTool extends RunnerTool { parent: string | null }
+interface Approval { tool: string | null; taskId: string | null; worker: boolean }
+
+function copyEvent<T extends RunnerEvent>(event: T): T {
+  return { ...event, ...(event.diagnostic === undefined ? {} : { diagnostic: { ...event.diagnostic } }) };
+}
+
+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'> {
+  if (process.platform !== 'linux') return {};
+  try {
+    const stat = readFileSync('/proc/self/stat', 'utf8');
+    const start = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    return start && /^\d{1,32}$/.test(start) ? { procStart: start } : {};
+  } catch {
+    log.warn('sdk-runner: process identity is unavailable');
+    return {};
+  }
+}
+
+export class Activity {
+  private readonly tools = new Map<string, TrackedTool>();
+  private readonly tasks = new ActivityTasks((kind, tool, taskId) => { this.taskEvent(kind, tool ?? null, taskId ?? null); });
+  private readonly approvals = new Map<string, Approval>();
+  private busy = false;
+  private failed = false;
+  private providerCode: RunnerFailureCode | null = null;
+  private readonly workerErrors = new Map<string, RunnerFailureCode>();
+  private interrupted: RunnerFailure | null = null;
+  private compacting = false;
+  private ready = false;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastWritten = '';
+  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, activeFailure: null, lastFailure: null,
+  };
+
+  constructor(private readonly path: string, cancelSignal?: RunnerActivity['cancelSignal']) {
+    if (cancelSignal !== undefined) this.state.cancelSignal = cancelSignal;
+  }
+
+  start(): void {
+    this.flush(true);
+    if (this.writeFailed) throw new Error(STATUS_UNAVAILABLE);
+    this.timer = setInterval(() => { this.flush(true); }, HEARTBEAT_MS);
+    this.timer.unref();
+  }
+
+  snapshot(): RunnerActivity {
+    const s = this.state;
+    return {
+      ...s, tools: [...s.tools], activeTools: s.activeTools.map((tool) => ({ ...tool })),
+      tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map(copyEvent),
+      ...(s.inputs === undefined ? {} : { inputs: s.inputs.map((input) => ({ ...input })) }),
+      activeFailure: s.activeFailure ? copyEvent(s.activeFailure) : null, lastFailure: s.lastFailure ? copyEvent(s.lastFailure) : null,
+    };
+  }
+
+  recover(tasks: SavedTask[]): void {
+    this.tasks.restore(tasks.map((task) => ({
+      id: task.id, kind: null, agent: null, status: task.state === 'interrupted' ? 'unknown' : task.state,
+      background: true, startedAt: 0, updatedAt: task.updatedAt, endedAt: null, lastTool: null, toolUses: 0, durationMs: 0,
+    })), tasks.flatMap((task) => task.toolUseId === null ? [] : [[task.toolUseId, task.id]]));
+    for (const task of tasks) {
+      if (task.notice === null) continue;
+      const code = task.notice.reason === 'worker_restart' ? 'interrupted' : task.notice.reason;
+      this.failure('task_failed', code, false, null, task.id);
+    }
+    this.update();
+  }
+
+  recovered(): void {
+    this.interrupted = null;
+    if (this.state.activeFailure?.code === 'interrupted') this.clearFailure();
+    this.update();
+  }
+
+  pending(count: number, oldest?: number | null): void {
+    this.state.pending = count;
+    if (oldest !== undefined) this.state.queueOldestAt = oldest;
+    this.update();
+  }
+
+  input(input: RunnerInput): void {
+    this.state.inputs = [input, ...(this.state.inputs ?? []).filter((entry) => entry.id !== input.id)].slice(0, MAX_EVENTS);
+    this.update();
+  }
+
+  call(state: NonNullable<RunnerActivity['callState']>): void {
+    this.state.callState = state;
+    this.update();
+  }
+
+  connected(): void {
+    this.ready = true;
+    this.update();
+  }
+
+  approval(id: string, ask: ApprovalAsk | null): void {
+    if (ask !== null && this.tasks.isHidden(ask.worker)) return;
+    const known = this.approvals.get(id);
+    if (ask !== null && known === undefined) {
+      const entry: Approval = { tool: activityName(ask.tool), taskId: this.tasks.known(ask.worker), worker: ask.worker !== null };
+      this.approvals.set(id, entry);
+      this.event('approval_waiting', entry.tool, entry.taskId);
+    } else if (ask === null && known !== undefined) {
+      this.approvals.delete(id);
+      this.event('approval_ended', known.tool, known.taskId);
+    }
+    this.update();
+  }
+
+  fail(err: unknown): void {
+    this.failed = true;
+    const safe = sessionFailure(err);
+    const failure = this.failure('session_failed', safe.code, true, null, null, {}, safe.diagnostic);
+    if (failure.code === 'interrupted') this.interrupted = failure;
+    this.state.phase = 'error';
+    this.state.mainPhase = 'error';
+    log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: this.state.lastError }, 'sdk-runner: activity error');
+    this.flush();
+  }
+
+  stop(): void {
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+    this.tasks.stop();
+    this.tools.clear();
+    this.approvals.clear();
+    this.busy = false;
+    this.state.mainStartedAt = null;
+    this.sync();
+    if (this.state.phase !== 'error') this.state.phase = 'stopped';
+    if (this.state.mainPhase !== 'error') this.state.mainPhase = 'stopped';
+    this.flush(true);
+  }
+
+  observe(message: SDKMessage): void {
+    if (message.type === 'system') this.system(message);
+    else if (message.type === 'result') this.result(message);
+    else if (message.type === 'assistant' || message.type === 'user') this.content(message);
+    else if (message.type === 'stream_event' && message.parent_tool_use_id === null && !this.turnOpen()) this.turn();
+    else return;
+    this.update();
+  }
+
+  private turnOpen(): boolean {
+    return this.busy && this.state.mainStartedAt !== null;
+  }
+
+  private system(message: System): void {
+    if (message.subtype === 'task_notification' && message.reason === 'worker_restart') this.workerErrors.set(message.task_id, 'interrupted');
+    switch (message.subtype) {
+      case 'init': this.init(message.session_id); break;
+      case 'status': this.status(message); break;
+      case 'session_state_changed': this.session(message.state); break;
+      case 'api_retry': this.event('api_retry'); break;
+      case 'permission_denied': this.event('permission_denied', activityName(message.tool_name), this.tasks.known(message.agent_id)); break;
+      default: this.tasks.observe(message); this.settle(message); break;
+    }
+  }
+
+  private init(sessionId: string): void {
+    this.state.sessionId = sessionId;
+    this.ready = true;
+    this.turn();
+  }
+
+  private status(message: Extract<System, { subtype: 'status' }>): void {
+    const compacting = message.status === 'compacting';
+    if (compacting && !this.compacting) this.event('compacting');
+    this.compacting = compacting;
+    if (message.compact_result === 'success') this.event('compacted');
+    else if (message.compact_result === 'failed') {
+      this.failure('compact_failed', 'compact_error', false, null, null, { id: message.uuid });
+    }
+  }
+
+  private session(state: 'idle' | 'running' | 'requires_action'): void {
+    if (state === 'running') this.turn();
+    else if (state === 'idle') {
+      this.busy = false;
+      this.state.mainStartedAt = null;
+    }
+  }
+
+  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');
+  }
+
+  private settle(message: System): void {
+    if (message.subtype === 'task_notification' && message.tool_use_id !== undefined) this.tools.delete(message.tool_use_id);
+    for (const [id, tool] of this.tools) {
+      tool.taskId ??= this.tasks.taskFor(tool.parent);
+      if (this.tasks.isHidden(tool.parent) || this.taskHiddenOrFinished(tool.taskId)) this.tools.delete(id);
+    }
+    for (const [id, approval] of this.approvals) if (this.taskHiddenOrFinished(approval.taskId)) this.approvals.delete(id);
+  }
+
+  private taskHiddenOrFinished(id: string | null): boolean {
+    return id !== null && (this.tasks.isHidden(id) || this.tasks.isFinished(id));
+  }
+
+  private taskEvent(kind: RunnerEventKind, tool: string | null, taskId: string | null): void {
+    if (kind === 'task_failed') this.failure(kind, this.workerErrors.get(taskId ?? '') ?? 'task_error', false, tool, taskId);
+    else this.event(kind, tool, taskId);
+    if (taskId !== null && ['task_completed', 'task_failed', 'task_stopped'].includes(kind)) this.workerErrors.delete(taskId);
+  }
+
+  private result(message: Extract<SDKMessage, { type: 'result' }>): void {
+    this.busy = (message.queued_turn_count ?? 0) > 0;
+    this.compacting = false;
+    this.state.mainStartedAt = null;
+    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' ? 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 (message.type === 'assistant') this.assistant(message, parent);
+    if (Array.isArray(content)) for (const block of content) if (isRecord(block)) this.block(block, parent);
+  }
+
+  private assistant(message: Extract<SDKMessage, { type: 'assistant' }>, parent: string | null): void {
+    if (parent !== null) {
+      this.tasks.model(parent, message.message.model);
+      const id = this.tasks.taskFor(parent);
+      if (id !== null && message.error !== undefined) this.workerErrors.set(id, PROVIDER_ERRORS[message.error]);
+      return;
+    }
+    this.turn();
+    if (message.error !== undefined) this.providerCode = message.error === 'unknown' ? null : PROVIDER_ERRORS[message.error];
+  }
+
+  private block(block: Record<string, unknown>, parent: string | null): void {
+    if (block.type === 'tool_use' && typeof block.id === 'string') {
+      if (block.name === 'Agent' || block.name === 'Task') this.tasks.launch(block.id, block.input);
+      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, block.content);
+  }
+
+  private tool(id: string, rawName: unknown, parent: string | null): void {
+    if (this.tools.has(id) || this.tools.size >= MAX_TRACKED) return;
+    if (this.tasks.isHidden(parent)) return;
+    const name = activityName(rawName) ?? 'tool';
+    const taskId = this.tasks.taskFor(parent);
+    this.tools.set(id, { id, name, taskId, startedAt: Date.now(), parent });
+    if (parent === null) this.event('tool_started', name);
+    log.info({ tool: name, worker: taskId }, 'sdk-runner: tool started');
+  }
+
+  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.toolFailure(id, tool, parent, content);
+      log.warn({ tool: name }, 'sdk-runner: tool failed');
+      return;
+    }
+    if (tool?.parent === null) this.event('tool_finished', name);
+    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'> = {}, diagnostic?: RunnerDiagnostic): RunnerFailure {
+    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }), ...(diagnostic === undefined ? {} : { diagnostic }) };
+    this.state.lastFailure = failure;
+    if (active) {
+      this.state.activeFailure = failure;
+      this.state.lastError = runnerFailureSummary(code, tool, diagnostic);
+    }
+    this.record(failure);
+    return failure;
+  }
+
+  private event(kind: RunnerEventKind, tool: string | null = null, taskId: string | null = null): void {
+    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;
+  }
+
+  private phaseOf(approval: boolean, working: boolean): RunnerPhase {
+    if (!this.ready) return 'starting';
+    if (this.compacting) return 'compacting';
+    if (approval) return 'approval';
+    if (working) return 'working';
+    return this.failed ? 'error' : 'idle';
+  }
+
+  private sync(): void {
+    const tools = [...this.tools.values()];
+    this.state.tools = [...new Set(tools.map((tool) => tool.name))].slice(0, MAX_TOOLS);
+    this.state.activeTools = tools.slice(0, MAX_TOOLS).map(({ id, name, taskId, startedAt, parent }) => ({ id, name, taskId, startedAt, worker: parent !== null }));
+    this.state.tasks = this.tasks.snapshot();
+    this.state.workers = this.tasks.running;
+    this.state.approvals = this.approvals.size;
+  }
+
+  private update(): void {
+    this.sync();
+    const main = this.busy || this.state.pending > 0;
+    const approvals = [...this.approvals.values()];
+    this.state.mainPhase = this.phaseOf(approvals.some((approval) => !approval.worker), main || [...this.tools.values()].some((tool) => tool.parent === null));
+    this.state.phase = this.phaseOf(approvals.length > 0, main || this.tools.size > 0 || this.state.workers > 0);
+    this.flush();
+  }
+
+  private flush(force = false): void {
+    const next = JSON.stringify({ ...this.state, updatedAt: 0 });
+    if (!force && next === this.lastWritten) return;
+    this.state.updatedAt = Date.now();
+    try {
+      writeAtomic(this.path, `${JSON.stringify(this.state)}\n`, 0o600);
+      this.lastWritten = next;
+      this.writeFailed = false;
+    } catch {
+      if (!this.writeFailed) log.error('sdk-runner: could not save activity status');
+      this.writeFailed = true;
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+import { dirname, join } from 'node:path';
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { AutomationStore } from '@metro-labs/core/automation-store';
+import { errMsg, log } from '@metro-labs/core/log';
+import { skillSourceRoot } from '@metro-labs/core/skill-source';
+import { SkillsRefresh } from './skills.js';
+import type { Activity } from './activity.js';
+import { approvalsThrough } from './approvals.js';
+import type { RunnerConfig } from './config.js';
+import { MetroLink } from './link.js';
+import { Runner, runnerOptions } from './runner.js';
+import { SessionStore } from './session-store.js';
+import { claimRunner } from './singleton.js';
+import { metroTools, type MetroTools } from './tool-proxy.js';
+
+export interface RunningAgent {
+  runner: Runner;
+  link: MetroLink;
+  done: Promise<void>;
+  stop(cancelActive?: boolean): Promise<void>;
+}
+
+export interface AppHooks {
+  lost(reason: string): void;
+  observe?: (message: SDKMessage) => void;
+  env?: NodeJS.ProcessEnv;
+  compactAt?: number;
+  activity?: Activity;
+}
+
+async function connected(cfg: RunnerConfig, hooks: AppHooks, release: () => Promise<void>): Promise<RunningAgent> {
+  const store = new SessionStore(cfg.statePath, cfg.claudeDir, cfg.cwd);
+  let tools: MetroTools | null = null;
+  const automationStore = new AutomationStore(join(dirname(cfg.statePath), 'automation'));
+  const skills = new SkillsRefresh(skillSourceRoot(cfg.claudeDir), cfg.claudeDir);
+  const runner = new Runner({ store, automationStore, skills, readOnly: (tool) => tools?.readOnly(tool) ?? false, ...hooks });
+  const link = await MetroLink.open(cfg.mcpUrl, cfg.key, {
+    channel: (event) => { runner.chat(event); },
+    call: (notice) => { runner.calls.notice(notice); },
+    callState: (state) => { runner.calls.reconcile(state.route); },
+    toolsChanged: () => { tools?.changed(); },
+    model: (model) => {
+      log.info({ model }, 'sdk-runner: the Model page picked a model');
+      runner.switchModel(model).catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'sdk-runner: could not switch the model');
+      });
+    },
+    lost: (reason) => { hooks.lost(reason); },
+  });
+  let stopped = false;
+  const stop = async (cancelActive = false): Promise<void> => {
+    if (stopped) {
+      if (cancelActive) runner.close(true);
+      return;
+    }
+    stopped = true;
+    runner.close(cancelActive);
+    await link.close().catch(() => { log.debug('sdk-runner: closing the metro link failed'); });
+    hooks.activity?.stop();
+    await release();
+  };
+  try {
+    tools = metroTools(link);
+    const resume = store.resumable();
+    log.info({ resume, model: cfg.model, mode: cfg.permissionMode }, 'sdk-runner: starting the Agent SDK session');
+    const approvals = approvalsThrough(link, (id, ask) => { hooks.activity?.approval(id, ask); }, (tool, input) => runner.calls.approval(tool, input));
+    runner.start(runnerOptions(cfg, tools, approvals, resume, hooks.env));
+    return { runner, link, done: runner.run(hooks.observe), stop };
+  } catch (err) {
+    runner.close(false);
+    await link.close().catch(() => { log.debug('sdk-runner: closing the metro link failed'); });
+    throw err;
+  }
+}
+
+export async function startAgent(cfg: RunnerConfig, hooks: AppHooks): Promise<RunningAgent> {
+  const release = await claimRunner(cfg.cwd);
+  try {
+    hooks.activity?.start();
+    return await connected(cfg, hooks, release);
+  } catch (err) {
+    hooks.activity?.fail(err);
+    hooks.activity?.stop();
+    await release().catch(() => { log.warn('sdk-runner: releasing process ownership failed'); });
+    throw err;
+  }
+}