@falai/agent 1.2.8 → 2.0.0

package/docs/concepts/pipeline.md

@@ -0,0 +1,399 @@
+---
+title: "Turn pipeline"
+description: "How a single call to agent.respond moves through directive resolution, routing, signals, hooks, the LLM, and persistence."
+type: concept
+order: 2
+---
+
+# Turn pipeline
+
+> **Where this is introduced:** [Architecture](./architecture.md)
+
+Every interaction with `@falai/agent` is a *turn* — one user message in,
+one assistant message out. Inside that boundary the framework runs a
+fixed sequence of phases: it consumes a pending directive, evaluates
+pre-signals in parallel with routing, picks the next step, runs hooks
+around an LLM call, applies the merged result, and persists. The order
+is the same on every turn. The shape of the turn is the framework. The
+LLM understands; the pipeline keeps the code in control.
+
+This page is the per-turn mental model: the diagram, the resolution
+precedence, the per-turn **directive bus**, and the merge rules used
+when more than one handler tries to write at once.
+
+## The pipeline diagram
+
+```mermaid
+graph TB
+    IN[respond / respondStream]
+    IN --> PEND{session.pendingDirective?}
+
+    PEND -- yes --> APPLY1[Apply pending directive]
+    APPLY1 --> STEP
+
+    PEND -- no --> PAR[Parallel]
+    PAR --> PRE[PRE-SIGNAL phase<br/>pre / both signals]
+    PAR --> ROUTER[AI routing<br/>FlowRouter]
+
+    PRE --> MERGE{Pre-signal directive?}
+    ROUTER --> MERGE
+    MERGE -- halt --> HALT[Skip LLM]
+    MERGE -- position --> APPLY2[Apply signal position]
+    MERGE -- augment only --> KEEP[Keep routing + apply augmentation]
+    MERGE -- none --> KEEP
+
+    APPLY2 --> STEP
+    KEEP --> STEP
+
+    STEP[Step resolution]
+    STEP --> AUTO[Auto-step chain]
+    AUTO --> BRANCH[step.branches]
+    BRANCH --> SUCC[Linear successor /<br/>AI step selection]
+
+    SUCC --> ENTER[onEnter / prepare hooks<br/>pre-LLM bus]
+    HALT --> POSTSIG
+    ENTER --> LLM[LLM call + tool loop]
+    LLM --> FIN[finalize hook<br/>post-LLM bus]
+    FIN --> COL[Collect + merge directives]
+
+    COL --> POSTSIG[POST-SIGNAL phase<br/>post / both signals]
+    POSTSIG --> PERSIST[Persist session]
+    PERSIST --> OUT[AgentResponse]
+```
+
+Three things to notice:
+
+- **`pendingDirective` shortcuts the top half.** When a previous turn
+  left a directive on the session, or `agent.dispatch()` was called
+  between turns, it is applied first and routing is skipped.
+- **Pre-signals run in parallel with routing.** Both calls are issued
+  via `Promise.all` so the common case (no halt, no signal redirect)
+  pays no extra latency. If a pre-signal halts or sets a position
+  field, the parallel routing result is discarded.
+- **Post-signals come after the LLM.** They cannot stop *this* turn —
+  they observe the assistant's reply, optionally extract structured
+  data, and at most arm `pendingDirective` for the next turn.
+
+The two signal phases are no-ops when `agent.signals` is empty or
+unset. See [Signals](../reference/signals.md) for the full surface.
+
+## Resolution precedence
+
+When more than one source could decide where the conversation goes
+next — a pending directive, a pre-signal, the AI router, an auto-step,
+a `step.branches` entry, the linear chain, the post-signal phase — the
+pipeline resolves them in a fixed, locked order. This order does not
+change between releases. Knowing it is enough to predict what every
+turn will do.
+
+1. **`session.pendingDirective` is consumed first.**
+   Set on the previous turn (e.g. by a post-signal, by a
+   `complete: { next }` chain, by a tool that emitted `goTo`) or by
+   `agent.dispatch()` from outside any turn. When present it is
+   applied verbatim and the rest of the top half is skipped. The
+   field is cleared as part of the apply step so it cannot fire
+   twice.
+
+2. **PRE-SIGNAL phase, in parallel with routing.**
+   Pre-phase signals (`phase: 'pre'` or `phase: 'both'`) run via the
+   same `Promise.all` that issues the routing classifier call. Their
+   directives merge through the per-turn bus (see below). If the
+   merged pre-phase directive sets `halt: true`, the LLM is skipped
+   for this turn. If it carries a position field (`goTo`,
+   `goToStep`, `complete`, `abort`, `reset`), that position wins and
+   the routing result is discarded. If it only carries augmentation
+   (`appendPrompt`, `injectTools`) or state writes (`dataUpdate`,
+   `contextUpdate`), routing is kept and the augmentation is layered
+   on top.
+
+3. **AI routing.**
+   `FlowRouter.decide` picks the active flow and entry step based on
+   the user message, conversation history, and each flow's `when`
+   condition. Used only when steps 1 and 2 produced no position
+   field. Routing is the framework's *intent classifier*: it answers
+   "what is the user trying to do right now?" and nothing else. It
+   never writes data and never speaks.
+
+4. **Auto-step chain.**
+   With a current flow and step in hand, the pipeline walks the
+   `auto: true` chain — each auto-step's `onEnter` and `prepare`
+   hooks fire, branches resolve, and the chain advances without an
+   LLM call until it reaches a non-auto step, a `halt`, a `reply`,
+   a `complete`, or the per-turn cap (`maxAutoStepsPerTurn`). Auto
+   steps are how the code half of the contract advances state in
+   bulk between user messages.
+
+5. **Step branches.**
+   When the resolved step has `branches`, they evaluate in
+   declaration order. The `if` predicate runs first (free, code-only
+   evaluation). If it passes, the optional `when` string is sent to
+   the AI as a yes/no classifier. The first entry whose conditions
+   all match wins; its `then` is applied — a step id (jump within
+   the flow), a flow id (cross-flow jump), or a full `Directive`.
+   Code-only branches incur zero token cost.
+
+6. **Linear successor / AI step selection.**
+   When no branch matched, the pipeline falls through to the linear
+   chain. If exactly one candidate successor passes its `skip`
+   condition, that step is entered. If several pass, the framework
+   asks the AI to pick (the same routing primitive, scoped to the
+   surviving candidates). If none pass, the flow is implicitly
+   complete (the *last step terminates the flow* rule from v2 — no
+   sentinel value, no special return type).
+
+7. **POST-SIGNAL phase.**
+   After `finalize` and the post-LLM bus merge, post-phase signals
+   evaluate sequentially against the just-completed turn. They see
+   the assistant's reply, the collected data, and any tool results.
+   Post-phase position directives (`goTo`, `goToStep`, `complete`)
+   set `session.pendingDirective` for the *next* turn — there is no
+   mid-turn re-entry, by design, to keep turn semantics legible.
+   Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are
+   dropped with a debug warning if a post-phase signal emits them.
+
+This is the precedence the rest of the framework is built around. The
+[Resolution precedence section](../reference/signals.md#resolution-precedence-within-a-turn)
+on the signals reference page restates the same list as a contract;
+this concept page is the prose explanation.
+
+## The directive bus
+
+Hooks, tools, and signal handlers all express their intent the same
+way: by emitting a [`Directive`](../reference/directive.md). The
+pipeline collects these emissions into a per-turn, in-memory **bus**
+and reduces them to a single applied directive at the end of each
+phase. Two phases, one merge function.
+
+### Pre-LLM phase
+
+Sources, in fixed order:
+
+1. `agent.hooks.onEnter` (if the agent supports hooks at this level)
+2. `flow.hooks.onEnter` for the active flow
+3. `step.hooks.onEnter` for the resolved step
+4. `step.hooks.prepare`
+5. Any `ctx.dispatch` calls made inside the above hooks
+
+These return `PreDirective` — the same shape as `Directive` plus the
+three pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`). The
+merged result feeds the prompt composer and tool manager before the
+LLM call:
+
+- `halt: true` skips the LLM entirely (a `reply`, if any, becomes the
+  literal assistant message).
+- `appendPrompt[]` is concatenated into the system prompt for this
+  turn only.
+- `injectTools[]` is added to the available tool list for this turn
+  only.
+- Position fields, state writes, and `reply` carry forward exactly
+  as they would from any directive.
+
+### Post-LLM phase
+
+Sources, in fixed order:
+
+1. Each `ToolResult.directive` returned during the tool loop
+2. Any `ctx.dispatch` calls inside tool handlers
+3. `step.hooks.finalize`
+4. `flow.hooks.onComplete` (when the flow finished this turn)
+5. The `then` branch of any matched `step.branches` entry whose `then`
+   was a full `Directive` (not just a step id)
+
+These return plain `Directive`. PreDirective-only fields here are
+dropped with a debug warning — `halt` after the fact has no meaning,
+and `appendPrompt` / `injectTools` could not influence a call that
+has already happened.
+
+### Why a bus
+
+Two reasons. First, multiple emitters are normal: a `prepare` hook
+might add a sentence to the prompt while a tool result writes
+collected data while a `finalize` hook completes the flow. The bus
+makes "who wrote what" explicit and the merge rules deterministic.
+Second, observability: `AgentResponse.directiveChain` returns the full
+list of emitted directives in order with their sources, so traces
+explain themselves without bisecting hook code.
+
+The bus is purely in-memory and lasts one turn. Nothing about the bus
+itself is persisted; only the *applied* directive's effects (state
+writes, position changes, `pendingDirective` for the next turn) cross
+the persistence boundary.
+
+## Algorithm 4 — merge rules
+
+When the bus has more than one directive in a phase, the pipeline
+folds them into a single `Directive` (or `PreDirective` in the pre-LLM
+phase) using the following rules. Same rules in both phases; the
+pre-LLM phase additionally folds the three augmentation fields.
+
+### Position fields — winner-takes-all by precedence
+
+Exactly one position field can apply per phase. The winner is chosen
+by the precedence:
+
+```
+abort > complete > goTo / goToStep > reset
+```
+
+- **`abort` always wins.** A handler that aborts the conversation
+  cannot be overridden by a later "go somewhere else" — there is no
+  somewhere else.
+- **`complete` beats `goTo` / `goToStep`.** The flow is ending; any
+  follow-up jump belongs in `complete.next`, not as a competing
+  position field.
+- **`goTo` and `goToStep` share a tier.** `goTo` is the cross-flow
+  hop; `goToStep` is the within-flow hop. Both express "next position
+  is here." Among same-tier emissions, last-wins.
+- **`reset` is lowest.** Any explicit jump out of the current flow
+  beats a "restart this flow" emitted earlier in the phase.
+
+Within the same precedence tier, **last emission wins**. The pipeline
+logs a debug-level warning naming all conflicting sources so a noisy
+turn is diagnosable.
+
+### `reply` — last-wins
+
+`reply` is a verbatim assistant utterance — the LLM is bypassed for
+the message body. If two emitters set `reply`, the second wins. The
+pipeline logs a debug warning so the override is visible.
+
+`reply` and `abort` are mutually exclusive at apply time: an aborted
+conversation cannot deliver a reply, and the pipeline rejects the
+combination as a `FlowConfigurationError`.
+
+### `dataUpdate` and `contextUpdate` — shallow-merge in emit order
+
+State writes are *additive*: every emitter contributes its slice and
+the merger shallow-merges them in declaration order, last write wins
+on key collision. The `Object.assign({}, a, b)` semantics — top-level
+keys overwrite, nested objects are not deep-merged.
+
+This is the rule that lets a flow-level `onEnter` set a default while
+a step-level `prepare` overrides one field on top, without the two
+hooks needing to know about each other.
+
+After merging, the combined `dataUpdate` is validated against
+`agent.schema` *atomically* — every field across every emitter is
+checked together, and the session is not mutated unless the whole set
+passes. A failure throws `DataValidationError` with the offending
+field and emitter listed.
+
+### `appendPrompt` and `injectTools` — concatenate, then dedupe
+
+Pre-LLM only. Both fields are arrays; the merger concatenates them in
+emit order and then deduplicates:
+
+- **`appendPrompt`** is concatenated and rendered into the prompt's
+  per-turn appendage slot. No deduplication — duplicates from
+  different sources are preserved (a flow-level "be polite" plus a
+  step-level "be polite" is acceptable redundancy).
+- **`injectTools`** is concatenated and deduped by `Tool.id`. When
+  two emitters inject a tool with the same id, the *later* definition
+  wins — typically a step-level injection overriding a flow-level
+  default.
+
+Both arrays apply only for this turn; they are stripped before
+`session.pendingDirective` is written, and they cannot be persisted.
+
+### `halt` — logical-OR
+
+Pre-LLM only. If *any* pre-phase emitter set `halt: true`, the merged
+directive halts. There is no "vote" — a single emitter is enough. The
+LLM is not called; if a `reply` is also set, that becomes the literal
+assistant message; otherwise the turn ends with an empty body and
+`stoppedReason: 'halt'`.
+
+`halt` is the framework's circuit breaker: a hook that detects an
+unresolvable state can stop the turn outright without competing with
+other emitters.
+
+## One turn end-to-end
+
+The same shape, traced as a sequence. Lanes are *User*, *Agent*
+(`agent.respond`), *Pipeline* (the internal turn pipeline),
+*Provider* (the AI), and *Adapter* (the persistence layer).
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Agent
+    participant Pipeline
+    participant Provider
+    participant Adapter
+
+    User->>Agent: respond("I want to book a hotel")
+    Agent->>Adapter: load session
+    Adapter-->>Agent: SessionState (with pendingDirective?)
+
+    alt session.pendingDirective is set
+        Agent->>Pipeline: applyDirective(pendingDirective)
+        Pipeline->>Pipeline: clear pendingDirective
+    else
+        par Parallel
+            Agent->>Pipeline: runPreSignalPhase()
+            Pipeline->>Provider: classifier call (batched signals)
+            Provider-->>Pipeline: matched + extracted
+        and
+            Agent->>Pipeline: FlowRouter.decide()
+            Pipeline->>Provider: routing call
+            Provider-->>Pipeline: { flow, step }
+        end
+        Pipeline->>Pipeline: merge pre-signal bus<br/>halt? position? augment? none?
+    end
+
+    Pipeline->>Pipeline: walk auto-step chain
+    Pipeline->>Pipeline: evaluate step.branches
+    Pipeline->>Pipeline: select successor / linear chain
+
+    Pipeline->>Pipeline: onEnter + prepare hooks<br/>(pre-LLM bus)
+    Pipeline->>Provider: generate(prompt + tools + history)
+
+    loop tool loop
+        Provider-->>Pipeline: tool call
+        Pipeline->>Pipeline: ToolManager.execute<br/>(may emit Directive)
+        Pipeline->>Provider: tool result
+    end
+
+    Provider-->>Pipeline: assistant message
+    Pipeline->>Pipeline: finalize hook<br/>(post-LLM bus)
+    Pipeline->>Pipeline: collect + merge directives<br/>(Algorithm 4)
+    Pipeline->>Pipeline: applyDirective(merged)
+
+    Pipeline->>Pipeline: runPostSignalPhase()
+    Pipeline->>Provider: extraction call (if signals declared)
+    Provider-->>Pipeline: matched + extracted
+    Pipeline->>Pipeline: post-phase position?<br/>arm pendingDirective for next turn
+
+    Pipeline->>Adapter: persist session
+    Pipeline-->>Agent: AgentResponse
+    Agent-->>User: assistant message
+```
+
+A few things this diagram makes precise that the high-level graph
+elides:
+
+- The session is loaded *before* the pending-directive check, because
+  `pendingDirective` lives on the session itself.
+- The pre-signal classifier call and the routing call are issued in
+  parallel; the merge step decides whether the routing result is used
+  or discarded.
+- The tool loop is internal to the LLM phase. Tools that emit
+  directives feed the *post-LLM* bus, not the pre-LLM one — they ran
+  during a call, not before it.
+- The post-signal phase happens *after* directive apply, before
+  persistence. That's the only window in which post-phase handlers
+  can see the fully-applied turn state.
+- Persistence is the last write. Anything that did not survive the
+  applied directive (the bus contents, the pre-LLM augmentation
+  arrays, `halt`) is gone by the time the adapter is called.
+
+## Where to go next
+
+The pipeline is the *what happens*. The directive is the *how
+handlers ask for things to happen*. The next concept page covers the
+flat shape, the position field rules, the inheritance chain
+`Directive → PreDirective → SignalDirective`, and the `flow`
+namespace helpers (`flow.isDirective`, `flow.merge`, `flow.validate`)
+that make the bus introspectable from user code.
+
+**Next:** [Directives](./directives.md)

package/docs/guides/branching.md

@@ -0,0 +1,263 @@
+---
+title: "Branching"
+description: "Add an explicit, source-local fork to a step with `branches`, mixing code predicates and AI conditions and pointing at step ids, flow ids, or full directives."
+type: guide
+order: 2
+---
+
+# Branching
+
+Most flows are linear: ask, collect, confirm, complete. A few aren't. Sometimes the conversation arrives at a step that has to choose between three or four next moves — and the choice is the point of the step, not an aside. This guide shows how to express that fork with `step.branches`.
+
+You already know the [`when` / `if` split](./conditions.md): `when` is an AI-evaluated string, `if` is a code predicate, and the two compose so that code runs first for free and the AI only fires when the predicate already passed. `branches` reuses that vocabulary in a list-shaped form. Each entry says "here is a possible next step, and here is how to choose it." Entries evaluate top-to-bottom; the first one whose conditions pass wins.
+
+By the end of this page you will have written four branch points: a pure-code fork that costs zero tokens, an AI-only fork that classifies intent, a combined fork that short-circuits the LLM call, and a cross-flow fork that hands control to a different flow with state carry.
+
+## The shape
+
+`step.branches` is an array of `BranchEntry` objects. Each entry has up to four fields:
+
+```typescript
+interface BranchEntry<TContext, TData> {
+  /** AI-evaluated condition. String or array of strings (AND). */
+  when?: string | string[];
+
+  /** Code predicate. Function or array of functions (AND). */
+  if?: BranchPredicate<TContext, TData> | BranchPredicate<TContext, TData>[];
+
+  /**
+   * Where to go when this entry matches. One of:
+   *  - A string matching a step id in the current flow.
+   *  - A string matching a flow id (sugar for `{ goTo: <flowId> }`).
+   *  - A full Directive (cross-flow step targets, state writes, completion).
+   */
+  then: string | Directive<TContext, TData>;
+
+  /** Optional label surfaced in event traces and flow visualization. */
+  label?: string;
+}
+```
+
+Three rules govern how a `branches` array is read:
+
+1. **Declaration order is evaluation order.** The first entry whose conditions pass wins. Later entries don't run.
+2. **Code-first short-circuit.** When an entry has both `if` and `when`, `if` runs first. `when` is only evaluated when `if` passes — saving the LLM call when the predicate already disqualifies the entry.
+3. **An entry with neither `when` nor `if` is an unconditional fallback.** It's only legal as the last entry in the array. Putting it earlier is a `FlowConfigurationError` because every later entry would be unreachable.
+
+If no entry matches, branches return `undefined` and resolution falls through to the linear `nextStep` chain or AI step selection — exactly as if `branches` were absent. That is the same fall-through that backs the implicit-fork pattern, so the two forms compose cleanly.
+
+## A code-only fork
+
+The cheapest fork is one that doesn't call the LLM at all. When the choice is purely a function of `data` and `context`, every entry uses `if` and the whole decision runs in pure TypeScript.
+
+```typescript
+flow({
+  id: "plan_routing",
+  steps: [
+    {
+      id: "route_by_plan",
+      auto: true,
+      branches: [
+        { if: ({ data }) => data.plan === "enterprise", then: "enterprise_path", label: "enterprise" },
+        { if: ({ data }) => data.plan === "pro",        then: "pro_path",        label: "pro" },
+        { then: "free_path" }, // unconditional fallback (last entry)
+      ],
+    },
+    { id: "enterprise_path", prompt: "A specialist will reach out." },
+    { id: "pro_path",        prompt: "Set up your pro account." },
+    { id: "free_path",       prompt: "Welcome to the free tier." },
+  ],
+});
+```
+
+Two things matter here. First, `auto: true` on the source step removes the LLM call that would otherwise run for `route_by_plan` itself — the step asks no question, only routes. Combined with code-only branches, the entire decision is a pure compute node in the graph. Second, the unconditional fallback at the end is what guarantees a target. Without it, a `data.plan` value the engine doesn't know about would fall through to linear succession instead of landing on `free_path`.
+
+The `BranchPredicate` receives `{ data, context, session, history }`. `data` is `Partial<TData>` — predicates have to null-check any field not declared in the source step's `requires`. Fields covered by `requires` are guaranteed present.
+
+## An AI-only fork
+
+Some forks need intent classification. The user said something; the agent has to decide whether they want to cancel, ask about billing, or get technical help. None of that lives in `data` yet, and writing a regex would lose the point of the framework.
+
+```typescript
+flow({
+  id: "support",
+  steps: [
+    {
+      id: "classify_request",
+      prompt: "How can I help?",
+      branches: [
+        { when: "user wants to cancel their account", then: "cancel_flow" },
+        { when: "user is asking about billing",        then: "billing_flow" },
+        { when: "user is asking a technical question", then: "tech_support" },
+        { then: "general_help" }, // fallback
+      ],
+    },
+    { id: "tech_support", prompt: "What are you running into?" },
+    { id: "general_help", prompt: "I can help with that." },
+    // cancel_flow and billing_flow are top-level flows resolved via goTo.
+  ],
+});
+```
+
+`when` strings reuse the same machinery as `step.when`. One LLM call evaluates each entry's condition in declaration order; the first match wins. Conditions are written from the agent's perspective — `"user wants to cancel"` reads naturally and matches the prompts the model already speaks. Don't try to compress them into keywords; the AI is doing classification, not pattern matching.
+
+The fallback at the end is doing real work too. When the model can't classify the message into any of the three buckets — say the user typed "hi" — `general_help` catches it instead of dropping the user into AI step selection.
+
+## Combining `if` and `when`
+
+When an entry has both fields set, code runs first and the AI call only fires when the predicate already passed. This is the same short-circuit you saw in the [conditions guide](./conditions.md), now scoped to a single branch entry.
+
+```typescript
+flow({
+  id: "pricing",
+  steps: [
+    {
+      id: "pricing_routing",
+      branches: [
+        {
+          // Free predicate runs first; AI condition only fires when it passes.
+          if: ({ data, context }) =>
+            data.country === "US" && context.featureFlags.enableUsPricing,
+          when: "user is asking about pricing",
+          then: "us_pricing",
+        },
+        {
+          when: "user is asking about pricing",
+          then: "global_pricing",
+        },
+        { then: "general_help" }, // fallback
+      ],
+    },
+    { id: "us_pricing",     prompt: "Here is US pricing." },
+    { id: "global_pricing", prompt: "Here is global pricing." },
+    { id: "general_help",   prompt: "I can help with that." },
+  ],
+});
+```
+
+For users outside the US — or with the feature flag off — `if` returns `false` immediately and the entry is skipped without ever evaluating `when`. The second entry then evaluates `when` once and routes to `global_pricing`. A US user with the flag on passes `if`, and only then does the AI call evaluate "user is asking about pricing." When both pass, the entry wins.
+
+The cost difference is real. Without the short-circuit, every turn would pay one LLM call to evaluate `when` for every entry that names it. With it, the framework spends tokens on the entries it can't dispose of for free.
+
+## Resolving `then`
+
+`then` accepts three forms, resolved in this order:
+
+1. **A step id in the current flow** — the engine enters that step directly. Same effect as `nextStep: <id>` would have on a linear chain.
+2. **A flow id** — sugar for `applyDirective({ goTo: <flowId> })`. The string is desugared into a flow transition with no data carry.
+3. **A `Directive` object** — applied via `applyDirective` directly. This is the form to use whenever you need anything more than a bare jump: cross-flow steps, data writes, completion, or verbatim replies.
+
+When a string matches both a local step id and a flow id (rare; you'd have to name them the same thing), the local step wins. Step ids are scoped to the current flow, so the lookup is unambiguous.
+
+A bare string **never** resolves to a step in a different flow, even when that step id is globally unique. Cross-flow step targets require the `Directive` form:
+
+```typescript
+{
+  if: ({ data }) => data.escalate === true,
+  then: { goToStep: { step: "priority_intake", flow: "Escalation" } },
+}
+```
+
+This is intentional. Keeping the string-form lookup confined to "current flow's steps or any flow id" means a glance at the source tells you what the string means without needing to know whether some unrelated flow happens to define a step by the same name. When you mean to cross flows, the `Directive` form makes that explicit at the call site.
+
+## A mixed-target router
+
+Most real branch points combine forms. One entry tests data, another classifies intent, a third writes state and completes. The `branches` array reads top-to-bottom as a list of cases:
+
+```typescript
+flow({
+  id: "router",
+  steps: [
+    {
+      id: "classify",
+      prompt: "How can I help?",
+      branches: [
+        // Step id in the current flow.
+        { if: ({ data }) => data.tier === "enterprise", then: "enterprise_path" },
+
+        // Flow id — sugar for { goTo: "CancellationFlow" }.
+        { when: "user wants to cancel", then: "CancellationFlow" },
+
+        // Full Directive — cross-flow with data carry.
+        {
+          when: "user is asking about a refund",
+          then: { goTo: { flow: "Refund", data: { source: "classify" } } },
+        },
+
+        // Cross-flow step reference (Directive required).
+        {
+          if: ({ data }) => data.escalate === true,
+          then: { goToStep: { step: "priority_intake", flow: "Escalation" } },
+        },
+
+        // Directive with completion + state write.
+        {
+          if: ({ data }) => data.shouldComplete === true,
+          then: { complete: true, dataUpdate: { closedAt: new Date().toISOString() } },
+        },
+
+        // Unconditional fallback.
+        { then: "default_path" },
+      ],
+    },
+    { id: "enterprise_path", prompt: "..." },
+    { id: "default_path",    prompt: "..." },
+  ],
+});
+```
+
+The mix is the point. Code-only entries pay nothing, AI entries pay one classification, the Directive entries reach across flows or write completion state. Everything declarative is in one list at the source step. There is no separate router file, no decision tree spread across `step.when` clauses on five different successors.
+
+## Coexisting with the implicit fork
+
+Branches don't replace the implicit-fork pattern (multiple successor steps each carrying their own `step.when`). Both forms stay first-class. Choose by intent:
+
+- **Implicit fork** when the flow reads as a linear chain that occasionally skips. The fork is incidental — the bulk of the flow is "do A, then B, then maybe C, then D."
+- **Explicit fork (`branches`)** when the source step is a routing point. The fork is the point — the step exists to choose between N targets and the targets are owned by the source.
+
+When both are present on the same step, branches take precedence. If a branch entry matches, the linear chain is bypassed entirely. If `branches` returns `undefined` — no entry matched — the linear chain runs as if `branches` were absent.
+
+```typescript
+flow({
+  id: "support",
+  steps: [
+    {
+      id: "intake",
+      prompt: "How can I help?",
+      // Branches handle the obvious cases up-front.
+      branches: [
+        { if: ({ data }) => data.priority === "P0", then: "fast_path" },
+        { when: "user is asking a billing question", then: "billing" },
+      ],
+    },
+    // Linear successors with their own `when` — the implicit-fork pattern.
+    // These only run if no branch entry matched on `intake`.
+    { id: "tech",      when: "user is asking a technical question", prompt: "..." },
+    { id: "general",   prompt: "I can help with that." },
+    // ...
+    { id: "fast_path", prompt: "..." },
+    { id: "billing",   prompt: "..." },
+  ],
+});
+```
+
+The combination here is deliberate. Branches catch the cases that have an explicit short-circuit (P0 priority is in `data`, billing is unambiguous to classify). Everything else falls through to the implicit fork, which the AI step selector picks among. Neither pattern is forced into doing what the other does better.
+
+## What you get back
+
+When a branch entry's `then` is applied, the response surfaces it the same way it would surface any other position decision. The active step changes, `currentStep.id` reflects the new step, and `appliedInstructions` is recomputed for the new scope. If the entry's `then` was a `Directive` that included `dataUpdate` or `contextUpdate`, those writes are visible on the response too — branches participate in state writes through the same `applyDirective` machinery as tools and hooks.
+
+The optional `label` field on each entry doesn't affect resolution; it's surfaced in event traces and in flow visualization tools so you can see which branch fired without having to read the predicate. Use it on entries whose `if`/`when` conditions are long enough to be hard to skim at a glance.
+
+## Recap
+
+Four moves cover almost every fork you'll write:
+
+- **Code-only** when the choice is in `data` or `context`. Free, deterministic, and combinable with `auto: true` for zero-LLM routing nodes.
+- **AI-only** when the choice is intent classification. One LLM call, declared at the source step instead of scattered across target-step `when` clauses.
+- **Combined `if + when`** when both must agree. Code runs first, AI runs only when code passed.
+- **Directive in `then`** when the target is in another flow, when state needs to be written, or when the branch should complete or abort the flow.
+
+`branches` doesn't add a new control-flow primitive. It reuses `when`, `if`, and `Directive` in a list shape that makes the fork visible at the source step. Pair it with the implicit-fork pattern when the linear chain is the natural read; pair it with `auto: true` when the routing decision shouldn't speak.
+
+**Next:** [Flow control](./flow-control.md)