@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,37 @@
+import { approvalId } from '@metro-labs/core/ids';
+import type { CallSource } from '@metro-labs/core/call';
+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 interface ApprovalBinding { call: CallSource; signal: AbortSignal }
+export type BindApproval = (tool: string, input: Record<string, unknown>) => ApprovalBinding | null | undefined;
+
+export function approvalsThrough(asker: Asker, waiting: ApprovalWatch = () => undefined, bind: BindApproval = () => undefined): CanUseTool {
+  return async (tool, input, options) => {
+    const binding = bind(tool, input);
+    if (binding === null) return { behavior: 'deny', message: 'This speech target is no longer authorized for the active call.' };
+    const signal = binding === undefined ? options.signal : AbortSignal.any([options.signal, binding.signal]);
+    const id = approvalId();
+    const worker = options.agentID ?? null;
+    log.info({ tool, id, worker }, 'sdk-runner: a tool waits for the owner’s approval');
+    waiting(id, { tool, worker });
+    const behavior = await asker.ask(
+      {
+        request_id: id,
+        tool_name: tool,
+        description: options.description ?? options.title ?? options.decisionReason ?? '',
+        input_preview: JSON.stringify(input),
+        ...(binding === undefined ? {} : { call: binding.call }),
+      },
+      signal,
+    ).finally(() => { waiting(id, null); });
+    log.info({ tool, id, behavior }, 'sdk-runner: the owner answered');
+    return behavior === 'allow' && !signal.aborted ? { behavior, updatedInput: input } : { behavior: 'deny', message: DENIED };
+  };
+}

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

@@ -0,0 +1,10 @@
+import { AutomationStore } from '@metro-labs/core/automation-store';
+import { automationCommandFailure, automationRoot, runAutomationCommand } from './automation-command.js';
+
+try {
+  const result = await runAutomationCommand(process.argv.slice(2), { store: new AutomationStore(automationRoot()) });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+} catch (err) {
+  process.stderr.write(`metro task: ${automationCommandFailure(err)}\n`);
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,151 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { AutomationError, automationRequest, assertRoutine, AUTOMATION_PROMPT_MAX } from '@metro-labs/core/automation-types';
+import type { AutomationRequest } from '@metro-labs/core/automation-types';
+import type { AutomationStore } from '@metro-labs/core/automation-store';
+
+const HOUR_MS = 3_600_000;
+const SLOT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+
+export class AutomationCommandError extends Error {}
+
+export interface AutomationCommandDeps {
+  store: Pick<AutomationStore, 'validate' | 'submit' | 'requests' | 'statuses' | 'finish'>;
+  now?: () => number;
+  readPrompt?: (path: string) => string;
+}
+
+export function automationShellCommand(args: readonly string[], runtime: { executable?: string; entry?: string } = {}): string {
+  const executable = runtime.executable ?? process.execPath;
+  const entry = runtime.entry ?? fileURLToPath(new URL('./automation-cli.ts', import.meta.url));
+  const quoted = [executable, '--no-install', entry, ...args].map((value) => `'${value.replaceAll("'", "'\\''")}'`);
+  return `BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 ${quoted.join(' ')}`;
+}
+
+export function automationRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env.HOME?.trim() ?? '';
+  const state = env.METRO_RUNNER_STATE?.trim() ?? '';
+  const path = state === '' ? join(home === '' ? homedir() : home, '.metro', 'agent-session.json') : state;
+  return join(dirname(path), 'automation');
+}
+
+function regularPromptPath(path: string): string {
+  const full = resolve(path);
+  let at = full;
+  for (;;) {
+    const stat = lstatSync(at);
+    if (stat.isSymbolicLink() || (at !== full && !stat.isDirectory()))
+      throw new AutomationCommandError('prompt file must not use symbolic links');
+    const parent = dirname(at);
+    if (parent === at) return full;
+    at = parent;
+  }
+}
+
+export function readAutomationPrompt(path: string): string {
+  let fd: number | undefined;
+  try {
+    fd = openSync(regularPromptPath(path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > AUTOMATION_PROMPT_MAX)
+      throw new AutomationCommandError('prompt must be a regular UTF-8 file of at most 64 KiB');
+    const buffer = Buffer.alloc(AUTOMATION_PROMPT_MAX + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const read = readSync(fd, buffer, size, buffer.length - size, size);
+      if (read === 0) break;
+      size += read;
+    }
+    if (size > AUTOMATION_PROMPT_MAX)
+      throw new AutomationCommandError('prompt must be a regular UTF-8 file of at most 64 KiB');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size));
+  } catch (err) {
+    if (err instanceof AutomationCommandError) throw err;
+    throw new AutomationCommandError('cannot read prompt as a regular UTF-8 file without symbolic links');
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function slotTime(text: string): number {
+  const slot = Date.parse(text);
+  if (!SLOT_RE.test(text) || !Number.isFinite(slot) || new Date(slot).toISOString() !== text.replace(/:([0-9]{2})Z$/, ':$1.000Z'))
+    throw new AutomationCommandError('--slot must be a valid UTC ISO timestamp ending in Z');
+  return slot;
+}
+
+function submitFlags(flags: string[]): { slot: number | undefined; dryRun: boolean } {
+  let slot: number | undefined;
+  let dryRun = false;
+  for (let i = 0; i < flags.length; i += 1) {
+    const flag = flags[i];
+    const value = flags[i + 1];
+    if (flag === '--dry-run' && !dryRun) dryRun = true;
+    else if (flag === '--slot' && slot === undefined && value !== undefined) {
+      slot = slotTime(value);
+      i += 1;
+    } else throw new AutomationCommandError('invalid or repeated submit option');
+  }
+  return { slot, dryRun };
+}
+
+function submitOptions(args: string[], now: number): { routine: string; path: string; slot: number; dryRun: boolean } {
+  const [routine, path, ...flags] = args;
+  if (routine === undefined || path === undefined || path.startsWith('--'))
+    throw new AutomationCommandError('submit needs <routine> <prompt-file> [--slot <UTC ISO timestamp>] [--dry-run]');
+  assertRoutine(routine);
+  const { slot, dryRun } = submitFlags(flags);
+  return { routine, path, slot: slot ?? Math.floor(now / HOUR_MS) * HOUR_MS, dryRun };
+}
+
+function metadata(request: AutomationRequest): Omit<AutomationRequest, 'prompt' | 'digest'> {
+  return { version: 1, routine: request.routine, slot: request.slot, uuid: request.uuid, createdAt: request.createdAt };
+}
+
+function submitTask(args: string[], deps: AutomationCommandDeps): object {
+  const now = (deps.now ?? Date.now)();
+  const { routine, path, slot, dryRun } = submitOptions(args, now);
+  const prompt = (deps.readPrompt ?? readAutomationPrompt)(path);
+  const request = automationRequest(routine, slot, prompt, now);
+  deps.store.validate();
+  if (dryRun) return { status: 'validated', queued: false, dryRun: true, ...metadata(request) };
+  const saved = deps.store.submit(routine, slot, prompt);
+  const state = deps.store.statuses().find((status) => status.uuid === saved.uuid)?.state ?? 'pending';
+  return { status: 'accepted', queued: state === 'pending', state, ...metadata(saved) };
+}
+
+function taskStatus(args: string[], deps: AutomationCommandDeps): object {
+  if (args.length > 1) throw new AutomationCommandError('status accepts only an optional routine');
+  const routine = args[0];
+  if (routine !== undefined) assertRoutine(routine);
+  deps.store.validate();
+  const statuses = new Map(deps.store.statuses().map((status) => [status.uuid, status]));
+  const tasks = deps.store.requests().filter((request) => routine === undefined || request.routine === routine).map((request) => {
+    const status = statuses.get(request.uuid);
+    return { ...metadata(request), state: status?.state ?? 'pending', token: status?.token ?? null, updatedAt: status?.updatedAt ?? null, ...(status?.detail === undefined ? {} : { detail: status.detail }) };
+  });
+  return { tasks };
+}
+
+function finishTask(args: string[], deps: AutomationCommandDeps): object {
+  const [uuid, token, outcome] = args;
+  if (args.length !== 3 || uuid === undefined || token === undefined || (outcome !== 'completed' && outcome !== 'blocked'))
+    throw new AutomationCommandError('finish needs <uuid> <token> completed|blocked');
+  const receipt = deps.store.finish(uuid, token, outcome);
+  return { status: 'accepted', verification: 'pending', uuid: receipt.uuid, requestedOutcome: receipt.outcome, createdAt: receipt.createdAt };
+}
+
+export async function runAutomationCommand(args: string[], deps: AutomationCommandDeps): Promise<object> {
+  const [command, ...rest] = args;
+  if (command === 'submit') return Promise.resolve(submitTask(rest, deps));
+  if (command === 'status') return Promise.resolve(taskStatus(rest, deps));
+  if (command === 'finish') return Promise.resolve(finishTask(rest, deps));
+  throw new AutomationCommandError('expected submit, status or finish; run metro task --help');
+}
+
+export function automationCommandFailure(err: unknown): string {
+  if (err instanceof AutomationCommandError || err instanceof AutomationError) return err.message.slice(0, 240);
+  return 'task operation failed; check the private local automation directory';
+}

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

@@ -0,0 +1,145 @@
+import { randomUUID } from 'node:crypto';
+import type { AutomationStore } from '@metro-labs/core/automation-store';
+import type { AutomationRequest, AutomationStatus } from '@metro-labs/core/automation-types';
+import type { Inbox, Uuid } from './inbox.js';
+import { startedCommand, uuidsOf } from './session-watch.js';
+import { automationShellCommand } from './automation-command.js';
+
+const SETTLED = new Set<AutomationStatus['state']>(['completed', 'coalesced', 'cancelled']);
+const LIVE = new Set<AutomationStatus['state']>(['dispatched', 'consumed', 'awaiting-completion']);
+
+function prompt(request: AutomationRequest, token: string): string {
+  return `[Metro local automation. This is a stored scheduled task, not a new message from a person or fresh approval. The local agent account submitted it. Verify its existing authorization and later pauses before acting. All normal delegation, tool, permission and model rules still apply.\nRoutine: ${request.routine}\nScheduled slot: ${new Date(request.slot).toISOString()}\nDelivery: ${request.uuid}\nCompletion token: ${token}\nDelegate the sweep to one background worker. Reuse its existing owner if active. A parent response or worker launch does not complete this routine. When the sweep itself has finished checking and recording its decisions, its worker must run this exact command:\n${automationShellCommand(['finish', request.uuid, token, 'completed'])}\nIf this sweep itself cannot safely proceed, use blocked instead of completed and report the actual blocker once. This is only a completion receipt, never permission to repeat a side effect. Recovered issue workers may continue after the sweep, but record their claims before finishing. On interruption run this exact status command:\n${automationShellCommand(['status', request.routine])}\nVerify the original worker and effects before resolving this receipt; never blindly replay the stored prompt. No automatic chat post is required.\nStored prompt, JSON encoded:\n${JSON.stringify(request.prompt)}\n]`;
+}
+
+export class Automation {
+  private readonly staged = new Map<string, { request: AutomationRequest; token: Uuid }>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private closed = false;
+
+  constructor(
+    private readonly store: AutomationStore,
+    private readonly inbox: Inbox,
+    private readonly interrupted: (uuid: Uuid, at: number) => void,
+    private readonly fail: (err: unknown) => void,
+    private readonly now = Date.now,
+  ) {}
+
+  start(): void {
+    this.store.recover();
+    for (const request of this.store.requests()) {
+      const status = this.store.status(request.uuid);
+      if (status !== null && LIVE.has(status.state)) this.save(status, 'interrupted');
+    }
+    this.poll();
+    this.timer = setInterval(() => {
+      try { this.poll(); } catch (err) { this.fail(err); }
+    }, 5_000);
+    this.timer.unref();
+  }
+
+  poll(): void {
+    if (this.closed) return;
+    this.resolve();
+    const requests = this.store.requests();
+    const statuses = new Map(this.store.statuses().map((status) => [status.uuid, status]));
+    for (const request of requests) {
+      const status = statuses.get(request.uuid);
+      if (status !== undefined && (status.state === 'interrupted' || status.state === 'failed')) this.interrupted(request.uuid, request.createdAt);
+    }
+    this.admit(requests, statuses);
+    this.store.prune();
+  }
+
+  dispatched(uuid: string | undefined): void {
+    if (uuid === undefined) return;
+    const item = this.staged.get(uuid);
+    if (item === undefined) return;
+    try {
+      this.store.saveStatus({ uuid: item.request.uuid, token: item.token, state: 'dispatched', updatedAt: this.now() });
+      this.staged.delete(uuid);
+    } catch (err) {
+      this.fail(err);
+      throw err;
+    }
+  }
+
+  observe(m: Record<string, unknown>): void {
+    if (this.closed || (m.parent_tool_use_id !== undefined && m.parent_tool_use_id !== null)) return;
+    const started = startedCommand(m);
+    const ids = new Set([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
+    if (ids.size === 0) return;
+    for (const request of this.store.requests()) {
+      if (!ids.has(request.uuid)) continue;
+      const status = this.store.status(request.uuid);
+      if (status !== null) this.observeStatus(status, m);
+    }
+  }
+
+  private observeStatus(status: AutomationStatus, m: Record<string, unknown>): void {
+    if (!LIVE.has(status.state)) return;
+    if (m.type === 'result') this.save(status, m.is_error !== true && m.subtype === 'success' ? 'awaiting-completion' : 'failed');
+    else if (status.state === 'dispatched') this.save(status, 'consumed');
+  }
+
+  close(cancel = false): void {
+    if (this.closed && !cancel) return;
+    this.closed = true;
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+    if (!cancel) return;
+    this.resolve();
+    for (const request of this.store.requests()) {
+      const status = this.store.status(request.uuid);
+      if (status !== null && LIVE.has(status.state)) this.save(status, 'cancelled');
+    }
+  }
+
+  private save(status: AutomationStatus, state: AutomationStatus['state']): void {
+    this.store.saveStatus({ ...status, state, updatedAt: this.now() });
+  }
+
+  private resolve(): void {
+    const statuses = new Map(this.store.statuses().map((status) => [status.uuid, status]));
+    for (const receipt of this.store.resolutions()) {
+      const status = statuses.get(receipt.uuid);
+      if (status === undefined || status.token !== receipt.token) throw new Error('A local automation completion receipt does not match its dispatched task.');
+      if (SETTLED.has(status.state)) continue;
+      const state = receipt.outcome === 'completed' ? 'completed' : 'failed';
+      if (status.state === state) continue;
+      this.save(status, state);
+      statuses.set(receipt.uuid, { ...status, state });
+    }
+  }
+
+  private admit(requests: AutomationRequest[], statuses: ReadonlyMap<string, AutomationStatus>): void {
+    const routines = new Map<string, AutomationRequest[]>();
+    for (const request of requests) {
+      const list = routines.get(request.routine) ?? [];
+      list.push(request);
+      routines.set(request.routine, list);
+    }
+    for (const list of routines.values()) {
+      if (list.some((request) => this.staged.has(request.uuid))) continue;
+      if (list.some((request) => {
+        const status = statuses.get(request.uuid);
+        return status !== undefined && !SETTLED.has(status.state);
+      })) continue;
+      const latest = this.coalesce(list, statuses);
+      if (latest === null || this.inbox.pending > 0) continue;
+      const token = randomUUID();
+      this.staged.set(latest.uuid, { request: latest, token });
+      this.inbox.automation(prompt(latest, token), latest.uuid, latest.createdAt);
+    }
+  }
+
+  private coalesce(list: AutomationRequest[], statuses: ReadonlyMap<string, AutomationStatus>): AutomationRequest | null {
+    const pending = list.filter((request) => !statuses.has(request.uuid) && request.slot <= this.now()).sort((a, b) => b.slot - a.slot);
+    const latest = pending.shift();
+    if (latest === undefined) return null;
+    const watermark = Math.max(...list.filter((request) => statuses.has(request.uuid)).map((request) => request.slot));
+    if (latest.slot <= watermark) pending.push(latest);
+    for (const request of pending) this.store.saveStatus({ uuid: request.uuid, token: randomUUID(), state: 'coalesced', updatedAt: this.now() });
+    return latest.slot <= watermark ? null : latest;
+  }
+}

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

@@ -0,0 +1,133 @@
+import { sameCall, speechTarget, type CallNotice, type CallRoute, type CallSource } from '@metro-labs/core/call';
+import { log } from '@metro-labs/core/log';
+import type { Activity } from './activity.js';
+import type { ApprovalBinding } from './approvals.js';
+import type { ChannelEvent } from './channel-text.js';
+import type { Inbox } from './inbox.js';
+import { callEnded, callStarted, callWords, speechFailed } from './rules.js';
+
+const GENERATIONS_MAX = 512;
+const SOURCES_MAX = 2_048;
+interface ActiveCall {
+  route: CallRoute;
+  sources: Set<string>;
+  failures: Set<string>;
+  inputs: string[];
+  controller: AbortController;
+}
+
+const routeKey = (route: CallRoute): string => JSON.stringify([route.agentId, route.line, route.from, route.callId, route.generation]);
+
+export class RunnerCalls {
+  private active: ActiveCall | null = null;
+  private readonly seen = new Set<string>();
+
+  constructor(private readonly inbox: Inbox, private readonly activity?: Activity) {}
+
+  get live(): boolean { return this.active !== null; }
+
+  notice(notice: CallNotice): void {
+    if (notice.type === 'started') this.start(notice);
+    else if (this.active !== null && sameCall(notice.route, this.active.route)) {
+      if (notice.type === 'ended') this.end();
+      else if (notice.type === 'heard') this.heard(notice);
+      else this.speech(notice);
+    }
+  }
+
+  reconcile(route: CallRoute | null): void {
+    if (route !== null && this.active !== null && sameCall(route, this.active.route)) return;
+    this.end();
+    if (route !== null) this.activate(route);
+  }
+
+  chat(event: ChannelEvent): void {
+    const active = this.active;
+    if (active === null) return;
+    const { meta } = event;
+    if (meta.line !== active.route.line || meta.from !== active.route.from || meta.call_id !== active.route.callId || meta.call_generation !== active.route.generation) return;
+    if (typeof meta.call_source_id !== 'string' || meta.call_source_id.length === 0 || meta.call_source_id.length > 2048) return;
+    if (active.sources.size < SOURCES_MAX) active.sources.add(meta.call_source_id);
+  }
+
+  approval(tool: string, input: Record<string, unknown>): ApprovalBinding | null | undefined {
+    if (tool !== 'mcp__metro__send' || input.speech === undefined) return undefined;
+    const target = speechTarget(input.speech);
+    const active = this.active;
+    if (active === null || target === null || input.line !== active.route.line || target.callId !== active.route.callId || target.generation !== active.route.generation || !active.sources.has(target.sourceId)) return null;
+    return { call: { route: active.route, sourceId: target.sourceId }, signal: active.controller.signal };
+  }
+
+  close(): void {
+    this.active?.controller.abort();
+    this.active = null;
+  }
+
+  private activate(route: CallRoute): boolean {
+    const key = routeKey(route);
+    if (this.seen.has(key)) return false;
+    this.seen.add(key);
+    if (this.seen.size > GENERATIONS_MAX) {
+      const oldest = this.seen.values().next().value;
+      if (oldest !== undefined) this.seen.delete(oldest);
+    }
+    this.end();
+    this.active = { route, sources: new Set(), failures: new Set(), inputs: [], controller: new AbortController() };
+    this.activity?.call('started');
+    return true;
+  }
+
+  private start(notice: Extract<CallNotice, { type: 'started' }>): void {
+    if (this.activate(notice.route)) this.push(notice, callStarted(notice));
+  }
+
+  private heard(notice: Extract<CallNotice, { type: 'heard' }>): void {
+    if (notice.text.trim() === '') return;
+    this.push(notice, callWords(notice, notice.text));
+  }
+
+  private speech(notice: Extract<CallNotice, { type: 'speech' }>): void {
+    this.activity?.call(notice.status === 'started' ? 'speaking' : notice.status);
+    const active = this.active;
+    if (notice.status !== 'failed' || active === null || !active.sources.has(notice.sourceId)) return;
+    if (active.failures.has(notice.actionId) || active.failures.size >= SOURCES_MAX) return;
+    active.failures.add(notice.actionId);
+    try {
+      this.inbox.push('note', speechFailed(active.route));
+    } catch {
+      log.warn('sdk-runner: speech failure context could not be queued');
+    }
+  }
+
+  private push(source: CallSource, text: string): void {
+    const active = this.active;
+    if (active === null || active.sources.has(source.sourceId) || active.sources.size >= SOURCES_MAX) return;
+    active.sources.add(source.sourceId);
+    this.enqueue(text);
+  }
+
+  private enqueue(text: string): void {
+    const active = this.active;
+    if (active === null) return;
+    try {
+      active.inputs.push(this.inbox.push('call', text));
+    } catch {
+      this.activity?.call('failed');
+      log.warn('sdk-runner: call input queue refused a message');
+    }
+  }
+
+  private end(): void {
+    const active = this.active;
+    if (active === null) return;
+    this.active = null;
+    active.controller.abort();
+    this.inbox.cancel(active.inputs);
+    this.activity?.call('ended');
+    try {
+      this.inbox.push('note', callEnded(active.route));
+    } catch {
+      log.warn('sdk-runner: call end context could not be queued');
+    }
+  }
+}

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