@stage-labs/metro 0.1.0-beta.263 → 0.1.0-beta.265

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

@@ -1,11 +1,25 @@
-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.
+import type { CallRoute, CallSource } from '@metro-labs/core/call';
+
+export const FRONT_RULES = `You are the orchestrator of this agent's persistent Agent SDK session. Typed chat, live call words (<call> blocks), and background worker reports share this conversation.
 - 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.
+- Plain assistant text is never spoken. Reply to a live <call> with mcp__metro__send using its exact line, text, and speech:{callId,generation,sourceId}. This sends speech only, not a chat post. Keep it short. Never paste a spoken reply or transcript into chat unless the owner explicitly requests a chat post.
+- Ordinary typed chat and worker results are never automatically spoken. For an explicit typed owner request to speak, use only that channel message's call_id, call_generation and call_source_id with its exact line as send speech:{callId:call_id,generation:call_generation,sourceId:call_source_id}. Without all three authorized live-call values, do not speak or guess a target. Do not reuse an earlier sourceId for a new reply.
+- A call ending invalidates its speech targets. Keep the chat session and background work running. Nothing is posted about a hangup unless requested. Speech status notifications are status only, never a request to speak.
 - 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.]`;
+const attr = (text: string): string => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+export function callWords(source: CallSource, text: string): string {
+  const { route, sourceId } = source;
+  return `<call line="${attr(route.line)}" from="${attr(route.from)}" callId="${attr(route.callId)}" generation="${attr(route.generation)}" sourceId="${attr(sourceId)}">\n${attr(text)}\n</call>`;
+}
+
+export const callStarted = (source: CallSource): string =>
+  `[A voice call started. Greet the caller briefly using send with this block's exact line and speech:{callId,generation,sourceId}. Do not post the greeting in chat.]\n${callWords(source, '')}`;
 
-export const CALL_ENDED = '[The voice call ended. Nothing about it is posted anywhere unless someone asks.]';
+export const callEnded = (route: CallRoute): string =>
+  `[The voice call ${attr(route.callId)} generation ${attr(route.generation)} ended. Its speech targets are invalid. Keep all other work running. Nothing about it is posted unless requested.]`;
 
-export const callWords = (text: string): string => `<call>${text}</call>`;
+export const speechFailed = (route: CallRoute): string =>
+  `[Speech delivery failed for voice call ${attr(route.callId)} generation ${attr(route.generation)} on ${attr(route.line)}. The full reply was not confirmed. Voice delivery needs attention before another attempt. This is status only: do not retry, speak, or post to chat in response. Keep the chat session and other work running.]`;

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

@@ -1,19 +1,18 @@
-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']);
@@ -62,22 +61,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 +95,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.safe,
+      dispatch: () => { this.watch.dispatched(); },
+      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 +134,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 +146,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 +160,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 +170,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 +201,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 || (!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,14 @@ 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 lastContext = 0;
   private streamUsage: Record<string, unknown> = {};
 
@@ -56,26 +47,42 @@ export class SessionWatch {
     return this.writes.size > 0;
   }
 
+  get safe(): boolean { return !this.busy && !this.writing && !this.compacting; }
+
+  dispatched(): void { this.busy = true; }
+  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.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 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();
-    else if (m.subtype === 'status') this.setCompacting(m.status === 'compacting');
+    if (m.subtype === 'session_state_changed') {
+      this.sessionStateSeen = true;
+      if (m.state === 'running' || m.state === 'requires_action') this.busy = true;
+      else if (m.state === 'idle') { this.busy = false; this.settle(); }
+    } else if (m.subtype === 'status') this.setCompacting(m.status === 'compacting');
     else if (m.subtype === 'compact_boundary') {
       this.setCompacting(false);
       this.lastContext = 0;

package/runtime/stations.json

@@ -36,5 +36,8 @@
     "outlook": {},
     "gmail": {},
     "webhook": {}
+  },
+  "patchedDependencies": {
+    "baileys@7.0.0-rc14": "patches/5bca2c07d5852d3f58453cff0448dd85da13d3665b61e3d758905b298d432d7c.patch"
   }
 }

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