@falai/agent 1.2.8 → 2.0.0

package/docs/reference/providers.md

@@ -0,0 +1,227 @@
+---
+title: "Providers"
+description: "Strategy classes that connect an Agent to Gemini, OpenAI, Anthropic, or OpenRouter."
+type: reference
+order: 10
+---
+
+# Providers
+
+> **Where this is introduced:** [Install](../start/01-install.md)
+
+Providers are the strategy plug between an `Agent` and a model vendor. Every provider implements the same `AiProvider` interface, so the Agent itself stays vendor-agnostic. Pass an instance to `createAgent({ provider })` and the agent talks to that vendor for every turn (and for compaction, if you wire it in).
+
+`@falai/agent` ships four built-in providers. All four accept an `apiKey` and a required `model`, support `backupModels` for automatic failover on overload or 5xx, and accept a vendor-typed `config` object that flows through to the underlying SDK.
+
+| Provider | Class | Options | SDK |
+|----------|-------|---------|-----|
+| Google Gemini | `GeminiProvider` | `GeminiProviderOptions` | `@google/genai` |
+| OpenAI | `OpenAIProvider` | `OpenAIProviderOptions` | `openai` |
+| Anthropic Claude | `AnthropicProvider` | `AnthropicProviderOptions` | `@anthropic-ai/sdk` |
+| OpenRouter | `OpenRouterProvider` | `OpenRouterProviderOptions` | `openai` (compat) |
+
+## Use with createAgent
+
+`createAgent({ provider })` accepts any class that implements `AiProvider`. Swap providers by changing the constructor; nothing else in your agent has to move.
+
+```typescript
+import {
+  createAgent,
+  GeminiProvider,
+  OpenAIProvider,
+  AnthropicProvider,
+  OpenRouterProvider,
+} from "@falai/agent";
+
+const provider =
+  process.env.PROVIDER === "openai"
+    ? new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5-mini" })
+    : process.env.PROVIDER === "anthropic"
+    ? new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-sonnet-4-5" })
+    : process.env.PROVIDER === "openrouter"
+    ? new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY!, model: "anthropic/claude-sonnet-4.5" })
+    : new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY!, model: "models/gemini-2.5-pro" });
+
+const agent = createAgent({ provider, schema, flows });
+```
+
+## GeminiProvider
+
+### Signature
+
+```typescript
+new GeminiProvider(options: GeminiProviderOptions)
+
+interface GeminiProviderOptions {
+  apiKey: string;
+  model: string;
+  backupModels?: string[];
+  config?: Partial<GenerateContentConfig>; // from @google/genai
+  retryConfig?: { timeout?: number; retries?: number };
+}
+```
+
+### Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `apiKey` | `string` | yes | — | Throws if empty. |
+| `model` | `string` | yes | — | Use the fully-qualified id, e.g. `"models/gemini-2.5-pro"`. |
+| `backupModels` | `string[]` | no | `[]` | Tried in order on 429/500/503/overload errors. |
+| `config` | `Partial<GenerateContentConfig>` | no | — | Vendor-typed defaults (e.g. `temperature`, `systemInstruction`). |
+| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
+| `retryConfig.retries` | `number` | no | `3` | Total attempts before giving up. |
+
+### Example
+
+```typescript
+const gemini = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro",
+  backupModels: ["models/gemini-2.5-flash"],
+  config: { temperature: 0.3 },
+});
+```
+
+## OpenAIProvider
+
+### Signature
+
+```typescript
+new OpenAIProvider(options: OpenAIProviderOptions)
+
+interface OpenAIProviderOptions {
+  apiKey: string;
+  organization?: string;
+  model: string;
+  backupModels?: string[];
+  config?: Partial<Omit<ChatCompletionCreateParamsNonStreaming, "model" | "messages">>;
+  retryConfig?: { timeout?: number; retries?: number };
+}
+```
+
+### Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `apiKey` | `string` | yes | — | Throws if empty. |
+| `organization` | `string` | no | — | Forwarded as `OpenAI-Organization`. |
+| `model` | `string` | yes | — | e.g. `"gpt-5"`, `"gpt-5-mini"`. |
+| `backupModels` | `string[]` | no | `[]` | Tried in order on overload/rate-limit errors. |
+| `config` | OpenAI params | no | — | Defaults for `temperature`, `top_p`, etc. |
+| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
+| `retryConfig.retries` | `number` | no | `3` | Total attempts. |
+
+### Example
+
+```typescript
+const openai = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5-mini",
+  organization: "org_abc",
+  config: { temperature: 0.2 },
+});
+```
+
+## AnthropicProvider
+
+### Signature
+
+```typescript
+new AnthropicProvider(options: AnthropicProviderOptions)
+
+interface AnthropicProviderOptions {
+  apiKey: string;
+  model: string;
+  backupModels?: string[];
+  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages">>;
+  retryConfig?: { timeout?: number; retries?: number };
+}
+```
+
+### Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `apiKey` | `string` | yes | — | Throws if empty. |
+| `model` | `string` | yes | — | e.g. `"claude-sonnet-4-5"`, `"claude-opus-4-1"`. |
+| `backupModels` | `string[]` | no | `[]` | Tried in order on 429/500/503/529/overload. |
+| `config` | Anthropic params | no | — | Defaults for `max_tokens`, `system`, etc. The provider sets `max_tokens=4096` if neither `config.max_tokens` nor `parameters.maxOutputTokens` is set. |
+| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
+| `retryConfig.retries` | `number` | no | `3` | Total attempts. |
+
+### Example
+
+```typescript
+const anthropic = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
+  config: { max_tokens: 8192 },
+});
+```
+
+## OpenRouterProvider
+
+OpenRouter is OpenAI-compatible and brokers many vendors behind one endpoint. Use it to A/B-test models without changing client code.
+
+### Signature
+
+```typescript
+new OpenRouterProvider(options: OpenRouterProviderOptions)
+
+interface OpenRouterProviderOptions {
+  apiKey: string;
+  model: string;
+  backupModels?: string[];
+  siteUrl?: string;
+  siteName?: string;
+  config?: Partial<Omit<ChatCompletionCreateParamsNonStreaming, "model" | "messages">>;
+  retryConfig?: { timeout?: number; retries?: number };
+}
+```
+
+### Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `apiKey` | `string` | yes | — | Throws if empty. |
+| `model` | `string` | yes | — | OpenRouter model id, e.g. `"anthropic/claude-sonnet-4.5"`. See [openrouter.ai/models](https://openrouter.ai/models). |
+| `backupModels` | `string[]` | no | `[]` | Tried in order on overload/capacity errors. |
+| `siteUrl` | `string` | no | `""` | Sent as `HTTP-Referer` for OpenRouter rankings. |
+| `siteName` | `string` | no | `""` | Sent as `X-Title` for OpenRouter rankings. |
+| `config` | OpenAI params | no | — | OpenAI-shaped defaults (forwarded to OpenRouter). |
+| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
+| `retryConfig.retries` | `number` | no | `3` | Total attempts. |
+
+### Example
+
+```typescript
+const openrouter = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-sonnet-4.5",
+  backupModels: ["openai/gpt-5-mini", "google/gemini-2.5-pro"],
+  siteName: "My App",
+});
+```
+
+## Errors
+
+All four providers share the same construction-time guards and runtime failure modes.
+
+| When | Error | Why |
+|------|-------|-----|
+| `apiKey` is empty or missing | `Error("<vendor> API key is required")` | Thrown from the constructor. |
+| `model` is empty or missing | `Error("Model is required. ...")` | Thrown from the constructor. |
+| Vendor returns no text and no tool calls | `Error("No response from <vendor>")` | Surfaces as a `ResponseGenerationError` once it bubbles through the agent. |
+| Primary and every backup model fail | The last backup error is rethrown | After exhausting `backupModels`. The agent wraps it in `ResponseGenerationError`. |
+| Anthropic streaming with `system: undefined` | Vendor 400 | Set `config.system` or rely on history-derived system messages. |
+
+The retry/backup logic only kicks in for transient errors: HTTP 429 / 500 / 503 (and 529 for Anthropic), `overloaded`-style codes, or messages containing `overloaded`, `unavailable`, `internal error`, or (OpenRouter only) `capacity`. Other errors fail fast.
+
+## Related
+
+- [Install](../start/01-install.md) — provider signup and env keys
+- [Architecture](../concepts/architecture.md) — where the provider sits in the engine
+- [createAgent](./create-agent.md) — the `provider` field
+- [Persistence adapters](./adapters.md) — the other strategy plug
+- [Errors](./errors.md) — `ResponseGenerationError` and friends

package/docs/reference/signals.md

@@ -0,0 +1,356 @@
+---
+title: "Signals"
+description: "Typed event detectors that run before and after each LLM turn, with optional structured extraction and rate-limited firing."
+type: reference
+order: 9
+---
+
+# Signals
+
+> **Where this is introduced:** [Turn pipeline](../concepts/pipeline.md)
+
+A `Signal` is a typed event detector that runs around an LLM turn. Each signal pairs a *condition* (`when` / `if`) with a *handler* that returns a `SignalDirective`. Signals optionally carry an `extract` schema for structured data extraction beyond boolean detection, run at two pipeline phases (PRE-SIGNAL parallel with routing, POST-SIGNAL after the LLM), are rate-limited (`once` / `always` / `cooldown`), and surface their firings on `AgentResponse.triggeredSignals`.
+
+Signals operate in two modes:
+
+- **Detection mode** — no `extract`. Boolean match/no-match via a batched classifier call. Multiple signals share one LLM call.
+- **Extraction mode** — `extract` set. Structured data extraction merged into the same batched call. The handler receives `ctx.extracted` typed by the `TExtract` generic.
+
+When `agent.signals` is empty or undefined, both phases short-circuit to zero cost — no extra provider calls.
+
+## Signature
+
+```typescript
+interface Signal<TContext = unknown, TData = unknown, TExtract = void> {
+  // Identity
+  id?: string;
+  title?: string;
+  description?: string;
+
+  // Conditions (v2 when/if split)
+  when?: string | string[];
+  if?: SignalPredicate<TContext, TData> | SignalPredicate<TContext, TData>[];
+
+  // Optional structured extraction
+  extract?: SignalSchema<TExtract>;
+
+  // Phase + handler
+  phase: 'pre' | 'post' | 'both';
+  handler: (ctx: SignalContext<TContext, TData, TExtract>) =>
+    | void
+    | SignalDirective<TContext, TData>
+    | Promise<void | SignalDirective<TContext, TData>>;
+
+  // Rate limiting
+  behavior?: 'once' | 'always' | 'cooldown';
+  cooldownMs?: number;
+
+  // Misc
+  enabled?: boolean;
+  priority?: number;
+}
+
+type SignalSchema<_T = unknown> = Record<string, unknown>;
+
+type SignalPredicate<TContext = unknown, TData = unknown> = (
+  ctx: SignalPredicateContext<TContext, TData>,
+) => boolean | Promise<boolean>;
+
+interface SignalPredicateContext<TContext = unknown, TData = unknown> {
+  data: Partial<TData>;
+  context: TContext;
+  session: SessionState<TData>;
+  history: Event[];
+}
+
+interface SignalContext<TContext = unknown, TData = unknown, TExtract = void> {
+  signal: Signal<TContext, TData, TExtract>;
+  phase: 'pre' | 'post';
+  matched: true;
+  reason: string;
+  extracted: TExtract extends void ? undefined : TExtract;
+
+  session: SessionState<TData>;
+  context: TContext;
+  data: Partial<TData>;
+  history: Event[];
+  lastUserMessage?: string;
+  triggeredAt: Date;
+
+  updateContext(updates: Partial<TContext>): Promise<void>;
+  updateData(updates: Partial<TData>): Promise<void>;
+  dispatch(directive: SignalDirective<TContext, TData>): void;
+}
+
+interface SignalDirective<TContext = unknown, TData = unknown>
+  extends PreDirective<TContext, TData> {
+  stopOtherSignals?: boolean;
+  replyWith?: string | ((ctx: SignalContext<TContext, TData>) => string);
+}
+
+interface SignalFiring<TContext = unknown, TData = unknown> {
+  id: string;
+  phase: 'pre' | 'post';
+  reason?: string;
+  extracted?: unknown;
+  directive?: SignalDirective<TContext, TData>;
+  handlerError?: string;
+  durationMs?: number;
+}
+
+interface SignalsState {
+  triggers: Record<string, SignalTriggerState>;
+}
+
+interface SignalTriggerState {
+  firstTriggeredAt: Date;
+  lastTriggeredAt: Date;
+  count: number;
+  lastReason?: string;
+  lastPhase?: 'pre' | 'post';
+}
+```
+
+Signals are wired into the agent through two `AgentOptions` fields:
+
+```typescript
+interface AgentOptions<TContext, TData> {
+  // ... other fields ...
+  signals?: Signal<TContext, TData, unknown>[];
+  signalBatchSize?: number; // default 10
+}
+```
+
+## Fields
+
+### `Signal`
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `id` | `string` | no | auto-generated | Stable identifier within a session. Used for `SignalsState.triggers` keying and on `SignalFiring`. Must be unique across the agent's signals. |
+| `title` | `string` | no | — | Display title shown in logs and traces. |
+| `description` | `string` | no | — | Free-text description; rendered into the classifier prompt. |
+| `when` | `string \| string[]` | no | — | AI-evaluated condition(s). Entries prefixed with `!` are exclusion conditions rendered under "DO NOT TRIGGER WHEN" (OR semantics — any match inhibits firing). Non-prefixed entries render under "TRIGGER WHEN" (AND semantics — all must match). |
+| `if` | `SignalPredicate \| SignalPredicate[]` | no | — | Code predicate(s). AND semantics. Free to evaluate. Runs before `when`; if any returns `false`, `when` is skipped (no token cost). |
+| `extract` | `SignalSchema<TExtract>` | no | — | When set, the signal operates in extraction mode. JSON Schema object describing the per-signal `extracted` field merged into the classifier response. The `TExtract` generic carries the resulting type onto `ctx.extracted`. |
+| `phase` | `'pre' \| 'post' \| 'both'` | yes | — | When the signal evaluates. `'pre'` runs in parallel with routing. `'post'` runs after the LLM call, before persistence. `'both'` evaluates in both phases. |
+| `handler` | `(ctx) => void \| SignalDirective \| Promise<…>` | yes | — | Invoked when the signal fires. May return a directive, dispatch one via `ctx.dispatch`, or return void for side-effect-only behavior. |
+| `behavior` | `'once' \| 'always' \| 'cooldown'` | no | `'always'` | Rate-limit / dedup mode. `'once'` fires once per session. `'cooldown'` requires `cooldownMs`. |
+| `cooldownMs` | `number` | conditional | — | Required when `behavior === 'cooldown'`. Suppresses re-firing for this duration after the last trigger. Misconfiguration logs a debug warning and falls back to `'always'`. |
+| `enabled` | `boolean` | no | `true` | When `false`, the signal is filtered out at the start of the phase. |
+| `priority` | `number` | no | `0` | Higher priority handlers run first within a phase. Ties break by declaration order in `agent.signals`. |
+
+### `SignalPredicateContext`
+
+Passed to every `if` predicate. Symmetric with `BranchPredicateContext`.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `data` | `Partial<TData>` | Collected data so far. Fields not yet collected are `undefined`. |
+| `context` | `TContext` | Ambient agent context. |
+| `session` | `SessionState<TData>` | Full session state, including `session.signals` for inspecting prior triggers. |
+| `history` | `Event[]` | Conversation history as native events. |
+
+A predicate that throws is treated as a non-match — other signals continue evaluating.
+
+### `SignalContext`
+
+Passed to handlers when a signal fires. Symmetric with `ToolContext`.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `signal` | `Signal<TContext, TData, TExtract>` | The signal definition that fired. |
+| `phase` | `'pre' \| 'post'` | Which phase this firing belongs to. Useful when `signal.phase === 'both'`. |
+| `matched` | `true` | Always `true` when the handler runs. Typed for narrowing. |
+| `reason` | `string` | AI rationale when `when` matched, or `'code-only'` / `'unconditional'`. |
+| `extracted` | `TExtract extends void ? undefined : TExtract` | Extracted data when `signal.extract` is set; `undefined` for detection-only signals. |
+| `session` | `SessionState<TData>` | Session state. Use writers below for mutations. |
+| `context` | `TContext` | Ambient agent context. |
+| `data` | `Partial<TData>` | Collected data (partial). |
+| `history` | `Event[]` | Conversation history. |
+| `lastUserMessage` | `string \| undefined` | Convenience accessor for the most recent user message. |
+| `triggeredAt` | `Date` | Wall-clock timestamp when the handler started. |
+| `updateContext` | `(updates) => Promise<void>` | Shallow-merge into `context`. Same contract as `ToolContext.updateContext`. |
+| `updateData` | `(updates) => Promise<void>` | Shallow-merge into `data`. Same contract as `ToolContext.updateData`. |
+| `dispatch` | `(directive) => void` | Emit a `SignalDirective` onto the per-turn bus. May be called multiple times; emissions merge by Algorithm 4 alongside hook and tool directives. |
+
+### `SignalDirective`
+
+Extends [`PreDirective`](./pre-directive.md), which extends [`Directive`](./directive.md). All position fields (`goTo`, `goToStep`, `complete`, `abort`, `reset`), state writes (`dataUpdate`, `contextUpdate`), `reply`, and PreDirective extras (`appendPrompt`, `injectTools`, `halt`) are inherited unchanged.
+
+| Added field | Type | Notes |
+|-------------|------|-------|
+| `stopOtherSignals` | `boolean` | When `true`, skip remaining signals in the current phase after this handler. Does not affect the other phase. Consumed inside the signal pipeline — does not enter the directive bus. |
+| `replyWith` | `string \| ((ctx) => string)` | Late-binding `reply`. String form is identical to `Directive.reply`. Function form is evaluated at emit time and projected onto `reply` before bus merging. |
+
+**Post-phase drop rules.** When a signal runs in the post-phase, `appendPrompt`, `injectTools`, and `halt` are dropped with a debug warning — they have no meaning after the LLM call has already completed. Position directives in the post-phase set `session.pendingDirective` for the *next* turn (no mid-turn re-entry).
+
+### `SignalFiring`
+
+One entry per signal that fired this turn. Populated in fire order across both phases on `AgentResponse.triggeredSignals` (and on the final chunk of `AgentResponseStreamChunk`). Mirrors the observability framing of `executedSteps` and `appliedInstructions`.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `string` | The signal's identifier. |
+| `phase` | `'pre' \| 'post'` | Phase the signal fired in. |
+| `reason` | `string \| undefined` | AI rationale, `'code-only'`, or `'unconditional'`. |
+| `extracted` | `unknown` | Extracted payload when in extraction mode. |
+| `directive` | `SignalDirective \| undefined` | The directive returned (or dispatched) by the handler. |
+| `handlerError` | `string \| undefined` | Error message if the handler threw. The turn continues — handler errors never break a turn. |
+| `durationMs` | `number \| undefined` | Wall-clock duration of the handler invocation. |
+
+### `SignalsState` and `SignalTriggerState`
+
+Persisted on `session.signals`. Adapters preserve this shape bit-identical.
+
+`SignalsState` has a single field, `triggers: Record<string, SignalTriggerState>`, keyed by `signal.id`.
+
+| `SignalTriggerState` field | Type | Notes |
+|----------------------------|------|-------|
+| `firstTriggeredAt` | `Date` | When this signal first fired in the session. Never updated on subsequent fires. |
+| `lastTriggeredAt` | `Date` | When this signal last fired. Drives `cooldown` arithmetic. |
+| `count` | `number` | Total fires for this signal in this session. Monotonically increasing. |
+| `lastReason` | `string \| undefined` | The `reason` from the most recent firing. |
+| `lastPhase` | `'pre' \| 'post' \| undefined` | The phase of the most recent firing. |
+
+### `signalBatchSize`
+
+Maximum signals per batched classifier call. Default `10`. When more LLM-conditioned signals are eligible after gating, they split into parallel batches of this size — each batch is one provider call, all batches run via `Promise.all`. Setting this to `0` or a non-integer throws `FlowConfigurationError` at agent construction.
+
+## Phase semantics
+
+| Capability | Pre-phase | Post-phase |
+|---|---|---|
+| `halt` | Skips the LLM call | Dropped with debug warning |
+| `reply` / `replyWith` | Replaces the message that would have been generated | Replaces the message that was just generated |
+| `goTo` / `goToStep` | Overrides routing for this turn | Sets `pendingDirective` for next turn |
+| `complete` | This turn closes the flow | Same |
+| `appendPrompt` | Injected into this turn's response prompt | Dropped with debug warning |
+| `injectTools` | Available to this turn's LLM | Dropped with debug warning |
+| `dataUpdate` / `contextUpdate` | Applied before LLM, visible in prompt | Applied, persisted |
+| `extract` results | Available to handler pre-LLM | Available to handler post-LLM |
+| `stopOtherSignals` | Stops further pre-signals | Stops further post-signals |
+
+### Resolution precedence within a turn
+
+Per turn, position decisions are resolved in this fixed order:
+
+1. **`session.pendingDirective`** (set last turn or via `agent.dispatch()`) — consumed first.
+2. **PRE-SIGNAL phase directives** (parallel with routing). Position fields override routing; `halt` discards routing entirely.
+3. **AI routing** — used only if (1) and (2) produced no position field.
+4. **Auto-step chain.**
+5. **Step branches.**
+6. **Linear successor / AI step selection** — final fallback.
+7. **POST-SIGNAL phase directives** — set `pendingDirective` for the *next* turn.
+
+## Examples
+
+### 1. Pre-phase halt with verbatim reply (escalation)
+
+A handoff signal that intercepts the turn before the LLM runs, notifies a side channel, and replies with a fixed message. Cooldown prevents re-notification within the hour.
+
+```typescript
+import type { Signal } from "@falai/agent";
+
+type Ctx = { conversationId: string };
+type Data = { topic?: string };
+
+export const humanHandoff: Signal<Ctx, Data> = {
+  id: "human_handoff",
+  title: "Human handoff requested",
+  description: "Lead asks to talk to a real person.",
+  when: [
+    "the user explicitly asks to talk to a human, agent, or representative",
+    "the user explicitly says they do not want to talk to a bot",
+    "!casual mentions of people (e.g., 'my colleague said')",
+    "!general frustration without an explicit handoff request",
+  ],
+  phase: "pre",
+  behavior: "cooldown",
+  cooldownMs: 60 * 60_000, // 1 hour
+  priority: 100,
+  async handler({ session, lastUserMessage }) {
+    await notifyTeam(session.id, lastUserMessage);
+    return {
+      halt: true,
+      replyWith: "I'm connecting you with someone from our team. They'll reach out shortly.",
+      stopOtherSignals: true,
+    };
+  },
+};
+```
+
+### 2. Post-phase extraction (entity capture)
+
+A signal that runs after every LLM turn, extracts a structured payload, and writes it back into collected data. No `when` — it's gated by `if` on session state, then unconditionally extracts when eligible.
+
+```typescript
+import type { Signal } from "@falai/agent";
+
+type Data = { leadStage?: "cold" | "warm" | "hot" | "closing" };
+
+export const leadStage: Signal<unknown, Data, { stage: Data["leadStage"]; confidence: number }> = {
+  id: "lead_stage",
+  title: "Lead stage classification",
+  if: ({ session }) => (session.history?.length ?? 0) > 5,
+  extract: {
+    type: "object",
+    properties: {
+      stage: { type: "string", enum: ["cold", "warm", "hot", "closing"] },
+      confidence: { type: "number", minimum: 0, maximum: 1 },
+    },
+    required: ["stage", "confidence"],
+  },
+  phase: "post",
+  behavior: "always",
+  async handler({ extracted, updateData }) {
+    if (extracted.confidence >= 0.6) {
+      await updateData({ leadStage: extracted.stage });
+    }
+  },
+};
+```
+
+### 3. Cooldown behavior
+
+A pre-phase signal that nudges the next prompt with a tone hint, suppressed for two minutes after each fire so a frustrated user isn't re-flagged on every turn.
+
+```typescript
+import type { Signal } from "@falai/agent";
+
+export const frustrationDetected: Signal = {
+  id: "frustration_detected",
+  when: "the user is visibly frustrated, impatient, or upset",
+  phase: "pre",
+  behavior: "cooldown",
+  cooldownMs: 2 * 60_000, // 2 minutes
+  async handler({ dispatch }) {
+    dispatch({
+      appendPrompt: ["The user is frustrated. Lead with empathy and acknowledge the issue."],
+    });
+  },
+};
+```
+
+## Errors
+
+Misuse surfaces as typed errors:
+
+- `FlowConfigurationError` — duplicate `id` across `agent.signals`, invalid `extract` schema (not a JSON Schema object), `signalBatchSize` not a positive integer, or a position directive (`goTo` / `goToStep`) that resolves to an unknown flow or step.
+- `DataValidationError` — `dataUpdate` (or `extracted` written via `updateData`) violates the agent schema.
+
+Soft failures handled in-band (no thrown error, turn continues):
+
+- **Handler throws** — recorded as `firings[i].handlerError`; iteration continues with the next signal.
+- **Classifier call fails** — all LLM-conditioned signals in that batch are treated as non-match; code-only and unconditional signals continue normally.
+- **Post-phase emits pre-LLM-only fields** (`halt` / `appendPrompt` / `injectTools`) — dropped with debug warning.
+- **`behavior: 'cooldown'` with no `cooldownMs`** — debug warning at construction; runtime treats as `'always'`.
+
+## Related
+
+- [Turn pipeline](../concepts/pipeline.md) — where signal phases sit in the turn lifecycle.
+- [Directives](../concepts/directives.md) — the inheritance chain Directive → PreDirective → SignalDirective.
+- [Directive](./directive.md) — base shape for all position and state fields.
+- [PreDirective](./pre-directive.md) — pre-LLM extras inherited by `SignalDirective`.
+- [createAgent](./create-agent.md) — `signals` and `signalBatchSize` options.
+- [Errors](./errors.md) — `FlowConfigurationError` format contract.