@agent-compose/sdk 0.5.1 → 0.5.5

package/src/agent/run-agent.ts

@@ -11,8 +11,13 @@
  */
 
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
+import { corePause } from "../pause/pause-core.js";
 import { agentLoop } from "./agent-loop.js";
+import { consumeSteerPending, runControlPoller } from "./steer-control.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";
@@ -21,8 +26,82 @@ import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
 import PROTOCOL_SUFFIX_RAW from "./protocol-suffix.md" with { type: "text" };
 
+/**
+ * Long-poll the per-run inbox for a specific agent and push each
+ * delivered message into the agent loop's input queue. Runs concurrent
+ * with the agent loop and stops when the agent settles (`signal`
+ * aborts).
+ *
+ * Resilient to network blips: a failed fetch is logged + retried after
+ * a short backoff. The user's message survives in the DB so the next
+ * successful poll picks it up — the poller is the consumer, not the
+ * durable store.
+ */
+async function runInboxPoller(opts: {
+  baseUrl:    string;
+  token:      string;
+  runId:      string;
+  agentId:    string;
+  inbox:      AsyncQueue<{ text: string; senderName?: string | null }>;
+  signal:     AbortSignal;
+}): Promise<void> {
+  let afterSeq = 0;
+  const headers = {
+    "authorization": `Bearer ${opts.token}`,
+    "accept":        "application/json",
+  } as const;
+  let backoffMs = 0;
+  while (!opts.signal.aborted) {
+    if (backoffMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      if (opts.signal.aborted) return;
+    }
+    const url = `${opts.baseUrl.replace(/\/+$/, "")}` +
+      `/api/v1/internal/runs/${opts.runId}/agents/${encodeURIComponent(opts.agentId)}/inbox?afterSeq=${afterSeq}`;
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: opts.signal });
+      if (!res.ok) {
+        // 401/403 = token expired or wrong run — stop polling, the
+        // agent's run is no longer reachable via this token. Other
+        // codes: back off and retry.
+        if (res.status === 401 || res.status === 403) return;
+        backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+        continue;
+      }
+      backoffMs = 0;
+      const body = await res.json() as { messages?: Array<{ seq: number; body: string; senderName: string | null }> };
+      for (const m of body.messages ?? []) {
+        opts.inbox.push({ text: m.body, senderName: m.senderName });
+        if (m.seq > afterSeq) afterSeq = m.seq;
+      }
+    } catch (err) {
+      if (opts.signal.aborted) return;
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      // Don't spam stderr — one warning per session is enough; the
+      // backoff escalates on its own.
+      if (backoffMs >= 4_000) {
+        process.stderr.write(`[inbox-poller] poll failed, backing off ${backoffMs}ms: ${err instanceof Error ? err.message : String(err)}\n`);
+      }
+    }
+  }
+}
+
 const PROTOCOL_SUFFIX = stripFrontmatter(PROTOCOL_SUFFIX_RAW);
 
+/** Appended to a `mode: "hitl"` agent's first prompt so it knows it may stop
+ *  and ask a human. Self-pause is opt-in per agent — an autonomous (`auto`)
+ *  agent never sees this and has no way to halt the workflow itself. */
+const HITL_ASK_INSTRUCTION = [
+  "## Asking a human",
+  "",
+  "If you hit a decision or need information only a human can provide, set " +
+    "`\"needs_input\": true` in your `<status>` block, put your question in a " +
+    "`\"question\"` field, set `\"exit_signal\": false`, and stop. The workflow " +
+    "pauses and a human answers; their reply arrives as your next message. Use " +
+    "this only when you genuinely cannot proceed on your own — prefer making a " +
+    "reasonable decision and continuing.",
+].join("\n");
+
 function stripFrontmatter(content: string): string {
   if (!content.startsWith("---")) return content;
   const end = content.indexOf("\n---", 3);
@@ -91,6 +170,11 @@ export interface AgentOpts<T = unknown> {
   tools?: string[];
   /** Turn/iteration caps. Defaults: 40 turns/iteration, 8 iterations. */
   budget?: AgentBudget;
+  /** Steerability (PR 7). `auto` (default) runs autonomously and ignores steer
+   *  requests; `hitl` lets a human pause this agent mid-run via the steer route
+   *  — the loop checks for a pending steer at each iteration boundary and only
+   *  `hitl` agents run the control poller. */
+  mode?: "auto" | "hitl";
   /** If set, the loop demands a `<response>` block when `exit_signal=true`
    *  and validates it against this schema. The response format appendix is
    *  appended to the prompt on first iteration. */
@@ -129,16 +213,92 @@ export interface AgentOpts<T = unknown> {
 }
 
 /**
- * Run an agent loop inside a workflow. Returns the loop's final
- * `AgentLoopResult`, including `response` when a `responseSchema` was
- * supplied and the model validated against it.
+ * Resolve the `agentId` for an `agent()` call. Resolution order:
+ *   1. Caller-supplied `explicitId` (the workflow author owns the id).
+ *   2. Step-mode derivation `step<idx>-agent-<callOrder>` — deterministic
+ *      across a pause-resume re-entry: the same step body re-executes in the
+ *      same call order, so the same id recovers `agent-<id>.json`. The step
+ *      index comes from the active-step context (set by the step runner),
+ *      NOT `process.env.AC_STEP_INDEX` — `serveStep` scrubs that before the
+ *      step body runs, which would orphan the state file on every resume
+ *      (see `active-step.ts`).
+ *   3. `randomUUID()` outside step mode (local tests, dev).
  */
+export function resolveAgentId(explicitId?: string): string {
+  if (explicitId) return explicitId;
+  const activeCall = nextAgentCallInActiveStep();
+  if (activeCall === null) return randomUUID();
+  return `step${activeCall.stepIndex}-agent-${activeCall.callIndex}`;
+}
+
 export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopResult<T>> {
   const workingDir = opts.workingDir ?? "";
 
-  return agentLoop({
+  // Stable agentId for this invocation. Used by the inbox URL (server
+  // scopes pending messages by agentId), the agentLoop (which would
+  // otherwise generate its own), AND the pause state-dir keys
+  // (`agent-<id>.json` / `runtime-<id>.json`). The pause-resume path
+  // re-enters the step from the top in a new subprocess, so the id MUST
+  // be deterministic across invocations — see `resolveAgentId`, which
+  // derives it from the active-step context rather than scrubbed env.
+  const agentId = resolveAgentId(opts.agentId);
+
+  // Wire up the runner-side inbox if the surrounding sandbox carries
+  // the run-callback token. Absent token = no inbox (local tests, non-
+  // sandbox callers); agent loop runs in legacy single-prompt mode.
+  const callbackUrl   = process.env.AGENT_COMPOSE_URL;
+  const callbackToken = process.env.AGENT_COMPOSE_RUN_TOKEN;
+  const runId         = process.env.RUN_ID;
+  const inbox = (callbackUrl && callbackToken && runId)
+    ? new AsyncQueue<{ text: string; senderName?: string | null }>()
+    : undefined;
+  const inboxAbort = new AbortController();
+  if (inbox && callbackUrl && callbackToken && runId) {
+    void runInboxPoller({
+      baseUrl: callbackUrl, token: callbackToken, runId, agentId, inbox,
+      signal:  inboxAbort.signal,
+    });
+  }
+  // Control poller (PR 7): long-polls the per-run control channel so a human
+  // steer-pause request reaches this agent and sets its take-once flag. Every
+  // agent polls — a human can steer ANY running agent regardless of `mode`
+  // (`mode` only governs whether the agent may pause itself). Shares the
+  // agent's abort signal — the finally below stops it with the inbox.
+  if (callbackUrl && callbackToken && runId) {
+    void runControlPoller({
+      baseUrl: callbackUrl, token: callbackToken, runId, agentId,
+      signal:  inboxAbort.signal,
+    });
+  }
+
+  // PR 7: the boundary's pause callable. Built from the ambient run/step
+  // context (RUN_ID + active step) so the loop never reads process.env or the
+  // active-step ALS itself — it stays unit-testable with a fake `pause`. The
+  // loop supplies the per-iteration agentScope so the pauseId is stable across
+  // resume. Absent outside step mode (local/non-workflow callers) ⇒ no steer.
+  const activeStepForPause = getActiveStep();
+  const steerPause = activeStepForPause && runId
+    ? function steerPauseFn<T>(
+        req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
+        agentScope: { agentId: string; iteration: number },
+      ): Promise<T> {
+        return corePause<T>(req, {
+          runId,
+          stepIndex: activeStepForPause.stepIndex,
+          agentScope,
+        });
+      }
+    : undefined;
+
+  // `auto` (default) runs autonomously; `hitl` may pause itself to ask a human
+  // (the boundary self-pause trigger + the prompt instruction above). Human
+  // steering works regardless — see the ungated control poller.
+  const mode = opts.mode ?? "auto";
+
+  try {
+  return await agentLoop({
     runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, runtimeOpts),
-    ...(opts.agentId !== undefined ? { agentId: opts.agentId } : {}),
+    agentId,
     ...(opts.label !== undefined ? { label: opts.label } : {}),
     ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),
     ...(opts.budget?.maxIterations     !== undefined ? { maxIterations:     opts.budget.maxIterations }     : {}),
@@ -150,9 +310,12 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
       // protocol suffix is needed so tool-use + status block grammar stays fresh.
       if (iteration > 0) return PROTOCOL_SUFFIX;
       const base = stripFrontmatter(opts.prompt);
-      return opts.responseSchema
-        ? `${base}\n\n${PROTOCOL_SUFFIX}\n\n${buildResponseFormatAppendix(opts.responseSchema)}`
-        : `${base}\n\n${PROTOCOL_SUFFIX}`;
+      const parts = [base, PROTOCOL_SUFFIX];
+      // hitl agents learn the self-pause protocol on their first turn; the model
+      // carries it across the session, so it isn't re-sent every iteration.
+      if (mode === "hitl") parts.push(HITL_ASK_INSTRUCTION);
+      if (opts.responseSchema) parts.push(buildResponseFormatAppendix(opts.responseSchema));
+      return parts.join("\n\n");
     },
     ...(opts.events ? { onAgentLifecycleEvent: (event: AgentLifecycleEvent) => { void opts.events?.emit(event); } } : {}),
     ...(opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {}),
@@ -162,5 +325,18 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
       teamId: "", runId: "", workflowId: "",
       factoryId: null, apiKeyScopes: [], parentRunId: null,
     }),
+    ...(inbox ? { inbox } : {}),
+    // PR 7 steer-pause wiring.
+    mode,
+    consumeSteerPending: () => consumeSteerPending(agentId),
+    ...(steerPause ? { pause: steerPause } : {}),
   });
+  } finally {
+    // Tear down the poller exactly once the agent loop returns
+    // (success, throw, or abort). Closing the queue first prevents
+    // the runtime from waiting on more inbox items; aborting stops
+    // the long-poll's pending fetch.
+    inbox?.close();
+    inboxAbort.abort();
+  }
 }

package/src/agent/steer-control.ts

@@ -0,0 +1,125 @@
+/**
+ * Steer-control (PR 7) — the in-sandbox half of "a human pauses a running
+ * agent." A `runControlPoller` long-polls the per-run control channel; when a
+ * `steer_pause` for this agent arrives it sets a per-agentId **take-once**
+ * flag. The agent loop consumes the flag at its next iteration boundary
+ * (`consumeSteerPending`) and takes a `ctx.pause` there (commit 6).
+ *
+ * Lives in its own module so both `run-agent.ts` (the poller, the signal) and
+ * `agent-loop.ts` (the consume) import it without a cycle.
+ *
+ * The flag is **transient** and best-effort: a steer NOTIFY that arrives while
+ * the poller is between long-poll requests is missed (no durable backing — the
+ * route writes no row). The human re-requests; the loop only commits a durable
+ * `run_pauses` row once it reaches a boundary and takes the pause.
+ */
+
+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(),
+});
+export type SteerDecision = z.infer<typeof SteerDecisionSchema>;
+
+/** Metadata a pending steer carries from the control message to the boundary
+ *  that turns it into a durable pause row. The flag store used to be a bare
+ *  `Set<string>` carrying none of this, so the committed `run_pauses` row
+ *  always had `correlation_key = null` and `reason = "human steer"` —
+ *  `resumePauseByKey` could never match and the operator's reason was lost. */
+export interface SteerPayload {
+  reason:         string | null;
+  correlationKey: string | null;
+}
+
+// Per-agentId FIFO queue of pending steers. Keyed by agentId (concurrent
+// `agent()` calls in one step body each have a distinct id), not a single
+// process-global flag — so one agent's steer can't be consumed by another.
+// A queue (not a single slot) so two distinct keyed steers each produce their
+// own correlatable pause instead of the second being silently dropped. Steers
+// that share a correlationKey (including the common null-key "just pause" case)
+// coalesce to the latest, so a double-click never piles up redundant pauses.
+const steerPending = new Map<string, SteerPayload[]>();
+
+/** Enqueue a pending steer-pause for `agentId` (called by the poller). A steer
+ *  whose correlationKey matches one already queued replaces it (idempotent);
+ *  a distinct key is appended. */
+export function signalSteerPending(agentId: string, payload: SteerPayload): void {
+  const queue = steerPending.get(agentId) ?? [];
+  const existing = queue.findIndex((p) => p.correlationKey === payload.correlationKey);
+  if (existing >= 0) queue[existing] = payload;
+  else queue.push(payload);
+  steerPending.set(agentId, queue);
+}
+
+/** Take-once read: dequeues and returns the next pending steer's payload for
+ *  `agentId` (FIFO), else null. The boundary calls this exactly once per check
+ *  so a single steer can't re-fire on the post-resume continuation; a second
+ *  queued steer surfaces at the next boundary. */
+export function consumeSteerPending(agentId: string): SteerPayload | null {
+  const queue = steerPending.get(agentId);
+  if (queue === undefined || queue.length === 0) return null;
+  const next = queue.shift()!;
+  if (queue.length === 0) steerPending.delete(agentId);
+  return next;
+}
+
+interface ControlMessage {
+  kind?:           string;
+  agentId?:        string | null;
+  reason?:         string | null;
+  correlationKey?: string | null;
+}
+
+/**
+ * Long-poll the per-run control channel and set the steer flag for this agent.
+ * Mirrors `runInboxPoller`: same per-run HMAC token, same backoff, stops on
+ * 401/403 (token expired / wrong run). The server holds each request open
+ * until a control message lands or the long-poll window elapses, so this
+ * loops mostly blocked in `fetch`.
+ */
+export async function runControlPoller(opts: {
+  baseUrl: string;
+  token:   string;
+  runId:   string;
+  agentId: string;
+  signal:  AbortSignal;
+}): Promise<void> {
+  const headers = { authorization: `Bearer ${opts.token}`, accept: "application/json" } as const;
+  const url = `${opts.baseUrl.replace(/\/+$/, "")}/api/v1/internal/runs/${opts.runId}/control`;
+  let backoffMs = 0;
+  while (!opts.signal.aborted) {
+    if (backoffMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      if (opts.signal.aborted) return;
+    }
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: opts.signal });
+      if (!res.ok) {
+        if (res.status === 401 || res.status === 403) return; // token expired / wrong run
+        backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+        continue;
+      }
+      backoffMs = 0;
+      const body = await res.json() as { control?: ControlMessage | null };
+      const ctrl = body.control;
+      // agentId === null ⇒ steer all agents on the run; else this agent only.
+      if (ctrl && ctrl.kind === "steer_pause" && (ctrl.agentId == null || ctrl.agentId === opts.agentId)) {
+        signalSteerPending(opts.agentId, {
+          reason:         ctrl.reason ?? null,
+          correlationKey: ctrl.correlationKey ?? null,
+        });
+      }
+    } catch (err) {
+      if (opts.signal.aborted) return;
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      if (backoffMs >= 4_000) {
+        process.stderr.write(`[control-poller] poll failed, backing off ${backoffMs}ms: ${err instanceof Error ? err.message : String(err)}\n`);
+      }
+    }
+  }
+}

package/src/client.ts

@@ -236,6 +236,105 @@ export interface RunStatus<TOutput = unknown> {
   output?: TOutput;
 }
 
+/** ADR-0006 step 10 — actor record returned on a successful resume.
+ *  Shape mirrors the server's `PauseResumeActor` type after the row
+ *  has been stamped. Audit FKs (`userId` / `keyId` / `runId`) may be
+ *  null when the referenced row was deleted between resume and the
+ *  response render — the immutable `label` survives. */
+export interface ResumePauseActor {
+  kind:     "session_user" | "api_key" | "agent";
+  /** Better Auth user id when kind='session_user'. */
+  userId?:  string | null;
+  /** api_keys.id when kind='api_key'. */
+  keyId?:   string | null;
+  /** Caller-run id when kind='agent' (NOT the run being resumed). */
+  runId?:   string | null;
+  /** Agent-instance within `runId` when kind='agent'. */
+  agentId?: string | null;
+  label:    string;
+}
+
+/** Success branch of the resume HTTP response. The pause has reached
+ *  a terminal state — `resolved` (workflow signal arrived), `expired`
+ *  (TTL fired first), or `cancelled` (workflow terminated mid-pause).
+ *  Only `resolved` carries the resume payload the user supplied. */
+export interface ResumePauseSuccess {
+  status:        "resolved" | "expired" | "cancelled";
+  pauseId:       string;
+  resolvedAt:    string | null;
+  resumePayload: unknown;
+  actor:         ResumePauseActor | null;
+}
+
+/** Pending branch — the workflow accepted the signal but the row
+ *  flip didn't observe within the route's 5s wait window. The
+ *  operation is in-flight; retry with the same `Idempotency-Key`
+ *  and the cache collapses the duplicate to a single canonical
+ *  response. */
+export interface ResumePausePending {
+  status:   "pending";
+  pauseId:  string;
+  timedOut: true;
+}
+
+export type ResumePauseResponse = ResumePauseSuccess | ResumePausePending;
+
+export interface ResumePauseOptions {
+  /** Stripe-style retry-dedup key — same syntax as the workflow-invoke
+   *  route: 1..255 chars of `[A-Za-z0-9_\-:.]`, no embedded CR/LF.
+   *  Sent as the `Idempotency-Key` request header. (The server reads the
+   *  header first, falling back to a body field for callers behind a
+   *  header-stripping proxy; this client only sends the header.) */
+  idempotencyKey?: string;
+  /** Abort the HTTP request mid-wait (e.g. from a UI cancel button).
+   *  The server's LISTEN tears down via the request's AbortSignal. */
+  signal?:         AbortSignal;
+}
+
+export interface RequestAgentPauseOptions {
+  /** Human-readable note surfaced to the agent as the pause reason. */
+  reason?:         string;
+  /** Your handle for answering this pause without the minted pauseId:
+   *  pass the same value to `resumePauseByKey`. */
+  correlationKey?: string;
+  /** Abort the HTTP request. */
+  signal?:         AbortSignal;
+}
+
+export interface AnswerSteerOptions extends ResumePauseOptions {
+  /** Who answered — surfaced to the agent as `[human steer from <actor>]`. */
+  actor?: string;
+}
+
+/** 202 envelope from a steer-pause request. The request is best-effort and
+ *  fire-and-forget: it publishes a transient control message and returns
+ *  immediately — the agent parks at its next iteration boundary (if it is
+ *  `mode: "hitl"` and still running). Answer it via `answerSteerByKey`
+ *  (pass the `correlationKey` you set here) or `answerSteer` (by pauseId). */
+export interface RequestAgentPauseResponse {
+  status:  "steer_requested";
+  runId:   string;
+  agentId: string;
+}
+
+export interface SendAgentMessageOptions {
+  /** Transcript attribution. For non-session callers (API key, orchestrator)
+   *  this names the sender; defaults to the caller's identity server-side. */
+  senderName?: string;
+  /** Abort the HTTP request. */
+  signal?:     AbortSignal;
+}
+
+/** 202 envelope from a message-to-running-agent request. The message is queued
+ *  durably and delivered mid-stream as the agent's next user turn — the workflow
+ *  is NOT paused. `seq` is the message's per-run ordinal. */
+export interface SendAgentMessageResponse {
+  status:  "message_enqueued";
+  runId:   string;
+  agentId: string;
+  seq:     number;
+}
+
 export interface RunDetail<TOutput = unknown> {
   runId: string;
   title: string;
@@ -429,6 +528,17 @@ export interface AgentComposeClientOptions {
 
 const PUBLIC_API_HOST = "https://api.agentcompose.ai";
 
+/** Build the `SteerDecisionSchema` resume payload from a steer answer. Rejects
+ *  an empty message client-side so the caller gets a synchronous error rather
+ *  than a delayed, fatal run failure when the in-sandbox schema check rejects
+ *  it. The `{ message }` shape is exactly what the steer boundary validates. */
+function steerAnswerPayload(message: string, actor?: string): { message: string; actor?: string } {
+  if (typeof message !== "string" || message.trim().length === 0) {
+    throw new Error("answerSteer: `message` must be a non-empty string");
+  }
+  return { message, ...(actor !== undefined ? { actor } : {}) };
+}
+
 export class AgentComposeClient {
   private readonly fetch:   typeof ofetch;
   private readonly baseUrl: string;
@@ -583,6 +693,173 @@ export class AgentComposeClient {
     return this.fetch(`/api/v1/workflows/${runId}/status`);
   }
 
+  // ── Pause-resume (ADR-0006 step 10) ───────────────────────────────────
+  //
+  // Resume a paused run via its pauseId OR its correlationKey. The
+  // server emits the workflow signal, holds the response for up to
+  // ~5s waiting on the row to flip terminal, then returns the
+  // resolved/expired/cancelled state (200) — or a pending+timedOut
+  // envelope (202) if the wait fires first. Either response shape
+  // carries the same `pauseId`.
+
+  /** Resume a paused run by pause id.
+   *
+   *  Returns the terminal state on success (200) or a pending
+   *  envelope (202) if the server's 5s wait timed out. For the
+   *  pending case, retry with the same `idempotencyKey` — the
+   *  server-side cache collapses duplicates to a single canonical
+   *  response once the workflow's row-flip lands.
+   *
+   *  Throws `AgentComposeError` on 4xx/5xx — 404 when the run or
+   *  pause doesn't exist, 403 when the caller lacks scope or the
+   *  run-token cross-run/cross-agent gate fails, 409 when the
+   *  `Idempotency-Key` was reused against a different operation.
+   */
+  async resumePause(
+    runId:   string,
+    pauseId: string,
+    payload: unknown,
+    opts?:   ResumePauseOptions,
+  ): Promise<ResumePauseResponse> {
+    const headers: Record<string, string> = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.fetch<ResumePauseResponse>(
+      `/api/v1/runs/${encodeURIComponent(runId)}/pauses/${encodeURIComponent(pauseId)}/resume`,
+      {
+        method: "POST",
+        body:   { resumePayload: payload },
+        ...(Object.keys(headers).length ? { headers } : {}),
+        ...(opts?.signal ? { signal: opts.signal } : {}),
+      },
+    );
+  }
+
+  /** Resume a paused run by correlation key. The correlation key is
+   *  the second resume key set on `ctx.pause({ correlationKey })`;
+   *  the server resolves it to a unique pending pause within the
+   *  run, then delegates to the same handler as `resumePause`.
+   *
+   *  The key is `encodeURIComponent`'d at the call site, so callers
+   *  pass the literal value (containing `/`, `:`, etc. as written).
+   */
+  async resumePauseByKey(
+    runId:          string,
+    correlationKey: string,
+    payload:        unknown,
+    opts?:          ResumePauseOptions,
+  ): Promise<ResumePauseResponse> {
+    const headers: Record<string, string> = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.fetch<ResumePauseResponse>(
+      `/api/v1/runs/${encodeURIComponent(runId)}/pauses/by-key/${encodeURIComponent(correlationKey)}/resume`,
+      {
+        method: "POST",
+        body:   { resumePayload: payload },
+        ...(Object.keys(headers).length ? { headers } : {}),
+        ...(opts?.signal ? { signal: opts.signal } : {}),
+      },
+    );
+  }
+
+  /** Answer a steer-pause by its `correlationKey` (PR 7) — the typed,
+   *  footgun-free way to resume a `requestAgentPause`.
+   *
+   *  The steer boundary validates its resume payload against
+   *  `SteerDecisionSchema` (`{ message }`) inside the re-spawned runner; a bare
+   *  string or wrong-shaped payload passed to `resumePause`/`resumePauseByKey`
+   *  fails that check and terminates the run. This wraps `message` in the
+   *  expected shape so the answer is always well-formed. `message` becomes the
+   *  agent's next user turn. Pass the `correlationKey` you gave
+   *  `requestAgentPause`.
+   *
+   *  Throws `AgentComposeError` on 4xx/5xx — 404 when no pending steer matches
+   *  the key. Throws synchronously if `message` is empty. */
+  async answerSteerByKey(
+    runId:          string,
+    correlationKey: string,
+    message:        string,
+    opts?:          AnswerSteerOptions,
+  ): Promise<ResumePauseResponse> {
+    return this.resumePauseByKey(runId, correlationKey, steerAnswerPayload(message, opts?.actor), opts);
+  }
+
+  /** Answer a steer-pause by its minted `pauseId`. Use this when you learned
+   *  the pauseId out of band (e.g. from the `pause_requested` lifecycle event);
+   *  otherwise prefer {@link answerSteerByKey}. Same `{ message }` wrapping and
+   *  validation as `answerSteerByKey`. */
+  async answerSteer(
+    runId:   string,
+    pauseId: string,
+    message: string,
+    opts?:   AnswerSteerOptions,
+  ): Promise<ResumePauseResponse> {
+    return this.resumePause(runId, pauseId, steerAnswerPayload(message, opts?.actor), opts);
+  }
+
+  /** Request that a running agent pause for human steering (PR 7).
+   *
+   *  Three callers share this route — an operator (session/api-key), another
+   *  agent or external orchestrator (run-callback token), and this method.
+   *  It is fire-and-forget: the server publishes a transient control message
+   *  and returns 202 immediately. The agent takes the pause at its next
+   *  iteration boundary — but only if it was started `mode: "hitl"` and is
+   *  still running; an `auto` agent ignores it. Delivery is best-effort (a
+   *  steer arriving between the in-sandbox poller's long-polls is missed —
+   *  re-request). Once the agent parks, answer it with `answerSteerByKey` (by
+   *  the `correlationKey` you pass here) or `answerSteer` (by the minted
+   *  pauseId) — these wrap the answer in the shape the steer boundary
+   *  validates. The human's `message` becomes the agent's next user turn.
+   *
+   *  Throws `AgentComposeError` on 4xx/5xx — 404 when the run doesn't exist,
+   *  403 when the caller lacks scope or the run-token gate fails.
+   */
+  async requestAgentPause(
+    runId:   string,
+    agentId: string,
+    opts?:   RequestAgentPauseOptions,
+  ): Promise<RequestAgentPauseResponse> {
+    const body: { reason?: string; correlationKey?: string } = {};
+    if (opts?.reason         !== undefined) body.reason         = opts.reason;
+    if (opts?.correlationKey !== undefined) body.correlationKey = opts.correlationKey;
+    return this.fetch<RequestAgentPauseResponse>(
+      `/api/v1/runs/${encodeURIComponent(runId)}/agents/${encodeURIComponent(agentId)}/pause`,
+      {
+        method: "POST",
+        body,
+        ...(opts?.signal ? { signal: opts.signal } : {}),
+      },
+    );
+  }
+
+  /** Send a message to a RUNNING agent — the lightweight steer (PR 7).
+   *
+   *  Durable and **non-halting**: the message is queued and delivered to the
+   *  agent mid-stream as its next user turn, *without* pausing the workflow.
+   *  This is the efficient way to nudge or redirect an agent that should keep
+   *  running — reserve `requestAgentPause` for when it must stop and wait. The
+   *  message lands at the agent's next iteration boundary (it finishes the
+   *  current model turn first). `senderName` sets the transcript attribution.
+   *
+   *  Throws `AgentComposeError` on 4xx/5xx — 404 unknown run, 403 scope/gate.
+   */
+  async sendAgentMessage(
+    runId:   string,
+    agentId: string,
+    message: string,
+    opts?:   SendAgentMessageOptions,
+  ): Promise<SendAgentMessageResponse> {
+    const body: { message: string; senderName?: string } = { message };
+    if (opts?.senderName !== undefined) body.senderName = opts.senderName;
+    return this.fetch<SendAgentMessageResponse>(
+      `/api/v1/runs/${encodeURIComponent(runId)}/agents/${encodeURIComponent(agentId)}/messages`,
+      {
+        method: "POST",
+        body,
+        ...(opts?.signal ? { signal: opts.signal } : {}),
+      },
+    );
+  }
+
   /** Full run detail, including input/output and lifecycle events. */
   getRun<TOutput = unknown>(runId: string): Promise<RunDetail<TOutput>> {
     return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}`);