@agent-compose/sdk 0.5.0 → 0.5.2

package/src/active-step.ts

@@ -0,0 +1,124 @@
+/**
+ * The step currently executing in this runner subprocess.
+ *
+ * Step-mode derivations that must be byte-identical across a pause-resume
+ * re-entry — the agent loop's `agentId` (which names `agent-<id>.json`) and
+ * the pause primitive's `pauseId` — need the running step's index. They
+ * CANNOT read it from `process.env.AC_STEP_INDEX`: `serveStep` scrubs the
+ * transport envs (`AC_STEP_MODE`, `AC_STEP_INDEX`, the result token, …) from
+ * `process.env` *before* the user step body runs, so by the time `agent()` /
+ * `ctx.pause` execute those reads return `undefined`
+ * (`step-invocation/server.ts` `scrubProtocolEnvs`). Reading scrubbed env was
+ * a latent resume bug: `agentId` fell through to `randomUUID()` on every
+ * subprocess, so resume never matched the prior `agent-<id>.json`.
+ *
+ * Instead the step runner sets the index here from the un-scrubbed `stepIndex`
+ * it already holds, and the derivations read it from here.
+ *
+ * Async-local rather than process-global: public in-process execution can run
+ * multiple workflows concurrently, and ids must stay scoped to the async step
+ * body that is deriving them. A fresh subprocess on resume starts with a fresh
+ * async context, the runner re-sets the same `stepIndex`, and the per-step
+ * call-order counters re-derive identical ids — which is exactly what lets
+ * resume find its on-disk state.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface ActiveStep {
+  stepIndex: number;
+}
+
+interface ActiveStepState extends ActiveStep {
+  nextAgentCallIndex: number;
+  pauseOrdinalByScope: Map<string, number>;
+}
+
+const activeStepStorage = new AsyncLocalStorage<ActiveStepState>();
+
+// Test/dev fallback for direct `setActiveStep(...)` users. The runner uses
+// `runWithActiveStep`, so production step execution is async-local.
+let fallbackActive: ActiveStepState | null = null;
+
+// Cross-SDK-instance bridge. `bundleWorkflow` builds the workflow with
+// `Bun.build` and NO `external`, so the bundle inlines its OWN copy of this
+// module — a distinct `AsyncLocalStorage` instance from the runner's. The
+// runner sets the active step via `runWithActiveStep` on ITS instance; the
+// bundle's `agent()` reads `currentState()` on the BUNDLE's instance and would
+// otherwise see null (→ a random agentId and an unwired steer-pause). So
+// `runWithActiveStep` ALSO publishes the state on a realm-shared `globalThis`
+// slot the bundle's copy can read. Consulted ONLY when the local ALS is empty,
+// so in-process execution keeps full async-local isolation between concurrent
+// runs (the ALS takes precedence below).
+const BRIDGE_KEY = Symbol.for("agent-compose.activeStep.bridge");
+function bridgeSlot(): { state: ActiveStepState | null } {
+  const g = globalThis as unknown as Record<symbol, { state: ActiveStepState | null } | undefined>;
+  return (g[BRIDGE_KEY] ??= { state: null });
+}
+
+function makeState(step: ActiveStep): ActiveStepState {
+  return {
+    stepIndex: step.stepIndex,
+    nextAgentCallIndex: 0,
+    pauseOrdinalByScope: new Map(),
+  };
+}
+
+function currentState(): ActiveStepState | null {
+  return activeStepStorage.getStore() ?? bridgeSlot().state ?? fallbackActive;
+}
+
+/** Set (or clear, with `null`) the step currently running. Called by the
+ *  step runner around `step.run(...)`. Prefer `runWithActiveStep` for real
+ *  async execution; this setter exists for tests and small synchronous helpers. */
+export function setActiveStep(step: ActiveStep | null): void {
+  fallbackActive = step ? makeState(step) : null;
+}
+
+/** Run `fn` with a step context scoped to this async call tree. */
+export async function runWithActiveStep<T>(step: ActiveStep, fn: () => Promise<T>): Promise<T> {
+  return activeStepStorage.run(makeState(step), fn);
+}
+
+/** Publish (or clear, with `null`) the active step on the cross-instance bridge.
+ *  Called ONLY by the sandbox step runner (`runWorkflowSingleStep`), which runs
+ *  exactly one step per subprocess — so there is no concurrency to race the
+ *  single global slot. The bundle's `agent()` reads this when its own ALS is
+ *  empty. Returns the prior value so the caller can restore it. */
+export function setActiveStepBridge(step: ActiveStep | null): { state: ActiveStepState | null } {
+  const slot = bridgeSlot();
+  const prev = { state: slot.state };
+  slot.state = step ? makeState(step) : null;
+  return prev;
+}
+
+/** Restore a bridge value captured by `setActiveStepBridge`. */
+export function restoreActiveStepBridge(prev: { state: ActiveStepState | null }): void {
+  bridgeSlot().state = prev.state;
+}
+
+
+/** The step currently running, or `null` outside step execution (local
+ *  tests, dev, between steps). */
+export function getActiveStep(): ActiveStep | null {
+  const state = currentState();
+  return state ? { stepIndex: state.stepIndex } : null;
+}
+
+/** Return the next implicit `agent()` call coordinate for the active step. */
+export function nextAgentCallInActiveStep(): { stepIndex: number; callIndex: number } | null {
+  const state = currentState();
+  if (!state) return null;
+  const callIndex = state.nextAgentCallIndex;
+  state.nextAgentCallIndex += 1;
+  return { stepIndex: state.stepIndex, callIndex };
+}
+
+/** Return the next pause ordinal in `scope` for the active step invocation. */
+export function nextPauseOrdinalInActiveStep(scope: string): number | null {
+  const state = currentState();
+  if (!state) return null;
+  const next = state.pauseOrdinalByScope.get(scope) ?? 0;
+  state.pauseOrdinalByScope.set(scope, next + 1);
+  return next;
+}

package/src/agent/agent-loop.ts

@@ -11,6 +11,9 @@ import { randomUUID } from "node:crypto";
 import type { Processor, ProcessorContext } from "../processors/processor.js";
 import { runProcessorChain } from "../processors/runner.js";
 import { RequestContext } from "../request-context/request-context.js";
+import { PauseManager } from "../pause/manager.js";
+import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
+import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
 
 export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
 
@@ -42,7 +45,7 @@ export type AgentMessageSummary =
   | { type: "init"; sessionId: string }
   | { type: "text"; text: string }
   | { type: "thinking"; text: string }
-  | { type: "tool_use"; toolName: string; toolUseId: string; toolInputPreview: string }
+  | { type: "tool_use"; toolName: string; toolUseId: string; toolInput: Record<string, unknown>; toolInputPreview: string }
   | { type: "tool_result"; toolUseId: string; output: string; isError: boolean }
   | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number }
   | { type: "done"; sessionId: string }
@@ -65,7 +68,7 @@ export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
     case "init": return { type: "init", sessionId: msg.sessionId };
     case "text": return { type: "text", text: msg.text };
     case "thinking": return { type: "thinking", text: msg.text };
-    case "tool_use": return { type: "tool_use", toolName: msg.toolName, toolUseId: msg.toolUseId, toolInputPreview: preview(msg.toolInput) };
+    case "tool_use": return { type: "tool_use", toolName: msg.toolName, toolUseId: msg.toolUseId, toolInput: msg.toolInput, toolInputPreview: preview(msg.toolInput) };
     case "tool_result": return { type: "tool_result", toolUseId: msg.toolUseId, output: truncate(msg.output), isError: msg.isError };
     case "usage": return {
       type: "usage", inputTokens: msg.inputTokens, outputTokens: msg.outputTokens,
@@ -78,7 +81,16 @@ export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
 }
 
 export type AgentLifecycleEvent =
-  | { event: "agent.spawned"; at: number; agentId: string; label: string; allowedTools?: string[] }
+  | {
+      event: "agent.spawned"; at: number; agentId: string; label: string;
+      allowedTools?: string[];
+      /** Resolved model id used for this agent (e.g. `claude-sonnet-4-6`).
+       *  Read off `client.model` after runtime construction. */
+      model?: string;
+      /** Short runtime self-identifier (`claude`, `openai-desktop`, …).
+       *  Drives the per-agent runtime icon on the dashboard. */
+      runtimeKind?: string;
+    }
   | { event: "agent.message"; at: number; agentId: string; label: string; iteration: number; message: AgentMessageSummary }
   | { event: "agent.iteration"; at: number; agentId: string; label: string; iteration: number; status: AgentStatus | null }
   | { event: "agent.settled"; at: number; agentId: string; label: string; outcome: "success" | "failed"; iterations: number; durationMs: number; failureReason?: string };
@@ -102,6 +114,37 @@ export interface AgentLoopOpts<TResponse = unknown> {
   processors?: readonly Processor[];
   /** Per-run typed bag — propagated to every processor as `ctx.requestContext`. */
   requestContext?: RequestContext;
+  /**
+   * Mid-iteration user-message injection. When set, the agent loop
+   * builds a per-iteration AsyncQueue and hands it to the runtime as
+   * `inboxStream`. The runner-side inbox poller calls `push()` on
+   * `inbox` when a user message arrives; the runtime (streaming-input
+   * Claude Agent SDK) picks it up at the next safe boundary.
+   *
+   * The loop drains `inbox` into the per-iteration queue while the
+   * iteration is active and stops draining at iteration end — any
+   * messages that arrive between iterations are buffered on `inbox`
+   * and drain into the NEXT iteration's queue. So no message is lost,
+   * but mid-iteration injection requires the runtime to support
+   * streaming input (ignored otherwise — handled at the runtime).
+   */
+  inbox?: import("./async-queue.js").AsyncQueue<{ text: string; senderName?: string | null }>;
+  /** PR 7 steer-pause: the boundary calls this to pause the workflow for a
+   *  human steer. agent() builds it (a corePause closed over runId/stepIndex);
+   *  the loop supplies the agentScope so the pauseId is stable across resume.
+   *  Absent ⇒ no steer pause (local tests, non-sandbox callers). */
+  pause?: <T = unknown>(
+    req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
+    agentScope: { agentId: string; iteration: number },
+  ) => Promise<T>;
+  /** PR 7: take-once read of this agent's pending steer (set by the control
+   *  poller). Returns the steer's payload (reason / correlationKey) or null.
+   *  The boundary consumes it once per check, and only when no steer is
+   *  already staged. */
+  consumeSteerPending?: () => SteerPayload | null;
+  /** PR 7: `auto` (autonomous, default) or `hitl` (can be steer-paused). The
+   *  boundary is inert unless `hitl`. */
+  mode?: "auto" | "hitl";
 }
 
 export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TResponse>): Promise<AgentLoopResult<TResponse>> {
@@ -154,13 +197,162 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   let completedIterations = 0;
   let lastResponseText = "";
   let lastResponseValidationError = "";
+  // Iteration the loop should resume at on entry. 0 = fresh run; >0 =
+  // restored from disk after a pause-resume. The `for` loop reads
+  // `startIteration` instead of starting at 0 so already-completed
+  // iterations don't re-run.
+  let startIteration         = 0;
+  // Was this invocation resumed from on-disk state? Drives an early
+  // call to `runtime.restoreCheckpoint(blob)` and suppresses the
+  // `agent.spawned` event (the agent already spawned in the prior
+  // subprocess; emitting again would double-count on the dashboard).
+  let resumed = false;
+  // PR 7: a pending human steer-pause intent. Persisted in loop state so it
+  // survives a resume and the boundary re-issues the pause on re-entry.
+  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number } | null = null;
+
+  const pauseManager = new PauseManager(agentId);
+  const restore = await pauseManager.restoreAgentLoop<TResponse>(client);
+  if (restore.kind === "settled") {
+    process.stdout.write(`${logLabel} restored settled agent result from checkpoint after ${restore.result.iterations} iterations\n`);
+    return { agentId, label, ...restore.result };
+  }
+  if (restore.kind === "running") {
+    const s = restore.state;
+    startIteration              = s.iteration;
+    completedIterations         = s.completedIterations;
+    lastSessionId               = s.lastSessionId;
+    lastStatus                  = s.lastStatus;
+    lastResponseText            = s.lastResponseText;
+    lastResponseValidationError = s.lastResponseValidationError;
+    iterationsWithoutStatus     = s.iterationsWithoutStatus;
+    blockerStreak               = s.blockerStreak;
+    pendingSteerPause            = s.pendingSteerPause ?? null;
+    resumed                     = true;
+    process.stdout.write(`${logLabel} resumed from agent-state checkpoint at iteration ${startIteration}/${maxIterations}\n`);
+  }
+  if (restore.kind === "invalid") {
+    // Forward-incompat or corrupt state file. Fall back to fresh start
+    // rather than partial-restore — a misread checkpoint would silently
+    // desync the loop from the model's actual conversation history.
+    process.stderr.write(
+      `${logLabel} agent-state checkpoint at agentId=${agentId} is unrecognised — starting fresh. ` +
+      `Schema version mismatch or corrupt file: ${restore.error}\n`,
+    );
+  }
+
+  // `agent.spawned` represents one logical agent instance, not one
+  // subprocess invocation. Skip on resume so the dashboard's per-agent
+  // card count doesn't increment every time a pause-resume re-enters
+  // the loop.
+  if (!resumed) {
+    opts.onAgentLifecycleEvent?.({
+      event: "agent.spawned",
+      at: startedAt,
+      agentId,
+      label,
+      allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+      ...(client.model       != null ? { model:       client.model       } : {}),
+      ...(client.kind        != null ? { runtimeKind: client.kind        } : {}),
+    });
+  }
+
+  /** Atomically flush loop state + runtime checkpoint to disk. Called
+   *  at every iteration boundary so a `ctx.pause` firing inside the
+   *  next iteration's body can rely on the most recent committed state.
+   *  Two writes (loop state, runtime blob) — both atomic individually;
+   *  the pair isn't transactional. If a stateful runtime later resumes
+   *  without its blob, restore fails loudly rather than continuing with
+   *  an empty conversation. */
+  const flushState = async (currentIteration: number): Promise<void> => {
+    await pauseManager.saveRunningAgentLoop({
+      iteration:                   currentIteration,
+      completedIterations,
+      lastSessionId,
+      lastStatus,
+      lastResponseText,
+      lastResponseValidationError,
+      iterationsWithoutStatus,
+      blockerStreak,
+      pendingSteerPause,
+    }, client);
+  };
 
-  opts.onAgentLifecycleEvent?.({ event: "agent.spawned", at: startedAt, agentId, label, allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS });
+  const writeSettledState = async (result: AgentLoopResult<TResponse>): Promise<void> => {
+    await pauseManager.saveSettledAgentLoop({
+      sessionId:  result.sessionId,
+      lastStatus: result.lastStatus,
+      iterations: result.iterations,
+      ...(result.response !== undefined ? { response: result.response } : {}),
+    });
+  };
 
   try {
-  for (let iteration = 0; iteration < maxIterations; iteration++) {
+  // The `|| pendingSteerPause` clause lets a staged steer (a self-pause asked on
+  // the FINAL budgeted iteration, or a restored intent) run one boundary past
+  // the budget so its pause fires and the human's answer gets an iteration —
+  // otherwise an end-of-iteration self-pause on the last turn would fall through
+  // to the exhaustion path and settle "success" with the question silently lost.
+  for (let iteration = startIteration; iteration < maxIterations || (!!opts.pause && pendingSteerPause !== null); iteration++) {
+    // Boundary flush. Captures the state that, on resume, makes this
+    // iteration the one we re-enter. A pause firing inside this
+    // iteration's body resumes here; a pause firing AFTER this
+    // iteration completes gets re-captured at the next boundary.
+    await flushState(iteration);
+
+    // PR 7 — human steer-pause boundary. Take a pause when a human steer is
+    // pending: a fresh poller flag, OR a pendingSteerPause restored from a prior
+    // pass. Persist the intent BEFORE pausing so the snapshot carries it; on
+    // resume the same corePause (keyed on agentId:iteration) returns the
+    // decision — no re-prompt. UNGATED: a human can steer ANY running agent,
+    // regardless of `mode`. (`mode` governs whether the agent may pause ITSELF.)
+    let steerDecision: SteerDecision | null = null;
+    if (opts.pause) {
+      // Consume a fresh poller flag ONLY when nothing is already staged —
+      // evaluating consume() unconditionally would clear (and discard) a steer
+      // that lands while a self-pause or a restored intent is already pending.
+      // The steer's reason + correlationKey ride through to the pause row so
+      // resumePauseByKey can resolve it (a bare flag dropped both).
+      if (pendingSteerPause === null) {
+        const steer = opts.consumeSteerPending?.() ?? null;
+        if (steer) {
+          pendingSteerPause = {
+            reason:         steer.reason ?? "human steer",
+            correlationKey: steer.correlationKey,
+            at:             Date.now(),
+          };
+        }
+      }
+      if (pendingSteerPause !== null) {
+        await flushState(iteration);                 // intent durable before the throw
+        steerDecision = await opts.pause<SteerDecision>(
+          {
+            reason: pendingSteerPause.reason,
+            ...(pendingSteerPause.correlationKey !== null ? { correlationKey: pendingSteerPause.correlationKey } : {}),
+            schema: SteerDecisionSchema,
+          },
+          { agentId, iteration },
+        );
+        // Reached ONLY on resume — the fresh pass threw PauseSignal above and
+        // unwound to serveStep.
+        pendingSteerPause = null;
+        await flushState(iteration);                 // commit the cleared intent
+      }
+    }
+
     const procCtx = buildProcCtx(iteration + 1);
-    const initialPrompt = opts.buildPrompt(lastStatus, iteration);
+    let initialPrompt = opts.buildPrompt(lastStatus, iteration);
+    if (steerDecision) {
+      // Deliver the human's answer as the agent's next user turn by appending
+      // it to the iteration prompt. `sendMessage({ prompt })` is the one input
+      // every runtime takes, so this is uniform — no per-runtime delivery path,
+      // no capability flag. On it>0 the prompt is PROTOCOL_SUFFIX and the
+      // runtime carries prior history (session resume / restored messages); on
+      // it==0 it's the original task, so the agent gets task-then-steer. No
+      // re-prompt — earlier turns are never resent.
+      const who = steerDecision.actor ? ` from ${steerDecision.actor}` : "";
+      initialPrompt = `${initialPrompt}\n\n[human steer${who}]: ${steerDecision.message}`;
+    }
 
     // processInput chain — deny ends the loop; abort ends the loop.
     const inputVerdict = await runProcessorChain(processors, (p) => p.processInput, initialPrompt, procCtx);
@@ -175,7 +367,19 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
 
     let responseText = "";
-    for await (const rawMsg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined, iteration: iteration + 1 })) {
+    // The single `opts.inbox` is shared across iterations, but the
+    // runtime treats it as a per-call iterable: each iteration's
+    // sendMessage starts its own for-await over the same queue, so
+    // a message pushed mid-iteration goes into the current call's
+    // streaming input, and a message pushed between iterations gets
+    // picked up by the next iteration's for-await (AsyncQueue
+    // semantics — buffered until consumed).
+    for await (const rawMsg of client.sendMessage({
+      prompt,
+      sessionId: iteration > 0 ? lastSessionId : undefined,
+      iteration: iteration + 1,
+      ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
+    })) {
       // processOutput chain — deny drops the message from accumulation;
       // abort ends the loop. Continue carries the (possibly mutated)
       // message forward.
@@ -202,23 +406,29 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     lastResponseText = responseText;
 
     let status = parseAgentStatus(responseText);
-    // Parse the response once per iteration; both the schema fast path
-    // below and the exit-signal-driven validation a few lines down
-    // need the same parsed payload. `null` when there's no <response>
-    // block AND no top-level JSON object.
-    const rawResponse = opts.responseSchema
+    // Inline safeParse (instead of letting parseAgentResponse validate)
+    // so a schema failure surfaces via lastResponseValidationError on
+    // the next iteration — the model needs that feedback to fix its
+    // output.
+    const rawResponse: unknown = opts.responseSchema
       ? parseAgentResponse(responseText) ?? parseRawJsonResponse(responseText)
       : null;
+    const validateResponse = (target: unknown) => {
+      const parsed = opts.responseSchema!.safeParse(target);
+      if (!parsed.success) lastResponseValidationError = parsed.error.message;
+      return parsed;
+    };
     if (opts.responseSchema && rawResponse !== null) {
-      const parsed = opts.responseSchema.safeParse(rawResponse);
+      const parsed = validateResponse(rawResponse);
       if (parsed.success) {
         const successStatus = status ?? { summary: "structured response completed", completed: [], blockers: [], exit_signal: true };
         // Successful schema-validation is progress, not a warning.
         process.stdout.write(`${logLabel} structured response validated after ${iteration + 1}/${maxIterations} iterations\n`);
+        const result: AgentLoopResult<TResponse> = { agentId, label, sessionId: lastSessionId, lastStatus: successStatus, iterations: iteration + 1, response: parsed.data };
+        await writeSettledState(result);
         opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: iteration + 1, durationMs: Date.now() - startedAt });
-        return { agentId, label, sessionId: lastSessionId, lastStatus: successStatus, iterations: iteration + 1, response: parsed.data };
+        return result;
       }
-      lastResponseValidationError = parsed.error.message;
     }
     completedIterations = iteration + 1;
     // Per-iteration status is informational progress. The presence
@@ -243,9 +453,8 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
         // fields (`exit_signal`, `blockers`, …) the agent emitted in a
         // separate <status> block. Distinct from the fast path above,
         // which validates the raw response alone.
-        const parsed = opts.responseSchema.safeParse({ ...status, ...(rawResponse as object) });
+        const parsed = validateResponse({ ...status, ...(rawResponse as object) });
         if (!parsed.success) {
-          lastResponseValidationError = parsed.error.message;
           process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(rawResponse).slice(0, 400)}\n`);
           status = { ...status!, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
           opts.onIteration?.(iteration + 1, status);
@@ -255,8 +464,27 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       }
       // Settled successfully — progress, not a warning.
       process.stdout.write(`${logLabel} done after ${iteration + 1}/${maxIterations} iterations\n`);
+      const result: AgentLoopResult<TResponse> = { agentId, label, sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response: response as TResponse };
+      await writeSettledState(result);
       opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: iteration + 1, durationMs: Date.now() - startedAt });
-      return { agentId, label, sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response: response as TResponse };
+      return result;
+    }
+
+    // PR 7 — agent self-pause (mode: "hitl" only). The agent set needs_input in
+    // its <status> and ended its turn. Stage a pause the NEXT boundary takes —
+    // the same machinery as a human steer, triggered by the agent's own status.
+    // The boundary pause itself is UNGATED; only this TRIGGER is gated by mode,
+    // so an `auto` agent's needs_input is ignored — it just keeps iterating.
+    if (opts.pause && opts.mode === "hitl" && status?.needs_input && pendingSteerPause === null) {
+      pendingSteerPause = {
+        reason:         status.question?.trim() || "the agent requested human input",
+        correlationKey: null,
+        at:             Date.now(),
+      };
+      blockerStreak = null;   // an explicit ask is not a stuck-loop
+      // Pause fires at the next boundary; the loop condition guarantees that
+      // boundary runs even when this was the final budgeted iteration.
+      continue;
     }
 
     if (!status) {
@@ -286,9 +514,15 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   if (opts.responseSchema)
     throw new Error(`${logLabel} did not produce a valid <response> after ${maxIterations} iterations${lastResponseValidationError ? `: ${lastResponseValidationError}` : ""}. Response tail: ${lastResponseText.slice(-600)}`);
   process.stderr.write(`${logLabel} exhausted ${maxIterations} iterations, proceeding with available work\n`);
+  const result: AgentLoopResult<TResponse> = { agentId, label, sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+  await writeSettledState(result);
   opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: maxIterations, durationMs: Date.now() - startedAt });
-  return { agentId, label, sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+  return result;
   } catch (err) {
+    // A boundary pause (PauseSignal) is control flow, not a failure — let it
+    // propagate so serveStep emits the pause sentinel; do not settle the agent
+    // as failed.
+    if (isPauseSignal(err)) throw err;
     opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "failed", iterations: completedIterations, durationMs: Date.now() - startedAt, failureReason: err instanceof Error ? err.message : String(err) });
     throw err;
   }

package/src/agent/async-queue.ts

@@ -0,0 +1,61 @@
+/**
+ * AsyncQueue — single-producer/single-consumer push-iterable.
+ *
+ * The Claude Agent SDK's streaming-input mode wants
+ * `prompt: AsyncIterable<SDKUserMessage>`. We need a primitive that:
+ *   - lets the agent loop `push()` user turns from outside the iterator
+ *     (initial prompt, plus async-arriving inbox messages)
+ *   - lets the SDK's `for await` consume them in order, blocking until
+ *     the next item arrives
+ *   - terminates cleanly via `close()` so the SDK sees the iterable
+ *     drain and finalises the assistant turn
+ *
+ * Why not an `EventEmitter` or RxJS — both are overkill for one shape.
+ * The implementation is ~30 lines of native Promise plumbing and stays
+ * inside the SDK package so it can be the canonical way agent-loop
+ * builds its prompt iterable.
+ */
+
+export class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly buffer:    T[]                         = [];
+  private readonly resolvers: Array<(v: IteratorResult<T>) => void> = [];
+  private done = false;
+
+  /** Push one item. If a consumer is awaiting, it wakes immediately;
+   *  otherwise the item is buffered until the next `next()` call. */
+  push(value: T): void {
+    if (this.done) return;
+    const resolve = this.resolvers.shift();
+    if (resolve) {
+      resolve({ value, done: false });
+    } else {
+      this.buffer.push(value);
+    }
+  }
+
+  /** Signal end-of-stream. Any pending awaiters resolve as
+   *  `{ done: true }`; subsequent `push()` calls are silent no-ops. */
+  close(): void {
+    if (this.done) return;
+    this.done = true;
+    while (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift()!;
+      resolve({ value: undefined as unknown as T, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: (): Promise<IteratorResult<T>> => {
+        const buffered = this.buffer.shift();
+        if (buffered !== undefined) return Promise.resolve({ value: buffered, done: false });
+        if (this.done) return Promise.resolve({ value: undefined as unknown as T, done: true });
+        return new Promise((resolve) => { this.resolvers.push(resolve); });
+      },
+      return: (): Promise<IteratorResult<T>> => {
+        this.close();
+        return Promise.resolve({ value: undefined as unknown as T, done: true });
+      },
+    };
+  }
+}

package/src/agent/protocol.ts

@@ -15,8 +15,18 @@ export const AgentMessageSchema = z.object({
   timestamp: z.string(),
 }).passthrough() as unknown as z.ZodType<AgentMessage>;
 
-export function parseAgentResponse(text: string): unknown {
+/** Parse the `<response>...</response>` block from agent text. Returns
+ *  `null` if missing or malformed. Callers run schema validation on
+ *  the returned `unknown` directly — the earlier generic overload that
+ *  did the safeParse inline returned `null` on schema failure,
+ *  swallowing the validation error without setting any breadcrumb on
+ *  the loop's `lastResponseValidationError`. No caller used that
+ *  overload; the dedicated `responseSchema` path in `agent-loop.ts`
+ *  does the parse-with-error-capture itself. */
+export function parseAgentResponse(text: string): unknown | null {
   const match = text.match(/<response>([\s\S]*?)<\/response>/);
   if (!match) return null;
-  try { return JSON.parse(match[1].trim()); } catch { return null; }
+  try {
+    return JSON.parse(match[1].trim());
+  } catch { return null; }
 }