@falai/agent 3.4.5 → 4.0.0-alpha.10

package/docs/reference/create-agent.md

@@ -1,216 +0,0 @@
----
-title: "createAgent"
-description: "Factory function that constructs an Agent from a single options object."
-type: reference
-order: 1
----
-
-# createAgent
-
-> **Where this is introduced:** [Your first agent](../start/02-first-agent.md)
-
-`createAgent` is the level-1 entry point for constructing an `Agent`. It is
-syntactic sugar over `new Agent(options)` and accepts the same `AgentOptions`
-shape. Generic inference flows from `schema` through every `flows[].steps[].collect`
-reference, so the type of `session.data` and tool handler arguments is derived
-once and propagates everywhere.
-
-## Signature
-
-```typescript
-function createAgent<TContext = unknown, TData = unknown>(
-  options: AgentOptions<TContext, TData>
-): Agent<TContext, TData>;
-
-interface AgentOptions<TContext = unknown, TData = unknown> {
-  name: string;
-  goal?: string;
-  persona?: Template<TContext>;
-  debug?: boolean;
-  context?: TContext;
-  contextProvider?: ContextProvider<TContext>;
-  hooks?: ContextLifecycleHooks<TContext, TData>;
-  provider: AiProvider;
-  schema?: StructuredSchema;
-  initialData?: Partial<TData>;
-  terms?: Term<TContext, TData>[];
-  instructions?: Instruction<TContext, TData>[];
-  tools?: Tool<TContext, TData, unknown>[];
-  flows?: FlowOptions<TContext, TData>[];
-  signals?: Signal<TContext, TData, unknown>[];
-  signalBatchSize?: number;
-  persistence?: PersistenceConfig<TData>;
-  knowledgeBase?: Record<string, unknown>;
-  flowSwitchMargin?: number;
-  maxHistoryMessages?: number;
-  maxAutoStepsPerTurn?: number;
-  maxDirectiveChain?: number;
-  maxToolLoops?: number;
-  compaction?: AgentCompactionConfig;
-  promptCache?: PromptCacheConfig;
-  routerMode?: 'ai';
-  sessionId?: string;
-  session?: SessionState;
-}
-```
-
-## Fields
-
-| Field | Type | Required | Default | Notes |
-|-------|------|----------|---------|-------|
-| `name` | `string` | yes | — | Display name surfaced in logs and prompt sections. |
-| `goal` | `string` | no | — | One-line objective rendered into the system prompt. |
-| `persona` | `Template<TContext>` | no | — | Who the agent is and how it communicates — role, tone, and self-concept. Rendered into the system prompt. |
-| `provider` | `AiProvider` | yes | — | Strategy instance: `GeminiProvider`, `OpenAIProvider`, `AnthropicProvider`, `OpenRouterProvider`, `DeepSeekProvider`, or your own (must declare `capabilities`). |
-| `schema` | `StructuredSchema` | no | — | Single source of truth for `TData`. Every `collect` key in every step must reference a property defined here. |
-| `initialData` | `Partial<TData>` | no | — | Staged at construction and seeds `session.data` when the first session is created. Loading an existing session keeps the stored data instead. |
-| `flows` | `FlowOptions<TContext, TData>[]` | no | `[]` | Conversation flows. May also be added later via `agent.createFlow(...)`. |
-| `tools` | `Tool<TContext, TData, unknown>[]` | no | `[]` | Agent-scoped tools. Each tool's `Tool.id` must be unique. |
-| `instructions` | `Instruction<TContext, TData>[]` | no | `[]` | Behavioral statements discriminated by `kind: 'must' \| 'never' \| 'should'`. Scoped at agent, flow, or step level. |
-| `terms` | `Term<TContext, TData>[]` | no | `[]` | Domain glossary entries inlined into the prompt. |
-| `signals` | `Signal<TContext, TData, unknown>[]` | no | `[]` | Typed event detectors that run before/after the LLM turn. |
-| `signalBatchSize` | `number` | no | `10` | Maximum signals per batched classifier call. Throws `FlowConfigurationError` if not a positive integer. |
-| `context` | `TContext` | no | — | Static ambient data (user info, env, etc.) available to every hook and tool. |
-| `contextProvider` | `ContextProvider<TContext>` | no | — | Async context loader. Use instead of `context` when ambient data must be fetched per turn. |
-| `hooks` | `ContextLifecycleHooks<TContext, TData>` | no | — | `beforeRespond`, `onContextUpdate`, `onDataUpdate` — fire around every turn. |
-| `persistence` | `PersistenceConfig<TData>` | no | in-memory | Session storage: `adapter`, `autoSave`, `userId`, plus `schemaVersion` / `migrateSession` for upgrading state written by older deployments. Omit for `MemoryAdapter`. |
-| `knowledgeBase` | `Record<string, unknown>` | no | — | Arbitrary JSON inlined into the prompt as background knowledge. |
-| `flowSwitchMargin` | `number` | no | `15` | Margin (0–100) the best alternative flow must exceed the current flow's score by before switching. Higher values make the agent stickier. |
-| `maxHistoryMessages` | `number` | no | `400` | Hard bound on `session.history`. Applied at end-of-turn finalize (and on interim auto-saves): the oldest entries are trimmed — never splitting an assistant/tool pair — and a warning is logged. Use `compaction` for summarization instead of truncation; set `0` to disable bounding entirely. |
-| `maxAutoStepsPerTurn` | `number` | no | `10` | Cap on consecutive `auto: true` steps per turn. Throws `FlowConfigurationError` when exceeded. |
-| `maxDirectiveChain` | `number` | no | `10` | Cap on chained directives per turn (e.g., `goTo` → `onEnter` emits `goTo` → …). Throws `FlowConfigurationError` when exceeded. |
-| `maxToolLoops` | `number` | no | `5` | Cap on tool-call follow-up rounds per turn, after the initial tool batch. Stops executing further tool calls when reached. Applies to both `respond()` and streaming. An explicit `0` disables tool loops. |
-| `compaction` | `AgentCompactionConfig` | no | — | History compaction config: `maxTokens`, `compactionThreshold`, `preserveRecentCount`, `maxToolResultChars`. |
-| `promptCache` | `PromptCacheConfig` | no | `{ enabled: true }` | Controls prompt-section memoization across turns. |
-| `debug` | `boolean` | no | `false` | Enables `loglevel` debug output. |
-| `routerMode` | `'ai'` | no | `'ai'` | Reserved for future router strategies. Any non-`'ai'` value throws `NotImplementedError` at construction. |
-| `sessionId` | `string` | no | — | Auto-loads the session with this id from the configured adapter. |
-| `session` | `SessionState` | no | — | Pre-built session passed in for convenience methods. |
-
-## Examples
-
-### Minimal agent
-
-```typescript
-import { createAgent, GeminiProvider } from '@falai/agent';
-
-const agent = createAgent({
-  name: 'Greeter',
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: {
-    type: 'object',
-    properties: { name: { type: 'string' } },
-  },
-  flows: [
-    {
-      title: 'Greet',
-      steps: [
-        { id: 'ask_name', prompt: 'Ask for the user\'s name.', collect: ['name'] },
-        { id: 'greet', prompt: 'Greet them by name.', requires: ['name'] },
-      ],
-    },
-  ],
-});
-
-const response = await agent.respond('Hi, I\'m Ada.');
-console.log(response.message);
-```
-
-### Tools, instructions, and persistence
-
-```typescript
-import { createAgent, GeminiProvider, MemoryAdapter } from '@falai/agent';
-
-const agent = createAgent({
-  name: 'BookingBot',
-  persona: 'Concise concierge. Always confirms dates before booking.',
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: {
-    type: 'object',
-    properties: {
-      city: { type: 'string' },
-      checkIn: { type: 'string' },
-    },
-  },
-  instructions: [
-    { kind: 'must', prompt: 'Validate dates are in the future.' },
-    { kind: 'never', prompt: 'Promise rates you have not looked up.' },
-  ],
-  tools: [
-    {
-      id: 'book_hotel',
-      description: 'Book a hotel for the collected city and date.',
-      parameters: {
-        type: 'object',
-        properties: {
-          city: { type: 'string' },
-          checkIn: { type: 'string' },
-        },
-        required: ['city', 'checkIn'],
-      },
-      handler: async (ctx, args) => {
-        const ref = await reserve(args.city, args.checkIn);
-        return { content: `Booked ${ref}.` };
-      },
-    },
-  ],
-  flows: [
-    {
-      title: 'Book',
-      requiredFields: ['city', 'checkIn'],
-      steps: [
-        { id: 'ask', prompt: 'Collect city and check-in date.', collect: ['city', 'checkIn'] },
-        { id: 'confirm', prompt: 'Confirm and call book_hotel.', requires: ['city', 'checkIn'] },
-      ],
-    },
-  ],
-  persistence: { adapter: new MemoryAdapter() },
-});
-```
-
-## Turn parameters and response surface
-
-`respond()` / `respondStream()` share one params object (`RespondParams`). Beyond the required `history`, two per-turn knobs matter:
-
-| Param | Type | Notes |
-|-------|------|-------|
-| `message` | `string` | The user's message for this turn. When set, the engine appends it to the history the model sees **and** to the returned session's history, then appends the assistant reply on top — callers who hold sessions no longer maintain history arrays by hand. Empty replies are not recorded. |
-| `allowedFlows` | `string[]` | Restricts this turn's **routing** candidates to these flow ids/titles. Directive targets (`goTo` etc.) still resolve against the full registry. Use for entry-pin funnels instead of cloning/filtering agents. |
-
-On the result side, `AgentResponse` carries:
-
-- `endedFlows?: EndedFlow[]` — flows that left their active position this turn (completions, redirects, resets), each as `{ flowId, title?, reason }`. Lets consumers stop re-deriving exits from `executedSteps` + cursor inspection. Streaming chunks do not carry `endedFlows`.
-- `metadata.tokensUsed?` — provider-reported usage for the turn's primary generation call (routing and extraction sub-calls are not included); present only when the provider reports usage. On streaming turns the same value rides on chunk `metadata`.
-
-```typescript
-const response = await agent.respond({
-  history,
-  message: "I'd like the vegetarian menu",
-  allowedFlows: ["order"],
-});
-
-for (const ended of response.endedFlows ?? []) {
-  console.log(`flow "${ended.title ?? ended.flowId}" ended (${ended.reason})`);
-}
-```
-
-## Errors
-
-`createAgent` runs the same construction-time validation as `new Agent(...)`.
-The following typed errors may be thrown:
-
-- `FlowConfigurationError` — duplicate flow ids or titles, duplicate signal ids, duplicate tool ids, invalid `signalBatchSize`, invalid signal `extract` schema, a step's `collect` references a key not defined in `schema`, a flow's `requiredFields`/`optionalFields` references an unknown schema key, or an unresolvable branch `then` target.
-- `NotImplementedError` — `routerMode` set to anything other than `'ai'`.
-
-Validation errors during a turn (not construction) — `DataValidationError`,
-`ToolExecutionError`, `ResponseGenerationError` — surface from
-`agent.respond(...)` and are documented on [Errors](./errors.md).
-
-## Related
-
-- [Architecture](../concepts/architecture.md) — the seven primitives and how they fit together
-- [Your first agent](../start/02-first-agent.md) — the tutorial that introduces `createAgent`
-- [Flow](./flow.md) — the `flows[]` entry shape
-- [Tool](./tool.md) — the `tools[]` entry shape
-- [Instruction](./instruction.md) — the `instructions[]` entry shape
-- [Errors](./errors.md) — typed error classes thrown at construction and at runtime

package/docs/reference/directive.md

@@ -1,242 +0,0 @@
----
-title: "Directive"
-description: "Flat shape returned by tools and hooks to write state, redirect the conversation, or speak verbatim."
-type: reference
-order: 6
----
-
-# Directive
-
-> **Where this is introduced:** [Directives](../concepts/directives.md)
-
-A `Directive<TContext, TData>` is the single shape any tool, hook, or branch returns when it wants to write state, change position, or speak verbatim. It is a **flat object literal** — not a discriminated union, not a class, not a builder. Every field is optional. Every directive is plain JSON-serializable data. Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are one-turn-lifetime and ignored with a WARN log when emitted from post-LLM hooks or persisted.
-
-A directive carries up to four orthogonal payloads:
-
-- **One position field** — `goTo`, `goToStep`, `complete`, `abort`, or `reset`. Where to send the conversation. Mutually exclusive: at most one per directive.
-- **State writes** — `dataUpdate` and/or `contextUpdate`. Shallow-merged into `session.data` and `session.context` before the next phase runs.
-- **A verbatim reply** — `reply`. The literal assistant utterance, bypassing the LLM.
-- **Per-position observability** — `reason` strings inside the object forms of position fields, surfaced in event traces and the directive chain log.
-
-Multiple directives emitted during the same turn are collected onto the per-turn bus and merged by Algorithm 4 (see [Merge rules](#merge-rules) below).
-
-## Signature
-
-```typescript
-interface Directive<TContext = unknown, TData = unknown> {
-  // ── Position fields (mutually exclusive: at most one) ────────────
-  goTo?:
-    | string
-    | {
-        flow?: string;
-        step?: string;
-        data?: Partial<TData>;
-        reason?: string;
-        carry?: "preserve" | "reset";
-      };
-
-  goToStep?:
-    | string
-    | { step: string; flow?: string; data?: Partial<TData>; reason?: string };
-
-  complete?:
-    | true
-    | { next?: Directive<TContext, TData>; reason?: string };
-
-  abort?:
-    | string
-    | { reason: string; clearSession?: boolean };
-
-  reset?:
-    | true
-    | { step?: string; clearData?: boolean; reason?: string };
-
-  // ── Verbatim utterance ───────────────────────────────────────────
-  reply?: string;
-
-  // ── State writes (shallow-merged, both phases) ───────────────────
-  contextUpdate?: Partial<TContext>;
-  dataUpdate?: Partial<TData>;
-}
-```
-
-## Fields
-
-### Position fields
-
-Exactly **zero or one** position field may be set per directive. Setting two or more is a runtime configuration error (see [Errors](#errors)). When zero are set, the directive is purely a state write or a verbatim reply.
-
-| Field | Shorthand | Object form | Notes |
-|-------|-----------|-------------|-------|
-| `goTo` | `string` (flow id / title) | `{ flow?, step?, data?, reason?, carry? }` | Jump to another flow. The string form is sugar for `{ flow: <string> }`. `carry: 'reset'` clears the destination flow's `requiredFields`/`optionalFields` on entry; `carry: 'preserve'` (default) preserves them. `data` is shallow-merged into `session.data` before entry. |
-| `goToStep` | `string` (step id in the current flow) | `{ step, flow?, data?, reason? }` | Jump to a step. The bare string form targets the current flow only — for cross-flow steps, use the object form with `flow`. |
-| `complete` | `true` | `{ next?, reason? }` | Mark the current flow complete. `next` is a chained `Directive` applied immediately after completion (e.g. transition to a follow-up flow). Equivalent to satisfying all `requiredFields`. |
-| `abort` | `string` (reason) | `{ reason, clearSession? }` | End the conversation. The string form is sugar for `{ reason: <string> }`. When `clearSession: true`, the session is cleared at the next persistence write. `reply` cannot co-exist with `abort` — an aborted conversation cannot deliver a reply. |
-| `reset` | `true` | `{ step?, clearData?, reason? }` | Restart the current flow. `step` re-enters at a specific step (default: initial). `clearData: true` clears every field declared in the flow's `requiredFields` and `optionalFields`. |
-
-Each object form carries an optional `reason: string`. The reason is **observability-only** — it appears in the per-turn directive-chain debug log so traces are self-explaining. It does not influence routing, merging, or any pipeline decision.
-
-### State writes
-
-| Field | Type | Phase | Notes |
-|-------|------|-------|-------|
-| `dataUpdate` | `Partial<TData>` | both | Shallow-merged into `session.data`. Triggers `flow.hooks.onDataUpdate` and `Agent` data hooks. Across multiple emitters this turn, key collisions resolve last-write-wins. |
-| `contextUpdate` | `Partial<TContext>` | both | Shallow-merged into `session.context`. Triggers `flow.hooks.onContextUpdate` and `Agent` context hooks. Last-write-wins on key collision. |
-
-Shallow-merge means each top-level key is replaced wholesale. To update a nested object, read it from `data`/`context`, merge in code, and write back the full sub-object. Deep merge is intentionally not provided — it would silently disagree with TypeScript's `Partial<>` shape.
-
-### `reply`
-
-`reply: string` is the verbatim assistant utterance. When set, the LLM call is skipped this turn and the string is emitted as the assistant message exactly as written. Templating is not applied — `reply` is the rendered output.
-
-`reply` co-validates with two fields:
-
-- **`abort`** — co-existence is rejected at validation. Aborted conversations cannot deliver a reply.
-- **`halt`** — when both are set, `reply` becomes the assistant output and the turn ends with `stoppedReason: 'reply'`. When `halt` is set without `reply`, the turn ends with `stoppedReason: 'halt'` and an empty assistant message.
-
-Across multiple emitters this turn, `reply` is **last-wins** — the most recent emission overrides earlier ones, with a `DEBUG` log when more than one emitter set it.
-
-## Merge rules
-
-Directives emitted during one turn — by tools (return value or `ctx.dispatch`), prepare/finalize hooks, onEnter/onComplete hooks, and signal handlers — are collected onto a per-phase bus and merged into a single applied directive. The bus runs in two phases (pre-LLM and post-LLM); merge rules are identical for both.
-
-| Field group | Merge rule |
-|-------------|-----------|
-| Position fields (`goTo`, `goToStep`, `complete`, `abort`, `reset`) | **Winner-takes-all by precedence:** `abort > complete > goTo / goToStep > reset`. Among entries of the same precedence, last emission wins. A `DEBUG` log records all losers. |
-| `reply` | **Last-wins.** Most recent non-empty `reply` overrides earlier ones. `DEBUG` log when more than one was set. |
-| `dataUpdate`, `contextUpdate` | **Shallow-merged across all emitters.** Last-write-wins on key collision. Always applied — never overridden by position fields. |
-| `appendPrompt` | **Concatenated** in emission order. |
-| `injectTools` | **Concatenated, then deduped by `Tool.id`** (last definition wins). |
-| `halt` | **Logical-OR.** Any emitter setting `halt: true` halts the turn. |
-
-The full algorithm is implemented by `flow.merge(a, b)`. See [`flow` namespace](#flow-namespace) below.
-
-> Branches **do not** participate in this bus. When a branch's `then` resolves to a `Directive`, it is applied via `applyDirective` directly, bypassing merge. The bus winner (if any) wins over branch evaluation: if the post-LLM bus produced a position field, branches don't run on that turn. See [Branches](./branches.md).
-
-## `flow` namespace
-
-The `flow` namespace exports three runtime helpers for working with directives. There are no constructor builders — directives are plain object literals.
-
-```typescript
-import { flow } from "@falai/agent";
-
-flow.isDirective(x);     // type guard
-flow.merge(a, b);        // Algorithm 4 merge of two directives
-flow.validate(d);        // throws FlowConfigurationError on invalid shape
-```
-
-| Helper | Signature | Notes |
-|--------|-----------|-------|
-| `flow.isDirective` | `(x: unknown) => x is Directive` | Structural type guard. Returns `true` for any non-null, non-array object. Filters out primitives, null/undefined, arrays, and functions. |
-| `flow.merge` | `<T extends Directive>(a: T, b: T) => T` | Merges by Algorithm 4. Position field uses precedence (b wins on tie). `reply` is last-wins. State writes shallow-merge. Pre-LLM fields concatenate / dedupe / OR per the table above. |
-| `flow.validate` | `(d: Directive) => void` | Throws `FlowConfigurationError` for: multiple position fields set; `goTo` set as an empty object `{}`; `reply` co-existing with `abort`. |
-
-## Examples
-
-### 1. Simple `goTo`
-
-A finalize hook redirects to a follow-up flow when a flag flips on the response.
-
-```typescript
-import type { Directive } from "@falai/agent";
-
-const step = {
-  id: "summary",
-  prompt: "Summarize the request.",
-  hooks: {
-    finalize: ({ data }): Directive | void => {
-      if (data.escalate) {
-        return { goTo: "Escalation", reason: "summary marked escalate=true" };
-      }
-    },
-  },
-};
-```
-
-### 2. `complete` with `dataUpdate`
-
-A booking tool finalizes its work and writes back the booking id while marking the flow done in one declarative result.
-
-```typescript
-import type { Tool, Directive } from "@falai/agent";
-
-export const bookHotel: Tool = {
-  id: "book_hotel",
-  description: "Reserve the collected dates.",
-  async handler(ctx) {
-    const id = await api.book(ctx.data);
-    const directive: Directive = {
-      complete: { reason: "reservation confirmed" },
-      dataUpdate: { bookingId: id, bookedAt: new Date().toISOString() },
-    };
-    return { data: { id }, directive };
-  },
-};
-```
-
-### 3. `abort`
-
-A permission tool halts the conversation when the caller cannot proceed. Note that `reply` cannot accompany `abort`; the abort reason itself is what's recorded.
-
-```typescript
-import type { Tool, Directive } from "@falai/agent";
-
-export const verifyAccess: Tool = {
-  id: "verify_access",
-  isReadOnly: () => true,
-  async handler(ctx) {
-    const allowed = await acl.check(ctx.context.userId);
-    if (!allowed) {
-      const directive: Directive = {
-        abort: { reason: "caller is not on the allow-list", clearSession: true },
-      };
-      return { data: { allowed: false }, directive };
-    }
-    return { data: { allowed: true } };
-  },
-};
-```
-
-### 4. `reply` only — speak verbatim, write nothing
-
-A finalize hook emits a confirmation utterance without changing position or writing state. The LLM call this turn is skipped; the literal string is the assistant message.
-
-```typescript
-import type { Directive } from "@falai/agent";
-
-const step = {
-  id: "confirm_handoff",
-  hooks: {
-    finalize: ({ data }): Directive | void => {
-      if (data.handoffReady) {
-        return { reply: "Connecting you with a specialist now." };
-      }
-    },
-  },
-};
-```
-
-## Errors
-
-`flow.validate(directive)` and the per-turn merge stage throw `FlowConfigurationError` for the following invariants. See [Errors](./errors.md) for the format contract.
-
-| Cause | Message shape |
-|-------|---------------|
-| Multiple position fields set on one directive | `[FlowConfigurationError] Invalid directive: multiple position fields set (...). A directive may have at most one position field. Remove the extras.` |
-| `goTo` set as an empty object `{}` | `[FlowConfigurationError] Invalid directive: goTo is set as an empty object. goTo requires a flow id or title. Provide { flow: "<id>" } or use the string shorthand.` |
-| `reply` co-existing with `abort` | `[FlowConfigurationError] Invalid directive: reply cannot co-exist with abort. An aborted conversation cannot deliver a reply. Remove one of the fields.` |
-
-Two related runtime behaviors are notable but **not** thrown errors:
-
-- Returning a directive with `appendPrompt` / `injectTools` / `halt` from a post-LLM hook (`finalize`, `onComplete`) drops those three fields with a `WARN` log; the remaining `Directive` portion is honored.
-- A `goTo` / `goToStep` referencing an unknown flow or step throws `FlowConfigurationError` at apply time, not at validation time — the validator does not have the agent's flow registry.
-
-## Related
-
-- [Directives](../concepts/directives.md) — the mental model for `Directive` and `SignalDirective`.
-- [Turn pipeline](../concepts/pipeline.md) — when the bus runs, and where merge sits in the per-turn sequence.
-- [Flow control](../guides/flow-control.md) — recipes for redirecting, completing, aborting, or replying from tools and hooks.
-- [Signals](./signals.md) — `SignalDirective` extends `Directive` for signal handlers.
-- [Tool](./tool.md) — `ctx.dispatch(directive)` and `ToolResult.directive`.
-- [Branches](./branches.md) — `then: Directive` as a branch target (note: branches bypass the bus).
-- [Errors](./errors.md) — `FlowConfigurationError` format contract.