@agent-compose/sdk 0.5.9 → 0.6.0

package/dist/agent/agent-loop.d.ts

@@ -9,7 +9,6 @@ import type { Processor } from "../processors/processor.js";
 import { type BoundaryPauseFn } from "../pause/pause-core.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { type SteerPayload } from "./steer-control.js";
-import { type LocalPauseRequest } from "./local-pause-request.js";
 export declare const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 export declare function parseAgentStatus(text: string): AgentStatus | null;
 export interface AgentLoopResult<TResponse = unknown> {
@@ -148,13 +147,6 @@ export interface AgentLoopOpts<TResponse = unknown> {
      *  The boundary consumes it once per check, and only when no steer is
      *  already staged. */
     consumeSteerPending?: () => SteerPayload | null;
-    /** Take-once read of a local `agentc pause` request this agent dropped in the
-     *  state dir during its turn (the CLI writes it; see local-pause-request.ts).
-     *  Returns the request (reason + offered options) or null. The loop turns it
-     *  into a staged self-pause the next boundary takes — the same snapshot-release
-     *  path as `needs_input`, but triggered by an explicit `agentc pause` call so
-     *  it is honored regardless of `mode`. */
-    consumeLocalPauseRequest?: () => LocalPauseRequest | null;
     /** PR 7: `auto` (autonomous, default) or `hitl` (can be steer-paused). The
      *  boundary is inert unless `hitl`. */
     mode?: "auto" | "hitl";

package/dist/agent/pause-client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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;
+export declare function requestPauseAndAwait(opts: RequestPauseOptions, fetchImpl?: FetchFn): Promise<PauseDecision>;
+export {};

package/dist/index.d.ts

@@ -23,8 +23,8 @@ export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
 export { RequestContext, ReservedKeyError, NonSerialisableValueError, AC_RESERVED_PREFIX, AC_TEAM_ID, AC_RUN_ID, AC_WORKFLOW_ID, AC_FACTORY_ID, AC_API_KEY_SCOPES, AC_PARENT_RUN_ID, AC_ABORT_SIGNAL, } from "./request-context/index.js";
 export type { RequestContextReserved, RequestContextWire, } from "./request-context/index.js";
-export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, } from "./processors/index.js";
-export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from "./processors/index.js";
+export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, createGatePauseProcessor, } from "./processors/index.js";
+export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, GatePausePolicy, GatePauseApproval, GatePauseConnection, } from "./processors/index.js";
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
@@ -59,14 +59,14 @@ export type { WorkflowResult, RunWorkflowOptions, EngineSubsystem } from "./work
 export { buildInvokeChild } from "./workflows/invoke-child.js";
 export { defineStep, isWorkflow, runWorkflowSteps, runWorkflowSingleStep, StepValidationError, WorkflowInputValidationError, WorkflowOutputValidationError, } from "./workflow-steps/index.js";
 export type { Step, StepContext, StepRunResult, Workflow, DefineStepOpts, StepWorkflowDefinition, WorkflowBuilder, RunWorkflowStepsOpts, RunWorkflowStepsResult, RunWorkflowSingleStepOpts, RunWorkflowSingleStepResult, StepObservability, SubStepEvent, } from "./workflow-steps/index.js";
-export { invokeStep, serveStep, parseStepResult, buildStepEnvs, StepExecutionError, STEP_RESULT_PREFIX, STEP_PAUSE_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./step-invocation/index.js";
+export { invokeStep, launchStep, reconnectStep, serveStep, parseStepResult, buildStepEnvs, StepExecutionError, STEP_RESULT_PREFIX, STEP_PAUSE_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./step-invocation/index.js";
 export { PauseError, PauseExpiredError, PauseSchemaError, PauseRequestError, } from "./pause/errors.js";
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
 export type { WaitForEventRequest } from "./pause/wrappers.js";
-export { writeLocalPauseRequest, consumeLocalPauseRequest } from "./agent/local-pause-request.js";
-export type { LocalPauseRequest, PauseOption } from "./agent/local-pause-request.js";
-export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest, StepHandler, StepHandlerResult, ServeStepRequest, } from "./step-invocation/index.js";
+export { requestPauseAndAwait } from "./agent/pause-client.js";
+export type { PauseDecision, RequestPauseOptions } from "./agent/pause-client.js";
+export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest, StepHandler, StepHandlerResult, ServeStepRequest, RunningStep, InvokeStepOptions, } from "./step-invocation/index.js";
 export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent-loop.js";
 export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
 export { agent } from "./agent/run-agent.js";

package/dist/index.js

@@ -1103,6 +1103,98 @@ function redactPattern(pattern, replacement = "[REDACTED]") {
     }
   };
 }
+// src/agent/pause-client.ts
+var isAbort = (signal) => Boolean(signal?.aborted);
+async function requestPauseAndAwait(opts, fetchImpl = fetch) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const headers = {
+    authorization: `Bearer ${opts.token}`,
+    "content-type": "application/json",
+    accept: "application/json"
+  };
+  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();
+  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;
+    try {
+      res = await fetchImpl(pollUrl, { method: "GET", headers, ...opts.signal ? { signal: opts.signal } : {} });
+    } catch (err) {
+      if (isAbort(opts.signal))
+        throw err;
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      continue;
+    }
+    if (!res.ok) {
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      continue;
+    }
+    backoffMs = 0;
+    const body = await res.json();
+    if (body.status === "pending")
+      continue;
+    return { status: body.status, decision: body.resumePayload ?? null };
+  }
+}
+
+// src/processors/gate-pause.ts
+var DENY_ANSWERS = new Set(["deny", "no", "reject", "decline", "block"]);
+function answerText(decision) {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision ? decision.decision : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+function createGatePauseProcessor(opts) {
+  return {
+    name: "gate-pause",
+    async processToolCall(call, ctx) {
+      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 ?? ""
+      };
+      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);
+      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.`);
+    }
+  };
+}
 // src/client.ts
 import { ofetch } from "ofetch";
 
@@ -2178,19 +2270,6 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
       }
       lastResponseText = responseText;
       let status = parseAgentStatus(responseText);
-      if (opts.pause && pendingSteerPause === null) {
-        const localPause = opts.consumeLocalPauseRequest?.() ?? null;
-        if (localPause) {
-          pendingSteerPause = {
-            reason: localPause.reason,
-            correlationKey: null,
-            ...localPause.options && localPause.options.length > 0 ? { payload: { options: localPause.options } } : {},
-            at: Date.now()
-          };
-          blockerStreak = null;
-          continue;
-        }
-      }
       const rawResponse = opts.responseSchema ? parseAgentResponse(responseText) ?? parseRawJsonResponse(responseText) : null;
       const validateResponse = (target) => {
         const parsed = opts.responseSchema.safeParse(target);
@@ -2523,6 +2602,9 @@ class ClaudeRunner {
       else
         opts.signal.addEventListener("abort", onLoopAbort, { once: true });
     }
+    const systemPromptAppend = [this.config.claudeMdContent, this.options.agentManual].filter((s) => Boolean(s && s.trim())).join(`
+
+`);
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -2537,9 +2619,9 @@ class ClaudeRunner {
           effort: this.config.effort,
           cwd: this.options.cwd,
           abortController: queryAbort,
-          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", preset: "claude_code", append: this.config.claudeMdContent } } : {},
+          ...systemPromptAppend ? { systemPrompt: { type: "preset", preset: "claude_code", append: systemPromptAppend } } : {},
           skills: this.config.skills ?? "all",
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
@@ -3051,7 +3133,7 @@ class CliAgentRunner {
       throw new Error("spawnAcpProcess called on a provider without commands.spawnDuplex");
     }
     const cmd = `${acp.command} ${acp.args.map(shellQuote).join(" ")}`.trim();
-    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 } : {}
@@ -3401,13 +3483,64 @@ function withSnapshotRetry(p) {
   const snapshot = p.snapshot.bind(p);
   return { ...p, snapshot: () => withSandboxRetry(snapshot) };
 }
+function wrapE2bBackgroundProcess(handle) {
+  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;
+        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();
+    }
+  };
+}
 function makeE2bSandboxProvider(sb) {
+  const base = makeSandboxProvider(sb);
   return {
-    ...makeSandboxProvider(sb),
+    ...base,
+    commands: {
+      ...base.commands,
+      async runBackground(cmd, opts) {
+        const { sudo, onStdout, onStderr, ...rest } = opts ?? {};
+        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() {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    async pauseProcess() {
+      await sb.pause();
+      return { resumeHandle: sb.sandboxId };
+    },
     async updateNetworkPolicy(policy) {
       await sb.updateNetwork(toE2bNetwork(policy));
     }
@@ -4478,25 +4611,11 @@ function parseStepResult(stdout, resultToken) {
   const message = baseMessage;
   return { ok: false, error: { kind, message } };
 }
-async function invokeStep(sandbox, request, opts) {
-  const resultToken = randomBytes2(16).toString("hex");
-  await Promise.all([
-    sandbox.files.write(stepInputPath(request.stepIndex), JSON.stringify(request.input)),
-    sandbox.files.write(requestContextPath(request.stepIndex), JSON.stringify(request.requestContext))
-  ]);
-  const envs = {
-    ...opts?.envs ?? {},
-    ...buildStepEnvs({
-      runId: request.runId,
-      stepIndex: request.stepIndex,
-      resultToken,
-      isResume: opts?.isResume
-    })
-  };
+function makeStreamSplitters(opts, resultToken) {
   const resultSentinel = stepResultLinePrefix(resultToken);
   const pauseSentinel = stepPauseLinePrefix(resultToken);
   const isSentinel = (line) => line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
-  const makeLineSplitter = (sink, filterSentinel) => {
+  const make = (sink, filterSentinel) => {
     if (!sink)
       return { onChunk: undefined, flush: () => {} };
     let buf = "";
@@ -4524,29 +4643,19 @@ async function invokeStep(sandbox, request, opts) {
       }
     };
   };
-  const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
-  const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
-  let result;
-  try {
-    result = await sandbox.commands.run(RUNNER_COMMAND, {
-      envs,
-      timeoutMs: 0,
-      ...stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {},
-      ...stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}
-    });
-  } catch (e) {
-    if (e instanceof SandboxUnavailableError)
-      throw e;
-    const ce = e;
-    result = {
-      stdout: ce.stdout ?? ce.result?.stdout ?? "",
-      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
-      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
-    };
-  }
-  stdoutSplitter.flush();
-  stderrSplitter.flush();
-  const parsed = parseStepResult(result.stdout, resultToken);
+  const stdout = make(opts?.onStdout, true);
+  const stderr = make(opts?.onStderr, false);
+  return {
+    ...stdout.onChunk ? { onStdout: stdout.onChunk } : {},
+    ...stderr.onChunk ? { onStderr: stderr.onChunk } : {},
+    flush: () => {
+      stdout.flush();
+      stderr.flush();
+    }
+  };
+}
+async function classifyRunnerOutcome(sandbox, output, resultToken) {
+  const parsed = parseStepResult(output.stdout, resultToken);
   if (parsed)
     return parsed;
   const fileRead = await sandbox.commands.run(`cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`).catch(() => null);
@@ -4555,9 +4664,9 @@ async function invokeStep(sandbox, request, opts) {
     if (fromFile)
       return fromFile;
   }
-  if (result.exitCode !== 0) {
-    const stderrTail = result.stderr.trim().slice(-2000);
-    const stdoutTail = result.stdout.trim().slice(-2000);
+  if (output.exitCode !== 0) {
+    const stderrTail = output.stderr.trim().slice(-2000);
+    const stdoutTail = output.stdout.trim().slice(-2000);
     const details = [
       stderrTail ? `stderr:
 ${stderrTail}` : "",
@@ -4569,13 +4678,13 @@ ${stdoutTail}` : ""
       ok: false,
       error: {
         kind: "runner-exit",
-        message: `runner subprocess exited ${result.exitCode} before emitting a step result${details ? `
+        message: `runner subprocess exited ${output.exitCode} before emitting a step result${details ? `
 ${details}` : ""}`,
-        exitCode: result.exitCode
+        exitCode: output.exitCode
       }
     };
   }
-  const tail = result.stdout.trim().slice(-500);
+  const tail = output.stdout.trim().slice(-500);
   return {
     ok: false,
     error: {
@@ -4586,6 +4695,99 @@ ${tail}` : ""}`
     }
   };
 }
+async function prepareStepLaunch(sandbox, request, opts) {
+  const resultToken = randomBytes2(16).toString("hex");
+  await Promise.all([
+    sandbox.files.write(stepInputPath(request.stepIndex), JSON.stringify(request.input)),
+    sandbox.files.write(requestContextPath(request.stepIndex), JSON.stringify(request.requestContext))
+  ]);
+  const envs = {
+    ...opts?.envs ?? {},
+    ...buildStepEnvs({ runId: request.runId, stepIndex: request.stepIndex, resultToken, isResume: opts?.isResume })
+  };
+  return { resultToken, envs };
+}
+async function invokeStep(sandbox, request, opts) {
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
+  let result;
+  try {
+    result = await sandbox.commands.run(RUNNER_COMMAND, {
+      envs,
+      timeoutMs: 0,
+      ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+      ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+    const ce = e;
+    result = {
+      stdout: ce.stdout ?? ce.result?.stdout ?? "",
+      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
+      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
+    };
+  }
+  splitters.flush();
+  return classifyRunnerOutcome(sandbox, result, resultToken);
+}
+async function launchStep(sandbox, request, opts) {
+  if (!sandbox.commands.runBackground) {
+    throw new Error("launchStep requires a provider with background-command support (commands.runBackground)");
+  }
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
+  const proc = await sandbox.commands.runBackground(RUNNER_COMMAND, {
+    envs,
+    timeoutMs: 0,
+    ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+    ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+  });
+  return {
+    runnerPid: proc.pid,
+    resultToken,
+    async wait() {
+      const result = await proc.wait();
+      splitters.flush();
+      return classifyRunnerOutcome(sandbox, result, resultToken);
+    }
+  };
+}
+async function reconnectStep(sandbox, resume, opts) {
+  if (!sandbox.commands.connectProcess) {
+    throw new Error("reconnectStep requires a provider with background-command support (commands.connectProcess)");
+  }
+  const { runnerPid, resultToken } = resume;
+  const splitters = makeStreamSplitters(opts, resultToken);
+  let proc = null;
+  try {
+    proc = await sandbox.commands.connectProcess(runnerPid, {
+      ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+      ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+  }
+  const attached = proc;
+  return {
+    runnerPid,
+    resultToken,
+    async wait() {
+      let output = { stdout: "", stderr: "", exitCode: 0 };
+      if (attached) {
+        try {
+          output = await attached.wait();
+        } catch (e) {
+          if (e instanceof SandboxUnavailableError)
+            throw e;
+        }
+      }
+      splitters.flush();
+      return classifyRunnerOutcome(sandbox, output, resultToken);
+    }
+  };
+}
 // src/step-invocation/server.ts
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 function writeSentinelLine(line) {
@@ -4692,41 +4894,6 @@ async function serveStep(handler) {
   await emitResult(token, payload);
   process.exit(exitCode);
 }
-// src/agent/local-pause-request.ts
-import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join3 } from "node:path";
-import { randomBytes as randomBytes3 } from "node:crypto";
-var UNSCOPED = "_unscoped";
-var requestsDir = () => join3(getStateDir(), "pause-requests");
-var markerPath = (agentId) => join3(requestsDir(), `${slug(agentId) || UNSCOPED}.json`);
-function slug(agentId) {
-  return (agentId ?? "").replace(/[^a-zA-Z0-9_.-]/g, "_");
-}
-function writeLocalPauseRequest(agentId, req) {
-  mkdirSync2(requestsDir(), { recursive: true });
-  const final = markerPath(agentId);
-  const tmp = `${final}.${randomBytes3(6).toString("hex")}.tmp`;
-  writeFileSync2(tmp, JSON.stringify(req), "utf8");
-  renameSync(tmp, final);
-}
-function consumeLocalPauseRequest(agentId) {
-  const paths = [...new Set([markerPath(agentId), markerPath(null)])];
-  for (const path of paths) {
-    if (!existsSync(path))
-      continue;
-    try {
-      const raw = JSON.parse(readFileSync2(path, "utf8"));
-      rmSync(path, { force: true });
-      if (raw && typeof raw === "object" && typeof raw.reason === "string" && raw.reason.trim().length > 0) {
-        const r = raw;
-        return { reason: r.reason.trim(), ...Array.isArray(r.options) && r.options.length > 0 ? { options: r.options } : {} };
-      }
-    } catch {
-      rmSync(path, { force: true });
-    }
-  }
-  return null;
-}
 // src/agent/run-agent.ts
 import { z as z12 } from "zod";
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -5055,7 +5222,7 @@ async function agent(opts) {
   const mode = opts.mode ?? "auto";
   try {
     return await agentLoop({
-      runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
+      runtime: (runtimeOpts) => 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 } : {},
@@ -5093,7 +5260,6 @@ async function agent(opts) {
       ...inbox ? { inbox } : {},
       mode,
       consumeSteerPending: () => consumeSteerPending(agentId),
-      consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
       ...steerPause ? { pause: steerPause } : {}
     });
   } finally {
@@ -5103,7 +5269,6 @@ async function agent(opts) {
 }
 export {
   writeTool,
-  writeLocalPauseRequest,
   writeAgentContext,
   stepInputPath,
   snapshotResolves,
@@ -5113,8 +5278,10 @@ export {
   runWorkflow,
   runProcessorChain,
   requireScope,
+  requestPauseAndAwait,
   requestContextPath,
   redactPattern,
+  reconnectStep,
   reconnectSandbox,
   readTool,
   parseStepResult,
@@ -5127,6 +5294,7 @@ export {
   makeDesktopSandboxProvider,
   listVercelRuntimeModels,
   listOwnedSandboxes,
+  launchStep,
   killSandboxById,
   killAllSandboxes,
   isWorkflow,
@@ -5149,10 +5317,10 @@ export {
   defineRuntime,
   createVercelRuntime,
   createSandbox,
+  createGatePauseProcessor,
   createCodexRuntime,
   createClaudeRuntime,
   createAmpRuntime,
-  consumeLocalPauseRequest,
   codingTools,
   codex_default as codexRuntime,
   claude_default as claudeRuntime,

package/dist/processors/gate-pause.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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";
+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;
+}
+export declare function createGatePauseProcessor(opts: {
+    policy: GatePausePolicy;
+    /** Override the server connection (defaults to the sandbox run-credential env). */
+    connection?: GatePauseConnection;
+}): Processor;

package/dist/processors/gate-pause.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/processors/index.d.ts

@@ -2,3 +2,5 @@ export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from ".
 export { Verdict } from "./processor.js";
 export { runProcessorChain } from "./runner.js";
 export { denyTools, humanApproval, requireScope, redactPattern, } from "./builtins.js";
+export { createGatePauseProcessor } from "./gate-pause.js";
+export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";