@falai/agent 3.4.5 → 4.0.0-alpha.10

package/docs/guides/streaming.md

@@ -1,149 +1,85 @@
 ---
 title: "Streaming"
-description: "Stream the assistant's reply token by token, surface tool calls in flight, and cancel mid-turn with an `AbortSignal`."
+description: "turnStream: the reply arrives as text deltas, the full turn result arrives last, and everything else works exactly as in turn()."
 type: guide
-order: 6
+order: 9
 ---
 
 # Streaming
 
-`agent.respond` returns a single `AgentResponse` after the LLM and any tool calls have finished. That works for batch work, but a chat UI feels dead until the first character lands. `agent.respondStream` returns an `AsyncGenerator<AgentResponseStreamChunk>`, yielding the assistant's reply incrementally and finishing with one terminal chunk that carries all the metadata.
+`agent.turnStream()` is `agent.turn()` that yields the reply while the model writes it.
 
-This guide is a recipe: take a non-streaming call site, swap to `respondStream`, render tokens as they arrive, expose a "thinking" indicator while tools run, read instruction and signal telemetry off the final chunk, and wire an `AbortSignal` so the user can stop mid-turn.
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-## The shape
-
-`respondStream` takes the same `RespondParams` as `respond` — `history`, optional `session`, optional `contextOverride`, optional `signal` — and returns an async iterable of chunks.
-
-```typescript
-const stream = agent.respondStream({
-  history: [{ role: "user", content: "Book me a hotel in Lisbon." }],
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
 });
 
-for await (const chunk of stream) {
-  process.stdout.write(chunk.delta);
-}
-```
-
-Every chunk has the same shape:
-
-```typescript
-interface AgentResponseStreamChunk<TData> {
-  delta: string;        // Text added since the previous chunk
-  accumulated: string;  // Full text so far
-  done: boolean;        // True only on the terminal chunk
-  // ...metadata fields, populated on the final chunk
-}
-```
-
-`delta` is the new token(s); concatenating every `delta` reproduces the final reply unless a post-phase signal replaces the message on the terminal chunk. `accumulated` is the authoritative running total — useful when your renderer needs the full string each tick (e.g., a Markdown view that re-parses on every update). `done` flips to `true` exactly once, on the terminal chunk.
-
-## Render incrementally
-
-The simplest renderer prints every `delta` as it arrives and clears the line on `done`:
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      on: [{ message: [] }],
+      steps: [{ id: "nome", collect: ["nome"] }],
+    }),
+  ],
+});
 
-```typescript
-for await (const chunk of agent.respondStream({ history })) {
-  if (chunk.delta) {
+for await (const chunk of agent.turnStream({ sessionId: "demo", message: "oi, sou o Rui" })) {
+  if ("delta" in chunk) {
     process.stdout.write(chunk.delta);
+    continue;
   }
-  if (chunk.done) {
-    process.stdout.write("\n");
-  }
-}
-```
-
-For a UI, push the latest `accumulated` into your component state. React, Solid, Svelte — they all re-render off whichever value you give them, and `accumulated` is the cheapest to consume because it never requires the renderer to track partial state.
-
-A common rendering rule of thumb:
-
-- Plain text view → append `delta`.
-- Markdown view that re-parses each frame → bind to `accumulated`.
-- Server-Sent Events transport → forward `{ delta, done }` per chunk; let the client reassemble.
-
-## Surface tool calls in flight
-
-Streaming works through tool calls transparently. When the LLM emits a tool call mid-reply, `respondStream` runs the tool, then resumes streaming the post-tool tokens — the consumer never sees the call boundary in the text. What you do get is a quiet gap while the tool executes, which is the right moment to show a "thinking" indicator.
-
-Detect the gap by watching for empty `delta` chunks after some text has already arrived, or — more robustly — toggle the indicator off as soon as the first non-empty `delta` lands:
-
-```typescript
-let thinking = true;
-let firstToken = true;
-
-for await (const chunk of agent.respondStream({ history })) {
-  if (chunk.delta) {
-    if (firstToken) {
-      thinking = false;
-      firstToken = false;
-      ui.hideSpinner();
-    }
-    ui.appendText(chunk.delta);
-  }
+  process.stdout.write("\n");
+  console.log(chunk.result.llmCalls, chunk.result.session.data); // 1 { nome: 'Rui' }
 }
 ```
 
-If you need finer-grained tool telemetry — which tool fired, with what arguments — read `chunk.toolCalls` on the terminal chunk. It mirrors the same field on the non-streaming `AgentResponse`. For per-tool progress UI, attach observability to the [tool's `handler`](../reference/tool.md) directly; the streaming chunk shape stays clean.
+The stream prints the reply one piece at a time, then the last chunk hands you the same `TurnResult` that `turn()` would have returned.
 
-When a step uses [verbatim `reply`](../reference/step.md) or a `halt` directive, the engine skips the LLM entirely and yields a single chunk with `done: true` and the full text in `accumulated`. The renderer above handles that case without a special branch — there is just no spinner gap.
+## The chunks
 
-## The terminal chunk
-
-The chunk where `done: true` carries every observability field that lives on `AgentResponse`. Three matter for most call sites:
-
-```typescript
-for await (const chunk of agent.respondStream({ history })) {
-  // ...render delta...
-  if (chunk.done) {
-    console.log("flow complete:", chunk.isFlowComplete);
-    console.log("instructions rendered:", chunk.appliedInstructions);
-    console.log("signals fired:", chunk.triggeredSignals);
-  }
-}
+```ts fragment
+type TurnStreamChunk<D> =
+  | { delta: string }                      // a piece of the reply, in order
+  | { done: true; result: TurnResult<D> }; // always last, exactly once
 ```
 
-- **`appliedInstructions`** — the [instructions](../reference/instruction.md) whose conditions passed and were rendered into this turn's prompt. Deterministic; derived from rendering, not from LLM self-report. Empty on intermediate chunks; populated only when `done: true`.
-- **`triggeredSignals`** — the [signals](../reference/signals.md) that fired during this turn (pre- and post-phase), in fire order. Same population rule.
-- **`isFlowComplete`** — `true` when this turn finished the flow. Use it to decide whether to clear the conversation, show a summary card, or transition the UI.
+Every `delta` is plain message text. Joined together they add up to the reply. The `done` chunk carries the whole result: `session`, `changed`, `messages[]`, `schedule[]`, `outcomes[]`, `started`, `ended`, `skipped`, `llmCalls`. Read [the agent reference](../reference/agent.md) for the fields.
 
-The terminal chunk also carries `executedSteps`, `stoppedReason`, `metadata` (model, token usage), and the updated `session`. These are the same fields you would read off `AgentResponse` — swapping between APIs does not change observability.
+## What streams and what does not
 
-## Cancel mid-stream
+Only the speak call streams: the one call that phrases the reply. Everything else in the turn is code or a call that never streams.
 
-Pass an `AbortSignal` through `respondStream` and abort the controller to cancel. The generator stops yielding, the in-flight LLM call is cancelled at the provider boundary, and any tool execution unwinds cleanly.
+| Source | Arrives as |
+|---|---|
+| the talk step's reply, or the idle speaker's | `delta` chunks, then in `result.messages[]` as one `kind: "ai"` message |
+| a `say` step's text | `result.messages[]` only, `kind: "verbatim"` |
+| the understand call (routing, mentions, extraction) | nothing visible; it finishes before the first delta |
+| actions, waits, `if` steps | `result.outcomes[]`, `result.schedule[]` |
 
-```typescript
-const controller = new AbortController();
+The provider streams a JSON envelope, not bare text: `{"message":"Oi, Rui! Em que posso"…` followed by the collected fields. The framework unwraps it as it arrives (`src/utils/streamingMessage.ts`), so a `delta` never contains a brace, a quote or a field name, and a field the model writes before the message is skipped rather than leaked. A provider that streams plain text passes through as it is.
 
-// User clicks Stop, or a 5s ceiling fires.
-const timer = setTimeout(() => controller.abort(), 5000);
+## Tool calls during a stream
 
-try {
-  for await (const chunk of agent.respondStream({
-    history,
-    signal: controller.signal,
-  })) {
-    process.stdout.write(chunk.delta);
-  }
-} finally {
-  clearTimeout(timer);
-}
-```
+A speak call may run in rounds: the model calls tools, the results go back as history, and the model is asked again. This happens inside the stream, before the `done` chunk. Each round streams. If the model writes something beside a tool call ("deixa eu ver"), that preamble reaches the stream, while `result.messages[0].text` holds only the final round's message. A UI that shows deltas as they come should replace what it showed with `result.messages[0].text` when `done` arrives, so both paths end on the same text.
 
-When the signal aborts, the loop exits cleanly — no exception is thrown by the generator itself. If the LLM provider surfaces the cancellation as an error, it lands as a [`ResponseGenerationError`](../reference/errors.md) and you handle it the way you would any other turn-level error.
+Rounds are capped by `maxToolLoops` on the agent, default 5; after the cap the model is asked once more with no tools so a message always comes back. Each round is one model call and counts in `result.llmCalls`.
 
-For a Stop button, store the `controller` reference for the active stream on the UI side and call `controller.abort()` from the click handler. For server-side hard ceilings, wrap `respondStream` with an `AbortController` whose `setTimeout` fires at your SLO budget.
+## A provider failure mid-stream
 
-If the turn fails — the generator surfaces an error chunk — it has no lasting effect: the in-memory session rolls back to its pre-turn snapshot (the user message added by `stream()` before the turn is retained), and persisted state is whatever the previous turn saved. Retrying is always safe.
+The stream never throws for a speak failure. You get zero or more deltas and then the `done` chunk, whose result carries a `deferred` outcome and a retry wake, exactly as `turn()` would report it.
 
-## Reliability: retries, backups, and the first-chunk deadline
+A failure mid-stream leaves the person looking at half a reply. Nothing of that half reaches `result.messages[]`, so the deltas you showed are its only trace: clear them when `done` carries a `deferred` outcome, and leave a short line saying the reply is coming. The retry wake fires a minute later, speaks that step again from the start, and its reply arrives as an ordinary message carrying the key the first attempt would have used.
 
-Streaming inherits the same resilience machinery as non-streaming calls — provider `retryConfig` and `backupModels` — with stream-specific rules:
+A failure in the understand call, before any delta, throws from the `for await` like `turn()` does. See [error handling](./error-handling.md).
 
-- **Retry only before the first chunk.** A stream that fails before yielding anything (a connection error, an empty completion, a stalled open) is retried on the same model up to `retryConfig.retries` times. Once a delta has reached your renderer, the stream is committed: any later failure propagates instead of retrying, so a retry can never emit a token your consumer has already seen.
-- **First-chunk deadline.** `retryConfig.timeout` doubles as the time-to-first-token budget. If the provider opens a stream but produces no first chunk within it, the attempt counts as failed and the retry and backup machinery takes over. Only the first chunk is bounded — later chunks are unbounded, so a long-but-healthy stream is never cut off.
-- **Transparent backup-model switch.** With `backupModels` configured, a model that fails mid-stream — even after deltas were delivered — falls through to the next model, whose chunks flow through unchanged. The switchover happens between chunks; no error reaches the consumer unless every model fails.
+## The same settle, the same result
 
-These knobs live on the provider constructor, not on `respondStream` — see [Providers](../reference/providers.md) for `retryConfig` and `backupModels`.
+`turnStream` runs the same eight phases as `turn()` and applies the reply the same way. With the same provider output, the two return identical results: the same message keys, the same data written, the same schedule. Stream when you show text to a person as it is written. When the messages leave through a channel you send to yourself, `turn()` is simpler, because it gives you the messages after the save and nothing before it.
 
-**Next:** [Errors](./error-handling.md)
+Save and send are still yours, and still in that order: the `done` chunk's `result.session` is what you save with the version you loaded, and a `SessionConflictError` means you replay the same input; see [persistence](./persistence.md). With a stream the person has already seen the text by then, which is fine in a chat window and is the reason to prefer `turn()` on a channel.

package/docs/guides/testing.md

@@ -0,0 +1,284 @@
+---
+title: "Testing"
+description: "A clock you hold still, a scheduler you fire by hand, a store in memory and a provider you script: everything a turn needs, with no network."
+type: guide
+order: 12
+---
+
+# Testing
+
+The core does no I/O beyond the provider and your actions, so a test drives a real `Agent` with four fakes. Start with the clock.
+
+```ts
+import { fakeClock } from "@falai/agent";
+
+const clock = fakeClock("2026-09-20T10:00:00.000Z");
+clock.advance("24h");
+console.log(clock.now().toISOString()); // 2026-09-21T10:00:00.000Z
+```
+
+Pass `clock` to the agent and every `now`, every wake time and every key that carries a timestamp comes from it. The core never reads `Date.now()`.
+
+## The four fakes
+
+| Fake | From | What it replaces |
+|---|---|---|
+| `fakeClock(iso)` | `@falai/agent` | time: `now()`, `advance("2d" \| ms)`, `set(iso)` |
+| `MemoryScheduler` | `@falai/agent` | your queue: `add(entry)`, `remove(key)`, `size`, `due(now)` returns and removes what is due, earliest first; a new entry with the same key replaces the old one, and `replaces` removes that key |
+| `MemoryStore` | `@falai/agent` | your database, with the same version check |
+| a scripted `AiProvider` | you write it, about 25 lines | the model |
+
+The snippets below use `node:assert/strict` so they run under `bun run` or `node` with no framework. The repo's own tests use `bun test` the same way.
+
+## A scripted provider
+
+The framework names each call through `parameters.schemaName`: `"understand"` for the call that judges the customer's message, `"speak"` for the call that phrases the reply. A scripted provider keeps one queue per name, shifts the next reply off it, and throws when a queue runs dry, so a turn that spends a call you did not expect fails loudly.
+
+```ts
+import type { AiProvider, GenerateMessageInput, GenerateMessageOutput, GenerateMessageStreamChunk } from "@falai/agent";
+
+type Reply = Record<string, unknown>;
+
+export interface Scripted extends AiProvider {
+  /** Every call's schema name, in order. */
+  calls: string[];
+}
+
+export function scripted(script: { understand?: Reply[]; speak?: Reply[] }): Scripted {
+  const queues: Record<string, Reply[]> = { understand: [...(script.understand ?? [])], speak: [...(script.speak ?? [])] };
+  const calls: string[] = [];
+
+  function next<T>(input: GenerateMessageInput): GenerateMessageOutput<T> {
+    const name = input.parameters?.schemaName ?? "(unnamed)";
+    calls.push(name);
+    const reply = queues[name]?.shift();
+    if (!reply) throw new Error(`no scripted "${name}" reply left for call #${calls.length}`);
+    const message = typeof reply.message === "string" ? reply.message : JSON.stringify(reply);
+    return { message, structured: reply as T };
+  }
+
+  return {
+    name: "scripted",
+    calls,
+    capabilities: { supportsTools: true, supportsNativeJsonSchema: true, supportsStreaming: true, supportsStreamingToolCalls: true, supportsPromptCaching: false },
+    generateMessage: <_C, T>(input: GenerateMessageInput) => Promise.resolve().then(() => next<T>(input)),
+    // eslint-disable-next-line @typescript-eslint/require-await -- one chunk, nothing to await
+    async *generateMessageStream<_C, T>(input: GenerateMessageInput): AsyncGenerator<GenerateMessageStreamChunk<T>> {
+      const out = next<T>(input);
+      yield { delta: out.message, accumulated: out.message, done: true, structured: out.structured };
+    },
+  };
+}
+```
+
+The two envelopes you script, as the framework reads them:
+
+```ts fragment
+// understand: every section present, empty when there is nothing to say
+{
+  flows: { triagem: 90 },                 // flowId → 0–100 fit of the message to the flow
+  mentions: { concorrente: true },        // flowId → the customer brought it up
+  extract: { concorrente: { trecho: "a Acme cobra metade" } },  // flowId → values for the mention's `extract`
+  branches: {},                           // "runId/stepId/index" → the `when` holds
+  fields: { nome: "Ana" },                // field → the raw value the customer gave
+}
+
+// speak: the message, then one property per pending field, null when the customer did not give it
+{ message: "Oi Ana! De qual empresa você fala?", empresa: null }
+
+// speak, calling a tool first: the next scripted speak reply answers after the tool ran
+{ toolCalls: [{ toolName: "orcamento", arguments: { pessoas: 30 } }] }
+```
+
+A `fields` value goes through the same coercion as production: `"sim"` becomes `true` for a boolean, `"1,5"` becomes `1.5` for a number, `"mil"` is dropped with the outcome `code: 'bad-value'`, and an enum value outside the list is dropped with `code: 'not-in-enum'`.
+
+## One test, end to end
+
+A triage flow that collects two fields and a silence flow that nudges after 24 hours. The test asserts the call count, the message keys, the wake key, then fires the wake through the scheduler.
+
+```ts
+import assert from "node:assert/strict";
+import { falai, fakeClock, MemoryScheduler, MemoryStore, type AiProvider, type DataOf, type GenerateMessageInput, type GenerateMessageOutput, type GenerateMessageStreamChunk, type TurnKind } from "@falai/agent";
+
+// The scripted provider from above, inlined so this file stands alone.
+type Reply = Record<string, unknown>;
+function scripted(script: { understand?: Reply[]; speak?: Reply[] }): AiProvider & { calls: string[] } {
+  const queues: Record<string, Reply[]> = { understand: [...(script.understand ?? [])], speak: [...(script.speak ?? [])] };
+  const calls: string[] = [];
+  function next<T>(input: GenerateMessageInput): GenerateMessageOutput<T> {
+    const name = input.parameters?.schemaName ?? "(unnamed)";
+    calls.push(name);
+    const reply = queues[name]?.shift();
+    if (!reply) throw new Error(`no scripted "${name}" reply left for call #${calls.length}`);
+    return { message: typeof reply.message === "string" ? reply.message : JSON.stringify(reply), structured: reply as T };
+  }
+  return {
+    name: "scripted",
+    calls,
+    capabilities: { supportsTools: true, supportsNativeJsonSchema: true, supportsStreaming: true, supportsStreamingToolCalls: true, supportsPromptCaching: false },
+    generateMessage: <_C, T>(input: GenerateMessageInput) => Promise.resolve().then(() => next<T>(input)),
+    // eslint-disable-next-line @typescript-eslint/require-await -- one chunk, nothing to await
+    async *generateMessageStream<_C, T>(input: GenerateMessageInput): AsyncGenerator<GenerateMessageStreamChunk<T>> {
+      const out = next<T>(input);
+      yield { delta: out.message, accumulated: out.message, done: true, structured: out.structured };
+    },
+  };
+}
+
+const T0 = "2026-09-20T10:00:00.000Z";
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome de um jeito leve." },
+  empresa: { type: "string", ask: "Pergunte de qual empresa a pessoa fala." },
+});
+type Data = DataOf<typeof f>;
+
+const triagem = f.flow({
+  id: "triagem",
+  name: "Triagem",
+  on: [{ message: ["quer saber como funciona", "pede um orçamento"] }],
+  steps: [
+    { id: "quem", prompt: "Descubra quem é e de onde fala.", collect: ["nome", "empresa"] },
+    { id: "tchau", prompt: "Agradeça e diga que um vendedor continua daqui." },
+  ],
+});
+
+const retomar = f.flow({
+  id: "retomar",
+  name: "Retomar quem sumiu",
+  on: [{ silence: "24h" }],
+  steps: [
+    { id: "p1", prompt: "Retome a conversa de forma leve e pergunte se ainda faz sentido." },
+    { id: "w1", wait: "2d", else: "end" },
+    { id: "p2", prompt: "Última tentativa, curta e sem pressão." },
+  ],
+});
+
+const clock = fakeClock(T0);
+const provider = scripted({
+  understand: [{ flows: {}, mentions: {}, extract: {}, branches: {}, fields: { nome: "Ana" } }],
+  speak: [{ message: "Oi Ana! De qual empresa você fala?", empresa: null }, { message: "Oi Ana, ainda faz sentido conversarmos?" }],
+});
+const agent = f.agent({ name: "Ana", provider, clock, flows: [triagem, retomar] });
+const store = new MemoryStore<Data>();
+const scheduler = new MemoryScheduler();
+
+async function runTurn(input: TurnKind & { sessionId: string }) {
+  const session = await store.load(input.sessionId);
+  const r = await agent.turn({ ...input, session: session ?? undefined, history: [] });
+  if (r.changed) {
+    await store.save(r.session, session?.version ?? 0);
+    for (const entry of r.schedule) scheduler.add(entry);
+  }
+  return r;
+}
+
+// Turn 1: the customer writes. Understand extracts the name (1 call), speak asks for the company (1 call).
+const t1 = await runTurn({ sessionId: "s1", message: "oi, sou a Ana, quero saber como funciona", id: "m1" });
+assert.equal(t1.llmCalls, 2);
+assert.deepEqual(provider.calls, ["understand", "speak"]);
+assert.equal(t1.session.data.nome, "Ana");
+assert.equal(t1.messages[0]?.key, "triagem#m1:quem:1"); // ${runId}:${stepId}:${visit}
+assert.equal(t1.outcomes.find((o) => o.kind === "collect")?.status, "ok");
+// The assistant spoke last: the silence flow armed a wake for 24h from now.
+const silenceKey = `silence:retomar:s1:${Date.parse(T0)}`;
+assert.deepEqual(t1.schedule.map((s) => s.key), [silenceKey]);
+assert.equal(scheduler.size, 1);
+
+// 23h later nothing is due; at 24h the wake fires.
+clock.advance("23h");
+assert.equal(scheduler.due(clock.now()).length, 0);
+clock.advance("1h");
+const due = scheduler.due(clock.now());
+assert.deepEqual(due.map((d) => d.key), [silenceKey]);
+
+// Turn 2: the wake starts `retomar`, which speaks first (1 call) and parks on w1.
+const t2 = await runTurn({ sessionId: "s1", wake: due[0].key });
+assert.equal(t2.llmCalls, 1);
+assert.deepEqual(t2.started.map((s) => s.flowId), ["retomar"]);
+assert.equal(t2.messages[0]?.key, `retomar#${Date.parse(T0)}:p1:1`);
+assert.deepEqual(t2.outcomes.find((o) => o.stepId === "w1"), {
+  runId: `retomar#${Date.parse(T0)}`,
+  flowId: "retomar",
+  stepId: "w1",
+  key: `retomar#${Date.parse(T0)}:w1:1`,
+  kind: "wait",
+  status: "waiting",
+  until: new Date(clock.now().getTime() + 2 * 86_400_000).toISOString(),
+  at: clock.now().toISOString(),
+});
+assert.deepEqual(t2.schedule.map((s) => s.key), [`retomar#${Date.parse(T0)}:w1:${clock.now().getTime() + 2 * 86_400_000}`]);
+// Triagem still holds its question: the nudge did not take the floor for good.
+assert.equal(t2.session.runs.find((r) => r.flowId === "triagem")?.status, "asking");
+assert.equal((await store.load("s1"))?.version, 2);
+
+console.log("ok");
+```
+
+What each assertion pins down:
+
+- `llmCalls` is the budget. A turn that spends more than you scripted throws inside the provider, so an unexpected third call cannot pass silently. `usage` is absent in tests unless your scripted provider reports token counts — real providers do, and the turn adds them up.
+- `messages[].key` is `${runId}:${stepId}:${visit}`, and `runId` is `${flowId}#${triggerKey}`. The trigger key of a message turn is the message `id` you passed; of a silence wake, the `lastAssistantAt` timestamp in milliseconds.
+- `schedule[].key` is what your queue job carries (its id is the key encoded, since BullMQ refuses a `:` in one) and what you pass back as `wake`. The silence key is `silence:${flowId}:${sessionId}:${ms}`; a timer wait's key is `${runId}:${stepId}:${atMs}`.
+- `outcomes[]` is the execution log, one line per step. Assert on `code`, which is stable across versions, not on `message`, the English sentence beside it; see [outcomes](../reference/outcomes.md).
+
+## Replaying the same input
+
+The keys are deterministic: the same input on the same session version mints the same run id, the same message keys and the same wake keys. That is what makes a `SessionConflictError` safe to replay and a duplicate webhook harmless. Prove it with two agents that share a clock:
+
+```ts
+import assert from "node:assert/strict";
+import { falai, fakeClock, type AiProvider, type GenerateMessageInput, type GenerateMessageOutput, type GenerateMessageStreamChunk } from "@falai/agent";
+
+type Reply = Record<string, unknown>;
+function scripted(speak: Reply[]): AiProvider {
+  const queue = [...speak];
+  function next<T>(input: GenerateMessageInput): GenerateMessageOutput<T> {
+    if (input.parameters?.schemaName !== "speak") throw new Error(`unexpected ${input.parameters?.schemaName ?? "unnamed"} call`);
+    const reply = queue.shift();
+    if (!reply) throw new Error("no scripted speak reply left");
+    return { message: String(reply.message), structured: reply as T };
+  }
+  return {
+    name: "scripted",
+    capabilities: { supportsTools: true, supportsNativeJsonSchema: true, supportsStreaming: true, supportsStreamingToolCalls: true, supportsPromptCaching: false },
+    generateMessage: <_C, T>(input: GenerateMessageInput) => Promise.resolve().then(() => next<T>(input)),
+    // eslint-disable-next-line @typescript-eslint/require-await -- one chunk, nothing to await
+    async *generateMessageStream<_C, T>(input: GenerateMessageInput): AsyncGenerator<GenerateMessageStreamChunk<T>> {
+      const out = next<T>(input);
+      yield { delta: out.message, accumulated: out.message, done: true, structured: out.structured };
+    },
+  };
+}
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+const flows = [
+  f.flow({ id: "boas-vindas", name: "Boas-vindas", on: [{ message: [] }], steps: [{ id: "nome", collect: ["nome"] }] }),
+  f.flow({ id: "retomar", name: "Retomar", on: [{ silence: "24h" }], steps: [{ id: "p1", prompt: "Retome a conversa." }] }),
+];
+const clock = fakeClock("2026-09-20T10:00:00.000Z");
+const reply = { message: "Oi! Como você se chama?", nome: null };
+
+const first = await f.agent({ name: "Ana", provider: scripted([reply]), clock, flows }).turn({ sessionId: "s1", message: "oi", id: "m1" });
+const replay = await f.agent({ name: "Ana", provider: scripted([reply]), clock, flows }).turn({ sessionId: "s1", message: "oi", id: "m1" });
+
+assert.deepEqual(replay.messages, first.messages); // same key: boas-vindas#m1:nome:1
+assert.deepEqual(replay.schedule, first.schedule); // same wake: silence:retomar:s1:<ms>
+assert.deepEqual(replay.session.runs, first.session.runs);
+assert.equal(first.llmCalls, 1); // a catch-all alone, and nothing to extract before the ask: no understand call
+console.log("ok");
+```
+
+The same holds inside one session: feed the same `{ message, id }` to the session version it was computed on and the result is the same. Feed it again to a version that already recorded that id and the turn is ignored with `changed: false` and the outcome `code: 'duplicate-input'`.
+
+## Other things worth a test
+
+- A `silenced` turn: `agent.turn({ …, silenced: "humano no comando" })` spends zero calls, phrases nothing, and still runs `do` steps. Assert `llmCalls === 0` and `messages.length === 0`.
+- A speak failure: leave the `speak` queue empty so the scripted provider throws inside the turn. `agent.turn()` still returns — no try/catch needed. Assert the outcome `{ status: "deferred", code: "provider-unavailable" }` and a `schedule[]` key ending in `:retry:<ms>`. See [error handling](./error-handling.md).
+- A stale wake: fire a key the session no longer waits for and assert `changed === false` and the outcome `code: 'stale-wake'`.
+- Actions: register `f.action` handlers that push `ctx.key` and `ctx.dedupeKey` to an array, and assert the list. The keys are the same on a replay.
+- The prompt: keep every `GenerateMessageInput` your provider receives and assert on `input.prompt` (which instructions reached it) and `input.tools` (which tools were offered). The repo's own scripted provider, `tests/mock-provider.ts`, records them as `calls[].prompt` and `calls[].input`.
+- Streaming: `turnStream` with the same scripted provider yields one `delta` per provider chunk and a final `{ done, result }` equal to what `turn()` returns.
+
+See [the pipeline](../concepts/pipeline.md) for what each phase costs, and [runs and waits](../concepts/runs-and-waits.md) for the full key table.