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

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

@@ -0,0 +1,293 @@
+import { readFileSync } from 'node:fs';
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import type { RunnerActivity, RunnerEventKind, RunnerPhase, RunnerTool } from '@metro-labs/core/runner-activity';
+import { writeAtomic } from '@metro-labs/core/secure-fs';
+import { ActivityTasks, activityName } from './activity-tasks.js';
+import type { ApprovalAsk } from './approvals.js';
+
+const HEARTBEAT_MS = 5_000;
+const MAX_TRACKED = 200;
+const MAX_TOOLS = 20;
+const MAX_EVENTS = 40;
+const STATUS_UNAVAILABLE = 'The SDK status file cannot be written. Check its path and permissions before starting.';
+type System = Extract<SDKMessage, { type: 'system' }>;
+interface TrackedTool extends RunnerTool { parent: string | null }
+interface Approval { tool: string | null; taskId: string | null; worker: boolean }
+
+export function failureSummary(err: unknown): string {
+  const text = err instanceof Error ? err.message : String(err);
+  if (text === STATUS_UNAVAILABLE) return STATUS_UNAVAILABLE;
+  if (/saved Agent SDK state/i.test(text)) return 'The saved Agent SDK state cannot be read. Restore it before starting.';
+  if (/unauthorized|authentication|invalid.*key|401|403/i.test(text)) return 'The provider refused authentication. Check the Model page.';
+  if (/ENOENT|not found|executable|spawn/i.test(text)) return 'The SDK executable could not start. Prepare the SDK runtime again.';
+  if (/ECONN|network|fetch failed|timed? ?out/i.test(text)) return 'The SDK connection failed. Check the server and provider connection.';
+  return 'The Agent SDK session failed. Check Terminal and the Model page.';
+}
+
+function processIdentity(): Pick<RunnerActivity, 'procStart'> {
+  if (process.platform !== 'linux') return {};
+  try {
+    const stat = readFileSync('/proc/self/stat', 'utf8');
+    const start = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    return start && /^\d{1,32}$/.test(start) ? { procStart: start } : {};
+  } catch {
+    log.warn('sdk-runner: process identity is unavailable');
+    return {};
+  }
+}
+
+export class Activity {
+  private readonly tools = new Map<string, TrackedTool>();
+  private readonly tasks = new ActivityTasks((kind, tool, taskId) => { this.taskEvent(kind, tool ?? null, taskId ?? null); });
+  private readonly approvals = new Map<string, Approval>();
+  private busy = false;
+  private failed = false;
+  private compacting = false;
+  private ready = false;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastWritten = '';
+  private writeFailed = false;
+  private readonly state: RunnerActivity = {
+    pid: process.pid, ...processIdentity(), runner: 'sdk', phase: 'starting', mainPhase: 'starting', mainStartedAt: null, sessionId: null, updatedAt: Date.now(),
+    pending: 0, workers: 0, approvals: 0, tools: [], activeTools: [], tasks: [], events: [], lastError: null,
+  };
+
+  constructor(private readonly path: string) {}
+
+  start(): void {
+    this.flush(true);
+    if (this.writeFailed) throw new Error(STATUS_UNAVAILABLE);
+    this.timer = setInterval(() => { this.flush(true); }, HEARTBEAT_MS);
+    this.timer.unref();
+  }
+
+  snapshot(): RunnerActivity {
+    const s = this.state;
+    return {
+      ...s, tools: [...s.tools], activeTools: s.activeTools.map((tool) => ({ ...tool })),
+      tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map((event) => ({ ...event })),
+    };
+  }
+
+  pending(count: number): void {
+    this.state.pending = count;
+    this.update();
+  }
+
+  connected(): void {
+    this.ready = true;
+    this.update();
+  }
+
+  approval(id: string, ask: ApprovalAsk | null): void {
+    if (ask !== null && this.tasks.isHidden(ask.worker)) return;
+    const known = this.approvals.get(id);
+    if (ask !== null && known === undefined) {
+      const entry: Approval = { tool: activityName(ask.tool), taskId: this.tasks.known(ask.worker), worker: ask.worker !== null };
+      this.approvals.set(id, entry);
+      this.event('approval_waiting', entry.tool, entry.taskId);
+    } else if (ask === null && known !== undefined) {
+      this.approvals.delete(id);
+      this.event('approval_ended', known.tool, known.taskId);
+    }
+    this.update();
+  }
+
+  fail(message: string): void {
+    this.failed = true;
+    this.state.lastError = message;
+    this.event('session_failed');
+    this.state.phase = 'error';
+    this.state.mainPhase = 'error';
+    log.error({ reason: message }, 'sdk-runner: activity error');
+    this.flush();
+  }
+
+  stop(): void {
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+    this.tasks.stop();
+    this.tools.clear();
+    this.approvals.clear();
+    this.busy = false;
+    this.state.mainStartedAt = null;
+    this.sync();
+    if (this.state.phase !== 'error') this.state.phase = 'stopped';
+    if (this.state.mainPhase !== 'error') this.state.mainPhase = 'stopped';
+    this.flush(true);
+  }
+
+  observe(message: SDKMessage): void {
+    if (message.type === 'system') this.system(message);
+    else if (message.type === 'result') this.result(message);
+    else if (message.type === 'assistant' || message.type === 'user') this.content(message);
+    else if (message.type === 'stream_event' && message.parent_tool_use_id === null && !this.turnOpen()) this.turn();
+    else return;
+    this.update();
+  }
+
+  private turnOpen(): boolean {
+    return this.busy && this.state.mainStartedAt !== null;
+  }
+
+  private system(message: System): void {
+    switch (message.subtype) {
+      case 'init': this.init(message.session_id); break;
+      case 'status': this.status(message); break;
+      case 'session_state_changed': this.session(message.state); break;
+      case 'api_retry': this.event('api_retry'); break;
+      case 'permission_denied': this.event('permission_denied', activityName(message.tool_name), this.tasks.known(message.agent_id)); break;
+      default: this.tasks.observe(message); this.settle(message); break;
+    }
+  }
+
+  private init(sessionId: string): void {
+    this.state.sessionId = sessionId;
+    this.ready = true;
+    this.turn();
+  }
+
+  private status(message: Extract<System, { subtype: 'status' }>): void {
+    const compacting = message.status === 'compacting';
+    if (compacting && !this.compacting) this.event('compacting');
+    this.compacting = compacting;
+    if (message.compact_result === 'success') this.event('compacted');
+    else if (message.compact_result === 'failed') {
+      this.state.lastError = 'Conversation compaction failed.';
+      this.event('compact_failed');
+    }
+  }
+
+  private session(state: 'idle' | 'running' | 'requires_action'): void {
+    if (state === 'running') this.turn();
+    else if (state === 'idle') {
+      this.busy = false;
+      this.state.mainStartedAt = null;
+    }
+  }
+
+  private turn(): void {
+    this.busy = true;
+    if (this.state.mainStartedAt !== null) return;
+    this.state.mainStartedAt = Date.now();
+    this.event('turn_started');
+  }
+
+  private settle(message: System): void {
+    if (message.subtype === 'task_notification' && message.tool_use_id !== undefined) this.tools.delete(message.tool_use_id);
+    for (const [id, tool] of this.tools) {
+      tool.taskId ??= this.tasks.taskFor(tool.parent);
+      if (this.tasks.isHidden(tool.parent) || this.taskHiddenOrFinished(tool.taskId)) this.tools.delete(id);
+    }
+    for (const [id, approval] of this.approvals) if (this.taskHiddenOrFinished(approval.taskId)) this.approvals.delete(id);
+  }
+
+  private taskHiddenOrFinished(id: string | null): boolean {
+    return id !== null && (this.tasks.isHidden(id) || this.tasks.isFinished(id));
+  }
+
+  private taskEvent(kind: RunnerEventKind, tool: string | null, taskId: string | null): void {
+    if (kind === 'task_failed') this.state.lastError = 'A background task failed. See Conversations and Terminal.';
+    this.event(kind, tool, taskId);
+  }
+
+  private result(message: Extract<SDKMessage, { type: 'result' }>): void {
+    this.busy = (message.queued_turn_count ?? 0) > 0;
+    this.compacting = false;
+    this.state.mainStartedAt = null;
+    for (const [id, tool] of this.tools) if (tool.parent === null) this.tools.delete(id);
+    this.failed = message.is_error || message.subtype !== 'success';
+    if (!this.failed) {
+      this.event('turn_finished');
+      return;
+    }
+    const code = message.subtype === 'success' ? 'provider_error' : message.subtype;
+    this.state.lastError = `SDK turn failed (${code}). Check Conversations and the Model page.`;
+    this.event('turn_failed');
+    log.error({ reason: code }, 'sdk-runner: turn failed');
+  }
+
+  private content(message: Extract<SDKMessage, { type: 'assistant' | 'user' }>): void {
+    const content = message.message.content;
+    const parent = message.parent_tool_use_id ?? null;
+    if (Array.isArray(content)) for (const block of content) if (isRecord(block)) this.block(block, parent);
+    if (parent === null && message.type === 'assistant') this.turn();
+  }
+
+  private block(block: Record<string, unknown>, parent: string | null): void {
+    if (block.type === 'tool_use' && typeof block.id === 'string') this.tool(block.id, block.name, parent);
+    else if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') this.finish(block.tool_use_id, block.is_error === true, parent);
+  }
+
+  private tool(id: string, rawName: unknown, parent: string | null): void {
+    if (this.tools.has(id) || this.tools.size >= MAX_TRACKED) return;
+    if (this.tasks.isHidden(parent)) return;
+    const name = activityName(rawName) ?? 'tool';
+    const taskId = this.tasks.taskFor(parent);
+    this.tools.set(id, { id, name, taskId, startedAt: Date.now(), parent });
+    if (parent === null) this.event('tool_started', name);
+    log.info({ tool: name, worker: taskId }, 'sdk-runner: tool started');
+  }
+
+  private finish(id: string, failed: boolean, parent: string | null): void {
+    const tool = this.tools.get(id);
+    if (tool === undefined && this.tasks.isHidden(parent)) return;
+    this.tools.delete(id);
+    const name = tool?.name ?? 'tool';
+    if (failed) {
+      this.state.lastError = `${name} failed. See its result in Conversations.`;
+      this.event('tool_failed', name, tool?.taskId ?? null);
+      log.warn({ tool: name }, 'sdk-runner: tool failed');
+      return;
+    }
+    if (tool?.parent === null) this.event('tool_finished', name);
+    log.info({ tool: name }, 'sdk-runner: tool finished');
+  }
+
+  private event(kind: RunnerEventKind, tool: string | null = null, taskId: string | null = null): void {
+    this.state.events.unshift({ at: Date.now(), kind, tool, taskId });
+    if (this.state.events.length > MAX_EVENTS) this.state.events.length = MAX_EVENTS;
+  }
+
+  private phaseOf(approval: boolean, working: boolean): RunnerPhase {
+    if (!this.ready) return 'starting';
+    if (this.compacting) return 'compacting';
+    if (approval) return 'approval';
+    if (working) return 'working';
+    return this.failed ? 'error' : 'idle';
+  }
+
+  private sync(): void {
+    const tools = [...this.tools.values()];
+    this.state.tools = [...new Set(tools.map((tool) => tool.name))].slice(0, MAX_TOOLS);
+    this.state.activeTools = tools.slice(0, MAX_TOOLS).map(({ id, name, taskId, startedAt, parent }) => ({ id, name, taskId, startedAt, worker: parent !== null }));
+    this.state.tasks = this.tasks.snapshot();
+    this.state.workers = this.tasks.running;
+    this.state.approvals = this.approvals.size;
+  }
+
+  private update(): void {
+    this.sync();
+    const main = this.busy || this.state.pending > 0;
+    const approvals = [...this.approvals.values()];
+    this.state.mainPhase = this.phaseOf(approvals.some((approval) => !approval.worker), main || [...this.tools.values()].some((tool) => tool.parent === null));
+    this.state.phase = this.phaseOf(approvals.length > 0, main || this.tools.size > 0 || this.state.workers > 0);
+    this.flush();
+  }
+
+  private flush(force = false): void {
+    const next = JSON.stringify({ ...this.state, updatedAt: 0 });
+    if (!force && next === this.lastWritten) return;
+    this.state.updatedAt = Date.now();
+    try {
+      writeAtomic(this.path, `${JSON.stringify(this.state)}\n`, 0o600);
+      this.lastWritten = next;
+      this.writeFailed = false;
+    } catch {
+      if (!this.writeFailed) log.error('sdk-runner: could not save activity status');
+      this.writeFailed = true;
+    }
+  }
+}

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

@@ -0,0 +1,77 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { errMsg, log } from '@metro-labs/core/log';
+import { failureSummary, type Activity } from './activity.js';
+import { approvalsThrough } from './approvals.js';
+import type { RunnerConfig } from './config.js';
+import { MetroLink } from './link.js';
+import { Runner, runnerOptions } from './runner.js';
+import { SessionStore } from './session-store.js';
+import { claimRunner } from './singleton.js';
+import type { SpeechSink } from './speech.js';
+import { metroTools, type MetroTools } from './tool-proxy.js';
+
+export interface RunningAgent {
+  runner: Runner;
+  link: MetroLink;
+  done: Promise<void>;
+  stop(): Promise<void>;
+}
+
+export interface AppHooks {
+  speech: SpeechSink;
+  lost(reason: string): void;
+  observe?: (message: SDKMessage) => void;
+  env?: NodeJS.ProcessEnv;
+  compactAt?: number;
+  activity?: Activity;
+}
+
+async function connected(cfg: RunnerConfig, hooks: AppHooks, release: () => Promise<void>): Promise<RunningAgent> {
+  const store = new SessionStore(cfg.statePath, cfg.claudeDir, cfg.cwd);
+  let tools: MetroTools | null = null;
+  const runner = new Runner({ store, sink: hooks.speech, readOnly: (tool) => tools?.readOnly(tool) ?? false, ...hooks });
+  const link = await MetroLink.open(cfg.mcpUrl, cfg.key, {
+    channel: (event) => { runner.chat(event); },
+    toolsChanged: () => { tools?.changed(); },
+    model: (model) => {
+      log.info({ model }, 'sdk-runner: the Model page picked a model');
+      runner.switchModel(model).catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'sdk-runner: could not switch the model');
+      });
+    },
+    lost: (reason) => { hooks.lost(reason); },
+  });
+  let stopped = false;
+  const stop = async (): Promise<void> => {
+    if (stopped) return;
+    stopped = true;
+    runner.close();
+    await link.close().catch(() => { log.debug('sdk-runner: closing the metro link failed'); });
+    hooks.activity?.stop();
+    await release();
+  };
+  try {
+    tools = metroTools(link);
+    const resume = store.resumable();
+    log.info({ resume, model: cfg.model, mode: cfg.permissionMode }, 'sdk-runner: starting the Agent SDK session');
+    runner.start(runnerOptions(cfg, tools, approvalsThrough(link, (id, ask) => { hooks.activity?.approval(id, ask); }), resume, hooks.env));
+    return { runner, link, done: runner.run(hooks.observe), stop };
+  } catch (err) {
+    runner.close();
+    await link.close().catch(() => { log.debug('sdk-runner: closing the metro link failed'); });
+    throw err;
+  }
+}
+
+export async function startAgent(cfg: RunnerConfig, hooks: AppHooks): Promise<RunningAgent> {
+  const release = await claimRunner(cfg.cwd);
+  try {
+    hooks.activity?.start();
+    return await connected(cfg, hooks, release);
+  } catch (err) {
+    hooks.activity?.fail(failureSummary(err));
+    hooks.activity?.stop();
+    await release().catch(() => { log.warn('sdk-runner: releasing process ownership failed'); });
+    throw err;
+  }
+}

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

@@ -0,0 +1,28 @@
+import { approvalId } from '@metro-labs/core/ids';
+import type { CanUseTool } from '@anthropic-ai/claude-agent-sdk';
+import { log } from '@metro-labs/core/log';
+import type { Asker } from './link.js';
+
+const DENIED = 'The owner did not approve this.';
+
+export interface ApprovalAsk { tool: string; worker: string | null }
+export type ApprovalWatch = (id: string, ask: ApprovalAsk | null) => void;
+
+export function approvalsThrough(asker: Asker, waiting: ApprovalWatch = () => undefined): CanUseTool {
+  return async (tool, input, options) => {
+    const id = approvalId();
+    log.info({ tool, id, worker: options.agentID ?? null }, 'sdk-runner: a tool waits for the owner’s approval');
+    waiting(id, { tool, worker: options.agentID ?? null });
+    const behavior = await asker.ask(
+      {
+        request_id: id,
+        tool_name: tool,
+        description: options.description ?? options.title ?? options.decisionReason ?? '',
+        input_preview: JSON.stringify(input),
+      },
+      options.signal,
+    ).finally(() => { waiting(id, null); });
+    log.info({ tool, id, behavior }, 'sdk-runner: the owner answered');
+    return behavior === 'allow' ? { behavior, updatedInput: input } : { behavior, message: DENIED };
+  };
+}

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

@@ -0,0 +1,26 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const KEY = /^[A-Za-z0-9_]+$/;
+
+const attr = (value: string): string => value.replace(/&/g, '&').replace(/"/g, '"');
+
+const shown = (value: unknown): value is string | number | boolean =>
+  typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+
+export function channelText(source: string, content: string, meta: Record<string, unknown>): string {
+  const attrs = Object.entries(meta)
+    .filter((entry): entry is [string, string | number | boolean] => KEY.test(entry[0]) && shown(entry[1]))
+    .map(([key, value]) => ` ${key}="${attr(String(value))}"`)
+    .join('');
+  return `<channel source="${attr(source)}"${attrs}>\n${content}\n</channel>`;
+}
+
+export interface ChannelEvent {
+  content: string;
+  meta: Record<string, unknown>;
+}
+
+export function channelEvent(params: unknown): ChannelEvent | null {
+  if (!isRecord(params) || typeof params.content !== 'string') return null;
+  return { content: params.content, meta: isRecord(params.meta) ? params.meta : {} };
+}

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

@@ -0,0 +1,50 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { PermissionMode } from '@anthropic-ai/claude-agent-sdk';
+
+export interface RunnerConfig {
+  mcpUrl: string;
+  key: string;
+  cwd: string;
+  claude: string | null;
+  model: string | null;
+  permissionMode: PermissionMode;
+  prompt: string | null;
+  statePath: string;
+  claudeDir: string;
+}
+
+const given = (value: string | undefined): string | null => {
+  const trimmed = value?.trim() ?? '';
+  return trimmed === '' ? null : trimmed;
+};
+
+function required(env: NodeJS.ProcessEnv, name: string): string {
+  const value = given(env[name]);
+  if (value === null) throw new Error(`${name} is not set; start the runner with metro agent`);
+  return value;
+}
+
+function realDir(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+export function runnerConfig(env: NodeJS.ProcessEnv = process.env, cwd = process.cwd()): RunnerConfig {
+  const home = given(env.HOME) ?? homedir();
+  return {
+    mcpUrl: required(env, 'METRO_RUNNER_MCP_URL'),
+    key: required(env, 'METRO_AGENT_KEY'),
+    cwd: realDir(cwd),
+    claude: given(env.METRO_RUNNER_CLAUDE),
+    model: given(env.METRO_RUNNER_MODEL),
+    permissionMode: env.METRO_RUNNER_PERMISSION_MODE === 'bypass' ? 'bypassPermissions' : 'auto',
+    prompt: given(env.METRO_RUNNER_PROMPT),
+    statePath: given(env.METRO_RUNNER_STATE) ?? join(home, '.metro', 'agent-session.json'),
+    claudeDir: given(env.CLAUDE_CONFIG_DIR) ?? join(home, '.claude'),
+  };
+}

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

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+
+export type Uuid = ReturnType<typeof randomUUID>;
+export type InputKind = 'chat' | 'call' | 'note';
+export type Priority = 'now' | 'next' | 'later';
+
+export interface Unanswered {
+  text: string;
+  at: number;
+}
+
+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 kinds = new Map<string, InputKind>();
+  private readonly ledger = new Map<string, Unanswered>();
+  private wake: (() => void) | null = null;
+  private closed = false;
+
+  constructor(private readonly changed: (unanswered: Unanswered[]) => void = () => undefined) {}
+
+  push(kind: InputKind, text: string, priority?: Priority, uuid: Uuid = randomUUID(), at = Date.now()): Uuid {
+    this.mark(uuid, kind);
+    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?.();
+    return uuid;
+  }
+
+  mark(uuid: string, kind: InputKind): void {
+    this.kinds.set(uuid, kind);
+    if (this.kinds.size <= KINDS_MAX) return;
+    const oldest = this.kinds.keys().next().value;
+    if (oldest !== undefined) this.kinds.delete(oldest);
+  }
+
+  kindOf(uuid: string): InputKind | undefined {
+    return this.kinds.get(uuid);
+  }
+
+  consumed(uuids: readonly string[]): void {
+    let changed = false;
+    for (const uuid of uuids) changed = this.ledger.delete(uuid) || changed;
+    if (changed) this.changed(this.unanswered());
+  }
+
+  unanswered(now = Date.now()): Unanswered[] {
+    return [...this.ledger.values()].filter((entry) => now - entry.at < LEDGER_AGE_MS);
+  }
+
+  close(): void {
+    this.closed = true;
+    this.wake?.();
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<SDKUserMessage> {
+    while (!this.closed) {
+      const next = this.queue.shift();
+      if (next !== undefined) {
+        yield next;
+        continue;
+      }
+      await new Promise<void>((resolve) => {
+        this.wake = resolve;
+      });
+      this.wake = null;
+    }
+  }
+
+  again(left: readonly Unanswered[]): void {
+    for (const entry of left) this.push('chat', entry.text, undefined, randomUUID(), entry.at);
+  }
+
+  private remember(uuid: string, text: string, at: number): void {
+    this.ledger.set(uuid, { text, at });
+    while (this.ledger.size > LEDGER_MAX) {
+      const oldest = this.ledger.keys().next().value;
+      if (oldest === undefined) break;
+      this.ledger.delete(oldest);
+    }
+    this.changed(this.unanswered());
+  }
+}