@agent-compose/sdk 0.6.0 → 0.8.0

package/README.md

@@ -23,34 +23,44 @@ npm install zod
 
 ## Authoring a workflow
 
-A workflow is `async (ctx, sandbox) => T`. Two positional args:
-
-- **`ctx`** carries the run identity (`run.id`), the caller's `input`, plus
-  observability helpers (`setMetadata`, `step`).
-- **`sandbox`** is a capability the engine constructs once for the run —
-  pass it to `agent({ sandbox, ... })` and to any helper that takes a
-  `SandboxProvider` (file writers, git utilities, command runners).
+A workflow is a typed chain of discrete steps:
+`defineWorkflow({ id, input, output }).step(defineStep(...)).build()`.
+Every step is a durable replay checkpoint — the engine records each
+step's validated output, so a retry or resume picks up after the last
+completed step instead of re-running the whole workflow. Pausing for
+human input (`ctx.pause`, `ctx.waitForEvent`) only works in this
+step-form.
 
 ```typescript
 // my-workflow.ts
-import { defineWorkflow, agent, claudeRuntime } from "@agent-compose/sdk";
+import { defineWorkflow, defineStep, agent, claudeRuntime } from "@agent-compose/sdk";
+import { z } from "zod";
 import PROMPT from "./prompt.md" with { type: "text" };
 
-export default defineWorkflow({
-  async run(ctx, sandbox) {
-    const repo = (ctx.input?.repo as string | undefined) ?? "owner/repo";
+const Input  = z.object({ repo: z.string() });
+const Output = z.object({ ok: z.boolean(), summary: z.string().optional() });
 
+const review = defineStep({
+  name:   "review",
+  input:  Input,
+  output: Output,
+  run: async (ctx) => {
     const result = await agent({
-      sandbox,
-      runtime:    claudeRuntime,
-      prompt:     `${PROMPT}\n\nRepository: ${repo}`,
-      tools:      ["Bash", "Read", "Edit", "Write", "Grep", "Glob"],
-      budget:     { turnsPerIteration: 40, maxIterations: 8 },
+      sandbox: ctx.sandbox,          // the run's own VM
+      runtime: claudeRuntime,
+      prompt:  `${PROMPT}\n\nRepository: ${ctx.input.repo}`,
+      tools:   ["Bash", "Read", "Edit", "Write", "Grep", "Glob"],
+      budget:  { turnsPerIteration: 40, maxIterations: 8 },
     });
-
     await ctx.setMetadata({ summary: result.status?.summary });
-    return { ok: result.status?.completed ?? false };
+    return { ok: result.status?.completed ?? false, summary: result.status?.summary };
   },
+});
+
+export default defineWorkflow({
+  id:     "my-workflow",
+  input:  Input,
+  output: Output,
   // Optional: outbound network rules that the runner sandbox will enforce
   // (Vercel only — E2B ignores). Use `$VAR` placeholders for secrets that
   // get resolved from the per-workflow secret store at dispatch time.
@@ -60,36 +70,52 @@ export default defineWorkflow({
       "api.anthropic.com": [{ transform: [{ headers: { "x-api-key": "$ANTHROPIC_API_KEY" } }] }],
     },
   },
-});
+})
+  .step(review)
+  .build();
 ```
 
-`defineWorkflow` is a thin sugar — it returns the bare `run` function with
-`networkPolicy` / `placeholders` / `snapshots`
-attached as metadata that the bundler picks up at registration time. A
-plain `export default async (ctx, sandbox) => {...}` is also valid; you
-just lose the metadata channel.
+The builder chain enforces at compile time that each step's `input`
+schema matches the previous step's `output`, and `.build()` verifies
+the final step's `output` is the same Zod instance as the workflow's
+declared `output`. `networkPolicy` / `placeholders` / `snapshots` on
+the definition become metadata the bundler picks up at registration
+time.
+
+> **Legacy run-form.** `defineWorkflow({ run(ctx, sandbox) { … } })` is
+> `@deprecated` — it compiles to a single opaque step, so there is no
+> per-step replay and pause doesn't work. Don't author new ones.
+
+### What a step can do with `ctx`
 
-### What the workflow can do with `ctx`
+Each step's `run(ctx)` receives a `StepContext`:
 
 ```ts
-interface WorkflowCtx {
+interface StepContext<TInput> {
+  input:       TInput;                // validated against the step's `input` schema
   run:         { id: string };
-  input?:      Record<string, unknown>;
+  sandbox?:    SandboxProvider;       // the run's VM — pass to `agent({ sandbox: ctx.sandbox })`
   setMetadata: (data: Record<string, unknown>) => Promise<void>;
-  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  step<T>(name: string, fn: () => Promise<T>): Promise<T>;   // durable named sub-step
+  pause<T>(req: PauseRequest<T>): Promise<T>;                // wait for a human, durably
+  sleep(durationMs: number): Promise<void>;
+  waitForEvent<T>(req: WaitForEventRequest<T>): Promise<T>;
+  invokeChild(name, input?, opts?): Promise<RunStatus>;      // run another workflow
 }
 ```
 
-`step("phase-name", () => …)` wraps a phase for the run timeline — emits
-`step_started` / `step_completed` / `step_failed` lifecycle events with
-duration. Use it for setup, external API calls, or anything you want
-visible on the dashboard's run detail page.
+`ctx.step("phase-name", () => …)` wraps a phase *within* a step for the
+run timeline — it memoises the result (a pause-resume re-entry restores
+it instead of re-running) and emits `workflow_substep_started` /
+`workflow_substep_completed` / `workflow_substep_failed` lifecycle
+events with duration. Use it for setup, external API calls, or anything
+you want visible on the dashboard's run detail page.
 
 ### The `agent` loop
 
 ```ts
 agent({
-  sandbox,            // the workflow's sandbox arg
+  sandbox,            // ctx.sandbox — the run's VM
   runtime,            // claudeRuntime, or your own via createClaudeRuntime / defineRuntime
   prompt,             // raw markdown — `--- frontmatter ---` is auto-stripped
   tools?,             // model tool allowlist (defaults inside agentLoop)
@@ -211,8 +237,8 @@ console.log(status.status);   // "success" | "failed" | "abandoned" | "canceled"
 console.log(status.output);   // workflow's return value
 ```
 
-`output` is the workflow's `run()` return value (whatever `defineWorkflow({
-async run() { return … } })` resolves to). `setMetadata()` writes to a
+`output` is the final step's return value, validated against the
+workflow's declared `output` schema. `setMetadata()` writes to a
 separate `metadata` field — useful for "side-channel" facts (PR url, plan
 url) without polluting the structured return.
 
@@ -364,10 +390,10 @@ await client.invoke("my-workflow", input, {
 });
 
 // Set a default at registration time:
-defineWorkflow({ run, snapshots: { saveLatest: true } });
+defineWorkflow({ id, input, output, snapshots: { saveLatest: true } }).step(…).build();
 
 // Retain every step's snapshot (not just the latest):
-defineWorkflow({ run, snapshots: { saveLatest: true, retainSteps: true } });
+defineWorkflow({ id, input, output, snapshots: { saveLatest: true, retainSteps: true } }).step(…).build();
 
 // Browse / clean up:
 const page = await client.listSnapshotsPage({ workflow: "my-workflow", limit: 50 });
@@ -408,7 +434,8 @@ programmatic / server-to-server callers.
 
 | Export | What |
 |---|---|
-| `defineWorkflow` | Attach metadata to a workflow `run` function |
+| `defineWorkflow` | Typed step-workflow builder — `defineWorkflow({ id, input, output }).step(...).build()` |
+| `defineStep` | Declare one typed workflow step (`{ name, input, output, run }`) |
 | `defineRuntime` | Wrap an agent execution provider as an `AgentRuntime` |
 | `defineSandboxEnvironment` | Sugar for declaring a workflow whose primary purpose is to build a snapshot for others to boot from |
 | `agent` / `agentLoop` | Embed an LLM loop inside a workflow |
@@ -421,7 +448,7 @@ programmatic / server-to-server callers.
 | `parseSseStream` | Generic SSE chunk decoder (used by `streamRunLogs`) |
 | `createSandbox` / `reconnectSandbox` / `killAllSandboxes` / `killSandboxById` / `getSandboxQuotas` / `listOwnedSandboxes` / `deleteSandboxSnapshot` | Sandbox-provider helpers (Vercel + E2B) |
 
-Type exports: `WorkflowFn`, `WorkflowCtx`, `WorkflowDefinition`,
+Type exports: `Workflow`, `Step`, `StepContext`, `WorkflowBuilder`,
 `WorkflowHooks`, `AgentBudget`, `AgentRuntime`, `RuntimeOptions`,
 `ModelExecutionContract`, `McpServerConfig`, `AgentMessage` (and its
 variants), `AgentStatus`, `RunStatus`, `RegisterResult`, `RunEvent`,

package/dist/agent/__tests__/runtime-json-schema.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * responseSchema → runtime outputFormat must NOT carry zod v4's
+ * `$schema: …/draft/2020-12/schema` header. Claude Code validates
+ * `--json-schema` with a validator that has no 2020-12 meta-schema
+ * registered, so a schema carrying the header kills the CLI at startup
+ * ("Claude Code process exited with code 1" before any API call) — the
+ * incident that took down every dynamic-task run after the 2026-07-17
+ * agent-env rebake baked claude 2.1.212.
+ */
+export {};

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

@@ -19,7 +19,27 @@ import type { SandboxProvider } from "../types/sandbox.js";
  * that credentials are network-injected (never in the env). The live
  * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
  */
-export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace` \u2014 import it from any script\nyou write there:\n\n    import { defineWorkflow, agent, AgentComposeClient } from \"@agent-compose/sdk\";\n\nUse `/ac:generate-workflow` / `/ac:generate-agent` to scaffold, then\n`agentc register <file.ts>` (or `/ac:register`).\n\n## Pausing to ask the human \u2014 `agentc pause`\n\nWhen you can't or shouldn't proceed without a human, run `agentc pause`, then\n**END YOUR TURN**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n`agentc pause` does NOT block and does NOT print the answer. It records your\nquestion and returns immediately. The moment you end your turn, the run pauses\n(your sandbox is snapshotted and compute stops while the human decides) and the\nhuman's answer is delivered to you as your **next message** \u2014 you pick up\nexactly where you left off, with the answer in hand. So: ask, end your turn,\nand wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task\ncomplete after pausing.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- A world-writable `/workspace` working directory";
+export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace`. **To author a workflow,\nALWAYS run `/ac:generate-workflow`** (and `/ac:generate-agent` for an agent\nstep) instead of writing source from memory \u2014 the skill scaffolds the correct,\ncurrent shape. Then `agentc register <file.ts>` (or `/ac:register`).\n\nThe skill writes **step-form** (a builder of discrete, durable `.step()`s).\nThe legacy run-form (`defineWorkflow({ run(ctx, sandbox) { \u2026 } })`) has been\nREMOVED from the SDK \u2014 registering one fails with an error. Step-form is the\nonly shape: durable per-step replay, and pause only works there.\n\n## Pausing to ask the human\n\nTo ask a human and get an answer back, use the **`AskUserQuestion`** tool if\nyou have it; otherwise run **`agentc pause`**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n**Both BLOCK and hand you the answer inline.** While you wait, the run is\nsuspended \u2014 your sandbox is frozen and compute stops, so a pause is free while\nthe human decides. When they answer, the call RETURNS with their decision: the\n`AskUserQuestion` tool result, or `agentc pause`'s output\n(`\u25B6 Resumed. The human answered: \u2026`), carries it.\n\n**Then USE that answer to finish your work \u2014 do NOT end your turn.** This is NOT\nfire-and-forget, and the answer does NOT arrive in a later message: it comes\nback right where you called it, on the SAME turn. The shape is: ask \u2192 the call\nblocks \u2192 it returns the human's answer \u2192 you act on it and produce your result.\nNever end your turn before the call returns, never guess an answer, and never\nproceed without one.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Computer Use \u2014 you have a real desktop, and it is already running\n\n**This machine has a graphical desktop.** Every session machine does \u2014 terminal\nsessions included \u2014 and the platform brings it UP AT BOOT, before your first\nturn: an X server on `DISPLAY=:0`, the openbox window manager, wallpaper and a\npanel. You do not start it, you do not wait for a human to open it, and you do\nnot need a viewer. Go straight to driving it.\n\n(The one exception, and it is rare: an image built without the GUI stack has no\ndisplay at all, and `DISPLAY=:0 xdotool getdisplaygeometry` errors outright.\nThat single case is the only one where this section does not apply \u2014 a\nscreenshot showing only wallpaper is NOT it, and neither is an app that failed\nto start.)\n\n**This is how you SEE anything.** Any question of the form \"does it render?\",\n\"is the page actually working?\", \"did the markers show up?\", \"what does it look\nlike?\" is answered by opening it on this desktop and screenshotting it \u2014 not by\nreasoning about the code, and not by a headless render (which proves the process\nstarts, not that the thing draws). Verify visually before you report visually.\n\n- **Input** \u2014 `xdotool` against `DISPLAY=:0`: `DISPLAY=:0 xdotool mousemove <x> <y>`,\n  `DISPLAY=:0 xdotool click 1` (1=left, 3=right), `DISPLAY=:0 xdotool type 'text'`,\n  `DISPLAY=:0 xdotool key Return` (also `ctrl+c`, `Tab`, `super`, \u2026).\n- **Screenshots** \u2014 `scrot` (or ImageMagick's `import`):\n  `DISPLAY=:0 scrot /tmp/screen.png`, then READ the PNG to see the screen,\n  before and after you act. A screenshot is your only eyes here.\n- **Apps + windows** \u2014 a plain X session. Launch in the background:\n  `DISPLAY=:0 <app> &`. Two things that trip agents up, both normal:\n  - a GUI app needs a **beat to map its window** \u2014 screenshot, and if you see\n    only wallpaper, wait a couple of seconds and screenshot again before\n    concluding anything;\n  - **Chromium needs `--no-sandbox`** in this environment (nested sandbox).\n    The whole recipe for looking at a local page:\n    `DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &`\n    then `sleep 5`, then `DISPLAY=:0 scrot /tmp/screen.png` and read it.\n  If a window still never appears, read the app's own log (`/tmp/*.log`) \u2014 the\n  desktop is not the thing that failed. Do NOT abandon it for a headless\n  screenshot: headless cannot tell you what the human will see.\n- **A human can watch** \u2014 the session header carries a **Desktop** button in the\n  dashboard, and what a teammate sees there is exactly this display. The desktop\n  runs whether or not anyone is looking; never wait for a viewer.\n\nNothing here changes the credentials rule above: tokens are injected at the\nnetwork layer, never present on the desktop or in any file you can read \u2014 so\nthere is nothing to type, paste, or screenshot a credential from.\n\n## Recording a demo \u2014 the desktop, captured to a video the human can play\n\n\"Record a demo of you using X\" is a normal ask, and this machine does it:\nstart a screen recording, drive the app with `xdotool` exactly as in Computer\nUse, stop the recording, and report the file. (For a LIVE view no recording is\nneeded \u2014 the session header's **Desktop** button already streams this display\nto any teammate watching; a recording is the durable, replayable artifact.\nBoth modes exist; say so when it matters.)\n\n**ffmpeg is NOT pre-installed** \u2014 install it first, once per machine:\n\n    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\n\n(drop `sudo` if you are already root). Then the whole recipe:\n\n    DISPLAY=:0 ffmpeg -f x11grab \\\n      -video_size \"$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)\" \\\n      -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\\n      demo.webm &\n    FFMPEG_PID=$!\n    # ... drive the app with xdotool, screenshotting as you go ...\n    kill -INT \"$FFMPEG_PID\" && wait \"$FFMPEG_PID\"\n\nThe gotchas, each one earned:\n- **Stop with SIGINT (`kill -INT`), never SIGKILL** \u2014 ffmpeg finalizes the\n  file on SIGINT; a hard kill truncates the encode mid-write.\n- **Record WebM (matroska-family), not MP4** \u2014 mp4 writes its moov atom at the\n  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays\n  playable up to the last written frame and plays natively in the browser.\n  MP4's only edge is compatibility with some external players \u2014 transcode\n  afterwards if you truly need it, never record straight to it.\n- **`-video_size` must match the real screen** \u2014 x11grab does not default to\n  it; read the geometry from `xdotool getdisplaygeometry` as above.\n- **10\u201312 fps is right for a screen demo** \u2014 small files, legible UI motion;\n  this is not video production.\n- **Write to the drive, not /tmp** \u2014 the recording must land in your working\n  directory to persist and show up in Files; a file in /tmp dies with the\n  sandbox.\n- When you stop, **TELL the human the exact drive path** of the video \u2014 a\n  recording they cannot find might as well not exist.\n\n## Previews \u2014 register every server you serve (cloud sessions)\n\nIn a cloud session, a dev server listening on a port becomes a hosted,\nmember-gated URL the human can open \u2014 but ONLY if you register it:\n\n    agentc preview open <port> [--name <label>] [--path </landing>]\n                                                 # hosted URL + an \"Open preview\" card\n    agentc preview list                          # the registry \u2014 what is live right now\n    agentc preview close <port>                  # take one down\n\n(`agentc preview announce` is the same verb as `open` \u2014 announce what you\nserve.) `--name` is the human-readable label; `--path` is where the app\nshould open (e.g. `/dashboard`) \u2014 the card and every chip land the human\nthere instead of a bare `/`.\n\nRegister EVERY server you start for a human, the moment it is listening, and\ntell them the URL the command printed. The registry is the only discoverable\nrecord of what this machine serves: an unregistered server keeps running, but\nnobody \u2014 not the human, not the assistant \u2014 can find its URL, and when the\nsandbox recycles it is gone without a trace. Never guess or hand out a raw\nport; the hosted URL from `agentc preview open` is the only address that\nworks outside this machine. (Outside a cloud session the command errors\nhonestly \u2014 there is no session sandbox to expose.)\n\nWhat registration buys you: the human sees each registered preview as a card\nin the conversation and a row in the session's Previews menu \u2014 MANY at once,\none per port \u2014 and the assistant resolves \"open the preview\" from this same\nregistry (its `list_previews` read), so what you register is exactly what\ngets opened. On deployments with subdomain previews the hosted URL is a real\norigin of its own \u2014 absolute asset paths and client-side routing work, the\nwhole app is navigable \u2014 so serve normally and let the platform address it;\nnever rewrite your app to a path prefix.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- `xdotool` / `scrot` \u2014 drive + screenshot the desktop (if this machine has one; see Computer Use)\n- 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 declare function buildAddedSessionBrief(p: AddedSessionBriefParams): string;
 /**
  * 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/dist/agent/agent-loop.d.ts

@@ -11,6 +11,20 @@ import { RequestContext } from "../request-context/request-context.js";
 import { type SteerPayload } from "./steer-control.js";
 export declare const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 export declare function parseAgentStatus(text: string): AgentStatus | null;
+/**
+ * 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 declare function runtimeJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown>;
 export interface AgentLoopResult<TResponse = unknown> {
     agentId: string;
     label: string;
@@ -62,7 +76,15 @@ export type AgentMessageSummary = {
         status: "pending" | "in_progress" | "completed";
     }[];
 };
-export declare 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 declare function summarizeAgentMessage(msg: DurableAgentMessage): AgentMessageSummary;
 export type AgentLifecycleEvent = {
     event: "agent.spawned";
     at: number;
@@ -152,3 +174,4 @@ export interface AgentLoopOpts<TResponse = unknown> {
     mode?: "auto" | "hitl";
 }
 export declare function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TResponse>): Promise<AgentLoopResult<TResponse>>;
+export {};