@falai/agent 3.4.5 → 4.0.0-alpha.1

package/docs/concepts/directives.md

@@ -1,369 +0,0 @@
----
-title: "Directives"
-description: "The flat object shape any tool, hook, or branch returns to write state, redirect the conversation, or speak verbatim."
-type: concept
-order: 3
----
-
-# Directives
-
-> **Where this is introduced:** [Turn pipeline](./pipeline.md)
-
-A directive is the single language `@falai/agent` speaks for control
-flow. When a tool decides "this user is ineligible," it returns
-`{ goTo: "Denial", reply: "Sorry — you don't qualify." }`. When a
-finalize hook closes a booking, it returns
-`{ complete: true, dataUpdate: { bookingId } }`. When a pre-phase
-signal detects a frustrated user, it dispatches
-`{ appendPrompt: ["Lead with empathy."] }`. Different jobs, different
-emitters, one shape.
-
-This page explains why the shape is flat, what each field does, how
-they merge when more than one handler emits during the same turn, and
-how `Directive` and `SignalDirective` relate. The page is conceptual —
-the [directive reference](../reference/directive.md) carries the
-field-by-field contract.
-
-## Why a flat shape
-
-An earlier draft of v2 modeled directives as a discriminated union:
-`{ type: 'goto_flow', flow: 'X' }`, `{ type: 'complete', next: ... }`,
-`{ type: 'abort', reason: ... }`, and so on. The shape that ships is
-flat — a single interface with optional fields, no `type`
-discriminator, no builder, no factory functions. Four reasons drove
-the decision, and each one is visible at the call site once you know
-to look for it.
-
-**Single shape.** Every emitter returns the same object literal. A
-finalize hook does not have to choose between `Directive.goto({...})`
-and `Directive.complete({...})` and `Directive.reply({...})` — it
-returns `{}` with whichever fields it needs. Authors learn one shape
-and reach for it from tools, from prepare hooks, from finalize hooks,
-from signal handlers, from branch `then` targets. The framework's
-control-flow vocabulary is one type wide. The same object literal is
-also persistable as `session.pendingDirective`, so the shape
-that sits in source code is the same shape that crosses the
-persistence boundary.
-
-**Trivially mergeable.** Algorithm 4 — the per-turn merge that the
-pipeline runs over the directive bus — works on a flat object: pick
-the winning position field by precedence, last-wins for `reply`,
-shallow-merge state writes, concatenate the pre-LLM arrays. A nested
-discriminated union would force a per-variant merge case at every
-combinator: how do you merge a `goto_flow` with a `complete`? With a
-`reply`? With a `dataUpdate`? Every cross-variant combination becomes
-its own special case. With a flat object, "merge" is one function
-that does not branch on shape.
-
-**Validates statically.** TypeScript narrowing on field presence is
-clean. `if (d.goTo) { /* d.goTo is string | object */ }` is the
-entire pattern. A discriminated union adds one extra branching level
-at every call site — `if (d.type === 'goto_flow') { /* d is the
-goto_flow variant */ }` — and the variant types repeat the same
-optional-fields prose for state writes and `reply`. The flat shape
-moves "is this a position directive or a state directive or a reply"
-from a type-level question to a runtime question that the merge
-algorithm answers once.
-
-**Composable.** A directive carries up to four orthogonal payloads
-without forcing them into a hierarchy: at most one position field,
-optional state writes (`dataUpdate` / `contextUpdate`), an optional
-verbatim `reply`, and optional pre-LLM augmentations (`appendPrompt`,
-`injectTools`, `halt`). `dataUpdate` works alongside `goTo`. `reply`
-works alongside `complete`. A booking tool's success result writes the
-booking id and finishes the flow in one return value:
-`{ complete: true, dataUpdate: { bookingId } }`. A bridge utterance
-at a flow boundary writes nothing and only speaks: `{ reply: "Let me
-transfer you." }`. The same primitive covers both because the fields
-do not exclude each other by shape — only by validation.
-
-The trade-off is that exhaustive `case` checking on a `type`
-discriminator is gone. The pipeline replaces it with structural
-validation (`flow.validate`) — one position field at most, no empty
-`goTo: {}`, no `reply` alongside `abort` — that runs at apply time
-anyway, since flow and step lookups are runtime checks regardless. The
-exchange is one less compile-time check for a far cleaner authoring
-surface and a merge algorithm that does not branch on shape.
-
-## Position fields and their precedence
-
-A directive carries at most one **position field**. Position fields
-answer the question "where does the conversation go next?" The five
-options span every form of position control the framework offers:
-
-| Field | What it means |
-|-------|---------------|
-| `goTo` | Jump to another flow. |
-| `goToStep` | Jump to a step (within the current flow, or — in the object form — within another flow). |
-| `complete` | Mark the current flow done. The flow's completion logic runs. |
-| `abort` | End the conversation. Optionally clear the session. |
-| `reset` | Restart the current flow. Optionally clear its declared fields. |
-
-Each of `goTo`, `goToStep`, `complete`, `abort`, and `reset` accepts
-both a shorthand and an object form. The shorthand expresses the
-common case (`goTo: "Booking"`, `complete: true`, `abort: "denied"`).
-The object form exposes the optional knobs — `reason` strings for
-observability, `data` for pre-entry state writes, `clearSession` /
-`clearData` flags for the destructive variants. The fields are
-mutually exclusive: setting two at once throws
-`FlowConfigurationError` at validation. There is no "go to *and*
-abort" — only one position can win per directive.
-
-When more than one emitter writes a position field during the same
-turn — a tool returns `goTo` and a finalize hook returns `complete` —
-the merge algorithm picks one winner by precedence:
-
-```
-abort > complete > goTo / goToStep > reset
-```
-
-The order encodes intent. **`abort` always wins.** A handler that
-ended the conversation cannot be overridden by a later "go somewhere
-else" — there is no somewhere else. **`complete` beats `goTo` and
-`goToStep`.** The flow is ending; any follow-up jump belongs in
-`complete.next` (which chains another directive after completion),
-not as a competing position field. **`goTo` and `goToStep` share a
-tier.** Both express "next position is here" — the difference is
-flow-level vs step-level granularity, and within the tier last
-emission 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 tier, the most recent emission wins, with a debug
-log naming all losers so a noisy turn is diagnosable from the trace.
-The precedence ordering does not change between phases: it applies to
-the pre-LLM bus, the post-LLM bus, and the signal phases identically.
-
-## State writes
-
-Two fields — `dataUpdate` and `contextUpdate` — write to session
-state. Both are `Partial<>` slices of their respective surfaces:
-`dataUpdate?: Partial<TData>` writes into `session.data`,
-`contextUpdate?: Partial<TContext>` writes into `session.context`.
-Both fire their respective hooks (`flow.hooks.onDataUpdate`,
-`flow.hooks.onContextUpdate`) after the merge applies, and both run
-through schema validation atomically — every field across every
-emitter on this turn is checked together, and the session is not
-mutated unless the whole set passes.
-
-State writes are **additive** and shallow-merged across emitters in
-emission order. If a flow-level `onEnter` writes
-`{ dataUpdate: { tier: "vip" } }` and a step-level `prepare` writes
-`{ dataUpdate: { lastSeen: now } }`, the merged result is
-`{ tier: "vip", lastSeen: now }` — neither hook needs to know about
-the other. On key collision, last write wins. The merge is shallow —
-top-level keys are replaced wholesale, nested objects are not
-deep-merged. To update a nested object, read it from `data`, merge
-in code, write back the full sub-object. Deep merge is intentionally
-absent because it would silently disagree with TypeScript's
-`Partial<>` shape: the type says "I'm overwriting this key," and the
-runtime should agree.
-
-State writes always apply, regardless of what the position fields do.
-A directive with `{ goTo: "Denial", dataUpdate: { reason: "expired" }
-}` jumps flows *and* writes the reason. A directive with only
-`{ dataUpdate: {...} }` writes state and stays where it is. Position
-fields and state writes are orthogonal payloads; they don't compete
-for the same slot.
-
-## Reply as a verbatim utterance
-
-The `reply: string` field is the framework's way of letting code
-speak. When a directive sets `reply`, the LLM call for the entered
-step is skipped this turn and the literal string becomes the
-assistant's message. The text is taken verbatim — no templating, no
-post-processing, no "the model rephrased it" surprise.
-
-`reply` is the right tool for utterances that should be exact:
-confirmations ("Booking confirmed."), bridges ("Connecting you with a
-specialist now."), refusals ("Sorry — you don't qualify."), and
-boilerplate at flow boundaries. It is the wrong tool for anything
-that should adapt to context — that's what the model is for. The two
-shapes coexist on the same step boundary: `reply` for the line, the
-LLM for the conversation.
-
-`reply` co-validates with two other fields. With **`abort`**, it is
-rejected at validation — an aborted conversation cannot deliver a
-reply. With **`halt: true`**, it is the assistant message and the
-turn ends with `stoppedReason: 'reply'`; if `halt` is set without
-`reply`, the turn ends with `stoppedReason: 'halt'` and an empty
-body. Across multiple emitters in the same turn, `reply` is
-**last-wins** — the most recent emission overrides earlier ones,
-with a debug log so the override is visible in the trace.
-
-`reply` works the same regardless of which phase emits it. The phase
-determines whether the reply replaces a message that would have been
-generated (pre-LLM) or replaces one that just was (post-LLM).
-
-## Pre-LLM-only fields
-
-Three fields on `Directive` only take effect in pre-LLM hooks
-(`onEnter`, `prepare`). When emitted from post-LLM hooks (`finalize`,
-`onComplete`) or persisted to `session.pendingDirective`, they are
-**ignored with a WARN log** — a visible signal in your logs that
-says "hey, this did nothing here."
-
-**`appendPrompt: string[]`** is the prompt nudge slot. Each string is
-a sentence the prompt composer appends to the system prompt for this
-turn only. A flow-level `onEnter` that detects a VIP caller can add
-"This caller is a VIP — confirm preferences before suggesting
-options." A step-level `prepare` that detects a returning customer
-can add "The user is a returning customer; skip introductions." Both
-fire on the same turn, and both sentences land in the prompt's
-per-turn appendage slot in emission order. The slot is never cached
-(the prompt section cache memoizes static sections only) and never
-persisted — `appendPrompt` lives for one turn and is gone.
-
-**`injectTools: Tool[]`** is the per-turn tool slot. Tools listed
-here are added to the available tool list for this turn only,
-stacked on top of the agent → flow → step → transient resolution
-chain. A `prepare` hook that detects an ambiguous request can inject
-a `lookup_account` tool for a single LLM call without registering it
-on the step or the flow. The slot is never persisted — tool
-references are functions, and functions are not JSON-serializable —
-so the field is structurally one-turn-only.
-
-**`halt: boolean`** is the kill switch. When any pre-phase emitter
-sets `halt: true`, the LLM call is skipped entirely. If `reply` is
-also set, the verbatim string becomes the assistant message. If not,
-the turn ends with `stoppedReason: 'halt'` and an empty body. `halt`
-merges by **logical-OR** — a single emitter setting it is enough to
-halt the turn. The field is the framework's circuit breaker: a hook
-that detects an unresolvable state can stop the turn outright
-without competing with other emitters.
-
-These fields are stripped from `session.pendingDirective` before
-persistence — they cannot survive across turns by design. If a
-post-LLM hook returns a directive with these fields set, they are
-dropped with a WARN log: an `appendPrompt` after the fact has no
-prompt to append to, an `injectTools` after the fact has no LLM call
-to inject into, and a `halt` after the fact has no LLM call to halt.
-The remaining fields are honored normally.
-
-`appendPrompt` is concatenated across emitters in emission order
-without deduplication — duplicate sentences from different sources
-are preserved (a flow-level "be polite" plus a step-level "be polite"
-is acceptable redundancy). `injectTools` is concatenated and then
-deduped by `Tool.id`, with the later definition winning — typically a
-step-level injection overriding a flow-level default. `halt` is
-logical-OR. The merge rules for the base fields stay identical:
-position fields by precedence, `reply` last-wins, state writes
-shallow-merged.
-
-## SignalDirective
-
-`SignalDirective` extends `Directive` with two signal-pipeline-specific
-fields: `stopOtherSignals` and `replyWith`.
-
-```mermaid
-classDiagram
-    Directive <|-- SignalDirective
-
-    class Directive {
-        +goTo? string | object
-        +goToStep? string | object
-        +complete? true | object
-        +abort? string | object
-        +reset? true | object
-        +reply? string
-        +dataUpdate? Partial~TData~
-        +contextUpdate? Partial~TContext~
-        +appendPrompt? string[]
-        +injectTools? Tool[]
-        +halt? boolean
-    }
-
-    class SignalDirective {
-        +stopOtherSignals? boolean
-        +replyWith? string | function
-    }
-
-    note for Directive "One type for all hooks, tools, and branches.\nPre-LLM fields ignored with WARN log outside pre-LLM hooks."
-    note for SignalDirective "Returned by signal handlers (pre / post / both phases)."
-```
-
-`SignalDirective` is what signal handlers return — pre-phase
-handlers, post-phase handlers, and `both`-phase handlers all use the
-same type. `stopOtherSignals` skips remaining handlers in the same
-phase (consumed inside the signal pipeline, not the directive bus).
-`replyWith` is a late-binding `reply` that accepts a function form
-evaluated at emit time. Phase semantics still apply: when a
-`SignalDirective` runs in the post-phase, `appendPrompt` /
-`injectTools` / `halt` are dropped (they have no meaning after the
-LLM call) and position fields set `pendingDirective` for the *next*
-turn rather than redirecting this one.
-
-Both types share one merge algorithm and one validation pass. A
-pre-phase signal can dispatch a `SignalDirective`, a `prepare` hook
-can return a `Directive`, and the engine merges them through the same
-`flow.merge`.
-
-## The `flow` namespace
-
-There are no constructor builders for directives. Directives are
-plain object literals — that is the whole point of the flat shape.
-What the framework does export is a small runtime helper namespace
-for working with directives in code: validating shapes that arrived
-from outside the framework, merging two directives by hand, and
-narrowing `unknown` values in type guards.
-
-```typescript
-import { flow } from "@falai/agent";
-
-flow.isDirective(x);   // structural type guard
-flow.merge(a, b);      // Algorithm 4 merge of two directives
-flow.validate(d);      // throws FlowConfigurationError on invalid shape
-```
-
-`flow.isDirective(x)` is a structural type guard. It returns `true`
-for any non-null, non-array object — primitives, `null`, `undefined`,
-arrays, and functions are filtered out. Use it to narrow an `unknown`
-value coming off an RPC payload or a queue message before passing it
-to `applyDirective` or `agent.dispatch`.
-
-`flow.merge(a, b)` is the same Algorithm 4 the engine runs internally
-on the per-turn directive bus, exposed for callers that need to
-compose results before dispatching them. Position fields merge by
-precedence (`abort > complete > goTo / goToStep > reset`, last-wins
-within the same tier), `reply` is last-wins, `dataUpdate` and
-`contextUpdate` shallow-merge in emission order, `appendPrompt`
-concatenates without deduplication, `injectTools` concatenates and
-then dedupes by `Tool.id` (later definition wins), and `halt` is
-logical-OR. The function is generic: merging two `Directive`s yields
-a `Directive`.
-
-`flow.validate(d)` enforces three structural invariants and throws
-`FlowConfigurationError` when any fails: at most one position field
-per directive, no empty `goTo: {}` (the object form requires a flow
-id), no `reply` alongside `abort`. The pipeline calls it eagerly on
-every emitted directive, so downstream code can rely on shape. It
-does **not** validate that referenced flows or steps exist — that
-check happens at apply time, against the agent's flow registry, which
-the validator does not have a handle on.
-
-The namespace's design intent is "runtime helpers, not authoring
-sugar." If you're constructing a directive in source, write the
-object literal. If you're handling a directive that came from
-elsewhere, narrow it with `flow.isDirective`, validate it with
-`flow.validate`, and merge it with `flow.merge`. The seam between
-"control flow as code" and "control flow as data" is exactly that
-small.
-
-## Where to go next
-
-The directive's mental model is in this page; the field-by-field
-contract — every position field's shorthand and object form, every
-state-write rule, every typed error the validator can throw — is in
-the [Directive reference](../reference/directive.md).
-The signal-specific additions live in [Signals](../reference/signals.md).
-
-When the goal is to *use* directives in handlers, the
-[Flow control guide](../guides/flow-control.md) walks through the
-recipes: redirecting from a tool, completing a flow with a chained
-follow-up, aborting on a permission failure, replying verbatim from a
-finalize hook, dispatching a directive from outside a turn. When the
-goal is to *understand* where directives sit in the per-turn
-sequence, [Turn pipeline](./pipeline.md) covers the bus, the merge
-phases, and the resolution precedence around the directive surface.
-
-**Next:** [createAgent reference](../reference/create-agent.md)