@agent-compose/sdk 0.6.0 → 0.8.0

package/dist/workflow-steps/step.d.ts

@@ -7,19 +7,33 @@
  *   - `output`  Zod schema; validated against `run`'s return value
  *   - `run`     step body
  *
+ * Optional narrative fields (rendered on the dashboard workflow graph):
+ *   - `summary`       one plain sentence of what the step actually does
+ *   - `deliverables`  files the step promises to produce
+ *
  * Validation is required (not optional) because the durability story rides
  * on every step boundary being a recordable, replayable JSON value. A step
  * without a schema is invisible to the engine's persistence layer.
  *
+ * Narrative caps are enforced HERE, at construction — the bundler evaluates
+ * the module at registration, so this is the "length-capped at registration"
+ * point and the error names the step in the author's own environment. The
+ * server's manifest zod re-checks the same caps (untrusted input).
+ *
  * Type inference flows: `defineStep` infers TInput/TOutput from the schemas
  * so `run(ctx)` is fully typed via `ctx.input` at the call site.
  */
 import type { z } from "zod";
-import type { Step, StepContext } from "./types.js";
+import type { Step, StepContext, StepDeliverable } from "./types.js";
 export interface DefineStepOpts<TInput, TOutput> {
     name: string;
     input: z.ZodType<TInput>;
     output: z.ZodType<TOutput>;
     run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+    /** One plain sentence of what the step actually does. 1-200 chars, no
+     *  control characters (so no newlines). */
+    summary?: string;
+    /** Files the step promises to produce. At most 8. */
+    deliverables?: StepDeliverable[];
 }
 export declare function defineStep<TInput, TOutput>(opts: DefineStepOpts<TInput, TOutput>): Step<TInput, TOutput>;

package/dist/workflow-steps/types.d.ts

@@ -14,6 +14,7 @@ import type { z } from "zod";
 import type { BaseExecutionContext } from "../types/execution-context.js";
 import type { AgentEventSink } from "../types/workflow.js";
 import type { WorkflowMetadata } from "../types/workflow-metadata.js";
+import type { StepObservability } from "./observability.js";
 /**
  * Per-step execution context. Threaded into every step's `execute(...)` so
  * the step can read tenant identity and run identity, log progress, and
@@ -59,6 +60,14 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
      */
     agentEvents: AgentEventSink;
 }
+/** One artifact a step promises to produce. `path` is workspace/drive-relative
+ *  (e.g. "out/report.html"); the dashboard derives the format tag from the
+ *  extension client-side — no `format` field here. */
+export interface StepDeliverable {
+    path: string;
+    /** Optional one-line description of the artifact. */
+    description?: string;
+}
 /**
  * Step definition — a single typed unit of work in a workflow chain.
  *
@@ -77,6 +86,11 @@ export interface Step<TInput, TOutput> {
     readonly output: z.ZodType<TOutput>;
     /** Step body. Receives a `StepContext<TInput>` and returns the typed output. */
     run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+    /** One plain sentence of what the step actually does — rendered on the
+     *  dashboard workflow graph. ≤200 chars, no newlines. */
+    readonly summary?: string;
+    /** Files the step promises to produce. ≤8 entries. */
+    readonly deliverables?: readonly StepDeliverable[];
 }
 /**
  * The result of running one step. Engine adapters persist these into the
@@ -89,18 +103,18 @@ export type StepRunResult<TOutput = unknown> = {
     status: "completed";
     output: TOutput;
     durationMs: number;
-    observability?: import("./observability.js").StepObservability;
+    observability?: StepObservability;
 } | {
     status: "failed";
     error: string;
     durationMs: number;
-    observability?: import("./observability.js").StepObservability;
+    observability?: StepObservability;
 };
 /**
  * Workflow — a list of typed steps plus the workflow's input/output
- * schemas plus its server-side metadata bag. Returned by `defineWorkflow(...)`
- * (run form) and `defineWorkflow(...).step(...)...build()` (step form).
- * Engine adapters consume this shape.
+ * schemas plus its server-side metadata bag. Returned by
+ * `defineWorkflow(...).step(...)...build()`. Engine adapters consume
+ * this shape.
  *
  * `input` validates the workflow input before the first step runs.
  * `output` validates the final step's output before the workflow

package/dist/workflow-steps/workflow.d.ts

@@ -20,7 +20,7 @@
  */
 import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
-import type { SnapshotConfig, SandboxResources } from "../types/workflow-metadata.js";
+import type { SnapshotConfig, SandboxResources, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, DriveMergePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 export interface WorkflowBuilder<TInput, TCurrent> {
@@ -50,7 +50,28 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
      *  and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
      *  sizing is template-defined. Omit → smallest SKU on the default provider. */
     resources?: SandboxResources;
+    /** What happens to this workflow's drive branch when a run ends:
+     *  `"auto"` (the default when omitted — today's behaviour) folds it into
+     *  `main`; `"manual"` proposes a merge approval at the same terminus
+     *  instead, leaving the branch durable until a human clicks approve. A
+     *  cancelled run neither merges nor proposes under either policy. */
+    mergePolicy?: DriveMergePolicy;
     processors?: readonly Processor[];
+    /** Connector requirements (ADR-0007) — providers whose APIs this workflow
+     *  calls. Dispatch resolves an authorized grant per provider and injects a
+     *  fresh access token at the network layer. */
+    connectors?: ConnectorRequirements;
+    /** Marks this workflow as a catalogue OPERATION of a connector — e.g. the
+     *  `create-issue` operation of the `github` connector. */
+    connectorOperation?: ConnectorOperationTag;
+    /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
+     *  See `InvokePolicy`. */
+    invokePolicy?: InvokePolicy;
+    /** Internal — set by `defineSandboxEnvironment`, not by workflow authors.
+     *  Marks the workflow as an environment build (base-env / agent-env) so the
+     *  server skips mounting the shared factory drive for its runs (#13). See
+     *  `WorkflowMetadata.environmentBuild`. */
+    environmentBuild?: boolean;
 }
 export declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;
 /** Type guard — true when `value` is a `Workflow`. */

package/dist/workflows/engine.d.ts

@@ -8,7 +8,8 @@
  * Errors classified into `WorkflowError` (user code threw) vs `EngineError`
  * (platform problem) for the runner harness to surface upstream.
  */
-import type { WorkflowHooks, WorkflowCtx } from "../types/workflow.js";
+import type { WorkflowHooks } from "../types/workflow.js";
+import type { InvokeChild } from "../types/execution-context.js";
 import { RequestContext } from "../request-context/request-context.js";
 import type { Workflow } from "../workflow-steps/types.js";
 import { type RunWorkflowStepsOpts } from "../workflow-steps/runner.js";
@@ -54,7 +55,7 @@ export interface RunWorkflowOptions {
     /** Provider-specific child workflow invocation. Temporal/Inngest providers
      *  inject their native child-workflow primitive; the LocalProvider injects
      *  the public Agent Compose API client. */
-    invokeChild?: WorkflowCtx["invokeChild"];
+    invokeChild?: InvokeChild;
 }
 export declare function runWorkflow<TInput, TOutput>(wf: Workflow<TInput, TOutput>, ctx: {
     run: {

package/dist/workflows/invoke-child.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowCtx } from "../types/workflow.js";
+import type { InvokeChild } from "../types/execution-context.js";
 /**
  * Build the public-API child workflow invoker used by legacy and sandboxed
  * workflow execution. Provider-backed engines may inject a different
@@ -7,4 +7,4 @@ import type { WorkflowCtx } from "../types/workflow.js";
 export declare function buildInvokeChild(runId: string, opts?: {
     fallbackBaseUrl?: string;
     defaultFactorySlug?: string;
-}): WorkflowCtx["invokeChild"];
+}): InvokeChild;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {

package/src/agent/agent-context.ts

@@ -71,29 +71,36 @@ Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
 
 ## Writing workflow / agent code — the SDK
 
-\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
-you write there:
+\`@agent-compose/sdk\` is installed in \`/workspace\`. **To author a workflow,
+ALWAYS run \`/ac:generate-workflow\`** (and \`/ac:generate-agent\` for an agent
+step) instead of writing source from memory — the skill scaffolds the correct,
+current shape. Then \`agentc register <file.ts>\` (or \`/ac:register\`).
 
-    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+The skill writes **step-form** (a builder of discrete, durable \`.step()\`s).
+The legacy run-form (\`defineWorkflow({ run(ctx, sandbox) { … } })\`) has been
+REMOVED from the SDK — registering one fails with an error. Step-form is the
+only shape: durable per-step replay, and pause only works there.
 
-Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
-\`agentc register <file.ts>\` (or \`/ac:register\`).
+## Pausing to ask the human
 
-## Pausing to ask the human — \`agentc pause\`
-
-When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
-**END YOUR TURN**:
+To ask a human and get an answer back, use the **\`AskUserQuestion\`** tool if
+you have it; otherwise run **\`agentc pause\`**:
 
     agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
                  --option retry --option skip
 
-\`agentc pause\` does NOT block and does NOT print the answer. It records your
-question and returns immediately. The moment you end your turn, the run pauses
-(your sandbox is snapshotted and compute stops while the human decides) and the
-human's answer is delivered to you as your **next message** — you pick up
-exactly where you left off, with the answer in hand. So: ask, end your turn,
-and wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task
-complete after pausing.
+**Both BLOCK and hand you the answer inline.** While you wait, the run is
+suspended — your sandbox is frozen and compute stops, so a pause is free while
+the human decides. When they answer, the call RETURNS with their decision: the
+\`AskUserQuestion\` tool result, or \`agentc pause\`'s output
+(\`▶ Resumed. The human answered: …\`), carries it.
+
+**Then USE that answer to finish your work — do NOT end your turn.** This is NOT
+fire-and-forget, and the answer does NOT arrive in a later message: it comes
+back right where you called it, on the SAME turn. The shape is: ask → the call
+blocks → it returns the human's answer → you act on it and produce your result.
+Never end your turn before the call returns, never guess an answer, and never
+proceed without one.
 
 Reach for it the moment you hit — or foresee — any of these:
 - **A wall only a human can clear:** a 401/403, a missing credential, an
@@ -118,14 +125,197 @@ request **without** an Authorization header and the platform adds it. Don't try
 to read or exfiltrate tokens; they aren't here. The "Connectors & access"
 section below (when present) lists exactly which providers this run can reach.
 
+## Computer Use — you have a real desktop, and it is already running
+
+**This machine has a graphical desktop.** Every session machine does — terminal
+sessions included — and the platform brings it UP AT BOOT, before your first
+turn: an X server on \`DISPLAY=:0\`, the openbox window manager, wallpaper and a
+panel. You do not start it, you do not wait for a human to open it, and you do
+not need a viewer. Go straight to driving it.
+
+(The one exception, and it is rare: an image built without the GUI stack has no
+display at all, and \`DISPLAY=:0 xdotool getdisplaygeometry\` errors outright.
+That single case is the only one where this section does not apply — a
+screenshot showing only wallpaper is NOT it, and neither is an app that failed
+to start.)
+
+**This is how you SEE anything.** Any question of the form "does it render?",
+"is the page actually working?", "did the markers show up?", "what does it look
+like?" is answered by opening it on this desktop and screenshotting it — not by
+reasoning about the code, and not by a headless render (which proves the process
+starts, not that the thing draws). Verify visually before you report visually.
+
+- **Input** — \`xdotool\` against \`DISPLAY=:0\`: \`DISPLAY=:0 xdotool mousemove <x> <y>\`,
+  \`DISPLAY=:0 xdotool click 1\` (1=left, 3=right), \`DISPLAY=:0 xdotool type 'text'\`,
+  \`DISPLAY=:0 xdotool key Return\` (also \`ctrl+c\`, \`Tab\`, \`super\`, …).
+- **Screenshots** — \`scrot\` (or ImageMagick's \`import\`):
+  \`DISPLAY=:0 scrot /tmp/screen.png\`, then READ the PNG to see the screen,
+  before and after you act. A screenshot is your only eyes here.
+- **Apps + windows** — a plain X session. Launch in the background:
+  \`DISPLAY=:0 <app> &\`. Two things that trip agents up, both normal:
+  - a GUI app needs a **beat to map its window** — screenshot, and if you see
+    only wallpaper, wait a couple of seconds and screenshot again before
+    concluding anything;
+  - **Chromium needs \`--no-sandbox\`** in this environment (nested sandbox).
+    The whole recipe for looking at a local page:
+    \`DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &\`
+    then \`sleep 5\`, then \`DISPLAY=:0 scrot /tmp/screen.png\` and read it.
+  If a window still never appears, read the app's own log (\`/tmp/*.log\`) — the
+  desktop is not the thing that failed. Do NOT abandon it for a headless
+  screenshot: headless cannot tell you what the human will see.
+- **A human can watch** — the session header carries a **Desktop** button in the
+  dashboard, and what a teammate sees there is exactly this display. The desktop
+  runs whether or not anyone is looking; never wait for a viewer.
+
+Nothing here changes the credentials rule above: tokens are injected at the
+network layer, never present on the desktop or in any file you can read — so
+there is nothing to type, paste, or screenshot a credential from.
+
+## Recording a demo — the desktop, captured to a video the human can play
+
+"Record a demo of you using X" is a normal ask, and this machine does it:
+start a screen recording, drive the app with \`xdotool\` exactly as in Computer
+Use, stop the recording, and report the file. (For a LIVE view no recording is
+needed — the session header's **Desktop** button already streams this display
+to any teammate watching; a recording is the durable, replayable artifact.
+Both modes exist; say so when it matters.)
+
+**ffmpeg is NOT pre-installed** — install it first, once per machine:
+
+    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+
+(drop \`sudo\` if you are already root). Then the whole recipe:
+
+    DISPLAY=:0 ffmpeg -f x11grab \\
+      -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
+      -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
+      demo.webm &
+    FFMPEG_PID=$!
+    # ... drive the app with xdotool, screenshotting as you go ...
+    kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
+
+The gotchas, each one earned:
+- **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
+  file on SIGINT; a hard kill truncates the encode mid-write.
+- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
+  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
+  playable up to the last written frame and plays natively in the browser.
+  MP4's only edge is compatibility with some external players — transcode
+  afterwards if you truly need it, never record straight to it.
+- **\`-video_size\` must match the real screen** — x11grab does not default to
+  it; read the geometry from \`xdotool getdisplaygeometry\` as above.
+- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+  this is not video production.
+- **Write to the drive, not /tmp** — the recording must land in your working
+  directory to persist and show up in Files; a file in /tmp dies with the
+  sandbox.
+- When you stop, **TELL the human the exact drive path** of the video — a
+  recording they cannot find might as well not exist.
+
+## Previews — register every server you serve (cloud sessions)
+
+In a cloud session, a dev server listening on a port becomes a hosted,
+member-gated URL the human can open — but ONLY if you register it:
+
+    agentc preview open <port> [--name <label>] [--path </landing>]
+                                                 # hosted URL + an "Open preview" card
+    agentc preview list                          # the registry — what is live right now
+    agentc preview close <port>                  # take one down
+
+(\`agentc preview announce\` is the same verb as \`open\` — announce what you
+serve.) \`--name\` is the human-readable label; \`--path\` is where the app
+should open (e.g. \`/dashboard\`) — the card and every chip land the human
+there instead of a bare \`/\`.
+
+Register EVERY server you start for a human, the moment it is listening, and
+tell them the URL the command printed. The registry is the only discoverable
+record of what this machine serves: an unregistered server keeps running, but
+nobody — not the human, not the assistant — can find its URL, and when the
+sandbox recycles it is gone without a trace. Never guess or hand out a raw
+port; the hosted URL from \`agentc preview open\` is the only address that
+works outside this machine. (Outside a cloud session the command errors
+honestly — there is no session sandbox to expose.)
+
+What registration buys you: the human sees each registered preview as a card
+in the conversation and a row in the session's Previews menu — MANY at once,
+one per port — and the assistant resolves "open the preview" from this same
+registry (its \`list_previews\` read), so what you register is exactly what
+gets opened. On deployments with subdomain previews the hosted URL is a real
+origin of its own — absolute asset paths and client-side routing work, the
+whole app is navigable — so serve normally and let the platform address it;
+never rewrite your app to a path prefix.
+
 ## Tools in this environment
 
 - \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
 - \`@agent-compose/sdk\` — installed in /workspace for writing workflows
 - \`/ac:*\` Claude Code skills — slash commands for the above
 - \`archil\` (factory drive), \`rtk\`, \`bun\`
+- \`xdotool\` / \`scrot\` — drive + screenshot the desktop (if this machine has one; see Computer Use)
 - A world-writable \`/workspace\` working directory`;
 
+/** Parameters for the `agentc session add` education brief (ADR-0055 §8). */
+export interface AddedSessionBriefParams {
+  conversationId: string;
+  serverUrl: string;
+  dashboardUrl: string | null;
+}
+
+/**
+ * The education brief `agentc session add` writes into a connected LOCAL
+ * session's CLAUDE.md/AGENTS.md — the same content family as
+ * `AGENT_COMPOSE_MANUAL`, rendered for the local context (one source,
+ * rendered per context). The manual above must stay BYTE-IDENTICAL (the
+ * server and base-env bake static copies of it); this function renders a
+ * sibling document and never touches it. The local context differs from the
+ * sandbox in exactly the ways stated here: auth rides the bridge credential
+ * fallback instead of injected run env; no factory drive is mounted — the
+ * files on this machine belong to the human; and the bound conversation is
+ * MIRROR-ONLY (ADR-0055 §8.6) — teammates read along but can never message
+ * the session through it, so the brief must not promise an inbound channel.
+ */
+export function buildAddedSessionBrief(p: AddedSessionBriefParams): string {
+  const dashboardSection = p.dashboardUrl === null ? "" : `
+
+## Dashboard
+
+Teammates follow this conversation (and the rest of the factory) in the
+Agent Compose dashboard: ${p.dashboardUrl}`;
+
+  return `# Connected to Agent Compose
+
+Agent Compose is your team's agent platform: durable conversations,
+workflow runs, and shared factory drives where humans and agents work
+together. THIS terminal's claude-code session is connected to Agent
+Compose conversation \`${p.conversationId}\` on ${p.serverUrl}.
+
+That conversation is a LIVE, READ-ONLY MIRROR of this terminal session:
+teammates read along in the dashboard as the work happens, but they cannot
+message you through it — anything posted there is answered by the server
+with a notice and never reaches this terminal. Everything you do here is
+mirrored automatically; you have an audience, not a channel.
+
+## The \`agentc\` toolbelt
+
+The \`agentc\` CLI works from this shell. It is already authenticated on
+this machine via the bridge credential fallback — no keys to manage,
+commands just work:
+
+    agentc list                          # registered workflows
+    agentc logs <run-id>                 # a run's logs
+    agentc invoke <workflow> -i '<json>' # dispatch a workflow
+    agentc events list                   # read the factory timeline
+
+## Scope — this is your LOCAL machine
+
+The files here are YOURS: no factory drive is mounted in this session,
+and nothing you write locally lands on a shared drive by itself. Cloud
+drive/branch semantics (per-run directories on the factory drive, drive
+branches, persist-by-default outputs) apply only to cloud sessions —
+not here.${dashboardSection}
+`;
+}
+
 /**
  * One connector this run can reach, as the agent should see it. Strictly
  * NON-SECRET — hosts, methods, paths, identity only. The access token is

package/src/agent/agent-loop.ts

@@ -39,6 +39,24 @@ export function parseAgentStatus(text: string): AgentStatus | null {
 
 const DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
 
+/**
+ * A `responseSchema` rendered for the runtime's structured-output surface.
+ *
+ * zod v4's `toJSONSchema` stamps `$schema: "…/draft/2020-12/schema"` on the
+ * result. Claude Code validates `--json-schema` with a validator that has no
+ * 2020-12 meta-schema registered, so any schema CARRYING that header is
+ * rejected at CLI startup — the process exits 1 before its first API call
+ * and every agent with a responseSchema dies on spawn (observed live on
+ * claude 2.1.212: `--json-schema is not a valid JSON Schema: no schema with
+ * key or ref "https://json-schema.org/draft/2020-12/schema"`). The header is
+ * pure metadata — drop it; the schema body is draft-07-compatible for every
+ * shape zod emits from our workflow schemas.
+ */
+export function runtimeJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown> {
+  const { $schema: _$schema, ...rest } = z.toJSONSchema(schema) as Record<string, unknown>;
+  return rest;
+}
+
 export interface AgentLoopResult<TResponse = unknown> {
   agentId:     string;
   label:       string;
@@ -71,7 +89,12 @@ function preview(value: unknown): string {
   }
 }
 
-export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
+/** Everything but the live-only streaming chunk: `text_delta` never becomes
+ *  an agent.message event (the terminating `text` carries the whole block) —
+ *  the loop filters it before summarizing. */
+type DurableAgentMessage = Exclude<AgentMessage, { type: "text_delta" } | { type: "usage_delta" }>;
+
+export function summarizeAgentMessage(msg: DurableAgentMessage): AgentMessageSummary {
   switch (msg.type) {
     case "init": return { type: "init", sessionId: msg.sessionId };
     case "text": return { type: "text", text: msg.text };
@@ -164,9 +187,16 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   const logLabel           = opts.label ?? "[Agent Loop]";
   const startedAt          = Date.now();
   // No budget ⇒ no turn cap: the harness runtime (Claude Code) decides when it's
-  // done. A numeric budget is an explicit caller choice, not a default we impose.
+  // done in one unbounded session. A numeric budget is an explicit caller choice.
+  // Default to a SMALL allowance (not 1) so the loop can RE-PROMPT for the closing
+  // <status>/<response> when a session ends EARLY — e.g. a human pause (agentc
+  // pause / AskUserQuestion) freezes the VM mid-tool and the resumed session can
+  // drop its final turn after doing the work. The re-prompt (PROTOCOL_SUFFIX)
+  // only fires when an iteration produced no exit_signal, so a clean run still
+  // settles in ONE iteration — these extra iterations are a recovery path, not
+  // the norm.
   const turnsPerIteration  = opts.turnsPerIteration;
-  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 3 : 8);
   // A responseSchema is a CONTRACT, not a hope: when the agent's <response> fails
   // validation, the loop re-prompts with the exact errors until it conforms —
   // without consuming the caller's iteration budget. The backstop below only
@@ -201,7 +231,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     // `session/request_permission` path through CliAgentRunner.gateToolCall) can
     // raise a human-approval `ctx.pause`, not just on the loop's own hooks.
     ...(opts.pause ? { pause: opts.pause } : {}),
-    ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: z.toJSONSchema(opts.responseSchema) as Record<string, unknown> } } : {}),
+    ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: runtimeJsonSchema(opts.responseSchema) } } : {}),
   });
 
   // Heads-up when a caller registers tool-call gating on a runtime that
@@ -421,6 +451,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       signal: loopAbort.signal,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
+      // Live-only streaming chunk: the terminating `text` message carries
+      // the complete block, so the loop (accumulation, events, processors)
+      // ignores deltas — they exist for progressive-rendering consumers
+      // (the conversation cloud executor), not the workflow event stream.
+      if (rawMsg.type === "text_delta" || rawMsg.type === "usage_delta") continue;
       // processOutput chain — deny drops the message from accumulation;
       // abort ends the loop. Continue carries the (possibly mutated)
       // message forward.
@@ -434,6 +469,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
         continue;
       }
       const msg = outputVerdict.value;
+      if (msg.type === "text_delta" || msg.type === "usage_delta") continue; // a processor cannot re-introduce a live-only chunk
       opts.onAgentEvent?.(iteration, msg);
       // Usage summaries carry the resolved model so the server can price
       // token rows per model without correlating back to agent.spawned.

package/src/agent/run-agent.ts

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
 import { corePause, type PauseRequest } from "../pause/pause-core.js";
+import { createAskHumanProcessor } from "../processors/ask-human.js";
 import { agentLoop } from "./agent-loop.js";
 import { consumeSteerPending, runControlPoller } from "./steer-control.js";
 import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
@@ -330,6 +331,13 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
   // (the boundary self-pause trigger + the prompt instruction above). Human
   // steering works regardless — see the ungated control poller.
   const mode = opts.mode ?? "auto";
+  // Ask-a-human is TOOLS-driven, not a separate mode: the ask-human processor is
+  // a chain default that maps the `AskUserQuestion` tool to a server pause (the
+  // run freezes, the human answers, the answer returns as the tool result). It's
+  // a no-op for any agent that doesn't have / call `AskUserQuestion`, so granting
+  // that tool to an agent IS its "can ask a human" switch — withhold it and the
+  // agent simply can't (it reports blockers up instead).
+  const processors = [createAskHumanProcessor(), ...(opts.processors ?? [])];
 
   try {
   return await agentLoop({
@@ -361,7 +369,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     ...(opts.events ? { onAgentLifecycleEvent: (event: AgentLifecycleEvent) => { void opts.events?.emit(event); } } : {}),
     ...(opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {}),
     ...(opts.onIteration  ? { onIteration:  opts.onIteration  } : {}),
-    ...(opts.processors?.length ? { processors: opts.processors } : {}),
+    ...(processors.length ? { processors } : {}),
     requestContext: opts.requestContext ?? RequestContext.fromReserved({
       teamId: "", runId: "", workflowId: "",
       factoryId: null, apiKeyScopes: [], parentRunId: null,