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

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

@@ -65,7 +65,7 @@ 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
   }
 }
 ```
@@ -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.
@@ -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.
 

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 |
@@ -65,7 +85,7 @@ The run starts beside the conversation. It is meant for `do` and `say` steps: it
 | `event` | `string` | required | The event's name in the agent's `events`. |
 | `after` | `Duration` | none | Park the run this long before its first step. |
 | `if` | `Pred<C, D>` | none | Judged when the event arrives, with the payload as `input`. |
-| `businessHours` | `boolean` | `false` | Snap the `after` wake forward. |
+| `businessHours` | `boolean` | `false` | Start only in working hours: snap the start (now, or now + `after`) forward with the agent's `businessHours`. |
 | `repeat` | `Repeat` | `'always'` | |
 
 The event's `payload` is the run's `input`.
@@ -96,15 +116,15 @@ Pass a real message `id` on every message turn. Only `id` is checked against the
 
 **Dedupe key.** `${flowId}:${anchor}:${nonce}`. The nonce is the trigger key when `repeat` is `'always'` and empty otherwise. It is written to `session.claims` when the run starts, given to actions as `ctx.dedupeKey`, and returned in `started[]`. The last 50 `'always'` claims per flow and anchor are kept; `'once'` and cooldown claims are never pruned. The host may pass claims from the customer's other sessions in `turn({ claims })`; they count the same.
 
-**Wake for `after`.** `${runId}:start:${atMs}`, where `atMs` is the fire time in milliseconds after `businessHours` snapping. The run is returned in `started[]` at once with the outcome `code: 'awaiting-trigger'`. At the wake it enters its first step. A second event for the same flow and anchor while it is parked replaces it: the parked run ends with reason `'replaced'`.
+**Wake for `after`.** `${runId}:start:${atMs}`, where `atMs` is the fire time in milliseconds after `businessHours` snapping. With `businessHours: true` and no `after`, the same wake parks a run whose event arrives outside working hours; inside them it starts at once. The run is returned in `started[]` at once with the outcome `code: 'awaiting-trigger'`. At the wake it enters its first step. A second event for the same flow and anchor while it is parked replaces it: the parked run ends with reason `'replaced'`.
 
 **Wake for silence.** `silence:${flowId}:${sessionId}:${lastAssistantAtMs}`. Armed at the end of every turn in which the assistant spoke and the customer has not written since, for every silence flow passing `if` and `repeat`; the entry's `replaces` names the previous silence wake. At fire time it is honoured only while `session.lastAssistantAt` still equals that timestamp and the customer has not written since (`code: 'silence-broken'` otherwise).
 
 ## 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.11",
   "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}`);
     }
   }