@graphrefly/graphrefly 0.40.0 → 0.42.0

package/dist/{index-DpiGqtrs.d.cts → index-B11anra4.d.cts}

@@ -1,18 +1,18 @@
-import { T as TokenUsage, L as LLMAdapter, P as PricingFn, C as ChatMessage, a as LLMInvokeOptions, d as ToolDefinition, b as LLMResponse, S as StreamDelta, c as ToolCall, e as CapabilitiesRegistry, M as ModelCapabilities, f as ModelFeatures, g as ModelLimits, h as ModelPricing, i as PriceBreakdown, j as PricingRegistry, R as Rate, k as TieredRate, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from './types-1Dhoi7HM.cjs';
-import { a as CascadeExhaustionReport, A as AdapterProvider, b as AdapterTier, d as AllTiersExhaustedError, C as CascadingLlmAdapterOptions, e as CreateAdapterOptions, O as OpenAICompatAdapterOptions, f as OpenAICompatPreset, g as OpenAISdkLike, h as cascadingLlmAdapter, c as createAdapter, o as openAICompatAdapter, t as tier } from './cascading-Cxs1eztH.cjs';
-import { N as Node, A as Actor } from './node-BYInONRr.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-_zeEnB9H.cjs';
-import { b as CircuitBreakerOptions, f as CircuitBreaker, g as CircuitOpenError } from './index-DGTo1yka.cjs';
+import { T as TokenUsage, L as LLMAdapter, P as PricingFn, C as ChatMessage, a as LLMInvokeOptions, d as ToolDefinition, b as LLMResponse, S as StreamDelta, c as ToolCall, e as CapabilitiesRegistry, M as ModelCapabilities, f as ModelFeatures, g as ModelLimits, h as ModelPricing, i as PriceBreakdown, j as PricingRegistry, R as Rate, k as TieredRate, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from './types-B1jDWVsM.cjs';
+import { a as CascadeExhaustionReport, A as AdapterProvider, b as AdapterTier, d as AllTiersExhaustedError, C as CascadingLlmAdapterOptions, e as CreateAdapterOptions, O as OpenAICompatAdapterOptions, f as OpenAICompatPreset, g as OpenAISdkLike, h as cascadingLlmAdapter, c as createAdapter, o as openAICompatAdapter, t as tier } from './cascading-CH-_VwG9.cjs';
+import { N as Node, A as Actor } from './node-ClS5yC-B.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-B00laMSQ.cjs';
+import { b as CircuitBreakerOptions, C as CircuitBreaker, c as CircuitOpenError } from './index-BoLv_OfD.cjs';
 import { NodeInput } from './extra/sources.cjs';
-import { W as WithReplayCacheOptions, F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as canonicalJson, g as fallbackAdapter, w as withReplayCache } from './fallback-8JYU8tlT.cjs';
-import { E as Extraction, D as DistillBundle, f as DEFAULT_DECAY_RATE } from './decay-C25AyNAj.cjs';
-import { G as Graph, a as GraphOptions, k as GraphCheckpointRecord, j as GraphAttachStorageOptions } from './graph-E6likq7w.cjs';
-import { T as TopicGraph } from './index-Cnr1WrlX.cjs';
-import { G as GateController, c as GateOptions } from './pipeline-graph-MWrQZXCq.cjs';
-import { V as VectorSearchResult, C as CollectionGraph, a as VectorIndexGraph, K as KnowledgeGraph } from './index-DktLSZOc.cjs';
+import { W as WithReplayCacheOptions, F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as canonicalJson, g as fallbackAdapter, w as withReplayCache } from './fallback-Ctlj2tMY.cjs';
+import { E as Extraction, D as DistillBundle, f as DEFAULT_DECAY_RATE } from './decay-2ZukgQ4o.cjs';
+import { G as Graph, a as GraphOptions, i as GraphCheckpointRecord, h as GraphAttachStorageOptions } from './graph-C4SHb3Ly.cjs';
+import { T as TopicGraph } from './index-BTQtTb_H.cjs';
+import { G as GateController, c as GateOptions } from './pipeline-graph-WBlobVhU.cjs';
+import { V as VectorSearchResult, C as CollectionGraph, a as VectorIndexGraph, K as KnowledgeGraph } from './index-2B7u2pVn.cjs';
 import { StorageHandle } from './extra/storage-core.cjs';
 import { SnapshotStorageTier } from './extra/storage-tiers.cjs';
-import { c as GraphSpecCatalog } from './index-C-dkXOpB.cjs';
+import { c as GraphSpecCatalog } from './index-Du7u1lSf.cjs';
 
 /**
  * Observable adapter wrapper — the "inverted statistics" surface.
@@ -939,6 +939,48 @@ declare function llmExtractor<TRaw, TMem>(systemPrompt: string, opts: LLMExtract
  */
 declare function llmConsolidator<TMem>(systemPrompt: string, opts: LLMConsolidatorOptions): (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
 
+/**
+ * `promptNode` — universal LLM transform as a reactive derived node.
+ *
+ * The shape: `deps → messagesNode (derived) → switchMap → call (producer) → output`.
+ * Each upstream wave is one LLM call; superseding waves cancel the in-flight
+ * call via the abort signal threaded through `nodeSignal(opts.abort)`.
+ *
+ * The producer-shape on the inner is load-bearing: it emits exactly one DATA
+ * + COMPLETE per wave, so the outer switchMap sees one DATA per wave (matches
+ * the `HarnessExecutor` contract). A `derived([call], parse)` would have its
+ * own first-run / push-on-subscribe semantics that can leak a transient null
+ * before the real response arrives — observed and reverted in an earlier
+ * attempt; see SESSION-ai-harness-module-review.md line 3654 for context.
+ * Locked as path (b) producer-based by Session C (2026-04-27).
+ *
+ * **Retry / replay-cache.** Stack middleware on the adapter:
+ *
+ * ```ts
+ * import { withRetry, withReplayCache } from "@graphrefly/graphrefly/patterns/ai";
+ *
+ * const adapter = withRetry(
+ *   withReplayCache(baseAdapter, { keyFn: (ctx) => ctx.messages[0].content }),
+ *   { count: 3, backoff: 200 },
+ * );
+ * const result = promptNode(adapter, [input], (q) => q);
+ * ```
+ *
+ * `promptNode` no longer ships `retries` / `cache` options — they duplicated
+ * middleware already at the adapter layer.
+ *
+ * **Cross-wave cache (COMPOSITION-GUIDE §32).** The switchMap output cache
+ * survives across new outer DATAs — `promptNode`'s cached value persists
+ * until the next wave fully resolves. Consumers that need to distinguish
+ * "fresh value for THIS session" from "stale cache from a prior session"
+ * (e.g. `agentLoop` resetting on new `run()`) must add a `state()` mirror
+ * at their session boundary and depend on the mirror, not the `promptNode`
+ * output directly. `promptNode` itself stays primitive — it does not
+ * embed a state-mirror.
+ *
+ * @module
+ */
+
 type PromptNodeOptions = {
     name?: string;
     model?: string;
@@ -954,11 +996,26 @@ type PromptNodeOptions = {
      */
     format?: "text" | "json" | "raw";
     /**
-     * Optional tool definitions forwarded to the adapter. Pair with
+     * Reactive tool definitions forwarded to the adapter. Pair with
      * `format: "raw"` (or read `toolCalls` from a downstream parser) when
      * tool-calling is in scope.
+     *
+     * **Reactive declared edge** (DF12, Tier 7): `tools` is a `Node` so the
+     * tools list participates in `describe()` topology and `explain()` causal
+     * chains. The tools Node is added to `messagesNode`'s declared deps —
+     * tools changes re-invoke the LLM (treated as a new call envelope).
+     * Wrap with `distinctUntilChanged` upstream if your tool selector emits
+     * noisy duplicates that would otherwise spam the adapter. See
+     * COMPOSITION-GUIDE §31 (Dynamic tool selection) for the canonical
+     * `toolSelector` pattern that produces this Node.
+     *
+     * **Activation note:** since `tools` is a real declared dep, `messagesNode`
+     * waits for the tools Node to DATA at least once before firing
+     * (push-on-subscribe SENTINEL gate). Pass a `state<ToolDefinition[]>([])`
+     * if you want immediate activation with no tools, or the latest published
+     * `toolSelector.tools` Node.
      */
-    tools?: readonly ToolDefinition[];
+    tools?: Node<readonly ToolDefinition[]>;
     /**
      * Optional system prompt. Forwarded via `opts.systemPrompt` to the adapter
      * only — never pushed as a `{role:"system"}` message (avoiding the
@@ -982,10 +1039,13 @@ type PromptNodeOptions = {
  *
  * **Topology** (visible in `describe()`):
  * ```
- * <deps...>          → <name>::messages   (derived, meta.ai = prompt_node)
- * <name>::messages   → <name>::output     (switchMap product, meta.ai = prompt_node::output)
- *   per-wave inner:  <name>::call         (producer, meta.ai = prompt_node::call)
+ * <deps...>, [tools?]  → <name>::messages   (derived, meta.ai = prompt_node)
+ * <name>::messages     → <name>::output     (switchMap product, meta.ai = prompt_node::output)
+ *   per-wave inner:    <name>::call         (producer, meta.ai = prompt_node::call)
  * ```
+ * When `opts.tools` is supplied, the tools `Node` is appended to
+ * `messagesNode`'s declared deps so it appears as a real edge in `describe()`
+ * / `explain()` (DF12, Tier 7).
  *
  * **No-input semantics** (matches the codebase-wide SENTINEL convention):
  * - **Initial no-input** (no real input has ever arrived) — emits nothing.
@@ -1390,6 +1450,77 @@ declare class ChatStreamGraph extends Graph {
 }
 declare function chatStream(name: string, opts?: ChatStreamOptions): ChatStreamGraph;
 
+/**
+ * Options for {@link handoff}.
+ */
+type HandoffOptions = {
+    /**
+     * Reactive gate: when this node's value is `true`, output flows from
+     * `from` to the `to` specialist; when `false`, `from`'s output flows
+     * through unchanged and `to` stays dormant. Omit to always hand off —
+     * useful when `from` is itself a router whose output shape already
+     * encodes routing intent.
+     */
+    condition?: NodeInput<boolean>;
+    name?: string;
+};
+/**
+ * Multi-agent handoff recipe — route `from`'s output into a specialist
+ * agent `toFactory` when `condition` is open. Thin composition over
+ * `switchMap` + gate; not a new primitive, just a named shape.
+ *
+ * The "handoff" pattern (popularized by the OpenAI Agents SDK) covers two
+ * idioms:
+ *
+ * 1. **Full handoff** — a triage agent routes the conversation to a
+ *    specialist, and the specialist becomes the active agent for the rest
+ *    of the turn. Accumulated context (memory, tool definitions) can travel
+ *    along by threading the same `agentMemory` bundle into both.
+ * 2. **Agents-as-tools** — the manager keeps control and calls the
+ *    specialist like a tool for a bounded subtask. Build this by registering
+ *    a `promptNode` instance as a `ToolDefinition` on the parent via
+ *    `toolRegistry`.
+ *
+ * This sugar covers (1) — a reactive route from one agent's output into a
+ * specialist factory. For (2) wire a tool registry manually; the pattern is
+ * additive with this one.
+ *
+ * @example Full handoff on a triage signal.
+ * ```ts
+ * import { handoff, promptNode } from "@graphrefly/graphrefly/patterns/ai";
+ *
+ * const triage = promptNode(adapter, [userMessage], (msg) =>
+ *   `Classify urgency of: ${msg}. Reply "high" or "normal".`);
+ * const isUrgent = derived([triage], ([v]) => v === "high");
+ *
+ * const specialist = handoff(
+ *   userMessage,
+ *   (input) => promptNode(specialistAdapter, [input], (m) => `Respond urgently: ${m}`),
+ *   { condition: isUrgent },
+ * );
+ * ```
+ *
+ * @param from - Source node whose value is threaded into the specialist.
+ * @param toFactory - Factory that takes `from` (as a reactive source) and
+ *   returns the specialist node. Called once, lazily, when the first
+ *   subscriber activates.
+ * @param opts - Optional reactive `condition` gate + name.
+ * @returns Node emitting the specialist's output when the gate is open, or
+ *   `from`'s value when the gate is closed. Null when `from` is null.
+ *
+ * **Performance caveat (Wave A Unit 5):** the specialist is mounted per
+ * source emission — each `v != null` DATA on `from` allocates a fresh
+ * `state<T>(v)` + invokes `toFactory`, and switchMap cancels the prior
+ * branch. For per-turn routing (≤1 emit/sec) this is negligible. For
+ * high-frequency sources (per-token routing, tight event loops), batch
+ * upstream (e.g. via `audit`, `throttle`, or `distinctUntilChanged`) before
+ * handing off — each mount/unmount cycle spins up full subgraphs
+ * (`messagesNode` + adapter bridge + output for a `promptNode` specialist).
+ *
+ * @category patterns.ai
+ */
+declare function handoff<T>(from: NodeInput<T | null>, toFactory: (input: Node<T>) => Node<T | null>, opts?: HandoffOptions): Node<T | null>;
+
 type ToolRegistryOptions = {
     graph?: GraphOptions;
 };
@@ -1527,258 +1658,50 @@ type ToolExecutionOptions = {
 declare function toolExecution(opts: ToolExecutionOptions): Node<readonly ToolResult[]>;
 
 /**
- * Reactive agent loop — autonomous multi-turn LLM agent with tool execution.
+ * Options for {@link toolSelector}.
  */
-type AgentLoopStatus = "idle" | "thinking" | "acting" | "done" | "error";
-
-type AgentLoopOptions = {
-    graph?: GraphOptions;
-    adapter: LLMAdapter;
-    tools?: readonly ToolDefinition[];
-    systemPrompt?: string;
-    maxTurns?: number;
-    stopWhen?: (response: LLMResponse) => boolean;
-    onToolCall?: (call: ToolCall) => void;
-    maxMessages?: number;
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-    /**
-     * Reactive tool-call splice (COMPOSITION-GUIDE §31 "interception is security").
-     * When set, the raw `toolCalls` node is piped through this transform before
-     * reaching the executor. The transform is a pure reactive composition —
-     * `(calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>` — so the
-     * gate is visible in `describe()` / `explain()` as a real edge (no hidden
-     * imperative wraps; §24).
-     *
-     * Typical uses:
-     * - **Filter / block** — `derived([calls, policy], ([raw, p]) => raw.filter(p))`
-     * - **Throttle / debounce** — `throttle(calls, windowMs)`
-     * - **Human-in-the-loop approval** — pipe through a `gate` controller so
-     *   calls wait for human approval before reaching the executor.
-     *
-     * The public `agent.toolCalls` node surfaces the POST-intercept stream, so
-     * audit / telemetry consumers see what the executor actually runs. The raw
-     * pre-intercept stream is not exposed — tests that need it should run
-     * without `interceptToolCalls` set (the identity case).
-     */
-    interceptToolCalls?: (calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>;
-};
+interface ToolSelectorOptions {
+    readonly name?: string;
+}
 /**
- * Reactive agent loop.
- *
- * The loop is a reactive state machine wired entirely from graph primitives:
- * `chat.messages` + `tools.schemas` + gating state feed a `promptInput`
- * derived; `switchMap` turns non-null inputs into an LLM invocation via
- * `fromAny(adapter.invoke(...))`. The LLM response drives chat writes and
- * status transitions via effects. Tool calls flow through a reactive
- * executor (`retrySource` + `rescue`) that retries once on error and
- * surfaces terminal errors as JSON-shaped `ToolResult` payloads for the
- * LLM to react to.
+ * Reactive tool availability (COMPOSITION-GUIDE §31). Given a base tool set
+ * (reactive or static) and one or more reactive predicates, emit the filtered
+ * subset of tools currently allowed. Feeds into `promptNode({ tools: Node<...> })`
+ * so the LLM sees a reactive menu instead of a frozen config.
  *
- * **No imperative control flow inside the reactive layer** (spec §5.8-5.12):
- * no `while` loops, no manual `await adapter.invoke`, no polling.
- * `agent.run()` is a thin `awaitSettled` bridge so callers can still `await`
- * the loop if they want a Promise.
+ * Each predicate is a `NodeInput<(tool) => boolean>`. A tool is included iff
+ * **every** predicate returns `true`. When any predicate value is `null` /
+ * `undefined` (e.g. upstream not yet ready) that predicate is treated as a
+ * pass-through — the tool isn't excluded on its basis. Predicate updates
+ * recompute the selected set.
  *
- * Public surface:
- * - `chat` / `tools` — subgraphs (imperative `append` at boundary, reactive `executeReactive` for tool invocation)
- * - `status` / `turn` / `aborted` — state nodes with explicit initials
- * - `lastResponse` / `toolCalls` / `toolResults` — reactive outputs (SENTINEL until first emission; callers use `awaitSettled` / `subscribe`)
- * - `run(userMessage?, signal?)` — optional user append + Promise bridge
- * - `abort()` — imperative abort shim; flips `aborted` state
+ * Pairs with `toolInterceptor` (§D9 / §31): **selection** controls what's
+ * offered to the LLM (pre-generation UX); **interception** gates what's
+ * executed after the LLM chooses (post-generation security). Tool selection
+ * is NOT a security boundary — an LLM can hallucinate tool calls outside
+ * its offered set; always pair with `toolInterceptor` for enforcement.
  *
- * **Lifecycle: single-mount.** `AgentLoopGraph` instances expect to be
- * constructed once and used until `destroy()`. The internal closure mirrors
- * (`latestTurn` / `latestAborted` / `latestStatus` / `latestMessages` /
- * `latestSchemas`) are wired by subscribe-and-capture at construction time;
- * their corresponding `addDisposer`-registered subscriptions are torn down
- * on subgraph unmount or `destroy()`. After teardown the mirrors freeze at
- * their last value, so re-using a destroyed instance — calling `run()`
- * again, or remounting under a new parent — would silently feed stale
- * mirror data into `promptInput`. If you need to "reset" an agent, build a
- * fresh `AgentLoopGraph` instance instead of recycling.
+ * @example
+ * ```ts
+ * const hasBudget = derived([costMeter], (c) => c.total < BUDGET);
+ * const canDestroy = state(false, { name: "destructive-allowed" });
+ * const tools = toolSelector(registry.schemas, [
+ *   derived([hasBudget], (b) => (t) => !t.meta?.expensive || b === true),
+ *   derived([canDestroy], (c) => (t) => !t.meta?.destructive || c === true),
+ * ]);
+ * const agent = promptNode(graph, "agent", { ..., tools });
+ * ```
  */
-declare class AgentLoopGraph extends Graph {
-    readonly chat: ChatStreamGraph;
-    readonly tools: ToolRegistryGraph;
-    /** Current agent status. `initial: "idle"` — always has a real value. */
-    readonly status: Node<AgentLoopStatus>;
-    /** Turn count (completed LLM invocations this run). `initial: 0`. */
-    readonly turn: Node<number>;
-    /** Aborted flag; flipped by `abort()` or external `AbortSignal`. `initial: false`. */
-    readonly aborted: Node<boolean>;
-    /**
-     * Most recent LLM response. State-backed mirror driven by the response
-     * effect. `initial: null` — subscribers can read the cache synchronously;
-     * `awaitSettled(lastResponse)` or `firstWhere(lastResponse, v => v != null)`
-     * bridges to the first non-null value as a Promise.
-     */
-    readonly lastResponse: Node<LLMResponse | null>;
-    /** Tool-call batch emitted by the most recent LLM response. SENTINEL. */
-    readonly toolCalls: Node<readonly ToolCall[]>;
-    /** Tool-result batch (one entry per call) after reactive execution. SENTINEL. */
-    readonly toolResults: Node<readonly ToolResult[]>;
-    private readonly _terminalResult;
-    private readonly _disposeRunWiring;
-    /** Guards against overlapping `run()` calls. */
-    private _running;
-    /**
-     * Abort controller for the currently-running `adapter.invoke`. Minted per
-     * switchMap project; aborted when the reactive `aborted` node flips true
-     * OR when the caller's external `AbortSignal` fires. Threaded into
-     * `adapter.invoke({ signal })` AND `fromAny(promise, { signal })`, so the
-     * reactive layer sees ERROR when the wire call is cancelled.
-     */
-    private _currentAbortController;
-    constructor(name: string, opts: AgentLoopOptions);
-    /**
-     * Bridge to `Promise<LLMResponse>` over the reactive pipeline.
-     *
-     * - If `userMessage` is provided, appends it as a user message and
-     *   transitions status to `"thinking"` to kick the loop.
-     * - If `signal` is provided, binds it to the reactive `aborted` node
-     *   AND threads into `adapter.invoke({ signal })` so the wire call can
-     *   cancel mid-flight. The reactive `aborted` state + effect 3 guarantee
-     *   that even an adapter that ignores `signal` will stop emitting into
-     *   the agent graph.
-     * - Resolves when `status === "done"` with the final LLM response.
-     *   Rejects with `AbortError` when the abort signal fires pre-response.
-     *   Rejects with the stage error when `status === "error"`.
-     *
-     * **Concurrency:** `run()` refuses to overlap with a pending call on the
-     * same agent. Attempting to call `run()` while a previous `run()` is
-     * still in-flight throws a `RangeError` immediately. Stale-resolution
-     * safety is provided by `awaitSettled({skipCurrent: true})`, which
-     * ignores the cached initial DATA from any previous run and resolves
-     * only on a fresh post-subscribe emission of `_terminalResult`.
-     */
-    run(userMessage?: string, signal?: AbortSignal): Promise<LLMResponse | null>;
-    /**
-     * Flip the reactive `aborted` state. Equivalent to setting an external
-     * `AbortSignal` — the pipeline observes and transitions to `"done"`.
-     */
-    abort(): void;
-    destroy(): void;
-}
-declare function agentLoop(name: string, opts: AgentLoopOptions): AgentLoopGraph;
+declare function toolSelector(allTools: NodeInput<readonly ToolDefinition[]>, constraints: readonly NodeInput<(tool: ToolDefinition) => boolean>[], opts?: ToolSelectorOptions): Node<readonly ToolDefinition[]>;
 
-/**
- * Options for {@link handoff}.
- */
-type HandoffOptions = {
-    /**
-     * Reactive gate: when this node's value is `true`, output flows from
-     * `from` to the `to` specialist; when `false`, `from`'s output flows
-     * through unchanged and `to` stays dormant. Omit to always hand off —
-     * useful when `from` is itself a router whose output shape already
-     * encodes routing intent.
-     */
-    condition?: NodeInput<boolean>;
-    name?: string;
-};
-/**
- * Multi-agent handoff recipe — route `from`'s output into a specialist
- * agent `toFactory` when `condition` is open. Thin composition over
- * `switchMap` + gate; not a new primitive, just a named shape.
- *
- * The "handoff" pattern (popularized by the OpenAI Agents SDK) covers two
- * idioms:
- *
- * 1. **Full handoff** — a triage agent routes the conversation to a
- *    specialist, and the specialist becomes the active agent for the rest
- *    of the turn. Accumulated context (memory, tool definitions) can travel
- *    along by threading the same `agentMemory` bundle into both.
- * 2. **Agents-as-tools** — the manager keeps control and calls the
- *    specialist like a tool for a bounded subtask. Build this by registering
- *    a `promptNode` instance as a `ToolDefinition` on the parent via
- *    `toolRegistry`.
- *
- * This sugar covers (1) — a reactive route from one agent's output into a
- * specialist factory. For (2) wire a tool registry manually; the pattern is
- * additive with this one.
- *
- * @example Full handoff on a triage signal.
- * ```ts
- * import { handoff, promptNode } from "@graphrefly/graphrefly/patterns/ai";
- *
- * const triage = promptNode(adapter, [userMessage], (msg) =>
- *   `Classify urgency of: ${msg}. Reply "high" or "normal".`);
- * const isUrgent = derived([triage], ([v]) => v === "high");
- *
- * const specialist = handoff(
- *   userMessage,
- *   (input) => promptNode(specialistAdapter, [input], (m) => `Respond urgently: ${m}`),
- *   { condition: isUrgent },
- * );
- * ```
- *
- * @param from - Source node whose value is threaded into the specialist.
- * @param toFactory - Factory that takes `from` (as a reactive source) and
- *   returns the specialist node. Called once, lazily, when the first
- *   subscriber activates.
- * @param opts - Optional reactive `condition` gate + name.
- * @returns Node emitting the specialist's output when the gate is open, or
- *   `from`'s value when the gate is closed. Null when `from` is null.
- *
- * **Performance caveat (Wave A Unit 5):** the specialist is mounted per
- * source emission — each `v != null` DATA on `from` allocates a fresh
- * `state<T>(v)` + invokes `toFactory`, and switchMap cancels the prior
- * branch. For per-turn routing (≤1 emit/sec) this is negligible. For
- * high-frequency sources (per-token routing, tight event loops), batch
- * upstream (e.g. via `audit`, `throttle`, or `distinctUntilChanged`) before
- * handing off — each mount/unmount cycle spins up full subgraphs
- * (`messagesNode` + adapter bridge + output for a `promptNode` specialist).
- *
- * @category patterns.ai
- */
-declare function handoff<T>(from: NodeInput<T | null>, toFactory: (input: Node<T>) => Node<T | null>, opts?: HandoffOptions): Node<T | null>;
-
-/**
- * Options for {@link toolSelector}.
- */
-interface ToolSelectorOptions {
-    readonly name?: string;
-}
-/**
- * Reactive tool availability (COMPOSITION-GUIDE §31). Given a base tool set
- * (reactive or static) and one or more reactive predicates, emit the filtered
- * subset of tools currently allowed. Feeds into `promptNode({ tools: Node<...> })`
- * so the LLM sees a reactive menu instead of a frozen config.
- *
- * Each predicate is a `NodeInput<(tool) => boolean>`. A tool is included iff
- * **every** predicate returns `true`. When any predicate value is `null` /
- * `undefined` (e.g. upstream not yet ready) that predicate is treated as a
- * pass-through — the tool isn't excluded on its basis. Predicate updates
- * recompute the selected set.
- *
- * Pairs with `toolInterceptor` (§D9 / §31): **selection** controls what's
- * offered to the LLM (pre-generation UX); **interception** gates what's
- * executed after the LLM chooses (post-generation security). Tool selection
- * is NOT a security boundary — an LLM can hallucinate tool calls outside
- * its offered set; always pair with `toolInterceptor` for enforcement.
- *
- * @example
- * ```ts
- * const hasBudget = derived([costMeter], (c) => c.total < BUDGET);
- * const canDestroy = state(false, { name: "destructive-allowed" });
- * const tools = toolSelector(registry.schemas, [
- *   derived([hasBudget], (b) => (t) => !t.meta?.expensive || b === true),
- *   derived([canDestroy], (c) => (t) => !t.meta?.destructive || c === true),
- * ]);
- * const agent = promptNode(graph, "agent", { ..., tools });
- * ```
- */
-declare function toolSelector(allTools: NodeInput<readonly ToolDefinition[]>, constraints: readonly NodeInput<(tool: ToolDefinition) => boolean>[], opts?: ToolSelectorOptions): Node<readonly ToolDefinition[]>;
-
-/** Generic per-dimension thresholds. Any dim below its threshold → reject. */
-type AdmissionThresholds<Dims extends string> = Partial<Record<Dims, number>>;
-type AdmissionScoredOptions<Dims extends string, TRaw = unknown> = {
-    /** Score function — must return a finite number for every dimension named in `thresholds`. */
-    scoreFn: (raw: TRaw) => Readonly<Record<Dims, number>>;
-    /** Per-dim minimums. Dims absent here are scored but not gated. */
-    thresholds?: AdmissionThresholds<Dims>;
-};
+/** Generic per-dimension thresholds. Any dim below its threshold → reject. */
+type AdmissionThresholds<Dims extends string> = Partial<Record<Dims, number>>;
+type AdmissionScoredOptions<Dims extends string, TRaw = unknown> = {
+    /** Score function — must return a finite number for every dimension named in `thresholds`. */
+    scoreFn: (raw: TRaw) => Readonly<Record<Dims, number>>;
+    /** Per-dim minimums. Dims absent here are scored but not gated. */
+    thresholds?: AdmissionThresholds<Dims>;
+};
 /**
  * Generic N-dimension admission filter. Rejects any input where one of the
  * configured threshold dimensions scores below its minimum. Missing scores
@@ -1919,6 +1842,262 @@ type MemoryTiersBundle<TMem> = {
     markPermanent: (key: string, value: TMem) => void;
 };
 
+type MemoryWithVectorsOptions<TMem> = {
+    /** Embedding dimension. Must match the `embedFn` output length. */
+    dimension: number;
+    /** Extract an embedding vector for a memory entry. */
+    embedFn: (mem: TMem) => readonly number[] | undefined;
+};
+/**
+ * Attach a vector index to a `DistillBundle`. Indexes every entry in the
+ * store as it changes. Returns the `VectorIndexGraph` so retrieval can read
+ * its `entries` and call `search()`.
+ *
+ * The indexer's keepalive is registered with `graph.addDisposer` so it tears
+ * down on `graph.destroy()`. The returned `dispose()` is also available for
+ * early release without destroying the parent graph.
+ */
+declare function memoryWithVectors<TMem>(graph: Graph, store: DistillBundle<TMem>, opts: MemoryWithVectorsOptions<TMem>): {
+    vectors: VectorIndexGraph<TMem>;
+    dispose: () => void;
+};
+type MemoryWithKGOptions<TMem> = {
+    /**
+     * Mount path for the KG subgraph on the parent graph. Defaults to `name`.
+     * Pass a different value when the parent graph reserves a stable mount
+     * path (e.g. `agentMemory` mounts at `"kg"` regardless of outer name).
+     */
+    mountPath?: string;
+    /**
+     * Extract entities + relations for a memory entry. Omit to mount an empty
+     * KG without an indexer effect — caller upserts entities / relations
+     * directly on the returned `kg` handle.
+     */
+    entityFn?: (key: string, mem: TMem) => {
+        entities?: Array<{
+            id: string;
+            value: unknown;
+        }>;
+        relations?: Array<{
+            from: string;
+            to: string;
+            relation: string;
+            weight?: number;
+        }>;
+    } | undefined;
+};
+/**
+ * Attach a knowledge graph alongside a `DistillBundle`. Inner graph is named
+ * `${name}-kg`; mount path defaults to `name` but can be overridden via
+ * `opts.mountPath` so a parent factory (e.g. `agentMemory`) can keep a stable
+ * mount path independent of the inner graph's identity.
+ *
+ * If `opts.entityFn` is omitted, no indexer effect is wired — the empty KG is
+ * mounted for manual `upsertEntity` / `link` use.
+ *
+ * Indexer keepalive (when present) is registered with `graph.addDisposer`;
+ * explicit `dispose()` is also available.
+ */
+declare function memoryWithKG<TMem>(graph: Graph, store: DistillBundle<TMem>, name: string, opts: MemoryWithKGOptions<TMem>): {
+    kg: KnowledgeGraph<unknown, string>;
+    dispose: () => void;
+};
+type MemoryWithTiersOptions<TMem> = MemoryTiersOptions<TMem> & {
+    /** Score function — same signature as `agentMemory.score`. */
+    score: (mem: TMem, context: unknown) => number;
+    /** Optional reactive context node (passed to `score`). */
+    context?: NodeInput<unknown>;
+};
+/**
+ * Attach 3-tier storage (active / archived / permanent) to a `DistillBundle`.
+ * Wires a `tierClassifier` effect that:
+ * - Promotes entries matching `permanentFilter` into the permanent tier.
+ * - Archives entries whose decayed score falls below `archiveThreshold`.
+ * - Caps the active tier at `maxActive`, evicting lowest-scored on overflow.
+ *
+ * **Closure state caveat (Unit 7 Q3 deferred):** `permanentKeys` +
+ * `entryCreatedAtNs` are still closure-held for now; promotion to reactive
+ * nodes is tracked in `docs/optimizations.md`.
+ */
+declare function memoryWithTiers<TMem>(graph: Graph, store: DistillBundle<TMem>, opts: MemoryWithTiersOptions<TMem>): {
+    tiers: MemoryTiersBundle<TMem>;
+    dispose: () => void;
+};
+type MemoryRetrievalOptions<TMem> = {
+    /** Score function (same shape as `agentMemory.score`). */
+    score: (mem: TMem, context: unknown) => number;
+    /** Cost function for budget packing. */
+    cost: (mem: TMem) => number;
+    /** Token / cost budget. Default 2000. */
+    budget?: number;
+    /** Top-K vector candidates. Default 20. */
+    topK?: number;
+    /** KG expansion depth in hops. Default 1. */
+    graphDepth?: number;
+    /** Hierarchical-context boost weight. Default 0. */
+    contextWeight?: number;
+    /** Hierarchical-context accessor for entries. */
+    contextOf?: (mem: TMem) => readonly string[] | undefined;
+    /** Optional reactive context node (passed to `score`). */
+    context?: NodeInput<unknown>;
+};
+type MemoryRetrievalBundle<TMem> = {
+    /** State node mirroring the latest packed retrieval result. */
+    readonly retrieval: Node<ReadonlyArray<RetrievalEntry<TMem>>>;
+    /** State node mirroring the latest retrieval trace. */
+    readonly retrievalTrace: Node<RetrievalTrace<TMem> | null>;
+    /** Imperative consumer API — synchronous; reads cache at call time. */
+    readonly retrieve: (query: RetrievalQuery) => ReadonlyArray<RetrievalEntry<TMem>>;
+    /** Reactive sibling — chain into the graph. Mirrors observability state. */
+    readonly retrieveReactive: (queryInput: NodeInput<RetrievalQuery | null>) => Node<ReadonlyArray<RetrievalEntry<TMem>>>;
+};
+/**
+ * Build the retrieval pipeline (vector + KG + budget packing) over a
+ * `DistillBundle` and optional `vectors` / `kg` bundles.
+ *
+ * Both consumer surfaces (`retrieve`, `retrieveReactive`) write to the same
+ * `retrieval` + `retrievalTrace` state nodes — observers subscribed to those
+ * see ALL queries regardless of which API issued them.
+ */
+declare function memoryRetrieval<TMem>(graph: Graph, store: DistillBundle<TMem>, vectors: VectorIndexGraph<TMem> | null, kg: KnowledgeGraph<unknown, string> | null, opts: MemoryRetrievalOptions<TMem>): MemoryRetrievalBundle<TMem>;
+
+/**
+ * Reactive agent loop — autonomous multi-turn LLM agent with tool execution.
+ */
+type AgentLoopStatus = "idle" | "thinking" | "acting" | "done" | "error";
+
+type AgentLoopOptions = {
+    graph?: GraphOptions;
+    adapter: LLMAdapter;
+    tools?: readonly ToolDefinition[];
+    systemPrompt?: string;
+    maxTurns?: number;
+    stopWhen?: (response: LLMResponse) => boolean;
+    onToolCall?: (call: ToolCall) => void;
+    maxMessages?: number;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Reactive tool-call splice (COMPOSITION-GUIDE §31 "interception is security").
+     * When set, the raw `toolCalls` node is piped through this transform before
+     * reaching the executor. The transform is a pure reactive composition —
+     * `(calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>` — so the
+     * gate is visible in `describe()` / `explain()` as a real edge (no hidden
+     * imperative wraps; §24).
+     *
+     * Typical uses:
+     * - **Filter / block** — `derived([calls, policy], ([raw, p]) => raw.filter(p))`
+     * - **Throttle / debounce** — `throttle(calls, windowMs)`
+     * - **Human-in-the-loop approval** — pipe through a `gate` controller so
+     *   calls wait for human approval before reaching the executor.
+     *
+     * The public `agent.toolCalls` node surfaces the POST-intercept stream, so
+     * audit / telemetry consumers see what the executor actually runs. The raw
+     * pre-intercept stream is not exposed — tests that need it should run
+     * without `interceptToolCalls` set (the identity case).
+     */
+    interceptToolCalls?: (calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>;
+};
+/**
+ * Reactive agent loop.
+ *
+ * The loop is a reactive state machine wired entirely from graph primitives:
+ * `chat.messages` + `tools.schemas` + gating state feed a `promptInput`
+ * derived; `switchMap` turns non-null inputs into an LLM invocation via
+ * `fromAny(adapter.invoke(...))`. The LLM response drives chat writes and
+ * status transitions via effects. Tool calls flow through a reactive
+ * executor (`retrySource` + `rescue`) that retries once on error and
+ * surfaces terminal errors as JSON-shaped `ToolResult` payloads for the
+ * LLM to react to.
+ *
+ * **No imperative control flow inside the reactive layer** (spec §5.8-5.12):
+ * no `while` loops, no manual `await adapter.invoke`, no polling.
+ * `agent.run()` is a thin `awaitSettled` bridge so callers can still `await`
+ * the loop if they want a Promise.
+ *
+ * Public surface:
+ * - `chat` / `tools` — subgraphs (imperative `append` at boundary, reactive `executeReactive` for tool invocation)
+ * - `status` / `turn` / `aborted` — state nodes with explicit initials
+ * - `lastResponse` / `toolCalls` / `toolResults` — reactive outputs (SENTINEL until first emission; callers use `awaitSettled` / `subscribe`)
+ * - `run(userMessage?, signal?)` — optional user append + Promise bridge
+ * - `abort()` — imperative abort shim; flips `aborted` state
+ *
+ * **Lifecycle: single-mount.** `AgentLoopGraph` instances expect to be
+ * constructed once and used until `destroy()`. The internal closure mirrors
+ * (`latestTurn` / `latestAborted` / `latestStatus` / `latestMessages` /
+ * `latestSchemas`) are wired by subscribe-and-capture at construction time;
+ * their corresponding `addDisposer`-registered subscriptions are torn down
+ * on subgraph unmount or `destroy()`. After teardown the mirrors freeze at
+ * their last value, so re-using a destroyed instance — calling `run()`
+ * again, or remounting under a new parent — would silently feed stale
+ * mirror data into `promptInput`. If you need to "reset" an agent, build a
+ * fresh `AgentLoopGraph` instance instead of recycling.
+ */
+declare class AgentLoopGraph extends Graph {
+    readonly chat: ChatStreamGraph;
+    readonly tools: ToolRegistryGraph;
+    /** Current agent status. `initial: "idle"` — always has a real value. */
+    readonly status: Node<AgentLoopStatus>;
+    /** Turn count (completed LLM invocations this run). `initial: 0`. */
+    readonly turn: Node<number>;
+    /** Aborted flag; flipped by `abort()` or external `AbortSignal`. `initial: false`. */
+    readonly aborted: Node<boolean>;
+    /**
+     * Most recent LLM response. State-backed mirror driven by the response
+     * effect. `initial: null` — subscribers can read the cache synchronously;
+     * `awaitSettled(lastResponse)` or `firstWhere(lastResponse, v => v != null)`
+     * bridges to the first non-null value as a Promise.
+     */
+    readonly lastResponse: Node<LLMResponse | null>;
+    /** Tool-call batch emitted by the most recent LLM response. SENTINEL. */
+    readonly toolCalls: Node<readonly ToolCall[]>;
+    /** Tool-result batch (one entry per call) after reactive execution. SENTINEL. */
+    readonly toolResults: Node<readonly ToolResult[]>;
+    private readonly _terminalResult;
+    private readonly _disposeRunWiring;
+    /** Guards against overlapping `run()` calls. */
+    private _running;
+    /**
+     * Abort controller for the currently-running `adapter.invoke`. Minted per
+     * switchMap project; aborted when the reactive `aborted` node flips true
+     * OR when the caller's external `AbortSignal` fires. Threaded into
+     * `adapter.invoke({ signal })` AND `fromAny(promise, { signal })`, so the
+     * reactive layer sees ERROR when the wire call is cancelled.
+     */
+    private _currentAbortController;
+    constructor(name: string, opts: AgentLoopOptions);
+    /**
+     * Bridge to `Promise<LLMResponse>` over the reactive pipeline.
+     *
+     * - If `userMessage` is provided, appends it as a user message and
+     *   transitions status to `"thinking"` to kick the loop.
+     * - If `signal` is provided, binds it to the reactive `aborted` node
+     *   AND threads into `adapter.invoke({ signal })` so the wire call can
+     *   cancel mid-flight. The reactive `aborted` state + effect 3 guarantee
+     *   that even an adapter that ignores `signal` will stop emitting into
+     *   the agent graph.
+     * - Resolves when `status === "done"` with the final LLM response.
+     *   Rejects with `AbortError` when the abort signal fires pre-response.
+     *   Rejects with the stage error when `status === "error"`.
+     *
+     * **Concurrency:** `run()` refuses to overlap with a pending call on the
+     * same agent. Attempting to call `run()` while a previous `run()` is
+     * still in-flight throws a `RangeError` immediately. Stale-resolution
+     * safety is provided by `awaitSettled({skipCurrent: true})`, which
+     * ignores the cached initial DATA from any previous run and resolves
+     * only on a fresh post-subscribe emission of `_terminalResult`.
+     */
+    run(userMessage?: string, signal?: AbortSignal): Promise<LLMResponse | null>;
+    /**
+     * Flip the reactive `aborted` state. Equivalent to setting an external
+     * `AbortSignal` — the pipeline observes and transitions to `"done"`.
+     */
+    abort(): void;
+    destroy(): void;
+}
+declare function agentLoop(name: string, opts: AgentLoopOptions): AgentLoopGraph;
+
 type AgentMemoryOptions<TMem = unknown> = {
     graph?: GraphOptions;
     /** LLM adapter for extraction and consolidation. */
@@ -2046,125 +2225,6 @@ type AgentMemoryGraph<TMem = unknown> = Graph & {
  */
 declare function agentMemory<TMem = unknown>(name: string, source: NodeInput<unknown>, opts: AgentMemoryOptions<TMem>): AgentMemoryGraph<TMem>;
 
-type MemoryWithVectorsOptions<TMem> = {
-    /** Embedding dimension. Must match the `embedFn` output length. */
-    dimension: number;
-    /** Extract an embedding vector for a memory entry. */
-    embedFn: (mem: TMem) => readonly number[] | undefined;
-};
-/**
- * Attach a vector index to a `DistillBundle`. Indexes every entry in the
- * store as it changes. Returns the `VectorIndexGraph` so retrieval can read
- * its `entries` and call `search()`.
- *
- * The indexer's keepalive is registered with `graph.addDisposer` so it tears
- * down on `graph.destroy()`. The returned `dispose()` is also available for
- * early release without destroying the parent graph.
- */
-declare function memoryWithVectors<TMem>(graph: Graph, store: DistillBundle<TMem>, opts: MemoryWithVectorsOptions<TMem>): {
-    vectors: VectorIndexGraph<TMem>;
-    dispose: () => void;
-};
-type MemoryWithKGOptions<TMem> = {
-    /**
-     * Mount path for the KG subgraph on the parent graph. Defaults to `name`.
-     * Pass a different value when the parent graph reserves a stable mount
-     * path (e.g. `agentMemory` mounts at `"kg"` regardless of outer name).
-     */
-    mountPath?: string;
-    /**
-     * Extract entities + relations for a memory entry. Omit to mount an empty
-     * KG without an indexer effect — caller upserts entities / relations
-     * directly on the returned `kg` handle.
-     */
-    entityFn?: (key: string, mem: TMem) => {
-        entities?: Array<{
-            id: string;
-            value: unknown;
-        }>;
-        relations?: Array<{
-            from: string;
-            to: string;
-            relation: string;
-            weight?: number;
-        }>;
-    } | undefined;
-};
-/**
- * Attach a knowledge graph alongside a `DistillBundle`. Inner graph is named
- * `${name}-kg`; mount path defaults to `name` but can be overridden via
- * `opts.mountPath` so a parent factory (e.g. `agentMemory`) can keep a stable
- * mount path independent of the inner graph's identity.
- *
- * If `opts.entityFn` is omitted, no indexer effect is wired — the empty KG is
- * mounted for manual `upsertEntity` / `link` use.
- *
- * Indexer keepalive (when present) is registered with `graph.addDisposer`;
- * explicit `dispose()` is also available.
- */
-declare function memoryWithKG<TMem>(graph: Graph, store: DistillBundle<TMem>, name: string, opts: MemoryWithKGOptions<TMem>): {
-    kg: KnowledgeGraph<unknown, string>;
-    dispose: () => void;
-};
-type MemoryWithTiersOptions<TMem> = MemoryTiersOptions<TMem> & {
-    /** Score function — same signature as `agentMemory.score`. */
-    score: (mem: TMem, context: unknown) => number;
-    /** Optional reactive context node (passed to `score`). */
-    context?: NodeInput<unknown>;
-};
-/**
- * Attach 3-tier storage (active / archived / permanent) to a `DistillBundle`.
- * Wires a `tierClassifier` effect that:
- * - Promotes entries matching `permanentFilter` into the permanent tier.
- * - Archives entries whose decayed score falls below `archiveThreshold`.
- * - Caps the active tier at `maxActive`, evicting lowest-scored on overflow.
- *
- * **Closure state caveat (Unit 7 Q3 deferred):** `permanentKeys` +
- * `entryCreatedAtNs` are still closure-held for now; promotion to reactive
- * nodes is tracked in `docs/optimizations.md`.
- */
-declare function memoryWithTiers<TMem>(graph: Graph, store: DistillBundle<TMem>, opts: MemoryWithTiersOptions<TMem>): {
-    tiers: MemoryTiersBundle<TMem>;
-    dispose: () => void;
-};
-type MemoryRetrievalOptions<TMem> = {
-    /** Score function (same shape as `agentMemory.score`). */
-    score: (mem: TMem, context: unknown) => number;
-    /** Cost function for budget packing. */
-    cost: (mem: TMem) => number;
-    /** Token / cost budget. Default 2000. */
-    budget?: number;
-    /** Top-K vector candidates. Default 20. */
-    topK?: number;
-    /** KG expansion depth in hops. Default 1. */
-    graphDepth?: number;
-    /** Hierarchical-context boost weight. Default 0. */
-    contextWeight?: number;
-    /** Hierarchical-context accessor for entries. */
-    contextOf?: (mem: TMem) => readonly string[] | undefined;
-    /** Optional reactive context node (passed to `score`). */
-    context?: NodeInput<unknown>;
-};
-type MemoryRetrievalBundle<TMem> = {
-    /** State node mirroring the latest packed retrieval result. */
-    readonly retrieval: Node<ReadonlyArray<RetrievalEntry<TMem>>>;
-    /** State node mirroring the latest retrieval trace. */
-    readonly retrievalTrace: Node<RetrievalTrace<TMem> | null>;
-    /** Imperative consumer API — synchronous; reads cache at call time. */
-    readonly retrieve: (query: RetrievalQuery) => ReadonlyArray<RetrievalEntry<TMem>>;
-    /** Reactive sibling — chain into the graph. Mirrors observability state. */
-    readonly retrieveReactive: (queryInput: NodeInput<RetrievalQuery | null>) => Node<ReadonlyArray<RetrievalEntry<TMem>>>;
-};
-/**
- * Build the retrieval pipeline (vector + KG + budget packing) over a
- * `DistillBundle` and optional `vectors` / `kg` bundles.
- *
- * Both consumer surfaces (`retrieve`, `retrieveReactive`) write to the same
- * `retrieval` + `retrievalTrace` state nodes — observers subscribed to those
- * see ALL queries regardless of which API issued them.
- */
-declare function memoryRetrieval<TMem>(graph: Graph, store: DistillBundle<TMem>, vectors: VectorIndexGraph<TMem> | null, kg: KnowledgeGraph<unknown, string> | null, opts: MemoryRetrievalOptions<TMem>): MemoryRetrievalBundle<TMem>;
-
 type GaugesAsContextOptions = {
     /** Group gauges by `meta.tags` (default true). */
     groupByTags?: boolean;