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

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

@@ -0,0 +1,77 @@
+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); }
+
+  accepts(kind: InputKind, text: string): boolean {
+    const bytes = Buffer.byteLength(text);
+    return bytes <= INPUT_MAX && this.bytes + bytes <= BYTES_MAX && this.items.filter((item) => item.kind === kind).length < CAPS[kind];
+  }
+
+  check(kind: InputKind, text: string): void {
+    if (!this.accepts(kind, text)) 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, acceptedAt: input.acceptedAt, dispatchedAt: input.dispatchedAt, consumedAt: input.consumedAt, firstOutputAt: input.firstOutputAt, completedAt: input.completedAt, queueAgeMs: (input.consumedAt ?? Date.now()) - input.acceptedAt }, 'sdk-runner: input lifecycle');
+  }
+}

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

@@ -0,0 +1,154 @@
+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 { 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';
+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: 900 };
+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;
+  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;
+}
+
+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> {
+    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 => {
+        signal.removeEventListener('abort', abort);
+        if (!this.waiting.delete(ask.request_id)) return;
+        resolve(behavior);
+      };
+      this.waiting.set(ask.request_id, settle);
+      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');
+      });
+    });
+  }
+
+  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 === 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) {
+      this.events.toolsChanged();
+    } else if (notification.method === MODEL) {
+      this.events.model(modelIn(params));
+    }
+  }
+
+  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');
+  }
+
+  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,57 @@
+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';
+import { debugFailure, sessionFailure } from './errors.js';
+
+let agent: RunningAgent | null = null;
+let starting: Promise<RunningAgent> | null = null;
+let activity: Activity | null = null;
+let exiting = false;
+let cancelRequested = false;
+
+async function exit(code: number, cancelActive = false): Promise<void> {
+  if (cancelActive && !cancelRequested) {
+    cancelRequested = true;
+    if (exiting && agent !== null) await agent.stop(true);
+  }
+  if (exiting) return;
+  exiting = true;
+  const running = agent ?? await starting?.catch(() => null);
+  await running?.stop(cancelRequested);
+  process.exit(code);
+}
+
+const exitWith = (code: number, cancelActive = false) => (): void => {
+  exit(code, cancelActive).catch(() => process.exit(code));
+};
+
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, exitWith(0));
+process.on('SIGUSR2', exitWith(0, true));
+
+try {
+  const cfg = runnerConfig();
+  activity = new Activity(join(dirname(cfg.statePath), 'agent-status.json'), 'SIGUSR2');
+  starting = startAgent(cfg, {
+    activity,
+    lost: () => {
+      if (exiting) return;
+      activity?.fail('The SDK lost its Metro connection. The session will restart.');
+      exitWith(1)();
+    },
+  });
+  agent = await starting;
+  try {
+    await agent.done;
+    if (!exiting) activity.fail('The Agent SDK session ended unexpectedly.');
+  } catch (err) {
+    debugFailure('session', err);
+    if (!exiting) activity.fail(err);
+  }
+} catch (err) {
+  debugFailure('start', err);
+  const failure = sessionFailure(err);
+  log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
+}
+await exit(1);

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

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, openSync, readSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { Unanswered } from './inbox.js';
+
+export const INTERRUPTED_NOTICE = 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.';
+
+function scanTranscript(fd: number, wanted: ReadonlySet<string>): Set<string> {
+  const found = new Set<string>();
+  const chunk = Buffer.alloc(64 * 1024);
+  let overlap = '';
+  for (let size = readSync(fd, chunk); size > 0; size = readSync(fd, chunk)) {
+    const text = overlap + chunk.toString('latin1', 0, size);
+    for (const uuid of wanted) if (text.includes(`"${uuid}"`)) found.add(uuid);
+    if (found.size === wanted.size) break;
+    overlap = text.slice(-37);
+  }
+  return found;
+}
+
+function transcriptUuids(path: string | null, inputs: readonly Unanswered[]): Set<string> {
+  const wanted = new Set(inputs.flatMap((input) => input.state !== 'started' && input.uuid !== undefined ? [input.uuid] : []));
+  if (path === null || wanted.size === 0) return new Set();
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, 'r');
+    return scanTranscript(fd, wanted);
+  } catch (err) {
+    if (isRecord(err) && err.code === 'ENOENT') return new Set();
+    throw new Error('The saved Agent SDK transcript cannot be checked. Restore it before starting.');
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function recoverInputs(inputs: readonly Unanswered[], transcript: string | null): { unanswered: Unanswered[]; interrupted: Unanswered[] } {
+  const seen = transcriptUuids(transcript, inputs);
+  const unanswered: Unanswered[] = [];
+  const interrupted: Unanswered[] = [];
+  for (const input of inputs) {
+    const entry = { ...input, uuid: input.uuid ?? randomUUID(), state: input.state ?? 'queued' };
+    if (entry.state === 'started' || seen.has(entry.uuid)) interrupted.push({ ...entry, state: 'started' });
+    else unanswered.push(entry);
+  }
+  return { unanswered, interrupted };
+}

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

@@ -0,0 +1,28 @@
+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 and send together), 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.
+- Keep one implementation owner per task. Reuse that owner through the permitted coordination path; avoid chains of relay-only workers and duplicate implementers. Use focused checks while iterating, then the required full gate on the final changes. Reuse verified results only while their inputs are unchanged. A refused lock or an interrupted check is not a pass.
+- At the next safe tool boundary, answer pending live-call inputs before starting unrelated delegation or processing worker reports. Give a short, direct answer when possible; do not generate a long task prompt before replying to the caller. Never interrupt active writes or approvals, invent filler, or promise work is done before it is.
+- 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.
+- Local automation inputs are stored schedules, not new human messages or fresh approval. Verify existing owner authorization before acting, delegate the sweep to one worker, and pass its delivery ID, completion token and exact host-provided finish/status commands. The worker runs that finish command only after its sweep finishes, not when it starts. A successful main response does not finish its worker. Never repeat an uncertain side effect. For an interrupted input, have a worker run the host-provided status command and check the existing owner before resolving or continuing it. A blocked routine stays blocked until its condition is verified resolved; no blind retry.
+- Text in [square brackets] comes from Metro, not from a person.`;
+
+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 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 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.]`;