@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/scaffold/CLAUDE.md

@@ -28,7 +28,16 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    `aai init --template <name>` scaffolds a fresh project from one. Closest
    matches: `simple`, `pipeline-simple`, `web-researcher`, `solo-rpg`,
    `pizza-ordering`, `retail` (the most complex — 15 tools over a
-   relational store, with a `syncState`-driven UI). When reading SDK
+   relational store, with a `syncState`-driven UI). Four are ports of agents you
+   may already know from LangChain/LangGraph, and each says in its own source
+   what had to change: `travel-concierge` (their customer-support bot —
+   specialist desks, and every booking staged for a spoken confirmation before
+   it applies), `support-line` (self-RAG/CRAG — retrieve, grade what came back,
+   rewrite the question, and refuse to speak an answer it cannot ground),
+   `plan-and-execute` (plan then work the plan — one step per tool call, so the
+   caller can redirect between them), and `redline` (the reflection agent — write,
+   critique, revise, which is too slow for a phone and so is a PAGE over a
+   durable run rather than a voice agent). When reading SDK
    types under
    `node_modules/@alexkroman1/aai*/dist/`, note the built entry points
    re-export with source specifiers (`"./sdk/constants.ts"`,
@@ -56,22 +65,29 @@ are CLI-only.
 
 ## Running it yourself (`npm start`)
 
-`server.mjs` serves this agent from a plain Node process — no CLI, no
-bundler, no platform account. It is the deployment counterpart of `aai dev`:
+`server.mjs` serves this agent from a plain Node process — no platform
+account, nothing managed. It is the deployment counterpart of `aai dev`:
 
 ```sh
 npm start                          # http://127.0.0.1:3000
 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.
+
 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
 wins — so `docker run -e MY_API_KEY=…` needs no `.env` in the image.
 
-Two things to know. It binds **loopback by default**, because this server has
+One thing to know: it binds **loopback by default**, because this server has
 no request authentication of its own; set `HOST=0.0.0.0` only behind your own
-proxy or auth. And with a custom `client.tsx`, run `npm run build` first —
-otherwise it serves the default UI and says so at startup.
+proxy or auth.
 
 Deleting `server.mjs` costs nothing: `aai dev`, `aai publish` and the managed
 platform never read it. `run_code` is the one feature that does not follow —
@@ -85,8 +101,9 @@ my-agent/
   agent.test.ts       # Unit tests (optional)
   client.tsx          # Custom UI (optional, React)
   shared.ts           # Types shared between agent.ts and client.tsx
-  system-prompt.md    # Long system prompts (optional, imported)
-  tools/              # Tool files when too large for inline (optional)
+  system-prompt.md    # The system prompt — discovered, not imported
+  tools/              # One file per tool — this is how a tool is declared
+  workflows/          # Durable workflow bodies (optional — see "Workflow apps")
   package.json
   tsconfig.json
   .env                # Local dev secrets (gitignored)
@@ -99,8 +116,9 @@ import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: string;                              // required — display name
-  systemPrompt?: string;                     // default: general voice assistant
-                                             // (`system` is an accepted alias)
+  systemPrompt?: string;                     // usually ABSENT — write system-prompt.md
+                                             // instead; declare it only to COMPOSE
+                                             // one (`system` is an accepted alias)
   greeting?: string;                         // default: "Hey there..."
   voice?: string;                            // TTS voice for the default pipeline, e.g. "michael"
                                              // (shorthand for tts: assemblyAITts({ voice });
@@ -111,7 +129,8 @@ export default agent({
   s2s?: S2sProvider;                         // explicit opt-in to speech-to-speech mode
   sttPrompt?: string;                        // STT guidance for jargon/acronyms
   builtinTools?: BuiltinTool[];              // see built-in tools table
-  tools?: Record<string, ToolDef>;
+                                             // (there is no `tools` field — a tool is a FILE;
+                                             //  see "A file in tools/ IS a tool")
   maxSteps?: number;                         // default: 10 — max tool calls per turn
   toolChoice?: ToolChoice;                   // "auto" (default) | "required" | "none"
                                              // | { type: "tool", toolName }
@@ -122,10 +141,8 @@ export default agent({
   interruptionMinDurationMs?: number;        // pipeline only — sustained speech (ms) before an interim barge-in interrupts (default 500; 0 disables)
   deadAirCoverMs?: number;                   // pipeline only — speak a short filler after this much silence in a turn (default 5000; 0 disables)
   resumeFalseInterruption?: boolean;         // pipeline only — resume an interrupted reply if no user turn commits (default true)
-  preemptiveGeneration?: boolean;            // pipeline only — start the reply from a high-confidence interim (default true; false opts out)
-  state?: () => S;                           // per-session mutable state, exposed as ctx.state
-                                             // (S is inferred; see "Typing ctx.state")
-  syncState?: (state: S) => unknown;         // push a projection of state to the client
+  preemptiveGeneration?: boolean;            // pipeline only — start the reply from a high-confidence interim (default false; true opts in)
+  syncState?: StateProjection;               // show a slot to the client: slot.projection(view)
                                              // (read it with useAgentState; see UI hooks)
 });
 ```
@@ -180,21 +197,347 @@ you want the three stages visible in the config or EU data residency across
 STT and the LLM gateway. Speech-to-speech (S2S) mode is an explicit opt-in
 via the `s2s` field — see below.
 
-System prompt from file:
+### `system-prompt.md` IS the system prompt
+
+**Write the prompt in `system-prompt.md` beside `agent.ts`, and declare
+nothing.** The build discovers the file, so there is no import line and no
+field — the same rule `tools/` follows, applied to the one part of an agent
+that is a DOCUMENT rather than a value:
 
 ```ts
+// agent.ts — nothing about the prompt appears here
+import { agent } from "@alexkroman1/aai";
+
+export default agent({ name: "My Agent" });
+```
+
+```markdown
+<!-- system-prompt.md -->
+You are a concise, friendly assistant.
+
+- Keep replies to one or two sentences.
+- Never read a URL aloud.
+```
+
+Why the file rather than a string: a prompt is markdown — paragraphs, headings,
+bulleted lists — and inline it becomes that document spelled as `\n\n` and `\n-`
+escapes inside one string literal, with no wrapping, no preview, and a diff that
+is one line no matter which bullet changed. Editing the prompt is the main loop
+of building an agent, so it should land in the most reviewable place available,
+not the least.
+
+Three rules, each a build error naming the file:
+
+- **A file nothing reads is an error.** If `system-prompt.md` exists and
+  `agent.ts` declares a DIFFERENT `systemPrompt`, the build fails rather than
+  ignoring the file — "I edited the prompt and nothing changed" is the failure
+  this mechanism exists to prevent.
+- **An empty file is an error**, not a silent fall-through to the framework
+  default. Delete the file if that is what you want.
+- **A `system-prompt/` directory is rejected.** One file, no concatenation
+  order to guess.
+
+**Composing a prompt is still legal, and it is the one case you write the import
+for.** When part of the prompt is computed — a menu, a catalogue, today's date —
+import the file and build the field; the build sees its own text inside your
+prompt and leaves what you built alone:
+
+```ts no-check
+// `no-check`: the prompt file and the menu module are the project's, not this
+// guide's — which is the point of the example.
 /// <reference types="vite/client" />
 import { agent } from "@alexkroman1/aai";
 import systemPrompt from "./system-prompt.md?raw";
-export default agent({ name: "My Agent", systemPrompt });
+import { menuText } from "./menu.ts";
+
+export default agent({ name: "Pizza", systemPrompt: `${systemPrompt}\n${menuText()}` });
 ```
 
+`greeting` stays a field, deliberately: it is one sentence with no structure to
+lose, and it crosses the wire to the browser beside `name` and `page`. **A
+document goes in a file, a value stays in the call.**
+
 **JSON imports need no attribute.** `resolveJsonModule` is on, so
 `import data from "./knowledge.json"` is all it takes. Do NOT write
 `assert { type: "json" }` — import assertions were replaced by import
 attributes and TypeScript rejects them (`TS2880`). If you want to be
 explicit the modern spelling is `with { type: "json" }`, but plain is fine.
 
+## Workflow apps — `workflowApp()`
+
+Not every agent's front door is a microphone. When the product is a FORM —
+submit a job, watch it run, read the result — declare it with `workflowApp()`
+instead of `agent()`:
+
+```ts no-check
+import { workflow, workflowApp } from "@alexkroman1/aai";
+import { z } from "zod";
+import { digestFlow } from "./workflows/digest.ts";
+
+export const digest = workflow({
+  description: "Summarize a link and file the digest",
+  input: z.object({ url: z.url().describe("The link to digest") }),
+  run: digestFlow,
+});
+
+export default workflowApp({
+  name: "Link Digest",
+  workflows: { digest },
+});
+```
+
+That is the whole declaration, and the fields it does NOT take are the point:
+a workflow app has no session and no LLM loop, so `systemPrompt`, `tools`,
+`maxSteps`, `syncState`, `stt`/`llm`/`tts`/`s2s` and every voice knob
+are **compile errors** here, not fields that quietly do nothing. `greeting` and
+`requiredEnv` stay. `workflowApp()` is `agent({ …, page: "static" })` with the
+discriminant already set — same definition object out, so `aai build`,
+`aai dev` and `aai publish` treat it like any other agent.
+
+Reach for it when the user asks for something that outlives a request: an
+overnight job, an upload that takes minutes, anything waiting on a third-party
+callback. Reach for `agent()` when someone is on the line — a voice agent can
+also START a workflow from a tool (`ctx.workflows.start(def, input)`) and
+answer the turn, which is the other shape.
+
+**Requires storage** (`aai storage enable`, or `DATABASE_URL` under
+`aai dev`): runs live in the database.
+
+### Workflow bodies live in `workflows/`
+
+The build transforms that directory and nothing else. A `"use workflow"` body
+written in `agent.ts` is never transformed — it runs inline once, with no
+durability and nothing saying so.
+
+```ts
+import { sleep } from "workflow";
+
+export async function digestFlow(input: { url: string }) {
+  "use workflow";
+
+  const digest = await summarize(input.url);
+  // Suspended, not blocked: the container is free to exit here and the run
+  // resumes when it comes due. `"6 hours"` works the same as `"10 seconds"`.
+  await sleep("10 seconds");
+  return { ...digest, filedAt: await file(digest) };
+}
+
+async function summarize(url: string) {
+  "use step";
+  // The whole Node runtime is available in a step: fetch, a model call, a
+  // database. Not in the body.
+  return { url, headline: `What ${new URL(url).hostname} says`, points: [] };
+}
+
+async function file(digest: { url: string }) {
+  "use step";
+  return new Date().toISOString();
+}
+```
+
+Three rules, all of which fail silently if broken:
+
+- **The body replays from the top on every resume**, so it holds no live handle
+  and makes no undurable decision — no `Date.now()`, no `Math.random()`, no
+  `fetch`. Those belong in a step, whose result is journaled and returned
+  unchanged on replay.
+- **A step's arguments and return value cross a queue**, so they must be
+  JSON-shaped and small. Put bytes in storage and pass the key.
+- **A step gets no tool context.** It is bundled and dispatched separately from
+  the agent, so there is no `ctx` in one — see below for how it reaches the
+  agent's env and a model anyway. `ctx.db` has no step-side equivalent yet.
+
+### A step's env, and calling a model from one
+
+A step has no `ctx`, so the two things tool code takes for granted come from
+`@alexkroman1/aai/utils` instead. Import them from THERE and not from
+`@alexkroman1/aai` — a `workflows/*.ts` module is bundled separately, and the
+root barrel would drag the whole SDK into that bundle.
+
+```ts no-check
+import { requireStepEnv, stepEnv, StepGenerateError, stepGenerate } from "@alexkroman1/aai/utils";
+import { FatalError } from "workflow";
+
+async function summarize(url: string, text: string) {
+  "use step";
+
+  // The agent's env by name — the same values a tool reads from `ctx.env`.
+  // `requireStepEnv` fails naming the key; `stepEnv` returns undefined.
+  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}`, {
+    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;
+}
+```
+
+Two things to know. **The env is what `.env` and `aai secret put` declare** —
+not your shell, even under `aai dev`, so that a step reads the same values
+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.
+
+### A step's HTTP: use `stepFetch`, not `fetch`
+
+Any outbound request from a step goes through `stepFetch` (also
+`@alexkroman1/aai/utils`). It is not a style preference — `fetch` is the wrong
+call to make from a step, for a reason nothing at the call site shows:
+
+```ts no-check
+import { multipartBody, stepFetch, StepTransportError } from "@alexkroman1/aai/utils";
+
+async function transcribeChunk(key: string, bytes: Uint8Array, index: number) {
+  "use step";
+
+  // Multipart as BYTES. Never a `FormData` — see below.
+  const part = multipartBody({
+    name: "audio",
+    filename: `chunk-${index}.wav`,
+    type: "audio/wav",
+    bytes,
+  });
+
+  const response = await stepFetch("https://sync.assemblyai.com/transcribe", {
+    method: "POST",
+    headers: { Authorization: key, ...part.headers },
+    body: part.body,
+    // Nothing here has a deadline of its own, and a hung request inside a step
+    // is a run that never finishes rather than one that retries.
+    signal: AbortSignal.timeout(60_000),
+  });
+  if (!response.ok) throw stepFailure(response);
+  return await response.json();
+}
+```
+
+**`fetch` speaks HTTP/2, and a fan-out is the worst case for that.** Node's
+global `fetch` offers `h2` in ALPN and the far side decides; a server that takes
+it gets every concurrent request from your process multiplexed onto ONE TCP
+connection, sharing one flow-control window. That is fine for small JSON calls
+and pathological for `mapInBatches` over large bodies. Measured on 8 concurrent
+17.66 MB uploads: `fetch` landed 14 of 16 at p50 8094ms, HTTP/1.1 landed 16 of
+16 at p50 3037ms.
+
+**And the two it lost are the reason this matters more than the latency.** On
+HTTP/2 a capacity limit arrives as a *stream reset* — `NGHTTP2_ENHANCE_YOUR_CALM`
+— and a stream error carries no HTTP status, so `isTransientStatus` and
+`retryAfter` cannot see it. Every sibling in the batch then retries in lockstep
+into the same reset, exhausts `maxRetries`, and fails the run with
+`TypeError: fetch failed`, whose real cause is two `cause` hops down where
+nothing prints it. Over HTTP/1.1 the identical limit arrives as `503` with
+`retry-after`, which your retry policy already reads.
+
+Three rules come with it:
+
+- **Bodies are BYTES or a string.** Never hand a `FormData`, `Blob`, `File`,
+  `Headers` or `Request` to a step's fetch: those are branded objects, checked
+  against the classes of whichever undici the fetch came from, and a foreign one
+  is silently stringified — `Content-Type: text/plain` with the 17-byte body
+  `[object FormData]`, answered `415`. `multipartBody()` is how a file becomes
+  bytes.
+- **A connection failure is a `StepTransportError`**, distinct from a response
+  with a bad status because only the first is unclassifiable. It names its whole
+  `cause` chain, and `err.codes` is what to branch on (`ECONNRESET`,
+  `ETIMEDOUT`, …).
+- **Test it with `stubStepFetch`** (`@alexkroman1/aai/testing`), not
+  `vi.stubGlobal("fetch", …)`. The global stub passes — an unpublished slot falls
+  back to it — while asserting a path production does not take, and it cannot see
+  the request body as bytes.
+
+`stepGenerate` already goes through this, so a step that only calls a model gets
+it for free.
+
+### A builtin's failure is its RESULT, so narrow it
+
+`webSearch`, `visitWebpage` and `fetchJson` (`@alexkroman1/aai/tools`) answer
+`T | ToolFailure` — they do not throw on an HTTP failure, a bot challenge or an
+oversized body, because a tool usually wants to hand the model something useful
+rather than fail the turn:
+
+```ts no-check
+import { webSearch } from "@alexkroman1/aai/tools";
+import { isToolFailure } from "@alexkroman1/aai/utils";
+
+const found = await webSearch<{ results?: { url?: string }[] }>({ query, max_results: 4 });
+// NOT `(found.results ?? [])` — a REFUSED search would then read as an empty web.
+if (isToolFailure(found)) return `That search failed: ${found.error}`;
+return (found.results ?? []).map((one) => one.url);
+```
+
+**`?? []` is the mistake, and it is a quiet one.** Both shipped templates that
+search wrote it, and one of them had a `catch` for this exact failure — which
+never ran, because a `catch` cannot see a returned value. DuckDuckGo refuses
+often enough that the empty answer is routine, and to the model "no results" and
+"the search was blocked" are different facts: told the first, it concludes the
+pages do not exist and tries again with different words until its budget is gone.
+
+An UNTYPED call (`await fetchJson(url)`) stays loose and needs no narrowing —
+naming a shape is what asks the compiler to make you handle the failure.
+
+### The page
+
+A workflow app's `client.tsx` mounts with `page()` rather than `client()` —
+there is no session to build, so no socket, no audio graph and no microphone
+request. Everything else is the same file, React and Tailwind included.
+
+```tsx no-check
+import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+import "@alexkroman1/aai-ui/styles.css";
+import type { WorkflowOutputOf } from "@alexkroman1/aai";
+import { useState } from "react";
+import type { digest } from "./agent.ts";
+
+// Hoisted: a client built in render is a new object every render.
+const api = createWorkflowApi();
+
+export function App() {
+  const [runId, setRunId] = useState<string>();
+  // The generic is what makes `run.output` typed rather than `unknown`.
+  const { run, polling } = useWorkflowRun<WorkflowOutputOf<typeof digest>>(runId, { api });
+
+  return (
+    <main>
+      <button
+        type="button"
+        onClick={async () => setRunId(await api.start("digest", { url: "https://example.com" }))}
+      >
+        Digest
+      </button>
+      {polling && <p>Working. You can close this tab — the run continues.</p>}
+      {run?.status === "completed" && <h2>{run.output.headline}</h2>}
+    </main>
+  );
+}
+
+page({ name: "Link Digest", component: App });
+```
+
+`api.start()` resolves as soon as the RUN EXISTS, not when it finishes — that
+is the whole mechanism. The `runId` is the entire client state, so it survives
+a reload, a different device, or `curl`. Note the workflow is named by the key
+it has in `workflows` above (`"digest"`); nothing else records that string, so
+a rename there is a 400 here rather than a compile error.
+
+The same routes are scriptable, which is the other half of having an API:
+
+```text
+GET    /workflows                 → the declared workflows, with input schemas
+POST   /workflows/runs            → { runId }   body: { workflow, input?, key?, wait? }
+GET    /workflows/runs/:id        → a run snapshot
+DELETE /workflows/runs/:id        → cancel
+GET    /workflows/runs/:id/events → SSE
+```
+
 ## Pipeline mode
 
 Pipeline mode is the default: omitting `stt`/`llm`/`tts` (and `s2s`) gives
@@ -299,7 +642,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
-2000 ms) / `deepgram({ endpointing })` (default 1500 ms), so mid-utterance
+1600 ms) / `deepgram({ 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
@@ -311,16 +654,20 @@ caller answers it and the answer barges in.
 a barge-in turns out to be noise — no user turn ever commits. The wait is not
 configurable: the resume fires once the transcript stream goes quiet with no
 final, so it can never race a real turn the STT is still endpointing.
-`preemptiveGeneration` (default `true`) starts generating the reply as soon
-as transcription is confident the caller has finished, and uses that
+`preemptiveGeneration` (default **`false`**) starts generating the reply as
+soon as transcription is confident the caller has finished, and uses that
 already-running answer if the committed transcript matches. It can shorten the
-pause before the agent speaks, and **how much is unmeasured** — nobody has
-shown the size of the saving. What bounds the downside is that a speculation
-never speaks, calls a tool, or enters history until the real turn adopts it, so
-the worst case is a wasted request and a turn that behaves exactly as it would
-with the flag off. Set `preemptiveGeneration: false` to opt out — worth doing
-on a tool-heavy agent, where a speculation that reaches a tool call is thrown
-away, so it is cost with no upside.
+pause before the agent speaks, and it is off by default because the measurement
+came back negative: over a tau2-bench retail run, 16 speculations started, 14
+were adopted at a p50 head start of 0.44s, and 5 of those 14 (36%) were poisoned
+after adoption by a tool call — discarded whole, each having burned p50 0.69s
+first. Net **+8ms per caller turn**, for 44% of its LLM requests thrown away.
+What bounds the downside either way is that a speculation never speaks, calls a
+tool, or enters history until the real turn adopts it, so the worst case is a
+wasted request and a turn that behaves exactly as it would with the flag off.
+Set `preemptiveGeneration: true` to opt in — worth trying on a text-heavy agent,
+since 36% poisoned is a tool-calling agent's number, and pointless on a
+tool-heavy one, where a speculation that reaches a tool call is thrown away.
 
 ## Providers
 
@@ -465,7 +812,8 @@ same way in `aai dev` and deployed.
 
 ```ts no-check
 ctx.env: Readonly<Record<string, string>>     // secrets from .env / aai secret put
-ctx.state: S                                   // per-session mutable state (agent's `state` factory)
+ctx.slots: SlotStore                           // where sessionSlot() keeps this session's state —
+                                               // reach for the slot, never this (see "Session state")
 ctx.db: Db                                     // SQL database, needs storage enabled (see Database section)
 ctx.messages: readonly Message[]               // conversation history [{role, content}]
 ctx.sessionId: string                          // unique session ID
@@ -495,17 +843,9 @@ export const lookup = tool({
 });
 ```
 
-**Typing `ctx.state` is optional.** `ctx.state` is untyped by default, and
-the project's tsconfig turns off `noImplicitAny`, so both of these compile
-with no annotations and no errors:
-
-```ts no-check
-ctx.state.count++;
-ctx.state.incidents.filter((i) => i.status === "open");
-```
-
-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.
+**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.
 
 **The one exception, and it is not optional: annotate any variable you
 declare empty.** With `noImplicitAny` off, TypeScript does not widen an empty
@@ -527,35 +867,74 @@ 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.
 
-Declaring a state type is still worth it once the shape is settled, because
-it turns a misspelled field into a compile error instead of `undefined` at
-runtime:
+### Session state
 
-```ts
-import { agent, tool } from "@alexkroman1/aai";
-import type { ToolContext } from "@alexkroman1/aai"; // types need `import type`
-import { z } from "zod";
+**A `sessionSlot` is the only way to keep state across a session's tool calls**,
+and it is one declaration in a shared module:
+
+```ts no-check
+// shared.ts — the one place the shape is written down.
+import { sessionSlot } from "@alexkroman1/aai";
+
+export type Incident = { id: string; status: "open" | "closed" };
 
-type Incident = { id: string; status: "open" | "closed" };
-type State = { incidents: Incident[] };
+export const incidentSlot = sessionSlot("incidents", () => ({ items: [] as Incident[] }));
+```
+
+```ts no-check
+// tools/list_open.ts — `slot.tool` READS: the body is handed the value, typed.
+import { incidentSlot } from "../shared.ts";
 
-const listOpen = tool({
+export default incidentSlot.tool({
   description: "List open incidents",
-  execute: (_args, ctx: ToolContext<State>) => {
-    // `i` infers as Incident, and `i.staus` would now be an error.
-    return ctx.state.incidents.filter((i) => i.status === "open");
-  },
+  // `i` infers as Incident, and `i.staus` would now be an error.
+  execute: (_args, incidents) => incidents.items.filter((i) => i.status === "open"),
 });
+```
 
-export default agent({
-  name: "Dispatch",
-  state: (): State => ({ incidents: [] }),
-  tools: { listOpen },
+```ts no-check
+// tools/open_incident.ts — `slot.updateTool` WRITES: mutate what you are handed.
+import { incidentSlot } from "../shared.ts";
+import { z } from "zod";
+
+export default incidentSlot.updateTool({
+  description: "Open an incident",
+  inputSchema: z.object({ id: z.string() }),
+  execute: ({ id }, incidents) => {
+    incidents.items.push({ id, status: "open" });
+    return { open: incidents.items.length };
+  },
 });
 ```
 
-A tool annotated with a state shape the agent's factory doesn't produce is a
-compile error, which is the point.
+Four rules, and each is an error rather than advice if you get it wrong:
+
+- **`tool` reads, `updateTool` writes.** What a read is handed is FROZEN, so
+  mutating it throws instead of quietly going nowhere.
+- **A write is SYNCHRONOUS.** The value you mutate is stored the moment your body
+  returns, so an `updateTool` body may not `await`. When you need a model call or
+  a fetch first, do it in an ordinary `tool()` and then mutate:
+
+  ```ts no-check
+  execute: async (args, ctx) => {
+    const priced = await ctx.generate({ prompt: `price ${args.sku}` });
+    return cartSlot.update(ctx, (cart) => {
+      cart.total = Number(priced.text);
+      return { total: cart.total };
+    });
+  }
+  ```
+
+- **Hold plain data.** Objects, arrays, strings, numbers, booleans and null. A
+  `Map`, a `Set`, a `Date` or a class instance is refused with the field named,
+  because none of them survives being stored.
+- **State is STORED when your app has a database** (`aai storage enable`, or a
+  `DATABASE_URL` in `.env`), so a crash or a redeploy no longer loses it. Without
+  one it lives in memory for the life of the process. You write the same code
+  either way; that is the reason for the rules above.
+
+There is nothing to declare on `agent()` — the slot owns its own default. Use
+`syncState: slot.projection(view)` to show state to a custom client.
 
 **`verbatimModuleSyntax` applies to every type you import** — `ToolContext`,
 `ToolDef`, `Message`, provider types. A plain
@@ -570,31 +949,30 @@ 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.
 
-### Inline tool example
+### A tool that calls an API
 
 ```ts
-import { agent, tool } from "@alexkroman1/aai";
+// tools/get_weather.ts  →  the model calls this "get_weather"
+import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 
-export default agent({
-  name: "Weather Agent",
-  tools: {
-    get_weather: tool({
-      description: "Get current weather for a city",
-      inputSchema: z.object({
-        city: z.string().describe("City name"),
-      }),
-      async execute({ city }, ctx) {
-        const resp = await fetch(
-          `https://api.example.com/weather?q=${city}&key=${ctx.env.WEATHER_KEY}`,
-        );
-        return resp.json();
-      },
-    }),
+export default tool({
+  description: "Get current weather for a city",
+  inputSchema: z.object({
+    city: z.string().describe("City name"),
+  }),
+  async execute({ city }, ctx) {
+    const resp = await fetch(
+      `https://api.example.com/weather?q=${city}&key=${ctx.env.WEATHER_KEY}`,
+    );
+    return resp.json();
   },
 });
 ```
 
+Nothing else. `agent.ts` does not import it, does not list it, and takes no
+`tools` field at all — see "A file in `tools/` IS a tool" below.
+
 **Calling the network builtins from your own tool code.** `web_search`,
 `visit_webpage` and `fetch_json` are declared to the MODEL — the LLM calls
 them, and they are not on `ctx`. When your own `execute` needs one, import
@@ -650,16 +1028,18 @@ the tool also returns an error, because `Promise<DrugInfo>` does not accept
 `{ error: "not found" }`. Every such annotation eventually costs a build
 round to widen into a union. Let it infer.
 
-### Separate file pattern
+### A file in `tools/` IS a tool — there is no registration step
 
-For complex tools — `tools/` is a convention, any import path works:
+**`tools/` is not a convention, it is the mechanism.** A file there is named for
+the tool the model calls, default-exports it, and is picked up by the build. It
+is not imported by `agent.ts` and not listed anywhere:
 
 ```ts
-// tools/roll_dice.ts
+// tools/roll_dice.ts  →  the model calls this "roll_dice"
 import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 
-export const rollDice = tool({
+export default tool({
   description: "Roll dice",
   inputSchema: z.object({ sides: z.number() }),
   execute({ sides }) {
@@ -669,16 +1049,42 @@ export const rollDice = tool({
 ```
 
 ```ts no-check
-// agent.ts
+// agent.ts — nothing about tools appears here
 import { agent } from "@alexkroman1/aai";
-import { rollDice } from "./tools/roll_dice.ts";
 
-export default agent({
-  name: "Dice Agent",
-  tools: { roll_dice: rollDice },
-});
+export default agent({ name: "Dice Agent" });
+```
+
+Three rules come with it, each a build error naming the file:
+
+- **The file name is the tool name**, so it must be lowercase, start with a
+  letter, and join words with `_` — `tools/incident_create.ts`, never
+  `incident-create.ts`. Renaming the file renames the tool.
+- **The export is the DEFAULT export**, and it must be a `tool()` (or a
+  `slot.tool()` / `slot.updateTool()`). A file exporting something else is
+  named at build time rather than becoming a tool that fails per turn.
+- **`tools/` is flat.** A nested file is rejected, because a provider will not
+  accept a tool name with a `/` in it and inventing a flattening rule would
+  freeze a guess. This applies to a nested HELPER too, not just a nested tool —
+  the build cannot tell them apart, so put shared helpers beside `agent.ts`
+  rather than under `tools/`. The error names the file and both ways out.
+
+A tool that closes over module-local state, or one built by your own wrapper,
+still gets its own file — the file names the instance and the factory lives
+beside it:
+
+```ts no-check
+// tools/to_hotel_assistant.ts
+import { delegationTool } from "../routing.ts";
+
+export default delegationTool("hotel");
 ```
 
+Why discovery rather than a map: the map was 62 lines across the shipped
+templates whose entire content was `snake_case_name: camelCaseImport`, and
+forgetting one line was **silent** — the file compiled, every check passed, and
+the tool simply never reached the model.
+
 ## Built-in tools
 
 Enable via `builtinTools` in `agent()`. **When `builtinTools` is omitted, none
@@ -770,7 +1176,7 @@ const rows = await ctx.db.query<{ value: { name: string } }>(
 
 Use `ctx.db` for data that must outlive the session (saves, filed records,
 user profiles). For scratch that only the current session needs, prefer
-`ctx.state` (per-session mutable state — no storage required); the
+a `sessionSlot` (per-session state, stored when the app has a database); the
 `remember`/`recall` builtins likewise remain for session-scoped notes the
 LLM manages itself.
 
@@ -907,11 +1313,12 @@ also what you want for anything that can be a string, an array, or null.
 **`useAgentState`** — the agent's session state, pushed automatically:
 
 ```ts no-check
+// shared.ts — the slot owns the shape; `agent()` has no `state` field.
+export const cartSlot = sessionSlot("cart", () => ({ cart: [] as Item[], staffPin: "" }));
+
 // agent.ts
 export default agent({
-  state: () => ({ cart: [] as Item[], staffPin: "" }),
-  syncState: (s) => ({ cart: s.cart }),   // staffPin never leaves the server
-  tools: { ... },
+  syncState: cartSlot.projection((s) => ({ cart: s.cart })),  // staffPin stays server-side
 });
 
 // client.tsx
@@ -1085,7 +1492,7 @@ Common mistakes when working in aai projects:
   preview redeploys itself, production on the next publish.
 - **The database is per-app.** Rows are shared by every session of one
   deployment — key them yourself if sessions must not see each other's data
-  (or keep session-scoped data in `ctx.state`).
+  (or keep session-scoped data in a `sessionSlot`).
 - **Rime language codes are ISO 639-3** (3-letter, e.g. `"eng"`), not
   ISO 639-1 (`"en"`).