@stage-labs/metro 0.1.0-beta.264 → 0.1.0-beta.266

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

@@ -1,26 +1,27 @@
-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 { isRecord } from '@metro-labs/core/is-record';
 import type { Activity } from './activity.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 { CALL_ENDED, callStarted, callWords, FRONT_RULES } from './rules.js';
+import { FRONT_RULES } from './rules.js';
 import { INTERRUPTED_NOTICE } from './recovery.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' };
+  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];
@@ -62,22 +63,33 @@ export type OpenSession = (params: { prompt: AsyncIterable<SDKUserMessage>; opti
 
 export interface RunnerParts {
   store: SessionStore;
-  sink: SpeechSink;
   readOnly: (tool: string) => boolean;
   compactAt?: number;
   open?: OpenSession;
   activity?: Activity;
 }
 
+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;
-  private readonly speech: SpeechRouter;
+  readonly calls: RunnerCalls;
   private readonly watch: SessionWatch;
   private session: Query | null = null;
   private sessionId: string | null = null;
-  private compactAsked = false;
+  private compactAsked: Uuid | null = null;
   private compactFloor: number | null = null;
-  private stall: ReturnType<typeof setTimeout> | null = null;
+  private compacted = false;
   private model: string | null = null;
   private switching: Promise<void> = Promise.resolve();
   private ended = false;
@@ -85,31 +97,27 @@ export class Runner {
   private interruptionReported = false;
 
   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 { unanswered: again, interrupted } = parts.store.recover();
+    this.inbox = new Inbox((unanswered) => { this.keep(unanswered); }, {
+      ready: () => this.watch.admitting,
+      dispatch: (message) => { this.watch.dispatched(message.uuid); },
+      input: (input) => { 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 } = parts.store.recover();
+    this.watch.restoreContext(context ?? 0);
     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;
-  }
+  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);
     this.session = (this.parts.open ?? query)({ prompt: this.inbox, options });
     this.model = options.model ?? null;
     this.queueModel(this.model);
@@ -128,9 +136,9 @@ export class Runner {
         const m: Record<string, unknown> = { ...message };
         this.trackInput(m);
         this.watch.observe(m);
-        this.speech.observe(message);
         this.note(m);
         this.parts.activity?.observe(message);
+        this.inbox.notify();
         observe?.(message);
       }
     } finally {
@@ -140,7 +148,9 @@ export class Runner {
 
   chat(event: ChannelEvent): Uuid {
     try {
-      return this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
+      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 {
@@ -152,23 +162,8 @@ export class Runner {
     }
   }
 
-  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(cancelActive = true): void {
-    this.clearStall();
+    this.calls.close();
     try {
       if (cancelActive && !this.ended) this.inbox.finished();
     } finally {
@@ -177,36 +172,6 @@ export class Runner {
     }
   }
 
-  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))
@@ -238,37 +203,50 @@ export class Runner {
     if (m.type === 'result') {
       const uuids = uuidsOf(m);
       if (uuids !== null) this.inbox.finished(uuids);
+      this.inbox.boundary();
       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);
-    this.parts.activity?.pending(unanswered.filter((entry) => entry.state !== 'started').length);
-  }
+  private keep(unanswered: Unanswered[]): void { this.parts.store.saveUnanswered(unanswered); }
 
   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;
+    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 === 'session_state_changed' && m.state === 'idle') this.maybeCompact();
+    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 {
-    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');
+    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;
+    }
+    this.maybeCompact();
+  }
+
+  private maybeCompact(resuming = false): void {
+    const busy = this.compactAsked !== null || !this.watch.safe || !this.watch.admitting || (!resuming && (this.calls.live || this.inbox.pending > 0));
+    if (!compactDue({ context: this.watch.context, floor: this.compactFloor, limit: this.parts.compactAt ?? COMPACT_AT, busy })) return;
+    this.compactAsked = this.inbox.compact();
+    log.info({ context: this.watch.context, resuming }, 'sdk-runner: compacting at a safe idle boundary');
   }
 
   private started(m: Record<string, unknown>): void {

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

@@ -13,6 +13,7 @@ interface Stored {
   sessionId: string | null;
   unanswered: Unanswered[];
   interrupted: Unanswered[];
+  context?: number;
 }
 
 function inputId(raw: unknown): Uuid | undefined {
@@ -35,11 +36,18 @@ function entry(raw: unknown): Unanswered | null {
 
 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);
-  return { sessionId: id, unanswered: entries(raw.unanswered), interrupted: entries(raw.interrupted) };
+  const context = contextOf(raw.context);
+  return { sessionId: id, unanswered: entries(raw.unanswered), interrupted: entries(raw.interrupted), ...(context === undefined ? {} : { context }) };
 }
 
 function entries(raw: unknown): Unanswered[] {
@@ -86,6 +94,11 @@ export class SessionStore {
     this.write({ ...this.read(), unanswered });
   }
 
+  saveContext(context: number): void {
+    const stored = this.read();
+    if (stored.context !== context) this.write({ ...stored, context });
+  }
+
   private read(): Stored {
     try {
       return stored(JSON.parse(readFileSync(this.path, 'utf8')));

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

@@ -1,8 +1,6 @@
 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');
@@ -24,21 +22,15 @@ function toolResultIds(message: unknown): string[] {
   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 busy = false;
+  private sessionStateSeen = false;
+  private requiresAction = false;
+  private awaitingInput: string | null = null;
   private lastContext = 0;
   private streamUsage: Record<string, unknown> = {};
 
@@ -56,25 +48,52 @@ export class SessionWatch {
     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.type === 'system') this.system(m);
-    else if (m.type === 'result') this.settle();
-    if (m.parent_tool_use_id !== null) return;
+    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(capMs = GATE_CAP_MS): Promise<void> {
-    return this.writing ? capped(this.idle, capMs) : Promise.resolve();
+  whenNotWriting(): Promise<void> {
+    return this.writing ? new Promise((resolve) => { this.idle.push(resolve); }) : Promise.resolve();
   }
 
-  whenNotCompacting(capMs = COMPACT_CAP_MS): Promise<void> {
-    return this.compactingNow ? capped(this.compacted, capMs) : 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;
+    if (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 === 'init') this.settle();
+    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);
@@ -83,6 +102,18 @@ export class SessionWatch {
     }
   }
 
+  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 : {};

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

@@ -1,79 +0,0 @@
-import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
-import { isRecord } from '@metro-labs/core/is-record';
-import type { InputKind } from './inbox.js';
-import { startedCommand, uuidsOf } from './session-watch.js';
-
-export interface SpeechSink {
-  say(text: string): void;
-  done(): void;
-  stalled?(): void;
-}
-
-
-function textDelta(event: unknown): string | null {
-  if (!isRecord(event) || event.type !== 'content_block_delta' || !isRecord(event.delta)) return null;
-  return event.delta.type === 'text_delta' && typeof event.delta.text === 'string' ? event.delta.text : null;
-}
-
-export class SpeechRouter {
-  private answering: string[] = [];
-  private speaking = false;
-  private live = false;
-
-  constructor(
-    private readonly kindOf: (uuid: string) => InputKind | undefined,
-    private readonly sink: SpeechSink,
-  ) {}
-
-  get callLive(): boolean {
-    return this.live;
-  }
-
-  get talking(): boolean {
-    return this.speaking;
-  }
-
-  setCallLive(on: boolean): void {
-    this.live = on;
-    if (!on) this.endTurn();
-  }
-
-  observe(message: SDKMessage): void {
-    const m: Record<string, unknown> = { ...message };
-    if (m.type === 'result') {
-      this.endTurn();
-      this.answering = [];
-      return;
-    }
-    if (m.type === 'system' && m.subtype === 'init') this.endTurn();
-    const started = startedCommand(m);
-    if (started !== null) this.answer([started]);
-    if (m.parent_tool_use_id === null) this.mainThread(m);
-  }
-
-  private answer(uuids: readonly string[]): void {
-    this.answering = [...new Set([...this.answering, ...uuids])];
-  }
-
-  private mainThread(m: Record<string, unknown>): void {
-    if (m.type !== 'stream_event' && m.type !== 'assistant') return;
-    const uuids = uuidsOf(m);
-    if (uuids !== null) this.answer(uuids);
-    const text = m.type === 'stream_event' ? textDelta(m.event) : null;
-    if (text === null || text === '' || !this.speaks()) return;
-    this.speaking = true;
-    this.sink.say(text);
-  }
-
-  private speaks(): boolean {
-    if (!this.live) return false;
-    if (this.answering.length === 0) return true;
-    return this.answering.some((uuid) => this.kindOf(uuid) === 'call');
-  }
-
-  private endTurn(): void {
-    if (!this.speaking) return;
-    this.speaking = false;
-    this.sink.done();
-  }
-}