@agent-compose/sdk 0.5.9 → 0.6.0

package/src/agent/pause-client.ts

@@ -0,0 +1,108 @@
+/**
+ * In-sandbox pause client (ADR-0028). The single way an agent pauses its OWN
+ * run: `agentc pause` and the gate-pause processor both call
+ * `requestPauseAndAwait`, which drives the server pause API and blocks until a
+ * human resolves it.
+ *
+ * Create-then-poll, NOT a held connection:
+ *   1. POST /pauses creates the pending row. The server wakes the step
+ *      activity, which freezes the live VM in place (E2B native suspend). The
+ *      poll loop below is part of that frozen process — between polls it costs
+ *      ZERO compute while the run is parked.
+ *   2. GET /pauses/:id long-polls (each request a bounded ~5s server-side
+ *      LISTEN race) until the row is terminal, then returns the human's answer.
+ *
+ * There is no marker file and no exception threaded through workflow code — the
+ * pause is a server operation, so nothing a `try/catch` can swallow.
+ */
+
+export interface PauseDecision {
+  status:   "resolved" | "expired" | "cancelled";
+  /** The human's answer (present on `resolved`). Caller-defined shape; the
+   *  dashboard sends `{ decision: string }`. Null on expiry/cancel. */
+  decision: unknown;
+}
+
+export interface RequestPauseOptions {
+  /** `AGENT_COMPOSE_URL` — the server base URL injected into the sandbox. */
+  baseUrl: string;
+  /** `AGENT_COMPOSE_RUN_TOKEN` — the run credential the agent already carries. */
+  token:   string;
+  /** `RUN_ID`. */
+  runId:   string;
+  /** Human-readable reason shown on the pause feed / approval UI. */
+  reason:  string;
+  /** Optional pause TTL; the workflow auto-expires the pause after this. */
+  ttlMs?:  number;
+  /** Optional decision options the human picks from (e.g. approve / deny). */
+  options?: Array<{ id: string; label: string }>;
+  /** The action under review (e.g. the tool call), surfaced to the human. */
+  action?: Record<string, unknown>;
+  /** Optional second-key resume route. */
+  correlationKey?: string;
+  /** Abort the wait (the agent loop's signal). */
+  signal?: AbortSignal;
+}
+
+/** Inject a custom fetch (tests). Defaults to global fetch. */
+type FetchFn = typeof fetch;
+
+const isAbort = (signal: AbortSignal | undefined) => Boolean(signal?.aborted);
+
+export async function requestPauseAndAwait(
+  opts: RequestPauseOptions,
+  fetchImpl: FetchFn = fetch,
+): Promise<PauseDecision> {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const headers = {
+    authorization:  `Bearer ${opts.token}`,
+    "content-type": "application/json",
+    accept:         "application/json",
+  } as const;
+
+  // 1. Create the pending pause. The server wakes the step activity → the live
+  //    VM suspends in place. 202 → { pauseId }.
+  const createRes = await fetchImpl(`${base}/api/v1/runs/${opts.runId}/pauses`, {
+    method:  "POST",
+    headers,
+    body: JSON.stringify({
+      reason: opts.reason,
+      ...(opts.ttlMs !== undefined  ? { ttlMs:          opts.ttlMs }          : {}),
+      ...(opts.options              ? { options:        opts.options }        : {}),
+      ...(opts.action               ? { action:         opts.action }         : {}),
+      ...(opts.correlationKey       ? { correlationKey: opts.correlationKey } : {}),
+    }),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+  if (!createRes.ok) {
+    const text = await createRes.text().catch(() => "");
+    throw new Error(`pause create failed (${createRes.status}): ${text.slice(0, 300)}`);
+  }
+  const { pauseId } = await createRes.json() as { pauseId: string };
+
+  // 2. Poll until terminal. Each GET is a bounded server long-poll; the loop
+  //    reissues. A transient error backs off and retries — the durable row is
+  //    the source of truth, so a dropped poll never loses the decision.
+  const pollUrl = `${base}/api/v1/runs/${opts.runId}/pauses/${pauseId}`;
+  let backoffMs = 0;
+  for (;;) {
+    if (isAbort(opts.signal)) throw new Error("pause wait aborted");
+    if (backoffMs > 0) await new Promise((r) => setTimeout(r, backoffMs));
+    let res: Awaited<ReturnType<FetchFn>>;
+    try {
+      res = await fetchImpl(pollUrl, { method: "GET", headers, ...(opts.signal ? { signal: opts.signal } : {}) });
+    } catch (err) {
+      if (isAbort(opts.signal)) throw err;
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      continue;
+    }
+    if (!res.ok) {
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      continue;
+    }
+    backoffMs = 0;
+    const body = await res.json() as { status: string; resumePayload?: unknown };
+    if (body.status === "pending") continue;
+    return { status: body.status as PauseDecision["status"], decision: body.resumePayload ?? null };
+  }
+}

package/src/agent/run-agent.ts

@@ -16,13 +16,12 @@ import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
 import { corePause, type PauseRequest } from "../pause/pause-core.js";
 import { agentLoop } from "./agent-loop.js";
 import { consumeSteerPending, runControlPoller } from "./steer-control.js";
-import { consumeLocalPauseRequest } from "./local-pause-request.js";
 import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
 import { AsyncQueue } from "./async-queue.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
-import { writeAgentContext } from "./agent-context.js";
+import { writeAgentContext, buildAgentContextDoc } from "./agent-context.js";
 import type { AgentBudget } from "../types/workflow.js";
 import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -334,7 +333,12 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
 
   try {
   return await agentLoop({
-    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    // Inject the platform manual into every runtime create() so a runtime that
+    // supports a system-prompt append (claude) carries it IN CONTEXT — not
+    // dependent on the agent choosing to `cat` AGENTS.md (which the SDK doesn't
+    // auto-load) or on writeAgentContext succeeding (it EACCES's on a read-only
+    // /workspace). buildAgentContextDoc is the same content writeAgentContext writes.
+    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
     agentId,
     ...(opts.label !== undefined ? { label: opts.label } : {}),
     ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),
@@ -366,9 +370,6 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     // PR 7 steer-pause wiring.
     mode,
     consumeSteerPending: () => consumeSteerPending(agentId),
-    // `agentc pause` self-pause: the loop reads the marker this agent's CLI
-    // dropped in the state dir and stages a snapshot-release pause from it.
-    consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
     ...(steerPause ? { pause: steerPause } : {}),
   });
   } finally {

package/src/index.ts

@@ -76,12 +76,16 @@ export {
   humanApproval,
   requireScope,
   redactPattern,
+  createGatePauseProcessor,
 } from "./processors/index.js";
 export type {
   Processor,
   ProcessorContext,
   ProcessorVerdict,
   ToolCall,
+  GatePausePolicy,
+  GatePauseApproval,
+  GatePauseConnection,
 } from "./processors/index.js";
 
 // Protocol types (agent-loop input/output shapes)
@@ -232,6 +236,8 @@ export type {
 // `invokeStep` (server) and `serveStep` (runner).
 export {
   invokeStep,
+  launchStep,
+  reconnectStep,
   serveStep,
   parseStepResult,
   buildStepEnvs,
@@ -256,10 +262,12 @@ export {
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
 export type { WaitForEventRequest } from "./pause/wrappers.js";
-// `agentc pause` writes a local pause-request marker the agent loop consumes
-// (the snapshot-release bridge); the CLI imports the writer.
-export { writeLocalPauseRequest, consumeLocalPauseRequest } from "./agent/local-pause-request.js";
-export type { LocalPauseRequest, PauseOption } from "./agent/local-pause-request.js";
+// ADR-0028 — the in-sandbox pause client. `agentc pause` and the gate-pause
+// processor both pause their OWN run through the server pause API and block
+// until a human answers (create-then-poll; the VM suspends in place while
+// parked). No marker, no exception threaded through workflow code.
+export { requestPauseAndAwait } from "./agent/pause-client.js";
+export type { PauseDecision, RequestPauseOptions } from "./agent/pause-client.js";
 export type {
   StepRequest,
   StepResult,
@@ -268,6 +276,8 @@ export type {
   StepHandler,
   StepHandlerResult,
   ServeStepRequest,
+  RunningStep,
+  InvokeStepOptions,
 } from "./step-invocation/index.js";
 
 // Agent loop — for workflows that embed an LLM agent in their run() body.

package/src/processors/gate-pause.ts

@@ -0,0 +1,94 @@
+/**
+ * Gate-pause processor (ADR-0028).
+ *
+ * A pre-tool gate that, when its `policy` flags a tool call as needing human
+ * approval, pauses the run as a SERVER operation (`requestPauseAndAwait`) and
+ * blocks until a human answers — then allows or denies the tool.
+ *
+ * It pauses through the server pause API (`requestPauseAndAwait`), so the pause
+ * is a server operation no `try/catch` can swallow. It does NOT use today's
+ * `ctx.pause`, which still throws `PauseSignal` — exactly the swallowable path
+ * ADR-0028 supersedes for agents. (Routing `ctx.pause` itself through this same
+ * server pause is the natural unification — ADR-0028 open question — at which
+ * point "the pause API" and "ctx.pause" become one thing.) Because it lives in
+ * the shared `gateToolCall` chain, one implementation covers every runtime — the
+ * Claude Agent SDK `PreToolUse` hook and the ACP `session/request_permission`
+ * path both route through it.
+ *
+ * Opt-in: the workflow/agent supplies the `policy` (which may be a heuristic or
+ * an async classifier agent). The connection defaults to the run credential in
+ * the sandbox env; absent it (local / non-sandbox), the gate is a no-op and
+ * tool calls pass through untouched.
+ */
+
+import type { Processor, ProcessorContext, ToolCall } from "./processor.js";
+import { Verdict } from "./processor.js";
+import { requestPauseAndAwait } from "../agent/pause-client.js";
+
+export interface GatePauseApproval {
+  /** Human-readable question shown on the approval UI. */
+  reason:   string;
+  /** Decision options the human picks from. Defaults to Approve / Deny. */
+  options?: Array<{ id: string; label: string }>;
+}
+
+/** Decide whether a tool call needs human approval. Return `false` to let it
+ *  through untouched, or an approval request to pause the run until a human
+ *  answers. May be async (e.g. a small classifier agent). */
+export type GatePausePolicy = (
+  call: ToolCall,
+  ctx:  ProcessorContext,
+) => (false | GatePauseApproval) | Promise<false | GatePauseApproval>;
+
+export interface GatePauseConnection { baseUrl: string; token: string; runId: string }
+
+const DENY_ANSWERS = new Set(["deny", "no", "reject", "decline", "block"]);
+
+/** Unwrap the dashboard's `{ decision }` resume payload to the raw answer text. */
+function answerText(decision: unknown): string {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision
+    ? (decision as { decision: unknown }).decision
+    : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+
+export function createGatePauseProcessor(opts: {
+  policy:      GatePausePolicy;
+  /** Override the server connection (defaults to the sandbox run-credential env). */
+  connection?: GatePauseConnection;
+}): Processor {
+  return {
+    name: "gate-pause",
+    async processToolCall(call: ToolCall, ctx: ProcessorContext) {
+      const approval = await opts.policy(call, ctx);
+      if (!approval) return Verdict.continue(call);
+
+      const conn = opts.connection ?? {
+        baseUrl: process.env.AGENT_COMPOSE_URL ?? "",
+        token:   process.env.AGENT_COMPOSE_RUN_TOKEN ?? "",
+        runId:   process.env.RUN_ID ?? "",
+      };
+      // No run credential (local / non-sandbox) — can't pause; let it through
+      // rather than hard-failing a dev invocation.
+      if (!conn.baseUrl || !conn.token || !conn.runId) return Verdict.continue(call);
+
+      const decision = await requestPauseAndAwait({
+        baseUrl: conn.baseUrl, token: conn.token, runId: conn.runId,
+        reason:  approval.reason,
+        action:  { tool: call.toolName, input: call.toolInput },
+        options: approval.options ?? [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
+        signal:  ctx.abortSignal,
+      });
+
+      const answer = answerText(decision.decision);
+      // Approve unless the human explicitly denied (or no answer came back on
+      // expiry/cancel). A free-form answer that isn't a deny word lets the tool
+      // run, with the human's guidance available to the model on the next turn.
+      if (decision.status === "resolved" && !DENY_ANSWERS.has(answer.toLowerCase())) {
+        return Verdict.continue(call);
+      }
+      const why = decision.status === "resolved" ? `denied: ${answer}` : `${decision.status} with no approval`;
+      return Verdict.deny(`Human ${why}. Tool "${call.toolName}" was not run — adjust course or ask again.`);
+    },
+  };
+}

package/src/processors/index.ts

@@ -14,3 +14,9 @@ export {
   requireScope,
   redactPattern,
 } from "./builtins.js";
+
+// ADR-0028 — server-driven human-approval gate. Pauses the run through the
+// server pause API and blocks until a human answers; covers every runtime
+// through the shared gateToolCall chain.
+export { createGatePauseProcessor } from "./gate-pause.js";
+export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";

package/src/runtimes/_cli-agent.ts

@@ -502,9 +502,7 @@ export class CliAgentRunner implements ModelExecutionContract {
     }
 
     const cmd = `${acp.command} ${acp.args.map(shellQuote).join(" ")}`.trim();
-    // Expose this agent's id to the adapter (and the tool subprocesses it
-    // spawns) so `agentc pause` scopes its state-dir marker to this agent.
-    const agentEnv = { ...acp.env, ...(this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {}) };
+    const agentEnv = { ...acp.env };
     const proc = spawnDuplex.call(this.sandbox.commands, cmd, {
       ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
       ...(Object.keys(agentEnv).length > 0 ? { envs: agentEnv } : {}),

package/src/runtimes/claude.ts

@@ -265,6 +265,14 @@ export class ClaudeRunner implements ModelExecutionContract {
       else opts.signal.addEventListener("abort", onLoopAbort, { once: true });
     }
 
+    // System-prompt append: the platform manual (agentManual, threaded from
+    // agent()) + any caller-supplied claudeMdContent. The Agent SDK does NOT
+    // auto-load CLAUDE.md from cwd (no settingSources), so without this the
+    // agent never reliably sees the manual — including how to pause.
+    const systemPromptAppend = [this.config.claudeMdContent, this.options.agentManual]
+      .filter((s): s is string => Boolean(s && s.trim()))
+      .join("\n\n");
+
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -279,15 +287,11 @@ export class ClaudeRunner implements ModelExecutionContract {
           effort: this.config.effort,
           cwd: this.options.cwd,
           abortController: queryAbort,
-          // Expose this agent's id to its tool subprocesses so `agentc pause`
-          // can scope its state-dir pause-request marker to the right agent
-          // (concurrent agent() calls share one sandbox). The loop's agentId is
-          // authoritative, so it wins over a stale env / config value.
-          env: { ...process.env, ...(this.config.env ?? {}), ...(this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {}) },
+          env: { ...process.env, ...(this.config.env ?? {}) },
           pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable
             ?? process.env.CLAUDE_CODE_EXECUTABLE
             ?? DEFAULT_CLAUDE_PATH,
-          ...(this.config.claudeMdContent ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: this.config.claudeMdContent } } : {}),
+          ...(systemPromptAppend ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: systemPromptAppend } } : {}),
           // Turn skills ON (and auto-add the `Skill` tool). The agent-env
           // bakes the `/ac:*` skills; without this the Agent SDK leaves
           // them un-enabled and the agent can't invoke them.

package/src/sandbox.ts

@@ -10,12 +10,12 @@ import { dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { Sandbox, SandboxNotFoundError, RateLimitError } from "e2b";
-import type { SandboxNetworkOpts as E2bNetworkOpts, SandboxNetworkRule as E2bNetworkRule } from "e2b";
+import type { SandboxNetworkOpts as E2bNetworkOpts, SandboxNetworkRule as E2bNetworkRule, CommandHandle } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
 import type { FailedAttemptError } from "p-retry";
 import { SandboxUnavailableError } from "./sandbox-errors.js";
-import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
+import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult, SandboxCommandRunOptions, SandboxBackgroundProcess } from "./types/sandbox.js";
 import type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 import type { NetworkPolicy as VercelNetworkPolicy, NetworkPolicyRule as VercelNetworkPolicyRule } from "@vercel/sandbox";
 
@@ -363,14 +363,69 @@ function withSnapshotRetry(p: SandboxProvider): SandboxProvider {
   return { ...p, snapshot: () => withSandboxRetry(snapshot) };
 }
 
+/** Wrap an E2B `CommandHandle` as a provider-agnostic background process.
+ *  `wait()` is normalised NOT to throw on a non-zero exit (mirroring the
+ *  `commands.run` contract in `makeSandboxProvider`) so callers branch on
+ *  `exitCode` instead of catching. */
+function wrapE2bBackgroundProcess(handle: CommandHandle): SandboxBackgroundProcess {
+  return {
+    pid: handle.pid,
+    async wait() {
+      try {
+        const r = await handle.wait();
+        return { exitCode: r.exitCode ?? 0, stdout: r.stdout, stderr: r.stderr };
+      } catch (e) {
+        const ce = e as { exitCode?: unknown; stdout?: unknown; stderr?: unknown };
+        if (typeof ce.exitCode === "number") {
+          return {
+            exitCode: ce.exitCode,
+            stdout: typeof ce.stdout === "string" ? ce.stdout : "",
+            stderr: typeof ce.stderr === "string" ? ce.stderr : "",
+          };
+        }
+        throw e;
+      }
+    },
+    async kill() { await handle.kill(); },
+  };
+}
+
 /** E2B base provider + live-filesystem snapshot. E2B's `createSnapshot()` captures
  *  the running sandbox as a persistent snapshot whose id is usable as a
  *  `Sandbox.create()` source and outlives the origin sandbox — so E2B reaches
  *  snapshot / `bootFrom` parity with Vercel, and snapshot-backed `ctx.pause` works
  *  on E2B. (Desktop intentionally omits this — it is registry-only, not selectable.) */
 function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
+  const base = makeSandboxProvider(sb);
   return {
-    ...makeSandboxProvider(sb),
+    ...base,
+    commands: {
+      ...base.commands,
+      // ADR-0028: background launch + reconnect-by-pid. The step runner runs as
+      // a background command so a server-driven pause can freeze it mid-turn
+      // (pauseProcess) and the resume activity can re-attach by pid and await
+      // its exit — continuing the SAME process, no re-run. E2B-only; Vercel's
+      // provider omits these and pauses via snapshot + re-run.
+      async runBackground(cmd, opts) {
+        const { sudo, onStdout, onStderr, ...rest } = (opts ?? {}) as SandboxCommandRunOptions;
+        const handle = await sb.commands.run(cmd, {
+          ...rest,
+          background: true,
+          ...(sudo ? { user: "root" } : {}),
+          ...(onStdout ? { onStdout } : {}),
+          ...(onStderr ? { onStderr } : {}),
+        });
+        return wrapE2bBackgroundProcess(handle);
+      },
+      async connectProcess(pid, opts) {
+        const handle = await sb.commands.connect(pid, {
+          ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+          ...(opts?.onStdout ? { onStdout: opts.onStdout } : {}),
+          ...(opts?.onStderr ? { onStderr: opts.onStderr } : {}),
+        });
+        return wrapE2bBackgroundProcess(handle);
+      },
+    },
     async snapshot() {
       // Raw capture — the transient pause/reclaim race is retried centrally:
       // createSandbox/reconnectSandbox wrap every provider's snapshot() in
@@ -379,6 +434,14 @@ function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    // ADR-0027: native VM-suspend. Freezes the live process in place (zero
+    // compute) and returns the sandbox id as the resume handle — resume is
+    // `reconnectSandbox(...)` (Sandbox.connect), which auto-resumes a paused VM.
+    // Distinct from snapshot(): no FS image, no kill, no re-run from the top.
+    async pauseProcess() {
+      await sb.pause();
+      return { resumeHandle: sb.sandboxId };
+    },
     // Push a freshly-resolved egress policy onto the live sandbox via E2B's
     // native `updateNetwork` — the E2B analogue of Vercel's `update({
     // networkPolicy })`. Lets the server re-resolve the run policy (re-minting

package/src/step-invocation/index.ts

@@ -27,7 +27,8 @@ export {
   stepInputPath,
   requestContextPath,
 } from "./protocol.js";
-export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export { invokeStep, launchStep, reconnectStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export type { RunningStep, InvokeStepOptions } from "./invoker.js";
 export { serveStep } from "./server.js";
 export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
 export { StepExecutionError } from "./types.js";