@graphrefly/graphrefly 0.47.1 → 0.48.0

package/dist/utils/ai/index.d.cts

@@ -1,5 +1,5 @@
-import { i as TokenUsage, L as LLMAdapter, g as PricingFn, a as ChatMessage, b as LLMInvokeOptions, k as ToolDefinition, c as LLMResponse, S as StreamDelta } from '../../types-BB5Lw-pB.cjs';
-export { C as CapabilitiesRegistry, M as ModelCapabilities, d as ModelFeatures, e as ModelLimits, f as ModelPricing, P as PriceBreakdown, h as PricingRegistry, R as Rate, T as TieredRate, j as ToolCall, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from '../../types-BB5Lw-pB.cjs';
+import { i as TokenUsage, L as LLMAdapter, g as PricingFn, a as ChatMessage, b as LLMInvokeOptions, k as ToolDefinition, c as LLMResponse, S as StreamDelta, j as ToolCall } from '../../types-BB5Lw-pB.cjs';
+export { C as CapabilitiesRegistry, M as ModelCapabilities, d as ModelFeatures, e as ModelLimits, f as ModelPricing, P as PriceBreakdown, h as PricingRegistry, R as Rate, T 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-BB5Lw-pB.cjs';
 import { C as CascadeExhaustionReport } from '../../cascading-baGkiihI.cjs';
 export { A as AdapterProvider, a as AdapterTier, b as AllTiersExhaustedError, c as CascadingLlmAdapterOptions, d as CreateAdapterOptions, O as OpenAICompatAdapterOptions, e as OpenAICompatPreset, f as OpenAISdkLike, g as cascadingLlmAdapter, h as createAdapter, o as openAICompatAdapter, t as tier } from '../../cascading-baGkiihI.cjs';
 import { Node, Actor } from '@graphrefly/pure-ts/core';
@@ -7,8 +7,8 @@ import { ReactiveLogBundle, NodeInput } from '@graphrefly/pure-ts/extra';
 import { a as CircuitBreakerOptions, C as CircuitBreaker } from '../../breaker-ugSdq54q.cjs';
 export { b as CircuitOpenError } from '../../breaker-ugSdq54q.cjs';
 import { R as RateLimitSignal, A as AdaptiveRateLimiterBundle } from '../../adaptive-rate-limiter-Dch_xYIi.cjs';
-import { W as WithReplayCacheOptions } from '../../fallback-Bx46zqky.cjs';
-export { F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as fallbackAdapter, w as withReplayCache } from '../../fallback-Bx46zqky.cjs';
+import { W as WithReplayCacheOptions } from '../../fallback-BROR6ZhO.cjs';
+export { F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as fallbackAdapter, w as withReplayCache } from '../../fallback-BROR6ZhO.cjs';
 import { E as Extraction } from '../../distill-De6Rnn15.cjs';
 import { Graph } from '@graphrefly/pure-ts/graph';
 import { TopicGraph } from '../messaging/index.cjs';
@@ -900,7 +900,7 @@ declare function llmConsolidator<TMem>(systemPrompt: string, opts: LLMConsolidat
  * **Retry / replay-cache.** Stack middleware on the adapter:
  *
  * ```ts
- * import { withRetry, withReplayCache } from "@graphrefly/graphrefly/patterns/ai";
+ * import { withRetry, withReplayCache } from "@graphrefly/graphrefly/utils/ai";
  *
  * const adapter = withRetry(
  *   withReplayCache(baseAdapter, { keyFn: (ctx) => ctx.messages[0].content }),
@@ -1413,7 +1413,7 @@ type HandoffOptions = {
  *
  * @example Full handoff on a triage signal.
  * ```ts
- * import { handoff, promptNode } from "@graphrefly/graphrefly/patterns/ai";
+ * import { handoff, promptNode } from "@graphrefly/graphrefly/utils/ai";
  *
  * const triage = promptNode(adapter, [userMessage], (msg) =>
  *   `Classify urgency of: ${msg}. Reply "high" or "normal".`);
@@ -1447,6 +1447,91 @@ type HandoffOptions = {
  */
 declare function handoff<T>(from: NodeInput<T | null>, toFactory: (input: Node<T>) => Node<T | null>, opts?: HandoffOptions): Node<T | null>;
 
+/**
+ * Options for {@link toolInterceptor}.
+ */
+interface ToolInterceptorOptions {
+    readonly name?: string;
+    /**
+     * Kill-switch. When this reactive Node emits `false`, **every** tool call
+     * in the wave is denied and the turn collapses to a clean no-op (RESOLVED,
+     * not an empty-array execution). An explicit `null` / `undefined` DATA
+     * value is pass-through ("deny when explicitly `false`"). Like
+     * {@link ToolInterceptorOptions.allow}, a switch node that has never
+     * emitted has **unspecified** gating — **always seed it**
+     * (`node([], { initial: true })`). Modelled as a reactive deny-signal, NOT
+     * a buffering `valve`: a security kill-switch must DROP denied calls,
+     * never buffer-and-replay them after re-enable — a re-enable with no fresh
+     * `calls` wave is a no-op (see {@link ToolInterceptorOptions.allow}).
+     */
+    readonly enabled?: NodeInput<boolean>;
+    /**
+     * Per-call allow predicates. A tool call is forwarded iff **every**
+     * predicate returns `true`. A predicate that has emitted an explicit
+     * `null` / `undefined` DATA value is pass-through (the policy author's
+     * "not-ready, allow" signal). **Always seed each predicate node with an
+     * `initial`** (e.g. `node([], { initial: null })` for pass-through-while-
+     * loading, or an initial predicate fn): a predicate node that has *never*
+     * emitted DATA has **unspecified** gating — depending on activation order
+     * the non-partial first-run gate may hold the tool turn or pass through,
+     * so a never-seeded policy must not be relied on either way. A predicate
+     * that **throws** is treated as **deny** for that call (a security gate
+     * must never fail open on a buggy policy).
+     *
+     * **Re-filtering is calls-driven, not predicate-driven.** A predicate (or
+     * {@link enabled}) change *alone* never re-emits an in-flight batch — that
+     * would replay a previously-denied batch with no LLM in the loop
+     * (confused-deputy). The post-intercept stream only re-evaluates on a
+     * *fresh* `calls` wave; predicate/switch updates take effect on the next
+     * tool-call batch.
+     */
+    readonly allow?: readonly NodeInput<(call: ToolCall) => boolean>[];
+}
+/**
+ * Reactive tool-call **enforcement** (COMPOSITION-GUIDE §31, Composition C).
+ * The post-generation security counterpart to `toolSelector`'s
+ * pre-generation UX: `toolSelector` controls what's *offered* to the LLM;
+ * `toolInterceptor` gates what's *executed* after the LLM chooses.
+ *
+ * Returns a transform `(calls) => Node<readonly ToolCall[]>` shaped to slot
+ * directly into `agentLoop`'s `interceptToolCalls` splice
+ * (`agent-loop.ts` D9). The returned node is `derived`-kind: it sees the raw
+ * tool-call batch, applies the kill-switch then the per-call predicates, and
+ *
+ * - emits the surviving subset when ≥1 call passes,
+ * - emits `[RESOLVED]` when the switch is off OR every call is denied — a
+ *   clean no-op turn, structurally identical to `toolCallsRaw`'s own
+ *   empty-batch gate, so `toolExecution`'s non-empty contract is preserved.
+ *
+ * Because the splice replaces the public `agent.toolCalls` view with this
+ * node, audit / telemetry observe the post-intercept reality.
+ *
+ * @example
+ * ```ts
+ * const killSwitch = node<boolean>([], { name: "tools-enabled", initial: true });
+ * const loop = agentLoop("agent", {
+ *   adapter,
+ *   tools: [searchTool, deleteTool],
+ *   interceptToolCalls: toolInterceptor({
+ *     enabled: killSwitch,
+ *     allow: [
+ *       // deny destructive tools unless an external policy node says ok
+ *       node([policyNode], (b, a, c) => {
+ *         const d = b.map((x, i) => x != null && x.length > 0 ? x.at(-1) : c.prevData[i]);
+ *         a.emit((call: ToolCall) => call.name !== "delete" || d[0] === true);
+ *       }, { describeKind: "derived" }),
+ *     ],
+ *   }),
+ * });
+ * ```
+ *
+ * @param opts - {@link ToolInterceptorOptions}.
+ * @returns A `(calls) => Node` transform for `agentLoop.interceptToolCalls`.
+ *
+ * @category ai
+ */
+declare function toolInterceptor(opts?: ToolInterceptorOptions): (calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>;
+
 /**
  * Options for {@link toolSelector}.
  */
@@ -1460,10 +1545,21 @@ interface ToolSelectorOptions {
  * 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.
+ * **every** predicate returns `true`. An *emitted* `null` / `undefined`
+ * predicate DATA value is pass-through — the tool isn't excluded on its
+ * basis ("deny when explicitly `false`, not when not-yet-ready"). **Always
+ * seed each predicate node with an `initial`** (e.g.
+ * `node([], { initial: null })` for pass-through-while-loading, or an
+ * initial predicate fn): a predicate node that has *never* emitted DATA
+ * (pure SENTINEL) has **unspecified** gating — depending on activation
+ * order it may or may not participate in the first-run gate (the open core
+ * SENTINEL-dep first-run-gate question), so a never-seeded predicate must
+ * not be relied on either way. Mirrors `toolInterceptor`'s *seed-an-`initial`*
+ * contract — but NOT its throwing-predicate behaviour: a constraint that
+ * *throws* tears the wave with an ERROR (no fail-closed catch), because
+ * selection is not a security boundary (a loud surface beats a silent
+ * deny here; pair with `toolInterceptor` for enforcement).
+ * 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
@@ -1477,7 +1573,7 @@ interface ToolSelectorOptions {
  *   const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
  *   actions.emit((data[0] as CostMeter).total < BUDGET);
  * }, { describeKind: "derived" });
- * const canDestroy = state(false, { name: "destructive-allowed" });
+ * const canDestroy = node<boolean>([], { name: "destructive-allowed", initial: false });
  * const tools = toolSelector(registry.schemas, [
  *   node([hasBudget], (batchData, actions, ctx) => {
  *     const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
@@ -1774,4 +1870,4 @@ type GraphDefValidation = {
  */
 declare function validateGraphDef(def: unknown): GraphDefValidation;
 
-export { type AdapterStats, type AdmissionScore3DOptions, type AdmissionScoredOptions, type AdmissionScores, type AdmissionThresholds, type AnthropicAdapterOptions, type AnthropicSdkLike, type BudgetCaps, BudgetExhaustedError, type BudgetTotals, type CallStatsEvent, CascadeExhaustionReport, ChatMessage, type ContentDecision, type ContentGateOptions, type CostMeterOptions, type CostMeterReading, type DryRunAdapterOptions, type ExtractedToolCall, type FrozenContextOptions, type GatedStreamHandle, type GatedStreamOptions, type GaugesAsContextOptions, type GoogleAdapterOptions, type GoogleSdkLike, type GoogleSdkRequestConfig, type GoogleSdkRequestParams, type GraphDefValidation, type GraphFromSpecOptions, type HandoffOptions, type HttpErrorLike, type KeywordFlag, type KeywordFlagExtractorOptions, type KnobsAsToolsResult, LLMAdapter, type LLMBudgetGateBundle, type LLMConsolidatorOptions, type LLMExtractorOptions, LLMInvokeOptions, LLMResponse, LLMTimeoutError, type McpToolSchema, type OpenAIToolSchema, PricingFn, type PromptCallOptions, type PromptNodeOptions, type RedactorOptions, type ResilientAdapterBundle, type ResilientAdapterOptions, type StampedDelta, type StrategyOperation, type StrategyPlan, StreamDelta, type StreamingPromptNodeHandle, type StreamingPromptNodeOptions, type SuggestStrategyOptions, type SystemPromptHandle, TokenUsage, ToolDefinition, type ToolSelectorOptions, type WithBreakerOptions, type WithBudgetGateOptions, type WithDryRunBundle, type WithDryRunOptions, type WithRateLimiterOptions, WithReplayCacheOptions, type WithRetryOptions, admissionFilter3D, admissionScored, anthropicAdapter, contentGate, costMeterExtractor, dryRunAdapter, frozenContext, gatedStream, gaugesAsContext, googleAdapter, graphFromSpec, graphFromSpecReactive, handoff, keywordFlagExtractor, knobsAsTools, llmConsolidator, llmExtractor, observableAdapter, parseRateLimitFromError, promptCall, promptNode, redactor, resilientAdapter, streamExtractor, streamingPromptNode, suggestStrategy, suggestStrategyReactive, systemPromptBuilder, toolCallExtractor, toolSelector, validateGraphDef, withBudgetGate, withDryRun, withLLMBreaker, withLLMTimeout, withRateLimiter, withRetry };
+export { type AdapterStats, type AdmissionScore3DOptions, type AdmissionScoredOptions, type AdmissionScores, type AdmissionThresholds, type AnthropicAdapterOptions, type AnthropicSdkLike, type BudgetCaps, BudgetExhaustedError, type BudgetTotals, type CallStatsEvent, CascadeExhaustionReport, ChatMessage, type ContentDecision, type ContentGateOptions, type CostMeterOptions, type CostMeterReading, type DryRunAdapterOptions, type ExtractedToolCall, type FrozenContextOptions, type GatedStreamHandle, type GatedStreamOptions, type GaugesAsContextOptions, type GoogleAdapterOptions, type GoogleSdkLike, type GoogleSdkRequestConfig, type GoogleSdkRequestParams, type GraphDefValidation, type GraphFromSpecOptions, type HandoffOptions, type HttpErrorLike, type KeywordFlag, type KeywordFlagExtractorOptions, type KnobsAsToolsResult, LLMAdapter, type LLMBudgetGateBundle, type LLMConsolidatorOptions, type LLMExtractorOptions, LLMInvokeOptions, LLMResponse, LLMTimeoutError, type McpToolSchema, type OpenAIToolSchema, PricingFn, type PromptCallOptions, type PromptNodeOptions, type RedactorOptions, type ResilientAdapterBundle, type ResilientAdapterOptions, type StampedDelta, type StrategyOperation, type StrategyPlan, StreamDelta, type StreamingPromptNodeHandle, type StreamingPromptNodeOptions, type SuggestStrategyOptions, type SystemPromptHandle, TokenUsage, ToolCall, ToolDefinition, type ToolInterceptorOptions, type ToolSelectorOptions, type WithBreakerOptions, type WithBudgetGateOptions, type WithDryRunBundle, type WithDryRunOptions, type WithRateLimiterOptions, WithReplayCacheOptions, type WithRetryOptions, admissionFilter3D, admissionScored, anthropicAdapter, contentGate, costMeterExtractor, dryRunAdapter, frozenContext, gatedStream, gaugesAsContext, googleAdapter, graphFromSpec, graphFromSpecReactive, handoff, keywordFlagExtractor, knobsAsTools, llmConsolidator, llmExtractor, observableAdapter, parseRateLimitFromError, promptCall, promptNode, redactor, resilientAdapter, streamExtractor, streamingPromptNode, suggestStrategy, suggestStrategyReactive, systemPromptBuilder, toolCallExtractor, toolInterceptor, toolSelector, validateGraphDef, withBudgetGate, withDryRun, withLLMBreaker, withLLMTimeout, withRateLimiter, withRetry };

package/dist/utils/ai/index.d.ts

@@ -1,5 +1,5 @@
-import { i as TokenUsage, L as LLMAdapter, g as PricingFn, a as ChatMessage, b as LLMInvokeOptions, k as ToolDefinition, c as LLMResponse, S as StreamDelta } from '../../types-BB5Lw-pB.js';
-export { C as CapabilitiesRegistry, M as ModelCapabilities, d as ModelFeatures, e as ModelLimits, f as ModelPricing, P as PriceBreakdown, h as PricingRegistry, R as Rate, T as TieredRate, j as ToolCall, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from '../../types-BB5Lw-pB.js';
+import { i as TokenUsage, L as LLMAdapter, g as PricingFn, a as ChatMessage, b as LLMInvokeOptions, k as ToolDefinition, c as LLMResponse, S as StreamDelta, j as ToolCall } from '../../types-BB5Lw-pB.js';
+export { C as CapabilitiesRegistry, M as ModelCapabilities, d as ModelFeatures, e as ModelLimits, f as ModelPricing, P as PriceBreakdown, h as PricingRegistry, R as Rate, T 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-BB5Lw-pB.js';
 import { C as CascadeExhaustionReport } from '../../cascading-CSSbKGrJ.js';
 export { A as AdapterProvider, a as AdapterTier, b as AllTiersExhaustedError, c as CascadingLlmAdapterOptions, d as CreateAdapterOptions, O as OpenAICompatAdapterOptions, e as OpenAICompatPreset, f as OpenAISdkLike, g as cascadingLlmAdapter, h as createAdapter, o as openAICompatAdapter, t as tier } from '../../cascading-CSSbKGrJ.js';
 import { Node, Actor } from '@graphrefly/pure-ts/core';
@@ -7,8 +7,8 @@ import { ReactiveLogBundle, NodeInput } from '@graphrefly/pure-ts/extra';
 import { a as CircuitBreakerOptions, C as CircuitBreaker } from '../../breaker-C9skL3d8.js';
 export { b as CircuitOpenError } from '../../breaker-C9skL3d8.js';
 import { R as RateLimitSignal, A as AdaptiveRateLimiterBundle } from '../../adaptive-rate-limiter-Dch_xYIi.js';
-import { W as WithReplayCacheOptions } from '../../fallback-pIWW8A2d.js';
-export { F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as fallbackAdapter, w as withReplayCache } from '../../fallback-pIWW8A2d.js';
+import { W as WithReplayCacheOptions } from '../../fallback-DO80aM_3.js';
+export { F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as fallbackAdapter, w as withReplayCache } from '../../fallback-DO80aM_3.js';
 import { E as Extraction } from '../../distill-De6Rnn15.js';
 import { Graph } from '@graphrefly/pure-ts/graph';
 import { TopicGraph } from '../messaging/index.js';
@@ -900,7 +900,7 @@ declare function llmConsolidator<TMem>(systemPrompt: string, opts: LLMConsolidat
  * **Retry / replay-cache.** Stack middleware on the adapter:
  *
  * ```ts
- * import { withRetry, withReplayCache } from "@graphrefly/graphrefly/patterns/ai";
+ * import { withRetry, withReplayCache } from "@graphrefly/graphrefly/utils/ai";
  *
  * const adapter = withRetry(
  *   withReplayCache(baseAdapter, { keyFn: (ctx) => ctx.messages[0].content }),
@@ -1413,7 +1413,7 @@ type HandoffOptions = {
  *
  * @example Full handoff on a triage signal.
  * ```ts
- * import { handoff, promptNode } from "@graphrefly/graphrefly/patterns/ai";
+ * import { handoff, promptNode } from "@graphrefly/graphrefly/utils/ai";
  *
  * const triage = promptNode(adapter, [userMessage], (msg) =>
  *   `Classify urgency of: ${msg}. Reply "high" or "normal".`);
@@ -1447,6 +1447,91 @@ type HandoffOptions = {
  */
 declare function handoff<T>(from: NodeInput<T | null>, toFactory: (input: Node<T>) => Node<T | null>, opts?: HandoffOptions): Node<T | null>;
 
+/**
+ * Options for {@link toolInterceptor}.
+ */
+interface ToolInterceptorOptions {
+    readonly name?: string;
+    /**
+     * Kill-switch. When this reactive Node emits `false`, **every** tool call
+     * in the wave is denied and the turn collapses to a clean no-op (RESOLVED,
+     * not an empty-array execution). An explicit `null` / `undefined` DATA
+     * value is pass-through ("deny when explicitly `false`"). Like
+     * {@link ToolInterceptorOptions.allow}, a switch node that has never
+     * emitted has **unspecified** gating — **always seed it**
+     * (`node([], { initial: true })`). Modelled as a reactive deny-signal, NOT
+     * a buffering `valve`: a security kill-switch must DROP denied calls,
+     * never buffer-and-replay them after re-enable — a re-enable with no fresh
+     * `calls` wave is a no-op (see {@link ToolInterceptorOptions.allow}).
+     */
+    readonly enabled?: NodeInput<boolean>;
+    /**
+     * Per-call allow predicates. A tool call is forwarded iff **every**
+     * predicate returns `true`. A predicate that has emitted an explicit
+     * `null` / `undefined` DATA value is pass-through (the policy author's
+     * "not-ready, allow" signal). **Always seed each predicate node with an
+     * `initial`** (e.g. `node([], { initial: null })` for pass-through-while-
+     * loading, or an initial predicate fn): a predicate node that has *never*
+     * emitted DATA has **unspecified** gating — depending on activation order
+     * the non-partial first-run gate may hold the tool turn or pass through,
+     * so a never-seeded policy must not be relied on either way. A predicate
+     * that **throws** is treated as **deny** for that call (a security gate
+     * must never fail open on a buggy policy).
+     *
+     * **Re-filtering is calls-driven, not predicate-driven.** A predicate (or
+     * {@link enabled}) change *alone* never re-emits an in-flight batch — that
+     * would replay a previously-denied batch with no LLM in the loop
+     * (confused-deputy). The post-intercept stream only re-evaluates on a
+     * *fresh* `calls` wave; predicate/switch updates take effect on the next
+     * tool-call batch.
+     */
+    readonly allow?: readonly NodeInput<(call: ToolCall) => boolean>[];
+}
+/**
+ * Reactive tool-call **enforcement** (COMPOSITION-GUIDE §31, Composition C).
+ * The post-generation security counterpart to `toolSelector`'s
+ * pre-generation UX: `toolSelector` controls what's *offered* to the LLM;
+ * `toolInterceptor` gates what's *executed* after the LLM chooses.
+ *
+ * Returns a transform `(calls) => Node<readonly ToolCall[]>` shaped to slot
+ * directly into `agentLoop`'s `interceptToolCalls` splice
+ * (`agent-loop.ts` D9). The returned node is `derived`-kind: it sees the raw
+ * tool-call batch, applies the kill-switch then the per-call predicates, and
+ *
+ * - emits the surviving subset when ≥1 call passes,
+ * - emits `[RESOLVED]` when the switch is off OR every call is denied — a
+ *   clean no-op turn, structurally identical to `toolCallsRaw`'s own
+ *   empty-batch gate, so `toolExecution`'s non-empty contract is preserved.
+ *
+ * Because the splice replaces the public `agent.toolCalls` view with this
+ * node, audit / telemetry observe the post-intercept reality.
+ *
+ * @example
+ * ```ts
+ * const killSwitch = node<boolean>([], { name: "tools-enabled", initial: true });
+ * const loop = agentLoop("agent", {
+ *   adapter,
+ *   tools: [searchTool, deleteTool],
+ *   interceptToolCalls: toolInterceptor({
+ *     enabled: killSwitch,
+ *     allow: [
+ *       // deny destructive tools unless an external policy node says ok
+ *       node([policyNode], (b, a, c) => {
+ *         const d = b.map((x, i) => x != null && x.length > 0 ? x.at(-1) : c.prevData[i]);
+ *         a.emit((call: ToolCall) => call.name !== "delete" || d[0] === true);
+ *       }, { describeKind: "derived" }),
+ *     ],
+ *   }),
+ * });
+ * ```
+ *
+ * @param opts - {@link ToolInterceptorOptions}.
+ * @returns A `(calls) => Node` transform for `agentLoop.interceptToolCalls`.
+ *
+ * @category ai
+ */
+declare function toolInterceptor(opts?: ToolInterceptorOptions): (calls: Node<readonly ToolCall[]>) => Node<readonly ToolCall[]>;
+
 /**
  * Options for {@link toolSelector}.
  */
@@ -1460,10 +1545,21 @@ interface ToolSelectorOptions {
  * 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.
+ * **every** predicate returns `true`. An *emitted* `null` / `undefined`
+ * predicate DATA value is pass-through — the tool isn't excluded on its
+ * basis ("deny when explicitly `false`, not when not-yet-ready"). **Always
+ * seed each predicate node with an `initial`** (e.g.
+ * `node([], { initial: null })` for pass-through-while-loading, or an
+ * initial predicate fn): a predicate node that has *never* emitted DATA
+ * (pure SENTINEL) has **unspecified** gating — depending on activation
+ * order it may or may not participate in the first-run gate (the open core
+ * SENTINEL-dep first-run-gate question), so a never-seeded predicate must
+ * not be relied on either way. Mirrors `toolInterceptor`'s *seed-an-`initial`*
+ * contract — but NOT its throwing-predicate behaviour: a constraint that
+ * *throws* tears the wave with an ERROR (no fail-closed catch), because
+ * selection is not a security boundary (a loud surface beats a silent
+ * deny here; pair with `toolInterceptor` for enforcement).
+ * 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
@@ -1477,7 +1573,7 @@ interface ToolSelectorOptions {
  *   const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
  *   actions.emit((data[0] as CostMeter).total < BUDGET);
  * }, { describeKind: "derived" });
- * const canDestroy = state(false, { name: "destructive-allowed" });
+ * const canDestroy = node<boolean>([], { name: "destructive-allowed", initial: false });
  * const tools = toolSelector(registry.schemas, [
  *   node([hasBudget], (batchData, actions, ctx) => {
  *     const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
@@ -1774,4 +1870,4 @@ type GraphDefValidation = {
  */
 declare function validateGraphDef(def: unknown): GraphDefValidation;
 
-export { type AdapterStats, type AdmissionScore3DOptions, type AdmissionScoredOptions, type AdmissionScores, type AdmissionThresholds, type AnthropicAdapterOptions, type AnthropicSdkLike, type BudgetCaps, BudgetExhaustedError, type BudgetTotals, type CallStatsEvent, CascadeExhaustionReport, ChatMessage, type ContentDecision, type ContentGateOptions, type CostMeterOptions, type CostMeterReading, type DryRunAdapterOptions, type ExtractedToolCall, type FrozenContextOptions, type GatedStreamHandle, type GatedStreamOptions, type GaugesAsContextOptions, type GoogleAdapterOptions, type GoogleSdkLike, type GoogleSdkRequestConfig, type GoogleSdkRequestParams, type GraphDefValidation, type GraphFromSpecOptions, type HandoffOptions, type HttpErrorLike, type KeywordFlag, type KeywordFlagExtractorOptions, type KnobsAsToolsResult, LLMAdapter, type LLMBudgetGateBundle, type LLMConsolidatorOptions, type LLMExtractorOptions, LLMInvokeOptions, LLMResponse, LLMTimeoutError, type McpToolSchema, type OpenAIToolSchema, PricingFn, type PromptCallOptions, type PromptNodeOptions, type RedactorOptions, type ResilientAdapterBundle, type ResilientAdapterOptions, type StampedDelta, type StrategyOperation, type StrategyPlan, StreamDelta, type StreamingPromptNodeHandle, type StreamingPromptNodeOptions, type SuggestStrategyOptions, type SystemPromptHandle, TokenUsage, ToolDefinition, type ToolSelectorOptions, type WithBreakerOptions, type WithBudgetGateOptions, type WithDryRunBundle, type WithDryRunOptions, type WithRateLimiterOptions, WithReplayCacheOptions, type WithRetryOptions, admissionFilter3D, admissionScored, anthropicAdapter, contentGate, costMeterExtractor, dryRunAdapter, frozenContext, gatedStream, gaugesAsContext, googleAdapter, graphFromSpec, graphFromSpecReactive, handoff, keywordFlagExtractor, knobsAsTools, llmConsolidator, llmExtractor, observableAdapter, parseRateLimitFromError, promptCall, promptNode, redactor, resilientAdapter, streamExtractor, streamingPromptNode, suggestStrategy, suggestStrategyReactive, systemPromptBuilder, toolCallExtractor, toolSelector, validateGraphDef, withBudgetGate, withDryRun, withLLMBreaker, withLLMTimeout, withRateLimiter, withRetry };
+export { type AdapterStats, type AdmissionScore3DOptions, type AdmissionScoredOptions, type AdmissionScores, type AdmissionThresholds, type AnthropicAdapterOptions, type AnthropicSdkLike, type BudgetCaps, BudgetExhaustedError, type BudgetTotals, type CallStatsEvent, CascadeExhaustionReport, ChatMessage, type ContentDecision, type ContentGateOptions, type CostMeterOptions, type CostMeterReading, type DryRunAdapterOptions, type ExtractedToolCall, type FrozenContextOptions, type GatedStreamHandle, type GatedStreamOptions, type GaugesAsContextOptions, type GoogleAdapterOptions, type GoogleSdkLike, type GoogleSdkRequestConfig, type GoogleSdkRequestParams, type GraphDefValidation, type GraphFromSpecOptions, type HandoffOptions, type HttpErrorLike, type KeywordFlag, type KeywordFlagExtractorOptions, type KnobsAsToolsResult, LLMAdapter, type LLMBudgetGateBundle, type LLMConsolidatorOptions, type LLMExtractorOptions, LLMInvokeOptions, LLMResponse, LLMTimeoutError, type McpToolSchema, type OpenAIToolSchema, PricingFn, type PromptCallOptions, type PromptNodeOptions, type RedactorOptions, type ResilientAdapterBundle, type ResilientAdapterOptions, type StampedDelta, type StrategyOperation, type StrategyPlan, StreamDelta, type StreamingPromptNodeHandle, type StreamingPromptNodeOptions, type SuggestStrategyOptions, type SystemPromptHandle, TokenUsage, ToolCall, ToolDefinition, type ToolInterceptorOptions, type ToolSelectorOptions, type WithBreakerOptions, type WithBudgetGateOptions, type WithDryRunBundle, type WithDryRunOptions, type WithRateLimiterOptions, WithReplayCacheOptions, type WithRetryOptions, admissionFilter3D, admissionScored, anthropicAdapter, contentGate, costMeterExtractor, dryRunAdapter, frozenContext, gatedStream, gaugesAsContext, googleAdapter, graphFromSpec, graphFromSpecReactive, handoff, keywordFlagExtractor, knobsAsTools, llmConsolidator, llmExtractor, observableAdapter, parseRateLimitFromError, promptCall, promptNode, redactor, resilientAdapter, streamExtractor, streamingPromptNode, suggestStrategy, suggestStrategyReactive, systemPromptBuilder, toolCallExtractor, toolInterceptor, toolSelector, validateGraphDef, withBudgetGate, withDryRun, withLLMBreaker, withLLMTimeout, withRateLimiter, withRetry };

package/dist/utils/ai/index.js

@@ -29,6 +29,7 @@ import {
   suggestStrategyReactive,
   systemPromptBuilder,
   toolCallExtractor,
+  toolInterceptor,
   toolSelector,
   validateGraphDef,
   withBudgetGate,
@@ -38,9 +39,10 @@ import {
   withRateLimiter,
   withRetry,
   zeroPrice
-} from "../../chunk-K7PDZYQE.js";
-import "../../chunk-2OB3CEJS.js";
-import "../../chunk-7ADWWI2T.js";
+} from "../../chunk-MQMTRKY3.js";
+import "../../chunk-B5Y5GPD5.js";
+import "../../chunk-LTSI7ULC.js";
+import "../../chunk-ZW32BPXV.js";
 import {
   AllTiersExhaustedError,
   anthropicAdapter,
@@ -49,19 +51,18 @@ import {
   googleAdapter,
   openAICompatAdapter,
   tier
-} from "../../chunk-4GYMCUDZ.js";
+} from "../../chunk-T2U6N3FV.js";
 import {
   CircuitOpenError
-} from "../../chunk-RJOG4IJU.js";
-import "../../chunk-RAGGHLCV.js";
+} from "../../chunk-T5URUIIY.js";
+import "../../chunk-GUNIRPEJ.js";
 import {
   FallbackMissError,
   ReplayCacheMissError,
   dryRunAdapter,
   fallbackAdapter,
   withReplayCache
-} from "../../chunk-CXANAIZU.js";
-import "../../chunk-IHTWQEDR.js";
+} from "../../chunk-XEWV254I.js";
 import {
   ChatStreamGraph,
   MemoryRetrievalGraph,
@@ -80,23 +81,23 @@ import {
   promptNode,
   toolExecution,
   toolRegistry
-} from "../../chunk-YXCPV26R.js";
-import "../../chunk-U225SKB4.js";
-import "../../chunk-NPRP3MCV.js";
+} from "../../chunk-3REMCHSS.js";
+import "../../chunk-K4ZYJ4EM.js";
+import "../../chunk-DHDCOOJU.js";
+import "../../chunk-F7EKHR32.js";
+import "../../chunk-JA67ZQG2.js";
+import "../../chunk-KUFXLAEY.js";
+import "../../chunk-TSBFTJKM.js";
+import "../../chunk-P5LBT622.js";
 import {
   DEFAULT_DECAY_RATE
 } from "../../chunk-QMBYUVRL.js";
 import "../../chunk-FMPF42Q4.js";
-import "../../chunk-BXGZFGZ4.js";
-import "../../chunk-BU3SEFA5.js";
-import "../../chunk-A7KV5UK4.js";
-import "../../chunk-DKNHAICT.js";
-import "../../chunk-O3MT7DYI.js";
-import "../../chunk-SOOKUYVM.js";
-import "../../chunk-Y52CS6YA.js";
-import "../../chunk-Z4YXAUDN.js";
-import "../../chunk-TSBFTJKM.js";
-import "../../chunk-P5LBT622.js";
+import "../../chunk-C5QD5DQX.js";
+import "../../chunk-V46JWFGV.js";
+import "../../chunk-G7H6PN7P.js";
+import "../../chunk-MMHGYX44.js";
+import "../../chunk-N6MNJNHB.js";
 import "../../chunk-AZDQPQ3V.js";
 export {
   AllTiersExhaustedError,
@@ -158,6 +159,7 @@ export {
   tier,
   toolCallExtractor,
   toolExecution,
+  toolInterceptor,
   toolRegistry,
   toolSelector,
   validateGraphDef,