@directive-run/ai 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,517 +1,11 @@
-import { Requirement, ModuleSchema, Plugin, System } from '@directive-run/core';
-import { CircuitState, ObservabilityInstance, TraceSpan, AggregatedMetric, CircuitBreakerConfig, CircuitBreaker, AlertConfig } from '@directive-run/core/plugins';
+import { G as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, S as SchemaValidator, T as ToolCallGuardrailData, A as AgentLike, M as Message, a as AdapterHooks, b as AgentRunner, c as ApprovalState, d as AgentState, R as RunOptions, e as RunResult, D as DebugEvent, B as BreakpointState, f as GoalResult } from './types-Co4BzMiH.cjs';
+export { g as AgentCircuitBreakerConfig, h as AgentCompleteEvent, i as AgentErrorEvent, j as AgentHealthState, k as AgentRetryConfig, l as AgentRetryEvent, m as AgentSelectionStrategy, n as AgentStartEvent, o as ApprovalRequest, p as ApprovalRequestEvent, q as ApprovalResponseEvent, r as BreakpointConfig, s as BreakpointContext, t as BreakpointHitEvent, u as BreakpointModifications, v as BreakpointRequest, w as BreakpointResumedEvent, x as BreakpointState, y as BreakpointType, C as Checkpoint, z as CheckpointContext, E as CheckpointDiff, F as CheckpointLocalState, H as CheckpointProgress, J as CheckpointRestoreEvent, K as CheckpointSaveEvent, L as CheckpointStore, N as ConstraintEvaluateEvent, P as CrossAgentDerivationFn, Q as CrossAgentSnapshot, U as DagCheckpointState, V as DagExecutionContext, W as DagNode, X as DagNodeStatus, Y as DagNodeUpdateEvent, Z as DagPattern, _ as DebateCheckpointState, $ as DebateRoundEvent, a0 as DebugEventBase, a1 as DebugEventType, a2 as DerivationUpdateEvent, a3 as GoalCheckpointConfig, a4 as GoalCheckpointState, a5 as GoalMetrics, a6 as GoalNode, a7 as GoalPattern, a8 as GoalStepMetrics, a9 as GuardrailCheckEvent, aa as GuardrailContext, ab as GuardrailError, ac as GuardrailErrorCode, ad as GuardrailResult, ae as GuardrailRetryConfig, af as GuardrailsConfig, ag as HandoffCompleteEvent, ah as HandoffStartEvent, ai as HealthMonitorConfig, aj as InMemoryCheckpointStore, ak as InMemoryCheckpointStoreOptions, al as MAX_BREAKPOINT_HISTORY, am as MultiAgentBreakpointType, an as MultiAgentCheckpointLocalState, ao as MultiAgentLifecycleHooks, ap as MultiAgentSelfHealingConfig, aq as NamedGuardrail, ar as OrchestratorConstraint, as as OrchestratorDebugConfig, at as OrchestratorLifecycleHooks, au as OrchestratorResolver, av as OrchestratorResolverContext, aw as OrchestratorState, ax as PatternCheckpointBase, ay as PatternCheckpointConfig, az as PatternCheckpointState, aA as PatternCompleteEvent, aB as PatternStartEvent, aC as RaceCancelledEvent, aD as RaceStartEvent, aE as RaceWinnerEvent, aF as ReflectCheckpointState, aG as ReflectionIterationEvent, aH as RejectedRequest, aI as RelaxationContext, aJ as RelaxationRecord, aK as RelaxationStrategy, aL as RelaxationTier, aM as RerouteDebugEvent, aN as RerouteEvent, aO as ResolverCompleteEvent, aP as ResolverErrorEvent, aQ as ResolverStartEvent, aR as SchemaValidationResult, aS as Scratchpad, aT as ScratchpadUpdateEvent, aU as SelfHealingConfig, aV as SequentialCheckpointState, aW as SingleAgentCheckpointLocalState, aX as StreamingCallbackRunner, aY as SupervisorCheckpointState, aZ as TokenUsage, a_ as ToolCall, a$ as createBreakpointId, b0 as createCheckpointId, b1 as createInitialBreakpointState, b2 as isGuardrailError, b3 as matchBreakpoint, b4 as validateCheckpoint } from './types-Co4BzMiH.cjs';
+import { E as ExecutionPattern, S as SerializedPattern, A as AgentHealthMetrics, D as DebugTimeline, H as HealthMonitor } from './multi-agent-orchestrator-CxL8ycw_.cjs';
+export { a as AgentMemory, b as AgentMemoryConfig, c as AgentOrchestrator, d as AgentRegistration, e as AgentRegistry, B as BackpressureStrategy, f as DebateConfig, g as DebatePattern, h as DebateResult, i as DebugTimelineListener, j as DebugTimelineOptions, k as DoneChunk, l as ErrorChunk, G as GuardrailTriggeredChunk, m as HandoffRequest, n as HandoffResult, o as HealthCircuitState, M as MemoryManageResult, p as MemoryState, q as MemoryStrategy, r as MemoryStrategyConfig, s as MemoryStrategyResult, t as MergedTaggedStreamResult, u as MessageChunk, v as MessageSummarizer, w as MultiAgentOrchestrator, x as MultiAgentOrchestratorOptions, y as MultiAgentRunCallOptions, z as MultiAgentState, C as MultiplexedStreamChunk, F as MultiplexedStreamResult, O as OrchestratorOptions, I as OrchestratorStreamChunk, J as OrchestratorStreamResult, P as ParallelPattern, K as ProgressChunk, R as RacePattern, L as RaceResult, N as RaceSuccessEntry, Q as ReflectIterationRecord, T as ReflectPattern, U as ReflectionConfig, V as ReflectionContext, W as ReflectionEvaluation, X as ReflectionEvaluator, Y as ReflectionExhaustedError, Z as RunAgentRequirement, _ as RunCallOptions, $ as SafeParseResult, a0 as SafeParseable, a1 as Semaphore, a2 as SequentialPattern, a3 as SerializedDagNode, a4 as SerializedGoalNode, a5 as SpawnOnConditionOptions, a6 as SpawnPoolConfig, a7 as StreamChunk, a8 as StreamRunOptions, a9 as StreamRunner, aa as StreamingGuardrail, ab as StreamingGuardrailResult, ac as StreamingRunResult, ad as StructuredOutputConfig, ae as StructuredOutputError, af as SupervisorPattern, ag as TokenChunk, ah as ToolEndChunk, ai as ToolStartChunk, aj as adaptOutputGuardrail, ak as aggregateTokens, al as allReadyStrategy, am as capabilityRoute, an as collectOutputs, ao as collectTokens, ap as combineStreamingGuardrails, aq as composePatterns, ar as concatResults, as as costEfficientStrategy, at as createAgentMemory, au as createAgentOrchestrator, av as createDebugTimeline, aw as createDebugTimelinePlugin, ax as createHealthMonitor, ay as createHybridStrategy, az as createKeyPointsSummarizer, aA as createLLMSummarizer, aB as createLengthStreamingGuardrail, aC as createMultiAgentOrchestrator, aD as createPatternStreamingGuardrail, aE as createSlidingWindowStrategy, aF as createStreamingRunner, aG as createTokenBasedStrategy, aH as createToxicityStreamingGuardrail, aI as createTruncationSummarizer, aJ as dag, aK as debate, aL as derivedConstraint, aM as diffCheckpoints, aN as extractJsonFromOutput, aO as filterStream, aP as findAgentsByCapability, aQ as forkFromCheckpoint, aR as getCheckpointProgress, aS as getPatternStep, aT as goal, aU as highestImpactStrategy, aV as mapStream, aW as mergeTaggedStreams, aX as parallel, aY as patternFromJSON, aZ as patternToJSON, a_ as pickBestResult, a$ as race, b0 as reflect, b1 as runAgentRequirement, b2 as runDebate, b3 as selectAgent, b4 as sequential, b5 as spawnOnCondition, b6 as spawnPool, b7 as supervisor, b8 as tapStream, b9 as withReflection, ba as withStructuredOutput } from './multi-agent-orchestrator-CxL8ycw_.cjs';
 export { AggregatedMetric, AlertConfig, AlertEvent, CircuitBreaker, CircuitBreakerConfig, CircuitBreakerOpenError, CircuitBreakerStats, CircuitState, DashboardData, MetricDataPoint, MetricType, OTLPExporter, OTLPExporterConfig, ObservabilityConfig, ObservabilityInstance, TraceSpan, createAgentMetrics, createCircuitBreaker, createOTLPExporter, createObservability } from '@directive-run/core/plugins';
-import { M as Message$1, g as RunResult, b as AgentLike, d as GuardrailFn, O as OutputGuardrailData, I as InputGuardrailData, S as SchemaValidator, T as ToolCallGuardrailData, f as AdapterHooks, c as AgentRunner, h as ApprovalState, i as AgentState, j as OrchestratorState, k as OrchestratorConstraint, R as RunOptions, N as NamedGuardrail, l as OrchestratorResolver, A as ApprovalRequest, m as AgentRetryConfig, n as OrchestratorLifecycleHooks, o as GuardrailsConfig } from './types-Bbar7yKz.cjs';
-export { e as GuardrailContext, p as GuardrailError, q as GuardrailErrorCode, G as GuardrailResult, r as GuardrailRetryConfig, s as OrchestratorResolverContext, t as RejectedRequest, u as SchemaValidationResult, v as TokenUsage, a as ToolCall, w as isGuardrailError } from './types-Bbar7yKz.cjs';
-
-/**
- * Agent Memory System
- *
- * Provides sliding window message management and automatic summarization
- * for long-running agent conversations.
- *
- * @example
- * ```typescript
- * import { createAgentMemory, createSlidingWindowStrategy } from '@directive-run/ai';
- *
- * const memory = createAgentMemory({
- *   strategy: createSlidingWindowStrategy({ maxMessages: 50 }),
- *   summarizer: async (messages) => {
- *     // Call LLM to summarize older messages
- *     return await summarizeWithLLM(messages);
- *   },
- * });
- *
- * // Use with orchestrator
- * const orchestrator = createAgentOrchestrator({
- *   memory,
- *   runner: run,
- * });
- * ```
- */
-/**
- * Memory-compatible message type.
- * Extends the standard Message type to include system messages for summaries.
- */
-interface MemoryMessage {
-    role: "user" | "assistant" | "tool" | "system";
-    content: string;
-    toolCallId?: string;
-}
-type Message = MemoryMessage;
-/** Configuration for memory management strategies */
-interface MemoryStrategyConfig {
-    /** Maximum number of messages to keep in active memory */
-    maxMessages?: number;
-    /** Maximum total tokens to keep in active memory */
-    maxTokens?: number;
-    /** Number of recent messages to always keep (protected from summarization) */
-    preserveRecentCount?: number;
-    /** Whether to include system messages in token count */
-    countSystemMessages?: boolean;
-}
-/** Result of a memory strategy evaluation */
-interface MemoryStrategyResult {
-    /** Messages to keep in active memory */
-    keep: Message[];
-    /** Messages to summarize or discard */
-    toSummarize: Message[];
-    /** Estimated token count of kept messages */
-    estimatedTokens: number;
-}
-/** Memory management strategy function */
-type MemoryStrategy = (messages: Message[], config: MemoryStrategyConfig) => MemoryStrategyResult;
-/** Summarizer function to compress older messages */
-type MessageSummarizer = (messages: Message[]) => Promise<string>;
-/** Agent memory configuration */
-interface AgentMemoryConfig {
-    /** Memory management strategy */
-    strategy: MemoryStrategy;
-    /** Optional summarizer for compressing old messages */
-    summarizer?: MessageSummarizer;
-    /** Strategy configuration */
-    strategyConfig?: MemoryStrategyConfig;
-    /** Whether to auto-manage memory after each interaction */
-    autoManage?: boolean;
-    /** Callback when memory is managed */
-    onMemoryManaged?: (result: MemoryManageResult) => void;
-    /** Callback when auto-manage encounters an error */
-    onManageError?: (error: Error) => void;
-    /** Maximum context window tokens (triggers additional summarization if exceeded) */
-    maxContextTokens?: number;
-}
-/** Result of memory management */
-interface MemoryManageResult {
-    /** Number of messages before management */
-    messagesBefore: number;
-    /** Number of messages after management */
-    messagesAfter: number;
-    /** Number of messages summarized */
-    messagesSummarized: number;
-    /** The summary that was generated (if any) */
-    summary?: string;
-    /** Estimated tokens before */
-    estimatedTokensBefore: number;
-    /** Estimated tokens after */
-    estimatedTokensAfter: number;
-}
-/** Memory state for a conversation */
-interface MemoryState {
-    /** Active messages in memory */
-    messages: Message[];
-    /** Summaries of older messages */
-    summaries: Array<{
-        content: string;
-        messagesCount: number;
-        createdAt: number;
-    }>;
-    /** Total messages ever processed */
-    totalMessagesProcessed: number;
-    /** Estimated current token count */
-    estimatedTokens: number;
-}
-/** Agent memory instance */
-interface AgentMemory {
-    /** Get current memory state */
-    getState(): MemoryState;
-    /** Add a message to memory */
-    addMessage(message: Message): void;
-    /** Check if memory management is currently in progress */
-    isManaging(): boolean;
-    /** Add multiple messages to memory */
-    addMessages(messages: Message[]): void;
-    /** Get messages for context (includes summaries as system messages) */
-    getContextMessages(): Message[];
-    /** Manually trigger memory management */
-    manage(): Promise<MemoryManageResult>;
-    /** Clear all memory */
-    clear(): void;
-    /** Export memory state for persistence */
-    export(): MemoryState;
-    /** Import memory state from persistence */
-    import(state: MemoryState): void;
-}
-/**
- * Create a sliding window memory strategy.
- *
- * Keeps the most recent N messages, moving older ones to summarization.
- *
- * @example
- * ```typescript
- * const strategy = createSlidingWindowStrategy({
- *   maxMessages: 50,
- *   preserveRecentCount: 10,
- * });
- * ```
- */
-declare function createSlidingWindowStrategy(defaultConfig?: MemoryStrategyConfig): MemoryStrategy;
-/**
- * Create a token-based memory strategy.
- *
- * Keeps messages until a token limit is reached, then moves older ones to summarization.
- *
- * @example
- * ```typescript
- * const strategy = createTokenBasedStrategy({
- *   maxTokens: 4000,
- *   preserveRecentCount: 5,
- * });
- * ```
- */
-declare function createTokenBasedStrategy(defaultConfig?: MemoryStrategyConfig): MemoryStrategy;
-/**
- * Create a hybrid strategy that combines message count and token limits.
- *
- * @example
- * ```typescript
- * const strategy = createHybridStrategy({
- *   maxMessages: 50,
- *   maxTokens: 4000,
- *   preserveRecentCount: 5,
- * });
- * ```
- */
-declare function createHybridStrategy(defaultConfig?: MemoryStrategyConfig): MemoryStrategy;
-/**
- * Create an agent memory instance.
- *
- * @example
- * ```typescript
- * const memory = createAgentMemory({
- *   strategy: createSlidingWindowStrategy({ maxMessages: 50 }),
- *   summarizer: async (messages) => {
- *     const response = await openai.chat.completions.create({
- *       model: 'gpt-4o-mini',
- *       messages: [
- *         { role: 'system', content: 'Summarize the following conversation concisely.' },
- *         ...messages.map(m => ({ role: m.role, content: m.content })),
- *       ],
- *     });
- *     return response.choices[0].message.content;
- *   },
- *   autoManage: true,
- * });
- * ```
- */
-declare function createAgentMemory(config: AgentMemoryConfig): AgentMemory;
-/**
- * Create a simple truncation "summarizer" that just returns key points.
- * Useful for testing or when LLM summarization isn't needed.
- */
-declare function createTruncationSummarizer(maxLength?: number): MessageSummarizer;
-/**
- * Create a summarizer that extracts only user questions and key assistant answers.
- */
-declare function createKeyPointsSummarizer(): MessageSummarizer;
-/**
- * Create a summarizer factory for LLM-based summarization.
- * You provide the LLM call function, this handles the prompt.
- *
- * @example
- * ```typescript
- * const summarizer = createLLMSummarizer(async (prompt) => {
- *   const response = await openai.chat.completions.create({
- *     model: 'gpt-4o-mini',
- *     messages: [{ role: 'user', content: prompt }],
- *   });
- *   return response.choices[0].message.content ?? '';
- * });
- * ```
- */
-declare function createLLMSummarizer(llmCall: (prompt: string) => Promise<string>, options?: {
-    maxSummaryLength?: number;
-    preserveKeyFacts?: boolean;
-}): MessageSummarizer;
-
-/**
- * OpenAI Agents Streaming - Token-by-token streaming with backpressure support
- *
- * Provides async iterators for streaming agent responses with guardrail evaluation
- * on partial output and configurable backpressure handling.
- *
- * @example
- * ```typescript
- * import { createAgentOrchestrator } from '@directive-run/ai';
- * import { createStreamingRunner } from '@directive-run/ai';
- *
- * const { stream, result } = orchestrator.runStream(agent, input);
- *
- * for await (const chunk of stream) {
- *   if (chunk.type === 'token') process.stdout.write(chunk.data);
- *   if (chunk.type === 'guardrail_triggered') handleGuardrail(chunk);
- * }
- *
- * const finalResult = await result;
- * ```
- */
-
-/** Token chunk from streaming response */
-interface TokenChunk {
-    type: "token";
-    data: string;
-    /** Running total of tokens received */
-    tokenCount: number;
-}
-/** Tool execution started */
-interface ToolStartChunk {
-    type: "tool_start";
-    tool: string;
-    toolCallId: string;
-    arguments: string;
-}
-/** Tool execution completed */
-interface ToolEndChunk {
-    type: "tool_end";
-    tool: string;
-    toolCallId: string;
-    result: string;
-}
-/** Message added to conversation */
-interface MessageChunk {
-    type: "message";
-    message: Message$1;
-}
-/** Guardrail was triggered during streaming */
-interface GuardrailTriggeredChunk {
-    type: "guardrail_triggered";
-    guardrailName: string;
-    reason: string;
-    /** Partial output at the time of trigger */
-    partialOutput: string;
-    /** Whether the stream was stopped */
-    stopped: boolean;
-}
-/** Progress update for UI feedback */
-interface ProgressChunk {
-    type: "progress";
-    phase: "starting" | "generating" | "tool_calling" | "finishing";
-    /** Percentage complete (0-100), if known */
-    percent?: number;
-    /** Human-readable status message */
-    message?: string;
-}
-/** Stream completed */
-interface DoneChunk {
-    type: "done";
-    totalTokens: number;
-    duration: number;
-    /** Number of tokens dropped due to backpressure (only with 'drop' strategy) */
-    droppedTokens: number;
-}
-/** Error during streaming */
-interface ErrorChunk {
-    type: "error";
-    error: Error;
-    /** Partial output before error */
-    partialOutput?: string;
-}
-/** Union of all stream chunk types */
-type StreamChunk = TokenChunk | ToolStartChunk | ToolEndChunk | MessageChunk | GuardrailTriggeredChunk | ProgressChunk | DoneChunk | ErrorChunk;
-/** Backpressure strategy when consumer is slow */
-type BackpressureStrategy = 
-/** Drop tokens when buffer is full (lossy, fast) */
-"drop"
-/** Block producer when buffer is full (lossless, may slow response) */
- | "block"
-/** Buffer all tokens (lossless, uses memory) */
- | "buffer";
-/** Streaming run options */
-interface StreamRunOptions {
-    /** Maximum turns before stopping */
-    maxTurns?: number;
-    /** Abort signal for cancellation */
-    signal?: AbortSignal;
-    /** Backpressure strategy (default: 'buffer') */
-    backpressure?: BackpressureStrategy;
-    /** Buffer size for 'drop' and 'block' strategies */
-    bufferSize?: number;
-    /** Evaluate guardrails every N tokens (default: 50) */
-    guardrailCheckInterval?: number;
-    /** Stop stream on guardrail trigger (default: true for critical) */
-    stopOnGuardrail?: boolean | ((chunk: GuardrailTriggeredChunk) => boolean);
-}
-/** Stream run function type (mirrors OpenAI Agents streaming API) */
-type StreamRunner = <T = unknown>(agent: AgentLike, input: string, options?: StreamRunOptions) => StreamingRunResult<T>;
-/** Result from a streaming run */
-interface StreamingRunResult<T = unknown> {
-    /** Async iterator for streaming chunks */
-    stream: AsyncIterable<StreamChunk>;
-    /** Promise that resolves to the final result */
-    result: Promise<RunResult<T>>;
-    /** Abort the stream */
-    abort: () => void;
-}
-/** Streaming guardrail that evaluates partial output */
-interface StreamingGuardrail {
-    /** Unique name for this guardrail */
-    name: string;
-    /** Check partial output (called every guardrailCheckInterval tokens) */
-    check: (partialOutput: string, tokenCount: number) => StreamingGuardrailResult | Promise<StreamingGuardrailResult>;
-    /** Whether to stop the stream on failure (default: true) */
-    stopOnFail?: boolean;
-}
-/** Result from a streaming guardrail check */
-interface StreamingGuardrailResult {
-    passed: boolean;
-    reason?: string;
-    /** Severity level for UI display */
-    severity?: "warning" | "error" | "critical";
-    /** Warning message (guardrail passed but wants to emit a warning) */
-    warning?: string;
-}
-/**
- * Create a streaming runner that wraps a base run function.
- * This is used internally by the orchestrator but can be used standalone.
- *
- * @param baseRunner - The underlying non-streaming runner
- * @param options - Configuration options
- */
-declare function createStreamingRunner(baseRunner: (agent: AgentLike, input: string, callbacks: {
-    onToken?: (token: string) => void;
-    onToolStart?: (tool: string, id: string, args: string) => void;
-    onToolEnd?: (tool: string, id: string, result: string) => void;
-    onMessage?: (message: Message$1) => void;
-    signal?: AbortSignal;
-}) => Promise<RunResult<unknown>>, options?: {
-    streamingGuardrails?: StreamingGuardrail[];
-}): StreamRunner;
-/**
- * Create a streaming guardrail that detects toxic content.
- *
- * @example
- * ```typescript
- * const toxicityGuardrail = createToxicityStreamingGuardrail({
- *   threshold: 0.9,
- *   checkFn: async (text) => myToxicityModel.score(text),
- * });
- * ```
- */
-declare function createToxicityStreamingGuardrail(options: {
-    /** Toxicity scoring function (returns 0-1) */
-    checkFn: (text: string) => number | Promise<number>;
-    /** Threshold above which content is flagged (default: 0.8) */
-    threshold?: number;
-    /** Stop the stream on detection (default: true) */
-    stopOnFail?: boolean;
-}): StreamingGuardrail;
-/**
- * Create a streaming guardrail that limits output length.
- *
- * @example
- * ```typescript
- * const lengthGuardrail = createLengthStreamingGuardrail({
- *   maxTokens: 4000,
- *   warnAt: 3500,
- * });
- * ```
- */
-declare function createLengthStreamingGuardrail(options: {
-    /** Maximum tokens before stopping */
-    maxTokens: number;
-    /** Warn at this token count (optional) */
-    warnAt?: number;
-    /** Stop the stream on max (default: true) */
-    stopOnFail?: boolean;
-}): StreamingGuardrail;
-/**
- * Create a streaming guardrail that detects patterns (regex-based).
- *
- * @example
- * ```typescript
- * const piiGuardrail = createPatternStreamingGuardrail({
- *   patterns: [
- *     { regex: /\b\d{3}-\d{2}-\d{4}\b/, name: 'SSN' },
- *     { regex: /\b\d{16}\b/, name: 'Credit Card' },
- *   ],
- *   stopOnFail: true,
- * });
- * ```
- */
-declare function createPatternStreamingGuardrail(options: {
-    patterns: Array<{
-        regex: RegExp;
-        name: string;
-    }>;
-    stopOnFail?: boolean;
-}): StreamingGuardrail;
-/**
- * Combine multiple streaming guardrails into one.
- *
- * @example
- * ```typescript
- * const combined = combineStreamingGuardrails([
- *   createToxicityStreamingGuardrail({ ... }),
- *   createLengthStreamingGuardrail({ ... }),
- * ]);
- * ```
- */
-declare function combineStreamingGuardrails(guardrails: StreamingGuardrail[], options?: {
-    name?: string;
-    stopOnFirstFail?: boolean;
-}): StreamingGuardrail;
-/**
- * Convert a regular output guardrail to a streaming guardrail.
- * Useful for reusing existing guardrails in streaming context.
- *
- * @example
- * ```typescript
- * const streamingPII = adaptOutputGuardrail(
- *   "pii-streaming",
- *   createPIIGuardrail({ redact: false }),
- *   { checkInterval: 100 }
- * );
- * ```
- */
-declare function adaptOutputGuardrail(name: string, guardrail: GuardrailFn<OutputGuardrailData>, options?: {
-    /** Only run after this many tokens (optimization) */
-    minTokens?: number;
-    stopOnFail?: boolean;
-}): StreamingGuardrail;
-/**
- * Collect all tokens from a stream into a string.
- *
- * @example
- * ```typescript
- * const { stream, result } = orchestrator.runStream(agent, input);
- * const fullOutput = await collectTokens(stream);
- * ```
- */
-declare function collectTokens(stream: AsyncIterable<StreamChunk>): Promise<string>;
-/**
- * Tap into a stream without consuming it.
- * Useful for logging or side effects.
- *
- * @example
- * ```typescript
- * const { stream } = orchestrator.runStream(agent, input);
- * const tapped = tapStream(stream, (chunk) => console.log(chunk));
- * for await (const chunk of tapped) { ... }
- * ```
- */
-declare function tapStream(stream: AsyncIterable<StreamChunk>, fn: (chunk: StreamChunk) => void | Promise<void>): AsyncIterable<StreamChunk>;
-/**
- * Filter stream chunks by type.
- *
- * @example
- * ```typescript
- * const tokensOnly = filterStream(stream, ['token']);
- * ```
- */
-declare function filterStream<T extends StreamChunk["type"]>(stream: AsyncIterable<StreamChunk>, types: T[]): AsyncIterable<Extract<StreamChunk, {
-    type: T;
-}>>;
-/**
- * Transform stream chunks.
- *
- * @example
- * ```typescript
- * const upperTokens = mapStream(stream, (chunk) => {
- *   if (chunk.type === 'token') return { ...chunk, data: chunk.data.toUpperCase() };
- *   return chunk;
- * });
- * ```
- */
-declare function mapStream<R>(stream: AsyncIterable<StreamChunk>, fn: (chunk: StreamChunk) => R | Promise<R>): AsyncIterable<R>;
+import { ModuleSchema, Plugin } from '@directive-run/core';
+import { E as Embedding, a as EmbedderFn } from './semantic-cache-F0psCRuz.cjs';
+export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as CacheStats, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-F0psCRuz.cjs';
 
 /**
  * Built-in guardrails for AI adapter — PII, moderation, rate limiting, tool allowlists, schema validation.
@@ -632,7 +126,7 @@ declare function createContentFilterGuardrail(options: {
 }): GuardrailFn<OutputGuardrailData>;
 
 /**
- * Helper functions for AI adapter — createRunner, estimateCost, state queries, validation.
+ * Agent utilities — createRunner, estimateCost, state queries, URL validation.
  */
 
 /** Check if agent is currently running. */
@@ -664,11 +158,11 @@ interface ParsedResponse {
 /** Options for creating an AgentRunner from buildRequest/parseResponse */
 interface CreateRunnerOptions {
     fetch?: typeof globalThis.fetch;
-    buildRequest: (agent: AgentLike, input: string, messages: Message$1[]) => {
+    buildRequest: (agent: AgentLike, input: string, messages: Message[]) => {
         url: string;
         init: RequestInit;
     };
-    parseResponse: (response: Response, messages: Message$1[]) => Promise<ParsedResponse>;
+    parseResponse: (response: Response, messages: Message[]) => Promise<ParsedResponse>;
     parseOutput?: <T>(text: string) => T;
     /** Lifecycle hooks for tracing, logging, and metrics */
     hooks?: AdapterHooks;
@@ -719,490 +213,124 @@ interface CreateRunnerOptions {
 declare function createRunner(options: CreateRunnerOptions): AgentRunner;
 
 /**
- * Constraint Helper Functions — Ergonomic builders for OrchestratorConstraint
+ * Middleware composition utility — left-to-right pipeline for AgentRunner wrappers.
+ *
+ * Each middleware is a function that takes an `AgentRunner` and returns a new
+ * `AgentRunner`. `pipe` applies them left to right, so the first middleware
+ * in the list wraps the runner first (innermost), and the last wraps last
+ * (outermost).
+ *
+ * @module
  *
  * @example
  * ```typescript
- * import { constraint, when } from '@directive-run/ai';
- *
- * constraints: {
- *   // Builder pattern
- *   escalate: constraint<MyFacts>()
- *     .when(f => f.confidence < 0.7)
- *     .require({ type: 'ESCALATE' })
- *     .priority(50)
- *     .build(),
- *
- *   // Quick shorthand
- *   pause: when<MyFacts>(f => f.errors > 3)
- *     .require({ type: 'PAUSE' }),
- * }
+ * import { pipe, withRetry, withFallback, withBudget } from '@directive-run/ai';
+ *
+ * const runner = pipe(
+ *   baseRunner,
+ *   withFallback([anthropicRunner, openaiRunner]),
+ *   withRetry({ maxRetries: 3 }),
+ *   withBudget({ budgets: [{ window: 'hour', maxCost: 5, pricing }] }),
+ * );
  * ```
  */
 
-interface ConstraintBuilderWithWhen<F extends Record<string, unknown>> {
-    require(req: Requirement | ((facts: F & OrchestratorState) => Requirement)): ConstraintBuilderWithRequire<F>;
-}
-interface ConstraintBuilderWithRequire<F extends Record<string, unknown>> {
-    priority(p: number): ConstraintBuilderWithRequire<F>;
-    build(): OrchestratorConstraint<F>;
-}
-interface ConstraintBuilder<F extends Record<string, unknown>> {
-    when(condition: (facts: F & OrchestratorState) => boolean | Promise<boolean>): ConstraintBuilderWithWhen<F>;
-}
+/** A function that wraps an AgentRunner, returning a new AgentRunner. */
+type RunnerMiddleware = (runner: AgentRunner) => AgentRunner;
 /**
- * Fluent builder for creating orchestrator constraints.
+ * Compose middleware left-to-right onto a base runner.
  *
- * @example
- * ```typescript
- * const myConstraint = constraint<MyFacts>()
- *   .when(f => f.confidence < 0.7)
- *   .require({ type: 'ESCALATE' })
- *   .priority(50)
- *   .build();
- * ```
+ * @param runner - The base `AgentRunner` to wrap.
+ * @param middlewares - One or more middleware functions to apply in order.
+ * @returns A new `AgentRunner` with all middleware applied.
  */
-declare function constraint<F extends Record<string, unknown> = Record<string, never>>(): ConstraintBuilder<F>;
-interface WhenResult<F extends Record<string, unknown>> {
-    require(req: Requirement | ((facts: F & OrchestratorState) => Requirement)): WhenWithRequire<F>;
+declare function pipe(runner: AgentRunner, ...middlewares: RunnerMiddleware[]): AgentRunner;
+
+type MermaidDirection = "LR" | "TD" | "TB" | "RL" | "BT";
+interface MermaidNodeShapes {
+    /** Shape for agent nodes. @default "square" */
+    agent?: "square" | "round" | "stadium" | "hexagon";
+    /** Shape for virtual nodes (Input, Output, Merge). @default "circle" */
+    virtual?: "circle" | "square" | "round" | "stadium";
 }
-/**
- * Result of `when().require()` — a valid `OrchestratorConstraint<F>` directly,
- * or chain `.withPriority(n)` to get a constraint with priority set.
- */
-interface WhenWithRequire<F extends Record<string, unknown>> extends OrchestratorConstraint<F> {
-    /** Return a new constraint with the given priority */
-    withPriority(p: number): OrchestratorConstraint<F>;
+interface MermaidOptions {
+    /** Graph flow direction. @default "LR" */
+    direction?: MermaidDirection;
+    /** Emits %%{init}%% preamble when set. */
+    theme?: "default" | "dark" | "forest" | "neutral";
+    /** Node shape overrides. */
+    shapes?: MermaidNodeShapes;
 }
 /**
- * Quick shorthand for creating simple constraints.
- * The returned object is a valid `OrchestratorConstraint<F>` — use directly
- * or chain `.withPriority(n)` to set priority.
+ * Convert an execution pattern to a Mermaid diagram string.
+ *
+ * Accepts both runtime `ExecutionPattern` (with function callbacks) and
+ * pre-serialized `SerializedPattern`. Normalizes internally via `patternToJSON()`
+ * when it detects function-valued fields.
  *
  * @example
  * ```typescript
- * const myConstraint = when<MyFacts>(f => f.errors > 3)
- *   .require({ type: 'PAUSE' });
- *
- * // With priority
- * const urgent = when<MyFacts>(f => f.critical)
- *   .require({ type: 'HALT' })
- *   .withPriority(100);
+ * const p = dag({ fetch: { agent: "fetcher" }, report: { agent: "reporter", deps: ["fetch"] } });
+ * console.log(patternToMermaid(p, { direction: "TD" }));
+ * // graph TD
+ * //   fetch[fetcher]
+ * //   fetch[fetcher] --> report[reporter]
  * ```
+ *
+ * @throws {Error} If pattern type is not one of the 8 known types.
  */
-declare function when<F extends Record<string, unknown> = Record<string, never>>(condition: (facts: F & OrchestratorState) => boolean | Promise<boolean>): WhenResult<F>;
+declare function patternToMermaid(pattern: ExecutionPattern<unknown> | SerializedPattern, options?: MermaidOptions): string;
 
 /**
- * Multi-Agent Orchestration Patterns
+ * Agent-to-Agent Communication Protocol
  *
- * Provides patterns for coordinating multiple AI agents:
- * - Parallel execution with result merging
- * - Sequential pipelines
- * - Supervisor patterns with worker delegation
- * - Constraint-driven agent selection
+ * Provides structured communication channels between agents for coordination,
+ * delegation, and knowledge sharing without central orchestration.
  *
  * @example
  * ```typescript
- * import { createMultiAgentOrchestrator } from '@directive-run/ai';
+ * import { createAgentNetwork, createMessageBus } from '@directive-run/ai';
  *
- * const orchestrator = createMultiAgentOrchestrator({
+ * const messageBus = createMessageBus();
+ *
+ * const network = createAgentNetwork({
+ *   bus: messageBus,
  *   agents: {
- *     researcher: { agent: researchAgent, maxConcurrent: 3 },
- *     writer: { agent: writerAgent, maxConcurrent: 1 },
- *     reviewer: { agent: reviewerAgent, maxConcurrent: 1 },
- *   },
- *   patterns: {
- *     parallelResearch: {
- *       type: 'parallel',
- *       agents: ['researcher', 'researcher', 'researcher'],
- *       merge: (results) => combineResearch(results),
- *     },
+ *     researcher: { capabilities: ['search', 'analyze'] },
+ *     writer: { capabilities: ['draft', 'edit'] },
+ *     reviewer: { capabilities: ['review', 'approve'] },
  *   },
  * });
- * ```
- */
-
-/**
- * Async semaphore for controlling concurrent access.
- * Uses a queue-based approach instead of polling for efficiency.
- *
- * @example
- * ```typescript
- * import { Semaphore } from '@directive-run/ai';
  *
- * const sem = new Semaphore(3); // Allow 3 concurrent operations
- *
- * async function doWork() {
- *   const release = await sem.acquire();
- *   try {
- *     await performWork();
- *   } finally {
- *     release();
- *   }
- * }
+ * // Agents can send messages to each other
+ * await network.send('researcher', 'writer', {
+ *   type: 'DELEGATION',
+ *   task: 'Draft an article based on this research',
+ *   context: { findings: [...] },
+ * });
  * ```
  */
-declare class Semaphore {
-    private count;
-    private readonly maxPermits;
-    private readonly queue;
-    constructor(max: number);
-    acquire(): Promise<() => void>;
-    private release;
-    /** Get current available permits */
-    get available(): number;
-    /** Get number of waiters in queue */
-    get waiting(): number;
-    /** Get maximum permits */
-    get max(): number;
-    /** Reject all pending waiters with an error and reset permits */
-    drain(): void;
-}
-/** Configuration for a registered agent */
-interface AgentRegistration {
-    /** The agent instance */
-    agent: AgentLike;
-    /** Maximum concurrent runs for this agent (default: 1) */
-    maxConcurrent?: number;
-    /** Timeout for agent runs (ms) */
-    timeout?: number;
-    /** Custom run options */
-    runOptions?: Omit<RunOptions, "signal">;
-    /** Description for constraint-based selection */
-    description?: string;
-    /** Capabilities this agent has */
-    capabilities?: string[];
-    /** Per-agent output guardrails (applied in addition to stack-level guardrails) */
-    guardrails?: {
-        output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
-    };
-}
-/** Agent registry configuration */
-interface AgentRegistry {
-    [agentId: string]: AgentRegistration;
-}
-/** State of a running agent */
-interface AgentRunState {
-    agentId: string;
-    runId: string;
-    status: "pending" | "running" | "completed" | "error" | "cancelled";
-    input: string;
-    output?: unknown;
-    error?: Error;
-    startedAt?: number;
-    completedAt?: number;
-    tokens: number;
-}
-/** Parallel execution pattern - run agents concurrently and merge results */
-interface ParallelPattern<T = unknown> {
-    type: "parallel";
-    /** Agent IDs to run in parallel (can repeat for multiple instances) */
-    agents: string[];
-    /** Function to merge results from all agents */
-    merge: (results: RunResult<unknown>[]) => T | Promise<T>;
-    /** Minimum successful results required (default: all) */
-    minSuccess?: number;
-    /** Overall timeout (ms) */
-    timeout?: number;
-}
-/** Sequential execution pattern - pipeline of agents */
-interface SequentialPattern<T = unknown> {
-    type: "sequential";
-    /** Agent IDs in execution order */
-    agents: string[];
-    /** Transform output to next input (default: stringify) */
-    transform?: (output: unknown, agentId: string, index: number) => string;
-    /** Final result extractor */
-    extract?: (output: unknown) => T;
-    /** Continue on error (default: false) */
-    continueOnError?: boolean;
-}
-/** Supervisor pattern - one agent directs others */
-interface SupervisorPattern<T = unknown> {
-    type: "supervisor";
-    /** Supervisor agent ID */
-    supervisor: string;
-    /** Worker agent IDs */
-    workers: string[];
-    /** Maximum delegation rounds */
-    maxRounds?: number;
-    /** Extract final result */
-    extract?: (supervisorOutput: unknown, workerResults: RunResult<unknown>[]) => T;
-}
-/** Union of all patterns */
-type ExecutionPattern<T = unknown> = ParallelPattern<T> | SequentialPattern<T> | SupervisorPattern<T>;
-/** Handoff request between agents */
-interface HandoffRequest {
+/** Base message structure */
+interface AgentMessage {
     id: string;
-    fromAgent: string;
-    toAgent: string;
-    input: string;
-    context?: Record<string, unknown>;
-    requestedAt: number;
+    type: AgentMessageType;
+    from: string;
+    to: string | string[] | "*";
+    timestamp: number;
+    correlationId?: string;
+    replyTo?: string;
+    priority?: "low" | "normal" | "high" | "urgent";
+    ttlMs?: number;
+    metadata?: Record<string, unknown>;
 }
-/** Handoff result */
-interface HandoffResult {
-    request: HandoffRequest;
-    result: RunResult<unknown>;
-    completedAt: number;
-}
-/** Constraint for agent selection */
-interface AgentSelectionConstraint {
-    when: (facts: Record<string, unknown>) => boolean | Promise<boolean>;
-    select: string | ((facts: Record<string, unknown>) => string);
-    input: string | ((facts: Record<string, unknown>) => string);
-    priority?: number;
-}
-/** Run agent requirement */
-interface RunAgentRequirement extends Requirement {
-    type: "RUN_AGENT";
-    agent: string;
-    input: string;
-    context?: Record<string, unknown>;
-}
-/** Multi-agent orchestrator options */
-interface MultiAgentOrchestratorOptions {
-    /** Base run function */
-    runner: AgentRunner;
-    /** Registered agents */
-    agents: AgentRegistry;
-    /** Execution patterns */
-    patterns?: Record<string, ExecutionPattern>;
-    /** Handoff callbacks */
-    onHandoff?: (request: HandoffRequest) => void;
-    /** Handoff completion callbacks */
-    onHandoffComplete?: (result: HandoffResult) => void;
-    /** Maximum number of handoff results to retain (default: 1000) */
-    maxHandoffHistory?: number;
-    /** Debug mode */
-    debug?: boolean;
-}
-/** Multi-agent state in facts */
-interface MultiAgentState {
-    /** Namespace for each agent's state */
-    __agents: Record<string, {
-        status: "idle" | "running" | "completed" | "error";
-        lastInput?: string;
-        lastOutput?: unknown;
-        lastError?: string;
-        runCount: number;
-        totalTokens: number;
-    }>;
-    /** Pending handoffs */
-    __handoffs: HandoffRequest[];
-    /** Completed handoffs */
-    __handoffResults: HandoffResult[];
-}
-/** Multi-agent orchestrator instance */
-interface MultiAgentOrchestrator {
-    /** Run a single agent */
-    runAgent<T>(agentId: string, input: string, options?: RunOptions): Promise<RunResult<T>>;
-    /** Run an execution pattern */
-    runPattern<T>(patternId: string, input: string): Promise<T>;
-    /** Run agents in parallel */
-    runParallel<T>(agentIds: string[], inputs: string | string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>): Promise<T>;
-    /** Run agents sequentially */
-    runSequential<T>(agentIds: string[], initialInput: string, options?: {
-        transform?: (output: unknown, agentId: string, index: number) => string;
-    }): Promise<RunResult<T>[]>;
-    /** Request a handoff between agents */
-    handoff(fromAgent: string, toAgent: string, input: string, context?: Record<string, unknown>): Promise<RunResult<unknown>>;
-    /** Get agent state */
-    getAgentState(agentId: string): MultiAgentState["__agents"][string] | undefined;
-    /** Get all agent states */
-    getAllAgentStates(): Record<string, MultiAgentState["__agents"][string]>;
-    /** Get pending handoffs */
-    getPendingHandoffs(): HandoffRequest[];
-    /** Reset all agent states */
-    reset(): void;
-    /** Dispose of the orchestrator, resetting all state */
-    dispose(): void;
-}
-/**
- * Create a multi-agent orchestrator.
- *
- * @example
- * ```typescript
- * const orchestrator = createMultiAgentOrchestrator({
- *   runner,
- *   agents: {
- *     researcher: { agent: researchAgent, maxConcurrent: 3 },
- *     writer: { agent: writerAgent },
- *     reviewer: { agent: reviewerAgent },
- *   },
- *   patterns: {
- *     research: {
- *       type: 'parallel',
- *       agents: ['researcher', 'researcher'],
- *       merge: (results) => results.map(r => r.output).join('\n\n'),
- *     },
- *     write: {
- *       type: 'sequential',
- *       agents: ['writer', 'reviewer'],
- *     },
- *   },
- * });
- *
- * // Run pattern
- * const research = await orchestrator.runPattern('research', 'What is AI?');
- *
- * // Run parallel
- * const results = await orchestrator.runParallel(
- *   ['researcher', 'researcher'],
- *   ['Question 1', 'Question 2'],
- *   (results) => results.map(r => r.output)
- * );
- *
- * // Handoff
- * const reviewed = await orchestrator.handoff('writer', 'reviewer', draft);
- * ```
- *
- * @throws {Error} If a pattern references an agent that is not in the registry
- */
-declare function createMultiAgentOrchestrator(options: MultiAgentOrchestratorOptions): MultiAgentOrchestrator;
-/**
- * Create a parallel pattern configuration.
- *
- * @example
- * ```typescript
- * const researchPattern = parallel(
- *   ['researcher', 'researcher', 'researcher'],
- *   (results) => results.map(r => r.output).join('\n')
- * );
- * ```
- */
-declare function parallel<T>(agents: string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>, options?: {
-    minSuccess?: number;
-    timeout?: number;
-}): ParallelPattern<T>;
-/**
- * Create a sequential pattern configuration.
- *
- * @example
- * ```typescript
- * const writeReviewPattern = sequential(
- *   ['writer', 'reviewer'],
- *   { transform: (output) => `Review this: ${output}` }
- * );
- * ```
- */
-declare function sequential<T>(agents: string[], options?: {
-    transform?: (output: unknown, agentId: string, index: number) => string;
-    extract?: (output: unknown) => T;
-    continueOnError?: boolean;
-}): SequentialPattern<T>;
-/**
- * Create a supervisor pattern configuration.
- *
- * @example
- * ```typescript
- * const managedPattern = supervisor(
- *   'manager',
- *   ['worker1', 'worker2'],
- *   { maxRounds: 3 }
- * );
- * ```
- */
-declare function supervisor<T>(supervisorAgent: string, workers: string[], options?: {
-    maxRounds?: number;
-    extract?: (supervisorOutput: unknown, workerResults: RunResult<unknown>[]) => T;
-}): SupervisorPattern<T>;
-/**
- * Create an agent selection constraint.
- *
- * @example
- * ```typescript
- * const constraints = {
- *   routeToExpert: selectAgent(
- *     (facts) => facts.complexity > 0.8,
- *     'expert',
- *     (facts) => facts.query
- *   ),
- * };
- * ```
- */
-declare function selectAgent(when: (facts: Record<string, unknown>) => boolean | Promise<boolean>, agent: string | ((facts: Record<string, unknown>) => string), input: string | ((facts: Record<string, unknown>) => string), priority?: number): AgentSelectionConstraint;
-/**
- * Create a RUN_AGENT requirement.
- *
- * @example
- * ```typescript
- * constraints: {
- *   needsResearch: {
- *     when: (facts) => facts.hasUnknowns,
- *     require: runAgentRequirement('researcher', facts.query),
- *   },
- * }
- * ```
- */
-declare function runAgentRequirement(agent: string, input: string, context?: Record<string, unknown>): RunAgentRequirement;
-/**
- * Merge results by concatenating outputs.
- */
-declare function concatResults(results: RunResult<unknown>[], separator?: string): string;
-/**
- * Merge results by picking the best one based on a scoring function.
- */
-declare function pickBestResult<T>(results: RunResult<T>[], score: (result: RunResult<T>) => number): RunResult<T>;
-/**
- * Merge results into an array of outputs.
- */
-declare function collectOutputs<T>(results: RunResult<T>[]): T[];
-/**
- * Aggregate token counts from results.
- */
-declare function aggregateTokens(results: RunResult<unknown>[]): number;
-
-/**
- * Agent-to-Agent Communication Protocol
- *
- * Provides structured communication channels between agents for coordination,
- * delegation, and knowledge sharing without central orchestration.
- *
- * @example
- * ```typescript
- * import { createAgentNetwork, createMessageBus } from '@directive-run/ai';
- *
- * const messageBus = createMessageBus();
- *
- * const network = createAgentNetwork({
- *   bus: messageBus,
- *   agents: {
- *     researcher: { capabilities: ['search', 'analyze'] },
- *     writer: { capabilities: ['draft', 'edit'] },
- *     reviewer: { capabilities: ['review', 'approve'] },
- *   },
- * });
- *
- * // Agents can send messages to each other
- * await network.send('researcher', 'writer', {
- *   type: 'DELEGATION',
- *   task: 'Draft an article based on this research',
- *   context: { findings: [...] },
- * });
- * ```
- */
-/** Base message structure */
-interface AgentMessage {
-    id: string;
-    type: AgentMessageType;
-    from: string;
-    to: string | string[] | "*";
-    timestamp: number;
-    correlationId?: string;
-    replyTo?: string;
-    priority?: "low" | "normal" | "high" | "urgent";
-    ttlMs?: number;
-    metadata?: Record<string, unknown>;
-}
-/** Message types for agent communication */
-type AgentMessageType = "REQUEST" | "RESPONSE" | "DELEGATION" | "DELEGATION_RESULT" | "QUERY" | "INFORM" | "SUBSCRIBE" | "UNSUBSCRIBE" | "UPDATE" | "ACK" | "NACK" | "PING" | "PONG" | "CUSTOM";
-/** Request message */
-interface RequestMessage extends AgentMessage {
-    type: "REQUEST";
-    action: string;
-    payload: Record<string, unknown>;
-    timeout?: number;
+/** Message types for agent communication */
+type AgentMessageType = "REQUEST" | "RESPONSE" | "DELEGATION" | "DELEGATION_RESULT" | "QUERY" | "INFORM" | "SUBSCRIBE" | "UNSUBSCRIBE" | "UPDATE" | "ACK" | "NACK" | "PING" | "PONG" | "CUSTOM";
+/** Request message */
+interface RequestMessage extends AgentMessage {
+    type: "REQUEST";
+    action: string;
+    payload: Record<string, unknown>;
+    timeout?: number;
 }
 /** Response message */
 interface ResponseMessage extends AgentMessage {
@@ -1681,7 +809,7 @@ declare function detectPII(text: string, options?: {
  */
 
 /** Audit event types - 17 total covering all system operations */
-type AuditEventType = "agent.run.start" | "agent.run.complete" | "agent.run.error" | "tool.call.start" | "tool.call.complete" | "tool.call.error" | "approval.requested" | "approval.granted" | "approval.denied" | "requirement.created" | "requirement.met" | "resolver.start" | "resolver.complete" | "resolver.error" | "fact.set" | "fact.batch" | "error.occurred" | "error.recovery";
+type AuditEventType = "agent.run.start" | "agent.run.complete" | "agent.run.error" | "tool.call.start" | "tool.call.complete" | "tool.call.error" | "approval.requested" | "approval.granted" | "approval.denied" | "requirement.created" | "requirement.met" | "resolver.start" | "resolver.complete" | "resolver.error" | "fact.set" | "fact.batch" | "error.occurred" | "error.recovery" | "checkpoint.save" | "checkpoint.restore" | "checkpoint.fork" | "checkpoint.replay";
 /** Single audit entry with hash chain linking */
 interface AuditEntry {
     /** Unique identifier for this entry */
@@ -2326,276 +1454,6 @@ declare function createInMemoryComplianceStorage(): ComplianceStorage;
  */
 declare function createCompliance(config: ComplianceConfig): ComplianceInstance;
 
-/**
- * Semantic Caching Guardrail
- *
- * Caches agent responses based on semantic similarity to reduce redundant LLM calls.
- * Uses vector embeddings to find semantically similar previous queries.
- *
- * @example
- * ```typescript
- * import { createSemanticCacheGuardrail } from '@directive-run/ai';
- *
- * const cacheGuardrail = createSemanticCacheGuardrail({
- *   embedder: async (text) => {
- *     // Use your embedding model (OpenAI, local model, etc.)
- *     return await getEmbedding(text);
- *   },
- *   similarityThreshold: 0.95,
- *   maxCacheSize: 1000,
- *   ttlMs: 3600000, // 1 hour
- * });
- *
- * const orchestrator = createAgentOrchestrator({
- *   guardrails: {
- *     input: [cacheGuardrail],
- *   },
- *   runner: run,
- * });
- * ```
- */
-/** Vector embedding (array of numbers) */
-type Embedding = number[];
-/** Function to generate embeddings for text */
-type EmbedderFn = (text: string) => Promise<Embedding>;
-/** Cached response entry */
-interface CacheEntry {
-    id: string;
-    query: string;
-    queryEmbedding: Embedding;
-    response: string;
-    metadata: Record<string, unknown>;
-    createdAt: number;
-    accessedAt: number;
-    accessCount: number;
-    agentName?: string;
-}
-/** Cache lookup result */
-interface CacheLookupResult {
-    hit: boolean;
-    entry?: CacheEntry;
-    similarity?: number;
-    latencyMs: number;
-}
-/** Semantic cache configuration */
-interface SemanticCacheConfig {
-    /** Function to generate embeddings */
-    embedder: EmbedderFn;
-    /** Similarity threshold (0.0 to 1.0) for cache hits */
-    similarityThreshold?: number;
-    /** Maximum number of entries to cache */
-    maxCacheSize?: number;
-    /** Time-to-live in milliseconds for cache entries */
-    ttlMs?: number;
-    /** Cache namespace for multi-tenant scenarios */
-    namespace?: string;
-    /** Custom storage backend (defaults to in-memory) */
-    storage?: SemanticCacheStorage;
-    /** Callback when cache hit occurs */
-    onHit?: (entry: CacheEntry, similarity: number) => void;
-    /** Callback when cache miss occurs */
-    onMiss?: (query: string) => void;
-    /** Callback when cache lookup encounters an error */
-    onError?: (error: Error) => void;
-    /** Whether to include agent name in cache key */
-    perAgent?: boolean;
-}
-/** Storage interface for cache backends */
-interface SemanticCacheStorage {
-    /** Get all entries for a namespace */
-    getEntries(namespace: string): Promise<CacheEntry[]>;
-    /** Add an entry to the cache */
-    addEntry(namespace: string, entry: CacheEntry): Promise<void>;
-    /** Update an entry (e.g., access count) */
-    updateEntry(namespace: string, id: string, updates: Partial<CacheEntry>): Promise<void>;
-    /** Remove an entry */
-    removeEntry(namespace: string, id: string): Promise<void>;
-    /** Clear all entries in a namespace */
-    clear(namespace: string): Promise<void>;
-}
-/** Semantic cache instance */
-interface SemanticCache {
-    /** Look up a query in the cache */
-    lookup(query: string, agentName?: string): Promise<CacheLookupResult>;
-    /** Store a response in the cache */
-    store(query: string, response: string, agentName?: string, metadata?: Record<string, unknown>): Promise<void>;
-    /** Invalidate cache entries matching a predicate */
-    invalidate(predicate: (entry: CacheEntry) => boolean): Promise<number>;
-    /** Clear all cache entries */
-    clear(): Promise<void>;
-    /** Get cache statistics */
-    getStats(): CacheStats;
-    /** Export cache entries (for persistence) */
-    export(): Promise<CacheEntry[]>;
-    /** Import cache entries (from persistence) */
-    import(entries: CacheEntry[]): Promise<void>;
-}
-/** Cache statistics */
-interface CacheStats {
-    totalEntries: number;
-    totalHits: number;
-    totalMisses: number;
-    hitRate: number;
-    avgSimilarityOnHit: number;
-    oldestEntry: number | null;
-    newestEntry: number | null;
-}
-/**
- * Create an in-memory cache storage backend.
- */
-declare function createInMemoryStorage(): SemanticCacheStorage;
-/**
- * Create a semantic cache instance.
- *
- * @example
- * ```typescript
- * const cache = createSemanticCache({
- *   embedder: async (text) => {
- *     const response = await openai.embeddings.create({
- *       model: 'text-embedding-3-small',
- *       input: text,
- *     });
- *     return response.data[0].embedding;
- *   },
- *   similarityThreshold: 0.92,
- *   maxCacheSize: 500,
- *   ttlMs: 3600000, // 1 hour
- * });
- *
- * // Check cache before calling agent
- * const result = await cache.lookup(userQuery);
- * if (result.hit) {
- *   return result.entry!.response;
- * }
- *
- * // Call agent and cache response
- * const response = await runAgent(userQuery);
- * await cache.store(userQuery, response);
- * ```
- */
-declare function createSemanticCache(config: SemanticCacheConfig): SemanticCache;
-/** Input guardrail data for semantic cache */
-interface SemanticCacheGuardrailData {
-    input: string;
-    agentName?: string;
-}
-/**
- * Result of semantic cache guardrail.
- *
- * **Important semantics:**
- * - `passed: false` + `cacheHit: true` = Short-circuit with cached response (not an error!)
- * - `passed: true` + `cacheHit: false` = No cache hit, proceed with agent call
- *
- * The `passed: false` follows guardrail convention where "not passing" stops the flow,
- * but in this case stopping is desirable (returning cached data is good).
- */
-interface SemanticCacheGuardrailResult {
-    /**
-     * Whether to proceed with the agent call.
-     * `false` means short-circuit with cached response (this is good, not an error).
-     * `true` means no cache hit, proceed with agent.
-     */
-    passed: boolean;
-    /** Indicates whether this was a cache hit */
-    cacheHit: boolean;
-    /** Reason for the result */
-    reason?: string;
-    /** The cached response (only present on cache hit) */
-    cachedResponse?: string;
-    /** Similarity score (0-1) of the cache hit */
-    similarity?: number;
-}
-/**
- * Create a semantic caching input guardrail.
- *
- * **How it works:**
- * - On cache HIT: Returns `{ passed: false, cacheHit: true, cachedResponse: "..." }`
- *   The orchestrator should detect `cacheHit: true` and return the cached response.
- * - On cache MISS: Returns `{ passed: true, cacheHit: false }`
- *   Proceed with normal agent execution.
- *
- * **Important:** `passed: false` with `cacheHit: true` is SUCCESS, not failure.
- * The guardrail "short-circuits" the flow to return cached data efficiently.
- *
- * @example
- * ```typescript
- * const cacheGuardrail = createSemanticCacheGuardrail({
- *   cache: mySemanticCache,
- * });
- *
- * const orchestrator = createAgentOrchestrator({
- *   guardrails: {
- *     input: [
- *       {
- *         name: 'semantic-cache',
- *         fn: cacheGuardrail,
- *       },
- *     ],
- *   },
- *   runner: run,
- * });
- *
- * // In your orchestrator wrapper, check for cache hits:
- * const guardrailResult = await cacheGuardrail({ input: userQuery });
- * if (guardrailResult.cacheHit) {
- *   return guardrailResult.cachedResponse; // Fast path!
- * }
- * // Otherwise proceed with agent call...
- * ```
- */
-declare function createSemanticCacheGuardrail(config: {
-    cache: SemanticCache;
-}): (data: SemanticCacheGuardrailData) => Promise<SemanticCacheGuardrailResult>;
-/**
- * Create a simple hash-based "embedder" for testing.
- * NOT suitable for production - use a real embedding model.
- */
-declare function createTestEmbedder(dimensions?: number): EmbedderFn;
-/** Batched embedder instance with dispose capability */
-interface BatchedEmbedder {
-    /** Embed a single text (batched internally) */
-    embed: EmbedderFn;
-    /** Flush any pending batch immediately */
-    flush(): Promise<void>;
-    /** Dispose of the embedder, clearing timers and rejecting pending requests */
-    dispose(): void;
-}
-/**
- * Create a batched embedder that groups multiple texts into single API calls.
- *
- * **BREAKING CHANGE:** Previously returned `EmbedderFn` directly. Now returns
- * a `BatchedEmbedder` object with `embed`, `flush`, and `dispose` methods.
- *
- * To migrate: `const embed = createBatchedEmbedder(...)` becomes
- * `const { embed } = createBatchedEmbedder(...)`.
- *
- * @example
- * ```typescript
- * const batchedEmbedder = createBatchedEmbedder({
- *   batchSize: 20,
- *   embedBatch: async (texts) => {
- *     const response = await openai.embeddings.create({
- *       model: 'text-embedding-3-small',
- *       input: texts,
- *     });
- *     return response.data.map(d => d.embedding);
- *   },
- *   maxWaitMs: 50,
- * });
- *
- * // Use the embedder
- * const embedding = await batchedEmbedder.embed("Hello world");
- *
- * // Clean up when done
- * batchedEmbedder.dispose();
- * ```
- */
-declare function createBatchedEmbedder(config: {
-    batchSize?: number;
-    embedBatch: (texts: string[]) => Promise<Embedding[]>;
-    maxWaitMs?: number;
-}): BatchedEmbedder;
-
 /**
  * Approximate Nearest Neighbor (ANN) Index for Semantic Cache
  *
@@ -2820,44 +1678,227 @@ declare function pipeThrough<TIn, TOut>(source: AsyncIterable<TIn>, destination:
 declare function mergeStreams<T>(...sources: AsyncIterable<T>[]): AsyncIterable<T>;
 
 /**
- * P2: Intelligent Retry — HTTP-status-aware retry wrapper for AgentRunner.
- *
- * Respects 429 Retry-After headers, uses exponential backoff with jitter for 503,
- * and never retries client errors (400/401/403/404/422).
+ * RAG Enricher — Composable retrieval-augmented generation pipeline.
  *
- * @module
+ * Embeds a query, searches a chunk store by cosine similarity, and assembles
+ * an enriched input string (context + history + query) for any agent.
  *
  * @example
  * ```typescript
- * import { withRetry, RetryExhaustedError } from '@directive-run/ai';
+ * import {
+ *   createRAGEnricher,
+ *   createJSONFileStore,
+ * } from '@directive-run/ai';
  *
- * const runner = withRetry(baseRunner, {
- *   maxRetries: 3,
- *   baseDelayMs: 1000,
- *   maxDelayMs: 30000,
- *   onRetry: (attempt, error, delayMs) => {
- *     console.log(`Retry ${attempt} in ${delayMs}ms: ${error.message}`);
- *   },
+ * const enricher = createRAGEnricher({
+ *   embedder: myEmbedder, // Provide your own EmbedderFn
+ *   storage: createJSONFileStore({ filePath: './embeddings.json' }),
  * });
  *
- * try {
- *   const result = await runner(agent, input);
- * } catch (err) {
- *   if (err instanceof RetryExhaustedError) {
- *     console.error(`All ${err.retryCount} retries failed:`, err.lastError);
- *   }
- * }
+ * const enrichedInput = await enricher.enrich('How do constraints work?', {
+ *   prefix: 'User is viewing: /docs/constraints',
+ *   history: [{ role: 'user', content: 'Hello' }],
+ * });
  * ```
  */
 
-/**
- * Configuration for the intelligent retry wrapper.
- *
- * @example
- * ```typescript
- * const config: RetryConfig = {
- *   maxRetries: 3,
- *   baseDelayMs: 1000,
+/** A document chunk with embedding and metadata */
+interface RAGChunk {
+    id: string;
+    content: string;
+    embedding: Embedding;
+    metadata: Record<string, unknown>;
+}
+/** Pluggable storage backend */
+interface RAGStorage {
+    getChunks(): Promise<RAGChunk[]>;
+    size(): Promise<number>;
+    /** Optional: optimized vector search (bypasses full getChunks scan) */
+    search?(query: Embedding, topK: number, minSimilarity: number): Promise<Array<RAGChunk & {
+        similarity: number;
+    }>>;
+    /** Reload storage (clear cache, re-read from source) */
+    reload?(): Promise<void>;
+    /** Dispose of resources */
+    dispose?(): void;
+}
+interface RAGEnricherConfig {
+    /** Function to generate query embeddings */
+    embedder: EmbedderFn;
+    /** Storage backend for document chunks */
+    storage: RAGStorage;
+    /** Number of top results to return (default: 5) */
+    topK?: number;
+    /** Minimum similarity score to include, clamped to [0, 1] (default: 0.3) */
+    minSimilarity?: number;
+    /** Custom chunk formatter */
+    formatChunk?: (chunk: RAGChunk, similarity: number) => string;
+    /** Custom context block formatter */
+    formatContext?: (formattedChunks: string[], query: string) => string;
+    /** Error callback — embedder/storage errors are non-fatal by default */
+    onError?: (error: Error) => void;
+}
+interface RAGEnrichOptions {
+    /** Prefix line (e.g. "User is viewing: /docs/constraints") */
+    prefix?: string;
+    /** Conversation history */
+    history?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Per-call topK override */
+    topK?: number;
+    /** Filter chunks before ranking (e.g. by metadata tag or section) */
+    filter?: (chunk: RAGChunk) => boolean;
+}
+interface RAGEnricher {
+    /** Retrieve relevant chunks for a query */
+    retrieve(query: string, topK?: number): Promise<Array<RAGChunk & {
+        similarity: number;
+    }>>;
+    /** Retrieve + format into an enriched input string */
+    enrich(input: string, options?: RAGEnrichOptions): Promise<string>;
+}
+/**
+ * Create a RAG enricher that retrieves relevant document chunks and
+ * assembles enriched input for an agent.
+ */
+declare function createRAGEnricher(config: RAGEnricherConfig): RAGEnricher;
+interface JSONFileStoreOptions {
+    /** Absolute or relative path to the JSON embeddings file */
+    filePath: string;
+    /** Optional transform from raw JSON entries to RAGChunk */
+    mapEntry?: (entry: Record<string, unknown>) => RAGChunk;
+    /** Cache TTL in ms. 0 = cache forever (default) */
+    ttlMs?: number;
+}
+/**
+ * Create a RAGStorage backed by a JSON file (lazy-loaded, cached in memory).
+ * Uses dynamic `import('node:fs')` for isomorphic safety.
+ */
+declare function createJSONFileStore(options: JSONFileStoreOptions): RAGStorage;
+
+/**
+ * SSE Transport — Wrap a streamable source into an HTTP Server-Sent Events
+ * response.
+ *
+ * Framework-agnostic: uses the WinterCG `Response` constructor (Node 18+,
+ * Deno, Bun, Cloudflare Workers, Next.js).
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createSSETransport,
+ *   createAgentOrchestrator,
+ *   createStreamingRunner,
+ * } from '@directive-run/ai';
+ *
+ * const transport = createSSETransport({
+ *   maxResponseChars: 10_000,
+ *   errorMessages: {
+ *     INPUT_GUARDRAIL_FAILED: 'Your message was flagged by our safety filter.',
+ *   },
+ * });
+ *
+ * // Next.js route handler
+ * export async function POST(req: Request) {
+ *   const { message } = await req.json();
+ *   return transport.toResponse(streamable, 'docs-qa', message);
+ * }
+ * ```
+ */
+/** Async iterable of string tokens with result promise and abort */
+interface SSETokenStream extends AsyncIterable<string> {
+    result: Promise<unknown>;
+    abort(): void;
+}
+/** Any object with a .stream() method compatible with SSE transport */
+interface SSEStreamable {
+    stream(agentId: string, input: string, opts?: {
+        signal?: AbortSignal;
+    }): SSETokenStream;
+}
+type SSEEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "truncated";
+    text: string;
+} | {
+    type: "done";
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "heartbeat";
+    timestamp: number;
+};
+interface SSETransportConfig {
+    /** Truncate response after this many characters (default: Infinity) */
+    maxResponseChars?: number;
+    /** Message shown when response is truncated */
+    truncationMessage?: string;
+    /** Heartbeat interval in ms (default: 0 = disabled) */
+    heartbeatIntervalMs?: number;
+    /** Map error codes/types to user-facing messages */
+    errorMessages?: Record<string, string> | ((error: unknown) => string);
+    /** Extra headers merged into the SSE response */
+    headers?: Record<string, string>;
+}
+interface SSETransport {
+    /** Create a full HTTP Response with SSE headers */
+    toResponse(source: SSEStreamable, agentId: string, input: string, opts?: {
+        signal?: AbortSignal;
+    }): Response;
+    /** Return just the ReadableStream (for Express/Koa `res.write()`) */
+    toStream(source: SSEStreamable, agentId: string, input: string, opts?: {
+        signal?: AbortSignal;
+    }): ReadableStream<Uint8Array>;
+}
+/**
+ * Create an SSE transport that converts a token stream into Server-Sent Events.
+ */
+declare function createSSETransport(config?: SSETransportConfig): SSETransport;
+
+/**
+ * P2: Intelligent Retry — HTTP-status-aware retry wrapper for AgentRunner.
+ *
+ * Respects 429 Retry-After headers, uses exponential backoff with jitter for 503,
+ * and never retries client errors (400/401/403/404/422).
+ *
+ * @module
+ *
+ * @example
+ * ```typescript
+ * import { withRetry, RetryExhaustedError } from '@directive-run/ai';
+ *
+ * const runner = withRetry(baseRunner, {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   onRetry: (attempt, error, delayMs) => {
+ *     console.log(`Retry ${attempt} in ${delayMs}ms: ${error.message}`);
+ *   },
+ * });
+ *
+ * try {
+ *   const result = await runner(agent, input);
+ * } catch (err) {
+ *   if (err instanceof RetryExhaustedError) {
+ *     console.error(`All ${err.retryCount} retries failed:`, err.lastError);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Configuration for the intelligent retry wrapper.
+ *
+ * @example
+ * ```typescript
+ * const config: RetryConfig = {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
  *   maxDelayMs: 30000,
  *   isRetryable: (error) => !error.message.includes("invalid API key"),
  *   onRetry: (attempt, error, delayMs) => {
@@ -3212,726 +2253,756 @@ declare function byPattern(pattern: RegExp, model: string): ModelRule;
 declare function withModelSelection(runner: AgentRunner, configOrRules: ModelSelectionConfig | ModelRule[]): AgentRunner;
 
 /**
- * P6: Structured Outputs — Schema validation with auto-retry for LLM responses.
- *
- * Turns unreliable text output into typed, validated data. Appends JSON schema
- * instructions to the system prompt and retries with error feedback on parse failure.
+ * P5: Batch Queue — Application-level batching for agent calls.
  *
- * Works with any Zod-compatible schema (any object with a `safeParse` method).
+ * Accumulates calls and flushes them in batches to reduce overhead.
+ * Each `submit()` returns a promise that resolves when its individual call completes.
+ * Batches execute calls in parallel up to a configurable concurrency limit.
  *
  * @module
  *
  * @example
  * ```typescript
- * import { z } from "zod";
- * import { withStructuredOutput, StructuredOutputError } from '@directive-run/ai';
- *
- * const SentimentSchema = z.object({
- *   sentiment: z.enum(["positive", "negative", "neutral"]),
- *   confidence: z.number().min(0).max(1),
- * });
+ * import { createBatchQueue } from '@directive-run/ai';
  *
- * const runner = withStructuredOutput(baseRunner, {
- *   schema: SentimentSchema,
- *   maxRetries: 2,
+ * const queue = createBatchQueue(runner, {
+ *   maxBatchSize: 20,
+ *   maxWaitMs: 5000,
+ *   concurrency: 5,
  * });
  *
- * const result = await runner(agent, "Analyze: I love this product!");
- * // result.output is typed as { sentiment: string; confidence: number }
- * ```
- */
-
-/**
- * Zod-compatible schema duck type — any object with a `safeParse` method.
+ * // Submit calls — they batch automatically
+ * const [r1, r2, r3] = await Promise.all([
+ *   queue.submit(agent, "input 1"),
+ *   queue.submit(agent, "input 2"),
+ *   queue.submit(agent, "input 3"),
+ * ]);
  *
- * This interface allows structured outputs to work with Zod, Valibot,
- * or any validation library that implements this pattern.
+ * // Force immediate flush
+ * await queue.flush();
  *
- * @example
- * ```typescript
- * import { z } from "zod";
- *
- * // Zod schemas implement SafeParseable automatically
- * const schema = z.object({ name: z.string() });
- *
- * // Custom schema
- * const custom: SafeParseable<{ name: string }> = {
- *   safeParse(value) {
- *     if (typeof value === "object" && value && "name" in value) {
- *       return { success: true, data: value as { name: string } };
- *     }
- *     return { success: false, error: { message: "Missing name field" } };
- *   },
- * };
+ * // Clean up (flushes remaining calls)
+ * await queue.dispose();
  * ```
  */
-interface SafeParseable<T = unknown> {
-    safeParse(value: unknown): SafeParseResult<T>;
-    /** Optional: schema description injected into the system prompt. */
-    description?: string;
-}
-interface SafeParseResult<T> {
-    success: boolean;
-    data?: T;
-    error?: {
-        message?: string;
-        issues?: Array<{
-            message: string;
-        }>;
-    };
+
+interface BatchQueueConfig {
+    /** Maximum number of calls per batch. @default 20 */
+    maxBatchSize?: number;
+    /** Maximum time to wait before flushing (ms). @default 5000 */
+    maxWaitMs?: number;
+    /** Number of calls to run in parallel within a batch. @default 5 */
+    concurrency?: number;
 }
-interface StructuredOutputConfig<T = unknown> {
-    /** Zod-compatible schema with safeParse. */
-    schema: SafeParseable<T>;
-    /** Max retries on parse/validation failure. @default 2 */
-    maxRetries?: number;
-    /** Custom JSON extractor. Default: finds first `{...}` or `[...]` in output. */
-    extractJson?: (output: string) => unknown;
-    /** Schema description to inject into system prompt. Auto-derived from schema.description if available. */
-    schemaDescription?: string;
+interface BatchQueue {
+    /** Submit a call to the queue. Returns a promise that resolves when the call completes. */
+    submit<T = unknown>(agent: AgentLike, input: string, options?: RunOptions): Promise<RunResult<T>>;
+    /** Flush all pending calls immediately. */
+    flush(): Promise<void>;
+    /** Get the number of pending calls. */
+    readonly pending: number;
+    /** Dispose the queue, flushing remaining calls. */
+    dispose(): Promise<void>;
 }
-/** Default JSON extractor — finds the first `{...}` or `[...]` in output. */
-declare function extractJsonFromOutput(output: string): unknown;
 /**
- * Wrap an AgentRunner with structured output parsing and validation.
+ * Create a batch queue for grouping agent calls.
  *
  * @example
  * ```typescript
- * import { z } from "zod";
- *
- * const SentimentSchema = z.object({
- *   sentiment: z.enum(["positive", "negative", "neutral"]),
- *   confidence: z.number().min(0).max(1),
+ * const queue = createBatchQueue(runner, {
+ *   maxBatchSize: 20,
+ *   maxWaitMs: 5000,
+ *   concurrency: 5,
  * });
  *
- * const runner = withStructuredOutput(baseRunner, {
- *   schema: SentimentSchema,
- *   maxRetries: 2,
- * });
+ * // Submit multiple calls — they batch automatically
+ * const [result1, result2, result3] = await Promise.all([
+ *   queue.submit(agent, "input 1"),
+ *   queue.submit(agent, "input 2"),
+ *   queue.submit(agent, "input 3"),
+ * ]);
  *
- * const result = await runner(agent, "Analyze: I love this product!");
- * // result.output is typed as { sentiment: string; confidence: number }
+ * // Clean up
+ * await queue.dispose();
  * ```
  */
-declare function withStructuredOutput<T = unknown>(runner: AgentRunner, config: StructuredOutputConfig<T>): AgentRunner;
-/** Error thrown when structured output parsing fails after all retries. */
-declare class StructuredOutputError extends Error {
-    readonly lastResult: RunResult<unknown> | undefined;
-    constructor(message: string, lastResult?: RunResult<unknown>);
-}
+declare function createBatchQueue(runner: AgentRunner, config?: BatchQueueConfig): BatchQueue;
 
 /**
- * Agent Stack — Composition API for AI Adapters
+ * P4: Constraint-Driven Provider Routing — Directive's unique differentiator.
  *
- * One factory that wires orchestrator, memory, circuit breaker, rate limiter,
- * streaming, multi-agent patterns, semantic cache, observability, OTLP export,
- * and communication bus with sensible defaults.
+ * Uses user-supplied constraints to select providers based on runtime state:
+ * cost, latency, error rates, and compliance regions.
  *
- * @example Basic usage
- * ```typescript
- * import { createAgentStack, parallel } from '@directive-run/ai';
- *
- * const stack = createAgentStack({
- *   runner: myAgentRunner,
- *   agents: { move: { agent: moveAgent, capabilities: ["move"] } },
- *   memory: { maxMessages: 30 },
- *   circuitBreaker: { failureThreshold: 3 },
- *   cache: { threshold: 0.98, maxSize: 200, ttlMs: 600_000 },
- *   observability: { serviceName: "my-app" },
- * });
+ * Tracks per-provider stats (call count, error count, cost, latency) and
+ * exposes them as {@link RoutingFacts} for constraint evaluation.
  *
- * const result = await stack.run("move", input);
- * ```
+ * @module
  *
- * @example Streaming
+ * @example
  * ```typescript
- * const stack = createAgentStack({
- *   runner: myAgentRunner,
- *   streaming: { runner: myStreamingAgentRunner },
- *   agents: { chat: { agent: chatAgent, capabilities: ["chat"] } },
+ * import { createConstraintRouter } from '@directive-run/ai';
+ * import type { ConstraintRouterRunner } from '@directive-run/ai';
+ *
+ * const router = createConstraintRouter({
+ *   providers: [
+ *     { name: "openai", runner: openaiRunner, pricing: { inputPerMillion: 5, outputPerMillion: 15 } },
+ *     { name: "anthropic", runner: anthropicRunner, pricing: { inputPerMillion: 3, outputPerMillion: 15 } },
+ *     { name: "ollama", runner: ollamaRunner },
+ *   ],
+ *   defaultProvider: "openai",
+ *   constraints: [
+ *     { when: (facts) => facts.totalCost > 100, provider: "ollama", priority: 10 },
+ *     { when: (facts) => facts.providers["openai"]?.errorCount > 5, provider: "anthropic" },
+ *   ],
+ *   preferCheapest: true, // opt-in to cheapest-provider heuristic
+ *   onProviderSelected: (name, reason) => console.log(`Using ${name} (${reason})`),
  * });
  *
- * const tokenStream = stack.stream("chat", "Hello!");
- * for await (const token of tokenStream) { process.stdout.write(token); }
- * const finalResult = await tokenStream.result;
+ * // Access runtime stats
+ * console.log(router.facts.totalCost, router.facts.callCount);
  * ```
  */
 
-/** Callback-based streaming run function (e.g. for SSE-based LLM APIs) */
-type StreamingCallbackRunner = (agent: AgentLike, input: string, callbacks: {
-    onToken?: (token: string) => void;
-    onToolStart?: (tool: string, id: string, args: string) => void;
-    onToolEnd?: (tool: string, id: string, result: string) => void;
-    onMessage?: (message: Message$1) => void;
-    signal?: AbortSignal;
-}) => Promise<RunResult<unknown>>;
-interface AgentStackConfig {
-    /** Required: base runner for agent execution */
+/**
+ * Provider definition for the constraint router.
+ *
+ * Each provider has its own runner, optional pricing (for cost tracking
+ * and cheapest-provider heuristic), and optional region tag.
+ */
+interface RoutingProvider {
+    /** Unique name for this provider. */
+    name: string;
+    /** The runner to use for this provider. */
     runner: AgentRunner;
-    /** Enables stack.stream() when provided */
-    streaming?: {
-        runner: StreamingCallbackRunner;
-    };
-    /** Agent registry — required for multi-agent patterns */
-    agents?: AgentRegistry;
-    /** Named execution patterns (parallel, sequential, supervisor) */
-    patterns?: Record<string, ExecutionPattern>;
-    memory?: {
-        maxMessages?: number;
-        preserveRecentCount?: number;
-    } | AgentMemory;
-    circuitBreaker?: CircuitBreakerConfig | CircuitBreaker;
-    rateLimit?: {
-        maxPerMinute: number;
-    };
-    cache?: {
-        threshold?: number;
-        maxSize?: number;
-        ttlMs?: number;
-        embedder?: EmbedderFn;
-    } | SemanticCache;
-    observability?: {
-        serviceName: string;
-        alerts?: AlertConfig[];
-    } | ObservabilityInstance;
-    otlp?: {
-        endpoint: string;
-        intervalMs?: number;
-        onError?: (err: Error, type: "metrics" | "traces") => void;
-    };
-    /** Message bus for agent communication */
-    messageBus?: {
-        maxHistory?: number;
-    } | MessageBus;
-    guardrails?: {
-        input?: Array<GuardrailFn<InputGuardrailData> | NamedGuardrail<InputGuardrailData>>;
-        output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
-        streaming?: StreamingGuardrail[];
-    };
-    maxTokenBudget?: number;
-    /** Cost per million tokens for cost estimation */
-    costPerMillionTokens?: number;
-    debug?: boolean;
-    constraints?: Record<string, OrchestratorConstraint<Record<string, unknown>>>;
-    resolvers?: Record<string, OrchestratorResolver<Record<string, unknown>, Requirement>>;
-    approvals?: {
-        /** @default true */
-        autoApproveToolCalls?: boolean;
-        onRequest?: (request: ApprovalRequest) => void;
-        /** @default 300_000 */
-        timeoutMs?: number;
-    };
-    retry?: AgentRetryConfig;
-    hooks?: OrchestratorLifecycleHooks;
-    /** P2: Intelligent retry config for the base runner. */
-    intelligentRetry?: RetryConfig;
-    /** P0: Fallback runners (tried in order on failure). */
-    fallback?: {
-        runners: AgentRunner[];
-        config?: FallbackConfig;
-    };
-    /** P1: Cost budget guards. */
-    budget?: BudgetConfig;
-    /** P3: Model selection rules (first match wins). */
-    modelSelection?: ModelRule[];
-    /** P6: Structured output config (applied per-agent via agents map, or globally here). */
-    structuredOutput?: StructuredOutputConfig;
-}
-interface StackRunOptions {
-    /** Override output guardrails for this call */
-    guardrails?: {
-        output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
-    };
-    /** Set to false to skip cache for this call */
-    cache?: false;
-    /** AbortSignal for cancellation */
-    signal?: AbortSignal;
-}
-interface StackStreamOptions {
-    signal?: AbortSignal;
-}
-interface TokenStream<T = string> extends AsyncIterable<string> {
-    /** Resolves to the final run result after the stream completes */
-    result: Promise<RunResult<T>>;
-    /** Abort the stream */
-    abort: () => void;
-}
-interface AgentStackState {
-    totalTokens: number;
-    estimatedCost: number;
-    circuitState: CircuitState;
-    cacheStats: CacheStats;
-    memoryMessageCount: number;
-    busMessageCount: number;
-    rateLimitRemaining: number | null;
-}
-/** Options for runStructured() */
-interface StructuredRunOptions<_T = unknown> extends StackRunOptions {
-    /** Validate the output. Return `true` or `{ valid: true }` on success. */
-    validate: (value: unknown) => boolean | {
-        valid: boolean;
-        errors?: string[];
-    };
-    /** Number of retry attempts on validation failure @default 1 */
-    retries?: number;
-}
-interface AgentStack {
-    /** Run a single registered agent by ID */
-    run<T = unknown>(agentId: string, input: string, options?: StackRunOptions): Promise<RunResult<T>>;
-    /** Run and validate output against a schema, retrying on failure */
-    runStructured<T>(agentId: string, input: string, options: StructuredRunOptions<T>): Promise<RunResult<T>>;
-    /** Run a named execution pattern */
-    runPattern<T = unknown>(patternId: string, input: string, options?: StackRunOptions): Promise<T>;
-    /** Stream tokens from a single agent */
-    stream<T = string>(agentId: string, input: string, options?: StackStreamOptions): TokenStream<T>;
-    /** Stream full rich chunks (token, tool_start, tool_end, etc.) from a single agent */
-    streamChunks<T = unknown>(agentId: string, input: string, options?: StackStreamOptions): StreamingRunResult<T>;
-    /** Approve a pending approval request */
-    approve(requestId: string): void;
-    /** Reject a pending approval request */
-    reject(requestId: string, reason?: string): void;
-    /** Aggregate state across all features */
-    getState(): AgentStackState;
-    /** Reset all feature state */
-    reset(): void;
-    /** Dispose all resources */
-    dispose(): Promise<void>;
-    readonly orchestrator: AgentOrchestrator<Record<string, unknown>>;
-    readonly observability: ObservabilityInstance | null;
-    readonly messageBus: MessageBus | null;
-    readonly coordinator: MultiAgentOrchestrator | null;
-    readonly cache: SemanticCache | null;
-    readonly memory: AgentMemory | null;
-    /** Get observability timeline (spans + metrics) for debugging */
-    getTimeline(limit?: number): {
-        spans: readonly TraceSpan[];
-        metrics: Record<string, AggregatedMetric>;
+    /** Token pricing (cost per million tokens). */
+    pricing?: {
+        inputPerMillion: number;
+        outputPerMillion: number;
     };
+    /** Geographic region (for compliance routing). */
+    region?: string;
 }
 /**
- * Create an agent stack that composes all AI adapter features.
+ * Runtime facts tracked by the router — exposed for user constraints.
  *
- * Only `runner` is required. Every other feature activates when its config key
- * is present. Pass a pre-built instance to reuse existing objects, or pass
- * shorthand config to let the stack create them.
+ * Access via the `facts` property on the returned {@link ConstraintRouterRunner}.
  */
-declare function createAgentStack(config: AgentStackConfig): AgentStack;
-
+interface RoutingFacts {
+    totalCost: number;
+    callCount: number;
+    errorCount: number;
+    lastProvider: string | null;
+    avgLatencyMs: number;
+    /** Per-provider stats. */
+    providers: Record<string, ProviderStats>;
+}
+interface ProviderStats {
+    callCount: number;
+    errorCount: number;
+    totalCost: number;
+    avgLatencyMs: number;
+    lastErrorAt: number | null;
+}
+/** User-supplied routing constraint. */
+interface RoutingConstraint {
+    /** When this constraint is active. */
+    when: (facts: RoutingFacts) => boolean;
+    /** The provider to route to. */
+    provider: string;
+    /** Priority — higher wins when multiple constraints match. @default 0 */
+    priority?: number;
+}
+interface ConstraintRouterConfig {
+    /** Available providers. */
+    providers: RoutingProvider[];
+    /** Default provider name. */
+    defaultProvider: string;
+    /** User-supplied routing constraints. */
+    constraints?: RoutingConstraint[];
+    /** Called when a provider is selected. */
+    onProviderSelected?: (providerName: string, reason: "constraint" | "cheapest" | "default") => void;
+    /** Error cooldown — skip a provider for this many ms after an error. @default 30000 */
+    errorCooldownMs?: number;
+    /**
+     * When true, automatically prefer the cheapest available provider
+     * (based on pricing) when no user constraint matches.
+     * When false, the default provider is used unless a constraint overrides it.
+     * @default false
+     */
+    preferCheapest?: boolean;
+}
 /**
- * AI Bridge — Syncs AI adapter state into a Directive system.
- *
- * Eliminates manual state sync boilerplate when using createAgentStack()
- * alongside createSystem().
- *
- * @example Using with AgentStack directly
- * ```typescript
- * const syncAI = createAISyncer(stack, (state) => {
- *   system.events.chat.updateAIState({
- *     totalTokens: state.totalTokens,
- *     estimatedCost: state.estimatedCost,
- *     circuitState: state.circuitState,
- *   });
- * });
- * syncAI();
- * ```
+ * Create a constraint-driven provider router.
  *
- * @example Using with a wrapper that has getState()
+ * @example
  * ```typescript
- * const syncAI = createAISyncer(myAIWrapper, (state) => {
- *   system.events.chat.updateAIState({ ... });
+ * const runner = createConstraintRouter({
+ *   providers: [
+ *     { name: "openai", runner: openaiRunner, pricing: { inputPerMillion: 5, outputPerMillion: 15 } },
+ *     { name: "anthropic", runner: anthropicRunner, pricing: { inputPerMillion: 3, outputPerMillion: 15 } },
+ *     { name: "ollama", runner: ollamaRunner },
+ *   ],
+ *   defaultProvider: "openai",
+ *   constraints: [
+ *     { when: (facts) => facts.totalCost > 100, provider: "ollama", priority: 10 },
+ *     { when: (facts) => facts.providers["openai"]?.errorCount > 5, provider: "anthropic" },
+ *   ],
  * });
- * syncAI();
  * ```
  */
+declare function createConstraintRouter(config: ConstraintRouterConfig): ConstraintRouterRunner;
+/** Helper type for accessing router facts. */
+type ConstraintRouterRunner = AgentRunner & {
+    readonly facts: RoutingFacts;
+};
+
 /**
- * Any object with a getState() method.
- * Works with AgentStack, or any wrapper that exposes getState().
- */
-interface Syncable<S> {
-    getState(): S;
-}
-/**
- * Create a sync function that reads the latest state from a source and
- * passes it to a callback (typically dispatching events into a Directive system).
+ * DevTools Server — WebSocket-based bridge between orchestrators and DevTools UI.
+ *
+ * Streams debug timeline events, health metrics, breakpoint state, and system
+ * snapshots in real-time to connected DevTools clients. Accepts commands from
+ * clients to resume/cancel breakpoints and request snapshots.
  *
- * Call the returned function after any AI operation to push state updates.
+ * Transport-agnostic: works with any WebSocket implementation (ws, Bun, Deno)
+ * via the {@link DevToolsTransport} interface.
+ *
+ * @module
  */
-declare function createAISyncer<S>(source: Syncable<S>, syncFn: (state: S) => void): () => void;
 
+/** A connected DevTools client */
+interface DevToolsClient {
+    /** Send a JSON-serializable message to this client */
+    send(data: string): void;
+    /** Close the connection */
+    close(): void;
+}
 /**
- * RAG Enricher — Composable retrieval-augmented generation pipeline.
+ * Transport layer for the DevTools server.
  *
- * Embeds a query, searches a chunk store by cosine similarity, and assembles
- * an enriched input string (context + history + query) for any agent.
+ * Implement this interface to bridge any WebSocket library (ws, Bun.serve, Deno.serve).
  *
- * @example
+ * @example Node.js with `ws`:
  * ```typescript
- * import {
- *   createRAGEnricher,
- *   createJSONFileStore,
- * } from '@directive-run/ai';
+ * import { WebSocketServer } from "ws";
  *
- * const enricher = createRAGEnricher({
- *   embedder: myEmbedder, // Provide your own EmbedderFn
- *   storage: createJSONFileStore({ filePath: './embeddings.json' }),
- * });
+ * function createWsTransport(port: number): DevToolsTransport {
+ *   const wss = new WebSocketServer({ port });
+ *   let onConnect: ((client: DevToolsClient) => void) | null = null;
  *
- * const enrichedInput = await enricher.enrich('How do constraints work?', {
- *   prefix: 'User is viewing: /docs/constraints',
- *   history: [{ role: 'user', content: 'Hello' }],
- * });
+ *   wss.on("connection", (ws) => {
+ *     const client: DevToolsClient = {
+ *       send: (data) => { if (ws.readyState === ws.OPEN) ws.send(data); },
+ *       close: () => ws.close(),
+ *     };
+ *     ws.on("message", (raw) => {
+ *       if (client._onMessage) client._onMessage(raw.toString());
+ *     });
+ *     ws.on("close", () => {
+ *       if (client._onClose) client._onClose();
+ *     });
+ *     onConnect?.(client);
+ *   });
+ *
+ *   return {
+ *     onConnection(handler) { onConnect = handler; },
+ *     close() { wss.close(); },
+ *   };
+ * }
  * ```
  */
-
-/** A document chunk with embedding and metadata */
-interface RAGChunk {
-    id: string;
-    content: string;
-    embedding: Embedding;
-    metadata: Record<string, unknown>;
-}
-/** Pluggable storage backend */
-interface RAGStorage {
-    getChunks(): Promise<RAGChunk[]>;
-    size(): Promise<number>;
-    /** Optional: optimized vector search (bypasses full getChunks scan) */
-    search?(query: Embedding, topK: number, minSimilarity: number): Promise<Array<RAGChunk & {
-        similarity: number;
-    }>>;
-    /** Reload storage (clear cache, re-read from source) */
-    reload?(): Promise<void>;
-    /** Dispose of resources */
-    dispose?(): void;
-}
-interface RAGEnricherConfig {
-    /** Function to generate query embeddings */
-    embedder: EmbedderFn;
-    /** Storage backend for document chunks */
-    storage: RAGStorage;
-    /** Number of top results to return (default: 5) */
-    topK?: number;
-    /** Minimum similarity score to include, clamped to [0, 1] (default: 0.3) */
-    minSimilarity?: number;
-    /** Custom chunk formatter */
-    formatChunk?: (chunk: RAGChunk, similarity: number) => string;
-    /** Custom context block formatter */
-    formatContext?: (formattedChunks: string[], query: string) => string;
-    /** Error callback — embedder/storage errors are non-fatal by default */
-    onError?: (error: Error) => void;
+interface DevToolsTransport {
+    /** Register a handler for new client connections */
+    onConnection(handler: (client: DevToolsClient, onMessage: (handler: (data: string) => void) => void, onClose: (handler: () => void) => void) => void): void;
+    /** Shut down the transport */
+    close(): void;
 }
-interface RAGEnrichOptions {
-    /** Prefix line (e.g. "User is viewing: /docs/constraints") */
-    prefix?: string;
-    /** Conversation history */
-    history?: Array<{
-        role: string;
-        content: string;
+/** Messages sent FROM the server TO clients */
+type DevToolsServerMessage = {
+    type: "welcome";
+    version: number;
+    sessionId: string;
+    timestamp: number;
+} | {
+    type: "event";
+    event: DebugEvent;
+} | {
+    type: "event_batch";
+    events: DebugEvent[];
+} | {
+    type: "snapshot";
+    data: DevToolsSnapshot;
+} | {
+    type: "health";
+    metrics: Record<string, AgentHealthMetrics>;
+} | {
+    type: "breakpoints";
+    state: BreakpointState;
+} | {
+    type: "pong";
+    timestamp: number;
+} | {
+    type: "scratchpad_state";
+    data: Record<string, unknown>;
+} | {
+    type: "scratchpad_update";
+    key: string;
+    value: unknown;
+} | {
+    type: "derived_state";
+    data: Record<string, unknown>;
+} | {
+    type: "derived_update";
+    id: string;
+    value: unknown;
+} | {
+    type: "fork_complete";
+    eventId: number;
+    newEventCount: number;
+} | {
+    type: "token_stream";
+    agentId: string;
+    tokens: string;
+    tokenCount: number;
+} | {
+    type: "stream_done";
+    agentId: string;
+    totalTokens: number;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+};
+/** Messages sent FROM clients TO the server */
+type DevToolsClientMessage = {
+    type: "request_snapshot";
+} | {
+    type: "request_health";
+} | {
+    type: "request_events";
+    since?: number;
+} | {
+    type: "request_breakpoints";
+} | {
+    type: "resume_breakpoint";
+    breakpointId: string;
+    modifications?: {
+        input?: string;
+        skip?: boolean;
+    };
+} | {
+    type: "cancel_breakpoint";
+    breakpointId: string;
+    reason?: string;
+} | {
+    type: "export_session";
+} | {
+    type: "import_session";
+    data: string;
+} | {
+    type: "request_scratchpad";
+} | {
+    type: "request_derived";
+} | {
+    type: "fork_from_snapshot";
+    eventId: number;
+} | {
+    type: "ping";
+};
+/** System snapshot sent to clients on demand */
+interface DevToolsSnapshot {
+    timestamp: number;
+    agents: Record<string, {
+        status: string;
+        lastInput?: string;
+        lastOutput?: unknown;
+        totalTokens: number;
+        runCount: number;
     }>;
-    /** Per-call topK override */
-    topK?: number;
-    /** Filter chunks before ranking (e.g. by metadata tag or section) */
-    filter?: (chunk: RAGChunk) => boolean;
-}
-interface RAGEnricher {
-    /** Retrieve relevant chunks for a query */
-    retrieve(query: string, topK?: number): Promise<Array<RAGChunk & {
-        similarity: number;
-    }>>;
-    /** Retrieve + format into an enriched input string */
-    enrich(input: string, options?: RAGEnrichOptions): Promise<string>;
+    coordinator?: {
+        globalTokens: number;
+        status: string;
+    };
+    derived?: Record<string, unknown>;
+    eventCount: number;
+}
+/** Configuration for the DevTools server */
+interface DevToolsServerConfig {
+    /** Transport to use for WebSocket connections */
+    transport: DevToolsTransport;
+    /** Debug timeline to subscribe to */
+    timeline: DebugTimeline;
+    /** Health monitor for metrics (optional) */
+    healthMonitor?: HealthMonitor | null;
+    /** Callback to get current agent states for snapshots */
+    getSnapshot?: () => DevToolsSnapshot;
+    /** Callback to get current breakpoint state */
+    getBreakpointState?: () => BreakpointState;
+    /** Callback to resume a breakpoint */
+    onResumeBreakpoint?: (id: string, modifications?: {
+        input?: string;
+        skip?: boolean;
+    }) => void;
+    /** Callback to cancel a breakpoint */
+    onCancelBreakpoint?: (id: string, reason?: string) => void;
+    /** Callback to get current scratchpad state */
+    getScratchpadState?: () => Record<string, unknown>;
+    /** Callback to get current derived state */
+    getDerivedState?: () => Record<string, unknown>;
+    /** Callback to fork from a snapshot event */
+    onForkFromSnapshot?: (eventId: number) => {
+        newEventCount: number;
+    };
+    /** Maximum events to batch before flushing. Default: 1 (no batching) */
+    batchSize?: number;
+    /** Flush interval for batched events (ms). Default: 50 */
+    batchIntervalMs?: number;
+    /** Health metrics push interval (ms). 0 = no auto-push. Default: 0 */
+    healthPushIntervalMs?: number;
+    /** Maximum connected clients. Default: 50 */
+    maxClients?: number;
+}
+/** DevTools server instance */
+interface DevToolsServer {
+    /** Number of connected clients */
+    readonly clientCount: number;
+    /** Broadcast a message to all connected clients */
+    broadcast(message: DevToolsServerMessage): void;
+    /** Push current health metrics to all clients */
+    pushHealth(): void;
+    /** Push current breakpoint state to all clients */
+    pushBreakpoints(): void;
+    /** Push a scratchpad key update to all clients */
+    pushScratchpadUpdate(key: string, value: unknown): void;
+    /** Push a derived value update to all clients */
+    pushDerivedUpdate(id: string, value: unknown): void;
+    /** Push streaming tokens to all clients */
+    pushTokenStream(agentId: string, tokens: string, tokenCount: number): void;
+    /** Signal stream completion to all clients */
+    pushStreamDone(agentId: string, totalTokens: number): void;
+    /** Shut down the server and disconnect all clients */
+    close(): void;
 }
 /**
- * Create a RAG enricher that retrieves relevant document chunks and
- * assembles enriched input for an agent.
+ * Create a DevTools server that bridges orchestrator state to DevTools UI clients.
+ *
+ * @example
+ * ```typescript
+ * const server = createDevToolsServer({
+ *   transport: createWsTransport(4040),
+ *   timeline: orchestrator.timeline!,
+ *   healthMonitor: orchestrator.healthMonitor,
+ *   getSnapshot: () => buildSnapshot(orchestrator),
+ *   getBreakpointState: () => orchestrator.getBreakpointState(),
+ *   onResumeBreakpoint: (id, mods) => orchestrator.resumeBreakpoint(id, mods),
+ *   onCancelBreakpoint: (id, reason) => orchestrator.cancelBreakpoint(id, reason),
+ * });
+ * ```
  */
-declare function createRAGEnricher(config: RAGEnricherConfig): RAGEnricher;
-interface JSONFileStoreOptions {
-    /** Absolute or relative path to the JSON embeddings file */
-    filePath: string;
-    /** Optional transform from raw JSON entries to RAGChunk */
-    mapEntry?: (entry: Record<string, unknown>) => RAGChunk;
-    /** Cache TTL in ms. 0 = cache forever (default) */
-    ttlMs?: number;
+declare function createDevToolsServer(config: DevToolsServerConfig): DevToolsServer;
+/** Options for connecting DevTools to an orchestrator */
+interface ConnectDevToolsOptions {
+    /** Port for the WebSocket server. Default: 4040 */
+    port?: number;
+    /** Host to bind to. Default: "localhost" */
+    host?: string;
+    /** Health metrics push interval (ms). Default: 5000 */
+    healthPushIntervalMs?: number;
+    /** Event batching size. Default: 1 (no batching) */
+    batchSize?: number;
+}
+/** Minimal orchestrator interface for DevTools connection */
+interface DevToolsCompatibleOrchestrator {
+    timeline: {
+        subscribe: (listener: (event: DebugEvent) => void) => () => void;
+        getEvents: () => DebugEvent[];
+        import: (json: string) => void;
+        export: () => string;
+        forkFrom?: (eventId: number) => void;
+    } | null;
+    healthMonitor?: {
+        getAllMetrics: () => Record<string, AgentHealthMetrics>;
+    } | null;
+    getPendingBreakpoints?: () => Array<{
+        id: string;
+        type: string;
+        agentId: string;
+        input: string;
+        label?: string;
+        requestedAt: number;
+    }>;
+    resumeBreakpoint?: (id: string, modifications?: {
+        input?: string;
+        skip?: boolean;
+    }) => void;
+    cancelBreakpoint?: (id: string, reason?: string) => void;
+    getAllAgentStates?: () => Record<string, {
+        status: string;
+        lastInput?: string;
+        lastOutput?: unknown;
+        totalTokens: number;
+        runCount: number;
+    }>;
+    /** Get current scratchpad state (multi-agent only) */
+    getScratchpadState?: () => Record<string, unknown>;
+    /** Get current derived values (multi-agent only) */
+    getDerivedState?: () => Record<string, unknown>;
 }
 /**
- * Create a RAGStorage backed by a JSON file (lazy-loaded, cached in memory).
- * Uses dynamic `import('node:fs')` for isomorphic safety.
- */
-declare function createJSONFileStore(options: JSONFileStoreOptions): RAGStorage;
-
-/**
- * SSE Transport — Wrap a Directive AgentStack token stream into an HTTP
- * Server-Sent Events response.
+ * Connect DevTools to an orchestrator instance.
  *
- * Framework-agnostic: uses the WinterCG `Response` constructor (Node 18+,
- * Deno, Bun, Cloudflare Workers, Next.js).
+ * Convenience function that creates a WebSocket transport and DevTools server,
+ * automatically wiring up the orchestrator's timeline, health monitor, and breakpoint system.
+ *
+ * Requires the `ws` package: `npm install ws`
+ *
+ * **Security:** Binding to `0.0.0.0` exposes the server to all network interfaces.
+ * Only do this behind a firewall or with proper authentication.
  *
  * @example
  * ```typescript
- * import { createSSETransport, createAgentStack } from '@directive-run/ai';
+ * const orchestrator = createMultiAgentOrchestrator({ debug: true, ... });
+ * const devtools = await connectDevTools(orchestrator, { port: 4040 });
  *
- * const transport = createSSETransport({
- *   maxResponseChars: 10_000,
- *   errorMessages: {
- *     INPUT_GUARDRAIL_FAILED: 'Your message was flagged by our safety filter.',
- *   },
- * });
- *
- * // Next.js route handler
- * export async function POST(req: Request) {
- *   const { message } = await req.json();
- *   return transport.toResponse(stack, 'docs-qa', message);
- * }
+ * // Later, clean up:
+ * devtools.close();
  * ```
  */
-
-type SSEEvent = {
-    type: "text";
-    text: string;
-} | {
-    type: "truncated";
-    text: string;
-} | {
-    type: "done";
-} | {
-    type: "error";
-    message: string;
-} | {
-    type: "heartbeat";
-    timestamp: number;
-};
-interface SSETransportConfig {
-    /** Truncate response after this many characters (default: Infinity) */
-    maxResponseChars?: number;
-    /** Message shown when response is truncated */
-    truncationMessage?: string;
-    /** Heartbeat interval in ms (default: 0 = disabled) */
-    heartbeatIntervalMs?: number;
-    /** Map error codes/types to user-facing messages */
-    errorMessages?: Record<string, string> | ((error: unknown) => string);
-    /** Extra headers merged into the SSE response */
-    headers?: Record<string, string>;
-}
-interface SSETransport {
-    /** Create a full HTTP Response with SSE headers */
-    toResponse(stack: AgentStack, agentId: string, input: string, opts?: {
-        signal?: AbortSignal;
-    }): Response;
-    /** Return just the ReadableStream (for Express/Koa `res.write()`) */
-    toStream(stack: AgentStack, agentId: string, input: string, opts?: {
-        signal?: AbortSignal;
-    }): ReadableStream<Uint8Array>;
+declare function connectDevTools(orchestrator: DevToolsCompatibleOrchestrator, options?: ConnectDevToolsOptions): Promise<DevToolsServer>;
+/**
+ * Configuration for the built-in Node.js `ws` transport.
+ *
+ * Requires the `ws` package to be installed: `npm install ws`
+ */
+interface WsTransportConfig {
+    /** Port to listen on. Default: 4040 */
+    port?: number;
+    /** Host to bind to. Default: "localhost" */
+    host?: string;
+    /** Maximum incoming message size in bytes. Default: 1048576 (1MB) */
+    maxPayloadBytes?: number;
 }
 /**
- * Create an SSE transport that converts a Directive AgentStack token stream
- * into Server-Sent Events.
+ * Create a DevTools transport using the Node.js `ws` WebSocket library.
+ *
+ * This is a convenience helper — you can implement {@link DevToolsTransport}
+ * with any WebSocket library.
+ *
+ * @example
+ * ```typescript
+ * const transport = await createWsTransport({ port: 4040 });
+ * const server = createDevToolsServer({ transport, timeline });
+ * ```
  */
-declare function createSSETransport(config?: SSETransportConfig): SSETransport;
+declare function createWsTransport(config?: WsTransportConfig): Promise<DevToolsTransport>;
 
 /**
- * P5: Batch Queue — Application-level batching for agent calls.
+ * Standalone utilities for goal planning and validation.
  *
- * Accumulates calls and flushes them in batches to reduce overhead.
- * Each `submit()` returns a promise that resolves when its individual call completes.
- * Batches execute calls in parallel up to a configurable concurrency limit.
- *
- * @module
+ * These functions work with the same `produces` / `requires` agent
+ * declarations used by the goal pattern, without requiring an
+ * orchestrator instance.
  *
  * @example
  * ```typescript
- * import { createBatchQueue } from '@directive-run/ai';
+ * import { validateGoal, planGoal, getDependencyGraph } from '@directive-run/ai';
  *
- * const queue = createBatchQueue(runner, {
- *   maxBatchSize: 20,
- *   maxWaitMs: 5000,
- *   concurrency: 5,
- * });
+ * const agents = {
+ *   fetcher: { produces: ['data'], requires: [] },
+ *   analyzer: { produces: ['analysis'], requires: ['data'] },
+ *   reporter: { produces: ['report'], requires: ['analysis'] },
+ * };
  *
- * // Submit calls — they batch automatically
- * const [r1, r2, r3] = await Promise.all([
- *   queue.submit(agent, "input 1"),
- *   queue.submit(agent, "input 2"),
- *   queue.submit(agent, "input 3"),
- * ]);
+ * // Validate — cycle detection, missing deps, warnings
+ * const validation = validateGoal(agents);
  *
- * // Force immediate flush
- * await queue.flush();
+ * // Plan — dry-run without executing agents
+ * const plan = planGoal(agents, ['query']);
  *
- * // Clean up (flushes remaining calls)
- * await queue.dispose();
+ * // Graph — topological order, roots, leaves, edges
+ * const graph = getDependencyGraph(agents);
  * ```
+ *
+ * @module
  */
 
-interface BatchQueueConfig {
-    /** Maximum number of calls per batch. @default 20 */
-    maxBatchSize?: number;
-    /** Maximum time to wait before flushing (ms). @default 5000 */
-    maxWaitMs?: number;
-    /** Number of calls to run in parallel within a batch. @default 5 */
-    concurrency?: number;
+/** Minimal agent declaration for goal utilities (subset of GoalNode) */
+interface GoalAgentDeclaration {
+    /** Fact keys this agent writes as output */
+    produces: string[];
+    /** Fact keys this agent reads as input */
+    requires?: string[];
+}
+/** Edge in the inferred dependency graph */
+interface GoalDependencyEdge {
+    from: string;
+    to: string;
+    /** Fact key that creates this dependency */
+    factKey: string;
 }
-interface BatchQueue {
-    /** Submit a call to the queue. Returns a promise that resolves when the call completes. */
-    submit<T = unknown>(agent: AgentLike, input: string, options?: RunOptions): Promise<RunResult<T>>;
-    /** Flush all pending calls immediately. */
-    flush(): Promise<void>;
-    /** Get the number of pending calls. */
-    readonly pending: number;
-    /** Dispose the queue, flushing remaining calls. */
-    dispose(): Promise<void>;
+/** Inferred dependency graph from produces/requires analysis */
+interface GoalDependencyGraph {
+    /** Agent IDs in topological order (roots first) */
+    order: string[];
+    /** Edges between agents */
+    edges: GoalDependencyEdge[];
+    /** Root agents (no unfulfilled requires from other agents) */
+    roots: string[];
+    /** Leaf agents (nothing depends on their produces) */
+    leaves: string[];
+    /** Map of fact key to agent ID that produces it */
+    producers: Map<string, string>;
+}
+/** Validation result */
+interface GoalValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/** A single step in an execution plan */
+interface GoalPlanStep {
+    /** Step number (1-based) */
+    step: number;
+    /** Agent IDs that would run in this step (parallel) */
+    agents: string[];
+    /** Fact keys available at the start of this step */
+    availableFacts: string[];
+    /** Fact keys produced after this step completes */
+    producedFacts: string[];
+}
+/** Result of a planGoal() dry-run */
+interface GoalExecutionPlan {
+    /** Ordered steps showing which agents run when */
+    steps: GoalPlanStep[];
+    /** Agents that can never run (requires never satisfiable) */
+    unreachableAgents: string[];
+    /** Required fact keys that no agent produces (must be in initial facts) */
+    externalDeps: string[];
+    /** Whether the plan can potentially reach all agents */
+    feasible: boolean;
 }
 /**
- * Create a batch queue for grouping agent calls.
+ * Get the dependency graph for a set of agent declarations.
+ *
+ * Uses Kahn's algorithm (topological sort) to compute execution order
+ * and detect circular dependencies.
+ *
+ * @throws If agents form a circular dependency or a fact key has multiple producers.
  *
  * @example
  * ```typescript
- * const queue = createBatchQueue(runner, {
- *   maxBatchSize: 20,
- *   maxWaitMs: 5000,
- *   concurrency: 5,
+ * const graph = getDependencyGraph({
+ *   fetcher: { produces: ['data'], requires: [] },
+ *   analyzer: { produces: ['analysis'], requires: ['data'] },
  * });
  *
- * // Submit multiple calls — they batch automatically
- * const [result1, result2, result3] = await Promise.all([
- *   queue.submit(agent, "input 1"),
- *   queue.submit(agent, "input 2"),
- *   queue.submit(agent, "input 3"),
- * ]);
- *
- * // Clean up
- * await queue.dispose();
+ * console.log(graph.order);  // ['fetcher', 'analyzer']
+ * console.log(graph.roots);  // ['fetcher']
+ * console.log(graph.leaves); // ['analyzer']
  * ```
  */
-declare function createBatchQueue(runner: AgentRunner, config?: BatchQueueConfig): BatchQueue;
-
+declare function getDependencyGraph(agents: Record<string, GoalAgentDeclaration>): GoalDependencyGraph;
 /**
- * P4: Constraint-Driven Provider Routing — Directive's unique differentiator.
+ * Validate a set of agent declarations for goal execution.
  *
- * Uses user-supplied constraints to select providers based on runtime state:
- * cost, latency, error rates, and compliance regions.
- *
- * Tracks per-provider stats (call count, error count, cost, latency) and
- * exposes them as {@link RoutingFacts} for constraint evaluation.
- *
- * @module
+ * Checks for:
+ * - Circular dependencies
+ * - Duplicate producers (same fact key produced by multiple agents)
+ * - Agents with no `produces` (will never contribute)
+ * - Required fact keys that no agent produces (must be in initial facts)
  *
  * @example
  * ```typescript
- * import { createConstraintRouter } from '@directive-run/ai';
- * import type { ConstraintRouterRunner } from '@directive-run/ai';
- *
- * const router = createConstraintRouter({
- *   providers: [
- *     { name: "openai", runner: openaiRunner, pricing: { inputPerMillion: 5, outputPerMillion: 15 } },
- *     { name: "anthropic", runner: anthropicRunner, pricing: { inputPerMillion: 3, outputPerMillion: 15 } },
- *     { name: "ollama", runner: ollamaRunner },
- *   ],
- *   defaultProvider: "openai",
- *   constraints: [
- *     { when: (facts) => facts.totalCost > 100, provider: "ollama", priority: 10 },
- *     { when: (facts) => facts.providers["openai"]?.errorCount > 5, provider: "anthropic" },
- *   ],
- *   preferCheapest: true, // opt-in to cheapest-provider heuristic
- *   onProviderSelected: (name, reason) => console.log(`Using ${name} (${reason})`),
+ * const result = validateGoal({
+ *   fetcher: { produces: ['data'] },
+ *   analyzer: { produces: ['analysis'], requires: ['data'] },
  * });
  *
- * // Access runtime stats
- * console.log(router.facts.totalCost, router.facts.callCount);
+ * if (!result.valid) {
+ *   console.error(result.errors);
+ * }
  * ```
  */
-
+declare function validateGoal(agents: Record<string, GoalAgentDeclaration>): GoalValidationResult;
 /**
- * Provider definition for the constraint router.
+ * Dry-run goal execution to preview the plan without running agents.
  *
- * Each provider has its own runner, optional pricing (for cost tracking
- * and cheapest-provider heuristic), and optional region tag.
- */
-interface RoutingProvider {
-    /** Unique name for this provider. */
-    name: string;
-    /** The runner to use for this provider. */
-    runner: AgentRunner;
-    /** Token pricing (cost per million tokens). */
-    pricing?: {
-        inputPerMillion: number;
-        outputPerMillion: number;
-    };
-    /** Geographic region (for compliance routing). */
-    region?: string;
-}
-/**
- * Runtime facts tracked by the router — exposed for user constraints.
+ * Shows which agents would run in each step, which facts would be produced,
+ * and whether any agents are unreachable.
  *
- * Access via the `facts` property on the returned {@link ConstraintRouterRunner}.
+ * @param agents - Agent declarations with produces/requires
+ * @param initialFactKeys - Fact keys available at the start (not values, just keys)
+ * @param maxSteps - Maximum steps to simulate (default: 50)
+ *
+ * @example
+ * ```typescript
+ * const plan = planGoal(
+ *   {
+ *     fetcher: { produces: ['data'] },
+ *     analyzer: { produces: ['analysis'], requires: ['data'] },
+ *     reporter: { produces: ['report'], requires: ['analysis'] },
+ *   },
+ *   ['query'],
+ * );
+ *
+ * console.log(plan.feasible);  // true
+ * console.log(plan.steps);     // 3 steps: fetcher → analyzer → reporter
+ * ```
  */
-interface RoutingFacts {
-    totalCost: number;
-    callCount: number;
-    errorCount: number;
-    lastProvider: string | null;
-    avgLatencyMs: number;
-    /** Per-provider stats. */
-    providers: Record<string, ProviderStats>;
-}
-interface ProviderStats {
-    callCount: number;
-    errorCount: number;
-    totalCost: number;
-    avgLatencyMs: number;
-    lastErrorAt: number | null;
-}
-/** User-supplied routing constraint. */
-interface RoutingConstraint {
-    /** When this constraint is active. */
-    when: (facts: RoutingFacts) => boolean;
-    /** The provider to route to. */
-    provider: string;
-    /** Priority — higher wins when multiple constraints match. @default 0 */
-    priority?: number;
-}
-interface ConstraintRouterConfig {
-    /** Available providers. */
-    providers: RoutingProvider[];
-    /** Default provider name. */
-    defaultProvider: string;
-    /** User-supplied routing constraints. */
-    constraints?: RoutingConstraint[];
-    /** Called when a provider is selected. */
-    onProviderSelected?: (providerName: string, reason: "constraint" | "cheapest" | "default") => void;
-    /** Error cooldown — skip a provider for this many ms after an error. @default 30000 */
-    errorCooldownMs?: number;
-    /**
-     * When true, automatically prefer the cheapest available provider
-     * (based on pricing) when no user constraint matches.
-     * When false, the default provider is used unless a constraint overrides it.
-     * @default false
-     */
-    preferCheapest?: boolean;
+declare function planGoal(agents: Record<string, GoalAgentDeclaration>, initialFactKeys?: string[], maxSteps?: number): GoalExecutionPlan;
+/** A single line in a goal execution explanation */
+interface GoalExplanationStep {
+    step: number;
+    agents: string[];
+    factsProduced: string[];
+    satisfaction: number;
+    satisfactionDelta: number;
+    durationMs: number;
+    tokensConsumed: number;
+    /** Human-readable description of what happened */
+    description: string;
+}
+/** Structured explanation of a goal execution */
+interface GoalExplanation {
+    /** Whether the goal was achieved */
+    achieved: boolean;
+    /** Human-readable summary */
+    summary: string;
+    /** Per-step explanations */
+    steps: GoalExplanationStep[];
+    /** Relaxation events with descriptions */
+    relaxations: Array<{
+        step: number;
+        label: string;
+        strategy: string;
+        description: string;
+    }>;
+    /** Total tokens consumed */
+    totalTokens: number;
+    /** Total duration (ms) */
+    durationMs: number;
 }
 /**
- * Create a constraint-driven provider router.
+ * Generate a human-readable explanation of a goal execution result.
+ *
+ * Takes a `GoalResult` and returns a structured explanation of why each
+ * agent ran, how satisfaction progressed, and what relaxations were applied.
  *
  * @example
  * ```typescript
- * const runner = createConstraintRouter({
- *   providers: [
- *     { name: "openai", runner: openaiRunner, pricing: { inputPerMillion: 5, outputPerMillion: 15 } },
- *     { name: "anthropic", runner: anthropicRunner, pricing: { inputPerMillion: 3, outputPerMillion: 15 } },
- *     { name: "ollama", runner: ollamaRunner },
- *   ],
- *   defaultProvider: "openai",
- *   constraints: [
- *     { when: (facts) => facts.totalCost > 100, provider: "ollama", priority: 10 },
- *     { when: (facts) => facts.providers["openai"]?.errorCount > 5, provider: "anthropic" },
- *   ],
- * });
+ * const result = await orchestrator.runGoal(nodes, input, when, options);
+ * const explanation = explainGoal(result);
+ *
+ * console.log(explanation.summary);
+ * // "Goal achieved in 3 steps (1,247 tokens, 892ms). Satisfaction: 0 → 1."
+ *
+ * for (const step of explanation.steps) {
+ *   console.log(step.description);
+ *   // "Step 1: Ran fetcher. Produced: data. Satisfaction: 0 → 0.3 (+0.3)."
+ * }
  * ```
  */
-declare function createConstraintRouter(config: ConstraintRouterConfig): ConstraintRouterRunner;
-/** Helper type for accessing router facts. */
-type ConstraintRouterRunner = AgentRunner & {
-    readonly facts: RoutingFacts;
-};
+declare function explainGoal<T = unknown>(result: GoalResult<T>): GoalExplanation;
 
 /**
  * MCP Type Definitions
@@ -4379,273 +3450,472 @@ declare function mcpGetPrompt(server: string, prompt: string, args?: Record<stri
 declare function mcpSyncResources(server?: string, pattern?: string | RegExp): MCPSyncResourcesRequirement;
 
 /**
- * AI Adapter – Constraint-driven agent orchestration with guardrails
+ * Evaluation Framework — Constraint-driven agent evaluation.
  *
- * Philosophy: "Use Directive WITH any LLM agent framework"
- * - Your framework handles LLM tool execution
- * - Directive adds safety guardrails, approval workflows, state persistence
- *
- * Also available:
- * - `@directive-run/ai/testing` – Mock runners, test orchestrators, assertion helpers
- * - `@directive-run/ai/anthropic` – Anthropic Claude adapter
- * - `@directive-run/ai/openai` – OpenAI / Azure / Together adapter
- * - `@directive-run/ai/ollama` – Local Ollama inference adapter
+ * Define eval criteria as composable functions. Run agents against datasets
+ * and score their outputs across multiple dimensions. Results integrate with
+ * the debug timeline for DevTools visualization.
  *
  * @example
  * ```typescript
- * import { createAgentOrchestrator } from '@directive-run/ai'
- *
- * const orchestrator = createAgentOrchestrator({
- *   runner: myAgentRunner,
- *   constraints: {
- *     needsExpertReview: {
- *       when: (facts) => facts.decision.confidence < 0.7,
- *       require: { type: 'EXPERT_AGENT', query: facts.userQuery }
- *     },
- *     budgetLimit: {
- *       when: (facts) => facts.tokenUsage > 10000,
- *       require: { type: 'PAUSE_AGENTS' }
- *     }
+ * const suite = createEvalSuite({
+ *   criteria: {
+ *     safe: evalSafety({ categories: ["pii"] }),
+ *     costEfficient: evalCost({ maxTokensPerRun: 5000 }),
+ *     fast: evalLatency({ maxMs: 3000 }),
  *   },
- *   guardrails: {
- *     input: [(data) => validatePII(data.input)],
- *     output: [(data) => checkToxicity(data.output)]
- *   }
- * })
+ *   agents: [researchAgent, writerAgent],
+ *   runner: myRunner,
+ *   dataset: [
+ *     { id: "case-1", input: "What is AI?", expected: "explanation about AI" },
+ *   ],
+ * });
+ *
+ * const results = await suite.run();
+ * // results.summary — pass/fail per criterion per agent
+ * // results.details — per-case breakdown
  * ```
+ *
+ * @module
  */
 
-/** Orchestrator options */
-interface OrchestratorOptions<F extends Record<string, unknown>> {
-    /** Function to run an agent */
+/** Single test case in the eval dataset */
+interface EvalCase {
+    /** Unique identifier for tracking across runs */
+    id?: string;
+    /** Input to feed the agent */
+    input: string;
+    /** Expected output or reference answer (for comparison-based criteria) */
+    expected?: string;
+    /** Reference context for faithfulness evaluation */
+    context?: string;
+    /** Tags for filtering and grouping results */
+    tags?: string[];
+    /** Additional context passed to criteria */
+    metadata?: Record<string, unknown>;
+}
+/** Result of evaluating a single criterion on a single case */
+interface EvalScore {
+    /** Score from 0.0 to 1.0 */
+    score: number;
+    /** Whether this score passes the criterion threshold */
+    passed: boolean;
+    /** Reason for the score */
+    reason?: string;
+    /** Duration of evaluation (ms) */
+    durationMs: number;
+}
+/** Context passed to eval criterion functions */
+interface EvalContext {
+    /** The agent being evaluated */
+    agent: AgentLike;
+    /** The test case */
+    testCase: EvalCase;
+    /** The agent's run result */
+    result: RunResult<unknown>;
+    /** Duration of the agent run (ms) */
+    runDurationMs: number;
+}
+/** Eval criterion function — scores an agent's output */
+type EvalCriterionFn = (context: EvalContext) => EvalScore | Promise<EvalScore>;
+/** Named eval criterion */
+interface EvalCriterion {
+    name: string;
+    fn: EvalCriterionFn;
+    /** Score threshold for passing. Default: 0.5 */
+    threshold?: number;
+    /** Weight for aggregation. Default: 1.0 */
+    weight?: number;
+}
+/** Per-case detail result */
+interface EvalCaseResult {
+    /** Test case that was evaluated */
+    testCase: EvalCase;
+    /** Agent that was evaluated */
+    agentName: string;
+    /** Agent run result */
+    runResult: RunResult<unknown>;
+    /** Score per criterion */
+    scores: Record<string, EvalScore>;
+    /** Overall weighted score (0.0-1.0) */
+    overallScore: number;
+    /** Whether all criteria passed */
+    allPassed: boolean;
+    /** Agent run duration (ms) */
+    runDurationMs: number;
+}
+/** Per-agent summary */
+interface EvalAgentSummary {
+    agentName: string;
+    /** Average score per criterion */
+    criterionAverages: Record<string, number>;
+    /** Pass rate per criterion (0.0-1.0) */
+    criterionPassRates: Record<string, number>;
+    /** Overall weighted average score */
+    overallScore: number;
+    /** Overall pass rate */
+    passRate: number;
+    /** Total tokens consumed */
+    totalTokens: number;
+    /** Average latency per run (ms) */
+    avgLatencyMs: number;
+    /** Total cases evaluated */
+    totalCases: number;
+    /** Cases that passed all criteria */
+    passedCases: number;
+}
+/** Complete eval suite results */
+interface EvalResults {
+    /** Summary per agent */
+    summary: Record<string, EvalAgentSummary>;
+    /** Detailed per-case results */
+    details: EvalCaseResult[];
+    /** Total duration (ms) */
+    durationMs: number;
+    /** Total tokens consumed across all agents and cases */
+    totalTokens: number;
+    /** Timestamp when the eval started */
+    startedAt: number;
+    /** Timestamp when the eval completed */
+    completedAt: number;
+}
+/** Configuration for createEvalSuite */
+interface EvalSuiteConfig {
+    /** Named criteria to evaluate */
+    criteria: Record<string, EvalCriterionFn | EvalCriterion>;
+    /** Agents to evaluate */
+    agents: AgentLike[];
+    /** Agent runner function */
     runner: AgentRunner;
-    /** Additional facts schema */
-    factsSchema?: Record<string, {
-        _type: unknown;
-        _validators: [];
-    }>;
-    /** Initialize additional facts */
-    init?: (facts: F & OrchestratorState) => void;
-    /** Constraints for orchestration */
-    constraints?: Record<string, OrchestratorConstraint<F>>;
-    /** Resolvers for orchestration */
-    resolvers?: Record<string, OrchestratorResolver<F, Requirement>>;
-    /** Guardrails */
-    guardrails?: GuardrailsConfig;
-    /** Callback for approval requests */
-    onApprovalRequest?: (request: ApprovalRequest) => void;
-    /**
-     * Auto-approve tool calls
-     * @default true
-     */
-    autoApproveToolCalls?: boolean;
-    /**
-     * Maximum token budget across all agent runs.
-     *
-     * When exceeded, agents are automatically paused with status "paused".
-     * Check `facts.agent.tokenUsage` to see current usage.
-     *
-     * For more sophisticated cost management (per-user budgets, tiered pricing,
-     * cost alerts), see the Cost Management section in the documentation.
-     *
-     * @example
-     * ```typescript
-     * const orchestrator = createAgentOrchestrator({
-     *   maxTokenBudget: 10000, // Pause after 10K tokens
-     * });
-     *
-     * // Check if paused due to budget
-     * if (orchestrator.facts.agent.status === 'paused') {
-     *   console.log('Budget exceeded:', orchestrator.facts.agent.tokenUsage);
-     * }
-     * ```
-     */
-    maxTokenBudget?: number;
-    /** Plugins */
-    plugins?: Plugin[];
-    /**
-     * Enable debugging
-     * @default false
-     */
-    debug?: boolean;
-    /**
-     * Approval timeout in milliseconds
-     * @default 300000 (5 minutes)
-     */
-    approvalTimeoutMs?: number;
-    /** Retry configuration for agent runs (no retries if not specified) */
-    agentRetry?: AgentRetryConfig;
-    /** Lifecycle hooks for observability */
-    hooks?: OrchestratorLifecycleHooks;
-    /**
-     * Optional memory instance. When provided, context messages are auto-injected
-     * into agent instructions before each run, and result messages are auto-stored.
-     */
-    memory?: AgentMemory;
-    /**
-     * Optional circuit breaker. Wraps every run() call.
-     * When OPEN, throws CircuitBreakerOpenError instead of calling the agent.
-     */
-    circuitBreaker?: CircuitBreaker;
-}
-/** Streaming run result from orchestrator */
-interface OrchestratorStreamResult<T = unknown> {
-    /** Async iterator for streaming chunks */
-    stream: AsyncIterable<OrchestratorStreamChunk>;
-    /** Promise that resolves to the final result */
-    result: Promise<RunResult<T>>;
-    /** Abort the stream */
-    abort: () => void;
-}
-/** Stream chunk types for orchestrator — extends StreamChunk with approval events */
-type OrchestratorStreamChunk = StreamChunk | {
-    type: "approval_required";
-    requestId: string;
-    toolName: string;
-} | {
-    type: "approval_resolved";
-    requestId: string;
-    approved: boolean;
-};
-/** Per-call options for run() */
-interface RunCallOptions {
-    /** Override output guardrails for this call only. Set to [] to skip. */
-    outputGuardrails?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
-    /** Override input guardrails for this call only. Set to [] to skip. */
-    inputGuardrails?: Array<GuardrailFn<InputGuardrailData> | NamedGuardrail<InputGuardrailData>>;
-    /** Signal for abort */
+    /** Dataset of test cases */
+    dataset: EvalCase[];
+    /** Run options passed to the runner */
+    runOptions?: Omit<RunOptions, "signal">;
+    /** Maximum concurrent agent runs. Default: 5 */
+    concurrency?: number;
+    /** Optional debug timeline for recording eval events */
+    timeline?: DebugTimeline;
+    /** Callback fired on each case completion */
+    onCaseComplete?: (result: EvalCaseResult) => void;
+    /** Callback fired on each agent completion */
+    onAgentComplete?: (summary: EvalAgentSummary) => void;
+    /** Abort signal */
     signal?: AbortSignal;
 }
-/** Orchestrator instance */
-interface AgentOrchestrator<F extends Record<string, unknown>> {
-    system: System<any>;
-    facts: F & OrchestratorState;
-    /** Run an agent with guardrails. Pass options to override guardrails per-call. */
-    run<T>(agent: AgentLike, input: string, options?: RunCallOptions): Promise<RunResult<T>>;
-    /**
-     * Run an agent with streaming support.
-     * Returns an async iterator for chunks and a promise for the final result.
-     *
-     * @example
-     * ```typescript
-     * const { stream, result, abort } = orchestrator.runStream(agent, input);
-     *
-     * for await (const chunk of stream) {
-     *   if (chunk.type === 'token') process.stdout.write(chunk.data);
-     *   if (chunk.type === 'approval_required') showApprovalDialog(chunk);
-     *   if (chunk.type === 'guardrail_triggered') handleGuardrail(chunk);
-     * }
-     *
-     * const finalResult = await result;
-     * ```
-     */
-    runStream<T>(agent: AgentLike, input: string, options?: {
-        signal?: AbortSignal;
-    }): OrchestratorStreamResult<T>;
-    /** Approve a pending request */
-    approve(requestId: string): void;
-    /** Reject a pending request */
-    reject(requestId: string, reason?: string): void;
-    /** Pause all agents */
-    pause(): void;
-    /** Resume agents */
-    resume(): void;
-    /** Reset conversation state */
-    reset(): void;
-    /** Dispose of the orchestrator */
-    dispose(): void;
+/** Eval suite instance */
+interface EvalSuite {
+    /** Run the full evaluation */
+    run(): Promise<EvalResults>;
+    /** Run evaluation for a specific agent only */
+    runAgent(agentName: string): Promise<EvalAgentSummary>;
+    /** Get the list of agents being evaluated */
+    getAgents(): AgentLike[];
+    /** Get the list of criteria */
+    getCriteria(): string[];
+    /** Get the dataset */
+    getDataset(): EvalCase[];
+}
+/** Options for cost evaluation */
+interface EvalCostOptions {
+    /** Maximum tokens per run */
+    maxTokensPerRun: number;
+}
+/**
+ * Evaluate cost efficiency — scores based on token usage relative to a budget.
+ *
+ * Score = 1.0 when tokens <= maxTokensPerRun * 0.5
+ * Score = 0.0 when tokens >= maxTokensPerRun * 2
+ * Linear interpolation between.
+ */
+declare function evalCost(options: EvalCostOptions): EvalCriterion;
+/** Options for latency evaluation */
+interface EvalLatencyOptions {
+    /** Maximum acceptable latency (ms) */
+    maxMs: number;
+}
+/**
+ * Evaluate latency — scores based on agent run duration.
+ *
+ * Score = 1.0 when duration <= maxMs * 0.5
+ * Score = 0.0 when duration >= maxMs * 2
+ * Linear interpolation between.
+ */
+declare function evalLatency(options: EvalLatencyOptions): EvalCriterion;
+/** Options for output length evaluation */
+interface EvalOutputLengthOptions {
+    /** Minimum output length (chars) */
+    minLength?: number;
+    /** Maximum output length (chars) */
+    maxLength?: number;
+}
+/**
+ * Evaluate output length — ensures output is within an acceptable range.
+ */
+declare function evalOutputLength(options: EvalOutputLengthOptions): EvalCriterion;
+/** Options for safety evaluation */
+interface EvalSafetyOptions {
+    /** Patterns to check for in output (overrides categories) */
+    blockedPatterns?: RegExp[];
+    /** Categories of content to check: "pii", "violence", "self_harm", "illegal" */
+    categories?: Array<"pii" | "violence" | "self_harm" | "illegal">;
+}
+/**
+ * Evaluate safety — checks output for blocked patterns or category-based content.
+ *
+ * When `categories` is provided, uses built-in pattern sets for each category.
+ * When `blockedPatterns` is provided, uses those directly (overrides categories).
+ * When neither is provided, defaults to all safety categories.
+ *
+ * Score = 1.0 when no blocked patterns found.
+ * Score = 0.0 when any blocked pattern matches.
+ */
+declare function evalSafety(options?: EvalSafetyOptions): EvalCriterion;
+/** Options for output structure evaluation */
+interface EvalStructureOptions {
+    /** Expected output type */
+    type?: "json" | "string";
+    /** Required keys if type is "json" */
+    requiredKeys?: string[];
+}
+/**
+ * Evaluate output structure — checks that output matches an expected format.
+ */
+declare function evalStructure(options: EvalStructureOptions): EvalCriterion;
+/**
+ * Evaluate with a custom LLM judge — uses a runner to grade the output.
+ *
+ * The judge agent receives the input, output, and expected answer, and
+ * returns a JSON score.
+ */
+interface EvalJudgeOptions {
+    /** Runner to use for the judge */
+    runner: AgentRunner;
+    /** Judge agent */
+    judge: AgentLike;
+    /** Custom grading prompt template. {{input}}, {{output}}, {{expected}} are replaced. */
+    promptTemplate?: string;
+    /** Optional abort signal */
+    signal?: AbortSignal;
+    /** Timeout for the judge call in ms. Default: 30_000 */
+    timeoutMs?: number;
+}
+declare function evalJudge(options: EvalJudgeOptions): EvalCriterion;
+/**
+ * Evaluate exact or substring match against expected output.
+ */
+interface EvalMatchOptions {
+    /** Match mode. Default: "contains" */
+    mode?: "exact" | "contains" | "regex";
+    /** Case-insensitive matching. Default: true */
+    caseInsensitive?: boolean;
+}
+declare function evalMatch(options?: EvalMatchOptions): EvalCriterion;
+/** Options for LLM-based semantic evaluation criteria */
+interface EvalSemanticOptions {
+    /** Runner to use for the judge LLM */
+    runner: AgentRunner;
+    /** Judge agent (model to use for evaluation) */
+    judge: AgentLike;
+    /** Optional abort signal */
+    signal?: AbortSignal;
+    /** Timeout for the judge call in ms. Default: 30_000 */
+    timeoutMs?: number;
+}
+/**
+ * Evaluate faithfulness — whether the output is grounded in the provided context.
+ *
+ * Requires `context` field on the EvalCase. Uses an LLM judge internally
+ * to extract and verify claims against the reference context.
+ */
+declare function evalFaithfulness(options: EvalSemanticOptions): EvalCriterion;
+/**
+ * Evaluate relevance — whether the output directly addresses the input question.
+ *
+ * Uses an LLM judge to assess how well the agent's output answers
+ * the original question.
+ */
+declare function evalRelevance(options: EvalSemanticOptions): EvalCriterion;
+/**
+ * Evaluate coherence — whether the output is logically consistent and well-structured.
+ *
+ * Uses an LLM judge to assess the internal coherence, logical flow,
+ * and consistency of the output.
+ */
+declare function evalCoherence(options: EvalSemanticOptions): EvalCriterion;
+/**
+ * Create an evaluation suite for testing agents against a dataset.
+ *
+ * @example
+ * ```typescript
+ * const suite = createEvalSuite({
+ *   criteria: {
+ *     fast: evalLatency({ maxMs: 3000 }),
+ *     cheap: evalCost({ maxTokensPerRun: 5000 }),
+ *   },
+ *   agents: [researchAgent, writerAgent],
+ *   runner: myRunner,
+ *   dataset: [{ input: "What is AI?" }],
+ * });
+ *
+ * const results = await suite.run();
+ * ```
+ */
+declare function createEvalSuite(config: EvalSuiteConfig): EvalSuite;
+/** Options for eval assertions in CI */
+interface EvalAssertOptions {
+    /** Minimum weighted overall score required (0.0-1.0) */
+    minScore?: number;
+    /** Minimum pass rate required (0.0-1.0) */
+    minPassRate?: number;
+    /** Criteria that must achieve 100% pass rate */
+    failOn?: string[];
 }
 /**
- * Create an orchestrator for OpenAI agents with Directive constraints.
+ * Assert eval results meet requirements — designed for CI pipelines.
+ *
+ * Throws an error with details if any assertion fails.
+ *
+ * @example
+ * ```typescript
+ * const results = await suite.run();
+ * evalAssert(results, {
+ *   minScore: 0.8,
+ *   minPassRate: 0.9,
+ *   failOn: ["safety"],
+ * });
+ * ```
+ */
+declare function evalAssert(results: EvalResults, options: EvalAssertOptions): void;
+
+/**
+ * OpenTelemetry Integration — AI-specific observability spans.
+ *
+ * Auto-instruments agent orchestrators with OpenTelemetry spans for
+ * agent runs, guardrail checks, constraint evaluations, and DAG execution.
+ * Works with any OTEL-compatible collector (Jaeger, Zipkin, Honeycomb, etc.).
+ *
+ * Uses OpenTelemetry GenAI semantic conventions (`gen_ai.*`) for
+ * AI-specific attributes alongside Directive-specific attributes.
  *
  * @example
  * ```typescript
- * import { run as runner } from '@openai/agents'
+ * import { createOtelPlugin } from "@directive-run/ai";
  *
  * const orchestrator = createAgentOrchestrator({
  *   runner,
- *   constraints: {
- *     escalateToExpert: {
- *       when: (facts) => facts.agent.output?.confidence < 0.7,
- *       require: (facts) => ({
- *         type: 'RUN_EXPERT_AGENT',
- *         query: facts.agent.input,
- *       }),
- *     },
- *     budgetExceeded: {
- *       when: (facts) => facts.agent.tokenUsage > 10000,
- *       require: { type: 'PAUSE_AGENTS' },
- *     },
- *   },
- *   guardrails: {
- *     input: [
- *       async (data) => {
- *         const hasPII = await detectPII(data.input);
- *         return { passed: !hasPII, reason: hasPII ? 'Contains PII' : undefined };
- *       },
- *     ],
- *     output: [
- *       async (data) => {
- *         const isToxic = await checkToxicity(data.output);
- *         return { passed: !isToxic, reason: isToxic ? 'Toxic content' : undefined };
- *       },
- *     ],
- *   },
+ *   plugins: [createOtelPlugin({ serviceName: "my-ai-app" })],
  * });
- *
- * // Run with guardrails and constraint-driven orchestration
- * const result = await orchestrator.run(myAgent, 'Hello, can you help me?');
+ * // Every run() creates spans with: agent name, model, tokens, cost, duration
  * ```
  *
- * @throws {Error} If autoApproveToolCalls is false but no onApprovalRequest callback is provided
+ * @module
  */
-declare function createAgentOrchestrator<F extends Record<string, unknown> = Record<string, never>>(options: OrchestratorOptions<F>): AgentOrchestrator<F>;
-/** Builder for type-safe orchestrator configuration */
-interface OrchestratorBuilder<F extends Record<string, unknown>> {
-    /** Add a constraint */
-    withConstraint<K extends string>(id: K, constraint: OrchestratorConstraint<F>): OrchestratorBuilder<F>;
-    /** Add a resolver */
-    withResolver<R extends Requirement>(id: string, resolver: OrchestratorResolver<F, R>): OrchestratorBuilder<F>;
-    /** Add an input guardrail */
-    withInputGuardrail(nameOrGuardrail: string | NamedGuardrail<InputGuardrailData>, fn?: GuardrailFn<InputGuardrailData>): OrchestratorBuilder<F>;
-    /** Add an output guardrail */
-    withOutputGuardrail(nameOrGuardrail: string | NamedGuardrail<OutputGuardrailData>, fn?: GuardrailFn<OutputGuardrailData>): OrchestratorBuilder<F>;
-    /** Add a tool call guardrail */
-    withToolCallGuardrail(nameOrGuardrail: string | NamedGuardrail<ToolCallGuardrailData>, fn?: GuardrailFn<ToolCallGuardrailData>): OrchestratorBuilder<F>;
-    /** Add a plugin */
-    withPlugin(plugin: Plugin): OrchestratorBuilder<F>;
-    /** Set memory instance for auto context injection and message storage */
-    withMemory(memory: AgentMemory): OrchestratorBuilder<F>;
-    /** Set circuit breaker to wrap all run() calls */
-    withCircuitBreaker(cb: CircuitBreaker): OrchestratorBuilder<F>;
-    /** Set max token budget */
-    withBudget(maxTokens: number): OrchestratorBuilder<F>;
-    /** Enable debug mode */
-    withDebug(enabled?: boolean): OrchestratorBuilder<F>;
-    /** Build the orchestrator */
-    build(options: {
-        runner: AgentRunner;
-        autoApproveToolCalls?: boolean;
-        onApprovalRequest?: (request: ApprovalRequest) => void;
-    }): AgentOrchestrator<F>;
+
+/** Minimal span interface compatible with OpenTelemetry API */
+interface OtelSpan {
+    /** Set an attribute on the span */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Add an event to the span */
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    /** Set the span status */
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    /** End the span */
+    end(): void;
+}
+/** OTEL status codes as a const object (no enum overhead) */
+declare const OtelStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+type OtelStatusCode = (typeof OtelStatusCode)[keyof typeof OtelStatusCode];
+/** Tracer interface compatible with OpenTelemetry API */
+interface OtelTracer {
+    /** Start a new span */
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): OtelSpan;
+}
+/** Configuration for the OTEL plugin */
+interface OtelPluginConfig {
+    /** Service name for span attribution */
+    serviceName: string;
+    /** Custom tracer instance. If not provided, uses a no-op tracer for standalone span collection. */
+    tracer?: OtelTracer;
+    /** Span prefix. Default: "directive.ai" */
+    spanPrefix?: string;
+    /** Span processor callback — called for every completed span. Useful for custom exporters. */
+    onSpanEnd?: (spanData: SpanData) => void;
+    /** Event types to instrument. Default: all */
+    instrumentEvents?: Set<string>;
+    /** TTL for active spans in ms. Spans older than this are cleaned up. Default: 300000 (5 min) */
+    spanTtlMs?: number;
+}
+/** Serializable span data for export */
+interface SpanData {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    attributes: Record<string, string | number | boolean>;
+    events: Array<{
+        name: string;
+        attributes?: Record<string, string | number | boolean>;
+        timestamp: number;
+    }>;
+    status: {
+        code: OtelStatusCode;
+        message?: string;
+    };
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+}
+/** OTEL Plugin instance */
+interface OtelPlugin {
+    /** Attach to a debug timeline to auto-instrument */
+    attach(timeline: DebugTimeline): () => void;
+    /** Get all collected spans (when using built-in collector) */
+    getSpans(): SpanData[];
+    /** Clear collected spans */
+    clearSpans(): void;
+    /** Get the underlying tracer */
+    getTracer(): OtelTracer;
+    /** Get count of currently active (in-flight) spans */
+    getActiveSpanCount(): number;
 }
 /**
- * Create a type-safe orchestrator builder.
+ * Create an OpenTelemetry plugin for AI observability.
+ *
+ * Subscribes to a DebugTimeline and creates spans for agent runs,
+ * guardrail checks, constraint evaluations, resolver executions,
+ * and execution patterns (DAG, parallel, sequential, etc.).
+ *
+ * Parent-child relationships:
+ * - Pattern spans are roots
+ * - Agent spans are children of the active pattern span (if any)
+ * - Guardrail/resolver spans within an agent run are children of the agent span
+ * - Constraint evaluations within an agent run are recorded as span events
  *
  * @example
  * ```typescript
- * const orchestrator = createOrchestratorBuilder<MyFacts>()
- *   .withConstraint('budget', {
- *     when: (facts) => facts.cost > 100,
- *     require: { type: 'PAUSE' },
- *   })
- *   .withInputGuardrail('pii', createPIIGuardrail())
- *   .withOutputGuardrail('toxicity', createModerationGuardrail({ ... }))
- *   .withBudget(10000)
- *   .withDebug()
- *   .build({ runner });
+ * // With built-in span collection:
+ * const otel = createOtelPlugin({ serviceName: "my-app" });
+ * const unsub = otel.attach(orchestrator.timeline);
+ * await orchestrator.run(agent, input);
+ * console.log(otel.getSpans()); // All spans from the run
+ *
+ * // With custom OTEL tracer:
+ * import { trace } from "@opentelemetry/api";
+ * const otel = createOtelPlugin({
+ *   serviceName: "my-app",
+ *   tracer: trace.getTracer("directive-ai"),
+ * });
  * ```
  */
-declare function createOrchestratorBuilder<F extends Record<string, unknown> = Record<string, never>>(): OrchestratorBuilder<F>;
+declare function createOtelPlugin(config: OtelPluginConfig): OtelPlugin;
 
-export { type ANNIndex, type ANNSearchResult, AdapterHooks, type AgentInfo, AgentLike, type AgentMemory, type AgentMemoryConfig, type AgentMessage, type AgentMessageType, type AgentNetwork, type AgentNetworkConfig, type AgentOrchestrator, type AgentRegistration, type AgentRegistry, AgentRetryConfig, type AgentRunState, AgentRunner, type AgentSelectionConstraint, type AgentStack, type AgentStackConfig, type AgentStackState, AgentState, AllProvidersFailedError, ApprovalRequest, ApprovalState, type AuditInstance, type AuditPluginConfig, type BackpressureStrategy, type BatchQueue, type BatchQueueConfig, type BatchedEmbedder, type BidirectionalStream, type BudgetConfig, type BudgetExceededDetails, BudgetExceededError, type BudgetRunner, type BudgetWindow, type CacheEntry, type CacheLookupResult, type CacheStats, type ComplianceConfig, type ComplianceInstance, type ComplianceStorage, type ConstraintBuilder, type ConstraintRouterConfig, type ConstraintRouterRunner, type CreateRunnerOptions, DEFAULT_INJECTION_PATTERNS, type DelegationMessage, type DelegationResultMessage, type DoneChunk, type EmbedderFn, type Embedding, type EnhancedPIIGuardrailOptions, type ErrorChunk, type ExecutionPattern, type FallbackConfig, GuardrailFn, type GuardrailTriggeredChunk, GuardrailsConfig, type HandoffRequest, type HandoffResult, type InformMessage, InputGuardrailData, type JSONFileStoreOptions, type MCPAdapter, type MCPAdapterConfig, type MCPApprovalRequest, type MCPCallToolRequirement, type MCPGetPromptRequirement, type MCPReadResourceRequirement, type MCPRequirement, type MCPResource, type MCPServerConfig, type MCPSyncResourcesRequirement, type MCPTool, type MCPToolConstraint, type MCPToolResult, type MemoryManageResult, type MemoryState, type MemoryStrategy, type MemoryStrategyConfig, type MemoryStrategyResult, Message$1 as Message, type MessageBus, type MessageBusConfig, type MessageChunk, type MessageFilter, type MessageHandler, type MessageSummarizer, type ModelRule, type ModelSelectionConfig, type MultiAgentOrchestrator, type MultiAgentOrchestratorOptions, type MultiAgentState, NamedGuardrail, type OrchestratorBuilder, OrchestratorConstraint, OrchestratorLifecycleHooks, type OrchestratorOptions, OrchestratorResolver, OrchestratorState, type OrchestratorStreamChunk, type OrchestratorStreamResult, OutputGuardrailData, type ParallelPattern, type ParsedResponse, type ProgressChunk, type PromptInjectionGuardrailOptions, type ProviderStats, type QueryMessage, type RAGChunk, type RAGEnrichOptions, type RAGEnricher, type RAGEnricherConfig, type RAGStorage, type RateLimitGuardrail, type RequestMessage, type ResponseMessage, type RetryConfig, RetryExhaustedError, type RoutingConstraint, type RoutingFacts, type RoutingProvider, type RunAgentRequirement, type RunCallOptions, RunOptions, RunResult, type SSEEvent, type SSETransport, type SSETransportConfig, STRICT_INJECTION_PATTERNS, type SafeParseResult, type SafeParseable, SchemaValidator, type SemanticCache, type SemanticCacheConfig, type SemanticCacheStorage, Semaphore, type SequentialPattern, type StackRunOptions, type StackStreamOptions, type StreamChannel, type StreamChannelConfig, type StreamChannelState, type StreamChunk, type StreamRunOptions, type StreamRunner, type StreamingCallbackRunner, type StreamingGuardrail, type StreamingGuardrailResult, type StreamingRunResult, type StructuredOutputConfig, StructuredOutputError, type StructuredRunOptions, type Subscription, type SupervisorPattern, type TokenChunk, type TokenPricing, type TokenStream, ToolCallGuardrailData, type ToolEndChunk, type ToolStartChunk, type TypedAgentMessage, type UpdateMessage, type VPTreeIndexConfig, type WhenWithRequire, adaptOutputGuardrail, aggregateTokens, byAgentName, byInputLength, byPattern, collectOutputs, collectTokens, combineStreamingGuardrails, concatResults, constraint, convertToolsForLLM, createAISyncer, createAgentAuditHandlers, createAgentMemory, createAgentNetwork, createAgentOrchestrator, createAgentStack, createAuditTrail, createBatchQueue, createBatchedEmbedder, createBidirectionalStream, createBruteForceIndex, createCompliance, createConstraintRouter, createContentFilterGuardrail, createDelegator, createEnhancedPIIGuardrail, createHybridStrategy, createInMemoryComplianceStorage, createInMemoryStorage, createJSONFileStore, createKeyPointsSummarizer, createLLMSummarizer, createLengthGuardrail, createLengthStreamingGuardrail, createMCPAdapter, createMessageBus, createModerationGuardrail, createMultiAgentOrchestrator, createOrchestratorBuilder, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPatternStreamingGuardrail, createPromptInjectionGuardrail, createPubSub, createRAGEnricher, createRateLimitGuardrail, createResponder, createRunner, createSSETransport, createSemanticCache, createSemanticCacheGuardrail, createSlidingWindowStrategy, createStreamChannel, createStreamingRunner, createTestEmbedder, createTokenBasedStrategy, createToolGuardrail, createToxicityStreamingGuardrail, createTruncationSummarizer, createUntrustedContentGuardrail, createVPTreeIndex, detectPII, detectPromptInjection, estimateCost, extractJsonFromOutput, filterStream, hasPendingApprovals, isAgentRunning, mapStream, markUntrustedContent, mcpCallTool, mcpGetPrompt, mcpReadResource, mcpSyncResources, mergeStreams, parallel, parseHttpStatus, parseRetryAfter, pickBestResult, pipeThrough, redactPII, runAgentRequirement, sanitizeInjection, selectAgent, sequential, supervisor, tapStream, validateBaseURL, when, withBudget, withFallback, withModelSelection, withRetry, withStructuredOutput };
+export { type ANNIndex, type ANNSearchResult, AdapterHooks, AgentHealthMetrics, type AgentInfo, AgentLike, type AgentMessage, type AgentMessageType, type AgentNetwork, type AgentNetworkConfig, AgentRunner, AgentState, AllProvidersFailedError, ApprovalState, type AuditEventType, type AuditInstance, type AuditPluginConfig, type BatchQueue, type BatchQueueConfig, type BidirectionalStream, type BudgetConfig, type BudgetExceededDetails, BudgetExceededError, type BudgetRunner, type BudgetWindow, type ComplianceConfig, type ComplianceInstance, type ComplianceStorage, type ConnectDevToolsOptions, type ConstraintRouterConfig, type ConstraintRouterRunner, type CreateRunnerOptions, DEFAULT_INJECTION_PATTERNS, DebugEvent, DebugTimeline, type DelegationMessage, type DelegationResultMessage, type DevToolsClient, type DevToolsClientMessage, type DevToolsCompatibleOrchestrator, type DevToolsServer, type DevToolsServerConfig, type DevToolsServerMessage, type DevToolsSnapshot, type DevToolsTransport, EmbedderFn, Embedding, type EnhancedPIIGuardrailOptions, type EvalAgentSummary, type EvalAssertOptions, type EvalCase, type EvalCaseResult, type EvalContext, type EvalCostOptions, type EvalCriterion, type EvalCriterionFn, type EvalJudgeOptions, type EvalLatencyOptions, type EvalMatchOptions, type EvalOutputLengthOptions, type EvalResults, type EvalSafetyOptions, type EvalScore, type EvalSemanticOptions, type EvalStructureOptions, type EvalSuite, type EvalSuiteConfig, ExecutionPattern, type FallbackConfig, type GoalAgentDeclaration, type GoalDependencyEdge, type GoalDependencyGraph, type GoalExecutionPlan, type GoalExplanation, type GoalExplanationStep, type GoalPlanStep, GoalResult, type GoalValidationResult, GuardrailFn, HealthMonitor, type InformMessage, InputGuardrailData, type JSONFileStoreOptions, type MCPAdapter, type MCPAdapterConfig, type MCPApprovalRequest, type MCPCallToolRequirement, type MCPGetPromptRequirement, type MCPReadResourceRequirement, type MCPRequirement, type MCPResource, type MCPServerConfig, type MCPSyncResourcesRequirement, type MCPTool, type MCPToolConstraint, type MCPToolResult, type MermaidDirection, type MermaidNodeShapes, type MermaidOptions, Message, type MessageBus, type MessageBusConfig, type MessageFilter, type MessageHandler, type ModelRule, type ModelSelectionConfig, type OtelPlugin, type OtelPluginConfig, type OtelSpan, OtelStatusCode, type OtelTracer, OutputGuardrailData, type ParsedResponse, type PromptInjectionGuardrailOptions, type ProviderStats, type QueryMessage, type RAGChunk, type RAGEnrichOptions, type RAGEnricher, type RAGEnricherConfig, type RAGStorage, type RateLimitGuardrail, type RequestMessage, type ResponseMessage, type RetryConfig, RetryExhaustedError, type RoutingConstraint, type RoutingFacts, type RoutingProvider, RunOptions, RunResult, type RunnerMiddleware, type SSEEvent, type SSETransport, type SSETransportConfig, STRICT_INJECTION_PATTERNS, SchemaValidator, SerializedPattern, type SpanData, type StreamChannel, type StreamChannelConfig, type StreamChannelState, type Subscription, type TokenPricing, ToolCallGuardrailData, type TypedAgentMessage, type UpdateMessage, type VPTreeIndexConfig, type WsTransportConfig, byAgentName, byInputLength, byPattern, connectDevTools, convertToolsForLLM, createAgentAuditHandlers, createAgentNetwork, createAuditTrail, createBatchQueue, createBidirectionalStream, createBruteForceIndex, createCompliance, createConstraintRouter, createContentFilterGuardrail, createDelegator, createDevToolsServer, createEnhancedPIIGuardrail, createEvalSuite, createInMemoryComplianceStorage, createJSONFileStore, createLengthGuardrail, createMCPAdapter, createMessageBus, createModerationGuardrail, createOtelPlugin, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createPubSub, createRAGEnricher, createRateLimitGuardrail, createResponder, createRunner, createSSETransport, createStreamChannel, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, createWsTransport, detectPII, detectPromptInjection, estimateCost, evalAssert, evalCoherence, evalCost, evalFaithfulness, evalJudge, evalLatency, evalMatch, evalOutputLength, evalRelevance, evalSafety, evalStructure, explainGoal, getDependencyGraph, hasPendingApprovals, isAgentRunning, markUntrustedContent, mcpCallTool, mcpGetPrompt, mcpReadResource, mcpSyncResources, mergeStreams, parseHttpStatus, parseRetryAfter, patternToMermaid, pipe, pipeThrough, planGoal, redactPII, sanitizeInjection, validateBaseURL, validateGoal, withBudget, withFallback, withModelSelection, withRetry };