@falai/agent 4.0.0-alpha.1 → 4.0.0-alpha.10

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"'`.

package/docs/reference/agent.md

@@ -77,7 +77,7 @@ class Agent<C, D> {
 | `tools` | `Tool<C, D>[]` | `[]` | Functions the model may call while it speaks. See [Tool](tool.md). |
 | `instructions` | `Instruction<C, D>[]` | `[]` | Agent-level rules, rendered into every speak call. See [Instruction](instruction.md). |
 | `knowledgeBase` | `Record<string, unknown>` | none | Any JSON the model should know. Rendered as nested bullets. |
-| `idle` | `Idle<C, D>` | `{ prompt: "" }` | The one speaker that is not a step. Answers a message when no run holds the floor. `'silent'` mutes it. |
+| `idle` | `Idle<C, D>` | `{ prompt: "" }` | The one speaker that is not a step. Answers a message when no run holds the floor. `'silent'` mutes it; then a lone message flow with no catch-all starts without being scored. |
 | `clock` | `Clock` | `() => new Date()` | Returns "now". Tests pass `fakeClock(iso)`. |
 | `businessHours` | `BusinessHours<C>` | none | `(at, { context }) => Date`. Moves a timer forward to the next working moment when a trigger or wait says `businessHours: true`. |
 | `maxToolLoops` | `number` | `5` | Tool rounds per speak call. `0` disables tools. After the last round the model is asked once more without tools, so a message always comes back. |
@@ -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.
@@ -105,7 +109,7 @@ Every input carries the common fields, plus exactly one of the four kinds.
 | `sessionId` | `string` | The conversation's id. A first turn creates the session under this id. |
 | `session` | `Session<D>` | The stored session, as the store returned it. Absent on a first turn. A `wake` without a session is ignored. |
 | `context` | `C` | Your ambient data for this turn. Required unless `C` allows `undefined` (`falai()` with no generic). |
-| `history` | `History` | The conversation so far. Pass it on every input kind, wakes included; both calls read it. Without it the framework falls back to `session.history`, then to an empty list. |
+| `history` | `History` | The conversation before this input. Pass it on every input kind, wakes included; both calls read it. Leave out the message this turn carries: both calls quote it on their own, so a history that ends with it is read twice. Store the message after the turn, not before. Without `history` the framework falls back to `session.history`, then to an empty list. |
 | `silenced` | `Silenced` | Your reason the assistant cannot speak right now. See below. |
 | `anchors` | `Record<string, { key: string; lastInboundAt?: string }>` | The host anchors this session belongs to, by name, e.g. `{ lead: { key: 'lead:456', lastInboundAt } }`. A flow with `anchor: 'lead'` keys its runs and claims by `anchors.lead.key`. |
 | `claims` | `{ held: Record<string, string>; active: string[] }` | Claims from the customer's other sessions: `held` maps a dedupe key to the ISO time it was taken; `active` lists live `${flowId}:${anchor}` pairs. A flow already active elsewhere is skipped with `code: 'already-running'`. |
@@ -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/flow-spec.md

@@ -132,7 +132,7 @@ Every message has the form `[FlowConfigurationError] <where>: <what>. <fix>`, wh
 | 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". |
 | Dangling jump | `then points at step "x", which does not exist` (also `else`, `onFail`, `branches[n].then`) | Use an existing step id or "end". |
 | Missing parameter | `action "notify" needs parameter "message"` | Add it to `with`. |
-| Wrong parameter type | `parameter "tags" of action "add_tags" must be a list of string, got string` | Values are not coerced; write the right type. |
+| Wrong parameter type | `parameter "tags" of action "add_tags" must be a list of strings, got string` | Values are not coerced; write the right type. |
 | 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. |

package/docs/reference/providers.md

@@ -185,7 +185,7 @@ Base URL `https://openrouter.ai/api`, chat completions with `json_schema`.
 
 Pass `providerOrder` to choose the hosts yourself. There is no way to say it inside `model`: OpenRouter answers `400 "z-ai/glm-5.3-flash@novita is not a valid model ID"`.
 
-One caveat worth measuring for your own model: through this gateway, `z-ai/glm-5.3-flash` put "somos umas 30 pessoas" in the wrong band of a four-value enum on most attempts, in every JSON mode and routing tried, while the same model on [ZaiProvider](#zaiprovider) and `deepseek-chat` got it right every time. Run `bun run eval:live --only openrouter` against the model you ship.
+**The route changes the answers, so measure your own model here.** Through this gateway, `z-ai/glm-5.3-flash` put "somos umas 30 pessoas" in the wrong band of a four-value enum on most attempts, in every JSON mode and routing tried, while the same model on [ZaiProvider](#zaiprovider) and `deepseek-chat` got it right every time. Over the 40-case understand eval on 2026-09-21 the same split holds: routing agreement 93% either way, but field agreement 86% (12/14) through OpenRouter against 100% (14/14) on `ZaiProvider`, and a median call three to five times slower. Prefer a model's own endpoint where you have one; run `bun run eval:understand` and `bun run eval:live --only openrouter` against the model you ship.
 
 ## DeepSeekProvider
 
@@ -236,7 +236,7 @@ import { ZaiProvider } from "@falai/agent";
 const zai = new ZaiProvider({ apiKey: process.env.ZAI_API_KEY ?? "" }); // model defaults to glm-5.3-flash
 ```
 
-The flat-rate Z.ai Coding Plan hosts GLM on an Anthropic-compatible endpoint. Model ids are bare, and "no thinking" has to be said with `config: { effort: "none" }`: leaving `effort` unset means the model's default, which is thinking on.
+The flat-rate Z.ai Coding Plan hosts GLM on an Anthropic-compatible endpoint. Model ids are bare, and thinking is off unless you ask for it: the endpoint reads an absent `thinking` field as thinking on, so `@providerkit/core` says "no" out loud for you. Measured 2026-09-21: a call with no `config.effort` sends `thinking: { type: "disabled" }`, the same body `effort: "none"` produces. Ask for thinking with `config: { effort: "high" }`.
 
 ## FallbackAiProvider
 

package/docs/reference/trigger.md

@@ -49,6 +49,26 @@ The run takes the conversation: it becomes the asker and holds the floor — onl
 
 The run starts beside the conversation. It is meant for `do` and `say` steps: it does not get routed to. A talk step in it behaves like any talk step and takes the floor.
 
+### Phrases that rule a trigger out
+
+Phrases are alternatives — one match is enough — so a list alone can only say "any of these". A phrase that opens with `!` says the opposite: it stops the trigger, whatever else matched.
+
+```ts fragment
+on: [{
+  mention: [
+    'o cliente pede para falar com uma pessoa',
+    '!o cliente só concorda com o horário oferecido',   // "pode sim" is a yes to the meeting
+    '!o cliente menciona outra pessoa sem pedir atendimento',
+  ],
+}]
+```
+
+Without the two exclusions, a customer answering "pode sim" to an offer of a meeting reads as a request for a human, because that sentence really does mention a person. The model is given the two lists separately and told that an exclusion overrides a match.
+
+Works in `message` (an exclusion scores the flow 0), in `mention` (an exclusion answers false), and in an instruction's `when`. Whitespace around a phrase is trimmed, a bare `"!"` is ignored, and a `!` anywhere but the first character is ordinary text.
+
+A trigger whose phrases are *all* exclusions can never fire, so `validateFlow` rejects it. For a flow that should catch everything else, use `message: []`.
+
 ### silence
 
 | Field | Type | Default | Meaning |
@@ -103,8 +123,8 @@ Pass a real message `id` on every message turn. Only `id` is checked against the
 ## Behaviour
 
 **How message flows are chosen.** On a message turn, the eligible flows are those with a non-empty `message` list passing `if` and `repeat`, in agent order.
-- One eligible flow and no run asking: it starts without being scored. The understand call is skipped altogether when there is nothing else to judge: no mention flows, no `when` branches, no unknown `'anywhere'` field.
-- Several: the understand call scores each from 0 to 100. With no run asking, the top flow starts if it scores 40 or more; otherwise the first eligible `message: []` flow starts, if there is one.
+- No run asking: the understand call scores each eligible flow from 0 to 100, a lone one included. The top flow starts if it scores 40 or more; otherwise the first eligible `message: []` flow starts, if there is one.
+- One exception: a single eligible flow, with no `message: []` flow passing and `idle: 'silent'`, starts without being scored, because a low score would leave the customer with no reply. The understand call is then skipped altogether when there is nothing else to judge: no mention flows, no `when` branches, no unknown `'anywhere'` field.
 - A run is asking: it keeps the floor unless another flow scores at least 15 above it and at least 40. Then that flow starts, or its suspended run resumes, and the asker is suspended.
 - The catch-all `message: []` is never scored. It obeys `if` and `repeat` like any trigger, so with the default `'once'` it fires once per session. When nothing starts and no run is asking, the idle speaker answers.
 

package/docs/rfc/v4-one-flow.md

@@ -239,7 +239,7 @@ type TurnInput<C, D, E> = {
 interface TurnResult<D> {
   session: Session<D>; changed: boolean;             // changed: false → save nothing
   messages: Array<{ text: string; kind: 'ai' | 'verbatim'; media?: { slug: string }; afterMs: number; key: string; runId?: string; stepId?: string }>;
-  schedule: Array<{ key: string; at: Date; replaces?: string }>;   // jobId = key; at fire: turn({ wake: key })
+  schedule: Array<{ key: string; at: Date; replaces?: string }>;   // job id = the key, encoded (BullMQ refuses ':'); at fire: turn({ wake: key })
   outcomes: StepOutcome[];
   started: Array<{ runId: string; flowId: string; anchor: string; dedupeKey: string }>;
   ended: Array<Run & { reason: 'end' | 'flow' | 'reset' | 'skipped' | 'failed' | 'replaced' }>;
@@ -265,7 +265,7 @@ Eight phases, one order for every input; only 3 and 6 spend LLM calls. `turn()`
    - `wake` starting with `silence:`: honored only when its `lastAssistantAtMs` equals `session.lastAssistantAt` and the lead has not written since (`lastUserAt`, and the anchor's `lastInboundAt` for lead-anchored flows, both `< lastAssistantAt`); it then goes through the start order below with `trigger.kind: 'silence'`. Otherwise `ignorado: silêncio quebrado`, `changed: false`. Any other `wake`: the run whose `waiting.key` equals it, else `ignorado: wake antigo`. A timer `wait` with `else` whose lead wrote after `waiting.setAt` takes `else` — the reply beat the job.
    - `event` / `start`: flows with a matching trigger start, in this order: `if` (payload as `input`) → `repeat` via claims (cooldown = interval check on `claims[key].at`) → `hop < 5` else `pulado: limite de encadeamento` → one active run per (flow, anchor) against `session.runs` and `claims.active`: a live run still parked on its own `after` timer is **replaced** (`ended.reason: 'replaced'`, its job self-skips), any other live run → `pulado: já em andamento` → `after` parks the new run.
    - Every run about to move re-checks `while` with fresh context; false → ends `pulado: premissa mudou`. Silence-triggered runs add the premise "no lead message since the run started" → `pulado: lead escreveu nesse meio-tempo`.
-3. **Understand** (≤1 call, `schemaName: 'understand'`). Only for `message` and inbound events with text; skipped under `silenced` unless `understand: true`, and when nothing is AI-conditioned. Candidates: the floor holder's flow (always, whatever its trigger), `message` flows passing `if` + `repeat`, `mention` flows with non-empty `mention` passing `if` + `repeat`. Envelope, every property required and nullable: `{ flows: { id: 0-100 }, mentions: { id: boolean }, extract: { id: {...} }, branches: { 'runId/stepId/i': boolean }, fields: { every pending field with extract 'anywhere' } }`. Shortcuts: exactly one eligible `message` flow and no floor → it starts, no scoring; zero candidates and zero pending fields → zero calls (S9).
+3. **Understand** (≤1 call, `schemaName: 'understand'`). Only for `message` and inbound events with text; skipped under `silenced` unless `understand: true`, and when nothing is AI-conditioned. Candidates: the floor holder's flow (always, whatever its trigger), `message` flows passing `if` + `repeat`, `mention` flows with non-empty `mention` passing `if` + `repeat`. Envelope, every property required and nullable: `{ flows: { id: 0-100 }, mentions: { id: boolean }, extract: { id: {...} }, branches: { 'runId/stepId/i': boolean }, fields: { every pending field with extract 'anywhere' } }`. Shortcuts: exactly one eligible `message` flow, no floor, no catch-all passing and `idle: 'silent'` → it starts, no scoring (with a catch-all or the idle speaker, a low score has somewhere to go, so it is scored); zero candidates and zero pending fields → zero calls (S9).
 4. **Decide** (code). Runs starting this turn apply `clearOnStart` first. Extracted values are checked: unknown keys dropped (`ignorado: campo desconhecido`), strings coerced to number/boolean, enum membership enforced, otherwise `campo descartado: valor fora da lista`; then written to `session.data` (one `known`: not `undefined | null | ''`). Mention runs start in flow order (a trigger `if` with `extract` sees `input` now); `mention: []` code-only detectors start here without the call. The first true branch of the asking step takes its `then`. Routing: if a run took or resumed the floor in Ingest, routing is skipped (scores recorded, not applied). Otherwise the floor (any run `running`/`asking`, not `waiting`) stays unless another flow scores ≥ current + 15 and ≥ 40; no floor → best ≥ 40 starts (a `suspended` run of that flow resumes instead), then a `message: []` catch-all, else the `idle` speaker.
 5. **Run** (code). If no run is `asking`, the most recently `suspended` returns to `asking`. The Runner advances every run that can move, oldest first, through `advance()`: `do` runs the handler with `key = ${runId}:${stepId}:${visit}` (`run.visits[stepId]` increments on entry; at-least-once, before the save); `failed` writes a `failed` outcome and continues to `then` unless `onFail`; `skipped` continues; `defer` re-parks under a fresh wake key; `spoke: true` makes it the turn's speaker. `say` appends a message (`once` → claim `${flowId}:${stepId}:${sessionId}`). `wait ≤ 10s` carries as `afterMs` to the next message emitted this turn, or schedules a real wake if none follows; longer waits park with `waiting` and a `schedule` entry, snapped by `businessHours`. `if` picks `then`/`else`. A talk step whose fields are all known is skipped (0 calls); otherwise it is queued for phase 6 and the current asker becomes `suspended` (a run started this turn by routing never suspends one that took the floor in Ingest). Flow missing from the agent → `pulado: fluxo desativado ou removido`; step missing → `pulado: passo removido`. Caps: 50 steps per run per turn → `falhou: laço de passos`; hop 5.
 6. **Speak** (≤1 call + tool rounds, `schemaName: 'speak'`). One talk step speaks. Talk step = `prompt`, `collect`, `say`. Rules: a `say` or `spoke: true` emitted this turn by a run **other than** the floor holder, in reply to a user message, silences the floor's talk (`pulado: outra resposta já saiu`; the run stays `asking`) — a run's own `say` never silences its own talk. Under `silenced` no message-producing step runs and no run advances past one: an `asking` run stays `asking`; a run whose talk step was reached by a wake, event or start ends `silenciado: <reason>` (an earlier `if: { silenced: true }` routes around it); `do` steps still run; zero calls. Prompt = identity + flow + step guideline + this step's pending fields with their `ask` (all of them; the step prompt says how many to ask) + known fields as facts + tools + instructions + history. A wake states *não há mensagem nova do cliente; você fala primeiro*. Envelope `{ message, ...pending fields of this step }`, all required and nullable, shallow-merged last-wins across tool rounds. Provider failure: in phase 3 the turn throws `ProviderError` (nothing ran, nothing saved; the host retries the input); in phase 6 the turn returns with the talk step re-parked under `${runId}:${stepId}:${visit}:retry:${atMs}` (+1m, +5m, +15m), outcome `deferred: IA indisponível`, session saved, phase 5 effects not repeated.
@@ -304,7 +304,7 @@ interface Store<D> { load(id: string): Promise<Session<D> | null>; save(session:
 
 **Keys.** Trigger key: `message`/`mention` → the input `id` (playground: `at`, replays not idempotent); `silence` → `lastAssistantAtMs`; `event`/`start` → the host key; `flow` → `${parentRunId}:${stepId}:${visit}`. Wake key: `${runId}:${stepId}:${atMs}`. Dedupe key `${flowId}:${anchor}:${nonce}`, nonce `''` for `once` and cooldown (blocked while `now - claims[key].at < cooldown`, else overwritten), the trigger key for `always` (last 50 kept).
 
-**Host contract:** (a) one `turn` per session at a time; a wake queues behind a debounced inbound not yet turned. (b) On every input: fresh `context`, `history`, `anchors` (with the lead's `lastInboundAt`), `claims` for non-`always` flows, `silenced` for every "cannot speak now" reason (ownership, Pausa, closed 24h window, quota, `sem conversa`); inbound messages carry the channel `id` and `at`. (c) `changed: false` → nothing. Else one transaction: `store.save`, `started[].dedupeKey` into a unique index, `started`/`ended` into a partial unique index `(flowId, anchor) WHERE live`, `outcomes`/`ended`/`skipped` into the `flowRuns` mirror, `messages[]` and `schedule[]` into the outbox. Conflict or unique violation → discard, replay. (d) Drain the outbox: send honoring `afterMs`, record a refused send against `key` in the mirror (`enviada`/`recusada` beside the framework's `gerada`); enqueue wakes with `jobId = key`, `queue.remove(replaces)` best-effort. (e) At fire: `turn({ wake, silenced })`. (f) Call `turn` for every inbound even while a human owns the lead. (g) `businessHours(at)` snaps, never clamps. (h) Lead-level events go to the lead's latest open conversation; none → session `lead:<id>` with `silenced: 'sem conversa'`. (i) `ProviderError` → retry the input with backoff.
+**Host contract:** (a) one `turn` per session at a time; a wake queues behind a debounced inbound not yet turned. (b) On every input: fresh `context`, `history`, `anchors` (with the lead's `lastInboundAt`), `claims` for non-`always` flows, `silenced` for every "cannot speak now" reason (ownership, Pausa, closed 24h window, quota, `sem conversa`); inbound messages carry the channel `id` and `at`. (c) `changed: false` → nothing. Else one transaction: `store.save`, `started[].dedupeKey` into a unique index, `started`/`ended` into a partial unique index `(flowId, anchor) WHERE live`, `outcomes`/`ended`/`skipped` into the `flowRuns` mirror, `messages[]` and `schedule[]` into the outbox. Conflict or unique violation → discard, replay. (d) Drain the outbox: send honoring `afterMs`, record a refused send against `key` in the mirror (`enviada`/`recusada` beside the framework's `gerada`); enqueue wakes under a job id made from the key (encoded: BullMQ refuses a `:` in a custom id), remove `replaces` the same way, best-effort. (e) At fire: `turn({ wake, silenced })`. (f) Call `turn` for every inbound even while a human owns the lead. (g) `businessHours(at)` snaps, never clamps. (h) Lead-level events go to the lead's latest open conversation; none → session `lead:<id>` with `silenced: 'sem conversa'`. (i) `ProviderError` → retry the input with backoff.
 
 ```ts
 const clock = fakeClock('2026-09-20T10:00Z');
@@ -420,7 +420,7 @@ const criarFluxo = tool({
 
 **S8 Scheduling.** `on: [{ message: ['quer marcar', 'quer remarcar'], repeat: 'always' }]`, `clearOnStart: ['data_preferida', 'horario_preferido', 'agenda_event_id', 'confirmado']` (applied before "sexta às 15h" lands), collect with agenda tools, `{ collect: ['confirmado'], ask: { confirmado: 'Confirme a data e o horário em uma frase.' } }`, `do book`, last step `then: { flow: 'pos-agendamento' }`.
 
-**S9 Config assistant.** Zero flows, zero fields → understand skipped → one speak call with tools. Interview mode: one `message` flow → single-flow shortcut, no scoring; collect steps skip when known.
+**S9 Config assistant.** Zero flows, zero fields → understand skipped → one speak call with tools. Interview mode: one `message` flow and `idle: 'silent'` → single-flow shortcut, no scoring; collect steps skip when known.
 
 **S10.** §8.
 
@@ -458,7 +458,7 @@ async function runTurn(sessionId: string, input: TurnInputBody) {
         await outbox.put(tx, r.messages, r.schedule);                              // wakes ride in the same transaction
       });
     } catch (e) { if (e instanceof SessionConflictError || isUniqueViolation(e)) continue; throw e; }
-    await outbox.drain(sessionId);                                                 // send honoring afterMs, enqueue wakes jobId = key
+    await outbox.drain(sessionId);                                                 // send honoring afterMs, enqueue wakes under the encoded key
     return;
   }
 }

package/docs/start/04-add-tools.md

@@ -174,7 +174,7 @@ const agent = f.agent({
 
 `parameters` use the same `type`, `enum` and `description` as fields (plus `optional: true`), and `run` receives them already typed: `mensagem` is a `string` above, nothing to check.
 
-`with` fills the parameters. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced before the action runs. A placeholder whose value is unknown stays as written, so a skipped `tamanho` reaches the seller as `{{data.tamanho}}`. Word the message without it, or fork first with an `if` step on `{ known: ["tamanho"] }`. A `do` step never talks to the model: zero calls.
+`with` fills the parameters. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced before the action runs. A placeholder whose value is unknown stays as written, so a skipped `tamanho` reaches the seller as `{{data.tamanho}}`. One the host filled with an empty string drops out instead. Word the message without it, or fork first with an `if` step on `{ known: ["tamanho"] }`. A `do` step never talks to the model: zero calls.
 
 The name and the parameters are checked when the agent is built. An unknown action, or a `with` missing a required parameter, throws `FlowConfigurationError` at startup with the step id and the fix.
 

package/docs/start/05-go-to-production.md

@@ -170,7 +170,7 @@ A `wait` longer than 10 seconds, a `silence` trigger or an `event` trigger with
 { key: "triagem#wamid.HBgL:w1:1790244000000", at: new Date("2026-09-24T10:00:00.000Z") }
 ```
 
-A `silence` trigger's wake also carries `replaces`: the earlier silence wake it supersedes. Put the entry in your queue with `jobId = key` and the session id in the payload. When `replaces` is set, remove that job; it is best effort, a stale wake is harmless. When the job fires:
+A `silence` trigger's wake also carries `replaces`: the earlier silence wake it supersedes. Put the entry in your queue with the key and the session id in the payload, under a job id made from the key: every key contains `:`, and BullMQ refuses a custom job id with a `:` in it unless it splits into exactly three parts, so encode it as `encodeURIComponent(key)`. When `replaces` is set, remove the job whose id is `encodeURIComponent(replaces)`; it is best effort, a stale wake is harmless. When the job fires:
 
 ```ts fragment
 await handle({ sessionId: job.data.sessionId, wake: job.data.key });
@@ -178,6 +178,21 @@ await handle({ sessionId: job.data.sessionId, wake: job.data.key });
 
 Only the run still waiting on that exact key honours the wake. Anything else returns `changed: false` with one line in `r.outcomes`: `code: 'stale-wake'` for a wait that a reply already resolved, `code: 'silence-broken'` when the customer wrote after the silence wake was set, `code: 'no-session'` when there is no session. So you do not have to cancel jobs: fire every one and the framework drops the stale ones.
 
+### When the queue loses its jobs
+
+A flushed Redis, or sessions lifted from 3.x by `migrateSession`, leave conversations waiting on wakes nobody will fire. `agent.pendingWakes({ session, context })` returns every wake a saved session waits on: each parked run's, and each silence flow's counted from `lastAssistantAt`, with the trigger's `if` and `repeat` judged on the `context` and `claims` you pass, as a turn would. It changes nothing and spends no model call. Enqueue what it returns as you would a turn's `schedule[]`:
+
+```ts fragment
+for (const wake of agent.pendingWakes({ session, context })) {
+  await queue.add("wake", { sessionId: session.id, key: wake.key }, {
+    jobId: encodeURIComponent(wake.key),
+    delay: Math.max(0, wake.at.getTime() - Date.now()),
+  });
+}
+```
+
+Running it twice is safe: BullMQ ignores a job whose id is already queued, and a wake that fires twice is dropped the second time as stale.
+
 `fakeClock` and `MemoryScheduler` are the test doubles for this: [Testing](../guides/testing.md) plays a two-day follow-up in one test.
 
 ## On every input

package/examples/06-triggers-and-waits.ts

@@ -117,9 +117,10 @@ const agent = f.agent({
 });
 
 // ─── The host loop ─────────────────────────────────────────────────────────
-// Real hosts persist `session`, enqueue each `schedule[]` entry with
-// `jobId = key`, and call `turn({ wake: key })` when it fires. Here we keep
-// them in memory and jump the clock.
+// Real hosts persist `session`, enqueue each `schedule[]` entry under the job
+// id `encodeURIComponent(key)` (BullMQ refuses a `:` in a custom id), and call
+// `turn({ wake: key })` when it fires. Here we keep them in memory and jump
+// the clock.
 
 const context: Ctx = { lead: { id: "456", nome: "Ana", etapa: "proposta", dono: "ia", tags: [] } };
 const timers: ScheduleEntry[] = [];

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@falai/agent",
-  "version": "4.0.0-alpha.1",
+  "packageManager": "bun@1.4.2",
+  "version": "4.0.0-alpha.10",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -59,7 +60,8 @@
     "release:alpha": "bun publish --tag alpha",
     "release": "bun publish",
     "test": "bun test tests/*.test.ts tests/scenarios/*.test.ts",
-    "eval:live": "bun run scripts/eval/live.ts"
+    "eval:live": "bun run scripts/eval/live.ts",
+    "eval:exclusions": "bun run scripts/eval/exclusions.ts"
   },
   "keywords": [
     "ai",
@@ -95,7 +97,7 @@
     "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
-    "@providerkit/core": "^0.11.0",
+    "@providerkit/core": "^0.11.1",
     "loglevel": "^1.9.2"
   },
   "peerDependencies": {

package/src/core/Agent.ts

@@ -7,7 +7,7 @@
  * provider call apiece, and Runner settles what they returned.
  */
 
-import type { AgentOptions, TurnInput, TurnResult, TurnStreamChunk } from "../types/agent.js";
+import type { AgentOptions, PendingWakesInput, ScheduleEntry, TurnInput, TurnResult, TurnStreamChunk } from "../types/agent.js";
 import type { TokenUsage } from "../types/ai.js";
 import type { CompactionOptions } from "../types/compaction.js";
 import { FlowConfigurationError } from "../types/errors.js";
@@ -56,6 +56,16 @@ export class Agent<C = unknown, D = unknown> {
     yield { done: true, result: this.runner.finish(turn) };
   }
 
+  /**
+   * Every wake a saved session is waiting on, as its turns scheduled them: each parked run's,
+   * and each silence flow's since the assistant last spoke. For a queue that lost its jobs, and
+   * for sessions no turn has armed yet, such as blobs lifted by `migrateSession`. It changes
+   * nothing and spends no call: enqueue the entries as you would a turn's `schedule[]`.
+   */
+  pendingWakes(input: PendingWakesInput<C, D>): ScheduleEntry[] {
+    return this.runner.pendingWakes(input);
+  }
+
   /** Load, Ingest, Understand, Decide and Run: everything before the one speaker is known. */
   private async open(input: TurnInput<C, D>): Promise<{ turn: Turn<C, D>; talk: TalkRequest<C, D> | IdleRequest<C, D> | null }> {
     const { runner } = this;

package/src/core/FlowSpec.ts

@@ -43,6 +43,7 @@ import type {
 } from "../types/flow.js";
 import type { StructuredSchema } from "../types/schema.js";
 import { isDuration } from "../utils/duration.js";
+import { splitPhrases } from "../utils/phrases.js";
 import { toWireSchema } from "../utils/schema.js";
 
 // ── The JSON form ───────────────────────────────────────────────────────
@@ -233,6 +234,8 @@ interface LooseInstruction {
 }
 interface LooseTrigger {
   repeat?: Repeat;
+  message?: string[];
+  mention?: string[];
   event?: string;
   silence?: Duration;
   after?: Duration;
@@ -248,6 +251,7 @@ interface LooseStep {
   ask?: Partial<Record<string, string>>;
   branches?: LooseBranch[];
   instructions?: LooseInstruction[];
+  say?: Template;
   do?: string;
   with?: Record<string, unknown>;
   wait?: Duration | { event: string; upTo?: Duration };
@@ -268,6 +272,12 @@ const BUILT_IN_CONDITIONS = ["equals", "known", "silenced"];
 
 const DURATION_HINT = 'Write a number and a unit: "30s", "5m", "24h" or "3d".';
 
+/** The four keys one of which makes an `on[]` entry a trigger. */
+const TRIGGER_KINDS = ["message", "mention", "silence", "event"] as const;
+
+/** The six keys one of which makes a step do something. */
+const STEP_DOES = ["prompt", "collect", "say", "do", "wait", "if"] as const;
+
 /**
  * Check a flow, typed or as a spec, against the agent's registries. Throws
  * `FlowConfigurationError` on the first problem that would break at runtime;
@@ -400,11 +410,8 @@ export function validateFlow<C = unknown, D = LooseData>(
         continue;
       }
       if (!matchesParam(def, value)) {
-        throw problem(
-          at,
-          `parameter "${param}" of action "${name}" must be ${describeDef(def)}, got ${describe(value)}`,
-          "Values are not coerced; write the right type.",
-        );
+        const { expected, got, fix } = mismatch(def, value);
+        throw problem(at, `parameter "${param}" of action "${name}" must be ${expected}, got ${got}`, fix);
       }
     }
     for (const param of Object.keys(given)) {
@@ -421,6 +428,18 @@ export function validateFlow<C = unknown, D = LooseData>(
 
   flow.on?.forEach((trigger, i) => {
     const at = `${flowAt}, trigger #${i + 1}`;
+    // A trigger that names no kind can never fire, and nothing downstream says
+    // so: the Runner simply never finds it eligible and the flow looks broken
+    // for some other reason. `{ kind: 'message', when: [...] }` — the v3 shape —
+    // lands here, and so does a typo in the one key that matters.
+    if (!TRIGGER_KINDS.some((key) => trigger[key] !== undefined)) {
+      throw problem(
+        at,
+        "names no trigger kind",
+        `A trigger is one of ${TRIGGER_KINDS.map((key) => `\`${key}\``).join(", ")}. ` +
+          "A flow the host starts itself has no `on` at all.",
+      );
+    }
     if (trigger.event !== undefined && !own(events, trigger.event)) {
       throw problem(at, `unknown event "${trigger.event}"`, "Register it in events or fix the name.");
     }
@@ -428,10 +447,36 @@ export function validateFlow<C = unknown, D = LooseData>(
     duration(trigger.after, at, "after");
     if (typeof trigger.repeat === "object") duration(trigger.repeat.cooldown, at, "repeat.cooldown");
     pred(trigger.if, at, "if");
+    // Phrases opening with `!` rule the trigger out; a list of nothing but
+    // those can never fire, so the flow is dead and nothing would say so.
+    // `message: []` is the deliberate catch-all and stays legal.
+    for (const key of ["message", "mention"] as const) {
+      const phrases: string[] | undefined = trigger[key];
+      if (!phrases?.length) continue;
+      if (splitPhrases(phrases).counts.length > 0) continue;
+      throw problem(
+        at,
+        `every ${key} phrase starts with "!", so nothing can ever match it`,
+        `A "!" phrase rules the trigger out. Add at least one plain phrase saying when it should fire${
+          key === "message" ? ", or use an empty list for a catch-all" : ""
+        }.`,
+      );
+    }
   });
 
   flow.steps.forEach((step, i) => {
     const at = `${flowAt}, step "${step.id}"`;
+    // Same reasoning as the trigger above: a step that does none of the five
+    // things is a step the run walks straight past, silently. `kind` alone is
+    // not enough — the spec form drops it and keeps the body, so what counts
+    // is whether the body says what to do.
+    if (!STEP_DOES.some((key) => step[key] !== undefined)) {
+      throw problem(
+        at,
+        "does nothing",
+        "A step talks (`prompt` / `collect`), says (`say`), acts (`do`), waits (`wait`) or forks (`if`).",
+      );
+    }
     const thenTo = edge(i, step.then, at, "then");
     edge(i, step.else, at, "else");
 
@@ -506,12 +551,33 @@ function matches(def: ScalarDef, value: unknown): boolean {
   return typeof value !== "boolean" && def.enum.includes(value);
 }
 
+/**
+ * What a rejected value should have been and what it was. A value of the right type that is
+ * not a listed one names the listed values: "must be a string, got string" would say nothing.
+ */
+function mismatch(def: ParamDef, value: unknown): { expected: string; got: string; fix: string } {
+  const scalar = def.type === "array" ? def.items : def;
+  const { enum: allowed, ...typeOnly } = scalar;
+  const items = def.type === "array" && Array.isArray(value) ? value : [value];
+  const off = allowed ? items.findIndex((item) => matches(typeOnly, item) && !matches(scalar, item)) : -1;
+  if (!allowed || off === -1) {
+    return { expected: describeDef(def), got: describe(value), fix: "Values are not coerced; write the right type." };
+  }
+  const list = (v: unknown) => JSON.stringify(v);
+  return { expected: `one of ${allowed.map(list).join(", ")}`, got: list(items[off]), fix: "Use one of the listed values." };
+}
+
 function describe(value: unknown): string {
   return Array.isArray(value) ? "list" : value === null ? "null" : typeof value;
 }
 
 function describeDef(def: ParamDef): string {
-  return def.type === "array" ? `a list of ${def.items.type}` : `a ${def.type}`;
+  return def.type === "array" ? `a list of ${def.items.type}s` : `${article(def.type)} ${def.type}`;
+}
+
+/** "an integer", "a string". A vowel test rather than one hard-coded type, so a new type reads right for free. */
+function article(type: string): string {
+  return /^[aeiou]/.test(type) ? "an" : "a";
 }
 
 // ── flowSpecSchema ──────────────────────────────────────────────────────

package/src/core/Prompt.ts

@@ -9,6 +9,7 @@
 
 import type { AgentOptions } from "../types/agent.js";
 import type { FieldDef, Instruction } from "../types/flow.js";
+import { splitPhrases } from "../utils/phrases.js";
 import { isKnown } from "../utils/schema.js";
 import { render, type TemplateScope } from "../utils/template.js";
 
@@ -106,7 +107,12 @@ export function instructionsSection<C, D>(groups: InstructionGroup<C, D>[], scop
       const text = render(item.prompt, scope).trim();
       if (!text) continue;
       const when = item.when === undefined ? [] : Array.isArray(item.when) ? item.when : [item.when];
-      const condition = when.length ? ` (apply only when: ${when.join(" OR ")})` : "";
+      const { counts, excludes } = splitPhrases(when);
+      const clauses = [
+        ...(counts.length ? [`apply only when: ${counts.join(" OR ")}`] : []),
+        ...(excludes.length ? [`never when: ${excludes.join(" OR ")}`] : []),
+      ];
+      const condition = clauses.length ? ` (${clauses.join("; ")})` : "";
       lines.push(`- [${item.kind ?? "should"}] ${group.caption} ${text}${condition}`);
     }
   }

package/src/core/Runner.ts

@@ -8,7 +8,7 @@
  *   begin ─▶ understandRequest ─(Understand)─▶ decide ─▶ advance ─(Speak)─▶ settle ─▶ finish
  */
 
-import type { AgentOptions, EndReason, TurnInput, TurnResult } from "../types/agent.js";
+import type { AgentOptions, EndReason, PendingWakesInput, ScheduleEntry, TurnBase, TurnInput, TurnResult } from "../types/agent.js";
 import type { TokenUsage } from "../types/ai.js";
 import type { ActionResult, Branch, DoStep, Duration, Flow, IfStep, Next, Pred, PredCtx, Repeat, SayStep, Step, StepBase, TalkStep, Trigger, WaitEventStep, WaitStep } from "../types/flow.js";
 import type { History } from "../types/history.js";
@@ -49,7 +49,7 @@ export type What =
 
 /** The mutable per-turn state. `session` is a deep copy; the input is never touched. */
 export interface Turn<C = unknown, D = unknown> {
-  readonly input: TurnInput<C, D>;
+  readonly input: TurnBase<C, D>;
   readonly what: What;
   readonly kind: InputKind;
   /** Message id, wake key, event key or start key: the trigger key of runs started this turn. */
@@ -171,11 +171,26 @@ export class Runner<C = unknown, D = unknown> {
   // ── Load + Ingest ─────────────────────────────────────────────────────
 
   begin(input: TurnInput<C, D>): Turn<C, D> {
-    const now = (this.options.clock ?? (() => new Date()))();
+    const now = this.now();
+    const turn = this.open(input, describe(input, now.toISOString()), now);
+    if (turn.what.kind === "wake" && !input.session) {
+      this.ignore(turn, "no-session", turn.what.key);
+      return turn;
+    }
+    turn.ingesting = true;
+    this.ingest(turn);
+    turn.ingesting = false;
+    return turn;
+  }
+
+  private now(): Date {
+    return (this.options.clock ?? (() => new Date()))();
+  }
+
+  private open(input: TurnBase<C, D>, what: What, now: Date): Turn<C, D> {
     const nowIso = now.toISOString();
-    const what = describe(input, nowIso);
     const silenced = typeof input.silenced === "string" ? input.silenced : input.silenced?.reason;
-    const turn: Turn<C, D> = {
+    return {
       input,
       what,
       kind: what.kind,
@@ -204,14 +219,17 @@ export class Runner<C = unknown, D = unknown> {
       speakDone: false,
       queue: [],
     };
-    if (what.kind === "wake" && !input.session) {
-      this.ignore(turn, "no-session", what.key);
-      return turn;
-    }
-    turn.ingesting = true;
-    this.ingest(turn);
-    turn.ingesting = false;
-    return turn;
+  }
+
+  /** Every wake the session waits on: each parked run's own, then each silence flow's since the assistant last spoke. */
+  pendingWakes(input: PendingWakesInput<C, D>): ScheduleEntry[] {
+    // No input arrives, so nothing reads `what`: the inert wake shape only fills the field.
+    const turn = this.open({ ...input, sessionId: input.session.id }, { kind: "wake", key: "" }, this.now());
+    // `park` always sets both; the type leaves them optional, so a hand-built blob without them has no wake to give.
+    const parked = turn.session.runs.flatMap(({ status, waiting }) =>
+      status === "waiting" && waiting?.key && waiting.until ? [{ key: waiting.key, at: new Date(waiting.until) }] : [],
+    );
+    return [...parked, ...this.silenceWakes(turn)];
   }
 
   private ingest(turn: Turn<C, D>): void {
@@ -508,8 +526,7 @@ export class Runner<C = unknown, D = unknown> {
     const floorRun = this.floorRun(turn);
     const floorFlow = floorRun && this.flows.get(floorRun.flowId);
     const eligible = this.eligibleMessageFlows(turn);
-    // Exactly one eligible message flow and no floor: it starts without scoring (S9).
-    const messageFlows = !floorRun && eligible.length === 1 ? [] : eligible;
+    const messageFlows = !floorRun && this.startsUnscored(turn, eligible) ? [] : eligible;
     const mentionFlows = this.mentionFlows()
       .filter(({ flow, trigger }) => trigger.mention.length > 0 && this.repeatAllows(turn, flow, trigger, turn.triggerKey))
       .map(({ flow }) => flow);
@@ -562,6 +579,14 @@ export class Runner<C = unknown, D = unknown> {
     return this.messageFlows(turn, (list) => list.length > 0);
   }
 
+  /**
+   * The lone eligible flow starts without a score only when a low score would have nowhere
+   * else to send the message: no catch-all passes and the idle speaker is silent (S9).
+   */
+  private startsUnscored(turn: Turn<C, D>, eligible: Flow<C, D>[]): boolean {
+    return eligible.length === 1 && this.options.idle === "silent" && this.messageFlows(turn, (list) => list.length === 0).length === 0;
+  }
+
   private messageFlows(turn: Turn<C, D>, accept: (list: string[]) => boolean): Flow<C, D>[] {
     const out: Flow<C, D>[] = [];
     for (const flow of this.flows.values()) {
@@ -605,7 +630,7 @@ export class Runner<C = unknown, D = unknown> {
         const current = scores[asker.flowId] ?? 0;
         const top = best(eligible.filter((f) => f.id !== asker.flowId));
         if (top && top.score >= current + ROUTE_STICKY && top.score >= ROUTE_MIN) route = top.flow;
-      } else if (eligible.length === 1) {
+      } else if (this.startsUnscored(turn, eligible)) {
         route = eligible[0];
       } else {
         const top = best(eligible);
@@ -1139,14 +1164,21 @@ export class Runner<C = unknown, D = unknown> {
     return new Date(reset !== undefined && reset > ladder ? reset : ladder);
   }
 
-  /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+  /** The assistant spoke this turn: its silence wakes replace the ones its last words set. */
   private armSilence(turn: Turn<C, D>): void {
+    const previous = turn.original?.lastAssistantAt;
+    if (turn.session.lastAssistantAt === previous) return;
+    turn.schedule.push(...this.silenceWakes(turn, previous));
+  }
+
+  /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+  private silenceWakes(turn: Turn<C, D>, previous?: string): ScheduleEntry[] {
     const { session } = turn;
     const { lastAssistantAt, lastUserAt } = session;
-    if (!lastAssistantAt || lastAssistantAt === turn.original?.lastAssistantAt) return;
-    if (lastUserAt && Date.parse(lastUserAt) > Date.parse(lastAssistantAt)) return;
+    if (!lastAssistantAt) return [];
+    if (lastUserAt && Date.parse(lastUserAt) > Date.parse(lastAssistantAt)) return [];
     const ms = Date.parse(lastAssistantAt);
-    const previous = turn.original?.lastAssistantAt;
+    const wakes: ScheduleEntry[] = [];
     for (const flow of this.flows.values()) {
       const trigger = (flow.on ?? []).find((t): t is SilenceTrigger<C, D> => "silence" in t);
       if (!trigger) continue;
@@ -1154,12 +1186,13 @@ export class Runner<C = unknown, D = unknown> {
       if (trigger.if && !this.holds(trigger.if, turn, this.draftRun(turn, flow, "silence", key))) continue;
       if (!this.repeatAllows(turn, flow, trigger, key)) continue;
       const at = this.snap(turn, new Date(ms + parseDuration(trigger.silence)), trigger.businessHours);
-      turn.schedule.push({
+      wakes.push({
         key: `silence:${flow.id}:${session.id}:${ms}`,
         at,
         ...(previous ? { replaces: `silence:${flow.id}:${session.id}:${Date.parse(previous)}` } : {}),
       });
     }
+    return wakes;
   }
 
   // ── Return (design §4.8) ──────────────────────────────────────────────