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

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' }>;
@@ -265,7 +267,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 +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');
@@ -420,7 +422,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 +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

@@ -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/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
@@ -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.2",
+  "packageManager": "bun@1.4.2",
+  "version": "4.0.0-alpha.21",
   "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.1",
+    "@providerkit/core": "^0.13.2",
     "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

@@ -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.`
             );
         }
     }