@falai/agent 3.4.4 → 4.0.0-alpha.1

package/docs/concepts/architecture.md

@@ -1,274 +1,152 @@
 ---
-title: "Architecture"
-description: "The six primitives of @falai/agent and how they fit together to keep language on the AI's side and decisions on the code's side."
+title: "Agent architecture"
+description: "The seven words the rest of the docs use, and the line between what the model decides and what the code decides."
 type: concept
 order: 1
 ---
 
-# Architecture
-
-> the AI understands, the code is in control
-
-Six types do all the work. Five are about declaration — what the agent looks like in source. One is about control — what tools and hooks return at runtime to redirect a turn. This page maps the ownership and reference relationships between them, explains the schema-first principle that makes pre-extraction work, and draws the line between what the AI does and what the code does.
-
-LLMs are good at language and unreliable at control flow. They paraphrase well; they do not maintain invariants. They infer intent well; they do not enforce completion gates. The framework's job is to keep the AI on the side of language — understanding intent, extracting structured data, generating prose — while keeping the code on the side of decisions: which flow runs, when a flow completes, what a tool actually does, what state survives a turn.
-
-This page explains the shape of that seam. It names the six primitives, says what each one is for, and shows how they reference each other. It does not teach syntax. Once the mental model is in place, the [reference](../reference/create-agent.md) pages document the contracts and the [tutorial](../start/01-install.md) walks through the code line by line.
-
-## Core vocabulary
-
-Eight terms cover everything below. Every other term in the docs defines itself at first use — there is no separate glossary.
-
-| Term | What it means here |
-|------|--------------------|
-| **Agent** | The top-level object. Owns the schema, provider, flows, tools, signals, and persistence. |
-| **Flow** | A single conversational goal — an ordered sequence of steps with shared completion semantics. |
-| **Step** | One node inside a flow. Asks a question, collects fields, calls tools, runs hooks, or speaks a verbatim line. |
-| **Tool** | A typed function the AI can call. May redirect the conversation by emitting a directive. |
-| **Instruction** | A behavioral statement (`must` / `never` / `should`) that shapes how the agent talks at a given scope. |
-| **Directive** | A flat object any tool, hook, or branch returns to write state, change position, or speak verbatim. |
-| **Schema** | The single source of truth for `TData` — what the agent collects across the whole conversation. |
-| **Context** | Ambient app data of type `TContext` — user, env, services. Independent of `TData`. |
-
-These are the words the rest of the docs use without footnotes. They are also the words the type system uses — every name in the table maps directly to an exported symbol or a generic parameter.
-
-## The six primitives
-
-Six types do all the work. The first five are about declaration — what the agent looks like in source. The last one is about control — what tools and hooks return at runtime to act on a turn. None of them is novel on its own. The shape of the framework is in how few there are and how cleanly they compose.
-
-A small illustrative sketch first, just to show the silhouette:
-
-```typescript
-const agent = createAgent({
-  name: "BookingBot",
-  schema: { /* TData shape */ },
-  provider: new GeminiProvider({ apiKey }),
-  instructions: [
-    { kind: "must", prompt: "Confirm dates before booking." },
-  ],
-  tools: [
-    { id: "book_hotel", handler: async (ctx) => { /* ... */ } },
-  ],
-  flows: [
-    {
-      title: "Booking",
-      requiredFields: ["city", "checkIn"],
-      steps: [
-        { id: "ask",     prompt: "Collect city and date.", collect: ["city", "checkIn"] },
-        { id: "confirm", prompt: "Confirm and call book_hotel.", requires: ["city", "checkIn"] },
-      ],
-    },
-  ],
-});
+# Agent architecture
+
+The AI understands. The code is in control.
+
+@falai/agent runs a conversation as a set of small programs called flows. The model has two jobs: read what the customer wrote, and phrase what the assistant says. Every other decision is code: which flow runs, which step comes next, which field is still missing, how long to wait, what to send and when.
+
+## The words
+
+These seven words are the whole design. The rest of the docs use them without explaining them again.
+
+| Word | What it is | Where it lives |
+|---|---|---|
+| **Agent** | The configuration: fields, flows, provider, registries. One instance serves every session. | `f.agent(options)` returns an `Agent` |
+| **Flow** | A trigger plus an ordered list of steps. | `Flow`, built with `f.flow()` |
+| **Trigger** | When a run of the flow starts: `message`, `mention`, `silence`, `event`, or none (the host starts it). | `Trigger`, in `flow.on[]` |
+| **Step** | One thing the run does: the model talks (`prompt` / `collect`), a fixed text goes out (`say`), the host does something (`do`), the run parks (`wait`), the code forks (`if`). | `Step`, in `flow.steps[]` |
+| **Field** | One piece of data to collect, authored once on the agent with its own `ask`. | `FieldDef`, in `falai().fields()` |
+| **Run** | One live execution of a flow inside a session. A session holds many runs; at most one is asking. That run holds the floor: the next message is read as its answer. | `Run`, in `session.runs[]` |
+| **Turn** | One call to `agent.turn(input)`: something happened, here is what to send and when to wake up. | `TurnInput` in, `TurnResult` out |
+
+Four registries live on the agent. Instructions are written inline, wherever they apply. Flows name registry entries as strings, and the names are checked when the agent is built.
+
+| On the agent | What it holds | Named from |
+|---|---|---|
+| `actions` | Host code a `do` step runs. Returns `{ ok }`, `{ skipped }`, `{ failed }` or `{ defer }`. | `do: 'notify'` |
+| `events` | Host events a trigger or a `wait` may name, each with an optional `direction`. | `on: [{ event: 'stage_entered' }]`, `wait: { event: 'meeting_booked' }` |
+| `conditions` | Host predicates a JSON `if` may name, with an argument. | `if: { tagsAny: ['vip'] }` |
+| `tools` | Typed functions the model may call while it speaks. They return `{ value?, data? }`, never movement. | `tools: ['checkAvailability']` on a step or a flow |
+| `instructions` | Rules the prompt carries while they apply: `must`, `never`, `should`. | Not named: written inline where they apply, on the agent, a flow, a step, or the idle speaker |
+
+The **host** is your program: the one that receives a message from the channel, loads the session, calls `turn()`, saves, sends and schedules. The framework does none of those.
+
+## How they fit
+
+```text
+Agent (immutable, one instance for every session)
+├── fields        nome, empresa, confirmado, …        authored once, typed
+├── flows[]       Flow = on[] (triggers) + steps[]
+│                   step: talk | say | do | wait | if
+│                   movement: then / else → step id | 'end' | { step, clear } | { flow, input }
+├── actions       do: 'notify'              ┐
+├── events        event: 'meeting_booked'   │  host registries,
+├── conditions    if: { inStage: 'x' }      │  referenced by name
+├── tools         the model may call these  ┘
+├── instructions  must / never / should
+├── idle          speaks when no run holds the floor ('silent' mutes it)
+└── provider      talks to the model
+
+Session (one per conversation; the host saves it)
+├── data          the collected fields, in any order
+├── runs[]        live runs: running | asking | waiting | suspended
+├── claims        which flows already ran here, so repeat: 'once' and cooldowns hold
+└── inputs        the last 50 input ids, for replays
+
+turn(input) ── message | wake | event | start ──▶ TurnResult
+                                                  session, changed, messages[], schedule[], llmCalls, …
 ```
 
-Five of the six primitives appear by name in that block. The remaining one — `Directive` — surfaces only when control flow is on the line, returned from a tool or hook to redirect the conversation.
-
-### Agent
-
-An `Agent<TContext, TData>` is the top-level handle. It binds the four ingredients of a conversational system: a **schema** (what to collect), a **provider** (which LLM to call), a set of **flows** (what goals to pursue), and an optional **persistence** adapter (where to keep sessions). Anything ambient — auth, feature flags, services — rides on `TContext`. Anything collected — names, dates, choices — lives in `TData`. Both type parameters are inferred once at the agent boundary and propagate through every flow, step, tool, and hook beneath it.
-
-The agent owns the registry. It assigns a deterministic id to every flow, step, and tool; it enforces a single `schema` at every `collect` site; it holds the chosen provider and the session lifecycle. It exposes `respond(params)` and `respondStream(params)` for handling user input, plus `dispatch(target, session)` for redirecting from outside a turn. One agent serves many concurrent conversations — a session id keys into the persistence adapter, and `respond` is otherwise stateless from the caller's perspective.
-
-### Flow
+## The two model calls
 
-A `Flow<TContext, TData>` is one conversational goal — booking a hotel, escalating a complaint, onboarding a teammate. Each flow declares a `title`, a list of `steps`, optional `requiredFields` that gate completion, and conditions for activation: `when` for AI-evaluated strings, `if` for code predicates. The flow router selects exactly one flow per turn, so a flow is also the unit of attention — at any moment, the agent is either inside one flow or sitting idle between flows.
+The model gets at most two calls per turn, and each has one job.
 
-A flow owns its steps in declaration order, its scoped instructions and tools, and its completion semantics. The top-level `onComplete: string` is sugar for chaining into another flow on completion; for dynamic logic, `hooks.onComplete` returns a `Directive`. The optional `reentrant` flag opts the flow into "do another?" loops — on re-entry, the engine clears every field declared in `requiredFields` and `optionalFields` so the flow starts fresh. A flow does not own session data — `TData` lives at the agent — but it does declare which fields it needs to be considered done.
+- **The understand call** reads the customer's message. It scores the candidate flows from 0 to 100, says which things the customer brought up, answers the `when` questions of the asking step, and extracts any field values the message carries. It never moves a run.
+- **The speak call** phrases the assistant's reply for one talk step (or for the idle speaker) and extracts the fields that step is still collecting. It may call tools in rounds. It never moves a run either.
 
-### Step
+Everything else is code, in `src/core/Runner.ts`: which flows are eligible, which run holds the floor, which fields are pending, which step comes next, how long a wait is, what key a message gets, when a claim (a record that this flow already ran) blocks a start, what the result says. Code behaves the same on a replay; the model does not. So nothing the model says is applied before code checks it: unknown fields are dropped, values are coerced to the field's type, `enum` membership is enforced.
 
-A `Step<TContext, TData>` is a single node inside a flow. Each step describes one moment in the conversation: ask a question, collect a few schema fields, call a tool, branch to another step, or speak a verbatim line. Steps are the smallest unit the engine can suspend on between user turns — when a step finishes, the engine checks for a directive, then for branches, then falls through to the linear successor. Steps are also the unit at which scoped tools and instructions attach, so a step can shadow an agent-level setting locally without modifying the agent.
+Two things follow. A flow with no talk steps costs zero model calls. And every result carries `llmCalls`, so a test asserts the budget instead of trusting it. [The turn pipeline](./pipeline.md) walks the eight phases and what each one spends.
 
-A step comes in three mutually exclusive shapes. An **LLM step** has a `prompt` and the engine calls the model. An **auto step** sets `auto: true` — pure computation, no LLM call, only `onEnter`, `prepare`, and `branches` execute. A **reply step** sets `reply` — the engine renders the template and emits it verbatim, skipping the model entirely. Beyond shape, a step owns its `collect` set (which schema fields it extracts), its `requires` list (prerequisites that must be present before entry), its scoped tools and instructions, its `branches` for explicit forks, and the four lifecycle positions: `onEnter`, `prepare`, `finalize`, `onExit`. The combination of three shapes and four lifecycle positions is what lets a step be either a conversational moment or a pure pipeline node, with no third category in between.
+## One agent, every session
 
-### Tool
+An `Agent` is immutable configuration. Build it once and keep it for the life of the process. It holds no session, no context and no history of its own; those arrive on every `turn()`.
 
-A `Tool<TContext, TData, TResult>` is a function the AI can call during a turn. Every tool is a single interface — `id` is the sole identifier, every metadata field is optional, and the handler receives a `ToolContext` (a typed view of `data`, `context`, `history`, plus `dispatch` for mid-handler redirection). A tool can return a plain value, a `ToolResult` with state writes, or a `ToolResult` with an embedded `directive` that redirects the conversation when the result is delivered.
+```ts
+import type { Agent } from "@falai/agent";
+declare const agent: Agent;
 
-A tool owns its parameters schema (what arguments the LLM may pass), its handler (what actually runs), and the optional safety metadata that lets the executor reason about it: `isReadOnly`, `isConcurrencySafe`, `isDestructive`, `validateInput`, `checkPermissions`, `maxResultSizeChars`. Tools are scoped — defined on the agent (always available), on a flow (available only while that flow is active), or on a step (available only while that step is current). Resolution stacks scope-on-scope so a step can shadow an agent-level tool by id without removing it from the registry.
-
-### Instruction
-
-An `Instruction<TContext, TData>` is a single behavioral statement that shapes how the agent talks. Every instruction carries a `kind` discriminator — `must` for absolute do, `never` for absolute don't, `should` for conditional nudge — alongside a `prompt` (the rendered text) and optional activation conditions (`when` for AI strings, `if` for code predicates). One shape covers every behavioral nudge in the system; the only thing that differs from one instruction to the next is its severity and its scope.
-
-An instruction owns its rendered position in the prompt. The composer renders each active instruction as a single bullet under the system prompt's `## Instructions` section, prefixed with its kind and a scope caption: `[Always]` for agent-level, `[In: <FlowTitle>]` for flow-level, `[Step: <stepId>]` for step-level. The set actually rendered on a turn is reported back as `appliedInstructions` on the response — observability is deterministic, derived from rendering, not self-reported by the model.
-
-### Directive
-
-A `Directive<TContext, TData>` is a flat object literal — not a class, not a builder, not a discriminated union — that any tool, hook, or branch returns to act on the turn. Every field is optional. A directive carries up to four orthogonal payloads: at most **one position field** (`goTo`, `goToStep`, `complete`, `abort`, or `reset`), zero or one **verbatim reply**, optional **state writes** (`dataUpdate` / `contextUpdate`), and optional **pre-LLM augmentation** (`appendPrompt`, `injectTools`, `halt`) plus optional `reason` strings inside object forms for traceability. The flatness is intentional — earlier drafts modeled directives as a discriminated union, but a flat object composes more naturally when a single decision point needs to write state, change position, and speak verbatim in one return value.
-
-The directive is the single language the framework speaks for control flow. A tool that decides "this user is ineligible" returns `{ goTo: "denial", reply: "Sorry — you don't qualify." }`. A finalize hook that finishes a booking returns `{ complete: true, dataUpdate: { bookingId } }`. A prepare hook that detects a VIP returns `{ appendPrompt: ["This caller is VIP — confirm preferences first."] }`. All of these merge through one algorithm — position fields by precedence, state writes shallow-merged, `reply` last-wins — implemented as `flow.merge(a, b)` and applied uniformly across the turn pipeline.
-
-The three pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) have a one-turn lifetime: they only take effect in pre-LLM hooks (`onEnter`, `prepare`). When emitted from post-LLM hooks or persisted to `session.pendingDirective`, they are ignored with a WARN log. This keeps one type for all emitters while the engine enforces the phase boundary at runtime.
-
-## Supporting concepts
-
-The six primitives carry the weight. Four supporting pieces make them ergonomic.
-
-### `flow` namespace
-
-`flow` is a small runtime helper namespace exported from the package root. There are no constructor builders here — directives are object literals everywhere they appear in source. The namespace exists for runtime work: validating a directive that arrived from outside the framework (an RPC payload, a queue message), merging two directives by hand when composing custom orchestration, or narrowing an `unknown` value to `Directive` in a type guard.
-
-```typescript
-import { flow } from "@falai/agent";
-
-flow.isDirective(x);   // type guard
-flow.merge(a, b);      // Algorithm 4 merge of two directives
-flow.validate(d);      // throws FlowConfigurationError on invalid shape
+const r = await agent.turn({ sessionId: "demo", message: "oi" });
+console.log(r.llmCalls); // 1: one flow, nothing to judge, one speak call
 ```
 
-`flow.merge` is the same algorithm the engine runs internally on the per-turn directive bus, exposed for callers that need to compose results before dispatching them. `flow.validate` enforces three invariants — at most one position field, no empty `goTo: {}`, no `reply` alongside `abort` — and throws a typed error otherwise. The pipeline calls it eagerly on every emitted directive, so downstream code can rely on shape.
+Here is the agent that call ran against:
 
-### `createAgent`
+```ts
+import { falai } from "@falai/agent";
+import type { AiProvider } from "@falai/agent";
 
-`createAgent(options)` is the level-1 entry point for constructing an agent. It is sugar over `new Agent(options)` and accepts the same `AgentOptions` shape, but reads more naturally for the common case: one options object, generic inference flowing from `schema` through every `flows[].steps[].collect` reference. The type of `session.data` and tool-handler arguments is derived once at the call site and propagates everywhere.
+declare const provider: AiProvider;
 
-```typescript
-const agent = createAgent({
-  name: "BookingBot",
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: { /* ... */ },
-  flows: [/* ... */],
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome da pessoa, sem tom de formulário." },
 });
-```
-
-The factory is the recommended construction path for application code. The class form (`new Agent(options)`) remains for power users who need to subclass — for example, to override `respond` for custom telemetry, or to add bespoke methods on top of the agent surface. Both share validation: misuse surfaces as `FlowConfigurationError` synchronously at construction, before any turn runs.
-
-### `Agent.dispatch`
-
-`agent.dispatch(target, session)` is the imperative entry point for redirecting a session from outside a turn — typically from a webhook, a cron job, or a UI button that jumps the user into a different flow. It accepts either a string shorthand (`"Feedback"` desugars to `{ goTo: "Feedback" }`) or a full `Directive`. Internally, it writes `session.pendingDirective`; the directive is consumed at the start of the next `respond` call before any other resolution runs. With a persistence adapter configured (and `autoSave` on — the default), dispatch persists immediately, so the queued directive survives process boundaries; without an adapter it is memory-only, and with `autoSave: false` persisting before the next turn is the caller's job. Because the save compare-and-swaps on the session version, a dispatch from a stale copy throws `SessionConflictError` instead of clobbering another writer.
-
-```typescript
-const updated = await agent.dispatch(
-  { goTo: "Billing", reply: "Transferring you now." },
-  session,
-);
-```
-
-Inside a turn, the same effect is reached by returning or dispatching a directive from a tool or hook — the per-turn bus handles the merge. Outside a turn, `Agent.dispatch` is the sanctioned entry point for setting the next position. There is one way to express each thing, and this is the one for "the user just clicked the cancel button in the UI; their next message should land in the Cancellation flow."
 
-The two routes — in-turn (return a directive) and out-of-turn (`Agent.dispatch`) — converge on the same place: `session.pendingDirective`. The pipeline consumes that field at the very top of the next turn before signals or routing run, applies it via `applyDirective`, and clears it. Persistence sees the same shape regardless of where the directive came from, which means the persisted state is independent of how the redirection was issued.
-
-### Branches
-
-A step's `branches` field declares an explicit, source-local fork: from this step, here are the next-step options and how each one is chosen. Branches sit between code and AI — `if` predicates evaluate for free, `when` strings call the LLM only when the predicate already passed. The first matching entry wins, and its `then` resolves to a step id (within the current flow), a flow id (sugar for `goTo`), or a full directive (for cross-flow steps and state-writing forks).
-
-Branches are the answer to "how do I fork without an LLM call when the choice is purely a function of `data`?" — combined with `auto: true`, an entire decision can run with zero tokens. They coexist with the implicit-fork pattern (multiple successor steps, each carrying its own `step.when`); when both are present on the same step, branches take precedence. Branch resolution sits between the post-LLM phase of the directive bus and the linear successor selection — it is one specific position in the [turn pipeline](./pipeline.md), not a parallel system.
-
-Branches are also the place where the AI/code split is most visible at the call site. A single `branches` array can mix entries: one entry that uses `if` only (free), one that uses `when` only (one LLM call), one that uses both (`if` short-circuits the `when` evaluation). The author chooses per branch, and the cost of that choice is local to one entry rather than buried in a flag elsewhere.
-
-## How the primitives reference each other
-
-The diagram below maps the ownership and reference relationships between the six primitives and the two state surfaces. Solid arrows are ownership. Dashed lines are scoping or extension. The two state nodes (`Schema` and `Context`) are not primitives — they are the typed surfaces the primitives operate on, drawn at the bottom because everything else references them.
-
-```mermaid
-graph TB
-  Schema[(Schema<br/>TData)]
-  Context[(Context<br/>TContext)]
-
-  Agent --> Schema
-  Agent --> Context
-  Agent -->|owns| Flow
-  Agent -->|owns| Tool
-  Agent -->|owns| Instruction
-
-  Flow -->|owns| Step
-  Flow -->|requiredFields| Schema
-  Flow -.scoped.- Tool
-  Flow -.scoped.- Instruction
-
-  Step -->|collect / requires| Schema
-  Step -.scoped.- Tool
-  Step -.scoped.- Instruction
-  Step -->|branches| Step
-  Step -->|onEnter / prepare| Directive
-  Step -->|finalize| Directive
-
-  Tool -->|ctx.dispatch| Directive
-  Tool -->|ToolResult.directive| Directive
-
-  Directive -.merged via.-> FlowNS[flow.merge]
+const agent = f.agent({
+  name: "Ana",
+  provider,
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      on: [{ message: [] }],
+      steps: [{ id: "nome", collect: ["nome"] }],
+    }),
+  ],
+});
 
-  classDef primitive fill:#1e293b,stroke:#0ea5e9,color:#fff;
-  classDef state fill:#0f172a,stroke:#64748b,color:#cbd5e1;
-  class Agent,Flow,Step,Tool,Instruction,Directive primitive;
-  class Schema,Context state;
+export { agent };
 ```
 
-Read it top-down. The agent owns flows, tools, and instructions, and binds them to a single schema and a single context type. A flow owns steps and may scope its own instructions and tools. A step references the schema through `collect` and `requires`, may carry its own scoped instructions and tools, and may fork via `branches` into another step. Hooks and tools emit directives — pre-LLM hooks use the pre-LLM fields (`appendPrompt`, `injectTools`, `halt`), post-LLM hooks use position/state/reply fields. The `flow` namespace validates and merges them.
-
-The two state types — `Schema` for `TData`, `Context` for `TContext` — sit at the bottom because everything else points at them. They are not primitives in the same sense as the six types; they are the typed surfaces those primitives operate on, and they are owned by the agent.
-
-Two things are deliberately absent from this diagram. There is no separate "router" primitive — flow selection is an internal pipeline phase, not a user-facing type. There is no separate "session" primitive in the declaration model — sessions are runtime state, indexed by `sessionId`, persisted by adapters, but not something application code constructs as a building block. Both of those concerns live in the [turn pipeline](./pipeline.md), where they are explained as steps in the per-turn sequence rather than parts of the static structure.
-
-## The schema-first principle
-
-`TData` is **agent-level**, not flow-level. One schema describes everything that can be collected across every flow. Flows declare which fields they need (`requiredFields`); steps declare which fields they extract (`collect`) and which they require (`requires`). This is what makes pre-extraction work: when the user message arrives, the engine extracts every collectable field it can in a single pass into `session.data`, then skips any step whose `collect` set is already satisfied.
-
-The agent owns the schema, so the same field can be collected by step A in flow X and used as a prerequisite by step B in flow Y. The contracts at every site are the same shape — `(keyof TData)[]` — and TypeScript verifies them at compile time. Move a field name once at the schema and the failures surface immediately at every call site that references it.
+The constructor checks the configuration before any turn runs: duplicate flow ids; every field, action, event, condition, tool and step id a flow names; the `with` of each `do` step against the action's parameters; the idle speaker's tool names. A bad name throws `FlowConfigurationError` when the agent is built, not on the turn that first reaches it.
 
-A practical consequence: a single user message like "I want a hotel in Lisbon for two people next Friday" populates `city`, `guests`, and `checkIn` in one extraction pass. The booking flow's first three steps all skip — their `collect` sets are already satisfied — and the engine arrives at the confirmation step on the very first turn. The flow's `requiredFields` gate completion the same way regardless of whether fields were collected one per turn or three at once. The schema does not care which step did the work; it only cares that the data is there.
+Per turn, the host passes what only it knows:
 
-## What the AI does, what the code does
+| Input | What it is |
+|---|---|
+| `sessionId`, `session?` | The session the host loaded, or nothing on a first turn. A wake never creates a session. |
+| `context` | Your own data for this turn: the customer, the tenant, whatever your flows read. Typed by `falai<C>()`. Templates read it as `{{context.x}}`; predicates, actions and tools as `ctx.context`. |
+| `history` | The conversation so far. Pass it on every input kind, wakes included; both calls read it. |
+| `silenced?` | Why the assistant cannot speak right now. `do` steps still run, nothing is phrased, zero calls — unless you pass `{ reason, understand: true }`, which still spends the understand call. |
+| `anchors?`, `claims?` | Host keys and claims from the customer's other sessions, for flows that run once per customer instead of once per session (see [Anchors](./runs-and-waits.md#anchors)). |
 
-Two halves divide the work, and the seven primitives are positioned on whichever half makes the decision cheap and correct.
+Then one of four input kinds: `{ message, id?, at? }`, `{ wake }`, `{ event, payload?, key }` or `{ start: { flow, input?, key } }`. [Agent](../reference/agent.md) lists every field.
 
-The AI is responsible for **language**: routing scores (which flow does this message want?), pre-extraction (what fields can be lifted out of this message?), step prompts (what should the assistant say to advance this step?), and the `when` half of conditions (does this AI-readable description match the situation?). The model is good at these jobs, and the framework spends tokens on them deliberately.
+## Never sends, never sleeps, never saves
 
-The code is responsible for **decisions**: completion (are all required fields present?), branches (does the `if` predicate pass?), tool execution (run the function, get a result), directive merging (which position field wins?), persistence (write the session, atomically). The runtime is good at these jobs, and the framework keeps them on the deterministic side of the seam.
-
-A primitive sits on the side that owns its decision. A `Flow.when` is AI because intent classification is the AI's job. A `Step.if` is code because boolean checks against `data` are the code's job. A `Directive` is code because the merge algorithm is deterministic. An `Instruction` is rendered text the code controls; the model only chooses how to follow it. Pulling on either thread leads back to the same answer: language belongs to the AI, decisions belong to the code, and the framework is the seam.
-
-The `when` / `if` split is the smallest visible expression of this principle. The same activation slot — on a flow, on a step, on an instruction, on a branch entry — accepts both: a string for the AI to evaluate, a function for the code to evaluate. When both are set, code runs first and short-circuits the AI call when the predicate already disqualifies the option. There is no unified condition type that abstracts the difference, because the difference is the point. One side spends tokens; the other does not. Authors choose explicitly, every time.
-
-## What stays out
-
-A few things are notably absent from the framework, and the absences are part of the architecture.
-
-There is no built-in router DSL. The flow router is a single internal phase that scores flows by their `when`/`if` activation, applies a margin against the currently active flow to avoid thrashing, and lands on exactly one flow per turn. It is not exposed for subclassing or composition because there is nothing usefully variable about it at the application layer.
-
-There is no per-flow schema. Every flow consumes the agent's `TData`. A flow that needs an extra structured field declares it on the agent schema and lists it in `requiredFields`. The "this flow has its own private state" pattern always becomes "this flow uses a subset of the shared schema."
-
-There is no implicit messaging. The framework never emits a message of its own. Completion is a pure state transition — the active flow ends, the session goes idle, and any prose at that boundary comes from a developer-defined `reply` step or from the next flow's first step. Nothing speaks unless a step or a directive says it.
-
-There is no glossary. Eight terms are defined in the callout at the top of this page, and every other term in the docs defines itself at first use on the page that introduces it. The framework's surface is small enough that a glossary would duplicate prose without adding clarity.
-
-## Why six primitives
-
-The set of six is the result of a few specific cuts. Each one collapsed a category of duplication into a single shape, and each one is worth naming for its own sake — not for migration purposes (the [migration guide](../migration/v1-to-v2.md) covers that), but because the surface visible today is the result of those choices.
-
-**One word per concept.** The verb form `route()` is still the act of selecting a flow, and "routing" is still the gerund — but the noun for "a single conversational goal" is **Flow**. The system that selects one is the **FlowRouter**. There is no overlap between the noun and the verb, which keeps the surface readable when the two appear in the same sentence.
-
-**One Instruction with a kind discriminator.** A behavioral statement is an `Instruction` with `kind: 'must' | 'never' | 'should'`. The three values cover absolute do, absolute don't, and conditional nudge — every behavioral statement an author wants to make falls into one of those categories, and the severity is visible at the call site. The renderer treats all three identically: same prompt position, same scope caption, same `appliedInstructions` reporting. Severity is what the model sees, not what the framework branches on.
-
-**One Tool with optional metadata.** A `Tool` is a single interface. The simple case is `{ id, handler }`. The production case adds `validateInput`, `checkPermissions`, `isReadOnly`, `isConcurrencySafe`, `isDestructive`, and `maxResultSizeChars` — every one optional. There is no upgrade boundary mid-codebase: a tool that starts as a plain function adds metadata fields when it needs them, without changing type or import. The executor reads each field defensively (undefined falls back to safe defaults), so the same tool runs identically with two metadata fields or zero.
-
-The remaining four primitives — Agent, Step, Flow, Directive — were always single-shape concepts. The six-primitive count is what survives those three consolidations plus the three that stood on their own.
-
-## Construction shape
-
-The level-1 entry point is `createAgent({ ... })` — one options object, generic inference flowing from `schema` through every `flows[].steps[].collect` reference. The class form `new Agent({ ... })` accepts the same options for power users who need to subclass.
-
-```typescript
-import { createAgent, GeminiProvider } from "@falai/agent";
-
-const agent = createAgent({
-  name: "BookingBot",
-  provider: new GeminiProvider({ apiKey }),
-  schema: { /* TData shape */ },
-  flows: [/* FlowOptions[] */],
-  tools: [/* Tool[] */],
-  instructions: [/* Instruction[] */],
-});
-```
+`turn()` does no I/O except the provider, your `do` handlers and the tools the model calls. It does not send a message, set a timer, read a clock you did not give it, or touch a store. It returns a plan:
 
-The construction shape encodes the ownership tree: an agent owns flows, tools, and instructions; the schema is set once; the provider is bound. Generic inference does the rest. The first time a `collect: ["foo"]` references a key not in the schema, the type checker objects at the call site. The first time two flows declare the same id, the constructor throws `FlowConfigurationError` synchronously. The first time a tool returns a malformed directive, `flow.validate` throws at apply time. Every error has a typed class, a single format (`[<ErrorClass>] <what>: <why>. <how to fix>.`), and a place in the construction or runtime sequence where it consistently surfaces.
+| Result | What the host does with it |
+|---|---|
+| `changed: false` | Nothing. Save nothing, send nothing. |
+| `session` | Save it with the version you loaded: `store.save(session, loadedVersion)`. A stale version throws `SessionConflictError`; discard everything and replay the same input. |
+| `messages[]` | Send each one, honouring `afterMs`, keyed by `key` so a retry never sends twice. |
+| `schedule[]` | Enqueue each wake with `jobId = key`. When it fires, call `turn({ wake: key })`. |
+| `outcomes`, `started`, `ended`, `skipped` | Your execution log. |
 
-## What's next
+The order matters: save first, then send and schedule. A message that leaves before the save is sent twice when the save loses a race; a message that leaves after it is not. The one exception is `do` handlers and tool handlers: they run inside the turn, before the save, so they run at least once and must be idempotent on `ctx.key`. [Runs and waits](./runs-and-waits.md#five-rules-that-always-hold) lists the five rules it rests on.
 
-The next page walks through what happens when `agent.respond(params)` is called: the per-turn pipeline, resolution precedence (`pendingDirective` first, then signals + routing in parallel, then auto-step chains, then branches, then linear succession), the directive bus, and how `flow.merge` collapses simultaneous emissions into a single applied directive. After that, the [Directives](./directives.md) page goes deeper into the directive shape itself — why it is flat, how `SignalDirective` extends it for signals, and what each field does.
+Time comes from `clock` on the agent (default: the system time), so a test passes `fakeClock()` and moves it by hand. Core code never reads `Date.now()`.
 
-If the goal right now is to write code, the [tutorial](../start/01-install.md) starts from a one-line install and arrives at a working agent in five short pages. If the goal is to look up an exact contract, every primitive on this page has a [reference](../reference/create-agent.md) page with the full TypeScript declaration, a fields table, two short examples, and the typed errors it can throw.
+## Where next
 
-**Next:** [Turn pipeline](./pipeline.md)
+- [The turn pipeline](./pipeline.md): the eight phases and what each one costs.
+- [Runs and waits](./runs-and-waits.md): the floor, waits, wakes, keys, claims.
+- [Field collection](./collection.md): pending fields, `ask`, `extract`, `maxAsks`.
+- [Your first agent](../start/02-first-agent.md): the same words, one file at a time.

package/docs/concepts/collection.md

@@ -0,0 +1,170 @@
+---
+title: "Field collection"
+description: "Declare each field once, then let the two model calls fill it and the code decide what is still missing."
+type: concept
+order: 4
+---
+
+# Field collection
+
+A field is one piece of data the conversation collects: a name, a company, a budget, a yes or no. You declare each field once, on the agent, with how to ask for it. Steps say which fields they collect. The model asks and extracts. Code decides what is still missing.
+
+## Declared once
+
+```ts
+import { falai } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome, sem tom de formulário." },
+});
+// `f` is the toolkit. `nome` is now a field any flow can collect.
+```
+
+Declare the rest the same way:
+
+```ts
+import { falai } from "@falai/agent";
+import type { DataOf } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome de um jeito leve, sem tom de formulário." },
+  tamanho: { type: "string", enum: ["1-10", "11-50", "51-200", "200+"], ask: "Pergunte quantas pessoas trabalham lá; ofereça as faixas." },
+  orcamento: { type: "number", ask: "Pergunte a faixa de investimento, dizendo que é só para orientar." },
+  confirmado: { type: "boolean", ask: "Resuma o que anotou e pergunte se está tudo certo." },
+});
+
+type Data = DataOf<typeof f>;
+// { readonly nome: string; readonly tamanho: "1-10" | "11-50" | "51-200" | "200+"; readonly orcamento: number; readonly confirmado: boolean }
+```
+
+| Property | What it does |
+|---|---|
+| `type` | `'string'`, `'number'`, `'integer'` or `'boolean'`. Values are coerced to it on the way in. |
+| `enum` | The allowed values. A value outside the list is dropped. It becomes a literal union in `Data`. |
+| `description` | What the field means, for the model. |
+| `ask` | How the model should ask for it. A step may override it. |
+| `extract` | Where a value may come from: `'anywhere'` or `'asked'`. The default depends on `type`, below. |
+
+`f.fields()` binds the data type, so `collect`, `ask`, `clearOnStart`, `{ step, clear }`, `if: { equals }` and an action's `ctx.set()` are all checked against these field names at compile time. The collected values live in `session.data` as a `Partial<Data>`.
+
+## Known and pending
+
+A field is **known** when its value is not `undefined`, `null` or `''`. Anything else is unknown. There is no "asked but refused" state, only a count.
+
+A talk step's **pending** fields are computed by code every time the step is reached or has spoken:
+
+```text
+pending = step.collect − known fields − fields asked maxAsks times      (in collect order)
+```
+
+Three things follow.
+
+- Fields land in any order. When the first message says "sou a Ana da Zeta, somos 30", three fields become known at once, one of them belonging to a later step.
+- A step with nothing pending is skipped with no model call: outcome `code: 'already-known'`. A run that was asking and finds its fields known on the next message logs `ok` and moves on.
+- A step stays `asking` until its pending set is empty or a branch fires. There is no deadlock: `maxAsks` empties the set eventually.
+
+## Where values come from
+
+Four writers reach `session.data`. Two are the model, two are your code.
+
+| Writer | Which fields | When |
+|---|---|---|
+| The understand call | Unknown fields with `extract: 'anywhere'` listed by any talk step of the floor's flow or of a candidate `message` flow | On a message, before runs move |
+| The speak call | The speaking step's pending fields, whatever their `extract`, in the envelope `{ message, ...fields }` | When the step speaks |
+| A tool's `data` | Whatever the tool returns | During a speak round, written as given |
+| An action's `ctx.set(patch)` | Whatever the action writes | During a `do` step, written as given |
+
+Values from the model are validated before they are written. Each dropped value leaves an outcome line instead of a write:
+
+| Check | Outcome detail |
+|---|---|
+| The name is not one of the agent's fields | `code: 'unknown-field'` |
+| The value does not fit the type | `code: 'bad-value'` |
+| The value is not in `enum` | `code: 'not-in-enum'` |
+
+Coercion is forgiving (`coerceField` in `src/utils/schema.ts`):
+
+- `"30"` becomes the number 30; a comma is a decimal separator, so `"1,5"` is 1.5.
+- An `integer` is truncated.
+- A boolean reads `true`, `sim`, `yes`, `1` as true and `false`, `não`, `nao`, `no`, `0` as false.
+- A number or boolean offered for a string is stringified.
+
+## `extract`: anywhere or asked
+
+`extract` says where a value may come from.
+
+- `'anywhere'`: from any customer message, by the understand call, before the run moves. The default for `string`, `number` and `integer`.
+- `'asked'`: only from the reply to the step that lists the field, by the speak envelope. The default for `boolean`, so a stray "sim" in an unrelated message never confirms anything.
+
+The default is `extractMode` in `src/utils/schema.ts`: `def.extract ?? (def.type === 'boolean' ? 'asked' : 'anywhere')`. Set it when the default is wrong for you: a document number you want only when asked, or a boolean the customer often volunteers.
+
+This split also decides which call spends tokens on what. On a message, the understand call lists every unknown `'anywhere'` field of the flows in play; the speak call lists only the current step's pending fields. A turn where everything the step needs is `'asked'` and no other flow is eligible skips the understand call entirely: one call for the whole turn (`tests/scenarios/s01-triagem.test.ts`, the correction test).
+
+## `maxAsks`
+
+`maxAsks` on a talk step is how many times a field may be asked before the step gives up on it. The default is 3 (`DEFAULT_MAX_ASKS` in `src/utils/schema.ts`).
+
+`run.asked[field]` goes up by one each time the step speaks and the field is still unknown after that reply's own extraction. A field that reaches the ceiling drops out of the pending set. When the set is empty the step reports it and moves to `then`:
+
+```text
+{ kind: 'collect', status: 'skipped', code: 'max-asks', detail: 'orcamento' }
+```
+
+One line per field that ran out of asks, with the field's slug in `detail`. `maxAsks: 1` means "ask once, do not insist". The field stays unknown: a later step may still collect it, and a later run of the flow starts the count again, because `asked` lives on the run.
+
+## Known fields are never re-extracted
+
+Once a field is known it disappears from both calls: the understand call does not list it, the speak envelope does not carry it, and the prompt shows it under "Already known" with the instruction never to ask again. This keeps both calls small, and it means a correction cannot happen by itself. To let the customer change a value, clear it:
+
+- `then: { step: 'quem', clear: ['confirmado', 'empresa'] }` clears the fields, then jumps. This is the idiom for a confirmation gate: a "no" clears the disputed field and re-asks it.
+- `clearOnStart: ['confirmado']` on a flow clears the fields when a run starts, before this turn's extraction lands. This is the idiom for `repeat: 'always'` flows that must ask again.
+- `ctx.set({ empresa: undefined })` from a `do` step.
+
+`onEnd: 'reset'` keeps the data: the new run starts at step one with everything still known, so only the steps whose fields were cleared will ask.
+
+```ts
+import { falai } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+  empresa: { type: "string", ask: "Pergunte de qual empresa a pessoa fala." },
+  orcamento: { type: "number", ask: "Pergunte a faixa de investimento." },
+  confirmado: { type: "boolean", ask: "Resuma o que anotou e pergunte se está tudo certo." },
+});
+
+const triagem = f.flow({
+  id: "triagem",
+  name: "Triagem",
+  on: [{ message: ["quer saber como funciona"], repeat: "always" }],
+  clearOnStart: ["confirmado"],
+  steps: [
+    { id: "quem", prompt: "Descubra quem é e de onde fala.", collect: ["nome", "empresa"] },
+    { id: "grana", collect: ["orcamento"], ask: { orcamento: "Pergunte quanto {{data.empresa}} pensa em investir por mês." }, maxAsks: 2 },
+    { id: "confirma", collect: ["confirmado"] },
+    { id: "ok", if: { equals: { confirmado: true } }, else: { step: "quem", clear: ["confirmado", "empresa"] } },
+    { id: "tchau", say: "Obrigada, {{data.nome}}. Um vendedor continua daqui." },
+  ],
+});
+
+export { triagem };
+```
+
+## The wording
+
+Three layers of text shape the question, from general to specific.
+
+1. The field's `ask`: the default wording for that field everywhere.
+2. The step's `ask: { orcamento: '…' }`: wins over the field's, for that step only.
+3. The step's `prompt`: the guideline for the whole reply. Without one, the default is "Collect what is still missing below, in the flow of the conversation, one or two things per message."
+
+All three are templates: `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are filled in before the model reads them. The model sees every pending field of the step with its wording, in collect order, and is told to ask at the pace the prompt sets and to take any value the customer's message already answers.
+
+## What the provider sees
+
+`toWireSchema` in `src/utils/schema.ts` is the only way a field definition reaches a provider. It keeps `type`, `description` and `enum` and strips `ask`, `extract` and `optional`: those are for the framework, not the model. The result is a closed JSON schema (`additionalProperties: false`). In both envelopes every property is required and nullable, so the model must answer each field with a value or `null`. A field name that is not a legal property name for the provider, or is spelled `message`, travels under an alias and is mapped back on the way out.
+
+## Where next
+
+- [Collect data](../start/03-collect-data.md): the same ideas as a tutorial.
+- [Branching](../guides/branching.md): `when` and `if` branches on a talk step.
+- [Fields](../reference/fields.md): `FieldDef`, `ScalarDef`, `DataOf`, `InferData`.