@falai/agent 4.0.0-alpha.13 → 4.0.0-alpha.15

package/docs/guides/error-handling.md

@@ -150,7 +150,7 @@ Most things that go wrong inside a turn become outcome lines, not exceptions:
 
 The full detail vocabulary is in [outcomes](../reference/outcomes.md).
 
-Two errors outside the four classes: a `compaction` option out of range throws a plain `Error` at construction (`compactionThreshold must be between 0.5 and 0.95, got 2`), and `PrismaStore` throws a `TypeError` when the client has no model by the given name.
+Two errors outside the four classes: a `compaction` option out of range throws a plain `Error` at construction (`[CompactionEngine] compactionThreshold is 2: it must be between 0.5 and 0.95. Use 0.8 unless you measured otherwise.`), and `PrismaStore` throws a `TypeError` when the client has no model by the given name. [Errors](../reference/errors.md) lists the other wiring errors thrown at construction.
 
 ## Catching by class
 

package/docs/guides/flow-control.md

@@ -144,7 +144,7 @@ Ends this run with `reason: 'flow'` and starts the other flow in the same turn.
 - has `hop` one higher than the parent. A chain deeper than 5 stops: the child is skipped with `code: 'hop-limit'`.
 - repeats by default (`'always'`), so a flow may be chained into many times; its claim carries the parent's step key.
 
-`flow` is a template: `{{input.flowId}}` resolves against the run's input and context. A flow id that does not exist lands in `skipped[]` with `code: 'flow-gone'`; a child flow with a live run for the same anchor is skipped with `code: 'already-running'`. This is how one flow hands the conversation to another: the last step of a qualifying flow can `then: { flow: 'agendamento' }`.
+`flow` is a template: `{{input.flowId}}` resolves against the run's input and context. A literal flow id the agent does not have logs a warning when the agent is built and is skipped at run time with `code: 'flow-gone'`; a template that resolves to no flow lands in `skipped[]` with `code: 'flow-gone'`; a child flow with a live run for the same anchor is skipped with `code: 'already-running'`. This is how one flow hands the conversation to another: the last step of a qualifying flow can `then: { flow: 'agendamento' }`.
 
 ## `onEnd`: after the last step
 

package/docs/guides/persistence.md

@@ -156,7 +156,7 @@ const viaRedis = new RedisStore({ redis, keyPrefix: "agent:", sessionTTL: 7 * 24
 const viaMongo = new MongoStore({ client: mongo, databaseName: "app" });
 const sqlite = new SQLiteStore({ db });
 await sqlite.initialize();
-const search = new OpenSearchStore(opensearch, { refresh: "wait_for" });
+const search = new OpenSearchStore({ client: opensearch, refresh: "wait_for" });
 await search.initialize();
 
 console.log([postgres, viaPrisma, viaRedis, viaMongo, sqlite, search].length); // 6

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

@@ -206,7 +206,7 @@ Per-field wording lives on the field (`ask`); a step may override it (`ask: { no
 type Next = string /* step id or 'end' */ | { step: string; clear?: string[] } | { flow: string; input?: unknown };
 ```
 
-Branches stay on talk steps, judged while the step is asking: `{ when: '...', then }` for the model, `{ if: pred, then }` for code. A `wait` step takes `if` branches only, judged when the customer replies, and only when the step also has an `else`; a `when` branch on a wait never fires. There is no standalone AI-judged step: the model forks only where fresh customer text exists.
+Branches stay on talk steps, judged while the step is asking: `{ when: '...', then }` for the model, `{ if: pred, then }` for code. A `wait` step takes `if` branches only, judged when the customer replies, and only when the step also has an `else`; `validateFlow` rejects a `when` branch on a wait, since nothing would ever judge it. There is no standalone AI-judged step: the model forks only where fresh customer text exists.
 
 ```ts fragment
 // ─── v3 ───
@@ -349,7 +349,7 @@ interface Store<D> {
 }
 ```
 
-The seven adapters survive as `Store` implementations and take the same client you passed before: `MemoryStore`, `PostgresStore`, `PrismaStore`, `RedisStore`, `MongoStore`, `SQLiteStore`, `OpenSearchStore`. They persist the v4 blob and a version, nothing else; message repositories, `SessionRepository`, `status`, `currentFlow` / `currentStep` columns, `PersistenceManager`, `autoSave`, `schemaVersion` and `restoreSession` are gone. The framework never calls a store: you `load`, `turn`, `save`.
+The seven adapters survive as `Store` implementations and take the same client you passed before: `MemoryStore`, `PostgresStore`, `PrismaStore`, `RedisStore`, `MongoStore`, `SQLiteStore`, `OpenSearchStore`. Each takes one options object with the client in it, so OpenSearch's becomes `new OpenSearchStore({ client, ...options })`. They persist the v4 blob and a version, nothing else; message repositories, `SessionRepository`, `status`, `currentFlow` / `currentStep` columns, `PersistenceManager`, `autoSave`, `schemaVersion` and `restoreSession` are gone. The framework never calls a store: you `load`, `turn`, `save`.
 
 **Use a fresh table.** The default names are the 3.x ones (`agent_sessions`, `agent:` prefix), so pass a new one (`tables.sessions` on Postgres, SQLite and Prisma, `collections.sessions` on Mongo, `indices.sessions` on OpenSearch, `keyPrefix` on Redis) or drop the old table first; `initialize()` (Postgres, SQLite, OpenSearch) only creates the table or index when it is missing, and does nothing while one of that name exists. A v4 store read against a live 3.x row fails loudly: Redis, Mongo, Prisma and OpenSearch throw `InvalidSessionError` (no `blob`), Postgres and SQLite fail on the missing `blob` column. Create the new table, then migrate rows on first load as §10 shows.
 

package/docs/reference/agent.md

@@ -86,7 +86,7 @@ class Agent<C, D> {
 
 `Idle` is `{ prompt: Template; tools?: string[]; instructions?: Instruction[] } | 'silent'`. Its `tools` list must name tools registered on the agent.
 
-`AgentCompactionConfig` is `{ maxTokens: number; compactionThreshold?: number; preserveRecentCount?: number; maxToolResultChars?: number; enabled?: boolean }`. Defaults: `compactionThreshold` `0.8` — compaction runs when the history passes 80% of `maxTokens` (allowed 0.5 to 0.95); keep the 4 most recent messages (at least 2); cut each tool result at 5000 characters (more than 0); `enabled: true`. Values outside those ranges throw at construction.
+`AgentCompactionConfig` is `{ maxTokens: number; compactionThreshold?: number; preserveRecentCount?: number; maxToolResultChars?: number; enabled?: boolean }`. `maxTokens` must be more than 0. Defaults: `compactionThreshold` `0.8` — compaction runs when the history passes 80% of `maxTokens` (allowed 0.5 to 0.95); keep the 4 most recent messages (at least 2); cut each tool result at 5000 characters (more than 0); `enabled: true`. Values outside those ranges throw at construction.
 
 ## turn()
 

package/docs/reference/errors.md

@@ -59,7 +59,7 @@ From `src/types/errors.ts`, `src/core/Migrate.ts` and `@providerkit/core`.
 | Class | Thrown by | When | What to do |
 |-------|-----------|------|------------|
 | `FlowConfigurationError` | `f.agent()` / `new Agent()`, `validateFlow`, `fromSpec` | A flow cannot run as written: a flow id or step id declared twice; a step with no id, or with the reserved id `"end"`; an unknown field in `collect` / `ask` / `clearOnStart`; an unknown action, event, condition or tool; a `then` pointing at a step that does not exist; an action `with` missing a required parameter; a duration that does not parse; a talk step with neither `prompt` nor `collect`. Also thrown at run time when a JSON predicate names a condition the agent does not have. | Fix the flow. It is a bug in the flow or the registries, never something to retry. |
-| `SessionConflictError` | every `Store.save` | The stored version is not `expectedVersion`: another turn saved first, or a `save(…, 0)` found a row. | Load the session again and replay the same input. Nothing was sent, so nothing is duplicated. |
+| `SessionConflictError` | every `Store.save` | The stored version is not `expectedVersion`: another turn saved first, a `save(…, 0)` found a row, or the row was deleted or expired after it was loaded (`actualVersion` is `undefined`). | Load the session again and replay the same input. Nothing was sent, so nothing is duplicated. |
 | `InvalidSessionError` | every `Store.load`, `assertSession`, `migrateSession` | A stored row is not a v4 session and not a recognisable 3.x one: wrong `v`, an `id` that does not match the row, a missing `data`, a run with a bad `status`, text that is not JSON. | Repair or delete the row. The framework never replaces a bad row with a fresh conversation, because that would re-ask every field and re-fire every once-flow. |
 | `ProviderError` | the built-in providers, `FallbackAiProvider` | A model call failed after the provider's own retries, backup models and fallbacks. `kind` says what would fix it. | Match on `kind` (table below). |
 
@@ -80,8 +80,8 @@ The bracket names the class, the text before the colon says what is wrong and wh
 [FlowConfigurationError] flow "triagem": has no steps list. Write steps as a list, even an empty one.
 [FlowConfigurationError] flow "a" is declared twice: flow ids must be unique. Rename one of them.
 [FlowConfigurationError] idle: unknown tool "buscar_preco". Register it in the agent's tools or fix the name.
-[SessionConflictError] Session "s1" was modified concurrently: expected version 1, found 2. Reload the session and retry the operation.
-[SessionConflictError] Session "s1" was modified concurrently: expected version 0, found none. Reload the session and retry the operation.
+[SessionConflictError] Session "s1" was modified concurrently: expected version 3, found 4. Reload the session and retry the operation.
+[SessionConflictError] Session "s1" is gone from the store: it was at version 3 and has since been deleted or expired. Load it again; a load that finds nothing starts a new conversation.
 [InvalidSessionError] stored session "s1" is unreadable: v is 3, expected 4. Repair or delete the row; it is never replaced by a fresh conversation.
 [InvalidSessionError] stored session "s1" is unreadable: expected an object, got "garbage". Repair or delete the row; it is never replaced by a fresh conversation.
 [InvalidSessionError] stored session "s1" is unreadable: data is missing, expected an object; not a 3.x session either. Repair or delete the row; it is never replaced by a fresh conversation.
@@ -124,11 +124,13 @@ The same `ProviderError` means two different things depending on which of the tw
 
 A few throws are plain `Error` or `TypeError`. One happens at run time: a reply that parses to a blank message with no tool calls throws `Error: No response from <provider>` out of `generateMessage`, after the provider's retries and backup models have run. A speak call swallows it and defers the step; an understand call hands it to you, so catch `Error`, not only `ProviderError`. The rest are wiring bugs at construction:
 
-- A provider built without a key or model: `Gemini API key is required`, `Model is required. Example: 'gpt-5.6' or 'gpt-5.5'`.
+- A provider built without a key or model: `[GeminiProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.GEMINI_API_KEY } and check the variable is set.`, `[OpenAIProvider] model is empty: there is no default. Pass one, e.g. { model: "gpt-5.6" }.`
 - `createOpenAICompatibleProvider` without `name`, `baseURL`, `apiKey` or `model`.
 - `FallbackAiProvider` with an empty `providers` list.
 - `PrismaStore` whose client has no delegate for the model: `[TypeError] PrismaStore cannot use model "agentSession": …`.
-- `compaction` options out of range (`compactionThreshold` outside 0.5–0.95, `preserveRecentCount` below 2, `maxToolResultChars` at or below 0).
+- `compaction` options out of range (`maxTokens` at or below 0, `compactionThreshold` outside 0.5–0.95, `preserveRecentCount` below 2, `maxToolResultChars` at or below 0): `[CompactionEngine] compactionThreshold is 1.2: it must be between 0.5 and 0.95. Use 0.8 unless you measured otherwise.`
+
+Each follows the same `[Class] what: why. how to fix.` shape as the package classes; only the class is plain `Error`.
 
 ## Example
 
@@ -147,7 +149,7 @@ import type { AiProvider, DataOf, Session, TurnResult } from "@falai/agent";
 
 declare const provider: AiProvider;
 declare function send(text: string, key: string, afterMs: number): Promise<void>;
-declare function enqueue(jobId: string, at: Date): Promise<void>;
+declare function enqueue(jobId: string, at: Date, payload: { sessionId: string; key: string }): Promise<void>;
 declare function sleep(ms: number): Promise<void>;
 
 const f = falai().fields({
@@ -213,7 +215,8 @@ async function handle(sessionId: string, text: string, id: string): Promise<Turn
   }
 
   for (const m of result.messages) await send(m.text, m.key, m.afterMs);
-  for (const s of result.schedule) await enqueue(s.key, s.at);
+  // The key rides in the payload for turn({ wake: key }); BullMQ refuses a ":" in a custom id, so the job id is encoded.
+  for (const s of result.schedule) await enqueue(encodeURIComponent(s.key), s.at, { sessionId, key: s.key });
   return result;
 }
 

package/docs/reference/flow-spec.md

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

package/docs/reference/outcomes.md

@@ -227,7 +227,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

@@ -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/step.md

@@ -160,7 +160,7 @@ The code forks. No model call.
 | `{ 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/start/01-install.md

@@ -19,17 +19,19 @@ This page puts the package in a project and runs the first example.
 ## Add it to your project
 
 ```bash
-bun add @falai/agent
+bun add @falai/agent@alpha
 ```
 
 With npm or pnpm:
 
 ```bash
-npm install @falai/agent
+npm install @falai/agent@alpha
 # or
-pnpm add @falai/agent
+pnpm add @falai/agent@alpha
 ```
 
+4.0 is in alpha. Plain `@falai/agent`, with no tag, still installs 3.x, and this tutorial will not compile against it.
+
 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falai/agent",
   "packageManager": "bun@1.4.2",
-  "version": "4.0.0-alpha.13",
+  "version": "4.0.0-alpha.15",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -97,7 +97,7 @@
     "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
-    "@providerkit/core": "^0.11.1",
+    "@providerkit/core": "^0.11.2",
     "loglevel": "^1.9.2"
   },
   "peerDependencies": {

package/src/core/Agent.ts

@@ -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";
@@ -110,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)) {
@@ -134,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

@@ -19,13 +19,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 +40,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 +48,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.`
             );
         }
     }