@falai/agent 4.0.0-alpha.9 → 4.0.0

package/docs/concepts/runs-and-waits.md

@@ -68,7 +68,7 @@ Every start, whatever the trigger, goes through the same checks in `Runner.start
 At most one run in a session is `asking`. That run holds the floor: its talk step spoke last, and the next message is read as its answer.
 
 - A talk step reached by any other run suspends the asker (`status: 'suspended'`, `suspendedAt: now`) and takes the floor. A follow-up nudge that fires while triage is mid-question does exactly this.
-- Whenever nobody is asking, at the start of phase 5 and again after Speak, the **most recently suspended** run returns to asking. It is a stack: `suspendedAt` decides, not `startedAt`. `tests/runner.test.ts` ("the floor") pins this with three runs.
+- Whenever nobody is asking, at the start of phase 5 and again after Speak, the **most recently suspended** run returns to asking. On a message, it also happens in phase 5 once every run has moved, when nothing has answered yet; the resumed run then answers it, or the next one down the stack does if it too moves on without a word. It is a stack: `suspendedAt` decides, not `startedAt`. `tests/runner.test.ts` ("the floor") pins this with three runs.
 - An asking run re-speaks only on a message. Wakes and events leave it alone.
 - On a message, routing may move the floor to another flow: it needs a score of at least 40 and at least 15 above the asker's. Then that flow's suspended run resumes, or a new run starts. Routing never takes the floor from a run that took it in Ingest (a resolved wait, a wake). [Triggers](../guides/triggers.md) has the routing rules.
 - One answer per message. When a run other than the floor holder answered this turn (a `say`, or a `do` returning `spoke: true`), the floor's talk is skipped (`code: 'another-reply'`) and the asker stays asking.
@@ -81,7 +81,7 @@ A `wait` step parks the run. There are two kinds.
 
 - **Ten seconds or less**, when the next step is a `say` or a talk step: no wake at all. The delay rides on that message as `afterMs` (`wait: '3s'` gives `afterMs: 3000`) and the run keeps moving. Any other short wait behaves like a long one.
 - **Longer**: the run parks with `waiting: { kind: 'timer', key, until, setAt }`, and `schedule[]` gets `{ key, at }`. `businessHours: true` moves `at` forward to the next open hour, using the agent's `businessHours` function.
-- A message, or an inbound event, while parked: every timer wait with an `else` takes it at Ingest, outcome `code: 'replied'`. An `if` branch on the wait step is checked first and wins over `else`; `when` branches on a wait step are not judged.
+- A message, or an inbound event, while parked: every timer wait with an `else` takes it at Ingest, outcome `code: 'replied'`. An `if` branch on the wait step is checked first and wins over `else`; `when` branches on a wait step are not judged, and `validateFlow` warns about them.
 - The wake fires: `code: 'no-reply'`, `then`. Unless the customer wrote after `waiting.setAt` and the step has an `else`: then `code: 'replied'`, `else`. The reply beat the job.
 
 **Event**: `{ wait: { event: 'meeting_booked', upTo?: '7d' }, else? }`. The event arrives: `code: 'event-arrived'`, `then`. `upTo` passes (default 30 days): `code: 'no-event'`, `else`, or the run ends when there is no `else`.

package/docs/guides/actions-and-events.md

@@ -111,7 +111,7 @@ const enviarTemplate = f.action({
 });
 ```
 
-**`defer`** is for "not now": no credits, a rate limit, a window that is closed. The run parks under the wake key `<runId>:<stepId>:<atMs>` and the host schedules it like any other wake. When it fires, the step runs again at the same visit, so `ctx.key` is the same. The outcome carries your `detail` and the `until` time.
+**`defer`** is for "not now": no credits, a rate limit, a window that is closed. The run parks under the wake key `<runId>:<stepId>:<atMs>` and the host schedules it like any other wake. When it fires, the step runs again at the same visit, so `ctx.key` is the same. The outcome carries your `detail` and the `until` time. A `defer` that is not a duration (`"2 minutos"`) cannot park anything, so the step fails instead, with `code: 'action-failed'` and a `detail` that quotes the value; the handler has already run, so throwing would make every replay repeat it.
 
 **`spoke: true`** says the action itself sent something to the customer, a template through the channel for example. The framework then treats the turn as the assistant having spoken: `lastAssistantAt` is stamped and silence flows are armed. On a message turn, it also means another run's talk step does not speak (`code: 'another-reply'`): one answer per message.
 

package/docs/guides/branching.md

@@ -64,8 +64,8 @@ console.log(t2.messages.map((m) => m.text)); // ["Claro, vou chamar alguém da e
 
 `branches` is allowed on two step kinds:
 
-- A talk step that collects (`collect`, with or without a `prompt`). Both `when` and `if` branches work while it asks. A `prompt` step with no `collect` speaks once and moves on in the same turn, so its branches are only judged in the rare turn where it is still asking: the last step of an `onEnd: 'stay'` flow, or a turn where another run answered the customer first.
-- A timer `wait` step (`wait: '2d'`). Only `if` branches are judged there.
+- A talk step that collects (`collect`, with or without a `prompt`). Both `when` and `if` branches work while it asks. A `prompt` step with no `collect` speaks once and moves on in the same turn, so its branches are only judged in the rare turn where it is still asking: the talk step an `onEnd: 'stay'` flow stays on, or a turn where another run answered the customer first. On the step a run stays on, an `if` branch that leads to `'end'` or to a step the run has already been through is not taken: that path already ran, and the fact would still hold on every message. Write a restart there as a `when`.
+- A timer `wait` step (`wait: '2d'`). Only `if` branches are judged there; `validateFlow` rejects a `when` branch on a wait.
 
 `say`, `do`, `if` and `wait: { event }` steps have no branches. A code fork between them is an `if` step.
 
@@ -79,6 +79,8 @@ console.log(t2.messages.map((m) => m.text)); // ["Claro, vou chamar alguém da e
 
 If no branch holds, the step carries on: it speaks again with what is still pending, or completes when its fields are known.
 
+A suspended run that gets the conversation back in the middle of a turn, because the run that was asking finished without a word, is checked the same way before it speaks, but only its `if` branches: the model was not asked about its `when` branches this turn.
+
 **On a `wait` step**, the branches are judged only when the customer replies while the run is parked, which is also when `else` applies. The first `if` branch that holds wins over `else`. A `wait` with no `else` ignores the reply, branches included. When the timer fires, branches are not consulted: the run takes `then`, or `else` if the customer wrote after the wait was set. The outcome line reads `code: 'replied'` or `code: 'no-reply'`.
 
 ```ts

package/docs/guides/compaction.md

@@ -34,13 +34,13 @@ With `maxTokens: 2000` the turn compacts when the history is estimated at 1600 t
 
 | Field | Meaning | Default |
 |---|---|---|
-| `maxTokens` | the token budget for the history | required |
+| `maxTokens` | the token budget for the history; more than 0 | required |
 | `compactionThreshold` | compact when the estimate reaches this share of `maxTokens`; between 0.5 and 0.95 | `0.8` |
 | `preserveRecentCount` | the newest messages are never changed or removed; at least 2 | `4` |
 | `maxToolResultChars` | characters kept of a tool result before it is cut; more than 0 | `5000` |
 | `enabled` | `false` turns compaction off without removing the config | `true` when the config is present |
 
-A value out of range throws at construction, as a plain `Error`: `compactionThreshold must be between 0.5 and 0.95, got 2`, `preserveRecentCount must be >= 2, got 1`, `maxToolResultChars must be > 0, got 0`.
+A value out of range throws at construction, as a plain `Error` that names the value and the fix, for example `[CompactionEngine] compactionThreshold is 2: it must be between 0.5 and 0.95. Use 0.8 unless you measured otherwise.` The same goes for a `maxTokens` of 0 or less, a `preserveRecentCount` under 2 and a `maxToolResultChars` of 0 or less.
 
 ## When it runs
 

package/docs/guides/error-handling.md

@@ -76,7 +76,7 @@ The speak call phrases the reply. If the provider fails here, or answers with an
 | A spent balance with no stated reset | `provider-quota` | Ends `failed` |
 | The key was rejected or has no access to the model | `provider-auth` | Ends `failed` |
 | The prompt is past the model's context window | `provider-context` | Ends `failed` |
-| The provider refused the request, or the model does not exist | `provider-invalid` | Ends `failed` |
+| The provider refused the request, the model does not exist, or the model spent all of `maxTokens` thinking and never answered | `provider-invalid` | Ends `failed` |
 
 A failure that waits returns with an outcome `{ kind: "prompt" | "collect", status: "deferred", code, until }`, a `schedule[]` entry keyed `${runId}:${stepId}:${visit}:retry:${atMs}`, and `llmCalls` counting the call that failed. The backoff is 1 minute, then 5, 15, an hour, six hours (`RETRY_BACKOFF` in `src/core/Runner.ts`); the attempt number is the count of trailing `deferred` outcomes for that step on that run. A provider that stated a reset later than the next rung is woken at the reset instead. When the wake fires, the step runs again at the same visit, so its message carries the same key it would have carried the first time.
 
@@ -150,7 +150,7 @@ Most things that go wrong inside a turn become outcome lines, not exceptions:
 
 The full detail vocabulary is in [outcomes](../reference/outcomes.md).
 
-Two errors outside the four classes: a `compaction` option out of range throws a plain `Error` at construction (`compactionThreshold must be between 0.5 and 0.95, got 2`), and `PrismaStore` throws a `TypeError` when the client has no model by the given name.
+Two errors outside the four classes: a `compaction` option out of range throws a plain `Error` at construction (`[CompactionEngine] compactionThreshold is 2: it must be between 0.5 and 0.95. Use 0.8 unless you measured otherwise.`), and `PrismaStore` throws a `TypeError` when the client has no model by the given name. [Errors](../reference/errors.md) lists the other wiring errors thrown at construction.
 
 ## Catching by class
 

package/docs/guides/flow-control.md

@@ -144,14 +144,14 @@ Ends this run with `reason: 'flow'` and starts the other flow in the same turn.
 - has `hop` one higher than the parent. A chain deeper than 5 stops: the child is skipped with `code: 'hop-limit'`.
 - repeats by default (`'always'`), so a flow may be chained into many times; its claim carries the parent's step key.
 
-`flow` is a template: `{{input.flowId}}` resolves against the run's input and context. A flow id that does not exist lands in `skipped[]` with `code: 'flow-gone'`; a child flow with a live run for the same anchor is skipped with `code: 'already-running'`. This is how one flow hands the conversation to another: the last step of a qualifying flow can `then: { flow: 'agendamento' }`.
+`flow` is a template: `{{input.flowId}}` resolves against the run's input and context. A literal flow id the agent does not have logs a warning when the agent is built and is skipped at run time with `code: 'flow-gone'`; a template that resolves to no flow lands in `skipped[]` with `code: 'flow-gone'`; a child flow with a live run for the same anchor is skipped with `code: 'already-running'`. This is how one flow hands the conversation to another: the last step of a qualifying flow can `then: { flow: 'agendamento' }`.
 
 ## `onEnd`: after the last step
 
 | `onEnd` | What happens | `ended[].reason` |
 |---|---|---|
 | `'end'` (default) | the run ends; the session is idle | `'end'` |
-| `'stay'` | the run stays at its last step and runs it again on the next message; each repetition mints a new key | none: the run does not end |
+| `'stay'` | the run goes back to the last talk step it took and answers every later message from there, with a new key each time; the steps after that talk step do not run again | none: the run does not end |
 | `'reset'` | the run ends and a fresh run of the same flow starts at the first step, data kept, one hop deeper | `'reset'` |
 
 ```ts
@@ -169,6 +169,8 @@ const faq = f.flow({
 });
 ```
 
+The talk step does not have to be the last step, and it does not need anything left to collect. A flow that asks for the name, tells the team, and then keeps talking is `steps: [{ id: "quem", collect: ["nome"] }, { id: "avisa", do: "notify" }]` with `onEnd: "stay"`: `avisa` runs once, then `quem` answers every message, even though the name is known. A `say` or a `do` that returned `spoke: true` on the way to the end counts as the answer to that message, so the step waits for the next one. A flow with no talk step ends, as with `'end'`.
+
 `'reset'` is a chain into the same flow, so it costs a hop: a flow with no talk step that resets forever stops at the hop cap instead of spinning.
 
 ## `while`: the run's premise

package/docs/guides/persistence.md

@@ -94,7 +94,7 @@ console.log(outbox[0]?.text, (await store.load("s1"))?.version); // "…", 1
 
 Three attempts is enough: a fourth conflict means two workers are firing on the same session, which is a queue problem, not a race.
 
-Three things happen after the save and never before it: messages go out (honouring `afterMs`, keyed by `key`), `schedule[]` entries go into your queue with `jobId = key`, and at fire time you call `turn({ wake: key })` through this same loop. `changed: false` means the input changed nothing (a stale wake, a repeated message id): skip the save and the send.
+Three things happen after the save and never before it: messages go out (honouring `afterMs`, keyed by `key`), `schedule[]` entries go into your queue with the key in the payload and `encodeURIComponent(key)` as the job id (BullMQ refuses a `:` in a custom id, and every key has one), and at fire time you call `turn({ wake: key })` through this same loop. `changed: false` means the input changed nothing (a stale wake, a repeated message id): skip the save and the send.
 
 ## What a row holds
 
@@ -156,7 +156,7 @@ const viaRedis = new RedisStore({ redis, keyPrefix: "agent:", sessionTTL: 7 * 24
 const viaMongo = new MongoStore({ client: mongo, databaseName: "app" });
 const sqlite = new SQLiteStore({ db });
 await sqlite.initialize();
-const search = new OpenSearchStore(opensearch, { refresh: "wait_for" });
+const search = new OpenSearchStore({ client: opensearch, refresh: "wait_for" });
 await search.initialize();
 
 console.log([postgres, viaPrisma, viaRedis, viaMongo, sqlite, search].length); // 6

package/docs/guides/testing.md

@@ -218,7 +218,7 @@ 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 stores as `jobId` and what you pass back as `wake`. The silence key is `silence:${flowId}:${sessionId}:${ms}`; a timer wait's key is `${runId}:${stepId}:${atMs}`.
+- `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

package/docs/guides/triggers.md

@@ -181,7 +181,7 @@ How it works, in order:
 
 1. The assistant speaks: a talk step, a `say`, or an action that returns `spoke: true`. The turn stamps `session.lastAssistantAt`.
 2. For every silence flow whose `if` holds and whose `repeat` allows, the turn puts a wake in `schedule[]`: key `silence:<flowId>:<sessionId>:<lastAssistantAtMs>`, `at` = that time plus the duration. `replaces` names the previous silence key of the same flow so the host can drop the old job. Dropping it is best effort; a stale wake is harmless.
-3. The host enqueues the wake with `jobId = key` and calls `turn({ wake: key })` when it fires.
+3. The host enqueues the wake with the key in the payload and `encodeURIComponent(key)` as the job id, because BullMQ refuses a `:` in a custom id, and calls `turn({ wake: key })` when it fires.
 4. The wake is honoured only while the session still shows that silence: the assistant's last message is still the same one and the customer has not written since. Otherwise the turn ends with `code: 'silence-broken'` and `changed: false`.
 5. The run starts, takes the floor and speaks first. A talk step costs one model call; the prompt tells the model there is no new message from the customer.
 
@@ -229,7 +229,7 @@ console.log(r.outcomes[0]?.code); // "awaiting-trigger"
 
 - `turn({ event, payload, key })` publishes it. The payload becomes the run's `input`: `{{input.stageId}}` in templates, `ctx.input` in actions, `input` in the trigger's `if`. `input` is typed `unknown` there; narrow it before you read it.
 - `after: '1h'` parks the new run before its first step. The wake key is `<runId>:start:<atMs>`; the outcome line reads `code: 'awaiting-trigger'`. If the same event arrives again for the same flow and anchor while the run is still parked there, the parked run is replaced (`ended[].reason: 'replaced'`). Any other live run makes the new one skip with `code: 'already-running'`.
-- `businessHours: true` moves `after` forward to the next working hour.
+- `businessHours: true` moves `after` forward to the next working hour. With no `after`, it holds an event that arrives after hours until the next working hour, and starts at once inside them.
 - Default `repeat: 'always'`: every event with a new `key` starts a run. The same `key` twice is skipped with `code: 'already-claimed'`, so publishing an event again is safe.
 - Zero model calls, unless the run reaches a talk step: then the assistant speaks first, one call.
 - An event may carry a `direction`, which stamps the session as the customer or the assistant speaking. See [Actions and events](actions-and-events.md).
@@ -298,7 +298,7 @@ Inside a session, a flow has at most one live run per anchor. A trigger that fir
 
 ## `businessHours`
 
-Timers can wait for working hours. Give the agent a `businessHours` function and set `businessHours: true` where it should apply: a silence trigger, an event's `after`, a `wait` step.
+Timers can wait for working hours. Give the agent a `businessHours` function and set `businessHours: true` where it should apply: a silence trigger, an event trigger (its `after`, or the start itself when it has none), a `wait` step.
 
 ```ts
 import { falai, GeminiProvider } from "@falai/agent";

package/docs/migration/v3-to-v4.md

@@ -65,12 +65,12 @@ async function onMessage(sessionId: string, context: unknown, history: History,
   if (r.changed) {
     await store.save(r.session, session?.version ?? 0);   // throws SessionConflictError when another turn saved first: drop this result and run the turn again
     for (const m of r.messages) await send(m.text, { after: m.afterMs, key: m.key });
-    for (const s of r.schedule) await queue.add({ jobId: s.key, at: s.at });
+    for (const s of r.schedule) await queue.add({ jobId: encodeURIComponent(s.key), at: s.at });   // BullMQ refuses a ':' in a custom id
   }
 }
 ```
 
-Input kinds, one of: `{ message, id?, at? }`, `{ wake }` (a key from `schedule[]`), `{ event, payload?, key }`, `{ start: { flow, input?, key } }`. Pass `context` and `history` on every call, wakes included. Pass `silenced: 'reason'` whenever the assistant must not speak (a human owns the conversation, the channel window is closed, no credits): `do` steps still run, zero model calls, and nothing is said. A run that was already asking stays asking and speaks on the first turn that is not silenced; a run that reaches a new talk or `say` step ends, and the step's outcome is `code: 'silenced'` with your reason in `detail`. Pass `silenced: { reason, understand: true }` to keep the understand call (extraction, mentions) while muting speech.
+Input kinds, one of: `{ message, id?, at? }`, `{ wake }` (a key from `schedule[]`), `{ event, payload?, key }`, `{ start: { flow, input?, key } }`. Pass `context` and `history` on every call, wakes included. Pass `silenced: 'reason'` whenever the assistant must not speak (a human owns the conversation, the channel window is closed, no credits): `do` steps still run, zero model calls, and nothing is said. A run that was already asking stays asking and speaks on the first turn that is not silenced; a run that reaches a new talk or `say` step ends, and the step's outcome is `code: 'silenced'` with your reason in `detail`. Pass `silenced: { reason, understand: true }` to keep the understand call (extraction, mentions) while muting speech. Pass `silenced: { reason, skip: true }` when the gate only stops messages (a closed channel window): the talk or `say` step is skipped and the run goes on to its `then`.
 
 `respondStream()` is `turnStream()`: yields `{ delta }` chunks and one `{ done: true, result }`.
 
@@ -147,7 +147,7 @@ const triagem = f.flow({
     { id: 'aviso', do: 'notify', with: { recipient: 'owner', message: 'Lead: {{data.nome}} ({{data.empresa}})' } },
     { id: 'tchau', say: 'Um vendedor continua daqui.' },
   ],
-  onEnd: 'end',   // or 'stay' (repeat the last step) or 'reset' (first step, data kept)
+  onEnd: 'end',   // or 'stay' (the last talk step answers every later message) or 'reset' (first step, data kept)
 });
 ```
 
@@ -206,7 +206,7 @@ Per-field wording lives on the field (`ask`); a step may override it (`ask: { no
 type Next = string /* step id or 'end' */ | { step: string; clear?: string[] } | { flow: string; input?: unknown };
 ```
 
-Branches stay on talk steps, judged while the step is asking: `{ when: '...', then }` for the model, `{ if: pred, then }` for code. A `wait` step takes `if` branches only, judged when the customer replies, and only when the step also has an `else`; a `when` branch on a wait never fires. There is no standalone AI-judged step: the model forks only where fresh customer text exists.
+Branches stay on talk steps, judged while the step is asking: `{ when: '...', then }` for the model, `{ if: pred, then }` for code. A `wait` step takes `if` branches only, judged when the customer replies, and only when the step also has an `else`; `validateFlow` rejects a `when` branch on a wait, since nothing would ever judge it. There is no standalone AI-judged step: the model forks only where fresh customer text exists.
 
 ```ts fragment
 // ─── v3 ───
@@ -303,7 +303,7 @@ const retomar = f.flow({
 });
 ```
 
-- `wait: '3s'` (10 s or less, and the next step is a `say` or a talk step) becomes `afterMs` on that message in the same turn; every other wait parks the run (stops it until a wake) and puts `{ key, at }` in `schedule[]`. Enqueue the wake with `jobId = key` and call `turn({ wake: key })` when it fires. The framework never cancels a wake itself: a stale one is ignored (`changed: false`). A re-armed silence wake names the one it supersedes in `replaces`; removing that job is optional.
+- `wait: '3s'` (10 s or less, and the next step is a `say` or a talk step) becomes `afterMs` on that message in the same turn; every other wait parks the run (stops it until a wake) and puts `{ key, at }` in `schedule[]`. Enqueue the wake with `encodeURIComponent(key)` as the job id (BullMQ refuses a `:` in a custom id) and call `turn({ wake: key })` when it fires. The framework never cancels a wake itself: a stale one is ignored (`changed: false`). A re-armed silence wake names the one it supersedes in `replaces`; removing that job is optional.
 - `on: [{ event: 'stage_entered', after: '1h' }]` starts a run when your code calls `turn({ event, payload, key })`. Declare events with `f.event<Payload>({ direction? })`: `inbound` counts as the customer speaking, `outbound` as the assistant.
 - `wait: { event: 'meeting_booked', upTo: '7d' }` parks until the event arrives.
 - Runs inside a session are concurrent; at most one is asking a question. A timer-started talk step suspends the current asker and hands the floor back when it is done.
@@ -349,7 +349,7 @@ interface Store<D> {
 }
 ```
 
-The seven adapters survive as `Store` implementations and take the same client you passed before: `MemoryStore`, `PostgresStore`, `PrismaStore`, `RedisStore`, `MongoStore`, `SQLiteStore`, `OpenSearchStore`. They persist the v4 blob and a version, nothing else; message repositories, `SessionRepository`, `status`, `currentFlow` / `currentStep` columns, `PersistenceManager`, `autoSave`, `schemaVersion` and `restoreSession` are gone. The framework never calls a store: you `load`, `turn`, `save`.
+The seven adapters survive as `Store` implementations and take the same client you passed before: `MemoryStore`, `PostgresStore`, `PrismaStore`, `RedisStore`, `MongoStore`, `SQLiteStore`, `OpenSearchStore`. Each takes one options object with the client in it, so OpenSearch's becomes `new OpenSearchStore({ client, ...options })`. They persist the v4 blob and a version, nothing else; message repositories, `SessionRepository`, `status`, `currentFlow` / `currentStep` columns, `PersistenceManager`, `autoSave`, `schemaVersion` and `restoreSession` are gone. The framework never calls a store: you `load`, `turn`, `save`.
 
 **Use a fresh table.** The default names are the 3.x ones (`agent_sessions`, `agent:` prefix), so pass a new one (`tables.sessions` on Postgres, SQLite and Prisma, `collections.sessions` on Mongo, `indices.sessions` on OpenSearch, `keyPrefix` on Redis) or drop the old table first; `initialize()` (Postgres, SQLite, OpenSearch) only creates the table or index when it is missing, and does nothing while one of that name exists. A v4 store read against a live 3.x row fails loudly: Redis, Mongo, Prisma and OpenSearch throw `InvalidSessionError` (no `blob`), Postgres and SQLite fail on the missing `blob` column. Create the new table, then migrate rows on first load as §10 shows.
 
@@ -386,6 +386,7 @@ const session = migrateSession(rowBlob, {
 - `version` is 0: the session has no row in the v4 table yet, so your usual `store.save(session, session.version)` is the insert.
 - `pendingDirective` is dropped.
 - A blob that is neither v4 nor a recognisable 3.x state throws `InvalidSessionError`; a corrupt row can no longer become a fresh conversation silently.
+- 3.x did not record when the assistant last spoke, so a lifted session has no `lastAssistantAt` and arms no silence follow-up until the assistant speaks again. At cutover, set `session.lastAssistantAt` and `session.lastUserAt` from your messages table, save, and enqueue `agent.pendingWakes({ session, context })`: a conversation that was quiet at cutover then gets its follow-up on time.
 
 Add a test that loads one real (anonymised) row per product and asserts the run's `stepId` and the carried claims.
 
@@ -441,7 +442,7 @@ Then, in this order:
 1. Convert stored flows and signal rules to `FlowSpec` rows. Keep talk-step ids; give each migrated signal flow `id = signal key`.
 2. Register your actions, events and conditions on the agent.
 3. Replace the `respond` call site with load → `turn` → save + messages + schedules in one transaction.
-4. Wire wakes (`jobId = key`, `turn({ wake })` at fire time) and host events.
+4. Wire wakes (job id `encodeURIComponent(key)`, `turn({ wake })` at fire time) and host events. At cutover, enqueue `agent.pendingWakes()` for every lifted session that was quiet.
 5. Put `migrateSession` in your deserializer and let it throw on garbage.
 6. Delete the automation engine, the follow-up sweep and the second composer.
 

package/docs/reference/actions-events-conditions.md

@@ -220,7 +220,7 @@ An event turn never spends an understand call. It costs one speak call (plus too
 
 1. **Direction.** `'inbound'` sets `lastUserAt` to now and resolves reply waits: every run parked on a timer `wait` that has an `else` resumes with `code: 'replied'` and follows a matching `if` branch's `then`, else `else`. `'outbound'` sets `lastAssistantAt` to now, which re-arms `silence` triggers at the end of the turn.
 2. **Waiting runs.** Every run parked on `wait: { event: name }` for this name resumes with `code: 'event-arrived'` and follows `then`. The first one to resume takes the floor for this turn.
-3. **Triggers.** Every flow with `on: [{ event: name }]` goes through the start order: trigger `if`, `repeat` (default `'always'` for events), the hop cap, one live run per flow and anchor. With `after`, the run parks first (`code: 'awaiting-trigger'`, wake key `${runId}:start:${atMs}`) and enters its first step when the wake fires; `businessHours: true` snaps that time forward through the agent's `businessHours` function.
+3. **Triggers.** Every flow with `on: [{ event: name }]` goes through the start order: trigger `if`, `repeat` (default `'always'` for events), the hop cap, one live run per flow and anchor. With `after`, the run parks first (`code: 'awaiting-trigger'`, wake key `${runId}:start:${atMs}`) and enters its first step when the wake fires; `businessHours: true` snaps that time forward through the agent's `businessHours` function. With `businessHours: true` and no `after`, an event that arrives outside working hours parks the run the same way until the next working moment.
 
 `wait: { event, upTo }` in a step parks the run for at most `upTo` (default `'30d'`, from `src/core/Runner.ts`). If the event never comes, the line carries `code: 'no-event'` and the run follows `else`, or ends when there is none.
 

package/docs/reference/agent.md

@@ -86,7 +86,7 @@ class Agent<C, D> {
 
 `Idle` is `{ prompt: Template; tools?: string[]; instructions?: Instruction[] } | 'silent'`. Its `tools` list must name tools registered on the agent.
 
-`AgentCompactionConfig` is `{ maxTokens: number; compactionThreshold?: number; preserveRecentCount?: number; maxToolResultChars?: number; enabled?: boolean }`. Defaults: `compactionThreshold` `0.8` — compaction runs when the history passes 80% of `maxTokens` (allowed 0.5 to 0.95); keep the 4 most recent messages (at least 2); cut each tool result at 5000 characters (more than 0); `enabled: true`. Values outside those ranges throw at construction.
+`AgentCompactionConfig` is `{ maxTokens: number; compactionThreshold?: number; preserveRecentCount?: number; maxToolResultChars?: number; enabled?: boolean }`. `maxTokens` must be more than 0. Defaults: `compactionThreshold` `0.8` — compaction runs when the history passes 80% of `maxTokens` (allowed 0.5 to 0.95); keep the 4 most recent messages (at least 2); cut each tool result at 5000 characters (more than 0); `enabled: true`. Values outside those ranges throw at construction.
 
 ## turn()
 
@@ -94,6 +94,10 @@ class Agent<C, D> {
 
 `turnStream(input)` runs the same turn and yields `{ delta: string }` chunks while the model phrases the reply, then one `{ done: true, result: TurnResult }`. When nobody speaks, only the last chunk comes. See [Streaming](../guides/streaming.md).
 
+## pendingWakes()
+
+`pendingWakes({ session, context, anchors?, claims? })` returns the `ScheduleEntry[]` a saved session is waiting on: each parked run's wake, and each silence flow's counted from `session.lastAssistantAt`, none once the customer wrote after it. The trigger's `if` and `repeat` are judged on the `context`, `anchors` and `claims` you pass, as in a turn. It changes nothing and spends no model call; the entries carry no `replaces`. Use it when a queue lost its jobs, and after `migrateSession`, since a 3.x blob has no `lastAssistantAt` and so no silence wake until the assistant speaks again.
+
 ## TurnInput
 
 Every input carries the common fields, plus exactly one of the four kinds.
@@ -122,10 +126,10 @@ Every input carries the common fields, plus exactly one of the four kinds.
 ### Silenced
 
 ```ts fragment
-type Silenced = string | { reason: string; understand?: boolean };
+type Silenced = string | { reason: string; understand?: boolean; skip?: boolean };
 ```
 
-A string closes the gate: `do` steps still run, nothing is phrased, zero model calls. A talk or `say` step reached while the gate is closed ends its run with `code: 'silenced'` (`detail` = your reason); a run that was already asking stays asking and speaks when the gate opens. `{ reason, understand: true }` keeps the understand call on, so routing, mentions and extraction still happen while the assistant stays quiet. Predicates see the reason as `ctx.silenced`.
+A string closes the gate: `do` steps still run, nothing is phrased, zero model calls. A talk or `say` step reached while the gate is closed ends its run with `code: 'silenced'` (`detail` = your reason); a run that was already asking stays asking and speaks when the gate opens. `{ reason, understand: true }` keeps the understand call on, so routing, mentions and extraction still happen while the assistant stays quiet. `{ reason, skip: true }` is for a gate that only stops messages, such as a closed channel window: the talk or `say` step is skipped with the same `code: 'silenced'` and the run takes its `then`. Predicates see the reason as `ctx.silenced`.
 
 ## TurnResult
 
@@ -134,7 +138,7 @@ A string closes the gate: `do` steps still run, nothing is phrased, zero model c
 | `session` | `Session<D>` | The session after this turn. `version` is unchanged; the host saves it with the version it loaded and the store bumps it. |
 | `changed` | `boolean` | `false` means save nothing and send nothing: the input was ignored or nothing moved. |
 | `messages` | `OutboundMessage[]` | What to send, in order. |
-| `schedule` | `ScheduleEntry[]` | Wakes to enqueue with `jobId = key`. At fire time call `turn({ wake: key })`. |
+| `schedule` | `ScheduleEntry[]` | Wakes to enqueue, with `encodeURIComponent(key)` as the job id. At fire time call `turn({ wake: key })`. |
 | `outcomes` | `StepOutcome[]` | One line per step this turn, for your execution log. See [Outcomes](outcomes.md). |
 | `started` | `Array<{ runId; flowId; anchor; dedupeKey }>` | Runs that started this turn. |
 | `ended` | `Array<Run & { reason: EndReason }>` | Runs that ended, with the run's last state and why: `'end'`, `'flow'`, `'reset'`, `'skipped'`, `'failed'` or `'replaced'`. |
@@ -183,7 +187,7 @@ if (r.usage) {
 
 | Field | Type | Meaning |
 |---|---|---|
-| `key` | `string` | The wake key. Use it as the job id and pass it back as `turn({ wake: key })`. |
+| `key` | `string` | The wake key. Pass it back as `turn({ wake: key })`. As a queue job id, encode it: BullMQ refuses a custom id with a `:` in it, and every key has one. |
 | `at` | `Date` | When to fire. |
 | `replaces` | `string` | An earlier wake this one supersedes. Removing it is best effort; a stale wake is ignored anyway. |
 

package/docs/reference/branches.md

@@ -34,7 +34,7 @@ type Branch<C = unknown, D = unknown> = { then: Next<D> } & (
 3. The run leaves the step with the outcome `code: 'branch'` (kind `prompt` or `collect`, status `ok`, `next` naming the target) and follows `then` in the same turn. Fields the understand call extracted from the same message are written first, so `then` may land on a step that is already satisfied.
 4. When no branch holds, the step continues as usual: pending fields are harvested and the step speaks again.
 
-A `when` branch costs the understand call; when it is the only thing to judge, that is one model call the turn would not otherwise spend. An `if` branch is judged on every message turn even when no understand call happens.
+A `when` branch costs the understand call; when it is the only thing to judge, that is one model call the turn would not otherwise spend. An `if` branch is judged on every message turn even when no understand call happens. A suspended run that returns to asking during the turn, because the asker ended or moved on without a word, has its `if` branches judged before its step speaks; its `when` branches were not in the understand call, so they wait for the next message.
 
 **On a wait step.** Only `if` branches are judged, and only when the customer writes before the time passes and the step has `else`. The first `if` branch that holds replaces `else` as the target (outcome `code: 'replied'`). A `when` branch on a wait step is never asked, because a reply to a wait step does not reach the understand call. When the wake fires, branches are not consulted: the run follows `then`, or `else` when the customer wrote after the wait was set.
 

package/docs/reference/errors.md

@@ -59,7 +59,7 @@ From `src/types/errors.ts`, `src/core/Migrate.ts` and `@providerkit/core`.
 | Class | Thrown by | When | What to do |
 |-------|-----------|------|------------|
 | `FlowConfigurationError` | `f.agent()` / `new Agent()`, `validateFlow`, `fromSpec` | A flow cannot run as written: a flow id or step id declared twice; a step with no id, or with the reserved id `"end"`; an unknown field in `collect` / `ask` / `clearOnStart`; an unknown action, event, condition or tool; a `then` pointing at a step that does not exist; an action `with` missing a required parameter; a duration that does not parse; a talk step with neither `prompt` nor `collect`. Also thrown at run time when a JSON predicate names a condition the agent does not have. | Fix the flow. It is a bug in the flow or the registries, never something to retry. |
-| `SessionConflictError` | every `Store.save` | The stored version is not `expectedVersion`: another turn saved first, or a `save(…, 0)` found a row. | Load the session again and replay the same input. Nothing was sent, so nothing is duplicated. |
+| `SessionConflictError` | every `Store.save` | The stored version is not `expectedVersion`: another turn saved first, a `save(…, 0)` found a row, or the row was deleted or expired after it was loaded (`actualVersion` is `undefined`). | Load the session again and replay the same input. Nothing was sent, so nothing is duplicated. |
 | `InvalidSessionError` | every `Store.load`, `assertSession`, `migrateSession` | A stored row is not a v4 session and not a recognisable 3.x one: wrong `v`, an `id` that does not match the row, a missing `data`, a run with a bad `status`, text that is not JSON. | Repair or delete the row. The framework never replaces a bad row with a fresh conversation, because that would re-ask every field and re-fire every once-flow. |
 | `ProviderError` | the built-in providers, `FallbackAiProvider` | A model call failed after the provider's own retries, backup models and fallbacks. `kind` says what would fix it. | Match on `kind` (table below). |
 
@@ -80,8 +80,8 @@ The bracket names the class, the text before the colon says what is wrong and wh
 [FlowConfigurationError] flow "triagem": has no steps list. Write steps as a list, even an empty one.
 [FlowConfigurationError] flow "a" is declared twice: flow ids must be unique. Rename one of them.
 [FlowConfigurationError] idle: unknown tool "buscar_preco". Register it in the agent's tools or fix the name.
-[SessionConflictError] Session "s1" was modified concurrently: expected version 1, found 2. Reload the session and retry the operation.
-[SessionConflictError] Session "s1" was modified concurrently: expected version 0, found none. Reload the session and retry the operation.
+[SessionConflictError] Session "s1" was modified concurrently: expected version 3, found 4. Reload the session and retry the operation.
+[SessionConflictError] Session "s1" is gone from the store: it was at version 3 and has since been deleted or expired. Load it again; a load that finds nothing starts a new conversation.
 [InvalidSessionError] stored session "s1" is unreadable: v is 3, expected 4. Repair or delete the row; it is never replaced by a fresh conversation.
 [InvalidSessionError] stored session "s1" is unreadable: expected an object, got "garbage". Repair or delete the row; it is never replaced by a fresh conversation.
 [InvalidSessionError] stored session "s1" is unreadable: data is missing, expected an object; not a 3.x session either. Repair or delete the row; it is never replaced by a fresh conversation.
@@ -96,9 +96,9 @@ Named by what fixes them, from `@providerkit/core`.
 | `kind` | Meaning | Retry? |
 |--------|---------|--------|
 | `aborted` | Your own `AbortSignal` fired. | Never. |
-| `timeout` | The stream stayed silent past `retryConfig.timeout` (default 60 s), or the provider sent 408. | Yes. |
-| `network` | The request never reached the provider: socket, DNS, proxy. | Yes. |
-| `overload` | Theirs and temporary: a 5xx, Anthropic's 529, "overloaded". | Yes, and worth a different model. |
+| `timeout` | The response went silent past `retryConfig.timeout` (default 60 s, keep-alives count as life), sent no chunk for 5 minutes, or the provider sent 408. | Yes. |
+| `network` | The request never reached the provider (socket, DNS, proxy), or the stream ended before the provider's end signal. | Yes. |
+| `overload` | Theirs and temporary: a 5xx, Anthropic's 529, "overloaded", or a turn that ended with no text and no tool call. | Yes, and worth a different model. |
 | `rate` | 429 per-minute throttle. | Wait `retryAfterMs`, or rotate key or model. |
 | `quota` | Balance or usage window exhausted. | Waiting minutes will not fix it. |
 | `entitlement` | The plan never included this API. | No; neither a new key nor a top-up fixes it. |
@@ -106,7 +106,7 @@ Named by what fixes them, from `@providerkit/core`.
 | `model` | The model id does not exist or is not served here. | No; the built-in providers do try the next `backupModels` entry. |
 | `context` | The prompt outgrew the context window. | No; send less. Compaction is the framework's answer. |
 | `content` | Safety filter or refusal. | No. |
-| `invalid` | Any other 4xx: a bug in what was sent. | No. |
+| `invalid` | Any other 4xx: a bug in what was sent. Also a turn that spent its whole `maxTokens` thinking and never answered: raise `config.maxTokens` or lower `config.effort`. | No. |
 | `unknown` | Nothing above matched. | No. |
 
 `isTransient` is true for `timeout`, `network`, `overload` and `rate`. `isBackupEligible` is what the provider uses to decide whether to try the next backup model.
@@ -124,11 +124,13 @@ The same `ProviderError` means two different things depending on which of the tw
 
 A few throws are plain `Error` or `TypeError`. One happens at run time: a reply that parses to a blank message with no tool calls throws `Error: No response from <provider>` out of `generateMessage`, after the provider's retries and backup models have run. A speak call swallows it and defers the step; an understand call hands it to you, so catch `Error`, not only `ProviderError`. The rest are wiring bugs at construction:
 
-- A provider built without a key or model: `Gemini API key is required`, `Model is required. Example: 'gpt-5.6' or 'gpt-5.5'`.
+- A provider built without a key or model: `[GeminiProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.GEMINI_API_KEY } and check the variable is set.`, `[OpenAIProvider] model is empty: there is no default. Pass one, e.g. { model: "gpt-5.6" }.`
 - `createOpenAICompatibleProvider` without `name`, `baseURL`, `apiKey` or `model`.
 - `FallbackAiProvider` with an empty `providers` list.
 - `PrismaStore` whose client has no delegate for the model: `[TypeError] PrismaStore cannot use model "agentSession": …`.
-- `compaction` options out of range (`compactionThreshold` outside 0.5–0.95, `preserveRecentCount` below 2, `maxToolResultChars` at or below 0).
+- `compaction` options out of range (`maxTokens` at or below 0, `compactionThreshold` outside 0.5–0.95, `preserveRecentCount` below 2, `maxToolResultChars` at or below 0): `[CompactionEngine] compactionThreshold is 1.2: it must be between 0.5 and 0.95. Use 0.8 unless you measured otherwise.`
+
+Each follows the same `[Class] what: why. how to fix.` shape as the package classes; only the class is plain `Error`.
 
 ## Example
 
@@ -147,7 +149,7 @@ import type { AiProvider, DataOf, Session, TurnResult } from "@falai/agent";
 
 declare const provider: AiProvider;
 declare function send(text: string, key: string, afterMs: number): Promise<void>;
-declare function enqueue(jobId: string, at: Date): Promise<void>;
+declare function enqueue(jobId: string, at: Date, payload: { sessionId: string; key: string }): Promise<void>;
 declare function sleep(ms: number): Promise<void>;
 
 const f = falai().fields({
@@ -213,7 +215,8 @@ async function handle(sessionId: string, text: string, id: string): Promise<Turn
   }
 
   for (const m of result.messages) await send(m.text, m.key, m.afterMs);
-  for (const s of result.schedule) await enqueue(s.key, s.at);
+  // The key rides in the payload for turn({ wake: key }); BullMQ refuses a ":" in a custom id, so the job id is encoded.
+  for (const s of result.schedule) await enqueue(encodeURIComponent(s.key), s.at, { sessionId, key: s.key });
   return result;
 }
 

package/docs/reference/fields.md

@@ -21,6 +21,7 @@ interface ScalarDef<T extends ScalarType = ScalarType> {
 }
 
 interface FieldDef<T extends ScalarType = ScalarType> extends ScalarDef<T> {
+  label?: string;
   ask?: string;
   extract?: "anywhere" | "asked";
 }
@@ -37,6 +38,7 @@ type DataOf<T extends { fields: FieldDefs }> = InferData<T["fields"]>;
 |---|---|---|---|
 | `type` | `ScalarType` | required | `'string'`, `'number'`, `'integer'` or `'boolean'`. |
 | `enum` | `readonly (string \| number)[]` | none | The allowed values. A value outside the list is dropped (`code: 'not-in-enum'`). In the data type the field becomes the literal union. |
+| `label` | `string` | none | The name a person reads, in an editor or next to a collected value. Never sent to the model. |
 | `description` | `string` | none | What the field is. Sent to the model with the field's type and options. |
 | `ask` | `string` | none | How the model should ask for it. Sent to the speak call as "How to ask" while the field is pending. A talk step's own `ask` overrides it. A template: `{{data.x}}` and `{{context.x}}` are filled in. |
 | `extract` | `'anywhere' \| 'asked'` | `'anywhere'` for string, number and integer; `'asked'` for boolean | Where a value may be taken from. `'anywhere'`: any message from the customer, whether or not the field was asked. `'asked'`: only the reply to the step that lists the field, so a stray "sim" never confirms anything. |
@@ -55,7 +57,7 @@ Properties are readonly — `fields()` takes the definitions as a `const` type,
 
 **Known.** A field is known when its value is not `undefined`, `null` or `''`. Known fields are never asked again and never re-extracted; both calls list them under "Already known".
 
-**Which call extracts what.** The understand call, on a message turn, extracts every unknown `'anywhere'` field named in a `collect` of the flow holding the floor and of every eligible message flow, in one envelope. The speak call extracts the pending fields of the step that speaks, `'asked'` ones included, in the same call that phrases the reply. Tools write `data` and actions call `ctx.set()`; those values are written as given, with no check.
+**Which call extracts what.** The understand call, on a message turn, extracts every unknown `'anywhere'` field that the flow holding the floor or an eligible message flow lists, in the flow's own `collect` or a talk step's, in one envelope. With nobody on the floor, the catch-all's fields are read too. The speak call extracts the pending fields of the step that speaks, `'asked'` ones included, in the same call that phrases the reply. Tools write `data` and actions call `ctx.set()`; those values are written as given, with no check.
 
 **Coercion.** A raw value from the model goes through `coerceField(def, raw)` before it is written:
 
@@ -68,9 +70,9 @@ Properties are readonly — `fields()` takes the definitions as a `const` type,
 
 Anything else is dropped with the outcome line `code: 'bad-value'`. A value outside `enum` is dropped with `code: 'not-in-enum'`. A value for a slug that is not a field is dropped with `code: 'unknown-field'`. Dropped values leave a `collect` outcome with status `skipped` and no run id; the field stays pending and is asked again.
 
-**What reaches the provider.** `toWireSchema(defs)` turns definitions into the JSON schema the model must fill: a closed object (`additionalProperties: false`) with one property per field carrying `type`, `description` and `enum`, and nothing else. `ask` and `extract` are stripped; they steer the framework, not the schema. In the envelope style used by both calls every property is required and nullable (`type: [type, 'null']`), so the model answers `null` for what the customer did not give. The prompt describes each field once more in words (`nome (string) [a | b]: description`) and, in the speak call, adds the pending field's "How to ask".
+**What reaches the provider.** `toWireSchema(defs)` turns definitions into the JSON schema the model must fill: a closed object (`additionalProperties: false`) with one property per field carrying `type`, `description` and `enum`, and nothing else. `label`, `ask` and `extract` are stripped; they are for people and the framework, not the schema. In the envelope style used by both calls every property is required and nullable (`type: [type, 'null']`), so the model answers `null` for what the customer did not give. The prompt describes each field once more in words (`nome (string) [a | b]: description`) and, in the speak call, adds the pending field's "How to ask".
 
-**Clearing.** `{ step, clear: ['x'] }` on a `then`/`else`/branch and `clearOnStart` on a flow delete the field from `session.data`, so the next step that collects it asks again. `maxAsks` on a talk step (default 3) is the other way a field stops being pending: it is skipped for that run with `code: 'max-asks'`, the field in `detail`.
+**Clearing.** `{ step, clear: ['x'] }` on a `then`/`else`/branch and `clearOnStart` on a flow delete the field from `session.data`, so the next step that collects it asks again. `{ step, clear }` also resets how many times the run asked it. `maxAsks` on a talk step (default 3) is the other way a field stops being pending: it is skipped for that run with `code: 'max-asks'`, the field in `detail`.
 
 **Action parameters** use the sibling type `ParamDef`: a `ScalarDef` plus `optional?: true`, or `{ type: 'array', items: ScalarDef }`. `InferParams<P>` gives the `with` shape. They share `toWireSchema` and the same strictness at construction. See [Actions, events and conditions](actions-events-conditions.md).
 

package/docs/reference/flow-spec.md

@@ -23,6 +23,7 @@ interface FlowSpec {
   on?: TriggerSpec[];
   anchor?: string;
   while?: ConditionSpec;
+  collect?: string[];
   clearOnStart?: string[];
   steps: StepSpec[];
   onEnd?: "end" | "stay" | "reset";
@@ -33,7 +34,7 @@ interface FlowSpec {
 type StepSpec = StepBase &
   (
     | { kind: "prompt"; prompt: Template; ask?; maxAsks?; branches?: BranchSpec[]; tools?; instructions?: InstructionSpec[] }
-    | { kind: "collect"; collect: string[]; prompt?: Template; ask?; maxAsks?; branches?: BranchSpec[]; tools?; instructions?: InstructionSpec[] }
+    | { kind: "collect"; collect: string[]; prompt?: Template; question?: Template; ask?; maxAsks?; branches?: BranchSpec[]; tools?; instructions?: InstructionSpec[] }
     | { kind: "say"; say: Template; media?: { slug: string }; once?: boolean }
     | { kind: "do"; do: string; with?: Record<string, unknown>; onFail?: Next }
     | { kind: "wait"; wait: Duration; businessHours?: boolean; else?: Next; branches?: BranchSpec[] }
@@ -52,8 +53,10 @@ type BranchSpec = { then: Next } & ({ when: string } | { if: ConditionSpec });
 
 type InstructionSpec = Omit<Instruction, "if"> & { if?: ConditionSpec };
 
-/** What a flow's names resolve against. */
-type Registries = Pick<AgentOptions, "fields" | "actions" | "events" | "conditions" | "tools">;
+/** What a flow's names resolve against. With `flows`, a literal `{ flow }` target must name one of them. */
+type Registries = Pick<AgentOptions, "fields" | "actions" | "events" | "conditions" | "tools"> & {
+  flows?: ReadonlyArray<{ id: string }>;
+};
 
 function fromSpec<C = unknown, D = InferData<FieldDefs>>(spec: FlowSpec): Flow<C, D>;
 function toSpec<C, D>(flow: Flow<C, D>): FlowSpec;
@@ -89,13 +92,13 @@ Every field means what it means on [Flow](./flow.md). The differences:
 | `waitEvent` | `wait: { event }` | An event. |
 | `if` | `if` step | A code fork. |
 
-`fromSpec` drops `kind`; `toSpec` derives it from the step's shape by this table. A talk step with neither `prompt` nor `collect` makes `toSpec` throw.
+`fromSpec` drops `kind`; `toSpec` derives it from the step's shape by this table. A talk step with neither `prompt` nor `collect` makes `toSpec` throw: `[FlowConfigurationError] flow "x", step "y": has neither prompt nor collect. A talk step needs a guideline, fields to collect, or both.`
 
 ## fromSpec
 
 - Strips `null` from every optional value, at any depth.
 - Removes `kind` from each step. Nothing else changes.
-- Throws `FlowConfigurationError` when `steps` is not a list: `[FlowConfigurationError] flow "x": has no steps list. Write steps as a list, even an empty one.`
+- Throws `FlowConfigurationError` when the JSON has the wrong shape, with the same shape checks `validateFlow` runs first: the flow or a step is not an object, a list is not a list (`steps`, `on`, `collect`, …), a step does two things or none, or its `kind` disagrees with its body. For example `[FlowConfigurationError] flow "x": has no steps list. Write steps as a list, even an empty one.`
 - Does **not** check names. The result is typed as a `Flow` but nothing is verified yet; `validateFlow` does that, and the agent runs it on every flow it is built with.
 
 ## toSpec
@@ -120,13 +123,17 @@ Every message has the form `[FlowConfigurationError] <where>: <what>. <fix>`, wh
 | Reserved step id | `uses the reserved id "end"` | "end" ends the run; pick another id. |
 | Duplicate step id | `duplicates an earlier step id` | Give each step its own id. |
 | Triggers, no steps | `has triggers but no steps` | Add at least one step or remove `on`. |
-| Unknown field | `unknown field "x" in collect` (also `ask`, `clearOnStart`, `then.clear`, `while.equals`, `if.known`, …) | Add it to the agent's fields or fix the slug. |
+| Trigger with no kind | `names no trigger kind` (`<where>` is `flow "id", trigger #n`; the v3 `{ kind: 'message', when }` shape lands here) | A trigger is one of `message`, `mention`, `silence`, `event`. A flow the host starts itself has no `on` at all. |
+| Only exclusions | `every message phrase starts with "!", so nothing can ever match it` (also `mention`) | A "!" phrase rules the trigger out. Add at least one plain phrase saying when it should fire, or use an empty list for a catch-all. |
+| Step does nothing | `does nothing` | A step talks (`prompt` / `collect`), says (`say`), acts (`do`), waits (`wait`) or forks (`if`). |
+| Unknown field | `unknown field "x" in collect` (the flow's or a step's; also `ask`, `clearOnStart`, `then.clear`, `while.equals`, `if.known`, …) | Add it to the agent's fields or fix the slug. |
 | Unknown tool | `unknown tool "x"` (flow or step `tools`) | Register it in the agent's tools or fix the name. |
 | Unknown action | `unknown action "x"` | Register it in actions or fix the name. |
 | Unknown event | `unknown event "x"` (trigger) or `unknown event "x" in wait` | Register it in events or fix the name. |
 | Unknown condition | `unknown condition "x" in if` | Register it in conditions or use equals, known, silenced. |
 | `equals` shape | `if.equals is not an object` | Write equals as { field: value }. |
 | `equals` type | `if.equals gives "orcamento" a string, but the field is a number` | Write a number; values are not coerced. |
+| `equals` off the list | `if.equals gives "etapa" "frio", which is not one of "novo", "quente"` | Use one of the listed values. |
 | `known` shape | `if.known is not a list` | Write known as [field, ...]. |
 | `silenced` shape | `if.silenced is not a boolean` | Write true or false. |
 | Bad duration | `wait has duration "5 min", which does not parse` (also `silence`, `after`, `repeat.cooldown`, `wait.upTo`) | Write a number and a unit: "30s", "5m", "24h" or "3d". |
@@ -136,17 +143,37 @@ Every message has the form `[FlowConfigurationError] <where>: <what>. <fix>`, wh
 | Extra parameter | `action "notify" has no parameter "to"` | Remove it or fix the name. |
 | Branch without a test | `branches[0] has neither when nor if` | Give the branch an AI condition (when) or a code one (if). |
 | Backward `if` with no `else` | `"if" jumps back to "quem" with no else` | Add else so the false branch has somewhere to go. |
+| Fixed question, nothing to ask | `has a question but collects nothing` | A fixed question asks for fields: add collect, or send the text with a say step. |
+| Not an object | `is null, not an object` (the flow), `steps[0] is null, not an object`, `with is "x", not an object` | Pass the flow itself: { id, name, steps }. / Write each entry of steps as an object. |
+| Not a list | `collect is "nome", not a list` (also `on`, `steps`, `clearOnStart`, `tools`, `instructions`, `branches`, `message`, `mention`, `then.clear`) | Write collect: ["nome"]. |
+| Not text | `say is 42, not text` (also `prompt`, `question`, `description`, `anchor`) | Write say as a string. |
+| Not one of the values | `onEnd is "restart", which is not one of "end", "stay", "reset"` (also `instructions[n].kind`) | Use one of them. |
+| Bad `repeat` | `repeat is "never"` | Use "once", "always" or { cooldown: "24h" }. |
+| Bad `maxAsks` | `maxAsks is "3", not a whole number of 1 or more` | Write a number like 3. |
+| Event wait without an event | `wait has no event` | Write wait: { event: "name" } to wait for an event, or a duration like "1h". |
+| Bad target | `then is 5, not a step id or a target` (also `else`, `onFail`, `branches[n].then`) | Write a step id, "end", { step: "id" } or { flow: "id" }. |
+| Step does two things | `mixes "say" and "do"` | A step does one thing. Split it into one step per kind. |
+| `kind` disagrees with the body | `has kind "do", but its body is a "say" step` | Set kind to "say", or change the body to match. |
 
 Parameter values are checked strictly: `"3"` is not a number, `3.5` is not an integer, and an `enum` must contain the value unless the string holds `{{`, because a template's value is only known at run time.
 
-Two checks live in the agent constructor rather than in `validateFlow`: `flow "x" is declared twice` and `idle: unknown tool "x"`.
+The agent constructor passes its own flows as `registries.flows`, so a literal chain to a flow it does not have is a warning in the log (see below). Five more checks live in the constructor rather than in `validateFlow`:
+
+- `flow "x" is declared twice`
+- `idle: unknown tool "x"`
+- `tool "x": parameters must be a JSON Schema object`
+- `condition "known" shadows a built-in`: `equals`, `known` and `silenced` are reserved
+- an unknown condition in an agent or idle instruction's `if`: `agent: unknown condition "vip" in instructions[0].if`
 
 ### Warnings
 
 | Warning | Why |
 |---|---|
 | `flow "f", step "s": then jumps back to "quem" without clear; the fields collected since stay known and those steps skip. Add clear: [...] to re-ask them.` | A `then`, `else`, `onFail` or branch target points at the same or an earlier step and clears nothing, so a collect step it lands on is skipped with `code: 'already-known'`. |
-| `flow "f", step "s": collects "nome", "empresa" with no prompt and no ask; the model has nothing to go on. Add a prompt or an ask per field.` | A collect step with no `prompt`, where no listed field has an `ask` on the step or on the agent. |
+| `flow "f", step "s": collects "nome", "empresa" with no prompt and no ask; the model has nothing to go on. Add a prompt or an ask per field.` | A collect step with no `prompt` and no `question`, where no listed field has an `ask` on the step or on the agent. |
+| `flow "f": collect lists "confirmado", which is only taken from the answer to a step that asks it, and no step does. Add it to a step's collect, or set extract: 'anywhere' on the field.` | A field in the flow's `collect` with `extract: 'asked'` (every boolean, by default) that no step's `collect` lists, so nothing can ever fill it. |
+| `flow "f", step "s": then names flow "humnao", which this agent does not have; a run skips this move with flow-gone. Use one of "vendas", "suporte", or add the flow.` | A literal `{ flow }` target missing from `registries.flows`; only checked when that list is set, and never for an id with `{{`. A warning rather than an error, so a host that drops one bad row keeps the rest of its agent. |
+| `flow "f", step "s": branches[0] is a "when" branch on a wait step, which no call judges, so a reply goes to else. Use "if", or move the branch to a talk step.` | No call judges a wait step, so an AI condition there never fires. `flowSpecSchema` no longer offers one. |
 
 ## flowSpecSchema