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

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

@@ -0,0 +1,392 @@
+import { randomUUID } from 'node:crypto';
+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 { runnerFailureSummary, type RunnerActivity, type RunnerDiagnostic, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerInput, type RunnerPhase, type 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';
+import { sdkTask, type SavedTask } from './task-state.js';
+import { sessionFailure } from './errors.js';
+export { failureSummary } from './errors.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 }
+
+function copyEvent<T extends RunnerEvent>(event: T): T {
+  return { ...event, ...(event.diagnostic === undefined ? {} : { diagnostic: { ...event.diagnostic } }) };
+}
+
+const PROVIDER_ERRORS: Record<NonNullable<Extract<SDKMessage, { type: 'assistant' }>['error']>, RunnerFailureCode> = {
+  authentication_failed: 'authentication', oauth_org_not_allowed: 'authentication', cloud_credential_error: 'authentication', account_on_hold: 'authentication', verification_required: 'authentication',
+  billing_error: 'billing', rate_limit: 'rate_limit', overloaded: 'provider_unavailable', server_error: 'provider_unavailable',
+  max_output_tokens: 'output_limit', invalid_request: 'invalid_request', model_not_found: 'invalid_request', unknown: 'provider_error',
+};
+
+function providerFailure(status: number | null | undefined): RunnerFailureCode {
+  const codes: Record<number, RunnerFailureCode | undefined> = { 400: 'invalid_request', 401: 'authentication', 402: 'billing', 403: 'authentication', 404: 'invalid_request', 429: 'rate_limit' };
+  if (status === null || status === undefined) return 'provider_error';
+  return codes[status] ?? (status >= 500 && status <= 599 ? 'provider_unavailable' : 'provider_error');
+}
+
+function readTokenLimit(content: unknown): boolean {
+  if (typeof content === 'string') return /File content \([\d,]+ tokens\) exceeds maximum allowed tokens \([\d,]+\)/.test(content.slice(0, 2_048));
+  return Array.isArray(content) && content.slice(0, 8).some((block: unknown) => isRecord(block) && block.type === 'text' && typeof block.text === 'string' && readTokenLimit(block.text));
+}
+
+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 providerCode: RunnerFailureCode | null = null;
+  private readonly workerErrors = new Map<string, RunnerFailureCode>();
+  private interrupted: RunnerFailure | null = null;
+  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, activeFailure: null, lastFailure: null,
+  };
+
+  constructor(private readonly path: string, cancelSignal?: RunnerActivity['cancelSignal']) {
+    if (cancelSignal !== undefined) this.state.cancelSignal = cancelSignal;
+  }
+
+  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(copyEvent),
+      ...(s.inputs === undefined ? {} : { inputs: s.inputs.map((input) => ({ ...input })) }),
+      activeFailure: s.activeFailure ? copyEvent(s.activeFailure) : null, lastFailure: s.lastFailure ? copyEvent(s.lastFailure) : null,
+    };
+  }
+
+  recover(tasks: SavedTask[]): void {
+    const workers = tasks.filter(sdkTask);
+    this.tasks.restore(workers.map((task) => ({
+      id: task.id, kind: null, agent: null, status: task.state === 'interrupted' ? 'unknown' : task.state, ...(task.description === undefined ? {} : { description: task.description }),
+      background: true, startedAt: 0, updatedAt: task.updatedAt, endedAt: null, lastTool: null, toolUses: 0, durationMs: 0,
+    })), workers.flatMap((task) => task.toolUseId === null ? [] : [[task.toolUseId, task.id]]));
+    for (const task of tasks) {
+      if (task.notice === null) continue;
+      const code = task.notice.reason === 'worker_restart' ? 'interrupted' : task.notice.reason;
+      this.failure('task_failed', code, false, null, task.id);
+    }
+    this.update();
+  }
+
+  recovered(): void {
+    this.interrupted = null;
+    if (this.state.activeFailure?.code === 'interrupted') this.clearFailure();
+    this.update();
+  }
+
+  pending(count: number, oldest?: number | null): void {
+    this.state.pending = count;
+    if (oldest !== undefined) this.state.queueOldestAt = oldest;
+    this.update();
+  }
+
+  input(input: RunnerInput): void {
+    this.state.inputs = [input, ...(this.state.inputs ?? []).filter((entry) => entry.id !== input.id)].slice(0, MAX_EVENTS);
+    this.update();
+  }
+
+  call(state: NonNullable<RunnerActivity['callState']>): void {
+    this.state.callState = state;
+    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(err: unknown): void {
+    this.failed = true;
+    const safe = sessionFailure(err);
+    const failure = this.failure('session_failed', safe.code, true, null, null, {}, safe.diagnostic);
+    if (failure.code === 'interrupted') this.interrupted = failure;
+    this.state.phase = 'error';
+    this.state.mainPhase = 'error';
+    log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: this.state.lastError }, '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 {
+    if (message.subtype === 'task_notification' && message.reason === 'worker_restart') this.workerErrors.set(message.task_id, 'interrupted');
+    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.failure('compact_failed', 'compact_error', false, null, null, { id: message.uuid });
+    }
+  }
+
+  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.clearFailure();
+    this.providerCode = null;
+    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.failure(kind, this.workerErrors.get(taskId ?? '') ?? 'task_error', false, tool, taskId);
+    else this.event(kind, tool, taskId);
+    if (taskId !== null && ['task_completed', 'task_failed', 'task_stopped'].includes(kind)) this.workerErrors.delete(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.clearFailure();
+      this.providerCode = null;
+      this.event('turn_finished');
+      return;
+    }
+    const code = message.subtype === 'success' ? this.providerCode ?? providerFailure(message.api_error_status) : message.subtype;
+    this.providerCode = null;
+    this.failure('turn_failed', code, true, null, null, { id: message.uuid });
+    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 (message.type === 'assistant') this.assistant(message, parent);
+    if (Array.isArray(content)) for (const block of content) if (isRecord(block)) this.block(block, parent);
+  }
+
+  private assistant(message: Extract<SDKMessage, { type: 'assistant' }>, parent: string | null): void {
+    if (parent !== null) {
+      this.tasks.model(parent, message.message.model);
+      const id = this.tasks.taskFor(parent);
+      if (id !== null && message.error !== undefined) this.workerErrors.set(id, PROVIDER_ERRORS[message.error]);
+      return;
+    }
+    this.turn();
+    if (message.error !== undefined) this.providerCode = message.error === 'unknown' ? null : PROVIDER_ERRORS[message.error];
+  }
+
+  private block(block: Record<string, unknown>, parent: string | null): void {
+    if (block.type === 'tool_use' && typeof block.id === 'string') {
+      if (block.name === 'Agent' || block.name === 'Task') this.tasks.launch(block.id, block.input);
+      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, block.content);
+  }
+
+  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, content: unknown): 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.toolFailure(id, tool, parent, content);
+      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 toolFailure(id: string, tool: TrackedTool | undefined, parent: string | null, content: unknown): void {
+    const name = tool?.name ?? 'tool';
+    const code = name === 'Read' && readTokenLimit(content) ? 'read_token_limit' : 'tool_error';
+    this.failure('tool_failed', code, false, name, tool?.taskId ?? this.tasks.taskFor(parent), { toolUseId: id });
+  }
+
+  private clearFailure(): void {
+    this.failed = false;
+    this.state.activeFailure = this.interrupted;
+    this.state.lastError = this.interrupted === null ? null : runnerFailureSummary(this.interrupted.code);
+  }
+
+  private failure(kind: RunnerEventKind, code: RunnerFailureCode, active: boolean, tool: string | null = null, taskId: string | null = null, identity: Pick<RunnerEvent, 'id' | 'toolUseId'> = {}, diagnostic?: RunnerDiagnostic): RunnerFailure {
+    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }), ...(diagnostic === undefined ? {} : { diagnostic }) };
+    this.state.lastFailure = failure;
+    if (active) {
+      this.state.activeFailure = failure;
+      this.state.lastError = runnerFailureSummary(code, tool, diagnostic);
+    }
+    this.record(failure);
+    return failure;
+  }
+
+  private event(kind: RunnerEventKind, tool: string | null = null, taskId: string | null = null): void {
+    this.record({ id: randomUUID(), at: Date.now(), kind, tool, taskId });
+  }
+
+  private record(event: RunnerEvent): void {
+    this.state.events.unshift(event);
+    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,87 @@
+import { dirname, join } from 'node:path';
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { AutomationStore } from '@metro-labs/core/automation-store';
+import { errMsg, log } from '@metro-labs/core/log';
+import { skillSourceRoot } from '@metro-labs/core/skill-source';
+import { SkillsRefresh } from './skills.js';
+import 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 { metroTools, type MetroTools } from './tool-proxy.js';
+
+export interface RunningAgent {
+  runner: Runner;
+  link: MetroLink;
+  done: Promise<void>;
+  stop(cancelActive?: boolean): Promise<void>;
+}
+
+export interface AppHooks {
+  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 automationStore = new AutomationStore(join(dirname(cfg.statePath), 'automation'));
+  const skills = new SkillsRefresh(skillSourceRoot(cfg.claudeDir), cfg.claudeDir);
+  const runner = new Runner({ store, automationStore, skills, readOnly: (tool) => tools?.readOnly(tool) ?? false, ...hooks });
+  const link = await MetroLink.open(cfg.mcpUrl, cfg.key, {
+    channel: (event) => { runner.chat(event); },
+    call: (notice) => { runner.calls.notice(notice); },
+    callState: (state) => { runner.calls.reconcile(state.route); },
+    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 (cancelActive = false): Promise<void> => {
+    if (stopped) {
+      if (cancelActive) runner.close(true);
+      return;
+    }
+    stopped = true;
+    runner.close(cancelActive);
+    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');
+    const approvals = approvalsThrough(link, (id, ask) => { hooks.activity?.approval(id, ask); }, (tool, input) => runner.calls.approval(tool, input));
+    runner.start(runnerOptions(cfg, tools, approvals, resume, hooks.env));
+    return { runner, link, done: runner.run(hooks.observe), stop };
+  } catch (err) {
+    runner.close(false);
+    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(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,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';
+}