@falai/agent 4.0.0-alpha.8 → 4.0.0

package/docs/reference/flow.md

@@ -19,6 +19,7 @@ interface Flow<C = unknown, D = unknown> {
   on?: Trigger<C, D>[];
   anchor?: string;
   while?: Pred<C, D>;
+  collect?: (keyof D & string)[];
   clearOnStart?: (keyof D & string)[];
   steps: Step<C, D>[];
   onEnd?: "end" | "stay" | "reset";
@@ -37,6 +38,7 @@ interface Flow<C = unknown, D = unknown> {
 | `on` | `Trigger<C, D>[]` | none | What starts a run. Absent or empty: only `turn({ start })` or another flow's `then: { flow }` starts it. See [Trigger](trigger.md). |
 | `anchor` | `string` | `'session'` | What a run is keyed to. `'session'` uses the session id. Any other name reads `input.anchors[name].key`, and falls back to the session id when the host did not pass that anchor. |
 | `while` | `Pred<C, D>` | the trigger's `if` | Re-checked before the run moves. When it stops holding, the run ends with `code: 'premise-changed'`. |
+| `collect` | `(keyof D & string)[]` | none | The data this flow needs, as agent field slugs. Talk steps' `collect` says which of it to ask, and in what order. |
 | `clearOnStart` | `(keyof D & string)[]` | none | Fields forgotten when a run of this flow starts, so a second run asks for them again. |
 | `steps` | `Step<C, D>[]` | required | In order. A run enters `steps[0]` and moves to the next step unless `then` says otherwise. See [Step](step.md). |
 | `onEnd` | `'end' \| 'stay' \| 'reset'` | `'end'` | What the run does after its last step. |
@@ -59,11 +61,13 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 
 **`while`.** Checked every time the run is about to move: at the start of each turn's run phase for a running run, and when an asking run resumes on a message. A parked run (`waiting`) or a suspended one is not checked until it moves again. Without `while`, the check is the trigger's `if`: the run holds while any trigger of the same kind as the one that started it would still fire. A run started by `start` or by another flow has no such trigger, so without `while` it always holds. A silence run also ends, with `code: 'customer-replied'`, when a wake finds that the customer wrote after the run started.
 
+**`collect`.** The flow's data is its `collect` plus every field its talk steps collect. While the flow holds the conversation, or could take it on this message, the understand call notes any of it the customer gives that is still unknown and has `extract: 'anywhere'`. A field no step asks is still noted that way; it is just never asked for. When nobody holds the conversation, the catch-all (`message: []`) that would take the message counts as a flow that could take it. See [Field collection](../concepts/collection.md).
+
 **`clearOnStart`.** Applied at start for every trigger kind, `start` and `{ flow }` chains included. Not applied when `onEnd: 'reset'` restarts the flow: reset keeps the data.
 
 **`onEnd`.**
 - `'end'`: the run ends with reason `'end'`.
-- `'stay'`: the run re-enters the last step (a new visit, so new keys) and stays asking. It speaks that step again on the next message. Meant for a last talk step that answers follow-up questions.
+- `'stay'`: the run goes back to the last talk step it took and stays there, asking. On a branched flow that is the step on its own path; when its log names none, the flow's last talk step. From then on that step answers every message, even when it has nothing left to collect, and each answer is a new visit, so a new key. The steps after it ran once, on the way to the end, and do not run again. If the run finishes on a message nothing has answered yet (no `say`, no `spoke: true`), the step answers it in that same turn. If another run is asking, the staying run waits `suspended` behind it and takes over when that run is done, answering the message that run moved on from without a word. When the customer's message belongs to this run (it was routed to this flow, or it resolved this run's `wait`), the run takes the conversation instead: the other asker is suspended, and this run answers unless its own `say` already did. Its `when` branches are judged on every message and still move the run. Its `if` branches are judged too, except one that leads to `'end'` or to a step the run has already been through: that path already ran and the fact is still true, so it would run again on every message. A field still pending there (a `when` branch took the run to the end before the customer gave it) is asked for on each answer, each with its own key, and `max-asks` is reported once, on the answer that reaches the limit. If the flow is edited off `'stay'` while a run stays, the new `onEnd` applies on that run's next message. A flow with no talk step ends, as with `'end'`.
 - `'reset'`: the run ends with reason `'reset'` and a fresh run of the same flow starts at `steps[0]`, data kept, one hop deeper. A flow that resets forever without asking anything stops at hop 5, with `code: 'hop-limit'`.
 
 **Instructions and tools while speaking.** The speak call sees the agent's instructions, then this flow's, then the step's, each already filtered by its `if`. Tools are the step's `tools`; without one, the flow's `tools`; without that, every agent tool.
@@ -77,7 +81,8 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 - no `id`, or `steps` is not a list
 - a step with no `id`, the id `'end'`, or an id used twice
 - triggers with zero steps
-- an unknown field slug in `clearOnStart`, `collect`, `ask`, `equals`, `known` or a `clear` list
+- an unknown field slug in the flow's `collect`, `clearOnStart`, a step's `collect`, `ask`, `equals`, `known` or a `clear` list
+- a `question` on a talk step that collects nothing
 - an unknown action in `do`; a `with` that misses a required parameter, names one the action does not have, or gives a value of the wrong type (`with` values are not coerced; a `{{template}}` string is accepted for any enum)
 - an unknown event in a trigger or in `wait: { event }`
 - an unknown condition name, or a malformed built-in (`equals` not an object, `known` not a list, `silenced` not a boolean); an `equals` value whose type does not match the field
@@ -87,7 +92,7 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 - a branch with neither `when` nor `if`
 - an `if` step whose `then` jumps backward with no `else`
 
-It returns warnings, logged by the agent, for two things that run but probably not as intended: a jump backward without `clear` (the fields collected since stay known, so those steps skip), and a `collect` step with no `prompt` and no `ask` on any of its fields.
+It returns warnings, logged by the agent, for three things that run but probably not as intended: a jump backward without `clear` (the fields collected since stay known, so those steps skip), a `collect` step with no `prompt`, no `question` and no `ask` on any of its fields, and a field in the flow's `collect` that only an answer can fill (`extract: 'asked'`) when no step asks it.
 
 `toSpec(flow)` throws `FlowConfigurationError` when a predicate is a function, because a function cannot be stored as JSON.
 

package/docs/reference/outcomes.md

@@ -25,7 +25,7 @@ type StepOutcomeCode =
   // A run ended early
   | "step-loop" | "step-gone" | "customer-replied" | "premise-changed" | "silenced"
   // A step
-  | "already-known" | "another-reply" | "already-sent" | "branch" | "max-asks"
+  | "already-known" | "asked-fixed" | "fixed-in-reply" | "another-reply" | "already-sent" | "branch" | "max-asks"
   | "inline-delay" | "awaiting-trigger" | "awaiting-event" | "event-arrived"
   | "no-event" | "replied" | "no-reply"
   // A host action
@@ -134,6 +134,8 @@ Grouped by what produced it. `kind` and `status` are given as `kind / status`. A
 |---|---|---|---|
 | `prompt` or `collect / ok` | none; `llmCalls` set | The speak call answered. The run is asking if fields are still pending, else it moved. | none. This line never carries `next`, even when the run moves on; the lines that follow show where it went |
 | `collect / skipped` | `already-known` | The step was entered and every field it collects was already known (or at `maxAsks`). No call. | `then` |
+| `collect / ok` | `asked-fixed` | The step's `question` went out word for word as its first ask. No call; the run is asking. | |
+| `collect / ok` | `fixed-in-reply`; `llmCalls` set | The customer's message asked something on the step's first ask, so one reply answered it and asked the step's `question`, in its words where they fit. It counts as one ask; the run is asking. | |
 | `collect / ok` | none, no `llmCalls` | An asking step whose remaining fields were all known when the customer's next message resumed it: the understand call filled them in from the message, or an action's `ctx.set()` or a tool's `data` had written them since the step last asked. It moved without speaking. | `then` |
 | `collect / skipped` | `max-asks`, `detail` = the field slug | One line per field still unknown when the step moves on because that field reached `maxAsks` (default 3). | |
 | `prompt` or `collect / ok` | `branch` | A branch of the asking step fired: an `if` branch held, or the model answered `when` with true. | the branch's `then` |
@@ -226,7 +228,7 @@ The run leaves `session.runs`, appears in `TurnResult.ended`, and writes one lin
 | `cooldown` | `repeat: { cooldown }` and the last run is younger than the cooldown. |
 | `already-running` | A live run of this flow exists for this anchor, in this session or (through `turn({ claims })`) in another of the customer's sessions. |
 | `hop-limit` | The start would be at hop 5. `{ flow }` jumps and `onEnd: 'reset'` each add a hop. |
-| `flow-gone` | `turn({ start })`, a silence wake, or a `{ flow }` jump named a flow the agent does not have. |
+| `flow-gone` | `turn({ start })`, a silence wake, or a `{ flow }` jump named a flow the agent does not have. For a literal `{ flow }` id, the agent build also logs a warning. |
 
 A trigger whose `if` is false starts nothing and writes nothing.
 

package/docs/reference/providers.md

@@ -468,7 +468,7 @@ What the adapter does on every call, from `src/providers/ProviderAdapter.ts`:
 3. Merges `defaults`, then `parameters.maxOutputTokens` as `maxTokens` and `parameters.reasoning.effort` as `effort`.
 4. Streams with a silence watchdog of `retryConfig.timeout` ms and `retryConfig.retries + 1` attempts, then moves to the next backup model when the error kind allows.
 5. Folds the chunks: text becomes `delta` chunks, tool call fragments are assembled and their arguments parsed, usage lands on `metadata` (`tokensUsed`, `promptTokens`, `completionTokens`, `cachedInputTokens`).
-6. Parses the accumulated text leniently into `structured`. Text that looks like an envelope but did not parse is dropped rather than handed to the customer. A message that is blank after parsing, with no tool calls, throws `Error: No response from <provider>` — after the retries and backup models, so the caller's path (a deferred speak step, or the host replaying the turn) is what picks it up. A stream that never produced any content is caught earlier, inside the retry, as a `ProviderError` of kind `overload`.
+6. Parses the accumulated text leniently into `structured`. Text that looks like an envelope but did not parse is dropped rather than handed to the customer. A message that is blank after parsing, with no tool calls, throws `Error: No response from <provider>` — after the retries and backup models, so the caller's path (a deferred speak step, or the host replaying the turn) is what picks it up. A stream that produced no text and no tool call is caught earlier, as a `ProviderError`; reasoning alone is not an answer. When it stopped at `maxTokens` the kind is `invalid`, never retried and never sent to a backup model, and the message says how many tokens went to thinking: `the output cap ran out before any answer (2048 of 2048 output tokens went to reasoning) — raise maxTokens or lower effort`. Any other empty stream is `overload`. A stream that stops before the provider's end signal (no finish reason, no `[DONE]`) throws a `ProviderError` of kind `network` once what arrived is delivered, so half an answer is never read as a whole one.
 
 ## Retries, backup models and fallbacks
 
@@ -480,7 +480,7 @@ Three layers, innermost first. All from `src/providers/ProviderAdapter.ts` and `
 | Backup model | `backupModels` | Retries exhausted with a backup-eligible kind, or `kind === "model"` (the endpoint does not serve that id). | Next model on the list, same provider. |
 | Fallback | `fallbacks` (per provider) or `FallbackAiProvider` | The provider fails or is on cooldown. | Next provider. Cooldowns per `kind`; a server-supplied `Retry-After` always wins over the default interval. |
 
-The `timeout` bounds silence, not the whole call: a stream that keeps producing tokens is left alone, one that goes quiet for 60 s is cut and retried.
+The `timeout` bounds silence, not the whole call: a stream that keeps producing tokens is left alone, one that goes quiet for 60 s is cut and retried. Keep-alives count as life. The wait for the first chunk, and a stream that sends only keep-alives, are cut by `@providerkit/core`'s progress clock: at 5 minutes, or at `timeout` when that is longer. A provider that rotates through models of its own, each watched on its own (an OpenCode Go chain), takes a long `timeout` so this watch never cuts the rotation short.
 
 ## Reasoning
 
@@ -490,7 +490,7 @@ interface ReasoningConfig {
 }
 ```
 
-`GenerateMessageInput.parameters.reasoning` is on the interface for a custom caller, but the framework never sets it. The one way to reach the wire is `config.effort` on a provider, which the adapter sends with every call as the provider's default. Absent means the model's own dynamic thinking and is never sent; `"none"` is the only way to say do not think. It matters most under a small `maxTokens`, where thinking tokens and the answer share one budget. Support varies per model; an unsupported level comes back as a 400 (`kind: "invalid"`).
+`GenerateMessageInput.parameters.reasoning` is on the interface for a custom caller, but the framework never sets it. The one way to reach the wire is `config.effort` on a provider, which the adapter sends with every call as the provider's default. Absent means the model's own dynamic thinking and is never sent; `"none"` is the only way to say do not think. It matters most under a small `maxTokens`, where thinking tokens and the answer share one budget: a turn that spends all of it thinking fails as `invalid`. Support varies per model; an unsupported level comes back as a 400 (`kind: "invalid"`).
 
 ## The AiProvider interface
 
@@ -618,6 +618,8 @@ Do not pick from that list. Ask the model you ship.
 
 Every `ProviderAdapter` subclass has `probeJsonWithTools(opts?)`. It asks the bound model, on the wire, both ways, and reports which shape called the tool on every sample.
 
+The probe asks the adapter's own model, never its fallbacks, one call at a time. A rate-limited fallback cannot make a working primary look broken, and a primary that fails the probe throws. A `FallbackAiProvider` has no probe of its own: probe each adapter you put in it.
+
 ```ts fragment
 interface JsonWithToolsProbe {
   /** The shape to configure, or null when neither called the tool on every sample. */

package/docs/reference/session.md

@@ -38,6 +38,7 @@ interface Run {
   hop: number;
   startedAt: string;
   suspendedAt?: string;
+  staying?: true;
   waiting?: { kind: "timer" | "event"; key?: string; until?: string; setAt: string; event?: string };
   asked: Record<string, number>;
   visits: Record<string, number>;
@@ -86,6 +87,7 @@ From `src/types/session.ts`. Every date is ISO 8601 text, never a `Date`: the bl
 | `hop` | `number` | Chaining depth. `0` for a run a trigger started; `+1` per `{ flow }` move and per `onEnd: 'reset'`. A start at hop 5 is skipped: `code: 'hop-limit'` on `TurnResult.skipped`. |
 | `startedAt` | `string` | The clock's now when the run started. |
 | `suspendedAt` | `string?` | Set while `suspended`. The most recently suspended run is the one that resumes. |
+| `staying` | `true?` | Set once an `onEnd: 'stay'` run has finished its steps and sits on its last talk step, answering every message. Any other move clears it. |
 | `waiting` | object? | Set while `waiting`. See below. |
 | `asked` | `Record<string, number>` | Per field, how many times a talk step spoke with that field still pending. A field at the step's `maxAsks` (default 3, `src/utils/schema.ts`) leaves the pending set: `code: 'max-asks'`, with the field's slug in `detail`. |
 | `visits` | `Record<string, number>` | Per step, how many times this run entered it. Part of every message and action key, so a revisit mints new keys. |

package/docs/reference/step.md

@@ -44,6 +44,7 @@ The model speaks. A guideline, fields to collect, or both.
 ```ts fragment
 type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | { collect: (keyof D & string)[]; prompt?: Template }) & {
   ask?: Partial<Record<keyof D & string, string>>;
+  question?: Template;
   maxAsks?: number;
   branches?: Branch<C, D>[];
   tools?: string[];
@@ -54,8 +55,9 @@ type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | {
 | Field | Type | Default | Meaning |
 |---|---|---|---|
 | `prompt` | `Template` | "Collect what is still missing below, in the flow of the conversation, one or two things per message." | The guideline for the reply. Required when there is no `collect`. |
-| `collect` | `(keyof D & string)[]` | none | Fields to collect. The step is done when they are known. |
+| `collect` | `(keyof D & string)[]` | none | Fields to ask for now, in this order. The step is done when they are known. The flow's own `collect` lists everything it needs; see [Flow](flow.md). |
 | `ask` | `Partial<Record<slug, string>>` | the field's own `ask` | Per-flow wording for a field. |
+| `question` | `Template` | none | A fixed first question, sent word for word with no model call. When the customer's message asks something, one AI reply answers it and asks this question. Needs `collect`. |
 | `maxAsks` | `number` | `3` | Times a field may be asked before it is skipped (`code: 'max-asks'`, the field in `detail`). |
 | `branches` | `Branch<C, D>[]` | none | Exits judged while the step asks. See [Branches](branches.md). |
 | `tools` | `string[]` | the flow's `tools`, else all | Tools the model may call from this step. |
@@ -64,6 +66,8 @@ type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | {
 - Pending fields are `collect` minus the known ones minus those at `maxAsks`, in `collect` order. A step the run enters whose pending list is empty is skipped with no model call (`code: 'already-known'`) and the run follows `then`. When the asking run resumes and the message filled the last field, the same move is logged `ok` with no detail.
 - Reaching a talk step suspends any other run that was asking; this run becomes the asker and holds the floor. It speaks in this turn if the speak call has not happened yet; otherwise it speaks on the next message.
 - The speak call returns the message plus one value per pending field. Values are validated and written; each field still pending is counted as asked once more. With pending fields left the run stays asking. With none left, or with no `collect` at all, the run follows `then` in the same turn.
+- With `question`, the step's first ask is that text, as a `kind: 'verbatim'` message (`code: 'asked-fixed'`). It goes out only when every field in `collect` is still pending and none was asked yet, and never on a run that stays (`onEnd: 'stay'`). Reached after this turn's speak call, it goes out in the same turn, the way a `say` does. It counts as one ask of each field.
+- When the customer's message asks something ("quanto tá o 13?"), one AI reply answers it and asks the question, in these words where they fit: only what the answer already covered, or what would contradict it, changes. Sending the text word for word after an answer could repeat or contradict it. The outcome line carries `code: 'fixed-in-reply'`. The understand call judges whether the message asks something (`asks`), and only while some flow has a fixed question. A message that only answers or greets gets the question word for word, with no speak call. An unjudged message, or the retry of a failed answer, counts as asking. Either way the question counts as one ask, so the step moves on at `maxAsks` whatever the customer does. Every later ask is the model's own wording. A `{ step, clear }` that clears the step's fields also clears their ask count, so the question goes out again.
 - With `silenced` set, a talk step ends the run with `code: 'silenced'` (`detail` = your reason); a run that was already asking stays asking instead.
 - Outcome kind: `collect` when `collect` is non-empty, else `prompt`.
 
@@ -153,11 +157,11 @@ The code forks. No model call.
 | Form | Meaning |
 |---|---|
 | `'passo'` | Jump to that step id. |
-| `'end'` | Finish the run here, exactly as running past the last step does — `onEnd` still decides: `'end'` ends it, `'stay'` re-enters the last step and keeps asking, `'reset'` starts a fresh run. `'end'` is reserved: no step may use it as an id. |
-| `{ step: 'passo', clear: ['campo'] }` | Delete the listed fields from `session.data`, then jump. The way to ask something again. |
-| `{ flow: 'outro', input? }` | End this run (reason `'flow'`) and start `outro` in the same turn, one hop deeper. The child gets `input`, or this run's `input` when absent, and holds the floor. `flow` is a template. |
+| `'end'` | Finish the run here, exactly as running past the last step does — `onEnd` still decides: `'end'` ends it, `'stay'` goes back to the last talk step and answers every message from there, `'reset'` starts a fresh run. `'end'` is reserved: no step may use it as an id. |
+| `{ step: 'passo', clear: ['campo'] }` | Delete the listed fields from `session.data` and forget how many times the run asked them, then jump. The way to ask something again. |
+| `{ flow: 'outro', input? }` | End this run (reason `'flow'`) and start `outro` in the same turn, one hop deeper. The child gets `input`, or this run's `input` when absent. It holds the floor when this run did, or when no run did: a `mention` flow that chains does not take the message from the run it was routed to. `flow` is a template. |
 
-Entering a step counts a visit; the visit is part of every key minted there, so a step visited twice sends twice. A `{ step }` jump to an id that no longer exists ends the run with `code: 'step-gone'`; a `{ flow }` to an unknown flow is skipped with `code: 'flow-gone'`.
+Entering a step counts a visit; the visit is part of every key minted there, so a step visited twice sends twice. A `{ step }` jump to an id that no longer exists ends the run with `code: 'step-gone'`; a `{ flow }` whose template resolves to an unknown flow is skipped with `code: 'flow-gone'`. A literal flow id the agent does not have is skipped the same way, and the agent build logs a warning for it.
 
 ## Caps
 

package/docs/reference/stores.md

@@ -261,6 +261,7 @@ return nil
 `ARGV` is the expected version, the next version, the blob, now as ISO text and the TTL in seconds. `nil` back is success; a version back is the conflict (`actualVersion` is that number); `'missing'` means the hash is gone (`actualVersion` is `undefined`).
 
 - `sessionTTL` defaults to `7 * 24 * 60 * 60` = 604800 seconds and is reset on every save. `0` never expires.
+- A session that expires takes its parked runs and claims with it. A wait longer than the TTL (an event wait defaults to 30 days) wakes to no session, and a `once` flow can fire again. Set `sessionTTL` above your longest wait, or to `0`.
 - `load` returns `null` when the hash has no fields.
 
 ### Example
@@ -409,12 +410,13 @@ console.log(await store.load("s1")); // null on a first turn
 
 ## OpenSearchStore
 
-Over `@opensearch-project/opensearch`'s client; Elasticsearch 7.x fits the same calls. One document per session, with `blob` stored but not indexed. The constructor takes the client first and the options second.
+Over `@opensearch-project/opensearch`'s client; Elasticsearch 7.x fits the same calls. One document per session, with `blob` stored but not indexed. Like the other stores, the constructor takes one object with the client in it.
 
 ### Signature
 
 ```ts fragment
 interface OpenSearchStoreOptions {
+  client: OpenSearchClient;
   /** Index name. Default `agent_sessions`. */
   indices?: { sessions?: string };
   /** Create the index with its mappings on `initialize()`. Default true. */
@@ -435,7 +437,7 @@ interface OpenSearchClient {
 }
 
 class OpenSearchStore<D = unknown> implements Store<D> {
-  constructor(client: OpenSearchClient, options?: OpenSearchStoreOptions);
+  constructor(options: OpenSearchStoreOptions);
   /** Create the index with its mappings when it is missing and `autoCreateIndices` is on. */
   initialize(): Promise<void>;
 }
@@ -479,7 +481,7 @@ import type { OpenSearchClient } from "@falai/agent";
 // const client = new Client({ node: process.env.OPENSEARCH_URL });   // from @opensearch-project/opensearch
 declare const client: OpenSearchClient;
 
-const store = new OpenSearchStore<{ nome: string }>(client, { indices: { sessions: "conversas" }, refresh: "wait_for" });
+const store = new OpenSearchStore<{ nome: string }>({ client, indices: { sessions: "conversas" }, refresh: "wait_for" });
 await store.initialize();
 console.log(await store.load("s1")); // null on a first turn
 ```

package/docs/reference/trigger.md

@@ -85,7 +85,7 @@ A trigger whose phrases are *all* exclusions can never fire, so `validateFlow` r
 | `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`.
@@ -116,7 +116,7 @@ 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).
 

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

@@ -104,6 +104,7 @@ type Trigger<C, D, Cond, E> = { repeat?: Repeat } & (      // default: message/m
 
 type Talk<C, D, Cond> = ({ prompt: Template; collect?: (keyof D)[] } | { collect: (keyof D)[]; prompt?: Template }) & {
   ask?: Partial<Record<keyof D, string>>;                   // per-flow wording; schema `ask` is the default
+  question?: Template;                                      // fixed first ask, verbatim, no call; needs collect
   maxAsks?: number; branches?: Branch<C, D, Cond>[]; tools?: string[]; instructions?: Instruction<C, D>[];
 };
 
@@ -121,6 +122,7 @@ interface Flow<C, D, Cond, A extends ActionMap, E> {
   on?: Trigger<C, D, Cond, E>[];        // absent or [] = Início manual
   anchor?: string;                      // 'session' (default) or a host anchor name — "vale por conversa / por lead"
   while?: Pred<C, D, Cond>;             // re-checked whenever the run moves; default = trigger `if`
+  collect?: (keyof D)[];                // the data this flow needs; steps' collect orders the asks
   clearOnStart?: (keyof D)[];
   steps: Step<C, D, Cond, A, E>[];      // ids required, unique, never 'end'
   onEnd?: 'end' | 'stay' | 'reset';     // default 'end'
@@ -239,7 +241,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' }>;
@@ -304,7 +306,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');
@@ -458,7 +460,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/01-install.md

@@ -30,6 +30,8 @@ npm install @falai/agent
 pnpm add @falai/agent
 ```
 
+This tutorial is for 4.x. If your project is on 3.x, start with the [migration guide](../migration/v3-to-v4.md): 3.x code will not compile against v4.
+
 The package ships an ESM build, a CommonJS build and its own TypeScript types. There is nothing else to install.
 
 ## Set a provider key

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
@@ -197,6 +212,8 @@ const history: History = [
 
 A run that was already asking stays asking and speaks when the gate opens. A run that reaches a new talk step while silenced ends, and the log says `code: 'silenced'` with your reason in `detail`. Keep calling `turn()` for every inbound even while a human owns the customer, so waits resolve and the state stays true. `silenced: { reason, understand: true }` still spends the understand call, so fields keep landing while nothing is said.
 
+A closed 24-hour window stops messages, not the follow-up. Pass `silenced: { reason, skip: true }` for a gate like that: a talk or `say` step is skipped (`status: 'skipped'`, `code: 'silenced'`) and the run takes the step's `then`, so the `do` step after it still alerts the team. Keep the plain string for a human owner or a paused assistant, where the whole run must stop.
+
 **`context`** is the per-turn data your flows and actions read, such as the customer record. It is typed once, `falai<Ctx>()`, and passed on every input. Ana has none. [Agent](../reference/agent.md) has the full `TurnInput`.
 
 ## Sessions from before v4

package/examples/05-branches.ts

@@ -54,7 +54,7 @@ const agent = f.agent({
           then: "dados",
         },
       ],
-      // After the last step the run stays on it, so follow-up questions land here.
+      // After the last step the run goes back to the last talk step it took, so follow-up questions land there.
       onEnd: "stay",
     }),
     f.flow({

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.8",
+  "packageManager": "bun@1.4.2",
+  "version": "4.0.0",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -87,7 +88,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
-    "@types/bun": "^1.3.0",
+    "@types/bun": "^1.4.2",
     "@types/node": "^20.19.22",
     "@types/pg": "^8.15.5",
     "eslint": "^9.17.0",
@@ -96,7 +97,7 @@
     "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
-    "@providerkit/core": "^0.11.1",
+    "@providerkit/core": "^0.20.0",
     "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";
@@ -15,7 +15,7 @@ import { logger, LoggerLevel } from "../utils/logger.js";
 import { addUsage } from "../utils/usage.js";
 import { CompactionEngine } from "./CompactionEngine.js";
 import type { IdleRequest, SpeakOutcome, TalkRequest } from "./contracts.js";
-import { validateFlow } from "./FlowSpec.js";
+import { BUILT_IN_CONDITIONS, checkPred, validateFlow } from "./FlowSpec.js";
 import { Runner, type Turn } from "./Runner.js";
 import { Speak } from "./Speak.js";
 import { Understand } from "./Understand.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;
@@ -100,6 +110,16 @@ function compactionOptions<C, D>(options: AgentOptions<C, D>): CompactionOptions
 
 /** Every name a flow uses must resolve now, not on the turn that first reaches it. */
 function validate<C, D>(options: AgentOptions<C, D>): void {
+  // A host condition under a built-in's name is never called: the built-in answers first.
+  for (const name of Object.keys(options.conditions ?? {})) {
+    if (BUILT_IN_CONDITIONS.includes(name)) {
+      throw new FlowConfigurationError(
+        `[FlowConfigurationError] condition "${name}" shadows a built-in: ${BUILT_IN_CONDITIONS.join(", ")} are reserved. Rename it.`,
+      );
+    }
+  }
+  // An agent-level `if` is judged on every turn, so an unknown name here would throw on every turn.
+  options.instructions?.forEach((ins, i) => checkPred(ins.if, "agent", `instructions[${i}].if`, options));
   const ids = new Set<string>();
   for (const flow of options.flows ?? []) {
     if (ids.has(flow.id)) {
@@ -124,6 +144,7 @@ function validate<C, D>(options: AgentOptions<C, D>): void {
   }
   const { idle } = options;
   if (idle && idle !== "silent") {
+    idle.instructions?.forEach((ins, i) => checkPred(ins.if, "idle", `instructions[${i}].if`, options));
     const known = new Set((options.tools ?? []).map((tool) => tool.id));
     for (const name of idle.tools ?? []) {
       if (!known.has(name)) {

package/src/core/CompactionEngine.ts

@@ -8,6 +8,7 @@
  * 4. auto_compact - summarize old messages via LLM provider
  */
 
+import { classify } from "@providerkit/core";
 import log from "loglevel";
 import type { HistoryItem } from "../types/history.js";
 import type { TokenUsage } from "../types/ai.js";
@@ -19,13 +20,20 @@ export class CompactionEngine {
      * Validate CompactionOptions. Throws on invalid values.
      */
     static validateOptions(options: CompactionOptions): void {
+        if (typeof options.maxTokens !== "number" || !(options.maxTokens > 0)) {
+            throw new Error(
+                `[CompactionEngine] maxTokens is ${String(options.maxTokens)}: it must be above 0. ` +
+                `Set it to the most history, in tokens, each call should carry, e.g. 100000.`
+            );
+        }
         if (
             typeof options.compactionThreshold !== "number" ||
             options.compactionThreshold < 0.5 ||
             options.compactionThreshold > 0.95
         ) {
             throw new Error(
-                `compactionThreshold must be between 0.5 and 0.95, got ${options.compactionThreshold}`
+                `[CompactionEngine] compactionThreshold is ${String(options.compactionThreshold)}: it must be between 0.5 and 0.95. ` +
+                `Use 0.8 unless you measured otherwise.`
             );
         }
         if (
@@ -33,7 +41,7 @@ export class CompactionEngine {
             options.preserveRecentCount < 2
         ) {
             throw new Error(
-                `preserveRecentCount must be >= 2, got ${options.preserveRecentCount}`
+                `[CompactionEngine] preserveRecentCount is ${String(options.preserveRecentCount)}: it must be 2 or more. Use 4, the default.`
             );
         }
         if (
@@ -41,7 +49,7 @@ export class CompactionEngine {
             options.maxToolResultChars <= 0
         ) {
             throw new Error(
-                `maxToolResultChars must be > 0, got ${options.maxToolResultChars}`
+                `[CompactionEngine] maxToolResultChars is ${String(options.maxToolResultChars)}: it must be above 0. Use 5000, the default.`
             );
         }
     }
@@ -171,13 +179,24 @@ export class CompactionEngine {
                 history: [],
                 context: {},
                 parameters: {
-                    maxOutputTokens: 1024,
+                    // Thinking spends this cap too, at whatever effort the host's
+                    // provider runs. 1024 fit the summary but not the thinking: in
+                    // production a ~250-token answer at effort "high" spent all of
+                    // a 2,048 cap thinking (OpenCode Go, 2026-09-30). 8192 is the
+                    // most every built-in provider's common models accept
+                    // (DeepSeek chat and the older Claude models stop there), so a
+                    // larger cap would 400 on them.
+                    maxOutputTokens: 8192,
                     jsonSchema: {},
                 },
             });
 
             return { text: result.message, usage: readUsage(result.metadata) };
-        } catch {
+        } catch (error) {
+            // Kind and message, or a cap spent thinking reads like an outage.
+            log.warn(
+                `CompactionEngine: the summary call failed (${classify(error)}: ${error instanceof Error ? error.message : String(error)}), falling back to aggressive truncation`
+            );
             return null;
         }
     }
@@ -337,10 +356,7 @@ export class CompactionEngine {
             };
         }
 
-        // Fallback: LLM summarization failed — aggressive truncation
-        log.warn(
-            "CompactionEngine: LLM summarization failed, falling back to aggressive truncation"
-        );
+        // Fallback: LLM summarization failed (logged with its reason) — aggressive truncation
         const truncated = CompactionEngine.aggressiveTruncate(
             microCompacted,
             options