@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

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

@@ -0,0 +1,130 @@
+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 { 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;
+}
+
+export interface LinkEvents {
+  channel(event: ChannelEvent): 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> {
+    return new Promise((resolve) => {
+      const settle = (behavior: Behavior): void => {
+        this.waiting.delete(ask.request_id);
+        resolve(behavior);
+      };
+      this.waiting.set(ask.request_id, settle);
+      signal.addEventListener('abort', () => {
+        settle('deny');
+      }, { 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 === ANSWER) {
+      this.answered(params);
+    } else if (notification.method === TOOLS_CHANGED) {
+      this.events.toolsChanged();
+    } else if (notification.method === MODEL) {
+      this.events.model(modelIn(params));
+    }
+  }
+
+  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,44 @@
+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';
+
+let agent: RunningAgent | null = null;
+let activity: Activity | null = null;
+
+async function exit(code: number): Promise<never> {
+  await agent?.stop();
+  process.exit(code);
+}
+
+const exitWith = (code: number) => (): void => {
+  exit(code).catch(() => process.exit(code));
+};
+
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, exitWith(0));
+
+try {
+  const cfg = runnerConfig();
+  activity = new Activity(join(dirname(cfg.statePath), 'agent-status.json'));
+  agent = await startAgent(cfg, {
+    activity,
+    speech: {
+      say: (text) => { log.debug({ chars: text.length }, 'sdk-runner: speech'); },
+      done: () => { log.debug('sdk-runner: speech done'); },
+    },
+    lost: () => {
+      activity?.fail('The SDK lost its Metro connection. The session will restart.');
+      exitWith(1)();
+    },
+  });
+  try {
+    await agent.done;
+    activity.fail('The Agent SDK session ended unexpectedly.');
+  } catch (err) {
+    activity.fail(failureSummary(err));
+  }
+} catch (err) {
+  log.error({ reason: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
+}
+await exit(1);

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

@@ -0,0 +1,11 @@
+export const FRONT_RULES = `You are the orchestrator of this agent's Agent SDK chat session. Chat messages (<channel> blocks) and the reports of your background workers arrive in this conversation. Voice calls still use a separate session. Do not claim that chat and calls share context.
+- Be fast. When you can answer a chat message at once, make the reaction and the answer one response of parallel tool calls (react, then send), with no typing signal. Use typing only when the answer will take a while.
+- Stay light: talk, decide and delegate. Real work goes to background workers (Agent tool, subagent_type "worker", run_in_background: true); keep answering while they run, and relay what they report.
+- Text in [square brackets] comes from Metro, not from a person.`;
+
+export const callStarted = (where: string): string =>
+  `[A voice call started: ${where}. Until it ends, the caller's words arrive as <call> blocks, and your plain text answer to a <call> block is spoken aloud: one to three short sentences, no markdown, lists, links or emoji. A <call> block comes first: start your response with the words for the caller, before any tool call, then finish other work, and write no more text in that response unless the caller needs to hear it. Never answer a <call> block with send. Chat messages that arrive during the call keep their usual handling with the metro tools; your text about them is not spoken. When a worker finishes during the call, tell the caller in a sentence or two. Greet the caller now in one short sentence.]`;
+
+export const CALL_ENDED = '[The voice call ended. Nothing about it is posted anywhere unless someone asks.]';
+
+export const callWords = (text: string): string => `<call>${text}</call>`;

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

@@ -0,0 +1,251 @@
+import { randomUUID } from 'node:crypto';
+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 type { Activity } from './activity.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 { CALL_ENDED, callStarted, callWords, FRONT_RULES } from './rules.js';
+import type { SessionStore } from './session-store.js';
+import { SessionWatch, startedCommand, uuidsOf } from './session-watch.js';
+import { SpeechRouter, type SpeechSink } from './speech.js';
+import { METRO_SERVER, type MetroTools } from './tool-proxy.js';
+
+const STARTUP_WAIT = 'CLAUDE_CODE_MCP_STARTUP_WAIT_MS';
+const STALL_MS = 2_000;
+export const COMPACT_AT = 120_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)));
+  return { [STARTUP_WAIT]: '0', ...unpinned, DISABLE_AUTOUPDATER: '1' };
+}
+
+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'],
+    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 }),
+    stderr: (text: string) => {
+      log.debug({ text: text.slice(0, 500) }, 'sdk-runner: claude stderr');
+    },
+  };
+}
+
+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;
+  sink: SpeechSink;
+  readOnly: (tool: string) => boolean;
+  compactAt?: number;
+  open?: OpenSession;
+  activity?: Activity;
+}
+
+export class Runner {
+  readonly inbox: Inbox;
+  private readonly speech: SpeechRouter;
+  private readonly watch: SessionWatch;
+  private session: Query | null = null;
+  private sessionId: string | null = null;
+  private compactAsked = false;
+  private compactFloor: number | null = null;
+  private stall: ReturnType<typeof setTimeout> | null = null;
+  private model: string | null = null;
+  private switching: Promise<void> = Promise.resolve();
+
+  constructor(private readonly parts: RunnerParts) {
+    this.inbox = new Inbox((unanswered) => {
+      this.keep(unanswered);
+    });
+    this.speech = new SpeechRouter((uuid) => this.inbox.kindOf(uuid), {
+      say: (text) => {
+        this.clearStall();
+        parts.sink.say(text);
+      },
+      done: () => {
+        parts.sink.done();
+      },
+    });
+    this.watch = new SessionWatch(parts.readOnly);
+    const again = parts.store.unanswered();
+    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');
+    this.session = (this.parts.open ?? query)({ prompt: this.inbox, options });
+    this.model = options.model ?? null;
+    this.queueModel(this.model);
+    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');
+    for await (const message of this.session) {
+      const m: Record<string, unknown> = { ...message };
+      const started = startedCommand(m);
+      this.inbox.consumed([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
+      this.watch.observe(m);
+      this.speech.observe(message);
+      this.note(m);
+      this.parts.activity?.observe(message);
+      observe?.(message);
+    }
+  }
+
+  chat(event: ChannelEvent): Uuid {
+    return this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
+  }
+
+  callStarted(where: string): Uuid {
+    this.speech.setCallLive(true);
+    return this.callPush(callStarted(where));
+  }
+
+  heard(text: string): Uuid {
+    return this.callPush(callWords(text));
+  }
+
+  callEnded(): Uuid {
+    this.speech.setCallLive(false);
+    this.clearStall();
+    return this.inbox.push('note', CALL_ENDED);
+  }
+
+  close(): void {
+    this.clearStall();
+    this.inbox.close();
+    this.session?.close();
+  }
+
+  private callPush(text: string): Uuid {
+    const uuid = randomUUID();
+    this.inbox.mark(uuid, 'call');
+    this.armStall();
+    if (this.watch.compacting) log.info('sdk-runner: a call message waits for the compaction to finish');
+    this.watch
+      .whenNotCompacting()
+      .then(() => this.watch.whenNotWriting())
+      .then(() => this.inbox.push('call', text, 'now', uuid))
+      .catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'sdk-runner: could not hand a call message to the session');
+      });
+    return uuid;
+  }
+
+  private armStall(): void {
+    this.clearStall();
+    if (this.parts.sink.stalled === undefined) return;
+    this.stall = setTimeout(() => {
+      this.stall = null;
+      if (this.speech.callLive && !this.speech.talking) this.parts.sink.stalled?.();
+    }, STALL_MS);
+    this.stall.unref();
+  }
+
+  private clearStall(): void {
+    if (this.stall !== null) clearTimeout(this.stall);
+    this.stall = null;
+  }
+
+  private queueModel(model: string | null): void {
+    this.switching = this.switching
+      .then(() => this.applyModel(model))
+      .catch((err: unknown) => {
+        this.parts.activity?.fail('The SDK could not apply the selected model. Check the Model page.');
+        log.warn({ model, err: errMsg(err) }, '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 (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 keep(unanswered: Unanswered[]): void {
+    this.parts.activity?.pending(unanswered.length);
+    try {
+      this.parts.store.saveUnanswered(unanswered);
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'sdk-runner: could not keep the unanswered chat messages');
+    }
+  }
+
+  private note(m: Record<string, unknown>): void {
+    if (m.type === 'system' && m.subtype === 'init') this.started(m);
+    else if (m.type === 'result') this.turnDone(m);
+    else if (m.type === 'system' && (m.subtype === 'task_started' || m.subtype === 'task_notification')) log.info({ task: m.task_id, status: m.status ?? 'started' }, `sdk-runner: worker ${m.subtype}`);
+    else if (m.type === 'system' && m.subtype === 'compact_boundary') {
+      this.compactAsked = false;
+      this.compactFloor = null;
+      log.info({ compact: m.compact_metadata }, 'sdk-runner: the conversation was compacted');
+    }
+  }
+
+  private turnDone(m: Record<string, unknown>): void {
+    log.info({ turnMs: m.duration_ms, context: this.watch.context, costUsd: m.total_cost_usd, subtype: m.subtype }, 'sdk-runner: turn done');
+    const limit = this.parts.compactAt ?? COMPACT_AT;
+    const context = this.watch.context;
+    if (context > 0) this.compactFloor ??= context;
+    if (!compactDue({ context, floor: this.compactFloor, limit, busy: this.compactAsked || this.speech.callLive || this.watch.compacting })) return;
+    this.compactAsked = true;
+    log.info({ context: this.watch.context }, 'sdk-runner: compacting while no call is live');
+    this.inbox.push('note', '/compact');
+  }
+
+  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;
+    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,71 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeAtomic } from '@metro-labs/core/secure-fs';
+import type { Unanswered } from './inbox.js';
+
+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[];
+}
+
+const entry = (raw: unknown): Unanswered | null =>
+  isRecord(raw) && typeof raw.text === 'string' && typeof raw.at === 'number' ? { text: raw.text, at: raw.at } : null;
+
+const UNREADABLE = 'The saved Agent SDK state cannot be read. Restore it before starting.';
+
+function stored(raw: unknown): Stored {
+  if (!isRecord(raw)) throw new Error(UNREADABLE);
+  const id = raw.sessionId ?? null;
+  if (id !== null && (typeof id !== 'string' || !SESSION_ID.test(id))) throw new Error(UNREADABLE);
+  const list = raw.unanswered === undefined ? [] : raw.unanswered;
+  if (!Array.isArray(list)) throw new Error(UNREADABLE);
+  const unanswered = list.map(entry);
+  if (!unanswered.every((e): e is Unanswered => e !== null)) throw new Error(UNREADABLE);
+  return { sessionId: id, unanswered };
+}
+
+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;
+  }
+
+  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 });
+  }
+
+  private read(): Stored {
+    try {
+      return stored(JSON.parse(readFileSync(this.path, 'utf8')));
+    } catch (err) {
+      if (isRecord(err) && err.code === 'ENOENT') return { sessionId: null, unanswered: [] };
+      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,111 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const METRO_TOOL = /^mcp__metro__(.+)$/;
+const GATE_CAP_MS = 5_000;
+const COMPACT_CAP_MS = 20_000;
+
+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;
+
+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));
+}
+
+function capped(waiters: (() => void)[], capMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, capMs);
+    waiters.push(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+export class SessionWatch {
+  private readonly writes = new Set<string>();
+  private readonly idle: (() => void)[] = [];
+  private readonly compacted: (() => void)[] = [];
+  private compactingNow = false;
+  private lastContext = 0;
+
+  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;
+  }
+
+  observe(m: Record<string, unknown>): void {
+    if (m.type === 'system') this.system(m);
+    else if (m.type === 'result') this.settle();
+    if (m.parent_tool_use_id !== null) return;
+    if (m.type === 'assistant' && isRecord(m.message)) this.assistant(m.message);
+    else if (m.type === 'user') for (const id of toolResultIds(m.message)) this.done(id);
+  }
+
+  whenNotWriting(capMs = GATE_CAP_MS): Promise<void> {
+    return this.writing ? capped(this.idle, capMs) : Promise.resolve();
+  }
+
+  whenNotCompacting(capMs = COMPACT_CAP_MS): Promise<void> {
+    return this.compactingNow ? capped(this.compacted, capMs) : Promise.resolve();
+  }
+
+  private system(m: Record<string, unknown>): void {
+    if (m.subtype === 'init') this.settle();
+    else if (m.subtype === 'status') this.setCompacting(m.status === 'compacting');
+    else if (m.subtype === 'compact_boundary') {
+      this.setCompacting(false);
+      this.lastContext = 0;
+    }
+  }
+
+  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); });
+  });
+}