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

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

@@ -1,8 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RunnerInput } from '@metro-labs/core/runner-activity';
+import { InputQueue } from './input-queue.js';
+import { InputTiming, type InputWatch } from './input-timing.js';
 
 export type Uuid = ReturnType<typeof randomUUID>;
-export type InputKind = 'chat' | 'call' | 'note';
+export type InputKind = RunnerInput['kind'];
 export type Priority = 'now' | 'next' | 'later';
 
 export interface Unanswered {
@@ -12,32 +15,49 @@ export interface Unanswered {
   state?: 'queued' | 'started';
 }
 
+interface InboxHooks {
+  ready?(): boolean;
+  dispatch?(message: SDKUserMessage): void;
+  queue?(count: number, oldest: number | null): void;
+  input?: InputWatch;
+}
+
 const KINDS_MAX = 2_000;
 const LEDGER_MAX = 100;
 const LEDGER_AGE_MS = 6 * 60 * 60_000;
 
 export class Inbox implements AsyncIterable<SDKUserMessage> {
-  private readonly queue: SDKUserMessage[] = [];
+  private readonly queue = new InputQueue();
   private readonly kinds = new Map<string, InputKind>();
   private readonly ledger = new Map<string, Unanswered>();
+  private readonly timing: InputTiming;
   private wake: (() => void) | null = null;
   private closed = false;
   private restoring = false;
 
-  constructor(private readonly changed: (unanswered: Unanswered[]) => void = () => undefined) {}
+  constructor(private readonly changed: (unanswered: Unanswered[]) => void = () => undefined, private readonly hooks: InboxHooks = {}) {
+    this.timing = new InputTiming(hooks.input ?? (() => undefined));
+  }
 
-  push(kind: InputKind, text: string, priority?: Priority, uuid: Uuid = randomUUID(), at = Date.now()): Uuid {
-    this.mark(uuid, kind);
+  get pending(): number { return this.queue.size; }
+
+  compact(): Uuid {
+    const uuid = this.push('note', '/compact');
+    this.queue.prefer(uuid);
+    return uuid;
+  }
+
+  push(kind: InputKind, text: string, _priority?: Priority, uuid: Uuid = randomUUID(), at = Date.now()): Uuid {
+    if (this.closed) throw new Error('The SDK input queue is closed.');
+    this.queue.check(kind, text);
     if (kind === 'chat') this.remember(uuid, text, at);
-    this.queue.push({
-      type: 'user',
-      message: { role: 'user', content: text },
-      parent_tool_use_id: null,
-      uuid,
-      origin: { kind: 'channel', server: 'metro' },
-      ...(priority === undefined ? {} : { priority }),
-    });
-    this.wake?.();
+    this.mark(uuid, kind);
+    this.queue.push(kind, {
+      type: 'user', message: { role: 'user', content: text }, parent_tool_use_id: null,
+      uuid, origin: { kind: 'channel', server: 'metro' },
+    }, text, at);
+    this.timing.accept(uuid, kind, at);
+    this.notify();
     return uuid;
   }
 
@@ -48,9 +68,7 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
     if (oldest !== undefined) this.kinds.delete(oldest);
   }
 
-  kindOf(uuid: string): InputKind | undefined {
-    return this.kinds.get(uuid);
-  }
+  kindOf(uuid: string): InputKind | undefined { return this.kinds.get(uuid); }
 
   started(uuids: readonly string[]): void {
     let changed = false;
@@ -61,12 +79,24 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
       changed = true;
     }
     if (changed) this.changed(this.unanswered());
+    this.timing.consume(uuids);
   }
 
+  output(): void { this.timing.output(); }
+  boundary(): void { this.timing.boundary(); }
+
   finished(uuids = this.startedUuids()): void {
     let changed = false;
     for (const uuid of uuids) changed = this.ledger.delete(uuid) || changed;
     if (changed) this.changed(this.unanswered());
+    this.timing.finish(uuids);
+  }
+
+  cancel(uuids: readonly string[]): void {
+    const ephemeral = uuids.filter((uuid) => this.kindOf(uuid) !== 'chat');
+    const removed = this.queue.cancel(new Set(ephemeral));
+    this.timing.finish(removed, true);
+    this.notify();
   }
 
   startedUuids(): string[] {
@@ -82,16 +112,22 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
     this.wake?.();
   }
 
+  notify(): void {
+    this.hooks.queue?.(this.queue.size, this.queue.oldest);
+    this.wake?.();
+  }
+
   async *[Symbol.asyncIterator](): AsyncIterator<SDKUserMessage> {
     while (!this.closed) {
-      const next = this.queue.shift();
+      const next = (this.hooks.ready?.() ?? true) ? this.queue.take() : undefined;
       if (next !== undefined) {
+        this.hooks.dispatch?.(next);
+        if (next.uuid !== undefined) this.timing.dispatch(next.uuid);
+        this.notify();
         yield next;
         continue;
       }
-      await new Promise<void>((resolve) => {
-        this.wake = resolve;
-      });
+      await new Promise<void>((resolve) => { this.wake = resolve; });
       this.wake = null;
     }
   }
@@ -108,12 +144,8 @@ export class Inbox implements AsyncIterable<SDKUserMessage> {
   }
 
   private remember(uuid: Uuid, text: string, at: number): void {
+    if (!this.ledger.has(uuid) && this.ledger.size >= LEDGER_MAX) throw new Error('The SDK input queue is full. Wait for queued work to finish before retrying.');
     this.ledger.set(uuid, { text, at, uuid, state: 'queued' });
-    while (this.ledger.size > LEDGER_MAX) {
-      const oldest = [...this.ledger].find(([, entry]) => entry.state !== 'started')?.[0];
-      if (oldest === undefined) break;
-      this.ledger.delete(oldest);
-    }
     if (!this.restoring) this.changed(this.unanswered());
   }
 }

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

@@ -0,0 +1,75 @@
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RunnerInput } from '@metro-labs/core/runner-activity';
+
+type InputKind = RunnerInput['kind'];
+
+const LANES: readonly InputKind[] = ['chat', 'call', 'note'];
+const CAPS: Record<InputKind, number> = { chat: 100, call: 32, note: 16 };
+const BYTES_MAX = 4 * 1024 * 1024;
+const INPUT_MAX = 256 * 1024;
+
+interface Queued {
+  kind: InputKind;
+  message: SDKUserMessage;
+  bytes: number;
+  at: number;
+}
+
+export class InputQueue {
+  private readonly items: Queued[] = [];
+  private bytes = 0;
+  private lane = 0;
+  private first: string | null = null;
+
+  prefer(uuid: string): void { this.first = uuid; }
+
+  get size(): number { return this.items.length; }
+  get oldest(): number | null { return this.items.reduce<number | null>((at, item) => at === null ? item.at : Math.min(at, item.at), null); }
+
+  check(kind: InputKind, text: string): void {
+    const bytes = Buffer.byteLength(text);
+    if (bytes > INPUT_MAX || this.bytes + bytes > BYTES_MAX || this.items.filter((item) => item.kind === kind).length >= CAPS[kind]) {
+      throw new Error('The SDK input queue is full. Wait for queued work to finish before retrying.');
+    }
+  }
+
+  push(kind: InputKind, message: SDKUserMessage, text: string, at: number): void {
+    const bytes = Buffer.byteLength(text);
+    this.items.push({ kind, message, bytes, at });
+    this.bytes += bytes;
+  }
+
+  take(): SDKUserMessage | undefined {
+    if (this.first !== null) {
+      const index = this.items.findIndex((item) => item.message.uuid === this.first);
+      this.first = null;
+      if (index >= 0) return this.remove(index)?.message;
+    }
+    for (let i = 0; i < LANES.length; i += 1) {
+      const lane = (this.lane + i) % LANES.length;
+      const index = this.items.findIndex((item) => item.kind === LANES[lane]);
+      if (index < 0) continue;
+      this.lane = (lane + 1) % LANES.length;
+      return this.remove(index)?.message;
+    }
+    return undefined;
+  }
+
+  cancel(uuids: ReadonlySet<string>): string[] {
+    const removed: string[] = [];
+    for (let index = this.items.length - 1; index >= 0; index -= 1) {
+      const uuid = this.items[index]?.message.uuid;
+      if (uuid !== undefined && uuids.has(uuid)) {
+        this.remove(index);
+        removed.push(uuid);
+      }
+    }
+    return removed;
+  }
+
+  private remove(index: number): Queued | undefined {
+    const [item] = this.items.splice(index, 1);
+    if (item !== undefined) this.bytes -= item.bytes;
+    return item;
+  }
+}

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

@@ -0,0 +1,68 @@
+import type { RunnerInput } from '@metro-labs/core/runner-activity';
+import { log } from '@metro-labs/core/log';
+
+export type InputWatch = (input: RunnerInput) => void;
+
+export class InputTiming {
+  private readonly inputs = new Map<string, RunnerInput>();
+  private readonly active = new Set<string>();
+
+  constructor(private readonly changed: InputWatch) {}
+
+  accept(id: string, kind: RunnerInput['kind'], at: number): void {
+    const input: RunnerInput = { id, kind, state: 'accepted', acceptedAt: at, dispatchedAt: null, consumedAt: null, firstOutputAt: null, completedAt: null };
+    this.inputs.set(id, input);
+    if (this.inputs.size > 2_000) {
+      const oldest = this.inputs.keys().next().value;
+      if (oldest !== undefined) { this.inputs.delete(oldest); this.active.delete(oldest); }
+    }
+    this.note(input);
+  }
+
+  dispatch(id: string): void {
+    const input = this.inputs.get(id);
+    if (input === undefined) return;
+    input.dispatchedAt = Date.now();
+    this.note(input);
+  }
+
+  consume(uuids: readonly string[]): void {
+    for (const id of uuids) {
+      const input = this.inputs.get(id);
+      if (input === undefined || input.consumedAt !== null) continue;
+      input.consumedAt = Date.now();
+      input.state = 'consumed';
+      this.active.add(id);
+      this.note(input);
+    }
+  }
+
+  output(): void {
+    for (const id of this.active) {
+      const input = this.inputs.get(id);
+      if (input === undefined || input.firstOutputAt !== null) continue;
+      input.firstOutputAt = Date.now();
+      input.state = 'output';
+      this.note(input);
+    }
+  }
+
+  finish(uuids: readonly string[], cancelled = false): void {
+    for (const id of uuids) {
+      const input = this.inputs.get(id);
+      if (input === undefined) continue;
+      input.completedAt = Date.now();
+      input.state = cancelled ? 'cancelled' : 'completed';
+      this.inputs.delete(id);
+      this.active.delete(id);
+      this.note(input);
+    }
+  }
+
+  boundary(): void { this.active.clear(); }
+
+  private note(input: RunnerInput): void {
+    this.changed({ ...input });
+    log.info({ input: input.id, kind: input.kind, state: input.state, queueAgeMs: (input.consumedAt ?? Date.now()) - input.acceptedAt }, 'sdk-runner: input lifecycle');
+  }
+}

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

@@ -3,6 +3,7 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 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 { CALL_NOTICE, CALL_STATE, callNotice, callState, type CallNotice, type CallSource, type CallState } from '@metro-labs/core/call';
 import { channelEvent, type ChannelEvent } from './channel-text.js';
 
 const CHANNEL = 'notifications/claude/channel';
@@ -23,10 +24,13 @@ export interface PermissionAsk {
   tool_name: string;
   description: string;
   input_preview: string;
+  call?: CallSource;
 }
 
 export interface LinkEvents {
   channel(event: ChannelEvent): void;
+  call?(notice: CallNotice): void;
+  callState?(state: CallState): void;
   toolsChanged(): void;
   model(model: string | null): void;
   lost(reason: string): void;
@@ -81,14 +85,19 @@ export class MetroLink implements Asker {
   ask(ask: PermissionAsk, signal: AbortSignal): Promise<Behavior> {
     if (signal.aborted) return Promise.resolve('deny');
     return new Promise((resolve) => {
+      const abort = (): void => {
+        settle('deny');
+        this.client.notification({ method: 'notifications/metro/permission_cancel', params: { request_id: ask.request_id } }).catch(() => {
+          log.warn('sdk-runner: could not cancel a pending approval with metro');
+        });
+      };
       const settle = (behavior: Behavior): void => {
-        this.waiting.delete(ask.request_id);
+        signal.removeEventListener('abort', abort);
+        if (!this.waiting.delete(ask.request_id)) return;
         resolve(behavior);
       };
       this.waiting.set(ask.request_id, settle);
-      signal.addEventListener('abort', () => {
-        settle('deny');
-      }, { once: true });
+      signal.addEventListener('abort', abort, { 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');
@@ -106,6 +115,10 @@ export class MetroLink implements Asker {
     if (notification.method === CHANNEL) {
       const event = channelEvent(params);
       if (event !== null) this.events.channel(event);
+    } else if (notification.method === CALL_NOTICE) {
+      this.callNotified(params);
+    } else if (notification.method === CALL_STATE) {
+      this.reconciled(params);
     } else if (notification.method === ANSWER) {
       this.answered(params);
     } else if (notification.method === TOOLS_CHANGED) {
@@ -115,6 +128,16 @@ export class MetroLink implements Asker {
     }
   }
 
+  private callNotified(params: Record<string, unknown>): void {
+    const notice = callNotice(params);
+    if (notice !== null) this.events.call?.(notice);
+  }
+
+  private reconciled(params: Record<string, unknown>): void {
+    const state = callState(params);
+    if (state !== null) this.events.callState?.(state);
+  }
+
   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');

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

@@ -23,10 +23,6 @@ try {
   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)();

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.]`;