@falai/agent 3.4.5 → 4.0.0-alpha.1

package/docs/reference/step.md

@@ -1,345 +1,227 @@
 ---
 title: "Step"
-description: "A node inside a flow — collects data, calls tools, runs computational work, or speaks a verbatim line."
+description: "StepBase and the six step kinds as tables, what then and else mean for each, Next in all its forms, and the per-turn caps."
 type: reference
 order: 3
 ---
 
 # Step
 
-> **Where this is introduced:** [Architecture](../concepts/architecture.md)
+A step is one thing a run does: the model talks, a fixed text goes out, the host does something, the run waits, or the code forks. Every step has an `id` and may have a `then`. A run enters the first step and moves to the next one in the list unless `then` says otherwise. There are six kinds, told apart by which property is present: `prompt` or `collect` (talk), `say`, `do`, `wait` with a duration, `wait` with an event, and `if`.
 
-A `Step` is a single node inside a `Flow`. Each step describes what
-the agent does at one point in a conversation: ask a question, collect
-schema fields, call tools, run a hook, branch to another step, or
-speak a verbatim line. Steps are the smallest unit the engine can
-suspend on between user turns.
+## Signature
 
-Steps are normally declared as `StepOptions` objects inside a flow's
-`steps[]` array. The `Step` class itself is rarely instantiated by
-hand — `createAgent` and `Flow.addStep` build instances from the
-options shape below. Validation runs eagerly at construction, so
-misuse surfaces as `FlowConfigurationError` before any turn runs.
+```ts fragment
+interface StepBase<D = unknown> {
+  id: string;
+  label?: string;
+  then?: Next<D>;
+  ui?: Record<string, unknown>;
+}
 
-A step is one of three mutually exclusive shapes:
+type Step<C, D> = StepBase<D> &
+  (TalkStep<C, D> | SayStep | DoStep<D> | WaitStep<C, D> | WaitEventStep<D> | IfStep<C, D>);
 
-- **LLM step** — the default. Has `prompt`, optionally `collect` / `tools` / `instructions`. The engine calls the LLM.
-- **Auto step** — `auto: true`. Pure computation, no LLM call. Only `onEnter`, `prepare`, and `branches` execute. Counts against `maxAutoStepsPerTurn`.
-- **Reply step** — `reply` is set. Renders a verbatim assistant message with no LLM call.
+type Next<D> =
+  | string
+  | { step: string; clear?: (keyof D & string)[] }
+  | { flow: Template; input?: unknown };
+```
 
-Mixing fields between shapes throws at construction time.
+## StepBase
 
-## Signature
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `id` | `string` | required | Unique inside the flow. Never `'end'`. Part of every message and action key (`${runId}:${id}:${visit}`). |
+| `label` | `string` | none | A human label for editors and logs. The framework never reads it. |
+| `then` | `Next<D>` | the next step in the list | Where the run goes when the step is done. At the last step, `onEnd` decides. |
+| `ui` | `Record<string, unknown>` | none | Editor data the framework carries and never reads. |
 
-```typescript
-interface StepOptions<TContext = unknown, TData = unknown> {
-  id?: string;
-  description?: string;
-
-  // Behaviour
-  prompt?: Template<TContext, TData>;
-  reply?: Template<TContext, TData>;
-  auto?: boolean;
-
-  // Data
-  collect?: (keyof TData)[];
-  requires?: (keyof TData)[];
-
-  // Activation
-  when?: ConditionWhen;                       // AI strings — `string | string[]`
-  if?: ConditionIf<TContext, TData>;          // code predicates — function or array
-  skip?: ConditionIf<TContext, TData>;        // code predicates — OR semantics
-
-  // Surface
-  tools?: (string | Tool<TContext, TData>)[];
-  instructions?: Instruction<TContext, TData>[];
-
-  // Lifecycle (shorthand — returns PrepareResult)
-  prepare?:
-    | string                                  // tool id
-    | Tool<TContext, TData>
-    | ((ctx: TContext, data?: Partial<TData>) =>
-        void | PrepareResult | Promise<void | PrepareResult>);
-  finalize?:
-    | string
-    | Tool<TContext, TData>
-    | ((ctx: TContext, data?: Partial<TData>) =>
-        void | PrepareResult | Promise<void | PrepareResult>);
-
-  // Lifecycle (full — receives HookContext, returns Directive)
-  hooks?: StepLifecycleHooks<TContext, TData>;
-
-  // Routing
-  branches?: BranchMap<TContext, TData>;
-}
+## Talk step
 
-interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
-  onEnter?: (ctx: HookContext<TContext, TData>) =>
-    void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
-  prepare?: (ctx: HookContext<TContext, TData>) =>
-    void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
-  finalize?: (ctx: HookContext<TContext, TData>) =>
-    void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
-  onExit?: (ctx: HookContext<TContext, TData>, reason: ExitReason) =>
-    void | Promise<void>;
-}
-```
+The model speaks. A guideline, fields to collect, or both.
 
-## Fields
-
-| Field | Type | Required | Default | Notes |
-|-------|------|----------|---------|-------|
-| `id` | `string` | no | derived from `description` | Stable identifier used by `goToStep`, `branches.then`, and event traces. Must be unique within the flow. |
-| `description` | `string` | no | — | One-line summary surfaced in routing and event traces. Used to derive `id` when omitted. |
-| `prompt` | `Template<TContext, TData>` | no | — | String or function `(params) => string \| Promise<string>`. Becomes the system-prompt instruction for the LLM call this step makes. Mutually exclusive with `auto: true` and `reply`. |
-| `reply` | `Template<TContext, TData>` | no | — | Verbatim assistant message. When set, the engine renders this template and emits it without calling the LLM. Cannot coexist with `prompt`, `collect`, `tools`, `finalize`, or `auto: true`. `stoppedReason: 'reply'`. |
-| `auto` | `boolean` | no | `false` | When `true`, the step runs without an LLM call — only `onEnter`, `prepare`, and `branches` execute. Cannot coexist with `prompt`, `collect`, `tools`, or `finalize`. Counts against `maxAutoStepsPerTurn`. |
-| `collect` | `(keyof TData)[]` | no | `[]` | Schema field keys this step is responsible for extracting from the user message. Every key must exist in the agent's `schema`. The engine skips the step automatically when every listed key is already present in `session.data` (pre-extraction). |
-| `requires` | `(keyof TData)[]` | no | `[]` | Prerequisite field keys. The engine refuses to enter the step until every key is present in `session.data`. When fields covered by `requires` are read inside `branches[].if` predicates, they are guaranteed to be defined. |
-| `when` | `string \| string[]` | no | — | AI-evaluated activation strings. Non-`!` strings are OR alternatives; `!` strings are OR exclusions where any match inhibits activation. Evaluated by the LLM at routing time. Functions are not allowed here — the constructor throws `FlowConfigurationError` if a function is found. |
-| `if` | `(ctx) => boolean \| Promise<boolean>` or array | no | — | Code-evaluated activation predicates (AND semantics). Evaluated locally — no LLM cost. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if every `if` predicate passes. |
-| `skip` | `(ctx) => boolean \| Promise<boolean>` or array | no | — | Code-evaluated skip predicates (OR semantics). When any predicate returns `true`, the step is bypassed. Only code predicates — no AI strings. |
-| `tools` | `(string \| Tool<TContext, TData>)[]` | no | `[]` | Tools available during this step. Strings are resolved against the agent's tool registry; objects are inline tools. Stacked on top of agent and flow scopes. |
-| `instructions` | `Instruction<TContext, TData>[]` | no | `[]` | Step-scoped behavioural statements (`kind: 'must' \| 'never' \| 'should'`). Active only while this step is current. See [Instruction](./instruction.md). |
-| `prepare` | function, tool id, or `Tool` object | no | — | Pre-LLM hook. Receives `(context, data?)` and returns `void \| PrepareResult` (a Directive may be returned too). `PrepareResult` includes the pre-LLM augmentation fields `appendPrompt: string[]` and `injectTools: Tool[]` — honored by auto steps; other step kinds drop them with a loud warning. |
-| `finalize` | function, tool id, or `Tool` object | no | — | Post-generation hook, runs before persistence. Same shape as `prepare`. A returned `goTo`/`goToStep`/`reset`/`complete` redirects the **next** turn; state writes land immediately. |
-| `hooks` | `StepLifecycleHooks<TContext, TData>` | no | — | Alternative spelling of `prepare`/`finalize` (`hooks.prepare`, `hooks.finalize`). Both spellings run when declared together — shorthand first, then the hook, returns merged via Algorithm 4. |
-| `branches` | `BranchEntry<TContext, TData>[]` | no | — | Explicit source-local fork. Evaluated after `finalize`, before linear successor selection. The first entry whose `if`/`when` passes wins; its `then` resolves to a step id, a flow id, or a `Directive`. See [Branches](./branches.md). |
-
-### Lifecycle hooks
-
-Two hook positions exist per step: `prepare` (before generation) and
-`finalize` (after generation, before persistence). Each is reachable
-through a top-level field, a `hooks.*` entry, or both — declaring both
-runs them in sequence (shorthand first) with their returns merged by
-Algorithm 4 (`flow.merge`).
-
-| Position | When it fires | May return | Use it for |
-|----------|---------------|------------|------------|
-| `prepare` / `hooks.prepare` | Before routing on the step's turn (non-auto steps). | `void \| PrepareResult` | Write session/context state, redirect the current turn with `goToStep`/`goTo`/`reset` (queued as `pendingDirective` and applied by routing this turn). |
-| `finalize` / `hooks.finalize` | After generation completes, BEFORE the session is persisted. | `void \| PrepareResult` | Validate collected data, write state, queue a redirect for the next turn (`pendingDirective`), e.g. `{ complete: { next: { goTo: 'Checkout' } } }`. |
-
-Handler directives merge through the canonical algorithm and are
-validated with `flow.validate`. State writes
-(`dataUpdate`/`contextUpdate`) apply immediately to the turn session,
-so auto-save captures them even if this is the conversation's last
-turn.
-
-Note for **auto steps**: their `prepare` runs inside the auto-chain,
-where pre-LLM fields (`appendPrompt`, `injectTools`, `halt`, `reply`)
-are honored directly.
-
-### Resolution within a step
-
-For one step, the engine walks this sequence per turn:
-
-1. Evaluate `if` (code, AND) and `when` (AI: positive OR, `!` exclusions inhibit) — fails skip the step entirely.
-2. Evaluate `skip` (code, OR) — true means bypass and fall through.
-3. Check `requires` — refuse entry if any required field is missing.
-4. Run `prepare` / `hooks.prepare`. Its merged directive applies state writes immediately; position fields queue as `pendingDirective` for this turn's routing.
-5. **LLM step**: call the LLM with the step's prompt, tools, and instructions; tool loop runs until completion. **Auto step**: skip the LLM call. **Reply step**: render `reply` as the verbatim assistant message.
-6. Run `finalize` / `hooks.finalize` (before persistence). State writes land now; position fields queue for the next turn.
-7. Evaluate `branches`. The first entry whose `if`/`when` passes wins; its `then` resolves to a step id, a flow id, or a full `Directive`. If no entry matches, fall through.
-8. Linear successor / AI step selection.
-9. Persist the session (auto-save) after finalize has run.
-
-## Examples
-
-### Collecting fields with prerequisites and skip
-
-```typescript
-import { createAgent, GeminiProvider } from '@falai/agent';
-
-const agent = createAgent({
-  name: 'BookingBot',
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: {
-    type: 'object',
-    properties: {
-      city: { type: 'string' },
-      checkIn: { type: 'string' },
-      guests: { type: 'integer' },
-    },
-  },
-  flows: [
-    {
-      title: 'Book',
-      requiredFields: ['city', 'checkIn', 'guests'],
-      steps: [
-        {
-          id: 'ask_destination',
-          prompt: 'Find out where and when the user wants to stay.',
-          collect: ['city', 'checkIn'],
-        },
-        {
-          id: 'ask_guests',
-          prompt: 'Confirm how many people are travelling.',
-          collect: ['guests'],
-          requires: ['city', 'checkIn'],
-          // Skip if the user already mentioned a party size
-          skip: ({ data }) => typeof data.guests === 'number',
-        },
-      ],
-    },
-  ],
-});
+```ts fragment
+type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | { collect: (keyof D & string)[]; prompt?: Template }) & {
+  ask?: Partial<Record<keyof D & string, string>>;
+  maxAsks?: number;
+  branches?: Branch<C, D>[];
+  tools?: string[];
+  instructions?: Instruction<C, D>[];
+};
 ```
 
-### Auto step with branches and a reply step
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `prompt` | `Template` | "Collect what is still missing below, in the flow of the conversation, one or two things per message." | The guideline for the reply. Required when there is no `collect`. |
+| `collect` | `(keyof D & string)[]` | none | Fields to collect. The step is done when they are known. |
+| `ask` | `Partial<Record<slug, string>>` | the field's own `ask` | Per-flow wording for a field. |
+| `maxAsks` | `number` | `3` | Times a field may be asked before it is skipped (`code: 'max-asks'`, the field in `detail`). |
+| `branches` | `Branch<C, D>[]` | none | Exits judged while the step asks. See [Branches](branches.md). |
+| `tools` | `string[]` | the flow's `tools`, else all | Tools the model may call from this step. |
+| `instructions` | `Instruction<C, D>[]` | none | Rules that apply only while this step speaks. |
 
-```typescript
-import { createAgent, GeminiProvider } from '@falai/agent';
+- Pending fields are `collect` minus the known ones minus those at `maxAsks`, in `collect` order. A step the run enters whose pending list is empty is skipped with no model call (`code: 'already-known'`) and the run follows `then`. When the asking run resumes and the message filled the last field, the same move is logged `ok` with no detail.
+- Reaching a talk step suspends any other run that was asking; this run becomes the asker and holds the floor. It speaks in this turn if the speak call has not happened yet; otherwise it speaks on the next message.
+- The speak call returns the message plus one value per pending field. Values are validated and written; each field still pending is counted as asked once more. With pending fields left the run stays asking. With none left, or with no `collect` at all, the run follows `then` in the same turn.
+- With `silenced` set, a talk step ends the run with `code: 'silenced'` (`detail` = your reason); a run that was already asking stays asking instead.
+- Outcome kind: `collect` when `collect` is non-empty, else `prompt`.
 
-const agent = createAgent({
-  name: 'EligibilityRouter',
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: {
-    type: 'object',
-    properties: { tier: { type: 'string' } },
-  },
-  flows: [
-    {
-      title: 'Quote',
-      steps: [
-        // Pure computation — no LLM call.
-        {
-          id: 'check_tier',
-          auto: true,
-          requires: ['tier'],
-          branches: [
-            { if: ({ data }) => data.tier === 'enterprise', then: 'concierge' },
-            { when: 'the user already used their free trial', then: 'upsell' },
-            { then: 'self_serve' }, // unconditional fallback
-          ],
-        },
-        // Verbatim message — no LLM call.
-        {
-          id: 'concierge',
-          reply: 'A concierge specialist will reach out within an hour.',
-        },
-        { id: 'upsell', prompt: 'Pitch the paid plan in two short sentences.' },
-        { id: 'self_serve', prompt: 'Walk them through the self-serve form.' },
-      ],
-    },
-  ],
-});
-```
+`then`: taken when every collected field is known (or skipped at `maxAsks`), or right after speaking for a step without `collect`. There is no `else`; use `branches`.
+
+## Say step
+
+A fixed message goes out, verbatim. No model call.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `say` | `Template` | required | The text. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are filled in. |
+| `media` | `{ slug: string }` | none | Passed through on the outbound message. |
+| `once` | `boolean` | `false` | Send at most once per session. A second visit is `code: 'already-sent'` and the run moves on. The claim key is `${flowId}:${stepId}:${sessionId}`. |
+
+- The message goes out with `kind: 'verbatim'` and `key = ${runId}:${stepId}:${visit}`. A short `wait` right before it becomes its `afterMs`.
+- A `say` counts as the assistant speaking: it re-arms silence triggers, and it makes any other run's talk step wait for the next message (`code: 'another-reply'`).
+- With `silenced` set, the run ends with `code: 'silenced'` (`detail` = your reason).
+
+`then`: taken right after the message is queued.
+
+## Do step
+
+The host does something. Runs even when `silenced`.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `do` | `string` | required | The action's name in the agent's `actions`. |
+| `with` | `Record<string, unknown>` | `{}` | The action's parameters. Checked at construction against `parameters`; strings are rendered as templates at run time. |
+| `onFail` | `Next<D>` | `then` | Where to go when the action reports `{ failed }` or throws. |
+
+- The action gets `{ context, data, input, run, key, dedupeKey, silenced, now, set }`. `key` is `${runId}:${stepId}:${visit}`, the same on a replay; make the handler idempotent on it.
+- `{ ok }` continues along `then`; `spoke: true` counts as the assistant speaking. `{ skipped: reason }` logs `code: 'action-skipped'` and continues along `then`. `{ failed: reason }` logs `code: 'action-failed'` and follows `onFail`, else `then`. A thrown error is a `failed` with the error's message.
+- `{ defer: '5m', detail }` parks the run under the wake key `${runId}:${stepId}:${atMs}`. At the wake the step runs again at the same visit, so with the same `key`.
+
+`then`: after `ok` or `skipped`, and after `failed` when there is no `onFail`.
 
-### `when` + `if`, scoped tools and instructions, hook-driven redirect
+## Wait step (duration)
 
-```typescript
-import { createAgent, GeminiProvider } from '@falai/agent';
+The run parks for a while.
 
-const agent = createAgent({
-  name: 'Refunds',
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: {
-    type: 'object',
-    properties: {
-      orderId: { type: 'string' },
-      refundAmount: { type: 'number' },
-    },
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `wait` | `Duration` | required | How long: `'30s'`, `'5m'`, `'24h'`, `'3d'`. |
+| `businessHours` | `boolean` | `false` | Snap the end of the wait forward with the agent's `businessHours`. |
+| `else` | `Next<D>` | none | Where to go when the customer writes before the time passes. Without it the customer's message does not end the wait. |
+| `branches` | `Branch<C, D>[]` | none | `if` branches judged when the customer writes, before `else`. See [Branches](branches.md). |
+
+- A wait of 10 seconds or less whose `then` leads straight to a `say` or talk step does not park: it becomes that message's `afterMs` (status `ok`, `code: 'inline-delay'`, `detail: '<ms>ms'`).
+- Otherwise the run parks under the wake key `${runId}:${stepId}:${atMs}` and one `schedule[]` entry is returned (outcome `waiting`, with `until`).
+- When the customer writes (a message, or an event with `direction: 'inbound'`) and the step has `else`, the run resumes at once: the first `if` branch that holds wins, else `else` (outcome `code: 'replied'`).
+- When the wake fires: `then` (`code: 'no-reply'`), or `else` when the step has one and the customer wrote after the wait was set (`code: 'replied'`).
+
+`then`: the time passed. `else`: the customer replied first.
+
+## Wait step (event)
+
+The run parks until a host event arrives.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `wait.event` | `string` | required | The event's name in the agent's `events`. |
+| `wait.upTo` | `Duration` | `'30d'` | Give up after this long. |
+| `else` | `Next<D>` | `'end'` | Where to go when `upTo` passes without the event. |
+
+- The run parks under the wake key `${runId}:${stepId}:${atMs}` (status `waiting`, `code: 'awaiting-event'`, the event name in `detail`).
+- `turn({ event })` with that name resumes every run waiting on it (outcome `code: 'event-arrived'`); the run takes the floor and follows `then` in the same turn. The event's `payload` does not replace the run's `input`.
+- When the wake fires first: `else`, or the run ends when there is none (outcome `code: 'no-event'`).
+
+`then`: the event came. `else`: `upTo` passed.
+
+## If step
+
+The code forks. No model call.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `if` | `Pred<C, D>` | required | A function `(ctx) => boolean`, or a `ConditionSpec` such as `{ equals: { confirmado: true } }`, `{ known: ['nome'] }`, `{ silenced: true }` or `{ naEtapa: 'proposta' }`. See [Conditions](../guides/conditions.md). |
+| `else` | `Next<D>` | `'end'` | Where to go when `if` is false. |
+
+- An `if` whose `then` jumps backward must have an `else`; construction rejects it otherwise.
+
+`then`: true. `else`: false.
+
+## Next
+
+| Form | Meaning |
+|---|---|
+| `'passo'` | Jump to that step id. |
+| `'end'` | Finish the run here, exactly as running past the last step does — `onEnd` still decides: `'end'` ends it, `'stay'` re-enters the last step and keeps asking, `'reset'` starts a fresh run. `'end'` is reserved: no step may use it as an id. |
+| `{ step: 'passo', clear: ['campo'] }` | Delete the listed fields from `session.data`, then jump. The way to ask something again. |
+| `{ flow: 'outro', input? }` | End this run (reason `'flow'`) and start `outro` in the same turn, one hop deeper. The child gets `input`, or this run's `input` when absent, and holds the floor. `flow` is a template. |
+
+Entering a step counts a visit; the visit is part of every key minted there, so a step visited twice sends twice. A `{ step }` jump to an id that no longer exists ends the run with `code: 'step-gone'`; a `{ flow }` to an unknown flow is skipped with `code: 'flow-gone'`.
+
+## Caps
+
+| Cap | Value | What happens |
+|---|---|---|
+| Steps per run per turn | 50 | The run ends with reason `'failed'` and `code: 'step-loop'`. |
+| Chain depth (`hop`) | 5 | A `{ flow }` or `onEnd: 'reset'` at hop 5 is skipped with `code: 'hop-limit'`. |
+| Short wait | 10 s | At or under it, and followed by a `say` or talk step, a wait rides as `afterMs` instead of a wake. |
+| Outcomes kept per run | 50 | Older lines fall off `run.outcomes`; `TurnResult.outcomes` is never trimmed. |
+
+## Example
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+const f = falai().fields({
+  pedido: { type: "string", ask: "Pergunte o número do pedido." },
+  resolvido: { type: "boolean", ask: "Pergunte se o problema foi resolvido." },
+});
+
+const agent = f.agent({
+  name: "Léo",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  events: { reembolso_feito: f.event<{ valor: number }>() },
+  actions: {
+    abrir_chamado: f.action({
+      parameters: { pedido: { type: "string" } },
+      run: (params) => ({ ok: true, detail: `chamado aberto para ${params.pedido}` }),
+    }),
   },
   flows: [
-    {
-      title: 'Refund',
+    f.flow({
+      id: "suporte",
+      name: "Suporte a pedidos",
+      on: [{ message: ["problema com um pedido", "pedido atrasado ou errado"] }],
       steps: [
-        {
-          id: 'verify',
-          prompt: 'Look up the order and quote a refund amount.',
-          collect: ['orderId', 'refundAmount'],
-          // Run only when both signals agree the user is requesting a refund.
-          when: 'the user is requesting a refund',
-          if: ({ context }) =>
-            (context as { authenticated: boolean }).authenticated,
-          tools: ['lookup_order'],
-          instructions: [
-            { kind: 'must',  prompt: 'State the refund amount before confirming.' },
-            { kind: 'never', prompt: 'Promise refunds without checking eligibility.' },
-          ],
-          hooks: {
-            // Full hook — receives HookContext, returns Directive.
-            finalize: ({ data }) => {
-              if ((data.refundAmount ?? 0) > 500) {
-                return { goToStep: 'manager_review' };
-              }
-            },
-          },
-        },
-        { id: 'manager_review', prompt: 'Hand off to a manager for approval.' },
+        // talk: done when `pedido` is known
+        { id: "dados", collect: ["pedido"] },
+        // do: the host acts; `with` is rendered
+        { id: "chamado", do: "abrir_chamado", with: { pedido: "{{data.pedido}}" }, onFail: "sem-chamado" },
+        // say: verbatim
+        { id: "aviso", say: "Abri um chamado para o pedido {{data.pedido}}. Aviso assim que o reembolso sair." },
+        // wait for an event, up to 7 days
+        { id: "espera", wait: { event: "reembolso_feito", upTo: "7d" }, else: "cobra" },
+        // a short wait rides as afterMs on the next message
+        { id: "pausa", wait: "5s" },
+        { id: "confere", collect: ["resolvido"] },
+        // if: code forks; the false branch clears and asks again
+        { id: "ok", if: { equals: { resolvido: true } }, then: "end", else: { step: "dados", clear: ["pedido", "resolvido"] } },
+        { id: "cobra", do: "abrir_chamado", with: { pedido: "{{data.pedido}}" }, then: "end" },
+        // onFail: say what broke, why, and what the lead can do now
+        { id: "sem-chamado", say: "Não consegui abrir o chamado: o sistema de chamados não respondeu. Peça um atendente e eu chamo alguém da equipe para abrir na mão.", then: "end" },
       ],
-    },
+    }),
   ],
 });
-```
-
-### Top-level `prepare` shorthand vs `hooks.prepare`
-
-```typescript
-// Shorthand — receives (context, data?), returns PrepareResult.
-{
-  id: 'enrich',
-  auto: true,
-  prepare: (context, data) => ({
-    dataUpdate: { customerTier: lookupTier(context, data?.email) },
-  }),
-}
 
-// Full hook — receives HookContext, returns Directive.
-{
-  id: 'enrich',
-  auto: true,
-  hooks: {
-    prepare: ({ context, data, dispatch }) => {
-      const tier = lookupTier(context, data?.email);
-      dispatch({ dataUpdate: { customerTier: tier } });
-      if (tier === 'blocked') {
-        return { halt: true, reply: 'This account is on hold.' };
-      }
-    },
-  },
-}
+const r = await agent.turn({ sessionId: "s1", message: "meu pedido veio errado" });
+console.log(r.outcomes.map((o) => `${o.stepId}: ${o.status}`), r.llmCalls); // [ 'dados: ok' ], 2: the step asked for the order id
 ```
 
-## Errors
-
-The `Step` constructor validates the options shape eagerly. The
-following are thrown synchronously when the agent is built:
-
-- `FlowConfigurationError` — `when` contains a function (functions
-  belong on `if`).
-- `FlowConfigurationError` — `auto: true` is combined with `prompt`,
-  `collect`, `tools`, or `finalize`.
-- `FlowConfigurationError` — `reply` is combined with `prompt`,
-  `collect`, `tools`, `finalize`, or `auto: true`.
-- `FlowConfigurationError` — `branches` is empty (`[]`).
-- `FlowConfigurationError` — a non-last `branches` entry has neither
-  `when` nor `if` (later entries would be unreachable).
-- `FlowConfigurationError` — a `branches[i].then` Directive sets more
-  than one position field (`goTo`, `goToStep`, `complete`, `abort`,
-  `reset`).
-- `FlowConfigurationError` — a `branches[i].then` Directive contains
-  an empty `goTo: {}`.
-- `FlowConfigurationError` — a tool-based `prepare`/`finalize` (tool id
-  or `Tool` object) is combined with `hooks.prepare`/`hooks.finalize`.
-  A step can only have one handler per position — remove one or inline
-  the tool call inside a function.
-
-Runtime errors that surface from a step's hook execution include
-`DataValidationError` (invalid collected data), `ToolExecutionError`
-(a tool inside the step threw or rejected), and
-`ResponseGenerationError` (LLM call failed after retries). See
-[Errors](./errors.md) for handling patterns.
-
-## Related
-
-- [Architecture](../concepts/architecture.md) — where Step fits among the six primitives
-- [Turn pipeline](../concepts/pipeline.md) — when each step phase fires inside a turn
-- [Flow](./flow.md) — the parent type that contains a step's `steps[]` entry
-- [Tool](./tool.md) — the shape consumed by `tools[]`
-- [Instruction](./instruction.md) — the shape consumed by `instructions[]`
-- [Branches](./branches.md) — the full `BranchEntry` / `BranchMap` contract
-- [Directive](./directive.md) — the post-LLM return type for `hooks.finalize`
-- [When and if](../guides/conditions.md) — picking between AI and code conditions
-- [Branching](../guides/branching.md) — adding source-local forks
-- [Flow control](../guides/flow-control.md) — redirecting from a hook
+## See also
+
+- [Branches](branches.md) for `branches[]` on talk and wait steps
+- [Flow](flow.md) for `onEnd` and `while`
+- [Outcomes](outcomes.md) for every code a step can emit
+- [Flow control](../guides/flow-control.md) and [Actions and events](../guides/actions-and-events.md)