@agent-compose/sdk 0.5.1 → 0.5.5

package/src/pause/state-dir.ts

@@ -0,0 +1,262 @@
+/**
+ * Pause state directory — durable per-agent / per-checkpoint / per-pause
+ * blobs the sandbox snapshot carries across pause-resume.
+ *
+ * Layout under `/tmp/wf/state/`:
+ *
+ *   agent-<agentInstanceId>.json     ← agent loop state (iteration, messages, processor cursor)
+ *   runtime-<agentInstanceId>.json   ← runtime-private blob (opaque to the loop)
+ *   checkpoints/<name>.json          ← user `ctx.checkpoint(name, fn)` memoised values
+ *   pauses/<pauseId>.json            ← pause records (request + resume payload once available)
+ *
+ * Atomic writes (write-tmp → fsync → rename) so a mid-write `sandbox.snapshot()`
+ * cannot capture partial state. Most read helpers return `null` on missing-file
+ * rather than throwing — callers branch on presence to distinguish "first
+ * run" from "post-resume restore". User checkpoints use an explicit
+ * found/value result because `null` is a valid memoised value.
+ *
+ * The state-dir layout is treated as wire protocol between the SDK
+ * runner (writer) and the SDK on the next subprocess invocation (reader).
+ * Changing a filename or shape is a breaking change to pause resumption
+ * for any in-flight paused workflow. See ADR-0006.
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Root of the pause state-dir. Defaults to `/tmp/wf/state` — the
+ *  canonical location inside the sandbox. Tests and non-`/tmp`-writable
+ *  environments can override via `AGENT_COMPOSE_STATE_DIR`.
+ *
+ *  Read at CALL TIME, not module load. An earlier draft cached it on
+ *  first import, but that turned out to be test-ordering-fragile: once
+ *  any test imported state-dir (directly or transitively via
+ *  agent-loop) the path got locked to whatever env was set at that
+ *  instant, and a later test setting `AGENT_COMPOSE_STATE_DIR` would
+ *  silently write to the cached path instead. Reading the env each
+ *  call costs nothing measurable next to the fsync. */
+export function getStateDir(): string {
+  return process.env.AGENT_COMPOSE_STATE_DIR ?? "/tmp/wf/state";
+}
+
+const checkpointsDir = () => join(getStateDir(), "checkpoints");
+const pausesDir      = () => join(getStateDir(), "pauses");
+
+const agentStatePath   = (agentInstanceId: string) => join(getStateDir(), `agent-${agentInstanceId}.json`);
+const runtimeStatePath = (agentInstanceId: string) => join(getStateDir(), `runtime-${agentInstanceId}.json`);
+const checkpointPath   = (name: string)            => join(checkpointsDir(), `${name}.json`);
+const pausePath        = (pauseId: string)         => join(pausesDir(), `${pauseId}.json`);
+
+/** `name` is interpolated into a filename; reject anything outside a
+ *  conservative slug. Prevents a workflow author from writing
+ *  `ctx.checkpoint("../../etc/passwd", fn)` and escaping the dir.
+ *
+ *  First character must be alphanumeric or `_` so dotfile names (`.foo`)
+ *  and parent-directory tokens (`.`, `..`) are rejected regardless of
+ *  any future change to the `.json` suffix invariant. Empty strings are
+ *  rejected because the first character is required.
+ *
+ *  Allowed: `agent-1`, `expensive_load`, `p.42`, `decision-v2`.
+ *  Rejected: ``, `.`, `..`, `.hidden`, `-leading`, `a/b`, `a\b`. */
+const NAME_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
+
+function assertSafeName(label: string, name: string): void {
+  if (!NAME_RE.test(name)) {
+    throw new Error(`${label} name must match ${NAME_RE} (got ${JSON.stringify(name)})`);
+  }
+}
+
+export function assertSafeCheckpointName(name: string): void {
+  assertSafeName("checkpoint", name);
+}
+
+/** Ensure the state-dir and its subdirectories exist. Idempotent —
+ *  re-running is a no-op. Called lazily by every write entry-point so
+ *  callers don't need to remember to call it. */
+async function ensureDirs(): Promise<void> {
+  await fs.mkdir(checkpointsDir(), { recursive: true });
+  await fs.mkdir(pausesDir(),      { recursive: true });
+}
+
+/** Atomic write: temp file in the same directory, fsync to flush
+ *  contents to disk, then rename onto the target. POSIX rename is
+ *  atomic when source and target are on the same filesystem (always
+ *  true here — same dir), so a snapshot in progress sees either the
+ *  pre-write file or the fully-written file, never a partial. */
+async function atomicWriteJSON(path: string, value: unknown): Promise<void> {
+  await ensureDirs();
+  const tmp = `${path}.tmp.${randomBytes(6).toString("hex")}`;
+  const payload = JSON.stringify(value);
+  if (payload === undefined) {
+    throw new Error("pause state values must be JSON-serialisable");
+  }
+  const handle = await fs.open(tmp, "w");
+  try {
+    await handle.writeFile(payload, { encoding: "utf8" });
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await fs.rename(tmp, path);
+}
+
+/** Read + JSON-parse. Returns `null` when the file doesn't exist —
+ *  the absence IS the signal "no state yet".
+ *  Any other error (permission, JSON syntax, partial write) bubbles
+ *  so the runner fails loudly rather than silently re-running. */
+async function readJSON<T = unknown>(path: string): Promise<T | null> {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export type CheckpointRead<T> =
+  | { found: true; value: T }
+  | { found: false };
+
+async function readJSONWithPresence<T = unknown>(path: string): Promise<CheckpointRead<T>> {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return { found: true, value: JSON.parse(raw) as T };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { found: false };
+    throw err;
+  }
+}
+
+// ── Agent loop state ────────────────────────────────────────────────────────
+//
+// `agentInstanceId` flows from workflow-author code (`agent({ agentId })`)
+// and from the step-mode derivation in `run-agent.ts`. Both are
+// validated here so a malformed id can't escape the state-dir even
+// through the agent / runtime entry points.
+
+export async function readAgentState<T = unknown>(agentInstanceId: string): Promise<T | null> {
+  assertSafeName("agent", agentInstanceId);
+  return readJSON<T>(agentStatePath(agentInstanceId));
+}
+
+export async function writeAgentState(agentInstanceId: string, state: unknown): Promise<void> {
+  assertSafeName("agent", agentInstanceId);
+  await atomicWriteJSON(agentStatePath(agentInstanceId), state);
+}
+
+// ── Runtime-private blob ────────────────────────────────────────────────────
+
+export async function readRuntimeCheckpoint<T = unknown>(agentInstanceId: string): Promise<T | null> {
+  assertSafeName("runtime", agentInstanceId);
+  return readJSON<T>(runtimeStatePath(agentInstanceId));
+}
+
+export async function writeRuntimeCheckpoint(agentInstanceId: string, blob: unknown): Promise<void> {
+  assertSafeName("runtime", agentInstanceId);
+  await atomicWriteJSON(runtimeStatePath(agentInstanceId), blob);
+}
+
+// ── User checkpoints ────────────────────────────────────────────────────────
+
+export async function readCheckpoint<T = unknown>(name: string): Promise<CheckpointRead<T>> {
+  assertSafeCheckpointName(name);
+  return readJSONWithPresence<T>(checkpointPath(name));
+}
+
+export async function writeCheckpoint(name: string, value: unknown): Promise<void> {
+  assertSafeCheckpointName(name);
+  await atomicWriteJSON(checkpointPath(name), value);
+}
+
+// ── Pause records ───────────────────────────────────────────────────────────
+
+/** The `pauses/<pauseId>.json` file — the only durable handoff between the
+ *  paused subprocess and the resumed one.
+ *
+ *  Written twice in two execution contexts:
+ *  - At pause time the runner writes the placeholder `{ pauseId, request }`
+ *    (no `resolved`). The snapshot captures it.
+ *  - At resume time the engine activity writes the resolution — usually
+ *    merged on top of the placeholder, but snapshotless pauses may only have
+ *    `{ resolved: true, resumePayload, expired }` in a fresh sandbox. Those
+ *    three resolution fields are always present together so the byte shape
+ *    distinguishes a real resume (`expired:false`) from a TTL expiry
+ *    (`expired:true`) from an unresolved placeholder (`resolved` absent).
+ *
+ *  `corePause` reads it on re-entry: `resolved !== true` ⇒ still my own
+ *  placeholder, pause again; `expired` ⇒ apply `onExpiry`; else return
+ *  `resumePayload`. */
+export interface PauseRecord {
+  pauseId:        string;
+  request:        unknown;
+  /** Set true once the engine has written the resolution (resume or expiry). */
+  resolved?:      boolean;
+  /** Value to return from `ctx.pause` on a real resume; null for expiry. */
+  resumePayload?: unknown;
+  /** True when the resolution is a TTL expiry, not a caller-driven resume. */
+  expired?:       boolean;
+}
+
+function hasOwn(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function validatePauseRecord(value: unknown, expectedPauseId: string): PauseRecord {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: expected object`);
+  }
+  const record = value as Record<string, unknown>;
+  if (record.pauseId !== undefined && record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: pauseId mismatch`);
+  }
+
+  if (record.resolved === true) {
+    if (typeof record.expired !== "boolean") {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require boolean expired`);
+    }
+    if (!hasOwn(record, "resumePayload") || record.resumePayload === undefined) {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require resumePayload`);
+    }
+    return {
+      pauseId: expectedPauseId,
+      request: hasOwn(record, "request") ? record.request : null,
+      ...record,
+    } as unknown as PauseRecord;
+  }
+
+  if (record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require matching pauseId`);
+  }
+  if (!hasOwn(record, "request") || record.request === undefined) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require request`);
+  }
+  if (record.resolved !== undefined && record.resolved !== false) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: resolved must be true, false, or absent`);
+  }
+  if (hasOwn(record, "expired") || hasOwn(record, "resumePayload")) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records must not include resolution fields`);
+  }
+  return record as unknown as PauseRecord;
+}
+
+export async function readPauseRecord(pauseId: string): Promise<PauseRecord | null> {
+  assertSafeName("pause", pauseId);
+  const record = await readJSON<unknown>(pausePath(pauseId));
+  return record === null ? null : validatePauseRecord(record, pauseId);
+}
+
+export async function writePauseRecord(record: PauseRecord): Promise<void> {
+  assertSafeName("pause", record.pauseId);
+  validatePauseRecord(record, record.pauseId);
+  await atomicWriteJSON(pausePath(record.pauseId), record);
+}
+
+/** Wipe the entire state directory. Used by the runner at first-boot
+ *  (no pauseId in env) so a freshly-dispatched run never inherits state
+ *  from a prior dispatch that shared the sandbox snapshot template.
+ *  No-op when the directory doesn't exist. */
+export async function resetStateDir(): Promise<void> {
+  await fs.rm(getStateDir(), { recursive: true, force: true });
+}

package/src/pause/wrappers.ts

@@ -0,0 +1,79 @@
+/**
+ * The three opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
+ * closure over `ctx.pause`:
+ *
+ *   - `requestDecision` — pause for a typed human/agent decision (schema required).
+ *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
+ *                         skips the snapshot, returns void.
+ *   - `waitForEvent`    — pause until an event resumes by correlation key.
+ *
+ * Built from a `PauseFn` so the wrapper logic lives in one place and the step
+ * runner just spreads them onto the context next to `pause`.
+ */
+
+import type { z } from "zod";
+import type { StepPauseRequest } from "../step-invocation/types.js";
+import type { PauseRequest } from "./pause-core.js";
+
+/** The public `ctx.pause` callable (always `kind: "custom"`). */
+export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
+
+/** Internal: pause with an explicit wire `kind`. The wrappers stamp
+ *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
+ *  `custom` and never exposes it. */
+export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
+
+export interface RequestDecisionRequest<T> {
+  reason:   string;
+  payload?: Record<string, unknown>;
+  /** Required — a decision is always validated against a shape. */
+  schema:   z.ZodType<T>;
+  ttlMs?:   number;
+}
+
+export interface WaitForEventRequest<T> {
+  reason:         string;
+  /** Required — the by-key resume route targets this. */
+  correlationKey: string;
+  schema?:        z.ZodType<T>;
+  ttlMs?:         number;
+}
+
+export interface PauseWrappers {
+  requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
+  sleep(durationMs: number): Promise<void>;
+  waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
+}
+
+export function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers {
+  return {
+    requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T> {
+      return pause<T>({
+        reason: req.reason,
+        schema: req.schema,
+        ...(req.payload !== undefined ? { payload: req.payload } : {}),
+        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
+      }, "decision");
+    },
+
+    // Resolves on its OWN ttl — there is no external resumer for a sleep, so
+    // onExpiry resolves (not throws) with void. snapshot:false keeps it cheap.
+    sleep(durationMs: number): Promise<void> {
+      return pause<void>({
+        reason:    `sleep ${durationMs}ms`,
+        ttlMs:     durationMs,
+        snapshot:  false,
+        onExpiry:  { mode: "resolve", value: undefined },
+      }, "sleep");
+    },
+
+    waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T> {
+      return pause<T>({
+        reason:         req.reason,
+        correlationKey: req.correlationKey,
+        ...(req.schema !== undefined ? { schema: req.schema } : {}),
+        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
+      }, "event");
+    },
+  };
+}

package/src/request-context/request-context.ts

@@ -39,6 +39,8 @@
  * is per-run by design (cross-run state must be explicit via `input`).
  */
 
+import { z } from "zod";
+
 /** Reserved key namespace prefix — anything starting with this is platform-owned. */
 export const AC_RESERVED_PREFIX = "ac__";
 
@@ -99,6 +101,18 @@ export interface RequestContextWire {
   user: Record<string, unknown>;
 }
 
+export const RequestContextWireSchema = z.object({
+  reserved: z.object({
+    teamId:       z.string(),
+    runId:        z.string(),
+    workflowId:   z.string(),
+    factoryId:    z.string().nullable(),
+    apiKeyScopes: z.array(z.string()).readonly(),
+    parentRunId:  z.string().nullable(),
+  }),
+  user: z.record(z.string(), z.unknown()),
+}) satisfies z.ZodType<RequestContextWire>;
+
 /** Thrown when a caller tries to `set` or `delete` a reserved key downstream. */
 export class ReservedKeyError extends Error {
   readonly key: string;
@@ -185,9 +199,10 @@ export class RequestContext<U extends Record<string, unknown> = Record<string, u
    * its own `AbortSignal` separately via `withAbortSignal()`.
    */
   static deserialise(wire: RequestContextWire): RequestContext {
+    const parsed = RequestContextWireSchema.parse(wire);
     const ctx = new RequestContext(
-      { ...wire.reserved, abortSignal: undefined },
-      new Map(Object.entries(wire.user)),
+      { ...parsed.reserved, abortSignal: undefined },
+      new Map(Object.entries(parsed.user)),
     );
     return ctx;
   }

package/src/runtimes/_cli-agent.ts

@@ -0,0 +1,161 @@
+/**
+ * CLI-agent runtime base — drive an external agentic coding CLI inside the
+ * sandbox and map its JSON-Lines (JSONL) stream onto the `AgentMessage`
+ * contract.
+ *
+ * This is a different *mechanism* from the other runtimes: `claudeRuntime`
+ * drives the Anthropic Agent SDK and `vercelRuntime` drives the Vercel AI SDK,
+ * but a CLI-agent runtime spawns the provider's own CLI (`codex exec --json`,
+ * `amp -x --stream-json`) — the CLI brings its own agent loop + tools, and we
+ * only stream-parse the events it prints. Codex and Amp are the first two; this
+ * base is the shared machinery (spawn → line-buffer stdout → JSONL parse →
+ * AsyncQueue bridge → init/usage/done/error lifecycle), parameterised per-CLI
+ * by a `CliAgentSpec`.
+ *
+ * Requirements (per spec): the provider CLI is installed in the sandbox image,
+ * and the provider's API key is present in the sandbox environment (see each
+ * spec's `authEnv`). `commands.run` inherits the sandbox env, so secrets set via
+ * `agentc secrets set` are visible to the CLI.
+ *
+ * NOTE: the per-CLI command construction + resume flags + exact event shapes in
+ * the shipped specs are mapped from each tool's docs and have NOT been verified
+ * against a live CLI run — verify before relying on them in production.
+ */
+
+import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider } from "../index.js";
+import { defineRuntime } from "../types/runtime.js";
+import { AsyncQueue } from "../agent/async-queue.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+/** Single-quote a value for safe interpolation into a `sh -c` command line. */
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Per-CLI behaviour. The base owns the lifecycle (init/done/error) and the
+ *  transport (spawn + JSONL parse); a spec owns the CLI-specific bits. */
+export interface CliAgentSpec {
+  /** Runtime self-id surfaced on `agent.spawned` (dashboard runtime icon). */
+  kind: string;
+  /** Env var the CLI reads for auth — documentation only (must be set in the
+   *  sandbox env via a workflow secret). */
+  authEnv: string;
+  /** Default model id when none is configured; omit to let the CLI choose. */
+  defaultModel?: string;
+  /** Serialise the user prompt into the bytes written to the prompt file —
+   *  plain text for a CLI that reads the prompt from stdin (codex `-`), or a
+   *  JSONL user message for a `--stream-json-input` CLI (amp). */
+  promptPayload(prompt: string): string;
+  /** Build the one-shot shell command for a turn. `promptPath` is a file in the
+   *  sandbox holding `promptPayload(prompt)`; `sessionId` continues a thread. */
+  buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string }): string;
+  /** Map one parsed JSONL stdout event to `AgentMessage`s. The base emits
+   *  `init`/`done`/`error` lifecycle itself, so a spec maps only content +
+   *  usage (text / thinking / tool_use / tool_result / usage). */
+  mapEvent(parsed: Record<string, unknown>): AgentMessage[];
+  /** Pull a session/thread id out of a parsed event so the next turn can
+   *  resume it (codex `thread.started.thread_id`, amp `session_id`). */
+  extractSessionId(parsed: Record<string, unknown>): string | undefined;
+}
+
+export class CliAgentRunner implements ModelExecutionContract {
+  readonly kind: string;
+
+  constructor(
+    private readonly sandbox: SandboxProvider,
+    private readonly options: RuntimeOptions,
+    private readonly spec: CliAgentSpec,
+    private readonly configModel?: string,
+  ) {
+    this.kind = spec.kind;
+  }
+
+  get model(): string | undefined {
+    return this.configModel ?? this.options.model ?? this.spec.defaultModel;
+  }
+
+  // No captureCheckpoint/restoreCheckpoint: the CLI persists its thread/rollout
+  // on the sandbox filesystem (which round-trips through the pause snapshot),
+  // and the loop already carries the session id we emit on init/done and pass
+  // back as `sessionId` for resume — same model as claudeRuntime.
+
+  async *sendMessage(opts: {
+    prompt: string;
+    sessionId?: string;
+    iteration?: number;
+    signal?: AbortSignal;
+  }): AsyncGenerator<AgentMessage> {
+    const promptPath = `/tmp/ac-${this.spec.kind}-${this.options.agentId ?? "agent"}-${opts.iteration ?? 0}.in`;
+    await this.sandbox.files.write(promptPath, this.spec.promptPayload(opts.prompt));
+    const cmd = this.spec.buildCommand({
+      promptPath,
+      sessionId: opts.sessionId,
+      model: this.model,
+      cwd: this.options.cwd,
+    });
+
+    // Bridge the streaming stdout callback into an async-iterable of complete
+    // JSONL lines. `onStdout` chunks aren't line-aligned, so buffer + split.
+    const lines = new AsyncQueue<string>();
+    let buf = "";
+    const onStdout = (data: string) => {
+      buf += data;
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (line) lines.push(line);
+      }
+    };
+
+    // `commands.run` resolves when the process exits. Kick it off (don't await
+    // yet); flush the trailing buffer + close the queue on completion so the
+    // for-await below drains and we can read the exit code.
+    const runPromise = this.sandbox.commands.run(cmd, {
+      ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
+      onStdout,
+    }).then(
+      (res) => { const tail = buf.trim(); if (tail) lines.push(tail); lines.close(); return res; },
+      (err) => { lines.close(); throw err; },
+    );
+
+    yield { type: "init", sessionId: opts.sessionId ?? "", timestamp: now() };
+
+    let sessionId = opts.sessionId;
+    let sawError = false;
+    try {
+      for await (const line of lines) {
+        let parsed: Record<string, unknown>;
+        try {
+          parsed = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+          continue; // skip any non-JSON noise that lands on stdout
+        }
+        const sid = this.spec.extractSessionId(parsed);
+        if (sid) sessionId = sid;
+        for (const msg of this.spec.mapEvent(parsed)) {
+          if (msg.type === "error") sawError = true;
+          yield msg;
+        }
+      }
+
+      const res = await runPromise;
+      if (res.exitCode !== 0 && !sawError) {
+        const tail = (res.stderr ?? "").slice(-2000);
+        yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now() };
+        return;
+      }
+      if (!sawError) yield { type: "done", sessionId: sessionId ?? "", timestamp: now() };
+    } catch (err) {
+      yield { type: "error", text: formatError(err), timestamp: now() };
+    }
+  }
+}
+
+export function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string) {
+  return defineRuntime({
+    create: (sandbox, opts) => new CliAgentRunner(sandbox, opts, spec, configModel),
+  });
+}

package/src/runtimes/amp.ts

@@ -0,0 +1,94 @@
+/**
+ * Amp CLI runtime — drives Sourcegraph's `amp -x --stream-json` agentic CLI
+ * inside the sandbox and maps its (Claude-Code-compatible) JSONL stream onto
+ * the AgentMessage contract. Built on the shared CLI-agent base; Amp brings its
+ * own loop + tools, so we only stream-parse what it prints.
+ *
+ * Auth: set `AMP_API_KEY` (`sgamp_…`) in the sandbox env via a workflow secret.
+ * Requires the `amp` CLI (`@ampcode/cli`) installed in the sandbox image. The
+ * model is chosen by the AMP_API_KEY account (e.g. a GPT-only token runs GPT);
+ * the runtime doesn't pin a model.
+ *
+ * ⚠️ NOT verified against a live `amp` run — the thread-continue syntax and the
+ * exact assistant/result shapes are mapped from the docs (ampcode.com). Verify
+ * before production use.
+ */
+
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+/** Block array off either `{ message: { content } }` (Claude shape) or a
+ *  top-level `{ content }`, whichever the stream uses. */
+function blocks(msg: Record<string, unknown>): Array<Record<string, unknown>> {
+  const inner = (msg.message as { content?: unknown[] } | undefined)?.content
+    ?? (msg.content as unknown[] | undefined)
+    ?? [];
+  return inner as Array<Record<string, unknown>>;
+}
+
+const ampSpec: CliAgentSpec = {
+  kind: "amp",
+  authEnv: "AMP_API_KEY",
+  // `--stream-json-input` reads JSON Lines user messages from stdin; write one.
+  // amp's --stream-json-input wants Claude-shaped content blocks, not a bare
+  // string (it rejects a string `content` with "expected array, received string").
+  promptPayload: (prompt) =>
+    JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: prompt }] } }) + "\n",
+  buildCommand: ({ promptPath, sessionId }) => {
+    // Continue the prior thread by id when we have one; else start fresh.
+    const cont = sessionId ? `threads continue ${shellQuote(sessionId)} ` : "";
+    return `amp ${cont}-x --stream-json --stream-json-input < ${shellQuote(promptPath)}`;
+  },
+  // Amp stamps `session_id` (a "T-…" thread id) on every message.
+  extractSessionId: (p) => (typeof p.session_id === "string" ? p.session_id : undefined),
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    if (p.type === "assistant") {
+      return blocks(p).flatMap((b): AgentMessage[] => {
+        if (b.type === "text") return [{ type: "text", text: String(b.text ?? ""), timestamp: ts }];
+        if (b.type === "thinking") return [{ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts }];
+        if (b.type === "tool_use") return [{ type: "tool_use", toolName: String(b.name ?? ""), toolInput: (b.input ?? {}) as Record<string, unknown>, toolUseId: String(b.id ?? ""), timestamp: ts }];
+        return [];
+      });
+    }
+    if (p.type === "user") {
+      return blocks(p).flatMap((b): AgentMessage[] =>
+        b.type === "tool_result"
+          ? [{ type: "tool_result", toolUseId: String(b.tool_use_id ?? ""), output: typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? ""), isError: Boolean(b.is_error), timestamp: ts }]
+          : []);
+    }
+    if (p.type === "result") {
+      const out: AgentMessage[] = [];
+      const u = p.usage as Record<string, number> | undefined;
+      if (u) out.push({
+        type: "usage",
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+        cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+        durationMs: Number(p.duration_ms ?? 0),
+        numTurns: Number(p.num_turns ?? 0),
+        timestamp: ts,
+      });
+      if (p.is_error || p.subtype === "error") {
+        out.push({ type: "error", text: formatError(p.result ?? p.error), timestamp: ts });
+      }
+      return out;
+    }
+    return []; // "system" → session id captured by extractSessionId; init/done owned by the base
+  },
+};
+
+export interface AmpRuntimeConfig {
+  /** Amp uses its configured model; reserved for forward-compatibility. */
+  model?: string;
+}
+
+export function createAmpRuntime(config: AmpRuntimeConfig = {}) {
+  return createCliAgentRuntime(ampSpec, config.model);
+}
+
+export default createAmpRuntime();