@falai/agent 3.4.5 → 4.0.0-alpha.2

package/docs/reference/errors.md

@@ -1,185 +1,229 @@
 ---
 title: "Errors"
-description: "Typed error classes the framework throws, and the message format contract every thrown error follows."
+description: "The four error classes the package exports, when each one is thrown, and the message format they follow."
 type: reference
-order: 12
+order: 14
 ---
 
 # Errors
 
-> **Where this is introduced:** [Errors](../guides/error-handling.md)
-
-`@falai/agent` throws typed `Error` subclasses for every failure mode the framework owns. Catch them by class to discriminate construction errors from runtime errors, and by `error.name` when a class that is not exported (`DataValidationError`) needs to be matched.
-
-Every thrown message follows the same format contract:
-
-```text
-[<ErrorClass>] <what>: <why>. <how to fix>.
-```
-
-The bracketed prefix matches the class name. The "what / why / how to fix" triplet is mandatory — the framework never throws a bare message.
+The package exports four error classes and one type. Catch them by class with `instanceof`; each also sets `name` to its class name. Three are the package's own. `ProviderError` and `ErrorKind` are re-exported from `@providerkit/core`, the library every built-in provider is built on, so a `ProviderError` thrown deep inside a provider is the same class you import from `@falai/agent`.
 
 ## Signature
 
-```typescript
-// Exported from "@falai/agent"
-class FlowConfigurationError extends Error { /* name = "FlowConfigurationError" */ }
-class ToolCreationError       extends Error { toolId: string; cause?: Error }
-class ToolExecutionError      extends Error {
-  toolId: string;
-  executionContext?: Record<string, unknown>;
-  cause?: Error;
+```ts fragment
+class FlowConfigurationError extends Error {
+  constructor(message: string);
 }
-class NotImplementedError     extends Error { /* name = "NotImplementedError" */ }
-class ProviderError           extends Error {
-  kind: ErrorKind;   // 'rate' | 'overload' | 'quota' | 'entitlement' | 'auth' | 'context' | …
-                             // | 'schema_rejected' | 'timeout' | 'network' | 'unknown'
-  provider: string;          // e.g. "openai"
-  cause?: unknown;           // original SDK/HTTP error
+
+class SessionConflictError extends Error {
+  readonly sessionId: string;
+  readonly expectedVersion: number;
+  /** The version the store found; undefined when the row is gone. */
+  readonly actualVersion: number | undefined;
 }
-class SessionConflictError    extends Error {
-  sessionId: string;
-  expectedVersion: number;
-  actualVersion: number | undefined;
+
+class InvalidSessionError extends Error {
+  readonly sessionId: string;
 }
-class ResponseGenerationError extends Error {
-  cause?: unknown;           // native `cause` — the original error
-  details?: {
-    originalError?: unknown;
-    params?: Record<string, unknown>;
-    phase?: string;
-    context?: Record<string, unknown>;
-  };
+
+class ProviderError extends Error {
+  readonly provider: string;
+  readonly kind: ErrorKind;
+  readonly status?: number;
+  readonly code?: string;
+  /** How long the provider asked you to wait (Retry-After, Gemini's RetryInfo). */
+  readonly retryAfterMs?: number;
+  /** Absolute reset of the binding limit; can be days beyond retryAfterMs. */
+  readonly resetAtMs?: number;
+  /** Which subscription window bound: "5h", "weekly" or "monthly", when the provider named one. */
+  readonly window?: "5h" | "weekly" | "monthly";
+  readonly shouldRetry?: boolean;
+  /** The provider's own response body, truncated. */
+  readonly body?: string;
+  get isTransient(): boolean;
+  get isBackupEligible(): boolean;
+  /** Wrap anything thrown into a classified ProviderError; an existing one passes through. */
+  static from(provider: string, err: unknown): ProviderError;
 }
 
-// Internal — match by `error.name` (not exported from the package barrel)
-class DataValidationError     extends Error { errors: ValidationError[] }
+type ErrorKind =
+  | "aborted" | "timeout" | "network" | "overload" | "rate" | "quota"
+  | "entitlement" | "auth" | "model" | "context" | "content" | "invalid" | "unknown";
 ```
 
-## Fields
+From `src/types/errors.ts`, `src/core/Migrate.ts` and `@providerkit/core`.
 
-| Class | Thrown when | Notable fields | Recover by |
-|-------|-------------|----------------|------------|
-| `FlowConfigurationError` | Construction- or run-time misconfiguration: duplicate ids, unknown `collect` keys, malformed `Directive`, auto-step cycles, branch targets that do not resolve, function on `when`. | `message` | Fix the offending agent/flow/step/branch/directive at the source. Not a runtime-recoverable error. |
-| `ToolCreationError` | A `Tool` fails registration (invalid schema, duplicate id, builder threw). | `toolId`, `cause` | Repair the tool definition. Not user-facing. |
-| `ToolExecutionError` | A handler throws, all retries fail, or `validateInput` cannot correct invalid args. | `toolId`, `executionContext`, `cause` | Surface a user-friendly message; optionally `agent.dispatch({ goTo: '<recovery-flow>' })`. |
-| `DataValidationError` | `agent.respond(...)` collects values that violate the declared `schema`. | `errors: ValidationError[]` | Re-prompt for the offending fields, then retry. |
-| `ResponseGenerationError` | A turn fails for any reason other than a typed error the framework rethrows bare (see `ProviderError` below) — provider call failure, malformed structured output, hook failure. Exported; also carries the original error on the native `.cause`. | `cause`, `details.phase`, `details.originalError` | Retry with backoff, fall back to a different provider, or surface a soft failure to the user. |
-| `ProviderError` | A provider call fails terminally — retries and `backupModels` exhausted. Normalized across all vendors. Propagates **bare** out of `respond()` (`instanceof` survives — no unwrapping needed). Streaming turns surface it wrapped on the final chunk's `error`. | `kind`, `provider`, `status`, `body`, `cause` | Match on `kind`: back off for `rate`/`overload`, top up for `quota`, fix credentials for `auth`, compact for `context`, fail fast otherwise. |
-| `SessionConflictError` | A session save carries a stale `version` — another writer persisted the session after this one loaded it (concurrent `respond()` calls, parallel webhooks, two tabs). | `sessionId`, `expectedVersion`, `actualVersion` | Reload the session and retry the operation, or surface the conflict. |
-| `NotImplementedError` | A reserved option is set to a value this version does not support (e.g. `routerMode: 'embedding'` in v2.0). | `message` | Use a supported value. |
+## The four classes
 
-## Examples
+| 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. |
+| `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). |
 
-### 1. Narrowing by class and `name`
+## The message format
 
-```typescript
-import {
-  FlowConfigurationError,
-  ResponseGenerationError,
-  ToolExecutionError,
-  NotImplementedError,
-} from "@falai/agent";
+The three package classes follow one shape:
 
-try {
-  const response = await agent.respond(message);
-  return response.message;
-} catch (err) {
-  if (err instanceof FlowConfigurationError) throw err;          // bug — bubble up
-  if (err instanceof NotImplementedError) throw err;             // config bug
-  if (err instanceof ToolExecutionError) {
-    log.warn({ toolId: err.toolId, cause: err.cause }, err.message);
-    return "Sorry, that action failed. Try again in a moment.";
-  }
-  // Not exported — match by name.
-  if (err instanceof Error && err.name === "DataValidationError") {
-    return "I need you to clarify a few details — let's try that again.";
-  }
-  if (err instanceof ResponseGenerationError) {
-    // err.cause is the original error — e.g. a provider SDK failure.
-    log.warn({ cause: err.cause, phase: err.details?.phase }, err.message);
-    return "I'm having trouble reaching the model. Please retry.";
-  }
-  throw err;
-}
+```text
+[ErrorClass] what: why. how to fix.
 ```
 
-### 2. Matching provider failures by normalized code
-
-`ProviderError` propagates **bare** out of `respond()` — catch it with `instanceof`, no unwrapping. The original SDK/HTTP error is on `.cause`.
-
-```typescript
-import { ProviderError } from "@falai/agent";
-
-try {
-  const response = await agent.respond({ history });
-} catch (err) {
-  if (err instanceof ProviderError) {
-    switch (err.kind) {
-      case "rate":
-      case "overload":
-        return retryWithBackoff();         // transient — wait and retry
-      case "auth":
-        throw err;                          // config bug — crash loudly
-      default:
-        log.error({ cause: err.cause }, err.message);
-        return "I'm having trouble reaching the model. Please retry.";
-    }
-  }
-  throw err;
-}
+The bracket names the class, the text before the colon says what is wrong and where, and the last sentence says what to change. Examples, copied from what the code emits:
+
+```text
+[FlowConfigurationError] flow "triagem", step "grana": unknown field "orcamento" in collect. Add it to the agent's fields or fix the slug.
+[FlowConfigurationError] flow "triagem", step "quem": then points at step "fim", which does not exist. Use an existing step id or "end".
+[FlowConfigurationError] flow "triagem", step "avisa": unknown action "notify". Register it in actions or fix the name.
+[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.
+[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.
 ```
 
-### 3. Recovering from a session conflict
+`ProviderError` does not follow this shape. A wire failure's message is the provider, the status and the vendor's own body, truncated (`openai 429: {"error":{"message":"Rate limit reached…"}}`); an error wrapped from something already thrown keeps that error's own text. Read `kind`, not the message.
 
-`SessionConflictError` means another writer persisted the session between your load and your save. Like `ProviderError`, it propagates bare out of `respond()`. Reload, then retry.
+## ProviderError kinds
 
-```typescript
-import { SessionConflictError } from "@falai/agent";
+Named by what fixes them, from `@providerkit/core`.
 
-try {
-  await agent.respond({ history, session });
-} catch (err) {
-  if (err instanceof SessionConflictError) {
-    const fresh = await agent.session.getOrCreate(sessionId);
-    return agent.respond({ history, session: fresh });
-  }
-  throw err;
-}
-```
+| `kind` | Meaning | Retry? |
+|--------|---------|--------|
+| `aborted` | Your own `AbortSignal` fired. | Never. |
+| `timeout` | The stream stayed silent past `retryConfig.timeout` (default 60 s), or the provider sent 408. | Yes. |
+| `network` | The request never reached the provider: socket, DNS, proxy. | Yes. |
+| `overload` | Theirs and temporary: a 5xx, Anthropic's 529, "overloaded". | Yes, and worth a different model. |
+| `rate` | 429 per-minute throttle. | Wait `retryAfterMs`, or rotate key or model. |
+| `quota` | Balance or usage window exhausted. | Waiting minutes will not fix it. |
+| `entitlement` | The plan never included this API. | No; neither a new key nor a top-up fixes it. |
+| `auth` | 401 or 403: the key is wrong. | No. |
+| `model` | The model id does not exist or is not served here. | No; the built-in providers do try the next `backupModels` entry. |
+| `context` | The prompt outgrew the context window. | No; send less. Compaction is the framework's answer. |
+| `content` | Safety filter or refusal. | No. |
+| `invalid` | Any other 4xx: a bug in what was sent. | No. |
+| `unknown` | Nothing above matched. | No. |
 
-### 4. The format contract in practice
+`isTransient` is true for `timeout`, `network`, `overload` and `rate`. `isBackupEligible` is what the provider uses to decide whether to try the next backup model.
 
-Every thrown message is parseable. The leading `[<ErrorClass>]` token mirrors the class name, the colon separates `<what>` from `<why>`, and the trailing sentence is `<how to fix>`.
+## Where a provider failure lands in a turn
 
-```text
-[FlowConfigurationError] Invalid directive: multiple position fields set (goTo, complete). A directive may have at most one position field. Remove the extras.
+The same `ProviderError` means two different things depending on which of the two calls failed. Both are in `src/core/Understand.ts`, `src/core/Speak.ts` and `src/core/Runner.ts`.
 
-[ToolExecutionError] Tool "book_hotel" execution failed: all 3 attempts exhausted. Check the tool handler for errors or increase maxRetries. Last error: ECONNRESET.
+- **Understand call fails**: `turn()` throws. Nothing ran, nothing changed, there is nothing to save. The host catches, waits (`retryAfterMs` when present) and calls `turn()` again with the same input.
+- **Speak call fails**: `turn()` does not throw. What happens next depends on what failed — see [Error handling](../guides/error-handling.md#in-the-speak-call-the-turn-returns-and-the-step-is-re-parked). A kind a wait can fix re-parks the talk step under `${runId}:${stepId}:${visit}:retry:${atMs}` with `status: 'deferred'`; a kind it cannot ends the run with `status: 'failed'` and no wake. Either way the session is saved as usual with `changed: true`, the `do` steps that ran before the call are not repeated, and a retry wake re-runs the same visit, so keys and idempotency hold. The idle speaker has no step to re-park: its failure leaves one `kind: 'idle'`, `status: 'deferred'` line and no wake.
+- **Tool handler throws** during a speak call: not an error for you. The model sees `{ error }` as the tool result and the turn continues.
+- **Action (`do`) handler throws**: not an error for you either. The result becomes `{ failed: error.message }`, the outcome is `code: 'action-failed'` with the message in `detail`, and the run follows `onFail` or `then`.
 
-[DataValidationError] Data validation failed: fields [checkIn must be a date] did not pass schema validation. Fix the offending values to match the declared schema.
+## Errors outside the contract
 
-[NotImplementedError] routerMode "embedding" is not implemented: only "ai" is supported in v2.0. Set routerMode to "ai" or omit the option.
-```
+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:
 
-## Errors
+- A provider built without a key or model: `Gemini API key is required`, `Model is required. Example: 'gpt-5.6' or 'gpt-5.5'`.
+- `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).
 
-The format contract itself has zero runtime enforcement — it is a contract on framework code, not on user code. If you write a custom `Tool` or hook that throws, follow the same shape so downstream `try/catch` blocks parse uniformly:
+## Example
 
-```typescript
-throw new ToolExecutionError(
-  `[ToolExecutionError] Tool "${tool.id}" booking failed: provider returned 503. Retry the call or fall back to manual booking.`,
-  tool.id,
-);
-```
+A host loop that catches each class where it can happen. The framework never sends or saves, so every catch site knows nothing has left the process yet.
 
-Tool input validation, permission denials, and missing-tool warnings are reported as `ToolResult { success: false, error }` rather than thrown — this keeps the AI's reasoning loop intact while preserving the same `[<ErrorClass>] <what>: <why>. <how to fix>.` shape in the `error` string.
+```ts
+import {
+  falai,
+  FlowConfigurationError,
+  InvalidSessionError,
+  MemoryStore,
+  ProviderError,
+  SessionConflictError,
+} from "@falai/agent";
+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 sleep(ms: number): Promise<void>;
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome de um jeito leve." },
+});
+type Data = DataOf<typeof f>;
+
+// A flow that cannot run throws here, before the first turn.
+function build() {
+  try {
+    return f.agent({
+      name: "Ana",
+      provider,
+      flows: [
+        f.flow({
+          id: "boas-vindas",
+          name: "Boas-vindas",
+          on: [{ message: [] }],
+          steps: [{ id: "quem", collect: ["nome"] }],
+        }),
+      ],
+    });
+  } catch (error) {
+    if (error instanceof FlowConfigurationError) console.error(error.message);
+    throw error;
+  }
+}
+
+const agent = build();
+const store = new MemoryStore<Data>();
+
+async function handle(sessionId: string, text: string, id: string): Promise<TurnResult<Data>> {
+  let session: Session<Data> | undefined;
+  try {
+    session = (await store.load(sessionId)) ?? undefined;
+  } catch (error) {
+    // A corrupt row. Alert someone; do not start over with a fresh session.
+    if (error instanceof InvalidSessionError) console.error(error.sessionId, error.message);
+    throw error;
+  }
+
+  let result: TurnResult<Data>;
+  try {
+    result = await agent.turn({ sessionId, session, message: text, id });
+  } catch (error) {
+    // The understand call failed: nothing ran. Wait and play the same input again.
+    // An empty reply throws a plain Error, not a ProviderError, so match both.
+    const emptyReply = error instanceof Error && error.message.startsWith("No response from");
+    if (emptyReply || (error instanceof ProviderError && error.isTransient)) {
+      await sleep(error instanceof ProviderError ? (error.retryAfterMs ?? 5_000) : 5_000);
+      return handle(sessionId, text, id);
+    }
+    throw error;
+  }
+  if (!result.changed) return result;
+
+  try {
+    await store.save(result.session, session?.version ?? 0);
+  } catch (error) {
+    // Another turn saved first. Nothing was sent: load the new version and replay.
+    if (error instanceof SessionConflictError) return handle(sessionId, text, id);
+    throw error;
+  }
+
+  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);
+  return result;
+}
+
+const r = await handle("s1", "oi, sou a Bia", "m1");
+console.log(r.llmCalls, r.session.data);
+```
 
-## Related
+## See also
 
-- [Errors](../guides/error-handling.md) — recipe-shaped guide that introduces this surface.
-- [createAgent](./create-agent.md) — construction-time errors thrown from `new Agent(...)`.
-- [Tool](./tool.md) — handler return shape and the `ToolExecutionError` triggers.
-- [Directive](./directive.md) — the validation rules that surface as `FlowConfigurationError`.
-- [Providers](./providers.md) — the retry/backup pipeline that ends in `ProviderError`.
-- [Persistence adapters](./adapters.md) — the optimistic locking that throws `SessionConflictError`.
+- [Error handling](../guides/error-handling.md): the same four classes as a walkthrough, with the replay and the retry wake.
+- [Session](./session.md): the version rule that produces `SessionConflictError`.
+- [Providers](./providers.md): retries, backup models and fallbacks before a `ProviderError` reaches you.
+- [Flow spec](./flow-spec.md): `validateFlow` and what it checks.

package/docs/reference/fields.md

@@ -0,0 +1,125 @@
+---
+title: "Fields"
+description: "How to declare a field, what ask and extract do, and how a value is checked before it reaches session.data."
+type: reference
+order: 5
+---
+
+# Fields
+
+A field is one piece of data the agent collects, authored once on the agent. Steps name fields in `collect`; the model extracts values from what the customer says; the framework checks each value against the field's type and writes it to `session.data`. Fields are typed: `falai().fields(defs)` turns the definitions into the data type every `collect`, `clear`, `equals` and `ctx.set` is checked against.
+
+## Signature
+
+```ts fragment
+type ScalarType = "string" | "number" | "integer" | "boolean";
+
+interface ScalarDef<T extends ScalarType = ScalarType> {
+  type: T;
+  description?: string;
+  enum?: readonly (string | number)[];
+}
+
+interface FieldDef<T extends ScalarType = ScalarType> extends ScalarDef<T> {
+  ask?: string;
+  extract?: "anywhere" | "asked";
+}
+
+type FieldDefs = Record<string, FieldDef>;
+
+type InferData<F extends FieldDefs> = { [K in keyof F]: /* string | number | boolean, or the enum's literal union */ };
+type DataOf<T extends { fields: FieldDefs }> = InferData<T["fields"]>;
+```
+
+## FieldDef
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `type` | `ScalarType` | required | `'string'`, `'number'`, `'integer'` or `'boolean'`. |
+| `enum` | `readonly (string \| number)[]` | none | The allowed values. A value outside the list is dropped (`code: 'not-in-enum'`). In the data type the field becomes the literal union. |
+| `description` | `string` | none | What the field is. Sent to the model with the field's type and options. |
+| `ask` | `string` | none | How the model should ask for it. Sent to the speak call as "How to ask" while the field is pending. A talk step's own `ask` overrides it. A template: `{{data.x}}` and `{{context.x}}` are filled in. |
+| `extract` | `'anywhere' \| 'asked'` | `'anywhere'` for string, number and integer; `'asked'` for boolean | Where a value may be taken from. `'anywhere'`: any message from the customer, whether or not the field was asked. `'asked'`: only the reply to the step that lists the field, so a stray "sim" never confirms anything. |
+
+The slug (the key in `fields`) is the name in `session.data`, in `collect`, in templates (`{{data.nome}}`) and in the model's envelope. Use letters, digits, `_` and `-`; any other character makes the framework send the field under an alias and map it back.
+
+## DataOf and InferData
+
+`InferData<F>` maps each slug to its value type: `string`, `number` (for `number` and `integer`), `boolean`, or the `enum` list as a literal union. Every key is required in `Data`; the session stores `Partial<Data>`, because fields land one at a time.
+
+`DataOf<typeof f>` is the shortcut for a bound toolkit: `type Data = DataOf<typeof f>`.
+
+Properties are readonly — `fields()` takes the definitions as a `const` type, so the data type is read-only; the framework writes `session.data`, your code reads it.
+
+## Behaviour
+
+**Known.** A field is known when its value is not `undefined`, `null` or `''`. Known fields are never asked again and never re-extracted; both calls list them under "Already known".
+
+**Which call extracts what.** The understand call, on a message turn, extracts every unknown `'anywhere'` field named in a `collect` of the flow holding the floor and of every eligible message flow, in one envelope. The speak call extracts the pending fields of the step that speaks, `'asked'` ones included, in the same call that phrases the reply. Tools write `data` and actions call `ctx.set()`; those values are written as given, with no check.
+
+**Coercion.** A raw value from the model goes through `coerceField(def, raw)` before it is written:
+
+| Field type | Accepted | Result |
+|---|---|---|
+| `string` | a string; a number or boolean | as is; converted with `String()` |
+| `number` | a finite number; a numeric string. `"1500,50"` becomes `1500.5` (one comma is read as the decimal mark); `"1.500,50"` is dropped | the number |
+| `integer` | as `number` | truncated toward zero |
+| `boolean` | a boolean; `"true"`, `"sim"`, `"yes"`, `"1"`; `"false"`, `"não"`, `"nao"`, `"no"`, `"0"` (case-insensitive, trimmed) | the boolean |
+
+Anything else is dropped with the outcome line `code: 'bad-value'`. A value outside `enum` is dropped with `code: 'not-in-enum'`. A value for a slug that is not a field is dropped with `code: 'unknown-field'`. Dropped values leave a `collect` outcome with status `skipped` and no run id; the field stays pending and is asked again.
+
+**What reaches the provider.** `toWireSchema(defs)` turns definitions into the JSON schema the model must fill: a closed object (`additionalProperties: false`) with one property per field carrying `type`, `description` and `enum`, and nothing else. `ask` and `extract` are stripped; they steer the framework, not the schema. In the envelope style used by both calls every property is required and nullable (`type: [type, 'null']`), so the model answers `null` for what the customer did not give. The prompt describes each field once more in words (`nome (string) [a | b]: description`) and, in the speak call, adds the pending field's "How to ask".
+
+**Clearing.** `{ step, clear: ['x'] }` on a `then`/`else`/branch and `clearOnStart` on a flow delete the field from `session.data`, so the next step that collects it asks again. `maxAsks` on a talk step (default 3) is the other way a field stops being pending: it is skipped for that run with `code: 'max-asks'`, the field in `detail`.
+
+**Action parameters** use the sibling type `ParamDef`: a `ScalarDef` plus `optional?: true`, or `{ type: 'array', items: ScalarDef }`. `InferParams<P>` gives the `with` shape. They share `toWireSchema` and the same strictness at construction. See [Actions, events and conditions](actions-events-conditions.md).
+
+## Example
+
+```ts
+import { falai, GeminiProvider, type DataOf } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome de um jeito leve, sem tom de formulário." },
+  tamanho: {
+    type: "string",
+    enum: ["1-10", "11-50", "51-200", "200+"],
+    ask: "Pergunte quantas pessoas trabalham lá e ofereça as faixas.",
+  },
+  orcamento: { type: "number", description: "Valor mensal em reais.", ask: "Pergunte a faixa de investimento, só para orientar." },
+  // boolean: extract defaults to 'asked', so only the reply to `confirma` can set it
+  confirmado: { type: "boolean", ask: "Resuma em uma frase o que anotou e pergunte se está tudo certo." },
+});
+
+type Data = DataOf<typeof f>;
+// { readonly nome: string; readonly tamanho: "1-10" | "11-50" | "51-200" | "200+"; readonly orcamento: number; readonly confirmado: boolean }
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "triagem",
+      name: "Triagem",
+      on: [{ message: [] }],
+      steps: [
+        { id: "quem", prompt: "Descubra quem é e de onde fala.", collect: ["nome", "tamanho", "orcamento"] },
+        { id: "confirma", collect: ["confirmado"] },
+        { id: "ok", if: { equals: { confirmado: true } }, else: { step: "quem", clear: ["confirmado"] } },
+        { id: "tchau", say: "Obrigada, {{data.nome}}. Um vendedor continua daqui." },
+      ],
+    }),
+  ],
+});
+
+const r = await agent.turn({ sessionId: "s1", message: "Oi, sou a Ana, somos 30 pessoas" });
+const data: Partial<Data> = r.session.data;
+console.log(data); // { nome: 'Ana', tamanho: '11-50' } once the model has read them; `orcamento` is still pending
+```
+
+## See also
+
+- [Collection](../concepts/collection.md) for pending fields, `maxAsks` and what each call extracts
+- [Step](step.md) for `collect`, `ask` and `maxAsks` on a talk step
+- [Actions, events and conditions](actions-events-conditions.md) for `ParamDef` and `InferParams`
+- [Outcomes](outcomes.md) for the dropped-value lines