@stage-labs/metro 0.1.0-beta.259 → 0.1.0-beta.260

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

@@ -0,0 +1,142 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RunnerEventKind, RunnerTask, RunnerTaskState } from '@metro-labs/core/runner-activity';
+
+export const activityName = (name: unknown): string | null => typeof name === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(name) ? name : null;
+const live = (task: RunnerTask): boolean => ['running', 'pending', 'paused'].includes(task.status);
+const terminal = (status: RunnerTaskState): boolean => ['completed', 'failed', 'stopped'].includes(status);
+type System = Extract<SDKMessage, { type: 'system' }>;
+type Emit = (kind: RunnerEventKind, tool?: string | null, taskId?: string | null) => void;
+
+export class ActivityTasks {
+  private readonly tasks = new Map<string, RunnerTask>();
+  private readonly parents = new Map<string, string>();
+  private readonly hidden = new Map<string, string>();
+  constructor(private readonly emit: Emit) {}
+
+  snapshot(): RunnerTask[] {
+    return [...this.tasks.values()].sort((a, b) => Number(live(b)) - Number(live(a)) || b.updatedAt - a.updatedAt).slice(0, 30).map((task) => ({ ...task }));
+  }
+
+  get running(): number { return [...this.tasks.values()].filter(live).length; }
+  taskFor(parent: string | null | undefined): string | null { return parent ? this.parents.get(parent) ?? null : null; }
+  known(id: string | null | undefined): string | null { return id && this.tasks.has(id) ? id : null; }
+  isHidden(id: string | null): boolean { return id !== null && this.hidden.has(id); }
+  isFinished(id: string): boolean { const task = this.tasks.get(id); return task !== undefined && !live(task); }
+
+  observe(message: System): void {
+    switch (message.subtype) {
+      case 'task_started': this.start(message); break;
+      case 'task_progress': this.progress(message); break;
+      case 'task_updated': this.patch(message); break;
+      case 'task_notification': this.end(message); break;
+      case 'background_tasks_changed': this.replace(message); break;
+      default: break;
+    }
+  }
+
+  stop(): void {
+    for (const task of this.tasks.values()) if (live(task)) this.status(task, 'stopped');
+  }
+
+  private get(id: string): RunnerTask | null {
+    if (!activityName(id) || this.hidden.has(id)) return null;
+    const known = this.tasks.get(id);
+    if (known) return known;
+    if (this.tasks.size >= 200) {
+      const old = [...this.tasks.values()].find((task) => !live(task));
+      if (!old) return null;
+      this.tasks.delete(old.id);
+      for (const [parent, taskId] of this.parents) if (taskId === old.id) this.parents.delete(parent);
+    }
+    const task: RunnerTask = { id, kind: null, agent: null, status: 'unknown', background: false, startedAt: 0, updatedAt: Date.now(), endedAt: null, lastTool: null, toolUses: 0, durationMs: 0 };
+    this.tasks.set(id, task);
+    return task;
+  }
+
+  private hide(id: string, toolUseId?: string): void {
+    this.tasks.delete(id);
+    const parents = [...this.parents].filter(([, task]) => task === id).map(([parent]) => parent);
+    for (const key of [id, toolUseId, ...parents]) {
+      if (key === undefined) continue;
+      const oldest = this.hidden.keys().next();
+      if (this.hidden.size >= 400 && !oldest.done) this.hidden.delete(oldest.value);
+      this.hidden.set(key, id);
+    }
+  }
+
+  private show(id: string): RunnerTask | null {
+    this.hidden.delete(id);
+    const task = this.get(id);
+    if (!task) return null;
+    for (const [key, taskId] of this.hidden) {
+      if (taskId !== id) continue;
+      this.hidden.delete(key);
+      this.parents.set(key, id);
+    }
+    return task;
+  }
+
+  private start(message: Extract<System, { subtype: 'task_started' }>): void {
+    if (message.ambient || message.skip_transcript) { this.hide(message.task_id, message.tool_use_id); return; }
+    const task = this.get(message.task_id);
+    if (!task) return;
+    task.kind = activityName(message.task_type);
+    task.agent = activityName(message.subagent_type);
+    task.background = message.is_backgrounded === true;
+    task.startedAt = Date.now();
+    task.endedAt = null;
+    if (message.tool_use_id) this.parents.set(message.tool_use_id, task.id);
+    this.status(task, 'running');
+  }
+
+  private progress(message: Extract<System, { subtype: 'task_progress' }>): void {
+    const task = this.tasks.get(message.task_id);
+    if (!task || terminal(task.status)) return;
+    task.lastTool = activityName(message.last_tool_name);
+    task.toolUses = message.usage.tool_uses;
+    task.durationMs = message.usage.duration_ms;
+    task.updatedAt = Date.now();
+  }
+
+  private patch(message: Extract<System, { subtype: 'task_updated' }>): void {
+    const task = this.tasks.get(message.task_id);
+    if (!task) return;
+    if (message.patch.is_backgrounded !== undefined) task.background = message.patch.is_backgrounded;
+    if (message.patch.status) this.status(task, message.patch.status === 'killed' ? 'stopped' : message.patch.status);
+    task.updatedAt = Date.now();
+  }
+
+  private end(message: Extract<System, { subtype: 'task_notification' }>): void {
+    if (message.ambient || message.skip_transcript) { this.hide(message.task_id); return; }
+    const task = this.get(message.task_id);
+    if (!task) return;
+    if (message.usage) {
+      task.durationMs = message.usage.duration_ms;
+      task.toolUses = message.usage.tool_uses;
+    }
+    this.status(task, message.status);
+  }
+
+  private replace(message: Extract<System, { subtype: 'background_tasks_changed' }>): void {
+    const ids = new Set(message.tasks.map((task) => task.task_id));
+    for (const task of this.tasks.values()) if (task.background && live(task) && !ids.has(task.id)) this.status(task, 'unknown');
+    for (const row of message.tasks) {
+      if (row.ambient) { this.hide(row.task_id); continue; }
+      const task = this.show(row.task_id);
+      if (!task || terminal(task.status)) continue;
+      task.kind = activityName(row.task_type);
+      task.background = true;
+      this.status(task, 'running');
+    }
+  }
+
+  private status(task: RunnerTask, status: RunnerTaskState): void {
+    const changed = task.status !== status;
+    task.status = status;
+    task.updatedAt = Date.now();
+    task.endedAt = terminal(status) ? task.updatedAt : null;
+    if (!changed) return;
+    const event: Partial<Record<RunnerTaskState, RunnerEventKind>> = { running: 'task_started', completed: 'task_completed', failed: 'task_failed', stopped: 'task_stopped' };
+    this.emit(event[status] ?? 'task_updated', null, task.id);
+  }
+}

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'),
+  };
+}