@falai/agent 3.4.5 → 4.0.0-alpha.10

package/docs/guides/error-handling.md

@@ -1,227 +1,233 @@
 ---
-title: "Errors"
-description: "Catch the typed error classes by class, narrow them with instanceof, and recover with the right pattern for each failure mode."
+title: "Error handling"
+description: "The four error classes, who throws each one and when, and what the host does about it."
 type: guide
 order: 7
 ---
 
-# Errors
+# Error handling
 
-`@falai/agent` throws typed `Error` subclasses for every failure mode the framework owns. Catching `Error` is fine for telemetry, but recovering well needs class-level narrowing — a `DataValidationError` wants a re-prompt, a `ToolExecutionError` wants a soft message and maybe a redirect, a `FlowConfigurationError` wants to crash the build. This page is the recipe for each. The full surface lives in the [errors reference](../reference/errors.md).
+The package exports four error classes. Catch them by class.
 
-## The format contract
+```ts
+import { falai, GeminiProvider, ProviderError } from "@falai/agent";
 
-Every thrown message follows the same shape:
+const f = falai().fields({});
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  idle: { prompt: "Responda pela empresa." },
+});
 
-```text
-[<ErrorClass>] <what>: <why>. <how to fix>.
+try {
+  await agent.turn({ sessionId: "demo", message: "oi" });
+} catch (error) {
+  if (error instanceof ProviderError) console.log(error.kind); // "auth" when the key is wrong
+  else throw error;
+}
 ```
 
-The bracketed prefix mirrors the class name. The colon separates `<what>` from `<why>`. The trailing sentence is `<how to fix>`. The contract is uniform across the classes the framework throws — `FlowConfigurationError`, `DataValidationError`, `ToolExecutionError`, `ResponseGenerationError`, `SessionConflictError`, and `NotImplementedError` — so log lines and `try/catch` blocks parse the same way regardless of which class fired. The one exception is `ProviderError`, which carries the vendor's own message verbatim; its structure lives in the normalized `code` field instead.
+Every message follows one format: `[ErrorClass] what: why. how to fix.` The class name comes first so a log line is greppable, and the last sentence says what to do.
 
-The format applies to framework-thrown errors. If you write a custom tool or hook that throws, follow the same shape so downstream handlers stay uniform.
+| Class | Thrown by | When | What to do |
+|---|---|---|---|
+| `FlowConfigurationError` | `f.agent()`, `validateFlow`, `toSpec`, `parseDuration` | a flow cannot run as written | fix the flow; never catch it in production |
+| `ProviderError` | the provider, inside the understand call | the model could not be reached | nothing ran and nothing was saved: retry the same input |
+| `SessionConflictError` | `store.save()` | another turn saved the session first | reload and replay the same input |
+| `InvalidSessionError` | `store.load()`, `assertSession`, `migrateSession` | a stored row is not a session | repair or delete the row; it is never treated as a new conversation |
 
-## The error classes
+`ProviderError` and its `ErrorKind` come from `@providerkit/core` and are re-exported here, so you never import that package yourself.
 
-| Class | Thrown when | Recover by |
-|-------|-------------|------------|
-| `FlowConfigurationError` | Misconfigured agent: duplicate ids, unknown `collect` keys, malformed `Directive`, branch targets that don't resolve, auto-step cycles, function on `when`. | Don't. Surface in CI. |
-| `DataValidationError` | A user message produces a value that violates the declared `schema`. | Re-prompt the user for the offending fields. |
-| `ToolExecutionError` | The framework's config-driven tools (data enrichment / API call / computation configs) fail after internal retries. A plain handler that throws does **not** throw this — it soft-fails a failure result back to the model instead (see Pattern 3). | User-friendly message, optional retry, optional `agent.dispatch` to a recovery flow. |
-| `ResponseGenerationError` | Anything inside the turn fails — provider call, parsing, persistence. Wraps the underlying error in `details.originalError`, also reachable as the native `err.cause`. | Inspect `.cause` first; backoff retry, fall back, or surface a soft failure. |
-| `ProviderError` | A provider call fails terminally — retries and `backupModels` exhausted. Normalized `code` across all vendors; original SDK error on `cause`. | Match on `code`: backoff for `rate_limited` / `overloaded`, fix credentials for `auth`. |
-| `SessionConflictError` | A session save carries a stale `version` — another writer persisted the session after this one loaded it. | Reload the session and retry the turn. |
-| `NotImplementedError` | A reserved option is set to a value this version does not support (e.g. `routerMode: 'embedding'` in v2.0). | Use a supported value. Same posture as `FlowConfigurationError`. |
+## FlowConfigurationError
 
-`FlowConfigurationError`, `ToolExecutionError`, `ProviderError`, `SessionConflictError`, `ResponseGenerationError`, and `NotImplementedError` are exported from `@falai/agent` and matchable with `instanceof`. Only `DataValidationError` is internal — match it by `error.name`.
+Raised when a name in a flow does not resolve or a jump has no way out. `f.agent()` runs `validateFlow` on every flow it is built with, so a broken flow fails at construction, not on the turn that first reaches it.
 
-How errors reach your `catch` depends on the class. `ProviderError` and `SessionConflictError` propagate **bare** out of `respond()` — no wrapping — so you can branch on them directly. Everything else thrown inside a turn arrives wrapped in a `ResponseGenerationError` whose native `.cause` (and `details.originalError`) holds the original. On the streaming path, errors are not thrown at all: they land on the terminal chunk's `error` field, wrapped the same way.
+What it catches, with the message each case gives:
 
-The provider stack classifies every failure as retriable or deterministic before spending budget: rate limits, overload, timeouts, and network faults retry with backoff; auth failures, invalid requests, and caller aborts fail fast because retrying would only repeat the outcome. By the time an error reaches your code, that machinery is exhausted.
+- a flow id declared twice: `flow "x" is declared twice: flow ids must be unique`
+- an unknown field in `collect`, `ask`, `clearOnStart`, `clear` or `equals`: `unknown field "x" in collect`
+- an unknown action, event, condition or tool: `unknown action "enviar_email"`
+- a `with` that misses a required parameter or gives the wrong type: `action "notify" needs parameter "message"`
+- a `then`, `else`, `onFail` or branch pointing at a step that does not exist, or a step id `"end"`, or a duplicate step id
+- an `if` step that jumps backward with no `else`
+- a duration that does not parse, in a trigger or a `wait`: `silence has duration "tomorrow", which does not parse`
+- `toSpec` on a flow that carries a function predicate, which cannot be stored as JSON
 
-One framing that makes recovery simpler: **a failed turn has no effect**. If `respond()` or `stream()` throws mid-turn, the in-memory session is rolled back to its pre-turn snapshot (the user message added by `chat()`/`stream()` before the turn is retained), and persisted state is whatever the previous turn saved. There is no partially mutated session to repair — retrying the turn is always safe.
+`validateFlow` also returns warnings for what runs but probably not as intended; the agent logs them with `logger.warn` at construction. See [flows from JSON](./flows-from-json.md) for the list.
 
-## Pattern 1: try/catch + instanceof narrowing
+Do not catch this class in a request handler. It means the code or the stored flow is wrong, and the fix is an edit, not a retry.
 
-Wrap every `agent.respond` and `agent.respondStream` call site. Narrow by class, return the right user-facing string per branch, rethrow what cannot be recovered.
+## ProviderError: two paths through a turn
 
-```typescript
-import {
-  ProviderError,
-  SessionConflictError,
-  ToolExecutionError,
-  ResponseGenerationError,
-} from "@falai/agent";
+A turn makes at most one understand call and one speak call. A tool round inside the speak call is one more, up to `maxToolLoops`; a compaction summary is one more again. The framework treats a provider failure differently in the two phases.
 
-try {
-  const response = await agent.respond({ history, session });
-  return response.message;
-} catch (err) {
-  // Typed operational errors propagate bare from respond() — narrow directly.
-  if (err instanceof SessionConflictError) throw err;      // see Pattern 5
-  if (err instanceof ProviderError) throw err;             // see Pattern 4
-
-  // Everything else thrown inside the turn arrives wrapped in a
-  // ResponseGenerationError; unwrap via `.cause` and narrow the original.
-  const cause = err instanceof ResponseGenerationError ? err.cause : err;
-  if (cause instanceof ToolExecutionError) {
-    log.warn({ toolId: cause.toolId }, cause.message);
-    return "Sorry — that action failed. Try again in a moment.";
-  }
-  if (cause instanceof Error && cause.name === "DataValidationError") {
-    return "I need a couple of details cleared up — let's try that again.";
-  }
-  throw err;
-}
-```
+### In the understand call: the turn throws
 
-The two bare classes rethrow to dedicated recovery paths. Wrapped errors narrow through `.cause` — a `ToolExecutionError` gets a soft message, a `DataValidationError` a clarifying question (Pattern 2). Anything unexpected falls through to the outer rethrow. Configuration bugs (`FlowConfigurationError`, `NotImplementedError`) belong in CI, not the request path — see Pattern 6.
+The understand call judges the customer's message: which flow it fits, what it mentions, which fields it gives. If the provider fails here, `agent.turn()` throws the `ProviderError`. Nothing has run yet: no action was called, no message was produced, and the host has not saved anything. Retry the same input later; the same message id mints the same keys, so the retry is a replay, not a duplicate.
 
-## Pattern 2: DataValidationError → re-prompt
+### In the speak call: the turn returns, and the step waits or ends
 
-A `DataValidationError` carries an `errors: ValidationError[]` array naming the offending fields. Use it to ask the user a targeted clarifying question instead of a generic one.
+The speak call phrases the reply. If the provider fails here, or answers with an empty message, the turn does not throw. What happens next depends on whether waiting could help.
 
-```typescript
-} catch (err) {
-  const cause = err instanceof ResponseGenerationError ? err.cause : err;
-  if (cause instanceof Error && cause.name === "DataValidationError") {
-    const fields = (cause as { errors: { path: string; message: string }[] }).errors
-      .map((e) => `${e.path} (${e.message})`)
-      .join(", ");
-    return `I couldn't read these from your message: ${fields}. Mind clarifying?`;
-  }
-  // ...
-}
-```
+| The failure | Code | What the run does |
+|---|---|---|
+| The provider was down, slow, overloaded or rate-limited; the reply was empty | `provider-unavailable` | Waits, then tries again |
+| A usage window that says when it reopens | `provider-quota` | Waits until then |
+| A spent balance with no stated reset | `provider-quota` | Ends `failed` |
+| The key was rejected or has no access to the model | `provider-auth` | Ends `failed` |
+| The prompt is past the model's context window | `provider-context` | Ends `failed` |
+| The provider refused the request, or the model does not exist | `provider-invalid` | Ends `failed` |
 
-The framework does not retry by itself — the next user turn is the retry. Keep `session` alive between turns so the partial collection survives.
+A failure that waits returns with an outcome `{ kind: "prompt" | "collect", status: "deferred", code, until }`, a `schedule[]` entry keyed `${runId}:${stepId}:${visit}:retry:${atMs}`, and `llmCalls` counting the call that failed. The backoff is 1 minute, then 5, 15, an hour, six hours (`RETRY_BACKOFF` in `src/core/Runner.ts`); the attempt number is the count of trailing `deferred` outcomes for that step on that run. A provider that stated a reset later than the next rung is woken at the reset instead. When the wake fires, the step runs again at the same visit, so its message carries the same key it would have carried the first time.
 
-## Pattern 3: tool failures — soft-fail, then message, retry, or dispatch
+**The provider's own answer wins.** The table reads the failure's kind, which is an inference. When the provider sends `x-should-retry` it is not one, so that is read first: a `503` saying don't ends the step instead of spending five wakes to be told again, and a rejected request saying do gets its wake instead of ending the run. It arrives on `ProviderError.shouldRetry`.
 
-First, what does *not* happen: a crashed handler does not crash the turn. When a tool handler throws — or a gate like `checkPermissions` denies the call — the executor catches it and feeds the model a failure result (`{"success": false, "error": "..."}`) as the tool's output. The model sees the failure honestly and can apologize, retry, or route around it; the turn continues. A thrown `ToolExecutionError` reaching your `catch` comes from the framework's config-driven tools (data enrichment, API call, computation configs), not from an ordinary handler.
+**The ladder ends.** After the sixth failure on the same step there is no seventh wake: the outcome is `status: "failed"` and the run ends. The same happens at once for a failure no wait can fix — retrying a rejected key or an oversized prompt only spends two model calls to reach the same wall. Both land in `ended` with `reason: "failed"`, so your execution log shows a conversation that stopped and why.
 
-When you do catch one, three shapes exist. Pick by what the failing tool was doing. In each, unwrap through `.cause` first — config-tool failures surface wrapped, like everything else from inside the turn.
+Actions that ran earlier in the same turn are not undone; they ran at-least-once and are idempotent on `ctx.key`. `say` steps that went out before the failure are in `messages[]` as usual.
 
-**Soft failure — speak and continue.** A read-only tool that timed out: tell the user, let the conversation move on.
+The idle speaker has no step to re-park. Its failure leaves one outcome, `{ kind: "idle", status: "deferred", code }`, and no wake: the customer's next message asks it again.
 
-```typescript
-const cause = err instanceof ResponseGenerationError ? err.cause : err;
-if (cause instanceof ToolExecutionError) {
-  log.warn({ toolId: cause.toolId }, cause.message);
-  return "I couldn't fetch that just now. Want to try again?";
-}
-```
+### What is in the error
 
-**Optional retry.** Wrap the `respond` call in a small retry loop for transient errors.
-
-```typescript
-for (let attempt = 0; attempt < 2; attempt++) {
-  try {
-    return (await agent.respond({ history, session })).message;
-  } catch (err) {
-    const cause = err instanceof ResponseGenerationError ? err.cause : err;
-    if (cause instanceof ToolExecutionError && attempt === 0) {
-      await new Promise((r) => setTimeout(r, 250));
-      continue;
-    }
-    throw err;
-  }
+```ts fragment
+class ProviderError extends Error {
+  provider: string;        // which provider failed
+  kind: ErrorKind;         // what fixes it; see below
+  body?: string;           // the provider's own response text, truncated — the real reason
+  status?: number;         // HTTP status when there was one
+  retryAfterMs?: number;   // honoured when the provider said how long to wait
+  isTransient: boolean;    // rate, overload, network, timeout
 }
 ```
 
-**Recovery flow.** Hard failures — a payment tool that hit a permanent denial — should redirect into a recovery flow rather than echo the error. Dispatch a directive against the session so the *next* turn enters the recovery flow.
+Log `body` first. A bare `400 status code (no body)` says nothing, and the provider's own text usually names what it rejected. `code`, `resetAtMs` and `shouldRetry` ride along too, whenever the provider sends them.
 
-```typescript
-const cause = err instanceof ResponseGenerationError ? err.cause : err;
-if (cause instanceof ToolExecutionError && cause.toolId === "charge_card") {
-  await agent.dispatch({ goTo: "PaymentRecovery" }, session);
-  return "I hit a snag with that payment. Let me walk you through it.";
-}
-```
+`ErrorKind` is named by what fixes the failure: `"aborted"`, `"timeout"`, `"network"`, `"overload"`, `"rate"`, `"quota"`, `"entitlement"`, `"auth"`, `"model"`, `"context"`, `"content"`, `"invalid"`, `"unknown"`. Waiting helps with `timeout`, `network`, `overload` and `rate`. It does not help with `quota` (the balance is gone), `auth` (the key is wrong), `model` (the id does not exist), `context` (the prompt is too long: send less history, see [compaction](./compaction.md)) or `invalid`.
+
+The built-in providers retry transient failures before throwing: 3 retries and a 60-second silence timeout by default (`RetryConfig`). A `ProviderError` that reaches your code has already been retried. To keep serving through an outage, wrap several providers in a `FallbackAiProvider`; see [providers](../reference/providers.md).
 
-The dispatched [`Directive`](../reference/directive.md) lands in `session.pendingDirective` and is consumed at the start of the next turn.
+## SessionConflictError
 
-## Pattern 4: ProviderError → match the code, backoff or fallback provider
+Every store's `save(session, expectedVersion)` compares before it writes. A first save passes `0` and inserts; a later save passes the version it loaded and updates only a row still at that version. When the row moved on, the store throws:
 
-Terminal provider failures throw `ProviderError` with a normalized `code` (`rate_limited`, `overloaded`, `auth`, `invalid_request`, `schema_rejected`, `timeout`, `network`, `unknown`) — the same shape whether you run Gemini, OpenAI, Anthropic, OpenRouter, or DeepSeek. From `respond()` it propagates **bare** — narrow with `instanceof` directly, no unwrapping. On the streaming path it arrives on the terminal chunk's `error`, wrapped in a `ResponseGenerationError` whose `.cause` holds the original.
+```ts fragment
+class SessionConflictError extends Error {
+  sessionId: string;
+  expectedVersion: number;          // what you loaded
+  actualVersion: number | undefined; // what is stored now; undefined when the row is gone
+}
+```
 
-Before an error ever reaches you, the provider stack has classified it: transient failures (`rate_limited`, `overloaded`, `timeout`, `network`) consumed the retry budget and any `backupModels`; deterministic ones (`auth`, `invalid_request`, caller aborts) failed fast without burning retries. So by catch time, retrying the same call is usually pointless — fall back to a second provider or surface the failure.
+This is the normal outcome of a race, not a bug: a wake and a customer message landing on one session at the same moment, or two webhooks for one conversation. Nothing was sent, because the host sends only after a successful save. Load again and run the same input on the new version. The replay usually ends differently, and correctly: in the race above, the customer's reply now finds the nudge run waiting and takes the wait's `else` instead of nudging again. See [persistence](./persistence.md) for the loop.
 
-```typescript
-import { ProviderError } from "@falai/agent";
+## InvalidSessionError
 
-async function respondWithFallback(history: HistoryItem[], session: Session) {
-  for (let attempt = 0; attempt < 3; attempt++) {
-    try {
-      return await primaryAgent.respond({ history, session });
-    } catch (err) {
-      if (!(err instanceof ProviderError)) throw err;
-      if (err.code === "auth" || err.code === "invalid_request") {
-        throw err; // config bug — retrying won't help
-      }
-      await new Promise((r) => setTimeout(r, 200 * 2 ** attempt));
-    }
-  }
-  return fallbackAgent.respond({ history, session });
+Every store runs `assertSession` on load, and `migrateSession` runs it on any blob that already carries `v: 4`. A row that is not a v4 session for that id, or a 3.x blob that cannot be read, throws:
+
+```ts fragment
+class InvalidSessionError extends Error {
+  sessionId: string;
+  // message: [InvalidSessionError] stored session "s1" is unreadable: data is "nope", expected an object. Repair or delete the row; it is never replaced by a fresh conversation.
 }
 ```
 
-Both agents share the same `flows`, `tools`, and `schema` — only the `provider` differs. The session is provider-agnostic, so the fallback picks up exactly where the primary left off. The original SDK error stays available on `providerError.cause` for vendor-specific logging.
+The design choice behind it: a corrupt row must fail loudly. If the framework started a fresh session instead, it would ask every field again and fire every once-flow again, and nobody would notice until a customer did. Alert on it, then repair or delete the row by hand.
 
-## Pattern 5: SessionConflictError → reload and retry
+## What never throws
 
-With a durable adapter, every save is a compare-and-swap on the session's `version`. When two writers race — concurrent `respond()` calls from parallel webhooks, two browser tabs on one `sessionId` — the loser's save throws `SessionConflictError` instead of silently overwriting the winner's state. (Same-process concurrent saves of one session are serialized automatically and never conflict.)
+Most things that go wrong inside a turn become outcome lines, not exceptions:
 
-The error names `sessionId`, `expectedVersion`, and `actualVersion`. The recovery is mechanical: reload the session, retry the turn. The failed turn rolled back, so there is nothing to clean up.
+| Situation | What you see |
+|---|---|
+| a tool handler throws, or its input fails validation or permission | the model reads `{ "error": "…" }` and answers anyway |
+| an action throws | `{ status: "failed", code: "action-failed", detail: "<message>" }`; the run takes `onFail`, or `then` when there is none |
+| a wake fires for a session that does not exist | one outcome `code: 'no-session'`, `changed: false` |
+| a wake nobody waits for any more | `code: 'stale-wake'`, `changed: false` |
+| a message id already seen | `code: 'duplicate-input'`, `changed: false` |
+| a `start` or a chain names a flow the agent no longer has | one `skipped[]` entry, `code: 'flow-gone'` |
+| compaction's summary call fails | the oldest messages are dropped instead; the turn goes on |
 
-```typescript
-import { ResponseGenerationError, SessionConflictError } from "@falai/agent";
+The full detail vocabulary is in [outcomes](../reference/outcomes.md).
 
-function isSessionConflict(err: unknown): boolean {
-  if (err instanceof SessionConflictError) return true; // bare from respond()
-  if (err instanceof ResponseGenerationError) {
-    return err.cause instanceof SessionConflictError; // wrapped on the stream path
-  }
-  return false;
-}
+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.
 
-try {
-  return await agent.respond({ history, session });
-} catch (err) {
-  if (isSessionConflict(err)) {
-    const fresh = await agent.session.getOrCreate(sessionId); // reload winning state
-    return agent.respond({ history, session: fresh });
-  }
-  throw err;
-}
-```
+## Catching by class
 
-Cap the retries — a hot session under sustained contention should surface the conflict rather than spin. See [Persistence](./persistence.md) for how the `version` column works per adapter.
+The host loop, with each class handled where it belongs:
 
-## Pattern 6: FlowConfigurationError → don't catch in production
+```ts
+import {
+  falai,
+  GeminiProvider,
+  InvalidSessionError,
+  MemoryStore,
+  ProviderError,
+  SessionConflictError,
+  type DataOf,
+  type Session,
+  type TurnResult,
+} from "@falai/agent";
 
-`FlowConfigurationError` is a *bug*, not a runtime condition. It fires when the agent definition is malformed: a step references a flow id that doesn't exist, two steps share a `collect` key, a branch target points nowhere, an auto-step chain loops. The right place to catch it is the test runner and CI — never the request path.
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+type Data = DataOf<typeof f>;
 
-Smoke-test agent construction in CI so misconfiguration crashes the build rather than the first user request:
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [f.flow({ id: "boas-vindas", name: "Boas-vindas", on: [{ message: [] }], steps: [{ id: "nome", collect: ["nome"] }] })],
+});
+const store = new MemoryStore<Data>();
 
-```typescript
-import { describe, expect, it } from "bun:test";
-import { FlowConfigurationError } from "@falai/agent";
-import { buildAgent } from "../src/agent";
+declare function requeue(input: { sessionId: string; text: string; id: string }, afterMs: number): Promise<void>; // your queue
 
-describe("agent construction", () => {
-  it("builds without configuration errors", () => {
-    expect(() => buildAgent()).not.toThrow(FlowConfigurationError);
-  });
-});
-```
+async function onMessage(sessionId: string, text: string, id: string): Promise<TurnResult<Data> | undefined> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let session: Session<Data> | null;
+    try {
+      session = await store.load(sessionId);
+    } catch (error) {
+      if (error instanceof InvalidSessionError) {
+        console.error(error.message); // alert a human; do not start a new conversation
+        return undefined;
+      }
+      throw error;
+    }
+
+    let r: TurnResult<Data>;
+    try {
+      r = await agent.turn({ sessionId, session: session ?? undefined, message: text, id });
+    } catch (error) {
+      if (error instanceof ProviderError) {
+        // The understand call failed. Nothing ran, nothing was saved.
+        // Put the same input back on your queue; the replay mints the same keys.
+        await requeue({ sessionId, text, id }, error.retryAfterMs ?? 60_000);
+        return undefined;
+      }
+      throw error;
+    }
+    if (!r.changed) return r;
 
-In the request handler, let it bubble all the way up. A 500 plus a loud log is the correct outcome — the next deploy is the fix.
+    try {
+      await store.save(r.session, session?.version ?? 0);
+    } catch (error) {
+      if (error instanceof SessionConflictError) continue; // someone saved first: replay on the new version
+      throw error;
+    }
+    // Only now: send r.messages and enqueue r.schedule.
+    return r;
+  }
+  throw new Error(`three conflicts in a row on session "${sessionId}": check for a stuck queue worker`);
+}
 
-```typescript
-if (err instanceof FlowConfigurationError) throw err;
+const r = await onMessage("demo", "oi, sou a Bia", "m1");
+console.log(r?.messages.map((m) => m.text));
 ```
 
-`NotImplementedError` follows the same posture: it means a reserved option was set to a value this version doesn't support. Read the message, fix the config, ship the fix. Don't catch it.
+Three attempts is enough: a fourth conflict means two workers are firing on the same session, which is a queue problem, not a race.
+
+A speak-call failure needs no branch here: it arrives as a `deferred` outcome and a `schedule[]` entry, and the loop already enqueues those. The only thing to add is a log line when `r.outcomes` contains a `deferred` status, so an outage shows up in your dashboards before the retry wake hides it.
 
-**Next:** [Compaction](./compaction.md)
+See [the errors reference](../reference/errors.md) for the exported shapes.