@falai/agent 4.0.0-alpha.2 → 4.0.0-alpha.21

package/docs/concepts/collection.md

@@ -7,7 +7,7 @@ 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.
+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. A flow lists the fields it needs, and its steps say which to ask and when. The model asks and extracts. Code decides what is still missing.
 
 ## Declared once
 
@@ -41,12 +41,45 @@ type Data = DataOf<typeof f>;
 |---|---|
 | `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`. |
+| `label` | The name a person reads, in an editor or next to a collected value. The model never sees it. |
 | `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>`.
 
+## A flow's data, a step's questions
+
+A scheduling flow needs one set of fields and a triage flow another. The flow's `collect` lists the fields it needs. Each talk step's `collect` says which of them to ask now, in what order: one field, or several when the step's prompt asks them together.
+
+```ts
+import { falai } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", label: "Nome", ask: "Pergunte o nome." },
+  dia: { type: "string", label: "Dia", ask: "Pergunte qual dia fica melhor." },
+  orcamento: { type: "number", label: "Orçamento" },
+});
+
+const agenda = f.flow({
+  id: "agenda",
+  name: "Agendamento",
+  on: [{ message: ["quer agendar uma visita"] }],
+  collect: ["nome", "dia", "orcamento"],
+  steps: [
+    { id: "quem", collect: ["nome"], question: "Claro! Qual é o seu nome?" },
+    { id: "quando", prompt: "Ofereça terça ou quinta.", collect: ["dia"] },
+    { id: "fim", say: "Combinado, {{data.nome}}. Até {{data.dia}}." },
+  ],
+});
+
+export { agenda };
+```
+
+No step asks for `orcamento`. It is still on the flow's list, so when the customer mentions a budget while this flow holds the conversation, the value is noted. A field on the list that only an answer can fill (`extract: 'asked'`, every boolean by default) and that no step asks can never be filled; `validateFlow` warns about it.
+
+Step one asks with fixed text: `question`. Its first ask goes out word for word, with no model call. It goes out only when every field the step collects is still missing. If the customer's first message already gave the name, the step is skipped. If that message asks something instead, the model answers it first and the question follows, word for word. A later ask is the model's own wording, so a customer who replies with a question gets an answer.
+
 ## 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.
@@ -69,7 +102,7 @@ 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 understand call | Unknown fields with `extract: 'anywhere'` that the floor's flow or a candidate `message` flow lists, in its own `collect` or a talk step's. With nobody on the floor, also the catch-all's (`message: []`) | 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 |
@@ -110,7 +143,7 @@ This split also decides which call spends tokens on what. On a message, the unde
 { 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.
+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. A step's fixed `question` counts as one ask. `{ step, clear }` resets the count of the fields it clears, so a confirmation loop asks from scratch each round.
 
 ## Known fields are never re-extracted
 
@@ -157,11 +190,13 @@ Three layers of text shape the question, from general to specific.
 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.
+A step's `question` skips all three for the first ask: it is the exact text the customer reads. Every later ask goes back to the three layers.
+
+All four 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.
+`toWireSchema` in `src/utils/schema.ts` is the only way a field definition reaches a provider. It keeps `type`, `description` and `enum` and strips `label`, `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
 

package/docs/concepts/pipeline.md

@@ -62,12 +62,12 @@ Code first works out what there is to judge:
 - **Candidates**: the flow holding the floor, whatever its trigger, plus every `message` flow with a non-empty phrase list whose `if` holds and whose `repeat` allows a start, in flow order. `message: []` catch-alls are never scored.
 - **Mentions**: every `mention` flow with a non-empty list whose `repeat` allows a start.
 - **Branches**: the `when` branches of the asking step.
-- **Fields**: every unknown field with `extract: 'anywhere'` listed by any talk step of the floor's flow or of a candidate flow.
+- **Fields**: every unknown field with `extract: 'anywhere'` that the floor's flow or a candidate flow lists, in its own `collect` or a talk step's. With nobody on the floor, the catch-all that would take the message adds its fields too, because an opening message often says the most. The fields its first step asks are read by that step's own speak call, so on their own they are not worth a call. A first step with a fixed `question` has no speak call, so its fields do count.
 
 Then the shortcuts, each worth zero calls:
 
 - Nothing to judge: no call. The catch-all or the idle speaker answers.
-- Exactly one eligible `message` flow, nobody on the floor, nothing else to judge: it starts without scoring.
+- Exactly one eligible `message` flow, nobody on the floor, no catch-all that passes, `idle: 'silent'`, nothing else to judge: it starts without scoring. With a catch-all or the idle speaker there, a low score has somewhere to go, so the lone flow is scored.
 - A floor holder, no other candidate, nothing else to judge: there is nothing to compare.
 
 Otherwise one call, `schemaName: 'understand'`, with one envelope: `{ flows: { id: 0–100 }, mentions: { id: boolean }, extract: { id: { … } }, branches: { q1: boolean }, fields: { field: value } }`. Only the sections with something to judge are present; inside a section every property is required and nullable, so the model must answer each one. Branch keys travel as short aliases (`q1`, `q2`) because a run id is not a legal property name; they are mapped back to `${runId}/${stepId}/${index}` when the reply is parsed. A reply with no usable JSON is logged and treated as an empty judgement; the call still counts. A provider failure here throws `ProviderError`: nothing ran, nothing was saved, and the host retries the input.
@@ -76,7 +76,7 @@ Otherwise one call, `schemaName: 'understand'`, with one envelope: `{ flows: { i
 
 Code applies the judgement in a fixed order.
 
-1. **Routing**, skipped when a run took the floor in Ingest. With an asking run, another flow takes over only when its score is at least 40 and beats the asker's by at least 15. With no asker: a single eligible flow starts as is; otherwise the best score at 40 or above starts, else the first `message: []` catch-all, else nobody, and the idle speaker answers in phase 6. A `suspended` run of the chosen flow resumes instead of a new one starting.
+1. **Routing**, skipped when a run took the floor in Ingest. With an asking run, another flow takes over only when its score is at least 40 and beats the asker's by at least 15. With no asker: the best score at 40 or above starts, else the first `message: []` catch-all, else nobody, and the idle speaker answers in phase 6. The one exception is a single eligible flow with no catch-all passing and `idle: 'silent'`: it starts as is. A `suspended` run of the chosen flow resumes instead of a new one starting.
 2. **Mention runs** start in flow order. A `mention: []` trigger is a code-only detector: it goes through the start checks on every message without the call, so a blocked `repeat` is logged as a skip. A trigger's `extract` values become the run's `input`.
 3. **The routed run** starts or resumes and holds the floor. A run that starts applies `clearOnStart` now, before extracted values land.
 4. **Fields** from the envelope are written one at a time, after validation. An unknown field name is dropped (`code: 'unknown-field'`), a value that does not fit the type is dropped (`code: 'bad-value'`), a value outside `enum` is dropped (`code: 'not-in-enum'`). Strings are coerced to numbers and booleans on the way in.
@@ -84,13 +84,13 @@ Code applies the judgement in a fixed order.
 
 ## 5. Run
 
-If no run is asking, the most recently suspended one returns to asking. Then every live run is moved in turn; a child started by `then: { flow }` joins the queue. A run moves only if it can: `waiting` and `suspended` runs stay put, and an asking run re-speaks only on a message, never on a wake or an event.
+If no run is asking, the most recently suspended one returns to asking. Then every live run is moved in turn; a child started by `then: { flow }` joins the queue. On a message that nothing has answered once the queue is empty, with nobody asking and no `silenced`, the most recently suspended run returns to asking and moves too, and so on down the stack until one answers: an asker that moved on without a word hands the message back to the run it suspended. A run that returns to asking on a message has its step's `if` branches judged first, as Decide does for the asker. A run moves only if it can: `waiting` and `suspended` runs stay put, and an asking run re-speaks only on a message, never on a wake or an event.
 
 Before a run moves, its premise is re-checked with this turn's context: `while` when the flow has one, otherwise the trigger's `if`. A false premise ends the run: `code: 'premise-changed'`. A silence-started run moved by a wake also ends when the customer has written since it started: `code: 'customer-replied'`. A flow the agent no longer has ends the run with `code: 'flow-gone'`; a missing step, `code: 'step-gone'`.
 
 Then the run walks its steps until one stops it.
 
-- **Talk** (`prompt` / `collect`). Pending is `collect` minus known minus at `maxAsks`. A collect step with nothing pending is skipped with no call (`code: 'already-known'`) and the run continues. Under `silenced`, a resuming asker stays asking and any other run ends `code: 'silenced'` (`detail` = your reason). Otherwise every other asking run is suspended, this run becomes `asking`, and it is the turn's speaker, unless speaking already happened this turn, in which case it waits for the next message.
+- **Talk** (`prompt` / `collect`). Pending is `collect` minus known minus at `maxAsks`. A collect step with nothing pending is skipped with no call (`code: 'already-known'`) and the run continues, except on the step an `onEnd: 'stay'` run stays on: that one answers anyway. Under `silenced`, a resuming asker stays asking and any other run ends `code: 'silenced'` (`detail` = your reason). Otherwise every other asking run is suspended, this run becomes `asking`, and it is the turn's speaker, unless speaking already happened this turn, in which case it waits for the next message.
 - **Say.** The text goes to `messages[]` as `kind: 'verbatim'` with the pending `afterMs`. `once` writes a claim; a repeat is `code: 'already-sent'`. Under `silenced` the run ends `code: 'silenced'` (`detail` = your reason).
 - **Do.** The action runs now, with `with` rendered against `data`, `context` and `input`, under `key = ${runId}:${stepId}:${visit}`. `{ ok }` continues (`spoke: true` makes this run the one that answered); `{ skipped }` continues (`code: 'action-skipped'`); `{ failed }` takes `onFail` or continues (`code: 'action-failed'`); `{ defer }` parks the run under a new wake and re-runs the same step, same key, when it fires. An unknown action is `code: 'action-failed'` with `detail: 'unknown action "notify"'`; a thrown error is `code: 'action-failed'`, the error message in `detail`.
 - **Wait** (timer). Ten seconds or less, when the next step is a `say` or a talk step: the delay rides on that message as `afterMs` (`code: 'inline-delay'`, `detail: '3000ms'`). Anything else parks the run and adds `{ key, at }` to `schedule[]`, with `at` moved forward to the next business hour when the step sets `businessHours: true`.
@@ -115,6 +115,7 @@ The prompt is built per call, in `src/core/Speak.ts`, in this order:
 - the known fields, as settled facts
 - the instructions whose `if` holds: agent, then flow, then step
 - the customer's message, or, on anything but a message (a wake, an event, a start), a note that there is no new message and the assistant speaks first
+- what this turn already sent before the reply (a `say`, a fixed question), in order, so the reply does not say it again
 - the response format
 
 The envelope is `{ message, ...pending fields of this step }`, every property required and nullable, so one call both answers and extracts. Tools run in rounds. Each round is one call; the model may call tools, their results go back as history, and it is asked again. After `maxToolLoops` rounds (default 5; `0` disables tools) it is asked once more without tools, so a message always comes back. Field values merge across rounds, last one wins. A provider failure or an empty message returns `deferred` instead of throwing; phase 7 re-parks the step.
@@ -123,15 +124,15 @@ The envelope is `{ message, ...pending fields of this step }`, every property re
 
 The one place the spoken result is applied.
 
-**Spoken.** The message goes to `messages[]` as `kind: 'ai'` with `key = ${runId}:${stepId}:${visit}`, or `idle:<trigger key>` for the idle speaker. Envelope values are validated and written like phase 4; tool `data` patches are written as given. Pending is recomputed. Each field still pending gets `asked + 1` and the run stays `asking`. Nothing pending: a field that hit `maxAsks` is reported (`code: 'max-asks'`, one line per field), the run takes `then` and keeps moving this turn, except that a talk step reached now waits for the next message.
+**Spoken.** The message goes to `messages[]` as `kind: 'ai'` with `key = ${runId}:${stepId}:${visit}`, or `idle:<trigger key>` for the idle speaker. Envelope values are validated and written like phase 4; tool `data` patches are written as given. Pending is recomputed. Each field still pending gets `asked + 1` and the run stays `asking`. Nothing pending: a field that hit `maxAsks` is reported (`code: 'max-asks'`, one line per field), the run takes `then` and keeps moving this turn, except that a talk step reached now waits for the next message. A run staying on its step (`onEnd: 'stay'`) takes no `then`: it stays there for the next message, one visit later. A run that reaches the end of an `onEnd: 'stay'` flow goes back to the last talk step it took; when another run is asking, it waits `suspended` behind it, unless this message was routed to it.
 
-**Deferred.** A failure a wait can fix — the provider was down, slow or rate-limited — re-parks the talk step under `${runId}:${stepId}:${visit}:retry:${atMs}`: +1m, +5m, +15m, +1h, +6h, then the run ends `failed`. A failure it cannot fix — a rejected key, a prompt past the context window — ends the run at once. The session is saved with everything phase 5 did. The retry wake re-runs the step under the same key, so the `do` steps before it do not run again.
+**Deferred.** A failure a wait can fix — the provider was down, slow or rate-limited — re-parks the talk step under `${runId}:${stepId}:${visit}:retry:${atMs}`: +1m, +5m, +15m, +1h, +6h, then the run ends `failed`. A failure it cannot fix — a rejected key, a prompt past the context window — ends the run at once. The session is saved with everything phase 5 did. The retry wake re-runs the step under the same key, so the `do` steps before it do not run again. When the host's history still ends with the customer's message, the retry's speak call is told that message has no answer yet, rather than that the assistant speaks first. Only the retry does this: any other wake speaks first, even when the history ends with a customer message, because a host may have skipped that message on purpose.
 
 Then three bookkeeping moves. `lastAssistantAt` is set when anything went out. The most recently suspended run resumes when nobody is asking. And when the assistant spoke last, every `silence` flow whose `if` and `repeat` allow it gets a wake at `lastAssistantAt + silence`, key `silence:${flowId}:${sessionId}:${lastAssistantAtMs}`, with `replaces` naming the previous one.
 
 ## 8. Return
 
-`TurnResult`: `session` (version unchanged; the host bumps it on save), `changed`, `messages` in emission order, `schedule`, `outcomes`, `started`, `ended` (each with a reason), `skipped` (triggers that matched but did not start, with the reason), `llmCalls`. `changed` is `false` when the input was ignored — a repeated message id, a wake with no session, a wake nothing is waiting for — or when the session came back identical with no message, no wake, no outcome and no skip to show for the turn.
+`TurnResult`: `session` (version unchanged by the turn; `Store.save` bumps it and returns the saved session), `changed`, `messages` in emission order, `schedule`, `outcomes`, `started`, `ended` (each with a reason), `skipped` (triggers that matched but did not start, with the reason), `llmCalls`. `changed` is `false` when the input was ignored — a repeated message id, a wake with no session, a wake nothing is waiting for — or when the session came back identical with no message, no wake, no outcome and no skip to show for the turn.
 
 ## The budget
 
@@ -139,12 +140,14 @@ Every row but the last is asserted by a scenario in `tests/scenarios/`; the comp
 
 | Turn | Calls | Why | Scenario |
 |---|---|---|---|
-| A message with a floor holder or several candidate flows | 2 | understand, then speak | S1 |
-| A message when one flow is eligible and nothing else needs judging | 1 | speak only | S0, S1 |
+| A message with a floor holder, several candidate flows, or one candidate that a catch-all or the idle speaker could stand in for | 2 | understand, then speak | S1, S13 |
+| A message with nothing to judge: a catch-all alone with nothing to learn beyond what its first step asks, a floor holder alone, or one flow with `idle: 'silent'` and no catch-all | 1 | speak only | S0, S1, S8, S14 |
 | A message with no flows, answered by the idle speaker | 1 | speak only | S9 |
 | A message where a mention flow's `say` answers | 1 | understand only; the floor's talk is skipped | S4 |
 | Each tool round | +1 | one more speak call | S8, S9 |
 | A wake or start that reaches a talk step | 1 | speak only; there is no message to understand | S2, S5, S12 |
+| A step's first ask with a fixed `question` | 0 | the text goes out as written | S14 |
+| The same, when the customer's message asks something | 1 | the answer, then the text as written | S14 |
 | A wake or start that runs only `do`, `wait` and `if` steps | 0 | code only | S5 (the start; its defer test covers the wake) |
 | Any input under `silenced` (a plain reason) | 0 | `do` steps run, nobody speaks; `{ reason, understand: true }` still spends the understand call | S2, S12 |
 | A message with `idle: 'silent'` and no eligible flow | 0 | nothing to judge, nobody speaks | S9 |

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

@@ -53,7 +53,7 @@ A `do` step fills the parameters with `with`. When the agent is built, `validate
 - a value has the wrong type; nothing is coerced, so `"3"` is not a number. A template such as `"{{data.cep}}"` is a string, so templates can only fill string parameters (and the items of a string array);
 - `with` names a parameter the action does not have.
 
-Templates in `with` are rendered right before `run` is called, against `data` (collected fields), `context` (this turn's host context) and `input` (the run's input). A path that resolves to nothing keeps its `{{...}}`, so a typo stays visible.
+Templates in `with` are rendered right before `run` is called, against `data` (collected fields), `context` (this turn's host context) and `input` (the run's input). An unknown path keeps its `{{...}}`, so a typo stays visible. A blank one drops out, and the space or comma it left behind goes with it — an empty string, or a path that walks through a `null` such as `{{context.lead.name}}` when there is no lead.
 
 ## What `run` sees
 
@@ -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/conditions.md

@@ -151,7 +151,7 @@ const suporte = f.flow({
 });
 ```
 
-What a `when` costs: the understand call happens at most once per turn, and every `when` branch rides in it. When that call would not happen otherwise (a single message flow, nothing to extract, no mention flows), a `when` branch alone makes the turn spend it. An instruction's `when` costs nothing extra: it is text inside the speak prompt.
+What a `when` costs: the understand call happens at most once per turn, and every `when` branch rides in it. When that call would not happen otherwise (no other flow to score, nothing to extract, no mention flows), a `when` branch alone makes the turn spend it. An instruction's `when` costs nothing extra: it is text inside the speak prompt.
 
 A `when` only makes sense where there is fresh customer text. Branches on a `wait` step are judged when the customer replies, by code only: an `if` branch there works, a `when` branch is listed by the type but never asked.
 

package/docs/guides/error-handling.md

@@ -80,6 +80,8 @@ The speak call phrases the reply. If the provider fails here, or answers with an
 
 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.
 
+**The provider's own answer wins.** The table reads the failure's kind, which is an inference. When the provider sends `x-should-retry` it is not one, so that is read first: a `503` saying don't ends the step instead of spending five wakes to be told again, and a rejected request saying do gets its wake instead of ending the run. It arrives on `ProviderError.shouldRetry`.
+
 **The ladder ends.** After the sixth failure on the same step there is no seventh wake: the outcome is `status: "failed"` and the run ends. The same happens at once for a failure no wait can fix — retrying a rejected key or an oversized prompt only spends two model calls to reach the same wall. Both land in `ended` with `reason: "failed"`, so your execution log shows a conversation that stopped and why.
 
 Actions that ran earlier in the same turn are not undone; they ran at-least-once and are idempotent on `ctx.key`. `say` steps that went out before the failure are in `messages[]` as usual.
@@ -148,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";
@@ -338,8 +338,8 @@ Every message turn decides who speaks, in this order:
 1. **Ingest first.** If the message ends a `wait` with `else` and the run goes on to another step, that run takes the floor and routing is skipped.
 2. **Eligible flows.** Message flows with a non-empty list whose `if` holds and whose `repeat` allows, in the order you passed them to the agent.
 3. **The run that is asking keeps priority.** When a run is asking, its flow is scored too. Another flow wins only when its score is at least 15 above the asking flow's and at least 40. Then a suspended run of that flow resumes, or a new run starts; the run that was asking is suspended and comes back when the winner ends.
-4. **One candidate, no floor.** It starts without scoring. If nothing else needs the model this turn (no mention flows, no pending fields to extract), the turn spends no understand call.
-5. **Several candidates, no floor.** The best score wins if it is at least 40. Otherwise the first `message: []` catch-all that passes `if` and `repeat` starts. Otherwise nobody takes the floor.
+4. **No floor.** The best score wins if it is at least 40. Otherwise the first `message: []` catch-all that passes `if` and `repeat` starts. Otherwise nobody takes the floor. A lone candidate is scored too, so "oi" does not start your scheduling flow just because it is the only one.
+5. **One candidate and nobody else to answer.** When no catch-all passes and `idle` is `'silent'`, a low score would leave the customer with no reply. So the one candidate starts without a score. If nothing else needs the model this turn (no mention flows, no pending fields to extract), the turn spends no understand call.
 6. **Nobody has the floor.** The idle speaker answers.
 
 Scores come from the understand call, 0 to 100 per candidate. The two thresholds, 40 and 15, are constants in `src/core/Runner.ts`.

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 ───
@@ -253,7 +253,10 @@ const f = falai().fields({ nome: { type: 'string' } });
 
 const concorrente = f.flow({
   id: 'concorrente', name: 'Lead falou de concorrente',
-  on: [{ mention: ['o lead cita ou compara com um concorrente'], extract: { trecho: { type: 'string' } }, repeat: 'once' }],
+  on: [{
+    mention: ['o lead cita ou compara com um concorrente', '!o lead fala do nosso próprio produto'],
+    extract: { trecho: { type: 'string' } }, repeat: 'once',
+  }],
   steps: [
     { id: 'tag',   do: 'add_tags', with: { tags: ['concorrente'] } },
     { id: 'avisa', do: 'notify', with: { recipient: 'owner', message: '{{data.nome}} falou de concorrente: "{{input.trecho}}"' } },
@@ -263,7 +266,7 @@ const concorrente = f.flow({
 
 | Signal facet | v4 |
 |---|---|
-| `when[]` with `!` exclusions | `mention: [...]`; write the exclusion into the phrase |
+| `when[]` with `!` exclusions | `mention: [...]`, exclusions and all — a `!` phrase still rules the trigger out. Copy the list across unchanged |
 | `if` | trigger `if`; sees `input` after `extract` |
 | `extract` | trigger `extract` → `run.input` → `{{input.x}}`; never written to `data` |
 | `phase: 'pre'` + `halt` + `reply` | a `say` first step; another run's `say` silences the floor's reply that turn |
@@ -300,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.
@@ -346,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.
 
@@ -383,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.
 
@@ -407,13 +411,14 @@ Host actions, events and conditions are registered once on the agent and referen
 | `agent.dispatch`, `pendingDirective`, `Directive`, `flow.merge`, `flow.validate` | `then` / `else` on steps |
 | `Flow` class, `Step` class, `flow` namespace, `FlowOptions`, `StepOptions` | plain objects: `Flow`, `Step` |
 | `title`, `when`, `if`, `reentrant`, `requiredFields`, `optionalFields`, `onComplete`, flow `hooks` | `id` + `name`, `on[]`, `repeat`, `clearOnStart`, `onEnd`, `while` |
-| `requires`, `skip`, `auto`, `reply`, step `hooks`, `prepare`, `finalize` | known-field skipping, `maxAsks`, `do`, `if`, `wait`, `say` |
+| `skip`, `auto`, `reply`, step `hooks`, `prepare`, `finalize` | known-field skipping, `maxAsks`, `do`, `wait`, `say` |
+| `requires` | an `if` step: `{ if: { known: [...] }, then: '<step>', else: 'end' }`. Not known-field skipping — that answers "do I still need to ask?", while `requires` answers "may this step run at all?". They differ exactly when the customer never answers: `maxAsks` retires the field and the step proceeds with it unknown. |
 | `Signal`, `SignalContext`, `SignalFiring`, `signals`, `signalBatchSize`, `triggeredSignals` | `mention` flows, `repeat`, `claims` |
 | `ToolContext.updateContext / updateData / setField / dispatch`, `ToolResult.dataUpdate / contextUpdate / directive`, `ToolManager`, `ToolScope`, tool config helpers | `Tool.handler(args, ctx) → { value?, data? }` |
 | `PersistenceAdapter`, `SessionRepository`, `MessageRepository`, `PersistenceManager`, `SessionManager`, `restoreSession`, `createPersistedState`, `enterFlow`, `enterStep`, `completeCurrentFlow`, `mergeCollected` | `Store`, the seven `*Store` classes, `migrateSession` |
 | `SessionState`, `CollectedStateData`, `SessionData` | `Session` |
 | `AgentResponse.executedSteps / stoppedReason / endedFlows / appliedInstructions / isFlowComplete` | `TurnResult.outcomes / started / ended / skipped / messages / schedule / llmCalls` |
-| `Template` as a function, `TemplateContext`, `ConditionEvaluator`, `ConditionWhen`, `ConditionIf`, `!` exclusions | `Template = string` with `{{data.x}}` `{{context.x}}` `{{input.x}}`; `Pred` (function or JSON) |
+| `Template` as a function, `TemplateContext`, `ConditionEvaluator`, `ConditionWhen`, `ConditionIf` | `Template = string` with `{{data.x}}` `{{context.x}}` `{{input.x}}`; `Pred` (function or JSON). **`!` exclusions are not gone** — a phrase opening with `!` still rules a trigger out. Copy the list across unchanged. |
 | `Term`, `terms` | put the glossary in `knowledgeBase` or an instruction |
 | `Instruction.enabled / tags / metadata` | filter before passing |
 | `promptCache`, `PromptSectionCache`, `PromptCacheConfig` | gone; every prompt is built per call. `compaction` stays and runs once per turn on the history you pass |
@@ -437,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

@@ -116,7 +116,7 @@ f.action<const P extends ParamDefs>(def: {
 
 ### Behaviour
 
-- `with` is rendered before `run` sees it. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced inside every string, at any depth. A path that resolves to nothing keeps its placeholder, so a typo stays visible.
+- `with` is rendered before `run` sees it. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced inside every string, at any depth. An unknown path keeps its placeholder, so a typo stays visible. A blank one drops out instead and the gap it left in the sentence closes — an empty string, or a path through a `null` (`{{context.lead.name}}` with no lead). A `null` at the end of a path is unknown, not blank.
 - `with` is checked when the agent is built, not on the turn that reaches the step. A missing required parameter, an unknown parameter, or a value outside `enum` throws `FlowConfigurationError`. So does a wrong type: `"3"` is not a number, because values are never coerced. A string that contains `{{` skips the `enum` check, because its value is only known at run time.
 - Actions run in the Run phase, by code, with zero model calls. They run while `silenced` too.
 - A `do` step whose action name is not registered throws at build. If the registry changed under a running agent, the step reports `code: 'action-failed'` with `detail: 'unknown action "notify"'`.
@@ -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.