@directive-run/ai 1.13.0 → 1.15.0

package/dist/{orchestrator-types-Bh8r3_Sq.d.cts → orchestrator-types-ZK9lv5Sm.d.ts}

@@ -1,6 +1,8 @@
-import { M as Message$1, n as RunResult, A as AgentLike, G as GuardrailFn, O as OutputGuardrailData, aX as StreamingCallbackRunner, q as DebugEvent, a8 as DebugEventType, b as AgentRunner, az as OrchestratorState, au as NamedGuardrail, I as InputGuardrailData, W as Checkpoint, L as BreakpointModifications, N as BreakpointRequest, o as OrchestratorConstraint, ax as OrchestratorResolver, aj as GuardrailsConfig, z as ApprovalRequest, av as OrchestratorDebugConfig, w as AgentRetryConfig, aw as OrchestratorLifecycleHooks, aU as SelfHealingConfig, e as CheckpointStore, H as BreakpointConfig, am as HealthMonitorConfig, p as RunOptions, T as ToolCallGuardrailData, l as PatternCheckpointConfig, i as DagPattern, m as GoalPattern, j as GoalNode, g as AgentSelectionStrategy, R as RelaxationTier, r as GoalResult, ab as GoalCheckpointState, aV as SequentialCheckpointState, aY as SupervisorCheckpointState, aG as ReflectCheckpointState, a5 as DebateCheckpointState, a2 as DagCheckpointState, aS as Scratchpad, as as MultiAgentLifecycleHooks, at as MultiAgentSelfHealingConfig, aq as MultiAgentBreakpointType, a0 as CrossAgentDerivationFn } from './types-CRmwFnVk.cjs';
-import { Plugin, System, Requirement } from '@directive-run/core';
+import { M as Message$1, q as RunResult, b as AgentLike, m as GuardrailFn, O as OutputGuardrailData, p as StreamingCallbackRunner, c as AgentRunner, r as OrchestratorState, N as NamedGuardrail, I as InputGuardrailData, C as Checkpoint, B as BreakpointModifications, d as BreakpointRequest, s as OrchestratorConstraint, t as OrchestratorResolver, u as GuardrailsConfig, A as ApprovalRequest, v as OrchestratorDebugConfig, w as AgentRetryConfig, x as OrchestratorLifecycleHooks, y as SelfHealingConfig, h as CheckpointStore, z as BreakpointConfig, R as RunOptions, T as ToolCallGuardrailData, P as PatternCheckpointConfig, k as DagPattern, E as GoalPattern, F as GoalNode, J as AgentSelectionStrategy, K as RelaxationTier, L as GoalResult, Q as GoalCheckpointState, U as SequentialCheckpointState, V as SupervisorCheckpointState, W as ReflectCheckpointState, X as DebateCheckpointState, Y as DagCheckpointState, S as Scratchpad, Z as MultiAgentLifecycleHooks, _ as MultiAgentSelfHealingConfig, $ as MultiAgentBreakpointType, a0 as CrossAgentDerivationFn } from './types-DJ09LjZX.js';
+import { System, Requirement, Plugin } from '@directive-run/core';
 import { CircuitBreaker } from '@directive-run/core/plugins';
+import { D as DebugTimeline } from './debug-timeline-L13P-U2I.js';
+import { H as HealthMonitor } from './health-monitor-qL9RNMH3.js';
 
 /**
  * Agent Memory System
@@ -600,89 +602,6 @@ interface MergedTaggedStreamResult {
  */
 declare function mergeTaggedStreams(sources: TaggedSource[]): MergedTaggedStreamResult;
 
-/**
- * Debug Timeline — AI-specific event log with snapshot correlation.
- *
- * Records agent lifecycle events (start, complete, error, guardrail checks,
- * approvals, handoffs, patterns) and correlates them with core time-travel
- * snapshots for visual timeline UIs and fork-and-replay debugging.
- *
- * Zero-cost when debug=false — the timeline is simply `null`.
- *
- * @module
- */
-
-/** Callback fired when a new event is recorded */
-type DebugTimelineListener = (event: DebugEvent) => void;
-/** Debug timeline instance */
-interface DebugTimeline {
-    /** Record a new event (id is auto-assigned) */
-    record(event: Omit<DebugEvent, "id"> & Record<string, unknown>): DebugEvent;
-    /** Get all events in order */
-    getEvents(): DebugEvent[];
-    /** Get events for a specific agent */
-    getEventsForAgent(agentId: string): DebugEvent[];
-    /** Get events by type with type narrowing */
-    getEventsByType<T extends DebugEventType>(type: T): Extract<DebugEvent, {
-        type: T;
-    }>[];
-    /** Get events at a specific snapshot */
-    getEventsAtSnapshot(snapshotId: number): DebugEvent[];
-    /** Get events in a time range */
-    getEventsInRange(startMs: number, endMs: number): DebugEvent[];
-    /** Fork from a snapshot — truncates events after it and calls goTo */
-    forkFrom(snapshotId: number): void;
-    /** Export timeline as JSON */
-    export(): string;
-    /** Import timeline from JSON */
-    import(json: string): void;
-    /** Clear all events */
-    clear(): void;
-    /** Subscribe to new events. Returns unsubscribe function. */
-    subscribe(listener: DebugTimelineListener): () => void;
-    /** Current number of events */
-    readonly length: number;
-}
-/** Options for creating a debug timeline */
-interface DebugTimelineOptions {
-    /** Maximum events before eviction. @default 2000 */
-    maxEvents?: number;
-    /** Callback to get current snapshot ID from the system */
-    getSnapshotId?: () => number | null;
-    /** Callback to navigate to a snapshot (for forkFrom) */
-    goToSnapshot?: (snapshotId: number) => void;
-}
-/**
- * Create a debug timeline for recording and correlating AI events.
- *
- * @example
- * ```typescript
- * const timeline = createDebugTimeline({ maxEvents: 1000 });
- *
- * timeline.record({
- *   type: "agent_start",
- *   timestamp: Date.now(),
- *   agentId: "researcher",
- *   snapshotId: null,
- *   inputLength: 42,
- * });
- *
- * const agentEvents = timeline.getEventsForAgent("researcher");
- * ```
- */
-declare function createDebugTimeline(options?: DebugTimelineOptions): DebugTimeline;
-/**
- * Create a Directive plugin that bridges core constraint/resolver events
- * to the debug timeline.
- *
- * @example
- * ```typescript
- * const timeline = createDebugTimeline();
- * const plugin = createDebugTimelinePlugin(timeline, () => system.history?.currentIndex ?? null);
- * ```
- */
-declare function createDebugTimelinePlugin(timeline: DebugTimeline, getSnapshotId: () => number | null): Plugin;
-
 /**
  * P6: Structured Outputs — Schema validation with auto-retry for LLM responses.
  *
@@ -1063,58 +982,6 @@ interface AgentOrchestrator<F extends Record<string, unknown>> {
  */
 declare function createAgentOrchestrator<F extends Record<string, unknown> = Record<string, never>>(options: OrchestratorOptions<F>): AgentOrchestrator<F>;
 
-/**
- * Health Monitor — tracks per-agent health metrics for self-healing networks.
- *
- * Pure computation module with zero Directive dependency.
- * Maintains a rolling window of success/failure events and computes a health
- * score from 0-100 based on configurable weights.
- *
- * @module
- */
-
-/** Circuit state values */
-type HealthCircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
-/** Per-agent health metrics */
-interface AgentHealthMetrics {
-    agentId: string;
-    circuitState: HealthCircuitState;
-    successRate: number;
-    avgLatencyMs: number;
-    recentFailures: number;
-    recentSuccesses: number;
-    healthScore: number;
-    /** Last N error messages (most recent last) */
-    lastErrors: string[];
-}
-/** Health monitor instance */
-interface HealthMonitor {
-    recordSuccess(agentId: string, latencyMs: number): void;
-    recordFailure(agentId: string, latencyMs: number, error?: Error): void;
-    getMetrics(agentId: string): AgentHealthMetrics;
-    getAllMetrics(): Record<string, AgentHealthMetrics>;
-    /** Returns a 0-100 health score. Returns 50 (neutral) when no data is available for the agent. */
-    getHealthScore(agentId: string): number;
-    updateCircuitState(agentId: string, state: HealthCircuitState): void;
-    /** Reset all metrics. Useful for testing. */
-    reset(): void;
-}
-/**
- * Create a health monitor that tracks per-agent metrics.
- *
- * @example
- * ```typescript
- * const monitor = createHealthMonitor({ windowMs: 30000 });
- *
- * monitor.recordSuccess("agent-a", 120);
- * monitor.recordFailure("agent-a", 5000, new Error("timeout"));
- *
- * const score = monitor.getHealthScore("agent-a");
- * console.log(score); // 0-100
- * ```
- */
-declare function createHealthMonitor(config?: HealthMonitorConfig): HealthMonitor;
-
 /**
  * Agent Reflection / Self-Improvement
  *
@@ -1383,7 +1250,7 @@ interface RaceSuccessEntry<T = unknown> {
 interface RaceResult<T = unknown> {
     winnerId: string;
     result: T;
-    allResults?: Array<RaceSuccessEntry<T>>;
+    allResults?: RaceSuccessEntry<T>[];
 }
 /**
  * Debate pattern - agents compete, evaluator judges across rounds.
@@ -1781,4 +1648,4 @@ interface MultiAgentOrchestrator {
     destroy(): void;
 }
 
-export { type SafeParseResult as $, type AgentRegistry as A, type BackpressureStrategy as B, type MessageChunk as C, type DebatePattern as D, type ExecutionPattern as E, type MessageSummarizer as F, type GuardrailTriggeredChunk as G, type HealthMonitor as H, type MultiAgentRunCallOptions as I, type MultiAgentState as J, type MultiplexedStreamChunk as K, type MultiplexedStreamResult as L, type MultiAgentOrchestratorOptions as M, type OrchestratorStreamChunk as N, type OrchestratorOptions as O, type ParallelPattern as P, type OrchestratorStreamResult as Q, type RacePattern as R, type SequentialPattern as S, type ProgressChunk as T, type RaceResult as U, type RaceSuccessEntry as V, type ReflectionConfig as W, type ReflectionContext as X, type ReflectionEvaluator as Y, ReflectionExhaustedError as Z, type RunCallOptions as _, type MultiAgentOrchestrator as a, type SafeParseable as a0, type StreamChunk as a1, type StreamRunOptions as a2, type StreamRunner as a3, type StreamingGuardrail as a4, type StreamingGuardrailResult as a5, type StreamingRunResult as a6, type StructuredOutputConfig as a7, StructuredOutputError as a8, type TaskContext as a9, tapStream as aA, withReflection as aB, withStructuredOutput as aC, type TaskRegistration as aa, type TokenChunk as ab, type ToolEndChunk as ac, type ToolStartChunk as ad, adaptOutputGuardrail as ae, collectTokens as af, combineStreamingGuardrails as ag, createAgentMemory as ah, createAgentOrchestrator as ai, createDebugTimeline as aj, createDebugTimelinePlugin as ak, createHealthMonitor as al, createHybridStrategy as am, createKeyPointsSummarizer as an, createLLMSummarizer as ao, createLengthStreamingGuardrail as ap, createPatternStreamingGuardrail as aq, createSlidingWindowStrategy as ar, createStreamingRunner as as, createTokenBasedStrategy as at, createToxicityStreamingGuardrail as au, createTruncationSummarizer as av, extractJsonFromOutput as aw, filterStream as ax, mapStream as ay, mergeTaggedStreams as az, type ReflectionEvaluation as b, type ReflectIterationRecord as c, type ReflectPattern as d, type SupervisorPattern as e, type RunAgentRequirement as f, type DebateResult as g, type AgentHealthMetrics as h, type DebugTimeline as i, type AgentMemory as j, type AgentMemoryConfig as k, type AgentOrchestrator as l, type AgentRegistration as m, type DebugTimelineListener as n, type DebugTimelineOptions as o, type DoneChunk as p, type ErrorChunk as q, type HandoffRequest as r, type HandoffResult as s, type HealthCircuitState as t, type MemoryManageResult as u, type MemoryState as v, type MemoryStrategy as w, type MemoryStrategyConfig as x, type MemoryStrategyResult as y, type MergedTaggedStreamResult as z };
+export { type StreamingGuardrailResult as $, type AgentOrchestrator as A, type BackpressureStrategy as B, type RaceSuccessEntry as C, type DebatePattern as D, type ErrorChunk as E, type ReflectIterationRecord as F, type GuardrailTriggeredChunk as G, type HandoffRequest as H, type ReflectPattern as I, type ReflectionConfig as J, type ReflectionContext as K, type ReflectionEvaluation as L, type MultiAgentOrchestrator as M, ReflectionExhaustedError as N, type OrchestratorOptions as O, type ParallelPattern as P, type RunAgentRequirement as Q, type ReflectionEvaluator as R, type RunCallOptions as S, type TaskRegistration as T, type SafeParseResult as U, type SafeParseable as V, type SequentialPattern as W, type StreamChunk as X, type StreamRunOptions as Y, type StreamRunner as Z, type StreamingGuardrail as _, type MultiAgentOrchestratorOptions as a, type StreamingRunResult as a0, type StructuredOutputConfig as a1, StructuredOutputError as a2, type SupervisorPattern as a3, type TaskContext as a4, type TokenChunk as a5, type ToolEndChunk as a6, type ToolStartChunk as a7, adaptOutputGuardrail as a8, collectTokens as a9, combineStreamingGuardrails as aa, createAgentMemory as ab, createAgentOrchestrator as ac, createHybridStrategy as ad, createKeyPointsSummarizer as ae, createLLMSummarizer as af, createLengthStreamingGuardrail as ag, createPatternStreamingGuardrail as ah, createSlidingWindowStrategy as ai, createStreamingRunner as aj, createTokenBasedStrategy as ak, createToxicityStreamingGuardrail as al, createTruncationSummarizer as am, extractJsonFromOutput as an, filterStream as ao, mapStream as ap, mergeTaggedStreams as aq, tapStream as ar, withReflection as as, withStructuredOutput as at, type MultiplexedStreamChunk as b, type AgentMemory as c, type AgentMemoryConfig as d, type AgentRegistration as e, type AgentRegistry as f, type DebateResult as g, type DoneChunk as h, type ExecutionPattern as i, type HandoffResult as j, type MemoryManageResult as k, type MemoryState as l, type MemoryStrategy as m, type MemoryStrategyConfig as n, type MemoryStrategyResult as o, type MergedTaggedStreamResult as p, type MessageChunk as q, type MessageSummarizer as r, type MultiAgentRunCallOptions as s, type MultiAgentState as t, type MultiplexedStreamResult as u, type OrchestratorStreamChunk as v, type OrchestratorStreamResult as w, type ProgressChunk as x, type RacePattern as y, type RaceResult as z };

package/dist/predicate.cjs

@@ -0,0 +1,2 @@
+'use strict';var chunkMDXDPECP_cjs=require('./chunk-MDXDPECP.cjs');require('./chunk-WCQK3JOR.cjs');Object.defineProperty(exports,"PredicateFromIntentError",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.a}});Object.defineProperty(exports,"predicateFromIntent",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.b}});Object.defineProperty(exports,"predicateFromIntentRaw",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.c}});Object.defineProperty(exports,"predicateFromIntentWithProvenance",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.g}});Object.defineProperty(exports,"predicateToolSpec",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.f}});Object.defineProperty(exports,"predicateToolSpecAnthropic",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.e}});Object.defineProperty(exports,"predicateToolSpecOpenAI",{enumerable:true,get:function(){return chunkMDXDPECP_cjs.d}});//# sourceMappingURL=predicate.cjs.map
+//# sourceMappingURL=predicate.cjs.map

package/dist/predicate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"predicate.cjs"}

package/dist/predicate.d.cts

@@ -0,0 +1,371 @@
+import { FactPredicate, SchemaValidationError } from '@directive-run/core';
+import { c as AgentRunner, b as AgentLike } from './types-DJ09LjZX.cjs';
+
+/**
+ * predicateFromIntent — let an LLM emit a typed FactPredicate as JSON,
+ * structurally + semantically validated before it ever reaches your
+ * constraint engine.
+ *
+ * Pipeline per call attempt:
+ *
+ *   1. Output-size check (reject before JSON.parse for DoS guard)
+ *   2. JSON.parse via extractJsonFromOutput (handles surrounding prose)
+ *   3. validatePredicate (structural: closed operator set, depth, JSON safety)
+ *   4. Operator-count check
+ *   5. validatePredicateAgainstSchema (semantic: operator-on-kind matrix)
+ *
+ * On any failure: a structured error message — including the offending
+ * clause's path, the allowed operators for that fact's kind, and the
+ * original schema kinds — is fed back to the LLM in the next attempt.
+ *
+ * Returns the validated FactPredicate. Throws PredicateFromIntentError
+ * on retry exhaustion. NEVER returns a partial / unvalidated predicate.
+ */
+
+interface PredicateFromIntentOptions<_F = Record<string, unknown>> {
+    /** Natural-language intent (untrusted user input — sanitize via `redact`). */
+    intent: string;
+    /**
+     * Module schema (must expose builders with `_typeName` or `_kind`).
+     * Pass either `{ facts: {...} }` or a bare `Record<string, builder>`.
+     */
+    schema: unknown;
+    /** AgentRunner from `@directive-run/ai` adapters (createOpenAIRunner, etc.). */
+    runner: AgentRunner;
+    /**
+     * Optional agent override. Default is `{ name: "predicate-emitter" }`
+     * with our system prompt; pass `instructions` to append additional
+     * context.
+     */
+    agent?: AgentLike;
+    /**
+     * Optional dotted-path namespace; useful for cross-module systems
+     * where the LLM should emit a predicate over `auth.token` (default:
+     * the schema's root facts).
+     */
+    factPath?: string;
+    /** Max retries on validation failure. Default 3. */
+    maxRetries?: number;
+    /**
+     * Hard byte cap on the LLM's raw output, BEFORE JSON.parse. Defaults
+     * to 64 KiB. A larger predicate is rejected outright; protects
+     * against multi-MB-payload DoS where the predicate is technically
+     * structurally valid.
+     */
+    maxPredicateBytes?: number;
+    /**
+     * Hard cap on the number of operator clauses in the predicate.
+     * Defaults to 256. Protects against `{ $any: [{ x: 1 }, … x100,000 ] }`
+     * style operator-count exhaustion.
+     */
+    maxOperatorCount?: number;
+    /**
+     * Optional sanitizer applied to `intent` BEFORE it lands in the
+     * system prompt. Useful for stripping or redacting user-controlled
+     * content that looks like prompt-injection.
+     */
+    redact?: (intent: string) => string;
+    /**
+     * Hard cap on the length of each `$in` / `$nin` array operand the LLM
+     * may emit. Defaults to 1000. Forwarded to
+     * `validatePredicateAgainstSchema`'s `maxArrayOperandLength`.
+     */
+    maxArrayOperandLength?: number;
+    /**
+     * Optional `AbortSignal` for cooperative cancellation. (N6)
+     *
+     * The retry loop checks `signal.aborted` between attempts AND forwards
+     * the signal into the runner call itself (`runner(agent, input, { signal })`).
+     * Whether the in-flight LLM call honors the signal depends on the runner:
+     * fetch-based adapters (the bundled OpenAI / Anthropic / Ollama runners)
+     * thread it through to `fetch`, so the network call aborts mid-stream.
+     * A custom runner that ignores the signal still delivers cancellation
+     * at the next retry boundary.
+     *
+     * On abort: throws `Error("aborted")`.
+     *
+     * NOTE: `predicateFromIntent` does NOT limit in-flight calls — callers
+     * MUST wrap with a concurrency limiter (e.g. `p-limit`) to bound
+     * fan-out under load.
+     */
+    signal?: AbortSignal;
+    /**
+     * When `true`, the {@link PredicateFromIntentProvenance} returned by
+     * `predicateFromIntentWithProvenance` omits the raw `intent` string and
+     * stores only the SHA-256 `intentHash`. Use this in PII-sensitive
+     * contexts where the original intent must not be persisted. (M6)
+     *
+     * **Default `false` for back-compat.** For PII-sensitive deployments,
+     * ALWAYS set `redactIntent: true` — the raw intent may contain
+     * user-supplied content (names, emails, medical or financial details,
+     * customer messages) that becomes a permanent record in
+     * `provenance.intent`. The default is opt-in only because flipping it
+     * now would silently strip diagnostic data from existing callers; v2
+     * may flip this default (tracked in IDEAS.md).
+     *
+     * Pair with a `redact:` sanitizer when the intent itself must be
+     * scrubbed BEFORE it lands in the LLM prompt — `redactIntent` controls
+     * only what enters the provenance record, not what the LLM sees.
+     */
+    redactIntent?: boolean;
+}
+interface PredicateFromIntentDiagnostics<F = Record<string, unknown>> {
+    /** The validated predicate (`null` if all retries failed). */
+    predicate: FactPredicate<F> | null;
+    /** Number of LLM calls actually made. */
+    attempts: number;
+    /** Errors encountered across all attempts (most recent last). */
+    errors: ReadonlyArray<{
+        attempt: number;
+        reason: string;
+        details?: readonly SchemaValidationError[];
+    }>;
+    /** The raw LLM output from the final attempt — useful for debugging. */
+    lastRawOutput?: string;
+}
+/** Thrown by `predicateFromIntent` on retry exhaustion. `predicateFromIntentRaw` returns these as a diagnostics payload instead. */
+declare class PredicateFromIntentError extends Error {
+    readonly attempts: number;
+    readonly errors: ReadonlyArray<{
+        attempt: number;
+        reason: string;
+        details?: readonly SchemaValidationError[];
+    }>;
+    readonly lastRawOutput: string | undefined;
+    readonly name = "PredicateFromIntentError";
+    constructor(message: string, attempts: number, errors: ReadonlyArray<{
+        attempt: number;
+        reason: string;
+        details?: readonly SchemaValidationError[];
+    }>, lastRawOutput: string | undefined);
+}
+/**
+ * Ask an LLM to emit a FactPredicate matching the user's intent, then
+ * validate it structurally + semantically before returning. On validation
+ * failure, retries with structured error feedback in the next prompt.
+ *
+ * Throws {@link PredicateFromIntentError} on retry exhaustion. NEVER
+ * returns a partial / unvalidated predicate.
+ *
+ * **Rate limiting:** this function does NOT limit in-flight calls. Wrap
+ * with a concurrency limiter (e.g. `p-limit` / `Bottleneck`) before
+ * exposing it to user-driven traffic. Pass an `AbortSignal` via `opts.signal`
+ * for cooperative cancellation between retry attempts.
+ *
+ * @example
+ * ```ts
+ * import { createOpenAIRunner } from "@directive-run/ai/openai";
+ * import { predicateFromIntent } from "@directive-run/ai";
+ *
+ * const runner = createOpenAIRunner({ apiKey, model: "gpt-4o-mini" });
+ *
+ * const predicate = await predicateFromIntent({
+ *   intent: "checkout is unblocked when the cart total is at least 50",
+ *   schema: myModule.schema,
+ *   runner,
+ * });
+ * // → { cartTotal: { $gte: 50 } }
+ * ```
+ */
+declare function predicateFromIntent<F = Record<string, unknown>>(opts: PredicateFromIntentOptions<F>): Promise<FactPredicate<F>>;
+/**
+ * Lower-level variant — returns the validated predicate (or null) plus
+ * full diagnostics. Use when you want to surface validation telemetry,
+ * preview the LLM's last raw output, or display per-attempt errors in
+ * a UI.
+ */
+declare function predicateFromIntentRaw<F = Record<string, unknown>>(opts: PredicateFromIntentOptions<F>): Promise<PredicateFromIntentDiagnostics<F>>;
+interface PredicateToolSpecOptions {
+    /** Tool name. Default `"emit_predicate"`. */
+    name?: string;
+    /** Tool description. Default: a one-liner describing predicate emission. */
+    description?: string;
+    /** Optional dotted-path namespace to restrict the tool's scope. */
+    factPath?: string;
+}
+/**
+ * Anthropic Messages API tool shape. Drop into the `tools: [...]` array.
+ * Anthropic's API expects `input_schema` at the top level of the tool.
+ */
+interface PredicateToolSpecAnthropic {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            predicate: {
+                type: "object";
+            };
+        };
+        required: ["predicate"];
+    };
+    /** Human-readable schema description — embed in your tool's "description" if your provider concatenates them. */
+    schemaSummary: string;
+}
+/**
+ * OpenAI Chat Completions / Responses API tool shape. Drop into the
+ * `tools: [...]` array. OpenAI nests the function payload under
+ * `function: { name, description, parameters }`.
+ */
+interface PredicateToolSpecOpenAI {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                predicate: {
+                    type: "object";
+                };
+            };
+            required: ["predicate"];
+        };
+    };
+    /** Human-readable schema description — embed in your tool's "description" if your provider concatenates them. */
+    schemaSummary: string;
+}
+/**
+ * @deprecated Use {@link PredicateToolSpecAnthropic} (or
+ * {@link PredicateToolSpecOpenAI}) directly. Kept as an alias for the
+ * pre-split shape that v1.12.x callers depend on; identical to
+ * `PredicateToolSpecAnthropic`.
+ */
+type PredicateToolSpec = PredicateToolSpecAnthropic;
+/**
+ * OpenAI Chat Completions / Responses API tool spec for predicate
+ * emission. Drop the result into your `tools: [...]` array; the model
+ * will be told to emit a predicate matching this schema.
+ *
+ * @example
+ * ```ts
+ * const tool = predicateToolSpecOpenAI(myModule.schema, { name: "set_checkout_rule" });
+ *
+ * await openai.chat.completions.create({
+ *   model: "gpt-4o-mini",
+ *   tools: [tool],
+ *   messages: [...],
+ * });
+ * ```
+ */
+declare function predicateToolSpecOpenAI(schema: unknown, opts?: PredicateToolSpecOptions): PredicateToolSpecOpenAI;
+/**
+ * Anthropic Messages API tool spec for predicate emission. Drop the
+ * result into your `tools: [...]` array; the model will be told to emit
+ * a predicate matching this schema.
+ *
+ * @example
+ * ```ts
+ * const tool = predicateToolSpecAnthropic(myModule.schema, { name: "set_checkout_rule" });
+ *
+ * await anthropic.messages.create({
+ *   model: "claude-3-5-sonnet-latest",
+ *   tools: [tool],
+ *   messages: [...],
+ * });
+ * ```
+ */
+declare function predicateToolSpecAnthropic(schema: unknown, opts?: PredicateToolSpecOptions): PredicateToolSpecAnthropic;
+/**
+ * @deprecated Use {@link predicateToolSpecAnthropic} (or
+ * {@link predicateToolSpecOpenAI}) directly. Back-compat alias for
+ * v1.12.x callers — emits the Anthropic shape, unchanged.
+ */
+declare function predicateToolSpec(schema: unknown, opts?: PredicateToolSpecOptions): PredicateToolSpec;
+interface PredicateFromIntentProvenance {
+    /**
+     * Resolved model name when the caller passes `agent: { model }`,
+     * otherwise `"unknown"`.
+     *
+     * NOTE: most callers omit `agent` (the default `predicate-emitter`
+     * agent has no model field set), so `model` is `"unknown"` by default.
+     * v1 does NOT read provider-detected model strings from `RunResult` —
+     * that requires every adapter to surface `runResult.model`, which the
+     * current `AgentRunner` contract does not. Tracked for v2; callers who
+     * need provider attribution today should pass `agent: { name, model: "..." }`.
+     */
+    readonly model: string;
+    /**
+     * Sanitized intent string actually sent to the LLM (post-redact). When
+     * `redactIntent: true` was passed, this field is omitted entirely — only
+     * `intentHash` is populated.
+     */
+    readonly intent?: string;
+    /**
+     * SHA-256 hex hash of the sanitized intent string (or djb2 fallback
+     * when `crypto.subtle` is unavailable). Always present — even when
+     * `intent` is omitted via `redactIntent`. (M6)
+     */
+    readonly intentHash: string;
+    /** Number of LLM calls that ran before the final predicate was accepted. */
+    readonly attemptCount: number;
+    /** ISO timestamp when the predicate was returned. */
+    readonly emittedAt: string;
+    /**
+     * Hash of the VALIDATED predicate (canonicalized via stableStringify
+     * before hashing). Two semantically-identical predicates emitted with
+     * different whitespace or key order produce the SAME `predicateHash`.
+     * Sufficient as a tamper-evident pointer alongside the persisted
+     * predicate. (N3)
+     *
+     * Renamed from `rawOutputHash` in v1.13.x — the old name hashed the
+     * raw LLM output string, which made two whitespace-different responses
+     * for the same logical predicate hash differently. Callers persisting
+     * the old `rawOutputHash` value should re-derive it from the stored
+     * predicate using `hashObject(predicate)` from `@directive-run/core/internals`.
+     */
+    readonly predicateHash: string;
+}
+interface PredicateFromIntentWithProvenanceResult<F = Record<string, unknown>> {
+    readonly predicate: FactPredicate<F>;
+    readonly provenance: PredicateFromIntentProvenance;
+}
+/**
+ * Like {@link predicateFromIntent} but additionally returns a structured
+ * provenance record — the model name, sanitized intent (or its hash),
+ * attempt count, timestamp, and a canonical hash of the validated
+ * predicate.
+ *
+ * **Production deployments MUST persist the provenance record alongside
+ * the predicate.** Without it, auditing "where did this rule come from?"
+ * becomes guesswork.
+ *
+ * Throws {@link PredicateFromIntentError} on retry exhaustion — same
+ * semantics as the un-provenanced variant.
+ *
+ * **PII guidance (M6):** pass `redactIntent: true` to omit the raw
+ * intent from the provenance record and persist only the `intentHash`.
+ * Useful when the intent itself is sensitive (medical, financial,
+ * customer messages, etc.).
+ *
+ * **Hash semantics (N3):**
+ * - `predicateHash` hashes the VALIDATED predicate object via stable
+ *   stringification — two whitespace-different LLM outputs that parse to
+ *   the same predicate produce the same hash.
+ * - `intentHash` hashes the sanitized intent STRING (SHA-256 when
+ *   available, djb2 fallback).
+ *
+ * @example
+ * ```ts
+ * const { predicate, provenance } = await predicateFromIntentWithProvenance({
+ *   intent: "block checkout when cart > 10k",
+ *   schema: checkoutModule.schema,
+ *   runner,
+ *   agent: { name: "predicate-emitter", model: "gpt-4o-mini" },
+ *   redactIntent: false, // default: store both intent + intentHash
+ * });
+ *
+ * await db.predicates.insert({
+ *   predicate,
+ *   model: provenance.model,
+ *   intent: provenance.intent,            // omitted when redactIntent: true
+ *   intentHash: provenance.intentHash,
+ *   emittedAt: provenance.emittedAt,
+ *   predicateHash: provenance.predicateHash,
+ *   attempts: provenance.attemptCount,
+ * });
+ * ```
+ */
+declare function predicateFromIntentWithProvenance<F = Record<string, unknown>>(opts: PredicateFromIntentOptions<F>): Promise<PredicateFromIntentWithProvenanceResult<F>>;
+
+export { type PredicateFromIntentDiagnostics, PredicateFromIntentError, type PredicateFromIntentOptions, type PredicateFromIntentProvenance, type PredicateFromIntentWithProvenanceResult, type PredicateToolSpec, type PredicateToolSpecAnthropic, type PredicateToolSpecOpenAI, type PredicateToolSpecOptions, predicateFromIntent, predicateFromIntentRaw, predicateFromIntentWithProvenance, predicateToolSpec, predicateToolSpecAnthropic, predicateToolSpecOpenAI };