@agent-compose/sdk 0.5.8 → 0.6.0

package/dist/types/protocol.d.ts

@@ -27,6 +27,23 @@ export interface AgentMessageToolResult extends AgentMessageBase {
     toolUseId: string;
     output: string;
     isError: boolean;
+    /** Structured file diffs produced by the tool call, carried alongside the
+     *  rendered `output` so a richer renderer can use the structure without
+     *  re-plumbing the normaliser. Sourced from ACP `tool_call`/`tool_call_update`
+     *  `diff` content blocks (WS-C / ADR-0020 Q3). Optional and additive:
+     *  existing producers (claude / vercel / legacy JSONL) omit it. `oldText` is
+     *  null for a newly created file. */
+    diffs?: {
+        path: string;
+        oldText: string | null;
+        newText: string;
+    }[];
+    /** File locations touched by the tool call (ACP `locations` field), enabling
+     *  "follow-along" UI. Optional and additive (WS-C / ADR-0020 Q3). */
+    locations?: {
+        path: string;
+        line?: number;
+    }[];
 }
 export interface AgentMessageDone extends AgentMessageBase {
     type: "done";
@@ -45,7 +62,21 @@ export interface AgentMessageUsage extends AgentMessageBase {
     durationMs: number;
     numTurns: number;
 }
-export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage;
+/** Structured execution plan emitted by an agent (ACP `plan` session update,
+ *  WS-C / ADR-0020 Q2). Each `plan` notification REPLACES the whole plan — the
+ *  normaliser emits one `AgentMessagePlan` per notification carrying the entire
+ *  `entries` array, and downstream treats the latest as authoritative. This is
+ *  NOT an `AgentStatus` and does not feed self-pause; it is observability only.
+ *  Additive 9th kind: existing producers never emit it. */
+export interface AgentMessagePlan extends AgentMessageBase {
+    type: "plan";
+    entries: {
+        content: string;
+        priority: "high" | "medium" | "low";
+        status: "pending" | "in_progress" | "completed";
+    }[];
+}
+export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessagePlan;
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {
     summary: string;

package/dist/types/runtime.d.ts

@@ -4,6 +4,7 @@
 import type { SandboxProvider } from "./sandbox.js";
 import type { AgentMessage } from "./protocol.js";
 import type { Processor, ProcessorContext, ToolCall } from "../processors/processor.js";
+import type { BoundaryPauseFn } from "../pause/pause-core.js";
 import type { RequestContext } from "../request-context/request-context.js";
 /** Configuration for a single MCP server. */
 export interface McpServerConfig {
@@ -28,6 +29,19 @@ export interface RuntimeOptions {
     /** Agent id and label for processor context / adapter logs. */
     agentId?: string;
     iteration?: number;
+    /** The platform manual (file conventions, connectors & access, how to pause).
+     *  `agent()` builds it per-run (`buildAgentContextDoc`) and threads it here so
+     *  a runtime that supports a system-prompt append (the claude runtime) injects
+     *  it directly — instead of relying on the agent to `cat` the on-disk
+     *  AGENTS.md/CLAUDE.md, which the Agent SDK doesn't auto-load and which can
+     *  fail to write on a read-only/degraded working dir. */
+    agentManual?: string;
+    /** The run's pause boundary, threaded from the agent loop so a runtime-driven
+     *  pre-tool gate (e.g. the ACP `session/request_permission` path through
+     *  `gateToolCall`) can raise a human-approval `ctx.pause`. The runtime binds it
+     *  to the current `{ agentId, iteration }` when it builds a ProcessorContext.
+     *  Absent ⇒ a processor pause throws (no boundary; see `boundProcessorPause`). */
+    pause?: BoundaryPauseFn;
     /** Optional JSON schema for runtimes with native structured-output support. */
     outputFormat?: {
         type: "json_schema";

package/dist/types/sandbox-environment.d.ts

@@ -35,7 +35,7 @@
  */
 import type { SandboxProvider } from "./sandbox.js";
 import type { Workflow } from "../workflow-steps/types.js";
-import type { SnapshotConfig } from "./workflow-metadata.js";
+import type { SandboxResources, SnapshotConfig } from "./workflow-metadata.js";
 export interface SandboxEnvironmentDefinition {
     name: string;
     description?: string;
@@ -45,6 +45,11 @@ export interface SandboxEnvironmentDefinition {
      *  useful — an env with no snapshot can't be referenced as a
      *  `bootFrom` on another workflow). */
     snapshots?: SnapshotConfig;
+    /** Which substrate to build this environment on (and any sizing).
+     *  An env image is provider-specific — a snapshot captured on E2B
+     *  can't boot on Vercel and vice-versa — so building the E2B base/
+     *  agent-env requires `resources: { provider: "e2b" }`. */
+    resources?: SandboxResources;
 }
 /** Sugar over `defineWorkflow` for setup-only workflows that exist to
  *  capture a snapshot. The workflow takes no meaningful input and returns

package/dist/types/sandbox.d.ts

@@ -21,6 +21,59 @@ export interface SandboxCommandResult {
     stdout: string;
     stderr: string;
 }
+/** A long-running command launched in the background (ADR-0028). Unlike
+ *  `commands.run` (which awaits completion on one connection), a background
+ *  command keeps running inside the VM independent of the launching
+ *  connection: it survives `pauseProcess()`/resume and is re-attachable by
+ *  `pid` after a fresh `Sandbox.connect`. This is what lets the platform
+ *  freeze an agent mid-turn for a human-in-the-loop pause and continue the
+ *  SAME process on resume — no re-run.
+ *
+ *  Implemented ONLY by process-resume-capable providers (E2B); the presence
+ *  of `commands.runBackground` IS the capability flag, paired with
+ *  `pauseProcess`. Providers without it leave both undefined and pause via
+ *  `snapshot()` + re-run instead. */
+export interface SandboxBackgroundProcess {
+    /** OS pid inside the VM — the durable handle used to reconnect after a
+     *  pause/resume cycle via `commands.connectProcess(pid)`. */
+    pid: number;
+    /** Resolve when the process exits, with its buffered result. Live output
+     *  streams to the `onStdout`/`onStderr` passed at launch / connect time.
+     *  Does NOT throw on a non-zero exit — the result carries `exitCode`. */
+    wait(): Promise<SandboxCommandResult>;
+    /** Force-terminate the process. */
+    kill(): Promise<void>;
+}
+/** A spawned long-lived command with a writable stdin and readable stdout,
+ *  exposed as byte web-streams. Unlike `commands.run` (which buffers to
+ *  completion and exposes stdout only via an `onStdout` callback), a duplex
+ *  handle keeps the process alive and lets the caller WRITE to its stdin —
+ *  the half `commands.run` cannot provide. It is the transport the ACP client
+ *  (`AcpClientPeer` over `ndJsonStream`) needs: the agent CLI reads JSON-RPC
+ *  request frames on stdin and answers on stdout.
+ *
+ *  Only `makeLocalSandboxProvider` implements it. The runner runs IN the
+ *  sandbox VM and spawns CLIs via the local provider (a plain `child_process`
+ *  pipe), so a duplex stdin works identically on Vercel/E2B/local. The
+ *  vercel/e2b providers are the SERVER→sandbox view and never spawn the in-VM
+ *  CLI, so they leave `spawnDuplex` undefined and callers fall back cleanly. */
+export interface SandboxDuplexProcess {
+    /** Subprocess stdin. JSON-RPC request frames are written here. */
+    stdin: WritableStream<Uint8Array>;
+    /** Subprocess stdout. JSON-RPC response/notification frames arrive here. */
+    stdout: ReadableStream<Uint8Array>;
+    /** Resolves when the subprocess exits, carrying the captured stderr tail. */
+    exited: Promise<{
+        exitCode: number;
+        stderr: string;
+    }>;
+    /** Force-terminate the subprocess. */
+    kill(): void;
+}
+export interface SandboxSpawnDuplexOptions {
+    cwd?: string;
+    envs?: Record<string, string>;
+}
 /**
  * A sandbox provider implements the RAW provider operations only. It does NOT
  * implement transient-failure retry/backoff: reconnecting and snapshotting both
@@ -43,6 +96,21 @@ export interface SandboxProvider {
     cwd?: string;
     commands: {
         run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
+        /** Spawn a long-lived command with a real duplex stdin/stdout. OPTIONAL —
+         *  implemented only by `makeLocalSandboxProvider` (the in-VM `child_process`
+         *  view). The vercel/e2b providers (server→sandbox) leave it undefined; an
+         *  ACP caller that finds it absent falls back to the JSONL transport. */
+        spawnDuplex?(cmd: string, opts?: SandboxSpawnDuplexOptions): SandboxDuplexProcess;
+        /** Launch a command in the background and return immediately with a
+         *  reconnectable handle (ADR-0028). The process survives the launching
+         *  connection dropping AND a `pauseProcess()`/resume cycle. OPTIONAL —
+         *  only process-resume providers (E2B) implement it; its presence (paired
+         *  with `pauseProcess`) is the native-pause capability flag. */
+        runBackground?(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxBackgroundProcess>;
+        /** Re-attach to a background command by `pid` after a fresh
+         *  `Sandbox.connect` (the resume half of `runBackground`). OPTIONAL,
+         *  E2B-only. Throws if no process with that pid is running. */
+        connectProcess?(pid: number, opts?: Pick<SandboxCommandRunOptions, "onStdout" | "onStderr" | "timeoutMs">): Promise<SandboxBackgroundProcess>;
     };
     files: {
         write(path: string, content: string): Promise<void>;
@@ -60,12 +128,24 @@ export interface SandboxProvider {
         snapshotId: string;
         sizeBytes?: number;
     }>;
-    /** Replace the live sandbox's egress policy in place. Vercel implements
-     *  it via `sandbox.update({ networkPolicy })` (2.x) so the server can
-     *  push a freshly resolved policy — with re-minted connector access
-     *  tokens — before each step instead of relying on the policy baked at
-     *  create. Providers whose enforcement lives inside the VM (E2B
-     *  iron-proxy) leave it undefined. */
+    /** Suspend the live VM in place and return a handle to resume it (ADR-0027).
+     *  Present ONLY on process-resume-capable providers (E2B via `sandbox.pause()`,
+     *  returning the sandbox id; resume is `Sandbox.connect(handle)`, which
+     *  auto-resumes the paused VM). Unlike `snapshot()` — which captures an FS
+     *  image, kills the origin, and re-runs the step from a fresh sandbox — a
+     *  process-resume pause FREEZES the live process (zero compute) and continues
+     *  it exactly where it blocked. The presence of this method IS the capability
+     *  flag: providers without native VM-suspend leave it undefined and fall back
+     *  to `snapshot()` + re-run. */
+    pauseProcess?(): Promise<{
+        resumeHandle: string;
+    }>;
+    /** Replace the live sandbox's egress policy in place — so the server can
+     *  push a freshly resolved policy (with re-minted connector access tokens)
+     *  before each step instead of relying on the policy baked at create.
+     *  Vercel implements it via `sandbox.update({ networkPolicy })` (2.x); E2B
+     *  via its native `sandbox.updateNetwork(...)`. Providers without a live
+     *  network-update primitive leave it undefined. */
     updateNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
 }
 /** Stateless provider-level snapshot deletion — no live sandbox needed,

package/dist/types/workflow-metadata.d.ts

@@ -8,8 +8,13 @@
  * Keep this module free of value imports from `types/workflow.ts` or
  * `workflow-steps/workflow.ts` — it is the cycle-break point.
  */
-import type { SandboxNetworkPolicy, SandboxSize } from "../sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize, SandboxProviderName } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
+/** The sandbox providers selectable per-workflow. A narrowing of
+ *  `SandboxProviderName` to the two substrates that execute step workloads —
+ *  `e2b-desktop` (registry-only, never a workflow's runtime) is deliberately
+ *  excluded so a workflow can only ask for a substrate that actually runs steps. */
+export type WorkflowSandboxProvider = Extract<SandboxProviderName, "vercel" | "e2b">;
 /**
  * Workflow-level metadata read by the server at registration. Lives on
  * every `Workflow` as `workflow.metadata`, regardless of which form of
@@ -75,11 +80,14 @@ export interface IOSchema {
 /** Alias kept for backwards source-compatibility with the original
  *  output-only release. New code should prefer `IOSchema`. */
 export type OutputSchema = IOSchema;
-/** Per-connector HTTP request matcher (Tier-2 capability narrowing). The
- *  iron-proxy / firewall consults these when deciding whether to attach the
- *  brokered Authorization header to an outbound request. A request to the
- *  connector host whose method is not in `methods`, or whose path matches no
- *  entry in `pathPrefixes`, is refused (403) and the token is WITHHELD. */
+/** Per-connector HTTP request matcher (Tier-2 capability narrowing). Vercel's
+ *  firewall consults these when deciding whether to attach the brokered
+ *  Authorization header to an outbound request: a request to the connector
+ *  host whose method is not in `methods`, or whose path matches no entry in
+ *  `pathPrefixes`, goes out WITHOUT the token. NOT enforced on E2B — its
+ *  native rules carry only a header transform, no method/path matcher, so the
+ *  token rides every request to an allowed connector host there (the host
+ *  allowlist still confines which hosts are reachable). See `toE2bNetwork`. */
 export interface ConnectorRequestRules {
     /** Allowed HTTP methods (upper-case). Omit = any method (subject to
      *  `access`). */
@@ -138,10 +146,19 @@ export interface InvokePolicy {
  *  today; kept as its own object so finer controls (disk, gpu, …) can be
  *  added later without reshaping `WorkflowMetadata`. */
 export interface SandboxResources {
-    /** Machine size — `small | medium | large`. Maps to provider specs at
-     *  create time (Vercel: 2 / 4 / 8 vCPU, 2048 MB RAM per vCPU). Omit →
-     *  `"small"`. E2B sizing is template-defined and ignores this. */
+    /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
+     *  (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
+     *  provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
+     *  per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
+     *  ignores this. */
     size?: SandboxSize;
+    /** Sandbox provider this workflow's runs execute on — `"vercel"` or
+     *  `"e2b"`. Optional and additive: omit and the run resolves to the
+     *  platform default (`vercel`). Set explicitly to pin a workflow to a
+     *  substrate regardless of the deployment default. Snapshot formats are
+     *  provider-specific, so the resolved provider is stamped on the run row
+     *  at first dispatch and reused across pause/resume/replay. */
+    provider?: WorkflowSandboxProvider;
 }
 export interface WorkflowMetadata {
     /** One-line, human-readable description of what the workflow does.
@@ -163,7 +180,8 @@ export interface WorkflowMetadata {
     outputSchema?: IOSchema;
     /** All snapshot config — boot source + capture mode. */
     snapshots?: SnapshotConfig;
-    /** Sandbox machine resources (size). Optional; omit → small. */
+    /** Sandbox machine resources — size + provider. Optional; omit → smallest
+     *  SKU on the platform-default provider (`vercel`). */
     resources?: SandboxResources;
     processors?: readonly Processor[];
     /** Connector requirements — providers whose APIs this workflow calls.
@@ -176,6 +194,18 @@ export interface WorkflowMetadata {
     /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
      *  See `InvokePolicy`. */
     invokePolicy?: InvokePolicy;
+    /** Set by `defineSandboxEnvironment` to mark this workflow as an ENVIRONMENT
+     *  BUILD — a setup-only workflow whose job is to leave its VM configured and
+     *  snapshot it (base-env / agent-env). Environment builds build a platform
+     *  IMAGE and never use the shared factory drive, so the server SKIPS mounting
+     *  /factory for them: a live Archil mount baked into the captured snapshot
+     *  fails the NEXT boot's re-mount ("an older Archil process is still running
+     *  for this mountpoint"), degrading /factory for every workflow booting from
+     *  that snapshot. Absent on ordinary workflows — which mount /factory exactly
+     *  as before. Optional + additive: an ABSENT flag contributes nothing to the
+     *  canonical metadata hash (frozen-metadata rule), so existing workflows are
+     *  not forced to re-register. */
+    environmentBuild?: boolean;
 }
 /**
  * Pull the server-readable declarations off a source object (run-form

package/dist/types/workflow.d.ts

@@ -41,9 +41,16 @@ export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<str
     /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
     setMetadata: (data: Record<string, unknown>) => Promise<void>;
     /**
-     * Wrap a named step for observability. Emits step_started / step_completed /
-     * step_failed lifecycle events with duration. Use for long phases you want
+     * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
+     * the sandbox state-dir; on a pause-resume re-entry the recorded value is
+     * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
+     * emits substep_started / substep_completed / substep_failed lifecycle
+     * events with duration — use for long phases you want both durable and
      * visible on the run's timeline (setup, external API calls, submit).
+     *
+     * Names must be unique within a step body (they key the memoise file).
+     * A body that pauses is never memoised — the resume re-runs it. For
+     * cross-process side effects (DB writes, emails) use `invokeChild`.
      */
     step<T>(name: string, fn: () => Promise<T>): Promise<T>;
     /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
@@ -101,10 +108,12 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      */
     snapshots?: SnapshotConfig;
     /**
-     * Sandbox machine size — `small` (default) | `medium` | `large`. Maps to
-     * provider machine specs at create (Vercel: 2 / 4 / 8 vCPU, 2048 MB RAM
-     * per vCPU). Optional; omit for `small`. E2B sizing is template-defined
-     * and ignores this. Per-invocation `invoke({ size })` overrides it.
+     * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
+     * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
+     * (`vercel` | `e2b`). `size` maps to provider machine specs at create
+     * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
+     * ignores it. Optional; omit → smallest SKU on the default provider.
+     * Per-invocation `invoke({ size })` overrides the size.
      */
     resources?: SandboxResources;
     /**
@@ -178,6 +187,13 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
      */
     invokePolicy?: InvokePolicy;
+    /**
+     * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
+     * Marks the workflow as an environment build (base-env / agent-env) so the
+     * server skips mounting the shared factory drive for its runs (#13). See
+     * `WorkflowMetadata.environmentBuild`.
+     */
+    environmentBuild?: boolean;
 }
 /**
  * Declare a workflow. Two forms; both return a `Workflow` whose

package/dist/utils/bundler.d.ts

@@ -84,7 +84,8 @@ export interface BundledWorkflow {
     /** Snapshot config from the workflow definition — `bootFrom` (where to
      *  restore at run start), `save`, `retain`. */
     snapshots?: SnapshotConfig;
-    /** Sandbox machine size declared via `defineWorkflow({ resources: { size } })`. */
+    /** Sandbox resources declared via `defineWorkflow({ resources })` — machine
+     *  SKU (`size`) and `provider` (`vercel` | `e2b`). */
     resources?: SandboxResources;
     workflowPlan: WorkflowPlan;
     /** Compact JSON-Schema-shaped description of the workflow's input
@@ -100,6 +101,9 @@ export interface BundledWorkflow {
     /** Tier-1 invoke ACL — who may dispatch this connector-brokering
      *  workflow (`defineWorkflow({ invokePolicy })`). */
     invokePolicy?: InvokePolicy;
+    /** Set by `defineSandboxEnvironment` — marks an environment build so the
+     *  server skips the /factory mount for its runs (#13). */
+    environmentBuild?: boolean;
 }
 /**
  * Parse the bundled source and assert the default export is a CallExpression

package/dist/workflow-steps/observability.d.ts

@@ -31,13 +31,19 @@
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
 import type { AgentEventSink } from "../types/workflow.js";
 import type { LiveAgentEventEmitter } from "./run-callback.js";
+import type { ScopedMemoize } from "../pause/checkpoint.js";
 /** One named sub-step (from `ctx.step("name", async () => ...)`).
- *  Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
+ *  Becomes a `workflow_substep_*` lifecycle event on the run timeline.
+ *
+ *  `restored` is the durable-step resume case (ADR-0012): the body did NOT
+ *  re-run — its memoised result was read from the state-dir checkpoint a
+ *  prior subprocess wrote. Always `durationMs: 0` (no work happened this
+ *  pass) and never carries `error`. */
 export interface SubStepEvent {
     name: string;
     startedAt: number;
     durationMs: number;
-    status: "completed" | "failed";
+    status: "completed" | "failed" | "restored";
     /** Present when status="failed" — the user error's message. */
     error?: string;
 }
@@ -64,14 +70,34 @@ export declare class StepObservabilityCollector {
     private events;
     private subSteps;
     private readonly liveEmitter?;
+    /** State-dir memoise bound to this step's `step<idx>` scope. Present in
+     *  the sandbox runner (durable `ctx.step`); absent in-process so unit
+     *  tests record observability without touching disk. */
+    private readonly memoize?;
+    /** Sub-step names already used in THIS step body. A durable `ctx.step`
+     *  memoises by name, so a reused name would alias two distinct bodies
+     *  onto one checkpoint file — guarded by throwing on reuse (ADR-0012). */
+    private readonly usedStepNames;
     /** Seqs of events the server confirmed via the live route. */
     private readonly ackedSeqs;
     /** Promises for in-flight live emits — awaited at snapshot time. */
     private readonly inFlight;
     constructor(opts?: {
         liveEmitter?: LiveAgentEventEmitter;
+        memoize?: ScopedMemoize;
     });
     readonly setMetadata: (data: Record<string, unknown>) => Promise<void>;
+    /**
+     * Durable named sub-step (ADR-0012). The body's result is memoised to the
+     * state-dir checkpoint keyed `step<idx>.<name>`; on a pause-resume re-entry
+     * the value is read from disk and `fn` is NOT re-run (recorded as a
+     * duration-0 `"restored"` sub-step). A body that PAUSES (PauseSignal)
+     * propagates BEFORE any memoise write — partial work is never stored, so
+     * the resume re-runs it.
+     *
+     * When no memoise store is wired (in-process tests), the body always runs
+     * and is recorded as a normal timed `"completed"` / `"failed"` sub-step.
+     */
     readonly step: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
     readonly agentEvents: AgentEventSink;
     /** Wait for in-flight live emits to settle (or timeout) so the

package/dist/workflow-steps/types.d.ts

@@ -36,14 +36,18 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
      */
     setMetadata(data: Record<string, unknown>): Promise<void>;
     /**
-     * Wrap a named sub-step for observability. Emits
-     * `workflow_substep_started` / `workflow_substep_completed` /
-     * `workflow_substep_failed` lifecycle events on the run timeline with
-     * the measured `durationMs`. Use for long sub-phases inside one step
-     * (setup, external API call, submit).
+     * Durable named sub-step (ADR-0012). Runs `fn` once and memoises its
+     * result to the state-dir checkpoint keyed `step<idx>.<name>`; on a
+     * pause-resume re-entry the value is read from disk and `fn` is NOT
+     * re-run. Emits `workflow_substep_started` /
+     * `workflow_substep_completed` / `workflow_substep_failed` lifecycle
+     * events on the run timeline with the measured `durationMs` — a restored
+     * sub-step reports `durationMs: 0` and status `"restored"`.
      *
-     * The block runs even if observability flushing fails — instrumentation
-     * never breaks the workflow.
+     * Names must be unique within one step body — they key the memoise file,
+     * so a reused name throws. A body that pauses (PauseSignal) is never
+     * memoised: the resume re-enters and re-runs it. For cross-process side
+     * effects (DB writes, emails) use `invokeChild`, not `step`.
      */
     step<T>(name: string, fn: () => Promise<T>): Promise<T>;
     /**

package/dist/workflow-steps/workflow.d.ts

@@ -46,8 +46,9 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     snapshots?: SnapshotConfig;
-    /** Sandbox machine size — small (default) | medium | large. Vercel maps
-     *  it to vCPUs; E2B sizing is template-defined. Omit → small. */
+    /** Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string)
+     *  and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
+     *  sizing is template-defined. Omit → smallest SKU on the default provider. */
     resources?: SandboxResources;
     processors?: readonly Processor[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
@@ -60,13 +60,14 @@
     "vitest": "^3.0.0"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "0.29.0",
     "@anthropic-ai/claude-agent-sdk": "^0.2.129",
     "@babel/parser": "^7.29.3",
     "@babel/types": "^7.29.0",
     "@e2b/desktop": "^1.1.2",
     "@vercel/sandbox": "^2.2.0",
     "ai": "^6.0.175",
-    "e2b": "^2.3.0",
+    "e2b": "2.30.5",
     "ofetch": "^1.5.1",
     "openai": "^6.33.0",
     "p-retry": "^6.2.0",

package/src/agent/agent-context.ts

@@ -81,11 +81,19 @@ Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
 
 ## Pausing to ask the human — \`agentc pause\`
 
-When you can't or shouldn't proceed without a human, run \`agentc pause\`. It
-blocks until they answer on the dashboard, then prints their answer to stdout:
+When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
+**END YOUR TURN**:
 
-    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
-                          --option retry --option skip)
+    agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                 --option retry --option skip
+
+\`agentc pause\` does NOT block and does NOT print the answer. It records your
+question and returns immediately. The moment you end your turn, the run pauses
+(your sandbox is snapshotted and compute stops while the human decides) and the
+human's answer is delivered to you as your **next message** — you pick up
+exactly where you left off, with the answer in hand. So: ask, end your turn,
+and wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task
+complete after pausing.
 
 Reach for it the moment you hit — or foresee — any of these:
 - **A wall only a human can clear:** a 401/403, a missing credential, an
@@ -99,8 +107,8 @@ Reach for it the moment you hit — or foresee — any of these:
   several valid paths, a conflict with existing state, missing input only they have.
 
 You compose the \`--reason\` (the ask) yourself; pass \`--option\` choices when
-there are clear ones, omit them for a free-form answer. Read the printed answer
-and act on it. Each agent pauses independently — pausing doesn't stop the others.
+there are clear ones, omit them for a free-form answer. Each agent pauses
+independently — pausing doesn't stop the others.
 
 ## Credentials
 

package/src/agent/agent-loop.ts

@@ -9,6 +9,7 @@ import { AgentStatusSchema, parseAgentResponse } from "./protocol.js";
 import type { AgentStatus, AgentMessage } from "./protocol.js";
 import { randomUUID } from "node:crypto";
 import type { Processor, ProcessorContext } from "../processors/processor.js";
+import { boundProcessorPause, type BoundaryPauseFn } from "../pause/pause-core.js";
 import { runProcessorChain } from "../processors/runner.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { PauseManager } from "../pause/manager.js";
@@ -55,7 +56,8 @@ export type AgentMessageSummary =
   | { type: "tool_result"; toolUseId: string; output: string; isError: boolean }
   | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number; model?: string }
   | { type: "done"; sessionId: string }
-  | { type: "error"; text: string };
+  | { type: "error"; text: string }
+  | { type: "plan"; entries: { content: string; priority: "high" | "medium" | "low"; status: "pending" | "in_progress" | "completed" }[] };
 
 function truncate(value: string): string {
   return value.length > MESSAGE_PREVIEW_CHARS ? `${value.slice(0, MESSAGE_PREVIEW_CHARS)}…` : value;
@@ -83,6 +85,11 @@ export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
     };
     case "done": return { type: "done", sessionId: msg.sessionId };
     case "error": return { type: "error", text: truncate(msg.text) };
+    // ACP `plan` (WS-C / ADR-0020 Q2). Pure observability — forwarded to
+    // onAgentEvent / agent.message; it is NOT an AgentStatus and never feeds
+    // self-pause. Pass the entries straight through (the dashboard renders the
+    // structured plan; no preview truncation needed — entries are short).
+    case "plan": return { type: "plan", entries: msg.entries };
   }
 }
 
@@ -135,14 +142,12 @@ export interface AgentLoopOpts<TResponse = unknown> {
    * streaming input (ignored otherwise — handled at the runtime).
    */
   inbox?: import("./async-queue.js").AsyncQueue<{ text: string; senderName?: string | null }>;
-  /** PR 7 steer-pause: the boundary calls this to pause the workflow for a
-   *  human steer. agent() builds it (a corePause closed over runId/stepIndex);
-   *  the loop supplies the agentScope so the pauseId is stable across resume.
-   *  Absent ⇒ no steer pause (local tests, non-sandbox callers). */
-  pause?: <T = unknown>(
-    req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
-    agentScope: { agentId: string; iteration: number },
-  ) => Promise<T>;
+  /** The run's pause boundary. agent() builds it (a corePause closed over
+   *  runId/stepIndex); the loop supplies the agentScope so the pauseId is
+   *  stable across resume. Drives both PR-7 steer-pause AND a processor's
+   *  `ctx.pause` (human-approval gate). Absent ⇒ no pause (local tests,
+   *  non-sandbox callers). */
+  pause?: BoundaryPauseFn;
   /** PR 7: take-once read of this agent's pending steer (set by the control
    *  poller). Returns the steer's payload (reason / correlationKey) or null.
    *  The boundary consumes it once per check, and only when no steer is
@@ -180,6 +185,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     retryCount:  0,
     agentId,
     iteration,
+    pause: boundProcessorPause(opts.pause, { agentId, iteration }),
   });
 
   if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
@@ -191,6 +197,10 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     processors,
     requestContext,
     agentId,
+    // Thread the pause boundary so a runtime-driven pre-tool gate (e.g. the ACP
+    // `session/request_permission` path through CliAgentRunner.gateToolCall) can
+    // raise a human-approval `ctx.pause`, not just on the loop's own hooks.
+    ...(opts.pause ? { pause: opts.pause } : {}),
     ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: z.toJSONSchema(opts.responseSchema) as Record<string, unknown> } } : {}),
   });
 
@@ -222,7 +232,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   let resumed = false;
   // PR 7: a pending human steer-pause intent. Persisted in loop state so it
   // survives a resume and the boundary re-issues the pause on re-entry.
-  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number } | null = null;
+  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number; payload?: Record<string, unknown> } | null = null;
 
   const pauseManager = new PauseManager(agentId);
   const restore = await pauseManager.restoreAgentLoop<TResponse>(client);
@@ -342,6 +352,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           {
             reason: pendingSteerPause.reason,
             ...(pendingSteerPause.correlationKey !== null ? { correlationKey: pendingSteerPause.correlationKey } : {}),
+            ...(pendingSteerPause.payload !== undefined ? { payload: pendingSteerPause.payload } : {}),
             schema: SteerDecisionSchema,
           },
           { agentId, iteration },
@@ -403,6 +414,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       // (otherwise it restarts the task in a fresh session and repeats side effects).
       sessionId: lastSessionId ?? undefined,
       iteration: iteration + 1,
+      // Thread the loop's abort signal so a runtime that owns a cancellable
+      // transport (the ACP path's `session/cancel`, ADR-0020) actually unwinds
+      // when the loop aborts — input/output processor `abort`, or any external
+      // cancel. Without this the cancel/session-cancel wiring is dead.
+      signal: loopAbort.signal,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
       // processOutput chain — deny drops the message from accumulation;
@@ -437,6 +453,12 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     lastResponseText = responseText;
 
     let status = parseAgentStatus(responseText);
+
+    // ADR-0028 — `agentc pause` is no longer a marker the loop consumes here. It
+    // is a server operation: the CLI blocks on the pause API and the run is
+    // frozen in place by the step activity, with no loop involvement. The steer
+    // (human-driven) and `needs_input` (self-pause) paths below are unaffected.
+
     // Inline safeParse (instead of letting parseAgentResponse validate)
     // so a schema failure surfaces via lastResponseValidationError on
     // the next iteration — the model needs that feedback to fix its