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

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

@@ -0,0 +1,358 @@
+import { query, type CanUseTool, type Options, type Query, type SDKMessage, type SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import { errMsg, log } from '@metro-labs/core/log';
+import { skillSourceRoot } from '@metro-labs/core/skill-source';
+import { type SkillsRefresh } from './skills.js';
+import { SkillWork } from './skill-work.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { AutomationStore } from '@metro-labs/core/automation-store';
+import type { Activity } from './activity.js';
+import { Automation } from './automation.js';
+import { ActivityTasks } from './activity-tasks.js';
+import { RunnerCalls } from './calls.js';
+import { channelText, type ChannelEvent } from './channel-text.js';
+import type { RunnerConfig } from './config.js';
+import { Inbox, type Unanswered, type Uuid } from './inbox.js';
+import { FRONT_RULES } from './rules.js';
+import { INTERRUPTED_NOTICE } from './recovery.js';
+import type { SessionStore } from './session-store.js';
+import { completedCommand, SessionWatch, startedCommand, uuidsOf } from './session-watch.js';
+import { TaskRecovery } from './task-recovery.js';
+import { METRO_SERVER, type MetroTools } from './tool-proxy.js';
+import { debugFailure, failureSummary, SessionError, StartupDiagnostics } from './errors.js';
+
+const STARTUP_WAIT = 'CLAUDE_CODE_MCP_STARTUP_WAIT_MS';
+export const COMPACT_AT = 120_000;
+export const COMPACT_IDLE_MS = 60_000;
+
+const MODEL_PINS: ReadonlySet<string> = new Set(['ANTHROPIC_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']);
+
+export function runnerEnv(env: NodeJS.ProcessEnv): Record<string, string | undefined> {
+  const unpinned = Object.fromEntries(Object.entries(env).filter(([name]) => !MODEL_PINS.has(name)));
+  const terminals = new Set((env.CLAUDE_CODE_TERMINAL_MCP_TOOLS ?? '').split(',').map((name) => name.trim()).filter(Boolean));
+  terminals.add('mcp__metro__send');
+  return { [STARTUP_WAIT]: '0', ...unpinned, DISABLE_AUTOUPDATER: '1', CLAUDE_CODE_TERMINAL_MCP_TOOLS: [...terminals].join(',') };
+}
+
+export type ModelSettings = Parameters<Query['applyFlagSettings']>[0];
+
+export const allowedOnly = (model: string | null): ModelSettings =>
+  model === null ? { availableModels: null, enforceAvailableModels: null } : { availableModels: [model], enforceAvailableModels: true };
+
+export function runnerOptions(cfg: RunnerConfig, tools: MetroTools, canUseTool: CanUseTool, resume: string | null, env = process.env): Options {
+  return {
+    ...(cfg.model === null ? {} : { model: cfg.model }),
+    cwd: cfg.cwd,
+    env: runnerEnv(env),
+    ...(cfg.claude === null ? {} : { pathToClaudeCodeExecutable: cfg.claude }),
+    settingSources: ['user', 'project', 'local'],
+    additionalDirectories: [skillSourceRoot(cfg.claudeDir)],
+    systemPrompt: { type: 'preset', preset: 'claude_code', append: cfg.prompt === null ? FRONT_RULES : `${cfg.prompt}\n\n${FRONT_RULES}` },
+    mcpServers: { [METRO_SERVER]: tools.config },
+    permissionMode: cfg.permissionMode,
+    allowDangerouslySkipPermissions: cfg.permissionMode === 'bypassPermissions',
+    canUseTool,
+    includePartialMessages: true,
+    extraArgs: { 'system-prompt-snapshot': 'off' },
+    ...(resume === null ? {} : { resume }),
+  };
+}
+
+export interface CompactState {
+  context: number;
+  floor: number | null;
+  limit: number;
+  busy: boolean;
+}
+
+export const compactDue = (s: CompactState): boolean => !s.busy && s.context >= s.limit && s.context - (s.floor ?? 0) >= s.limit / 2;
+
+export type OpenSession = (params: { prompt: AsyncIterable<SDKUserMessage>; options: Options }) => Query;
+
+export interface RunnerParts {
+  store: SessionStore;
+  readOnly: (tool: string) => boolean;
+  compactAt?: number;
+  open?: OpenSession;
+  activity?: Activity;
+  automationStore?: AutomationStore;
+  skills?: SkillsRefresh;
+}
+
+function streamOutput(event: Record<string, unknown>): boolean {
+  if (event.type === 'content_block_start' && isRecord(event.content_block)) return event.content_block.type === 'tool_use';
+  return event.type === 'content_block_delta' && isRecord(event.delta) && event.delta.type === 'text_delta' && typeof event.delta.text === 'string' && event.delta.text.length > 0;
+}
+
+function visibleOutput(m: Record<string, unknown>): boolean {
+  if (m.type === 'assistant' && isRecord(m.message) && Array.isArray(m.message.content)) {
+    return m.message.content.some((block: unknown) => isRecord(block) && (block.type === 'tool_use' || (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0)));
+  }
+  return m.type === 'stream_event' && isRecord(m.event) && streamOutput(m.event);
+}
+
+export class Runner {
+  readonly inbox: Inbox;
+  readonly calls: RunnerCalls;
+  readonly automation: Automation | null;
+  private readonly recovery: TaskRecovery;
+  private readonly watch: SessionWatch;
+  private readonly diagnostics = new StartupDiagnostics();
+  private readonly tasks = new ActivityTasks(() => undefined);
+  private readonly skillWork = new SkillWork();
+  private compactTimer: ReturnType<typeof setTimeout> | null = null;
+  private session: Query | null = null;
+  private sessionId: string | null = null;
+  private compactAsked: Uuid | null = null;
+  private compactFloor: number | null = null;
+  private compacted = false;
+  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.watch = new SessionWatch(parts.readOnly);
+    this.inbox = new Inbox((unanswered) => { this.keep(unanswered); }, {
+      ready: () => { parts.skills?.check(); return this.watch.admitting && parts.skills?.busy !== true; },
+      dispatch: (message) => { this.automation?.dispatched(message.uuid); this.watch.dispatched(message.uuid); },
+      input: (input) => { this.cancelCompact(); parts.activity?.input(input); },
+      queue: (count, oldest) => { parts.activity?.pending(count, oldest); },
+    });
+    this.calls = new RunnerCalls(this.inbox, parts.activity);
+    const { unanswered: again, interrupted, context, tasks } = parts.store.recover();
+    this.recovery = new TaskRecovery(parts.store, this.inbox, tasks, interrupted, (err) => {
+      log.error({ err: errMsg(err) }, 'sdk-runner: task recovery could not be saved');
+      this.parts.activity?.fail(INTERRUPTED_NOTICE);
+      this.close(false);
+    }, Date.now, () => { parts.activity?.recovered(); });
+    this.automation = parts.automationStore === undefined ? null : new Automation(parts.automationStore, this.inbox, (uuid, at) => {
+      if (this.recovery.ledger.snapshot().some((task) => task.id === `input:${uuid}`)) return;
+      this.recovery.ledger.interrupted([{ uuid, at, text: '' }], Date.now());
+      this.recovery.start();
+    }, (err) => {
+      log.error({ err: errMsg(err) }, 'sdk-runner: local automation could not be saved');
+      this.parts.activity?.fail('Local scheduled work could not be saved. Check metro task status before resuming.');
+      this.close(false);
+    });
+    this.watch.restoreContext(context ?? 0);
+    parts.activity?.recover(tasks);
+    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');
+  }
+
+  get id(): string | null { return this.sessionId; }
+
+  start(options: Options): Query {
+    if (this.session !== null) throw new Error('the runner was already started');
+    if (options.resume === undefined) this.watch.restoreContext(0);
+    else this.maybeCompact(true);
+    try {
+      this.session = (this.parts.open ?? query)({ prompt: this.inbox, options: { ...options, stderr: (text) => { if (this.sessionId === null) this.diagnostics.stderr(text); } } });
+    } catch (err) {
+      const failure = this.diagnostics.failure(err);
+      this.diagnostics.clear();
+      throw new SessionError(failure);
+    }
+    this.model = options.model ?? null;
+    this.queueModel(this.model);
+    this.parts.skills?.start({
+      safe: () => !this.ended && this.watch.safe && this.watch.admitting && this.compactAsked === null && !this.calls.live && this.skillWork.safe,
+      reload: () => this.session?.reloadSkills() ?? Promise.reject(new Error('The SDK session is closed.')),
+      wake: () => { this.inbox.notify(); },
+    });
+    this.recovery.start();
+    this.automation?.start();
+    return this.session;
+  }
+
+  switchModel(model: string | null): Promise<void> {
+    this.queueModel(model);
+    return this.switching;
+  }
+
+  async run(observe?: (message: SDKMessage) => void): Promise<void> {
+    if (this.session === null) throw new Error('the runner was not started');
+    try {
+      for await (const message of this.session) {
+        if (this.ended) break;
+        this.cancelCompact();
+        if (message.type === 'system') this.tasks.observe(message);
+        const m: Record<string, unknown> = { ...message };
+        this.recovery.observe(m);
+        this.automation?.observe(m);
+        this.trackInput(m);
+        this.observeWork(m);
+        this.note(m);
+        this.parts.activity?.observe(message);
+        this.inbox.notify();
+        this.maybeCompact();
+        observe?.(message);
+      }
+    } catch (err) {
+      throw new SessionError(this.diagnostics.failure(err));
+    } finally {
+      this.finishRun();
+    }
+  }
+
+  private finishRun(): void {
+    this.diagnostics.clear();
+    this.cancelCompact();
+    this.parts.skills?.close();
+    this.automation?.close(false);
+    this.recovery.close(false);
+    this.ended = true;
+  }
+
+  chat(event: ChannelEvent): Uuid {
+    try {
+      const uuid = this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
+      this.calls.chat(event);
+      return uuid;
+    } 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;
+    }
+  }
+
+  close(cancelActive = false): void {
+    this.cancelCompact();
+    this.parts.skills?.close();
+    this.calls.close();
+    try {
+      this.recovery.close(cancelActive);
+      this.automation?.close(cancelActive);
+    } finally {
+      this.ended = true;
+      this.inbox.close();
+      this.session?.close();
+    }
+  }
+
+  private queueModel(model: string | null): void {
+    this.switching = this.switching
+      .then(() => this.applyModel(model))
+      .catch((err: unknown) => {
+        debugFailure('model switch', err);
+        const failure = new SessionError(this.diagnostics.failure(err));
+        this.parts.activity?.fail(failure);
+        log.warn({ reason: failure.failure.code, diagnostic: failure.failure.diagnostic, summary: failureSummary(failure) }, 'sdk-runner: the session could not take the model the Model page picked');
+      });
+  }
+
+  private async applyModel(model: string | null): Promise<void> {
+    const session = this.session;
+    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);
+    this.model = model;
+    log.info({ was, now: model }, 'sdk-runner: the session thinks with the new model from now on, with no restart');
+  }
+
+  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);
+      this.inbox.boundary();
+      return;
+    }
+    const completed = completedCommand(m);
+    if (completed !== null) { this.inbox.finished([completed]); return; }
+    const started = startedCommand(m);
+    this.inbox.started([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
+    if (visibleOutput(m)) this.inbox.output();
+  }
+
+  private keep(unanswered: Unanswered[]): void { this.parts.store.saveUnanswered(unanswered); }
+
+  private note(m: Record<string, unknown>): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    if (m.type === 'result') this.turnDone(m);
+    if (m.type !== 'system') return;
+    if (m.subtype === 'init') this.started(m);
+    else if (m.subtype === 'compact_boundary') {
+      this.compacted = true;
+      this.compactFloor = null;
+      this.parts.store.saveContext(0);
+      log.info({ compact: m.compact_metadata }, 'sdk-runner: the conversation was compacted');
+    }
+  }
+
+  private turnDone(m: Record<string, unknown>): void {
+    const context = this.watch.context;
+    log.info({ turnMs: m.duration_ms, context, costUsd: m.total_cost_usd, subtype: m.subtype }, 'sdk-runner: turn done');
+    this.parts.store.saveContext(context);
+    if (this.compactAsked !== null && uuidsOf(m)?.includes(this.compactAsked)) {
+      this.compactAsked = null;
+      if (!this.compacted) this.compactFloor = context;
+    }
+    if (this.compacted && context > 0) {
+      this.compactFloor = context;
+      this.compacted = false;
+    }
+  }
+
+  private observeWork(message: Record<string, unknown>): void {
+    this.watch.observe(message);
+    this.skillWork.observe(message);
+    this.parts.skills?.check();
+  }
+
+  private get maintenanceBusy(): boolean {
+    return this.ended || this.parts.skills?.busy === true || this.compactAsked !== null || !this.watch.safe || !this.watch.admitting;
+  }
+
+  private compactReady(resuming = false): boolean {
+    const busy = this.maintenanceBusy || (!resuming && (this.calls.live || this.inbox.pending > 0 || this.tasks.running > 0));
+    return compactDue({ context: this.watch.context, floor: this.compactFloor, limit: this.parts.compactAt ?? COMPACT_AT, busy });
+  }
+
+  private maybeCompact(resuming = false): void {
+    if (!this.compactReady(resuming)) return;
+    if (resuming) { this.askCompact(true); return; }
+    this.compactTimer = setTimeout(() => {
+      this.compactTimer = null;
+      if (this.compactReady()) this.askCompact(false);
+    }, COMPACT_IDLE_MS);
+    this.compactTimer.unref();
+  }
+
+  private askCompact(resuming: boolean): void {
+    this.compactAsked = this.inbox.compact();
+    log.info({ context: this.watch.context, resuming }, 'sdk-runner: compacting at a safe idle boundary');
+  }
+
+  private cancelCompact(): void {
+    if (this.compactTimer !== null) clearTimeout(this.compactTimer);
+    this.compactTimer = null;
+  }
+
+  private started(m: Record<string, unknown>): void {
+    const id = typeof m.session_id === 'string' ? m.session_id : null;
+    if (id === null || id === this.sessionId) return;
+    this.sessionId = id;
+    this.diagnostics.clear();
+    log.info({ session: id, model: m.model, claude: m.claude_code_version }, 'sdk-runner: session up');
+    try {
+      this.parts.store.save(id);
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'sdk-runner: could not keep the session id for the next start');
+    }
+  }
+}

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

@@ -0,0 +1,129 @@
+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, Uuid } from './inbox.js';
+import { recoverInputs } from './recovery.js';
+import { recoveredTasks, savedTasks, type SavedTask } from './task-state.js';
+
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export const projectFolder = (cwd: string): string => cwd.replace(/[^A-Za-z0-9]/g, '-');
+
+interface Stored {
+  sessionId: string | null;
+  unanswered: Unanswered[];
+  interrupted: Unanswered[];
+  context?: number;
+  tasks: SavedTask[];
+}
+
+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.';
+
+function contextOf(raw: unknown): number | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw < 0) throw new Error(UNREADABLE);
+  return raw;
+}
+
+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 context = contextOf(raw.context);
+  return { sessionId: id, unanswered: entries(raw.unanswered), interrupted: entries(raw.interrupted), tasks: savedTasks(raw.tasks), ...(context === undefined ? {} : { context }) };
+}
+
+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 {
+  constructor(
+    private readonly path: string,
+    private readonly claudeDir: string,
+    private readonly cwd: string,
+  ) {}
+
+  resumable(): string | null {
+    const id = this.read().sessionId;
+    if (id === null) return null;
+    return existsSync(join(this.claudeDir, 'projects', projectFolder(this.cwd), `${id}.jsonl`)) ? id : null;
+  }
+
+  unanswered(): Unanswered[] {
+    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, tasks: recoveredTasks(stored.tasks), unanswered: recovered.unanswered, interrupted: [...stored.interrupted, ...recovered.interrupted] };
+    if (stored.unanswered.length > 0 || stored.tasks.some((task) => task.state === 'running')) this.write(next);
+    return next;
+  }
+
+  save(id: string): void {
+    const stored = this.read();
+    if (!SESSION_ID.test(id) || stored.sessionId === id) return;
+    this.write({ ...stored, sessionId: id });
+  }
+
+  saveUnanswered(unanswered: Unanswered[]): void {
+    this.write({ ...this.read(), unanswered });
+  }
+
+  saveContext(context: number): void {
+    const stored = this.read();
+    if (stored.context !== context) this.write({ ...stored, context });
+  }
+
+  interrupted(): Unanswered[] { return this.read().interrupted; }
+
+  saveTasks(tasks: SavedTask[], handled: ReadonlySet<string> = new Set()): void {
+    const stored = this.read();
+    this.write({ ...stored, tasks: savedTasks(tasks), interrupted: stored.interrupted.filter((entry) => !handled.has(`input:${entry.uuid ?? entry.at}`)) });
+  }
+
+  cancelTasks(tasks: SavedTask[], active: ReadonlySet<string>): void {
+    const stored = this.read();
+    const unanswered = stored.unanswered.filter((input) => input.state !== 'started' && (input.uuid === undefined || !active.has(input.uuid)));
+    this.write({ ...stored, tasks: savedTasks(tasks), unanswered, interrupted: [] });
+  }
+
+  private read(): Stored {
+    try {
+      return stored(JSON.parse(readFileSync(this.path, 'utf8')));
+    } catch (err) {
+      if (isRecord(err) && err.code === 'ENOENT') return { sessionId: null, unanswered: [], interrupted: [], tasks: [] };
+      throw new Error(UNREADABLE);
+    }
+  }
+
+  private write(stored: Stored): void {
+    writeAtomic(this.path, `${JSON.stringify({ ...stored, savedAt: new Date().toISOString() }, null, 2)}\n`, 0o600);
+  }
+}

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

@@ -0,0 +1,158 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const METRO_TOOL = /^mcp__metro__(.+)$/;
+
+export const uuidsOf = (m: Record<string, unknown>): string[] | null => {
+  if (Array.isArray(m.user_message_uuids)) return m.user_message_uuids.filter((u): u is string => typeof u === 'string');
+  return typeof m.user_message_uuid === 'string' ? [m.user_message_uuid] : null;
+};
+
+export const startedCommand = (m: Record<string, unknown>): string | null =>
+  m.type === 'command_lifecycle' && m.state === 'started' && typeof m.command_uuid === 'string' ? m.command_uuid : null;
+
+export const completedCommand = (m: Record<string, unknown>): string | null =>
+  m.type === 'command_lifecycle' && m.state === 'completed' && typeof m.command_uuid === 'string' ? m.command_uuid : null;
+
+const num = (value: unknown): number => (typeof value === 'number' ? value : 0);
+
+function contextOf(usage: unknown): number {
+  if (!isRecord(usage)) return 0;
+  return num(usage.input_tokens) + num(usage.cache_read_input_tokens) + num(usage.cache_creation_input_tokens);
+}
+
+function toolResultIds(message: unknown): string[] {
+  if (!isRecord(message) || !Array.isArray(message.content)) return [];
+  return message.content.filter(isRecord).filter((b) => b.type === 'tool_result' && typeof b.tool_use_id === 'string').map((b) => String(b.tool_use_id));
+}
+
+export class SessionWatch {
+  private readonly writes = new Set<string>();
+  private readonly idle: (() => void)[] = [];
+  private readonly compacted: (() => void)[] = [];
+  private compactingNow = false;
+  private busy = false;
+  private sessionStateSeen = false;
+  private requiresAction = false;
+  private awaitingInput: string | null = null;
+  private lastContext = 0;
+  private streamUsage: Record<string, unknown> = {};
+
+  constructor(private readonly readOnly: (tool: string) => boolean) {}
+
+  get compacting(): boolean {
+    return this.compactingNow;
+  }
+
+  get context(): number {
+    return this.lastContext;
+  }
+
+  get writing(): boolean {
+    return this.writes.size > 0;
+  }
+
+  get safe(): boolean { return !this.busy && !this.writing && !this.compacting; }
+
+  get admitting(): boolean {
+    return this.awaitingInput === null && !this.requiresAction && !this.compacting;
+  }
+
+  dispatched(uuid?: string): void {
+    this.busy = true;
+    this.awaitingInput = uuid ?? null;
+  }
+
+  restoreContext(context: number): void { this.lastContext = context; }
+
+  observe(m: Record<string, unknown>): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    this.acknowledge(m);
+    this.lifecycle(m);
+    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);
+  }
+
+  whenNotWriting(): Promise<void> {
+    return this.writing ? new Promise((resolve) => { this.idle.push(resolve); }) : Promise.resolve();
+  }
+
+  whenNotCompacting(): Promise<void> {
+    return this.compactingNow ? new Promise((resolve) => { this.compacted.push(resolve); }) : Promise.resolve();
+  }
+
+  private acknowledge(m: Record<string, unknown>): void {
+    if (this.awaitingInput === null) return;
+    const completed = completedCommand(m) === this.awaitingInput;
+    if (completed || startedCommand(m) === this.awaitingInput || uuidsOf(m)?.includes(this.awaitingInput)) this.awaitingInput = null;
+  }
+
+  private lifecycle(m: Record<string, unknown>): void {
+    if (m.type === 'system') this.system(m);
+    else if (m.type === 'result' && !this.sessionStateSeen) {
+      this.busy = typeof m.queued_turn_count === 'number' && m.queued_turn_count > 0;
+      this.settle();
+    }
+    if (m.type === 'assistant' || m.type === 'stream_event' || startedCommand(m) !== null) this.busy = true;
+  }
+
+  private system(m: Record<string, unknown>): void {
+    if (m.subtype === 'session_state_changed') this.sessionState(m.state);
+    else if (m.subtype === 'status') this.setCompacting(m.status === 'compacting');
+    else if (m.subtype === 'compact_boundary') {
+      this.setCompacting(false);
+      this.lastContext = 0;
+      this.streamUsage = {};
+    }
+  }
+
+  private sessionState(state: unknown): void {
+    this.sessionStateSeen = true;
+    if (state === 'running' || state === 'requires_action') {
+      this.busy = true;
+      this.requiresAction = state === 'requires_action';
+    } else if (state === 'idle') {
+      this.busy = false;
+      this.requiresAction = false;
+      this.settle();
+    }
+  }
+
+  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();
+  }
+
+  private assistant(message: Record<string, unknown>): void {
+    this.lastContext = contextOf(message.usage) || this.lastContext;
+    if (!Array.isArray(message.content)) return;
+    for (const block of message.content.filter(isRecord)) {
+      if (block.type !== 'tool_use' || typeof block.id !== 'string' || typeof block.name !== 'string') continue;
+      const tool = METRO_TOOL.exec(block.name)?.[1];
+      if (tool !== undefined && !this.readOnly(tool)) this.writes.add(block.id);
+    }
+  }
+
+  private done(id: string): void {
+    if (this.writes.delete(id) && this.writes.size === 0) this.wake();
+  }
+
+  private settle(): void {
+    if (this.writes.size === 0) return;
+    this.writes.clear();
+    this.wake();
+  }
+
+  private wake(): void {
+    for (const resume of this.idle.splice(0)) resume();
+  }
+}

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

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:net';
+
+export async function claimRunner(home: string): Promise<() => Promise<void>> {
+  const hash = createHash('sha256').update(home).digest('hex');
+  const server = createServer((socket) => { socket.destroy(); });
+  const address = process.platform === 'linux' ? { path: `\0metro-sdk-${hash}` } : { host: '127.0.0.1', port: 30_000 + parseInt(hash.slice(0, 4), 16) % 30_000 };
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', () => { reject(new Error('The Agent SDK runner is already running, or its local process lock is unavailable.')); });
+    server.listen(address, resolve);
+  });
+  return () => new Promise<void>((resolve, reject) => {
+    server.close((err) => { if (err === undefined) resolve(); else reject(err); });
+  });
+}