@falai/agent 3.4.5 → 4.0.0-alpha.2

package/docs/reference/instruction.md

@@ -1,179 +1,125 @@
 ---
 title: "Instruction"
-description: "Unified behavioral primitive that shapes how the agent responds, with a kind discriminator (must / never / should) and agent / flow / step scoping."
+description: "One rule the model follows while it speaks, gated by an AI-judged `when` or a code-judged `if`, at agent, flow, step or idle scope."
 type: reference
-order: 5
+order: 8
 ---
 
 # Instruction
 
-> **Where this is introduced:** [Instructions](../guides/instructions.md)
+An instruction is one sentence the model obeys while it speaks: "never invent prices", "answer in three sentences". It has a `kind` (`must`, `never`, `should`), a `prompt`, and two optional tests: `when`, a string the model judges, and `if`, a predicate your code judges, which costs no model call. The same shape goes on the agent, a flow, a talk step or the idle speaker; only its place in the configuration changes.
 
-An `Instruction` is a single statement of behavior the agent should follow. v2 collapses three v1 types into one — every instruction now carries a `kind` discriminator (`'must'`, `'never'`, or `'should'`) and a `prompt` that is rendered into the system prompt with a scope caption. The same shape works at agent, flow, and step scope; only its position in the configuration changes.
-
-The set of instructions actually rendered into a given turn's prompt is reported back on the response as `appliedInstructions` — observability is deterministic, derived from rendering, not self-reported by the model. For instructions with a textual `when`, this means the condition was presented to the model, not that the model reported a match.
+Source: `src/types/flow.ts`, `src/core/Runner.ts` (`speakRequest`), `src/core/Prompt.ts` (`instructionsSection`).
 
 ## Signature
 
-```typescript
-interface Instruction<TContext = unknown, TData = unknown> {
+```ts fragment
+interface Instruction<C = unknown, D = unknown> {
   id?: string;
-  kind?: 'must' | 'never' | 'should';        // default: 'should'
-  when?: ConditionWhen;                       // AI strings: positives OR, ! exclusions inhibit
-  if?: ConditionIf<TContext, TData>;          // code-evaluated function(s), AND semantics
-  prompt: Template<TContext, TData>;
-  enabled?: boolean;                          // default: true
-  tags?: string[];
-  metadata?: Record<string, unknown>;
-}
-
-interface ScopedInstructions<TContext = unknown, TData = unknown> {
-  global: Instruction<TContext, TData>[];
-  flow?: { flowTitle: string; items: Instruction<TContext, TData>[] };
-  step?: { stepId: string; items: Instruction<TContext, TData>[] };
-}
-
-interface AppliedInstruction {
-  id: string;
-  scope: 'global' | 'flow' | 'step';
-  scopeRef?: string;                          // flowTitle for flow, stepId for step
+  kind?: "must" | "never" | "should";
+  when?: string | string[];
+  if?: Pred<C, D>;
+  prompt: Template;
 }
 ```
 
 ## Fields
 
-### `Instruction`
-
-| Field | Type | Required | Default | Notes |
-|-------|------|----------|---------|-------|
-| `prompt` | `Template<TContext, TData>` | yes | — | Behavioral text rendered into the prompt under the `## Instructions` section. |
-| `kind` | `'must' \| 'never' \| 'should'` | no | `'should'` | Severity. `'must'` = absolute do, `'never'` = absolute don't, `'should'` = conditional nudge. |
-| `when` | `ConditionWhen` | no | — | AI-evaluated activation string or array. Non-`!` entries are OR alternatives. `!` entries are OR exclusions; any matching exclusion inhibits the instruction. Functions are not allowed here; use `if`. |
-| `if` | `ConditionIf<TContext, TData>` | no | — | Code-evaluated activation function (or array). Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if `if` passes. |
-| `id` | `string` | no | auto | Stable identifier used in `AppliedInstruction.id`. Auto-generated when omitted. |
-| `enabled` | `boolean` | no | `true` | Set `false` to skip the instruction without removing it from configuration. |
-| `tags` | `string[]` | no | — | Free-form tags for filtering and grouping. |
-| `metadata` | `Record<string, unknown>` | no | — | Free-form per-instruction metadata. |
-
-### `AppliedInstruction`
-
-| Field | Type | Notes |
-|-------|------|-------|
-| `id` | `string` | The `Instruction.id` that fired. |
-| `scope` | `'global' \| 'flow' \| 'step'` | Where the instruction was declared. |
-| `scopeRef` | `string \| undefined` | `flowTitle` for `flow`, `stepId` for `step`, `undefined` for `global`. |
-
-## Scoping
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `id` | `string` | none | Yours. The framework carries it and never reads it. |
+| `kind` | `"must" \| "never" \| "should"` | `"should"` | How hard the rule is. `must` is a hard rule, `never` a hard ban, `should` a preference. The word is written into the prompt as is. |
+| `when` | `string \| string[]` | none | When the rule applies, judged by the model from the conversation. Several strings are alternatives (OR). Rendered into the prompt as text; it never costs a call of its own. |
+| `if` | `Pred<C, D>` | none | When the rule applies, judged by code. A function or a JSON `ConditionSpec`. False: the instruction is left out of this call. |
+| `prompt` | `Template` | required | The rule. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are filled in first. |
 
-The same `Instruction` shape attaches at three positions:
+## Scopes
 
-- **Agent (global):** `AgentOptions.instructions` — always considered, on every turn, for every flow.
-- **Flow:** `FlowOptions.instructions` — considered when the active flow matches.
-- **Step:** `StepOptions.instructions` — considered when the active step matches.
+| Scope | Where | Applies |
+|---|---|---|
+| Agent | `AgentOptions.instructions` | On every speak call, talk steps and the idle speaker alike. |
+| Flow | `Flow.instructions` | While a talk step of that flow speaks. |
+| Step | `TalkStep.instructions` | While that step speaks. |
+| Idle | `Idle.instructions` (`idle: { prompt, instructions }`) | While the idle speaker answers. |
 
-At prompt-build time the composer renders each eligible instruction as a single bullet:
+The list the model sees is built in this order: agent, then flow, then step. For the idle speaker: agent, then idle. Duplicates are kept: the same sentence in two scopes appears twice.
 
-```
-- [<kind>] [<scope-caption>] <prompt> (apply only when: <when-clause> OR <when-clause>; do not apply when: <exclusion-clause>)
-```
+## Behaviour
 
-The parenthesized condition is omitted when `when` is not set. If `when` contains only `!` exclusions, the suffix uses only `do not apply when: ...`. Code-evaluated `if` predicates run first; a failing predicate removes the entire bullet before the prompt reaches the model.
+- Instructions reach the **speak call only**. The understand call (routing, mentions, branches, extraction) never sees them.
+- `if` is judged by code when the speak request is built, with a `PredCtx` of `{ context, data, input, run, silenced, now }`. `run` is the speaking run; while the idle speaker answers, `run` is absent and `input` is `undefined` for every instruction it judges — agent-level and `idle`-level alike. Write `if` predicates on the agent and on `idle` so they work without a run.
+- `when` is not judged by code. It is appended to the line as `(apply only when: a OR b)` and the model decides.
+- Each surviving instruction becomes one line under a `## Instructions` heading, in this exact form:
 
-Scope captions are fixed by where the instruction was declared:
+  ```text
+  - [should] [Always] Responda em até três frases.
+  - [must] [Always] Reconheça o problema antes de explicar qualquer coisa. (apply only when: a pessoa está irritada)
+  ```
 
-| Scope | Caption |
-|-------|---------|
-| Agent | `[Always]` |
-| Flow | `[In: <FlowTitle>]` |
-| Step | `[Step: <stepId>]` |
+  The first bracket is `kind` (or `should` when absent). The second is the group caption. Every scope goes into one group captioned `[Always]`, so the caption does not say which scope a line came from.
+- `prompt` is rendered with the turn's `data`, `context` and the run's `input`, then trimmed. A line that renders to nothing is dropped. When no line survives, the whole section is left out.
+- Instructions have no effect on movement, extraction or which flow starts. They shape wording only.
+- In a stored flow (`FlowSpec`) an instruction is an `InstructionSpec`: the same fields with `if` in JSON form. `flowSpecSchema` lets a model write flow-level instructions and leaves step-level ones out.
 
-Example block in the rendered prompt:
+## Example
 
-```
-## Instructions
-
-- [must] [Always] Always greet by name
-- [never] [Always] Promise delivery dates you cannot guarantee
-- [should] [In: Booking] Confirm dates before calling book_hotel
-- [should] [Step: payment] If the card is declined, never retry without confirmation
-```
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-## Examples
-
-### 1. Agent-level absolutes plus a step-level nudge
+interface Ctx {
+  plano: "gratis" | "pro";
+  horaLocal: number;
+}
 
-```typescript
-import { createAgent, GeminiProvider } from '@falai/agent';
+const f = falai<Ctx>().fields({
+  duvida: { type: "string", ask: "Pergunte qual é a dúvida, em uma frase." },
+});
 
-const agent = createAgent({
-  name: 'BookingBot',
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+const agent = f.agent({
+  name: "Bia",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
   instructions: [
-    { kind: 'must', prompt: 'Validate dates are in the future before booking.' },
-    { kind: 'never', prompt: 'Promise rates you have not looked up.' },
+    { kind: "never", prompt: "Nunca invente preços ou prazos." },
+    // The model judges `when` from the conversation.
+    { kind: "must", when: "a pessoa está irritada", prompt: "Reconheça o problema antes de explicar qualquer coisa." },
+    // Code judges `if`; it costs nothing. No `run` here, so read only `context` and `data`.
+    {
+      kind: "should",
+      if: ({ context }) => context.horaLocal >= 18 || context.horaLocal < 9,
+      prompt: "Avise que o suporte humano volta às 9h.",
+    },
   ],
   flows: [
-    {
-      title: 'Booking',
-      instructions: [
-        { kind: 'should', prompt: 'Offer to compare two options before committing.' },
-      ],
+    f.flow({
+      id: "duvidas",
+      name: "Dúvidas",
+      on: [{ message: [] }], // no examples: the catch-all, starts when no other message flow wins
+      // Applies to every talk step of this flow.
+      instructions: [{ kind: "should", prompt: "Responda em até três frases." }],
       steps: [
+        { id: "qual", collect: ["duvida"] },
         {
-          id: 'payment',
-          prompt: 'Take payment.',
-          instructions: [
-            { kind: 'must', prompt: 'If the card is declined, never retry without confirmation.' },
-          ],
+          id: "resposta",
+          prompt: "Responda a dúvida.",
+          // Applies to this step only.
+          instructions: [{ kind: "must", prompt: "Termine perguntando se ficou claro." }],
         },
       ],
-    },
+    }),
   ],
 });
-```
-
-### 2. Conditional activation with `when` and `if`
-
-```typescript
-import type { Instruction } from '@falai/agent';
-
-type Ctx = { tier: 'free' | 'pro' };
-type Data = { hasQuoted: boolean };
-
-const concise: Instruction<Ctx, Data> = {
-  kind: 'should',
-  when: 'User asks a simple yes/no question',
-  prompt: 'Answer in one sentence.',
-};
 
-const proOnly: Instruction<Ctx, Data> = {
-  kind: 'must',
-  if: (ctx) => ctx.context.tier === 'pro',
-  prompt: 'Offer to export the conversation as PDF.',
-};
-```
-
-### 3. Reading `appliedInstructions` from a response
-
-```typescript
-const response = await agent.respond('Hi, I want to book a room.');
-
-for (const a of response.appliedInstructions ?? []) {
-  console.log(`${a.scope}${a.scopeRef ? `:${a.scopeRef}` : ''} → ${a.id}`);
-}
-// global → ins_validate_dates
-// flow:Booking → ins_offer_two_options
+const r = await agent.turn({
+  sessionId: "demo",
+  context: { plano: "gratis", horaLocal: 21 },
+  message: "quanto custa o plano pro?",
+});
+console.log(r.messages[0]?.text);
 ```
 
-## Errors
-
-- `FlowConfigurationError` — duplicate `id` across instructions in the same scope, or `kind` set to a value other than `'must' | 'never' | 'should'`.
-- `DataValidationError` — a `Template` `prompt` references a `data` field not declared in the agent `schema`.
-
-## Related
+## See also
 
-- [Instructions](../guides/instructions.md) — recipe for shaping behavior with `must` / `never` / `should`
-- [Architecture](../concepts/architecture.md) — where Instruction fits among the six primitives
-- [createAgent](./create-agent.md) — `AgentOptions.instructions`
-- [Flow](./flow.md) — `FlowOptions.instructions`
-- [Step](./step.md) — `StepOptions.instructions`
+- [Instructions](../guides/instructions.md): choosing a scope and a kind.
+- [Conditions](../guides/conditions.md): `when` versus `if`.
+- [Actions, events, conditions](./actions-events-conditions.md): `Pred`, `PredCtx` and `ConditionSpec`.
+- [Agent](./agent.md): `AgentOptions.instructions`, `idle`, `persona` and `goal`.

package/docs/reference/outcomes.md

@@ -0,0 +1,273 @@
+---
+title: "Outcomes"
+description: "Every line a turn writes about what a run did, with the full list of outcome codes and what produces each."
+type: reference
+order: 13
+---
+
+# Outcomes
+
+A turn writes one line per thing a run did: a step ran, a step was skipped, a run parked, a value was dropped. Those lines are `StepOutcome`s. They come back on `TurnResult.outcomes` and stay on each run as `run.outcomes` (the last 50). Beside them, `TurnResult.started`, `ended` and `skipped` say which runs began, which ended and why, and which triggers matched but started nothing. This page lists every line the code can write, so a panel that shows runs can label each one.
+
+Source: `src/types/session.ts`, `src/types/agent.ts`, `src/core/Runner.ts`, `src/core/Speak.ts`, `src/utils/outcomes.ts`, `src/utils/schema.ts`.
+
+## Signature
+
+```ts fragment
+type StepOutcomeKind = "prompt" | "collect" | "say" | "do" | "wait" | "if" | "idle";
+type StepOutcomeStatus = "ok" | "skipped" | "failed" | "waiting" | "deferred";
+
+type StepOutcomeCode =
+  // The turn refused the input
+  | "no-session" | "duplicate-input" | "stale-wake" | "silence-broken"
+  // A trigger matched but started nothing
+  | "already-claimed" | "cooldown" | "hop-limit" | "already-running" | "flow-gone"
+  // A run ended early
+  | "step-loop" | "step-gone" | "customer-replied" | "premise-changed" | "silenced"
+  // A step
+  | "already-known" | "another-reply" | "already-sent" | "branch" | "max-asks"
+  | "inline-delay" | "awaiting-trigger" | "awaiting-event" | "event-arrived"
+  | "no-event" | "replied" | "no-reply"
+  // A host action
+  | "action-skipped" | "action-failed" | "action-deferred"
+  // A value the model gave
+  | "unknown-field" | "bad-value" | "not-in-enum"
+  // The model
+  | "provider-unavailable" | "provider-quota" | "provider-auth"
+  | "provider-context" | "provider-invalid";
+
+interface StepOutcome {
+  runId?: string;
+  flowId?: string;
+  stepId?: string;
+  key?: string;
+  kind: StepOutcomeKind;
+  status: StepOutcomeStatus;
+  /** Why. Absent when the line needs no reason. Switch on this. */
+  code?: StepOutcomeCode;
+  /** The English sentence for `code`, filled by the framework. */
+  message?: string;
+  detail?: string;
+  next?: string;
+  until?: string;
+  at: string;
+  llmCalls?: number;
+}
+
+type EndReason = "end" | "flow" | "reset" | "skipped" | "failed" | "replaced";
+
+interface TurnResult<D = unknown> {
+  outcomes: StepOutcome[];
+  started: Array<{ runId: string; flowId: string; anchor: string; dedupeKey: string }>;
+  ended: Array<Run & { reason: EndReason }>;
+  skipped: Array<{ flowId: string; anchor: string; triggerKey: string; code: StepOutcomeCode; message: string }>;
+  llmCalls: number;
+  // session, changed, messages, schedule: see Agent
+}
+```
+
+## StepOutcome fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `runId` | `string` | `${flowId}#${triggerKey}`. Absent on lines that belong to no run (an ignored input, a dropped value, the idle speaker). |
+| `flowId` | `string` | The run's flow. Absent whenever `runId` is absent. |
+| `stepId` | `string` | The step the line is about. Absent when the run has not entered a step, and whenever `runId` is absent. |
+| `key` | `string` | Three shapes: `${runId}:${stepId}:${visit}` on a step line, the input's own key on an ignored input, `idle:${triggerKey}` on the idle speaker's `ok` line. Absent on three kinds of line. A run-ending line. A wait line written during Ingest (`replied`, `no-reply`, `no-event`, `event-arrived`, `awaiting-trigger`) — a message turn writes `replied` too, when the customer's reply resolves a parked `wait`. And a `collect / skipped` line for a value the model gave that could not be written (`unknown-field`, `bad-value`, `not-in-enum`). |
+| `kind` | `StepOutcomeKind` | What kind of step. `prompt` and `collect` are both talk steps: `collect` when the step has a non-empty `collect` list. `idle` is the idle speaker. |
+| `status` | `StepOutcomeStatus` | See below. |
+| `code` | `StepOutcomeCode` | Why the line says what it says. Switch on this; it is stable across versions. Absent when the line needs no reason (a step that simply ran). |
+| `message` | `string` | The English sentence for `code`, copied in by the framework so a log reads on its own. To show a line in another language, map `code` yourself. The whole table is exported as `OUTCOME_MESSAGES`. Absent whenever `code` is. |
+| `detail` | `string` | Text this one occurrence adds: the field slug (`unknown-field`, `bad-value`, `not-in-enum`, `max-asks`), the action's own words (`action-skipped`, `action-failed`, `action-deferred`), your `silenced` reason, the event name (`awaiting-event`), `"5000ms"` (`inline-delay`). |
+| `next` | `string` | Where the step's `then` sent the run: a step id, `end`, or `flow:<id>` when it chained into another flow. Absent when the step has no `then` (the run still moves to the next step in order), when it parked, when the line does not move it, and on the talk step's `ok` line after a speak call. |
+| `until` | `string` | ISO time of the wake, on `waiting` and `deferred` lines. |
+| `at` | `string` | ISO time of the turn (the agent's clock). |
+| `llmCalls` | `number` | Model calls the speak call spent. Present on the talk step's `ok` line and on both idle lines (`ok` and `deferred`). The talk step's `deferred` line does not carry it; `TurnResult.llmCalls` still counts those calls. |
+
+### Statuses
+
+| Status | Meaning |
+|---|---|
+| `ok` | The step did its job and the run moved (or is now asking). |
+| `skipped` | Nothing happened here, on purpose. `code` says why. |
+| `failed` | An action returned `failed`, or the run hit the 50-step cap. |
+| `waiting` | The run parked. `until` says when the wake fires. |
+| `deferred` | The step will be tried again later: an action asked for it, or the provider failed. |
+
+### Where lines land
+
+- `TurnResult.outcomes`: every line of this turn, in order, run lines and no-run lines alike.
+- `run.outcomes`: the run's own lines, kept to the last 50, on the run inside `session.runs` and inside `TurnResult.ended`.
+- `TurnResult.changed` is `false` when the input was ignored; the one ignored-input line is still on `outcomes` so you can log it, but there is nothing to save or send.
+
+## Every code
+
+Grouped by what produced it. `kind` and `status` are given as `kind / status`. A blank `code` cell means the line carries no code at all.
+
+### The input was ignored
+
+`wait / skipped`, no run, `key` = the input's key, `changed: false`.
+
+| `code` | When |
+|---|---|
+| `no-session` | `turn({ wake })` with no `session`. A wake never creates a session. |
+| `duplicate-input` | `turn({ message, id })` with an `id` already among the session's last 50 input ids. A replay of an already applied message. |
+| `stale-wake` | A wake key that no live run is waiting on. The run moved on, ended, or was re-parked under a newer key. |
+| `silence-broken` | A silence wake whose time no longer matches `lastAssistantAt`, or the customer wrote since. The assistant or the customer spoke after the wake was set. |
+
+### Waits and wakes
+
+| `kind / status` | `code` | When | `next` |
+|---|---|---|---|
+| `wait / ok` | `inline-delay`, `detail` = `"5000ms"` | A `wait` of 10 s or less, followed by a `say` or talk step, became the next message's `afterMs` delay. No wake. | `then` |
+| `wait / waiting` | none | A timer `wait` parked. Wake key `${runId}:${stepId}:${atMs}`. | |
+| `wait / ok` | `no-reply` | The wake fired and the customer had not written since the wait was set. | `then` |
+| `wait / ok` | `replied` | The customer wrote (a message, or an `inbound` event) while a timer `wait` with `else` was parked; or the wake fired after the customer had written. | `else`; when the customer's reply resolves the wait (a message or an `inbound` event), a matching `if` branch's `then` wins. When the wake fires after the customer had written, always `else` |
+| `wait / waiting` | `awaiting-event`, `detail` = the event name | A `wait: { event }` parked. `until` = now + `upTo` (default 30 days). | |
+| `wait / ok` | `event-arrived` | The event was reported before `upTo`. | `then` |
+| `wait / ok` | `no-event` | The `upTo` wake fired first. | `else`, or `end` |
+| `wait / waiting` | `awaiting-trigger` | A run started by an `event` trigger with `after` parked before its first step. Wake key `${runId}:start:${atMs}`. | |
+
+### Talk steps (`prompt` / `collect`)
+
+| `kind / status` | `code` | When | `next` |
+|---|---|---|---|
+| `prompt` or `collect / ok` | none; `llmCalls` set | The speak call answered. The run is asking if fields are still pending, else it moved. | none. This line never carries `next`, even when the run moves on; the lines that follow show where it went |
+| `collect / skipped` | `already-known` | The step was entered and every field it collects was already known (or at `maxAsks`). No call. | `then` |
+| `collect / ok` | none, no `llmCalls` | An asking step whose remaining fields were all known when the customer's next message resumed it: the understand call filled them in from the message, or an action's `ctx.set()` or a tool's `data` had written them since the step last asked. It moved without speaking. | `then` |
+| `collect / skipped` | `max-asks`, `detail` = the field slug | One line per field still unknown when the step moves on because that field reached `maxAsks` (default 3). | |
+| `prompt` or `collect / ok` | `branch` | A branch of the asking step fired: an `if` branch held, or the model answered `when` with true. | the branch's `then` |
+| `prompt` or `collect / skipped` | `another-reply` | On a message turn, another run's `say` or an action with `spoke: true` already answered. The talk waits; the run stays asking. | |
+| `prompt` or `collect / skipped` | `silenced`, `detail` = your reason | The step was reached fresh while `silenced`. The run ends (`reason: 'skipped'`). A step that was already asking stays asking silently and writes no line. | |
+| `prompt` or `collect / deferred` | `provider-unavailable`, `provider-quota` | Waiting can still fix it: the provider was down, slow, rate-limited, or returned an empty message; or a usage window said when it reopens. The step is re-parked under `${runId}:${stepId}:${visit}:retry:${atMs}` at +1m, +5m, +15m, +1h, +6h, or at the stated reset when that is later. `until` set. | |
+| `prompt` or `collect / failed` | `provider-auth`, `provider-context`, `provider-invalid`, `provider-quota` | Waiting cannot fix it: a rejected key, a prompt past the context window, a request the provider refused, a spent balance with no stated reset. No wake; the run ends `failed`. | |
+| `prompt` or `collect / failed` | `provider-unavailable` | The retryable ladder ran out — six failures on the same step. The run ends `failed`. | |
+
+### Say steps
+
+| `kind / status` | `code` | When | `next` |
+|---|---|---|---|
+| `say / ok` | none | The text went into `messages[]` with `kind: 'verbatim'`. | `then` |
+| `say / skipped` | `already-sent` | `once: true` and this step already sent in this session (claim `${flowId}:${stepId}:${sessionId}`). | `then` |
+| `say / skipped` | `silenced`, `detail` = your reason | Reached while `silenced`. The run ends (`reason: 'skipped'`). | |
+
+### Do steps
+
+The action's own words arrive in `detail`, unprefixed, exactly as it returned them.
+
+| `kind / status` | `code` | When | `next` |
+|---|---|---|---|
+| `do / ok` | none; `detail` when the action gave one | The action returned `{ ok: true }`. | `then` |
+| `do / skipped` | `action-skipped`, `detail` = the action's words | The action returned `{ skipped: reason }`. | `then` |
+| `do / failed` | `action-failed`, `detail` = the action's words | The action returned `{ failed: reason }` or threw, and then the error message is the reason. | `onFail`, else `then` |
+| `do / failed` | `action-failed`, `detail: 'unknown action "notify"'` | The action name is not registered. The agent constructor refuses such a flow, so this appears only if registries changed under a running agent. | `onFail`, else `then` |
+| `do / deferred` | `action-deferred`, `detail` = the action's words | The action returned `{ defer, detail }`. Wake key `${runId}:${stepId}:${atMs}`; the same step re-runs at the same visit, same `ctx.key`. `until` set. | |
+
+### If steps
+
+| `kind / status` | `code` | When | `next` |
+|---|---|---|---|
+| `if / ok` | none | The predicate was judged. | `then` on true; `else` or `end` on false |
+
+### Values the model gave
+
+`collect / skipped`, no run, `detail` = the field slug. The understand or speak call reported a value that could not be written.
+
+| `code` | When |
+|---|---|
+| `unknown-field` | The model named a field the agent does not have. |
+| `bad-value` | The value could not be turned into the field's type (`string`, `number`, `integer`, `boolean`). Strings become numbers and booleans when they parse; `sim`/`não` count as booleans. |
+| `not-in-enum` | The value is not in the field's `enum`. |
+
+Tool `data` is written without these checks and never produces these lines.
+
+### The idle speaker
+
+No run.
+
+| `kind / status` | `code` | When |
+|---|---|---|
+| `idle / ok` | none; `llmCalls` and `key` (`idle:${triggerKey}`) set | No run held the floor on a message turn and `idle` is not `'silent'`; the model answered. |
+| `idle / deferred` | any `provider-*` code; `llmCalls` set, no `key` | The idle speaker's call failed or came back empty. No retry wake either way: it has no step to re-park, and the next message tries again. |
+
+### A run ended early
+
+The run leaves `session.runs`, appears in `TurnResult.ended`, and writes one line whose `kind` is the current step's kind, or `if` when the run had not entered a step yet.
+
+| `status` | `code` | `reason` on `ended` | When |
+|---|---|---|---|
+| `skipped` | `premise-changed` | `skipped` | The flow's `while` (default: the trigger's `if`) stopped holding when the run was about to move. |
+| `skipped` | `customer-replied` | `skipped` | A silence run woke up, but the customer had written since the run started. |
+| `skipped` | `flow-gone` | `skipped` | The run's flow is no longer on the agent. |
+| `skipped` | `step-gone` | `skipped` | The run's step id, or a `then` target, is no longer in the flow. |
+| `skipped` | `silenced`, `detail` = your reason | `skipped` | A talk or `say` step reached while `silenced` (see above). |
+| `failed` | `step-loop` | `failed` | The run moved through 50 steps in one turn. A cycle with no wait, talk or end. |
+
+## End reasons
+
+`TurnResult.ended` carries each ended run with its `reason`:
+
+| `reason` | When |
+|---|---|
+| `end` | The run passed its last step, hit `then: 'end'`, or `onEnd` is `'end'` (the default). |
+| `flow` | The run followed `then: { flow }`; a child run started at `hop + 1`. |
+| `reset` | `onEnd: 'reset'`: this run closed and a fresh run of the same flow started at step one, data kept, `hop + 1`. |
+| `skipped` | One of the codes above: `premise-changed`, `customer-replied`, `flow-gone`, `step-gone` or `silenced`. |
+| `failed` | `step-loop`. |
+| `replaced` | The run was parked on its trigger's `after` (no step entered) and the same trigger fired again: the new run takes its place. |
+
+## Triggers that matched but started nothing
+
+`TurnResult.skipped` entries have `{ flowId, anchor, triggerKey, code, message }` and write no `StepOutcome`.
+
+| `code` | When |
+|---|---|
+| `already-claimed` | `repeat: 'once'` and this flow already ran for this session or anchor; or `repeat: 'always'` and this exact trigger key was already used (a replayed event, start or chain). |
+| `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. |
+
+A trigger whose `if` is false starts nothing and writes nothing.
+
+## Example
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+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: [] }], // no examples: the catch-all, starts when no other message flow wins
+      steps: [
+        { id: "quem", collect: ["nome"] },
+        { id: "tchau", say: "Obrigada, {{data.nome}}. Um vendedor continua daqui." },
+      ],
+    }),
+  ],
+});
+
+const r = await agent.turn({ sessionId: "demo", message: "oi, sou a Ana" });
+
+for (const line of r.outcomes) {
+  console.log(`${line.stepId ?? "-"} ${line.kind}/${line.status} ${line.code ?? ""} ${line.detail ?? ""} → ${line.next ?? ""}`);
+}
+for (const run of r.ended) console.log(`${run.id} ended: ${run.reason}`);
+for (const skip of r.skipped) console.log(`${skip.flowId} not started: ${skip.code}`);
+console.log(`model calls: ${r.llmCalls}`);
+```
+
+## See also
+
+- [Runs and waits](../concepts/runs-and-waits.md): statuses, the floor, wakes and the key table.
+- [Session](./session.md): `Run`, `RunStatus` and where `outcomes` live.
+- [Error handling](../guides/error-handling.md): what a deferred talk step means for the host.
+- [Actions, events, conditions](./actions-events-conditions.md): `ActionResult` and the `do` lines.