@agent-compose/sdk 0.5.8 → 0.5.9

package/src/agent/local-pause-request.ts

@@ -0,0 +1,90 @@
+/**
+ * Local pause-request marker — the in-sandbox bridge from `agentc pause` to
+ * the agent loop's snapshot-release pause boundary.
+ *
+ * `agentc pause` runs as a grandchild subprocess of the runner (the agent CLI
+ * shells out to it). It cannot throw a `PauseSignal` into the loop and the
+ * in-memory steer flag (`signalSteerPending`) lives in a different process, so
+ * the only reliable channel is the shared sandbox filesystem. The CLI writes a
+ * durable marker here; the agent loop consumes it at the end of the turn
+ * (alongside the `needs_input` self-pause) and stages a real `ctx.pause` the
+ * next boundary takes — which snapshots the sandbox, releases the activity
+ * (compute stops), and parks the workflow. On resume the human's answer is
+ * delivered as the agent's next user turn.
+ *
+ * This is the ONLY place the marker path + shape are defined — both the CLI
+ * (writer) and the SDK loop (reader) import it, so the two halves can never
+ * drift. Like the rest of the state-dir, the layout is a wire protocol between
+ * the runner and the next subprocess invocation (ADR-0006). The marker is
+ * consumed BEFORE the snapshot, so it never needs to survive a pause.
+ *
+ * Scoped by `agentId` so concurrent `agent()` calls sharing one sandbox each
+ * see only their own request. When the id is unavailable (older agent env that
+ * doesn't inject `AGENT_COMPOSE_AGENT_ID`) both sides fall back to a single
+ * unscoped slot — correct for the common single-agent step, and the only case
+ * where an unscoped marker can be ambiguous (two anonymous agents) is one the
+ * old block-poll CLI couldn't handle either.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+import { getStateDir } from "../pause/state-dir.js";
+
+/** A choice offered to the human. A bare string is shorthand for
+ *  `{ label, value }` with both equal — exactly what the dashboard's
+ *  `readOptions` accepts. */
+export type PauseOption = string | { label: string; value: string };
+
+/** What `agentc pause` records for the loop to turn into a `ctx.pause`. */
+export interface LocalPauseRequest {
+  /** The question shown to the human (becomes the pause `reason`). */
+  reason:   string;
+  /** Optional offered choices, rendered as buttons in the dashboard. */
+  options?: PauseOption[];
+}
+
+const UNSCOPED = "_unscoped";
+
+const requestsDir = () => join(getStateDir(), "pause-requests");
+const markerPath  = (agentId: string | undefined | null) =>
+  join(requestsDir(), `${slug(agentId) || UNSCOPED}.json`);
+
+/** Keep the agentId filename-safe. Agent ids are `step<idx>-agent-<n>` shaped,
+ *  but defend against anything exotic so the marker can never escape the dir. */
+function slug(agentId: string | undefined | null): string {
+  return (agentId ?? "").replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+/** Write the marker atomically (tmp → rename) so the loop never reads a
+ *  partial file mid-write. Called by `agentc pause`. */
+export function writeLocalPauseRequest(agentId: string | undefined | null, req: LocalPauseRequest): void {
+  mkdirSync(requestsDir(), { recursive: true });
+  const final = markerPath(agentId);
+  const tmp   = `${final}.${randomBytes(6).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify(req), "utf8");
+  renameSync(tmp, final);
+}
+
+/** Take-once read: returns + deletes this agent's pending pause request, else
+ *  null. Checks the agent-scoped slot first, then the unscoped fallback. The
+ *  loop calls this once per turn; a malformed marker is dropped (deleted +
+ *  null) rather than wedging the loop. */
+export function consumeLocalPauseRequest(agentId: string | undefined | null): LocalPauseRequest | null {
+  const paths = [...new Set([markerPath(agentId), markerPath(null)])]; // dedupe when agentId is absent
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+      rmSync(path, { force: true });
+      if (raw && typeof raw === "object" && typeof (raw as LocalPauseRequest).reason === "string" && (raw as LocalPauseRequest).reason.trim().length > 0) {
+        const r = raw as LocalPauseRequest;
+        return { reason: r.reason.trim(), ...(Array.isArray(r.options) && r.options.length > 0 ? { options: r.options } : {}) };
+      }
+    } catch {
+      rmSync(path, { force: true }); // unreadable / partial → drop it
+    }
+  }
+  return null;
+}

package/src/agent/run-agent.ts

@@ -13,9 +13,10 @@
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
-import { corePause } from "../pause/pause-core.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";
@@ -315,7 +316,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
   const activeStepForPause = getActiveStep();
   const steerPause = activeStepForPause && runId
     ? function steerPauseFn<T>(
-        req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
+        req: PauseRequest<T>,
         agentScope: { agentId: string; iteration: number },
       ): Promise<T> {
         return corePause<T>(req, {
@@ -365,6 +366,9 @@ 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/agent/steer-control.ts

@@ -17,13 +17,27 @@
 import { z } from "zod";
 
 /** What a steer/resume answer carries. Used as the boundary pause's `schema`
- *  so it is validated client-side in the re-spawned runner — a null/empty
- *  message is rejected (PauseSchemaError) so an agent never resumes on an
- *  empty steer. `message` becomes the agent's next user turn. */
-export const SteerDecisionSchema = z.object({
-  message: z.string().min(1),
-  actor:   z.string().nullish(),
-});
+ *  so it is validated client-side in the re-spawned runner — an empty answer
+ *  is rejected (PauseSchemaError) so an agent never resumes on nothing. The
+ *  normalised `message` becomes the agent's next user turn.
+ *
+ *  Accepts BOTH resume-payload conventions and normalises to `{ message }`:
+ *    - `{ message }` — the SDK / API steer convention (`answerSteer`).
+ *    - `{ decision }` — what the dashboard's RunPausePanel universally sends
+ *      for every pause (option click or free text). Without this, resuming an
+ *      agent steer / `needs_input` / `agentc pause` pause from the dashboard
+ *      failed schema validation in the re-spawned runner and the agent never
+ *      got the answer — the resume looked like it did nothing. */
+export const SteerDecisionSchema = z
+  .object({
+    message:  z.string().min(1).optional(),
+    decision: z.string().min(1).optional(),
+    actor:    z.string().nullish(),
+  })
+  .transform((d) => ({ message: (d.message ?? d.decision ?? "").trim(), actor: d.actor ?? null }))
+  .refine((d) => d.message.length > 0, {
+    message: "a steer/resume answer needs a non-empty `message` or `decision`",
+  });
 export type SteerDecision = z.infer<typeof SteerDecisionSchema>;
 
 /** Metadata a pending steer carries from the control message to the boundary

package/src/client.ts

@@ -103,7 +103,8 @@ export interface RegisterWorkflowInput {
   /** All snapshot config — `bootFrom` (where to restore at run start),
    *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
   snapshots?: SnapshotConfig;
-  /** Sandbox machine size (template default). See `WorkflowMetadata.resources`. */
+  /** Sandbox machine resources — size + provider (template defaults).
+   *  See `WorkflowMetadata.resources`. */
   resources?: SandboxResources;
   /** Provider-neutral execution plan detected by the CLI bundler. */
   workflowPlan?: WorkflowPlan;
@@ -121,6 +122,10 @@ export interface RegisterWorkflowInput {
   inputSchema?: IOSchema;
   /** Output schema extracted from the workflow's `output` zod schema. */
   outputSchema?: IOSchema;
+  /** Set by `defineSandboxEnvironment` — marks an environment build so the
+   *  server skips the /factory mount for its runs (#13). See
+   *  `WorkflowMetadata.environmentBuild`. */
+  environmentBuild?: boolean;
   /** Factory slug. Defaults to `"default"`. */
   factorySlug?: string;
 }
@@ -1240,6 +1245,35 @@ export class AgentComposeClient {
     return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
   }
 
+  // ── Factory-level secrets (ADR-0014) ────────────────────────────────────────
+  // The inherited tier: a factory secret is visible to EVERY workflow in the
+  // factory; a workflow secret of the same key overrides it. Values are stored
+  // in GCP Secret Manager; never returned by reads.
+
+  /** Create or update a factory-level secret. */
+  setFactorySecret(key: string, value: string, opts?: SecretOptions): Promise<SetSecretResult> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`, {
+      method: "POST",
+      body: { key, value },
+    });
+  }
+
+  /** List factory-level secret keys (metadata only — values are never returned). */
+  async listFactorySecrets(opts?: SecretOptions): Promise<SecretListEntry[]> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`,
+    );
+    return body.secrets.map(s => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+
+  /** Delete a factory-level secret. */
+  deleteFactorySecret(key: string, opts?: SecretOptions): Promise<void> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
+  }
+
   // ── API keys ───────────────────────────────────────────────────────────────
   // Both endpoints require an admin-scoped key as the bearer token.
 

package/src/index.ts

@@ -73,6 +73,7 @@ export {
   Verdict,
   runProcessorChain,
   denyTools,
+  humanApproval,
   requireScope,
   redactPattern,
 } from "./processors/index.js";
@@ -179,9 +180,12 @@ export type { RunEvent } from "./types/events.js";
 
 // Sandbox providers
 export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
-  getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot,
+  getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, snapshotResolves,
   makeSandboxProvider, makeDesktopSandboxProvider,
-  parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
+  parseSseExecStream, AGENT_COMPOSE_TAG,
+  SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES,
+  isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
+  isPlatformE2bTemplateAlias } from "./sandbox.js";
 export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 export type {
   SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform,
@@ -252,6 +256,10 @@ 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";
 export type {
   StepRequest,
   StepResult,

package/src/pause/checkpoint.ts

@@ -1,5 +1,6 @@
 /**
- * `ctx.checkpoint(name, fn)` — disk-backed memoise across pause-resume.
+ * Disk-backed memoise across pause-resume — the engine behind durable
+ * `ctx.step(name, fn)` (ADR-0012).
  *
  * First call: `fn()` runs, the result is atomically written to
  * `/tmp/wf/state/checkpoints/<name>.json`. On any subsequent invocation
@@ -16,29 +17,47 @@
  * memoisation is in-sandbox only and would silently retry on a sandbox
  * recreation that lost the checkpoint file.
  *
- * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+ * INTERNAL only — there is no public `ctx.checkpoint`. The durable
+ * `ctx.step` wires `scopedMemoize("step<idx>")` and reports a "restored"
+ * sub-step on a cache hit. See ADR-0012.
  */
 
 import { assertSafeCheckpointName, readCheckpoint, writeCheckpoint } from "./state-dir.js";
 
-/** Read-or-run-and-write helper. `name` is validated by the state-dir
- *  layer (rejects path-escape attempts); `fn` is awaited if it returns
- *  a Promise so sync and async callers compose identically. */
-export async function checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T> {
+/** Result of a memoise call — `restored` distinguishes a disk hit (fn was
+ *  NOT run, value read from a prior subprocess) from a fresh run (fn ran,
+ *  value just written). The durable `ctx.step` maps `restored` onto the
+ *  duration-0 "restored" sub-step status. */
+export interface MemoizeResult<T> {
+  value:    T;
+  restored: boolean;
+}
+
+/** Read-or-run-and-write helper reporting whether the value was restored
+ *  from disk. `name` is validated by the state-dir layer (rejects
+ *  path-escape attempts); `fn` is awaited if it returns a Promise so sync
+ *  and async callers compose identically.
+ *
+ *  A pause inside `fn` (PauseSignal) propagates BEFORE any write — a
+ *  partially-completed body is never memoised, so the resume re-runs it. */
+export async function memoize<T>(name: string, fn: () => Promise<T> | T): Promise<MemoizeResult<T>> {
   const existing = await readCheckpoint<T>(name);
-  if (existing.found) return existing.value;
+  if (existing.found) return { value: existing.value, restored: true };
   const value = await fn();
   await writeCheckpoint(name, value);
-  return value;
+  return { value, restored: false };
 }
 
-/** Bind user checkpoint names to a runner-owned namespace. The user's
- *  `name` is still validated independently so a scope prefix cannot turn
- *  an empty or path-escaping name into a valid filename. */
-export function scopedCheckpoint(scope: string): typeof checkpoint {
+/** A memoise function bound to a runner-owned scope. */
+export type ScopedMemoize = <T>(name: string, fn: () => Promise<T> | T) => Promise<MemoizeResult<T>>;
+
+/** Bind memoise names to a runner-owned namespace (e.g. `step<idx>`). The
+ *  caller's `name` is still validated independently so a scope prefix
+ *  cannot turn an empty or path-escaping name into a valid filename. */
+export function scopedMemoize(scope: string): ScopedMemoize {
   assertSafeCheckpointName(scope);
-  return async <T>(name: string, fn: () => Promise<T> | T): Promise<T> => {
+  return async <T>(name: string, fn: () => Promise<T> | T): Promise<MemoizeResult<T>> => {
     assertSafeCheckpointName(name);
-    return checkpoint(`${scope}.${name}`, fn);
+    return memoize(`${scope}.${name}`, fn);
   };
 }

package/src/pause/manager.ts

@@ -44,7 +44,7 @@ const RunningAgentLoopStateSchema = z.object({
   blockerStreak:               z.object({ key: z.string(), count: z.number().int().nonnegative() }).nullable(),
   // PR 7: a human-requested steer-pause intent, persisted so it survives a
   // resume and the loop re-issues the boundary pause on re-entry.
-  pendingSteerPause:            z.object({ reason: z.string(), correlationKey: z.string().nullable(), at: z.number().int() }).nullable().default(null),
+  pendingSteerPause:            z.object({ reason: z.string(), correlationKey: z.string().nullable(), at: z.number().int(), payload: z.record(z.string(), z.unknown()).optional() }).nullable().default(null),
 });
 
 const SettledAgentLoopStateSchema = z.object({
@@ -76,7 +76,7 @@ export interface AgentLoopProgressState {
   blockerStreak:               { key: string; count: number } | null;
   /** PR 7 steer-pause intent — see RunningAgentLoopStateSchema. Optional so the
    *  loop can omit it until it wires steer (the schema defaults it to null). */
-  pendingSteerPause?:           { reason: string; correlationKey: string | null; at: number } | null;
+  pendingSteerPause?:           { reason: string; correlationKey: string | null; at: number; payload?: Record<string, unknown> } | null;
 }
 
 export interface SettledAgentLoopResult<TResponse = unknown> {

package/src/pause/pause-core.ts

@@ -94,6 +94,41 @@ export function isPauseSignal(err: unknown): err is PauseSignal {
   return typeof err === "object" && err !== null && (err as Record<symbol, unknown>)[PAUSE_SIGNAL_BRAND] === true;
 }
 
+/**
+ * The run's pause boundary. The runner (`run-agent` `steerPause`) closes a
+ * `corePause` over the ambient `runId`/`stepIndex`; the agent loop / runtime
+ * supplies the per-iteration `agentScope` so the pauseId stays stable across
+ * the loop's iteration-skipping on resume. Absent outside a workflow step
+ * (local / non-sandbox callers) — see `boundProcessorPause`.
+ */
+export type BoundaryPauseFn = <T = unknown>(
+  req: PauseRequest<T>,
+  agentScope: { agentId: string; iteration: number },
+) => Promise<T>;
+
+/**
+ * Build the `ProcessorContext.pause` callable for a given hook scope: binds the
+ * boundary to this hook's `{ agentId, iteration }` so a processor calling
+ * `ctx.pause(req)` gets a deterministic, resume-stable pauseId. When no boundary
+ * is wired (local tests, non-sandbox callers), the returned fn rejects loudly
+ * rather than silently no-op'ing — pause genuinely cannot work without the
+ * runner's snapshot/Temporal machinery.
+ */
+export function boundProcessorPause(
+  boundary: BoundaryPauseFn | undefined,
+  scope: { agentId: string; iteration: number },
+): <T = unknown>(req: PauseRequest<T>) => Promise<T> {
+  return <T = unknown>(req: PauseRequest<T>): Promise<T> => {
+    if (!boundary) {
+      return Promise.reject(new PauseRequestError(
+        "ctx.pause is unavailable here: no pause boundary is wired (a processor can " +
+        "only pause inside a sandboxed workflow step, not in a local/unit-test run)",
+      ));
+    }
+    return boundary(req, scope);
+  };
+}
+
 // ── Deterministic pauseId ───────────────────────────────────────────────────
 
 /** Fixed namespace for agent-compose pause ids (UUIDv5). Constant — must

package/src/pause/state-dir.ts

@@ -6,7 +6,7 @@
  *
  *   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
+ *   checkpoints/<name>.json          ← durable `ctx.step(name, fn)` memoised values (keyed `step<idx>.<name>`)
  *   pauses/<pauseId>.json            ← pause records (request + resume payload once available)
  *
  * Atomic writes (write-tmp → fsync → rename) so a mid-write `sandbox.snapshot()`
@@ -50,7 +50,7 @@ const pausePath        = (pauseId: string)         => join(pausesDir(), `${pause
 
 /** `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.
+ *  `ctx.step("../../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

package/src/processors/builtins.ts

@@ -4,7 +4,8 @@
  * exist as load-bearing examples and as defaults for common policies.
  */
 
-import type { Processor } from "./processor.js";
+import { z } from "zod";
+import type { Processor, ToolCall } from "./processor.js";
 import { Verdict } from "./processor.js";
 
 /**
@@ -27,6 +28,48 @@ export function denyTools(names: readonly string[]): Processor {
   };
 }
 
+/** Resume payload a reviewer sends back to a `humanApproval` pause. */
+const ApprovalDecision = z.object({
+  approved: z.boolean(),
+  reason:   z.string().optional(),
+});
+
+/**
+ * Pause the run for HUMAN APPROVAL before a matching tool executes — the
+ * human-in-the-loop pre-tool gate (ADR-0006 `ctx.pause`). Over an ACP runtime
+ * this is exactly the `session/request_permission` path: the CLI asks to run a
+ * tool, the gate runs here, and `ctx.pause` snapshots the workflow and waits
+ * durably until a reviewer resolves the pause with `{ approved, reason? }`.
+ * Approve → the tool runs; deny → the reason is returned to the model as the
+ * tool result and the loop continues.
+ *
+ *   tools?  — only these tool names require approval (default: EVERY tool call).
+ *   reason? — build the human-facing prompt from the call (default names the tool).
+ *
+ * Dormant on runtimes without pre-tool gating; active on those that wire
+ * `processToolCall` (the ACP CLI runtimes, the Claude pre-tool hook, Vercel).
+ */
+export function humanApproval(opts?: {
+  tools?:  readonly string[];
+  reason?: (call: ToolCall) => string;
+}): Processor {
+  const gated = opts?.tools ? new Set(opts.tools) : null;
+  return {
+    name: "humanApproval",
+    async processToolCall(call, ctx) {
+      if (gated && !gated.has(call.toolName)) return Verdict.continue(call);
+      const decision = await ctx.pause({
+        reason:  opts?.reason?.(call) ?? `Approve tool call: ${call.toolName}`,
+        payload: { tool: call.toolName, input: call.toolInput, toolUseId: call.toolUseId },
+        schema:  ApprovalDecision,
+      });
+      return decision.approved
+        ? Verdict.continue(call)
+        : Verdict.deny(decision.reason ?? `tool "${call.toolName}" denied by human reviewer`);
+    },
+  };
+}
+
 /**
  * Require the calling API key to carry every scope in `required`. Aborts the
  * agent loop with a clear reason if any are missing — defence-in-depth on

package/src/processors/index.ts

@@ -10,6 +10,7 @@ export { runProcessorChain } from "./runner.js";
 
 export {
   denyTools,
+  humanApproval,
   requireScope,
   redactPattern,
 } from "./builtins.js";

package/src/processors/processor.ts

@@ -30,6 +30,7 @@
 
 import type { AgentMessage } from "../types/protocol.js";
 import type { RequestContext } from "../request-context/request-context.js";
+import type { PauseRequest } from "../pause/pause-core.js";
 
 /** Proposed tool call. Mirrors the relevant fields of AgentMessageToolUse but
  *  lives as its own type so runtime adapters (candidate #1) can populate it
@@ -53,6 +54,18 @@ export interface ProcessorContext {
   agentId:        string;
   /** Iteration of the agent loop (1-based). */
   iteration:      number;
+  /**
+   * Pause the run from inside a processor — the human-approval primitive for a
+   * pre-tool-use gate (ADR-0006 §"reachable from every user code path";
+   * ADR-0020 the ACP `session/request_permission` path). On the fresh pass it
+   * throws `PauseSignal` (internal control flow) so the workflow snapshots and
+   * waits durably; on step re-entry after resolution it returns the resume
+   * payload (validated against `req.schema` if given). The agent loop / runtime
+   * wires it to the run's pause boundary with a deterministic, resume-stable
+   * pauseId (keyed on this hook's agentId + iteration). Calling it outside a
+   * sandboxed workflow step throws — pause requires the runner's pause boundary.
+   */
+  pause<T = unknown>(req: PauseRequest<T>): Promise<T>;
 }
 
 /**