@alexkroman1/aai-cli 7.0.0 → 8.1.0

package/dist/scaffold/CLAUDE.md

@@ -18,11 +18,51 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    agent that no longer exists. When a test fails after your change, decide
    which side is stale: updating the test to match the new agent is a normal
    fix, not a workaround. Do not delete a test to make it pass.
-3. **Run `pnpm build` before declaring done** — bundles `agent.ts`,
+3. **Run `pnpm eval` when you change what the agent DOES** — a test asserts
+   the agent's shape; an eval drives a real session and asserts what it did.
+   Cases live in `agent.eval.test.ts` (the `simple` template ships one):
+
+   ```ts no-check
+   import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+   import { expect } from "vitest";
+   import agentDef from "./agent.ts";
+
+   describeEval(agentDef, (test) => {
+     test(
+       "looks the order up before answering",
+       async ({ session }) => {
+         // `say()` returns THAT turn — the reply, its tool calls, its events.
+         const turn = await session.say("where is order W1234?");
+         expect(turn.toolCalls.map((c) => c.name)).toContain("look_up");
+         expect(turn.text).toMatch(/shipped/i);
+       },
+       // What a SCRIPTED model answers with when there is no key (below).
+       { stubReply: "Order W1234 shipped yesterday." },
+     );
+   });
+   ```
+
+   Everything is real except the microphone and the speaker: your tools run,
+   your prompt runs, the session's own event stream is what you assert over.
+   Two things to know before reading a green run:
+
+   - **With a provider key it uses a LIVE model** — it spends tokens, and it is
+     a noisy instrument. One failure is a question, not a verdict; re-run before
+     believing either answer.
+   - **Without one it uses a SCRIPTED model** answering each case's `stubReply`,
+     and says so. That still proves the agent boots, the tools resolve and the
+     session reaches a reply — it proves nothing about what the agent SAYS. Give
+     a case `{ live: true }` instead when no script could honestly stand in
+     (a tool the model has to choose for itself, a refusal, a judgement).
+
+   No eval can see anything below the audio boundary — when the agent decides
+   you stopped talking, barge-in, two sentences merging into one turn. Those
+   need `pnpm dev` and your own voice.
+4. **Run `pnpm build` before declaring done** — bundles `agent.ts`,
    type-checks, and validates the manifest. Catches issues `dev` won't.
-4. **Make small, focused changes** — verify each one before stacking the
+5. **Make small, focused changes** — verify each one before stacking the
    next.
-5. **Look at templates before writing custom code** — the CLI ships working
+6. **Look at templates before writing custom code** — the CLI ships working
    examples inside its own package, at
    `node_modules/@alexkroman1/aai-cli/dist/templates/`. Read them directly;
    `aai init --template <name>` scaffolds a fresh project from one. Closest
@@ -51,6 +91,7 @@ npx @alexkroman1/aai-cli init             # Scaffold a new agent
 npx @alexkroman1/aai-cli templates        # List available templates
 npx @alexkroman1/aai-cli dev              # Start local dev server
 npx @alexkroman1/aai-cli test             # Run agent.test.ts via vitest
+npx @alexkroman1/aai-cli eval             # Run agent.eval.test.ts against a model
 npx @alexkroman1/aai-cli build            # Bundle and validate
 npx @alexkroman1/aai-cli deploy           # Deploy to production
 npx @alexkroman1/aai-cli delete           # Remove deployed agent
@@ -59,9 +100,9 @@ npx @alexkroman1/aai-cli secret delete NAME
 npx @alexkroman1/aai-cli secret list
 ```
 
-The scaffold's `package.json` exposes `dev`, `build`, `test`, and `deploy`
-as `pnpm <name>` shortcuts. Other commands (`init`, `templates`, `delete`, `secret`)
-are CLI-only.
+The scaffold's `package.json` exposes `dev`, `build`, `test`, `eval` and
+`deploy` as `pnpm <name>` shortcuts. Other commands (`init`, `templates`,
+`delete`, `secret`) are CLI-only.
 
 ## Running it yourself (`npm start`)
 
@@ -75,11 +116,15 @@ PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
 
 `npm start` **builds first** (that is the `prestart` script) and then serves
 the result: `server.mjs` boots `.aai/worker.mjs`, the same artifact
-`aai publish` uploads. The build is what makes `tools/` work — a tool is
-registered by existing, and the enumeration happens where the bundle is
-assembled, so a server that loaded `agent.ts` directly would run an agent with
-none of its tools. The same build produces your `client.tsx`, so a custom UI is
-served with no extra step.
+`aai publish` uploads. It serves your own `client.tsx` build when there is one
+and falls back to `defaultClientDir()` (`@alexkroman1/aai-ui/client-dir`), the
+prebuilt default UI shipped inside the package — the only export of `aai-ui`
+that runs on Node rather than in the browser.
+
+The build is what makes `tools/` work — a tool is registered by existing, and
+the enumeration happens where the bundle is assembled, so a server that loaded
+`agent.ts` directly would run an agent with none of its tools. The same build
+produces your `client.tsx`, so a custom UI is served with no extra step.
 
 Secrets work the same as everywhere else: `ctx.env` holds the keys declared
 in `.env` (or `.env.example`), and a real environment variable of that name
@@ -99,6 +144,7 @@ it needs the platform's sandbox and refuses outside one.
 my-agent/
   agent.ts            # Agent definition (required)
   agent.test.ts       # Unit tests (optional)
+  agent.eval.test.ts  # Behaviour evals, run by `pnpm eval` (optional)
   client.tsx          # Custom UI (optional, React)
   shared.ts           # Types shared between agent.ts and client.tsx
   system-prompt.md    # The system prompt — discovered, not imported
@@ -213,6 +259,19 @@ import { agent } from "@alexkroman1/aai";
 export default agent({ name: "My Agent" });
 ```
 
+Declare neither and the agent runs on `DEFAULT_SYSTEM_PROMPT`, exported from
+`@alexkroman1/aai` so you can read what you are replacing — or compose against
+it, rather than restating the voice rules at the bottom of this guide:
+
+```ts
+import { DEFAULT_SYSTEM_PROMPT, agent } from "@alexkroman1/aai";
+
+export default agent({
+  name: "My Agent",
+  systemPrompt: `${DEFAULT_SYSTEM_PROMPT}\n\nYou only ever discuss pizza.`,
+});
+```
+
 ```markdown
 <!-- system-prompt.md -->
 You are a concise, friendly assistant.
@@ -369,10 +428,10 @@ A step has no `ctx`, so the two things tool code takes for granted come from
 root barrel would drag the whole SDK into that bundle.
 
 ```ts no-check
-import { requireStepEnv, stepEnv, StepGenerateError, stepGenerate } from "@alexkroman1/aai/step";
-import { FatalError } from "workflow";
+import { stepEnv } from "@alexkroman1/aai/step";
+import { stepGenerateClassified } from "@alexkroman1/aai/step-errors";
 
-async function summarize(url: string, text: string) {
+async function summarize(text: string) {
   "use step";
 
   // The agent's env by name — the same values a tool reads from `ctx.env`.
@@ -380,16 +439,9 @@ async function summarize(url: string, text: string) {
   const style = stepEnv("DIGEST_STYLE") ?? "plain";
 
   // One model call, on the agent's own ASSEMBLYAI_API_KEY and default model.
-  return await stepGenerate(`${style} summary of:\n\n${text}`, {
+  return await stepGenerateClassified(`${style} summary of:\n\n${text}`, {
     system: "Reply with two sentences and nothing else.",
-  }).catch(stopOrRetry);
-}
-
-// The DevKit retries a step that throws, so decide which failures deserve it.
-// A rate limit does; a bad key does not.
-function stopOrRetry(err: unknown): never {
-  if (err instanceof StepGenerateError && !err.retryable) throw new FatalError(err.message);
-  throw err;
+  });
 }
 ```
 
@@ -399,7 +451,118 @@ before and after a deploy. List what you read in `requiredEnv` and a deploy
 checks it for you. And **`stepGenerate` is not `ctx.generate`**: it is one
 request to the AssemblyAI LLM Gateway, with no tools and no structured output,
 because bundling the AI SDK into a step artifact costs megabytes on every
-deploy. Ask it for JSON and parse the reply if you need a shape.
+deploy. Use `stepGenerateJsonClassified` with a Zod `schema` if you need a shape.
+
+### From a step, reach for the `Classified` call
+
+`@alexkroman1/aai/step-errors` publishes a wrapper for every `/step` call that
+can fail against a remote service, and **inside a `"use step"` body the wrapper
+is the one to use**:
+
+| Raw, on `@alexkroman1/aai/step` | Use this instead, on `@alexkroman1/aai/step-errors` |
+| --- | --- |
+| `stepGenerate` | `stepGenerateClassified` |
+| `stepGenerateJson` | `stepGenerateJsonClassified` |
+| `stepFetch` | `stepFetchOk` |
+| `stepTranscribeSync` | `stepTranscribeSyncClassified` |
+| `stepTranscribeUpload` / `Submit` / `Poll` | the matching `*Classified` |
+| `sendToChannel` (`/channels`) | `sendToChannelClassified` |
+
+The whole of what a wrapper adds is `throwStepError`, and that is worth having
+because the DevKit's retry policy is decided by WHICH error a step throws. Raw,
+every failure looks the same to it: a bad API key is retried until the attempts
+run out, and a rate limit backs off for the DevKit's default one second while
+the delay the gateway itself named sits unread on the error. Classified, a
+terminal failure raises `FatalError` and stops, and a transient one raises
+`RetryableError` carrying the far side's own `Retry-After`. That matters most
+where this SDK encourages a fan-out, because N steps hit a rate limit together
+and a second later all N ask again.
+
+**Reach for the raw call when the failure is not simply a failure** — a `404`
+that means "already deleted", a `4xx` whose body decides which advice to print.
+Then classify it yourself: `throwStepError(err)`, `throwFatalStepError(err)` to
+stop outright, `toStepError(cause, message)` to build the error without throwing,
+or `throwFfmpegStepError(err)` for a media failure, whose default runs the other
+way (only a `timeout` or an `aborted` is worth another attempt).
+
+**Why the split exists, since the wrapper is what you usually want:** this is
+the one authoring module allowed to import the DevKit's `workflow` package, and
+`/step` is not written only for a step — `mapConcurrent` bounds a rate-limited
+call anywhere, `stepFetch` is an ordinary HTTP client, and your specs drive
+exported steps directly. Putting `workflow` in `/step`'s graph would put it in
+every one of those bundles. A step pays nothing for the extra import line.
+
+### Media, big files, and transcription from a step
+
+Three more subpaths a `workflows/*.ts` module can reach, all with the same
+bundling rule as `/step` — import them there, never through the root barrel:
+
+- **`@alexkroman1/aai/transcribe`** — `stepTranscribeSync(bytes)` for a short
+  recording, or `stepTranscribeUpload` → `stepTranscribeSubmit` →
+  `stepTranscribePoll` for a long one, plus `Transcript`, `TranscribeError` and
+  the `TRANSCRIBE_*` limits. Use the `Classified` wrappers above: a provider
+  refusal — a container it will not read, a recording with no speech — arrives
+  with `retryable: false`, and unclassified a step re-uploads the same bytes
+  until its attempts run out.
+- **`@alexkroman1/aai/ffmpeg`** — `transcodeToWav(bytes, { sampleRate })`,
+  `runFfmpeg(args)`, `probeMedia(source)` for duration and stream info, and
+  `FfmpegError`/`isFfmpegError`. Under `aai dev` it needs ffmpeg on your PATH;
+  a `missing-binary` failure says so and carries the install line.
+- **`@alexkroman1/aai/step-files`** — for a recording too big to hold in memory.
+  `readUploadToFile(uploadId, path)` streams an upload to disk,
+  `writeUploadFromFile(path)` streams one back, and `withTempDir(work)` gives
+  both a directory that is cleaned up even when the step throws.
+
+```ts no-check
+import { probeMedia, runFfmpeg } from "@alexkroman1/aai/ffmpeg";
+import { throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
+import { readUploadToFile, withTempDir } from "@alexkroman1/aai/step-files";
+
+export async function measure(uploadId: string) {
+  "use step";
+
+  return await withTempDir(async (dir) => {
+    const path = `${dir}/input`;
+    // Read the upload ONCE. A five-step version reads it five times, and on a
+    // 700 MB recording that is the expensive part by an order of magnitude.
+    await readUploadToFile(uploadId, path);
+    const media = await probeMedia(path).catch(throwFfmpegStepError);
+    return { durationMs: media.durationMs };
+  });
+}
+```
+
+`call-audit` is the worked example for all three at once.
+
+### Posting somewhere — `@alexkroman1/aai/channels`
+
+A run that finishes while nobody is on the line needs somewhere to put the
+result. `slackChannel({ webhookUrl })` names a destination and
+`sendToChannelClassified(channel, message)` posts to it:
+
+```ts no-check
+import { type ChannelMessage, slackChannel } from "@alexkroman1/aai/channels";
+import { requireStepEnv } from "@alexkroman1/aai/step";
+import { sendToChannelClassified } from "@alexkroman1/aai/step-errors";
+
+export async function announce(headline: string, points: string[]) {
+  "use step";
+
+  const message: ChannelMessage = {
+    text: headline,
+    sections: points.map((point) => ({ text: point })),
+  };
+  return await sendToChannelClassified(slackChannel({ webhookUrl: requireStepEnv("SLACK_WEBHOOK_URL") }), message);
+}
+```
+
+The webhook URL is a secret like any other — declare it in `requiredEnv` and set
+it with `aai secret put`. A channel's credential is its DESTINATION and is
+passed in, which is why no channel reads an env var of its own. `ChannelMessage`
+is rendered per platform, so the same message is legal on a channel kind added
+later; `isSlackWebhookUrl` / `isSlackWorkflowTriggerUrl` validate a pasted URL
+before a run depends on it, and `channelAdvice` turns a refusal into a sentence
+a person can act on. `podcast-digest` is the worked example.
 
 ### A step's HTTP: use `stepFetch`, not `fetch`
 
@@ -685,14 +848,14 @@ descriptor (the descriptor owns its own voice). A raw config that skips
 ```ts
 import { agent } from "@alexkroman1/aai";
 import { assemblyAIStt } from "@alexkroman1/aai/stt";
-import { anthropic } from "@alexkroman1/aai/llm";
-import { cartesia } from "@alexkroman1/aai/tts";
+import { anthropicLlm } from "@alexkroman1/aai/llm";
+import { cartesiaTts } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
   stt: assemblyAIStt({ model: "universal-3-5-pro" }),
-  llm: anthropic({ model: "claude-haiku-4-5" }),
-  tts: cartesia(),
+  llm: anthropicLlm({ model: "claude-haiku-4-5" }),
+  tts: cartesiaTts(),
 });
 ```
 
@@ -716,7 +879,7 @@ one-word backchannels like "yeah" don't cut it off);
 500 ms; `0` disables; interim transcripts only — committed turns always
 land). End-of-turn detection (how long a pause ends the user's turn)
 belongs to the STT provider: `assemblyAIStt({ minTurnSilenceMs })` (default
-1600 ms) / `deepgram({ endpointing })` (default 1500 ms), so mid-utterance
+1600 ms) / `deepgramStt({ endpointing })` (default 1500 ms), so mid-utterance
 pauses don't split a request.
 `deadAirCoverMs` is how long a turn may go silent before the transport speaks
 a short filler, so a long tool chain doesn't sound like a dropped call. It is
@@ -753,15 +916,15 @@ for the providers you actually use.
 | Factory         | Default model          | Env var              |
 | --------------- | ---------------------- | -------------------- |
 | `assemblyAIStt` | `"universal-3-5-pro"`  | `ASSEMBLYAI_API_KEY` |
-| `deepgram`      | `"nova-3"`             | `DEEPGRAM_API_KEY`   |
+| `deepgramStt`   | `"nova-3"`             | `DEEPGRAM_API_KEY`   |
 | `elevenLabsStt` | `"scribe_v2_realtime"` | `ELEVENLABS_API_KEY` |
-| `soniox`        | `"stt-rt-v3"`          | `SONIOX_API_KEY`     |
+| `sonioxStt`     | `"stt-rt-v3"`          | `SONIOX_API_KEY`     |
 
 All STT factories accept `{ model?: string, ... }`. Bare calls
-(`deepgram()`, `soniox()`, etc.) use the default model. Language is spelled
-`language` where the vendor takes one code (`deepgram`, `elevenLabsStt`) and
-`languages` where it takes a list (`assemblyAIStt`, `soniox`) — and only
-`deepgram`'s unset value means English; the other three auto-detect.
+(`deepgramStt()`, `sonioxStt()`, etc.) use the default model. Language is spelled
+`language` where the vendor takes one code (`deepgramStt`, `elevenLabsStt`) and
+`languages` where it takes a list (`assemblyAIStt`, `sonioxStt`) — and only
+`deepgramStt`'s unset value means English; the other three auto-detect.
 
 `elevenLabsStt` carries the stage in its name because ElevenLabs is
 better known for TTS: when that stage arrives, `elevenLabs` is the name it
@@ -776,32 +939,32 @@ API keys require it; the US endpoints reject them. Example:
 
 | Factory         | SDK package         | Env var                        |
 | --------------- | ------------------- | ------------------------------ |
-| `anthropic`     | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY`            |
-| `openai`        | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
-| `google`        | `@ai-sdk/google`    | `GOOGLE_GENERATIVE_AI_API_KEY` |
-| `mistral`       | `@ai-sdk/mistral`   | `MISTRAL_API_KEY`              |
-| `xai`           | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
-| `groq`          | `@ai-sdk/groq`      | `GROQ_API_KEY`                 |
-| `openrouter`    | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
-| `gateway`       | `ai` (built in)     | `AI_GATEWAY_API_KEY`           |
+| `anthropicLlm`  | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY`            |
+| `openaiLlm`     | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
+| `googleLlm`     | `@ai-sdk/google`    | `GOOGLE_GENERATIVE_AI_API_KEY` |
+| `mistralLlm`    | `@ai-sdk/mistral`   | `MISTRAL_API_KEY`              |
+| `xaiLlm`        | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
+| `groqLlm`       | `@ai-sdk/groq`      | `GROQ_API_KEY`                 |
+| `openrouterLlm` | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
+| `gatewayLlm`    | `ai` (built in)     | `AI_GATEWAY_API_KEY`           |
 | `assemblyAILlm` | `@ai-sdk/openai`    | `ASSEMBLYAI_API_KEY`           |
 
 LLM factories require `{ model: string }` — the `ModelOptions` interface,
 shared by all of them except `assemblyAILlm`. Example:
-`anthropic({ model: "claude-haiku-4-5" })`. The argument is required because a
-third-party vendor's catalog is not this SDK's to default from;
+`anthropicLlm({ model: "claude-haiku-4-5" })`. The argument is required
+because a third-party vendor's catalog is not this SDK's to default from;
 `assemblyAILlm()` is the one bare call, since it has a default model.
 
-`openrouter` routes through [OpenRouter](https://openrouter.ai) — an
+`openrouterLlm` routes through [OpenRouter](https://openrouter.ai) — an
 OpenAI-compatible endpoint fronting hundreds of models addressed as
 `"creator/model"`, e.g.
-`openrouter({ model: "meta-llama/llama-3.3-70b-instruct" })`. It needs
+`openrouterLlm({ model: "meta-llama/llama-3.3-70b-instruct" })`. It needs
 no extra SDK install (it reuses the `@ai-sdk/openai` client).
 
-`gateway` routes through the [Vercel AI
+`gatewayLlm` routes through the [Vercel AI
 Gateway](https://vercel.com/docs/ai-gateway) — one endpoint fronting
 hundreds of models addressed as `"creator/model"`, e.g.
-`gateway({ model: "zai/glm-4.6" })`. It needs no extra SDK install
+`gatewayLlm({ model: "zai/glm-4.6" })`. It needs no extra SDK install
 (the gateway client ships inside the `ai` package).
 
 `assemblyAILlm` routes through the [AssemblyAI LLM
@@ -826,12 +989,12 @@ Mixing providers works the same way — declare the stages you're changing:
 
 ```ts
 import { agent } from "@alexkroman1/aai";
-import { cartesia } from "@alexkroman1/aai/tts";
+import { cartesiaTts } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
   llm: "claude-sonnet-4-6",
-  tts: cartesia(),
+  tts: cartesiaTts(),
 });
 ```
 
@@ -840,10 +1003,10 @@ export default agent({
 | Factory         | Default voice                            | Env var              |
 | --------------- | ---------------------------------------- | -------------------- |
 | `assemblyAITts` | `"jane"`                                 | `ASSEMBLYAI_API_KEY` |
-| `cartesia`      | `"f786b574-daa5-4673-aa0c-cbe3e8534c02"` | `CARTESIA_API_KEY`   |
-| `rime`          | `"cove"` (model `mistv2`)                | `RIME_API_KEY`       |
+| `cartesiaTts`   | `"f786b574-daa5-4673-aa0c-cbe3e8534c02"` | `CARTESIA_API_KEY`   |
+| `rimeTts`       | `"cove"` (model `mistv2`)                | `RIME_API_KEY`       |
 
-Bare calls (`assemblyAITts()`, `cartesia()`, `rime()`) use the defaults.
+Bare calls (`assemblyAITts()`, `cartesiaTts()`, `rimeTts()`) use the defaults.
 Override with `{ voice, model, language }`.
 
 **AssemblyAI TTS** shares `ASSEMBLYAI_API_KEY` with AssemblyAI STT and the
@@ -908,6 +1071,8 @@ ctx.sessionId: string                          // unique session ID
 ctx.send(event: string, data: unknown): void   // push custom event to browser client (silently dropped over 64 KB JSON)
 ctx.generate(opts): Promise<{ text, object? }> // one-shot LLM call (host-side)
                                                // with a `schema`, `object` is REQUIRED and typed by it
+ctx.delegate(sub, opts): Promise<DelegateResult> // run a subagent — a whole tool loop with its own
+                                               // context window (see "Subagents")
 ctx.signal: AbortSignal                        // aborts on barge-in, reset, session stop, or this call's timeout
 ```
 
@@ -931,29 +1096,29 @@ export const lookup = tool({
 });
 ```
 
-**The project's tsconfig turns off `noImplicitAny`, so write the code first.**
-Do NOT add type annotations defensively — almost nothing requires them, and time
-spent on them is time not spent on the agent.
+**Write the code first; let inference do the work.** The project runs `strict`,
+so a variable declared empty and filled in the same scope widens from what you
+put in it — `const items = []` followed by `items.push(pick)` infers `Pick[]`
+with no annotation. Do NOT add type annotations defensively.
 
-**The one exception, and it is not optional: annotate any variable you
-declare empty.** With `noImplicitAny` off, TypeScript does not widen an empty
-initializer from what you later assign, so `[]` stays `never[]` and `null`
-stays `null` — forever, whether or not a callback is involved:
+**Annotate the DECLARATION when the first write is somewhere the compiler
+cannot follow** — inside a callback, or after the value has already been read.
+The widening only tracks straight-line code in one scope, so in those cases the
+declaration keeps its starting type:
 
 ```ts no-check
-const items = [];            // never[]  → items.push(x) is an error
-let best = null;             // null     → best = {...} is an error
-const [picks, set] = useState([]);  // never[] in a client, same thing
+const items = [];                      // stays never[] if the only push is in a callback
+let best = null;                       // stays null if the only assignment is in a callback
+const [picks, set] = useState([]);     // never[] — useState's argument is read immediately
 
-const items: Pick[] = [];    // ✅ annotate the DECLARATION
-let best: Pick | null = null;       // ✅
+const items: Pick[] = [];              // ✅ annotate the DECLARATION
+let best: Pick | null = null;          // ✅
 const [picks, set] = useState<Pick[]>([]);  // ✅
 ```
 
 Annotating the *use* instead does not help — the declaration is still wrong,
 so the next push reports the next line, and you can burn a whole session
-fixing one call site at a time. This is the single most common way a
-generated agent fails to build.
+fixing one call site at a time.
 
 ### Session state
 
@@ -1037,6 +1202,129 @@ that's also how S2S agents use it. Pass a Zod schema as `schema` for typed
 structured output (`generateObject`-style): the result's `object` carries
 the parsed, typed value. A plain JSON Schema object also works.
 
+The option bag is `GenerateOptions` and the answer is `GenerateResult`
+(`GenerateObjectResult<T>` with a `schema`), both exported from
+`@alexkroman1/aai` — annotate a helper that wraps the call rather than
+re-describing the shape. `GenerateFn` is the type of `ctx.generate` itself,
+which is what a spec passes to `createToolContext({ generate })`.
+
+### When the NEXT step is the hard part — `dialog()` and `procedure()`
+
+Two declarations for flows, and the difference is who is driving.
+
+**`dialog()` gates what the MODEL may do next.** A prompt asking the agent to
+collect an address before taking payment is a suggestion; a dialog is a rule.
+`dialog(key, spec)` takes `{ initial, states }`, each state carrying an
+`instruction` the agent is given while it is there and an `on` map of the events
+that leave it. It is a slot underneath, so the position is persisted with the
+rest of the session and survives a reconnect.
+
+```ts no-check
+import { dialog } from "@alexkroman1/aai";
+
+export const checkout = dialog("checkout", {
+  initial: "collecting",
+  states: {
+    collecting: {
+      instruction: "Take the order. Confirm it back before charging anything.",
+      on: { CONFIRMED: "paying" },
+    },
+    paying: {
+      instruction: "Take payment with charge_card. Do not add items now.",
+      on: { PAID: "done" },
+    },
+    done: { instruction: "Read back the order number and say goodbye." },
+  },
+});
+```
+
+A tool declared with `checkout.tool({...})` is REFUSED unless the dialog is in a
+state that allows it, and the refusal reaches the model as a `ToolFailure` it
+can recover from — the point being that the gate is enforced at EXECUTION
+rather than hoped for in a prompt. The states and events are inferred from the
+spec, so a misspelled `send` is a compile error. `dispatch-center` and
+`solo-rpg` are the worked examples.
+
+**`procedure()` runs a flow YOU drive, with no model in the loop.** Where a
+dialog constrains a conversation, a procedure is an algorithm with branches,
+retries and a bounded budget — a grading loop, a retrieval-and-check cycle —
+expressed as a statechart rather than as a `while` with four early returns:
+
+```ts no-check
+import { procedure } from "@alexkroman1/aai";
+
+const answer = procedure(ragMachine);
+const result = await answer.run({ question }, { signal: ctx.signal });
+```
+
+`run` resolves with the machine's output, or throws `ProcedureNotFinishedError`
+if it stops without reaching a final state — which is what makes "we ran out of
+attempts" a state you declare and handle rather than an error. Options are
+`ProcedureRunOptions`; the machine is an XState machine, and `xstate` is already
+an SDK dependency. `support-line` is the worked example.
+
+### Subagents (`ctx.delegate`)
+
+`ctx.generate` is ONE prompt. When answering takes an unknown number of tool
+calls whose intermediate results the conversation has no reason to carry,
+delegate to a **subagent** instead: a second tool loop with its own
+instructions, model, tools and — the whole point — its own context window.
+
+```ts
+import { subagent, tool } from "@alexkroman1/aai";
+import { z } from "zod";
+
+const researcher = subagent({
+  name: "researcher",
+  instructions:
+    "Research the task with the tools you have. IMPORTANT: your final message " +
+    "is the only thing the caller sees — end with a self-contained summary.",
+  builtinTools: ["web_search", "visit_webpage"],
+  maxSteps: 6,
+});
+
+export default tool({
+  description: "Research a question in depth",
+  inputSchema: z.object({ question: z.string() }),
+  execute: async ({ question }, ctx) => {
+    const { text, toolCalls } = await ctx.delegate(researcher, { task: question });
+    return { answer: text, lookups: toolCalls.length };
+  },
+});
+```
+
+Four rules, each of which is how a subagent disappoints when you skip it:
+
+- **Tell it to summarize.** You receive its FINAL message. A subagent that
+  signs off with "Done." has thrown away everything it read.
+- **Write the task as a complete brief.** Its context is isolated — it has not
+  heard the conversation. Anything it needs from the call goes in `task`, or in
+  the optional `context` string.
+- **Give it a budget.** `maxSteps` (default: the framework's) bounds the loop;
+  past it the subagent is asked for its answer with its tools withheld, so a
+  capped run still answers. In a voice session the tool timeout bounds the
+  whole thing, so keep it small.
+- **Say you are looking it up before you call.** A delegated run takes a
+  moment, and a silent line is the worst thing on a phone call.
+
+Runs are ordinary promises, so several fan out at once — this is the other
+reason to reach for a subagent:
+
+```ts no-check
+const runs = await Promise.allSettled(
+  angles.map((angle) => ctx.delegate(researcher, { task: angle })),
+);
+```
+
+A subagent may name its own `llm` (a cheaper model for a narrower job) and its
+own `tools` — an explicit map of `tool()` values, which is how you give one
+run a strictly smaller surface than the agent has. **Delegation is one level
+deep**: a subagent's own tools get a `ctx.delegate` that refuses.
+
+In tests, `stubDelegate` from `@alexkroman1/aai/testing` fakes the capability,
+routed by subagent name; `createToolContext()` defaults `delegate` to a
+rejection so an unstubbed run cannot reach a real model.
+
 ### A tool that calls an API
 
 ```ts
@@ -1221,6 +1509,30 @@ Reaching for the `fetch_json` builtin instead is a different design, not a
 shortcut for the same one: it hands URL choice to the model. You cannot
 call it from `execute` — see the builtin table above.
 
+## Small helpers — `@alexkroman1/aai/utils`
+
+Zero-dependency helpers a tool body, a step or a client may reach for, so the
+same three lines are not rewritten per template. Import from `/utils`, which is
+safe from a `workflows/*.ts` module and from a browser bundle:
+
+| Helper | For |
+| --- | --- |
+| `errorMessage(err)`, `errorDetail(err)` | Turning an unknown `catch` value into a sentence for the model or the log |
+| `responseErrorMessage(res, label)` | The same for a non-2xx `Response`, preferring a JSON `error` field over the bare status |
+| `safeJsonParse(text)` | A parse that answers `undefined` instead of throwing |
+| `formatBytes`, `formatDuration`, `countWords`, `plural` | Narration. Each returns ONE fixed shape, so a step's progress line and the page rendering the same run cannot disagree — they did, one template printing `1:04:09` from its workflow and `64:09` from its page |
+| `pushCapped(list, item, max)` | An append that keeps the last N, for a log a session accumulates |
+| `isRecord(x)`, `omitUndefined(obj)` | The object guard and the spread-free way to drop undefined fields |
+| `decodeHtmlEntities(text)` | Scraped text on its way to a model |
+| `createKeyedLock()` / `withLock(lock, key, work)` | Serializing async work per key |
+
+**`createKeyedLock` is the one an agent most needs and least expects to.** The
+LLM loop runs a step's tool calls CONCURRENTLY, so two tools mutating the same
+external resource interleave at every `await`. A session-state mutation is NOT
+that case — `slot.update`'s window is synchronous — so reach for the lock when
+the thing being mutated is outside the session. `withLock` takes an optional
+acquire deadline and throws `KeyedLockTimeoutError` when it runs out.
+
 ## Database API — `ctx.db`
 
 Persistent SQL storage scoped per app, backed by the app's own Postgres
@@ -1487,6 +1799,27 @@ Available from `@alexkroman1/aai-ui`:
 | `MessageList` | — | Messages with auto-scroll, tool calls, transcript |
 | `Controls` | — | Stop/Resume + New Conversation buttons |
 | `Button` | — | Styled button |
+| `UploadProgressBar` | `upload, onPause?, onResume?` | Bytes in flight, with pause/resume |
+
+**Forms are declared, not written.** `<Form onSubmit>` collects typed values off
+the DOM and hands them over once the browser's own validation passes; the field
+components — `TextField`, `TextAreaField`, `NumberField`, `SelectField`,
+`CheckboxField`, `FileField` and `SubmitButton` — are plain named inputs, and
+`Field`/`FieldShell` are what a custom control wraps itself in to match them.
+For a workflow app there is usually no field markup at all: `<WorkflowFields
+workflow="name" />` fetches that workflow's input schema and renders a control
+per field, so a page written against one workflow serves another.
+
+```tsx no-check
+import { Form, WorkflowFields } from "@alexkroman1/aai-ui";
+
+<Form onSubmit={(values) => submit(values)} error={error}>
+  <WorkflowFields workflow="digest" />
+</Form>;
+```
+
+`transcription-workflow` is the all-declared version; `link-digest` writes its
+form by hand, which is what the two are for.
 
 The usual shape — note `StartScreen` **wraps** the app rather than sitting
 beside it; writing `<StartScreen ... />` self-closing is a `TS2741:
@@ -1567,6 +1900,14 @@ Never hardcode secrets in agent code.
 - Define personality, tone, and specialty
 - Include when and how to use each tool
 
+**Three helpers for the other direction — what the caller SAID.** Speech
+arrives as words, so `@alexkroman1/aai` publishes the conversions a tool
+otherwise re-derives: `spokenDigits("four one five")` gives `"415"` for an
+order number or a phone number, `spokenOrdinal("the third one")` gives `3`, and
+`resolveOne(candidates, spoken, opts)` picks the one item a phrase meant —
+answering a `ToolFailure` the model can act on when nothing matches or several
+do, which is the case a hand-written `.find()` gets wrong.
+
 Patterns by agent type:
 
 - **Code execution:** "You MUST use run_code for ANY math, counting, or