@directive-run/ai 0.1.1 → 0.3.0

package/dist/multi-agent-orchestrator-uMp8bLfV.d.ts

@@ -0,0 +1,2290 @@
+import { M as Message$1, e as RunResult, A as AgentLike, G as GuardrailFn, O as OutputGuardrailData, aX as StreamingCallbackRunner, D as DebugEvent, a1 as DebugEventType, b as AgentRunner, aw as OrchestratorState, aq as NamedGuardrail, I as InputGuardrailData, C as Checkpoint, u as BreakpointModifications, v as BreakpointRequest, ar as OrchestratorConstraint, au as OrchestratorResolver, af as GuardrailsConfig, o as ApprovalRequest, as as OrchestratorDebugConfig, k as AgentRetryConfig, at as OrchestratorLifecycleHooks, aU as SelfHealingConfig, L as CheckpointStore, r as BreakpointConfig, ai as HealthMonitorConfig, R as RunOptions, T as ToolCallGuardrailData, ay as PatternCheckpointConfig, Z as DagPattern, a7 as GoalPattern, a6 as GoalNode, m as AgentSelectionStrategy, aL as RelaxationTier, f as GoalResult, a4 as GoalCheckpointState, aV as SequentialCheckpointState, aY as SupervisorCheckpointState, aF as ReflectCheckpointState, _ as DebateCheckpointState, U as DagCheckpointState, aS as Scratchpad, ao as MultiAgentLifecycleHooks, ap as MultiAgentSelfHealingConfig, am as MultiAgentBreakpointType, P as CrossAgentDerivationFn, W as DagNode, V as DagExecutionContext, az as PatternCheckpointState, E as CheckpointDiff, H as CheckpointProgress, a5 as GoalMetrics } from './types-Co4BzMiH.js';
+import { Plugin, System, Requirement } from '@directive-run/core';
+import { CircuitBreaker } from '@directive-run/core/plugins';
+
+/**
+ * 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;
+
+/**
+ * Agent 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. @default 1000 */
+    bufferSize?: number;
+    /** Evaluate guardrails every N tokens. @default 50 */
+    guardrailCheckInterval?: number;
+    /** Stop stream on guardrail trigger. @default true */
+    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: StreamingCallbackRunner, 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>;
+/** A multiplexed stream chunk tagged with the agent that produced it */
+interface MultiplexedStreamChunk {
+    chunk: OrchestratorStreamChunk;
+    agentId: string;
+}
+/** Result from a parallel streaming operation */
+interface MultiplexedStreamResult<T = unknown> {
+    stream: AsyncIterable<MultiplexedStreamChunk>;
+    results: Promise<RunResult<unknown>[]>;
+    merge: Promise<T>;
+    abort: () => void;
+    /** Number of chunks dropped due to buffer overflow */
+    getDroppedCount: () => number;
+}
+/** A source stream with its agent ID */
+interface TaggedSource {
+    agentId: string;
+    stream: AsyncIterable<OrchestratorStreamChunk>;
+}
+/**
+ * Merge multiple async iterables into a single multiplexed stream,
+ * tagging each chunk with its source agent ID.
+ *
+ * Race-based merge: pulls from all sources concurrently, emitting
+ * chunks in arrival order. Error chunks from individual agents are
+ * tagged and emitted (other agents continue).
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeTaggedStreams([
+ *   { agentId: "researcher", stream: researchStream },
+ *   { agentId: "writer", stream: writerStream },
+ * ]);
+ *
+ * for await (const { chunk, agentId } of merged) {
+ *   console.log(`[${agentId}]`, chunk);
+ * }
+ * ```
+ */
+/** Result from mergeTaggedStreams */
+interface MergedTaggedStreamResult {
+    stream: AsyncIterable<MultiplexedStreamChunk>;
+    /** Number of chunks dropped due to buffer overflow */
+    getDroppedCount: () => number;
+}
+declare function mergeTaggedStreams(sources: TaggedSource[]): MergedTaggedStreamResult;
+
+/**
+ * Debug Timeline — AI-specific event log with snapshot correlation.
+ *
+ * Records agent lifecycle events (start, complete, error, guardrail checks,
+ * approvals, handoffs, patterns) and correlates them with core time-travel
+ * snapshots for visual timeline UIs and fork-and-replay debugging.
+ *
+ * Zero-cost when debug=false — the timeline is simply `null`.
+ *
+ * @module
+ */
+
+/** Callback fired when a new event is recorded */
+type DebugTimelineListener = (event: DebugEvent) => void;
+/** Debug timeline instance */
+interface DebugTimeline {
+    /** Record a new event (id is auto-assigned) */
+    record(event: Omit<DebugEvent, "id"> & Record<string, unknown>): DebugEvent;
+    /** Get all events in order */
+    getEvents(): DebugEvent[];
+    /** Get events for a specific agent */
+    getEventsForAgent(agentId: string): DebugEvent[];
+    /** Get events by type with type narrowing */
+    getEventsByType<T extends DebugEventType>(type: T): Extract<DebugEvent, {
+        type: T;
+    }>[];
+    /** Get events at a specific snapshot */
+    getEventsAtSnapshot(snapshotId: number): DebugEvent[];
+    /** Get events in a time range */
+    getEventsInRange(startMs: number, endMs: number): DebugEvent[];
+    /** Fork from a snapshot — truncates events after it and calls goTo */
+    forkFrom(snapshotId: number): void;
+    /** Export timeline as JSON */
+    export(): string;
+    /** Import timeline from JSON */
+    import(json: string): void;
+    /** Clear all events */
+    clear(): void;
+    /** Subscribe to new events. Returns unsubscribe function. */
+    subscribe(listener: DebugTimelineListener): () => void;
+    /** Current number of events */
+    readonly length: number;
+}
+/** Options for creating a debug timeline */
+interface DebugTimelineOptions {
+    /** Maximum events before eviction. @default 2000 */
+    maxEvents?: number;
+    /** Callback to get current snapshot ID from the system */
+    getSnapshotId?: () => number | null;
+    /** Callback to navigate to a snapshot (for forkFrom) */
+    goToSnapshot?: (snapshotId: number) => void;
+}
+/**
+ * Create a debug timeline for recording and correlating AI events.
+ *
+ * @example
+ * ```typescript
+ * const timeline = createDebugTimeline({ maxEvents: 1000 });
+ *
+ * timeline.record({
+ *   type: "agent_start",
+ *   timestamp: Date.now(),
+ *   agentId: "researcher",
+ *   snapshotId: null,
+ *   inputLength: 42,
+ * });
+ *
+ * const agentEvents = timeline.getEventsForAgent("researcher");
+ * ```
+ */
+declare function createDebugTimeline(options?: DebugTimelineOptions): DebugTimeline;
+/**
+ * Create a Directive plugin that bridges core constraint/resolver events
+ * to the debug timeline.
+ *
+ * @example
+ * ```typescript
+ * const timeline = createDebugTimeline();
+ * const plugin = createDebugTimelinePlugin(timeline, () => system.debug?.currentIndex ?? null);
+ * ```
+ */
+declare function createDebugTimelinePlugin(timeline: DebugTimeline, getSnapshotId: () => number | null): Plugin;
+
+/**
+ * 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.
+ *
+ * Works with any Zod-compatible schema (any object with a `safeParse` method).
+ *
+ * @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),
+ * });
+ *
+ * const runner = withStructuredOutput(baseRunner, {
+ *   schema: SentimentSchema,
+ *   maxRetries: 2,
+ * });
+ *
+ * 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.
+ *
+ * This interface allows structured outputs to work with Zod, Valibot,
+ * or any validation library that implements this pattern.
+ *
+ * @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" } };
+ *   },
+ * };
+ * ```
+ */
+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 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;
+}
+/** Default JSON extractor — finds the first `{...}` or `[...]` in output. */
+declare function extractJsonFromOutput(output: string): unknown;
+/**
+ * Wrap an AgentRunner with structured output parsing and validation.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ *
+ * const SentimentSchema = z.object({
+ *   sentiment: z.enum(["positive", "negative", "neutral"]),
+ *   confidence: z.number().min(0).max(1),
+ * });
+ *
+ * const runner = withStructuredOutput(baseRunner, {
+ *   schema: SentimentSchema,
+ *   maxRetries: 2,
+ * });
+ *
+ * const result = await runner(agent, "Analyze: I love this product!");
+ * // result.output is typed as { sentiment: string; confidence: number }
+ * ```
+ */
+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>);
+}
+
+/** Orchestrator options */
+interface OrchestratorOptions<F extends Record<string, unknown>> {
+    /** Function to run an agent */
+    runner: AgentRunner;
+    /**
+     * Schema for custom facts tracked in the orchestrator's Directive System.
+     * @example
+     * ```typescript
+     * import { t } from '@directive-run/core';
+     * const orchestrator = createOrchestrator({
+     *   factsSchema: { confidence: t.number(), category: t.string() },
+     *   // ...
+     * });
+     * ```
+     */
+    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;
+    /** Fires when token usage reaches this percentage of maxTokenBudget (0-1). @default 0.8 */
+    budgetWarningThreshold?: number;
+    /** Callback when budget warning threshold is reached */
+    onBudgetWarning?: (event: {
+        currentTokens: number;
+        maxBudget: number;
+        percentage: number;
+    }) => void;
+    /** Plugins */
+    plugins?: Plugin[];
+    /**
+     * Enable debugging — `true` for default debug, or config object for advanced options
+     * @default false
+     */
+    debug?: boolean | OrchestratorDebugConfig;
+    /**
+     * 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;
+    /** Self-healing configuration for automatic fallback */
+    selfHealing?: SelfHealingConfig;
+    /**
+     * Default schema for structured output. When set, agent output is parsed and
+     * validated against this schema with automatic retry on failure.
+     * Any Zod-compatible schema (anything with `safeParse`) works.
+     */
+    outputSchema?: SafeParseable<unknown>;
+    /**
+     * Max retries for structured output parsing.
+     * @default 2
+     */
+    maxSchemaRetries?: number;
+    /** Optional checkpoint store for save/restore workflow state. */
+    checkpointStore?: CheckpointStore;
+    /**
+     * Breakpoint configurations for human-in-the-loop pause points.
+     * Zero overhead when empty — guard checks at each insertion point.
+     */
+    breakpoints?: BreakpointConfig[];
+    /** Callback fired when a breakpoint is hit and waiting for resolution. */
+    onBreakpoint?: (request: BreakpointRequest) => void;
+    /**
+     * Timeout for breakpoint resolution in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    breakpointTimeoutMs?: number;
+}
+/** 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 */
+    signal?: AbortSignal;
+    /** Override structured output schema for this call. Set to `null` to opt out. */
+    outputSchema?: SafeParseable<unknown> | null;
+    /** Override max schema retries for this call. */
+    maxSchemaRetries?: number;
+}
+/** 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;
+    /** Total tokens consumed across all agent runs */
+    readonly totalTokens: number;
+    /** Debug timeline (null when debug is false) */
+    readonly timeline: DebugTimeline | null;
+    /** Wait until agent is idle. Resolves immediately if already idle. */
+    waitForIdle(timeoutMs?: number): Promise<void>;
+    /** Create a checkpoint of the current orchestrator state. Only valid when agent is not running. */
+    checkpoint(options?: {
+        label?: string;
+    }): Promise<Checkpoint>;
+    /** Restore orchestrator state from a checkpoint. */
+    restore(checkpoint: Checkpoint, options?: {
+        restoreTimeline?: boolean;
+    }): void;
+    /** Resume a pending breakpoint, optionally with input modifications. */
+    resumeBreakpoint(id: string, modifications?: BreakpointModifications): void;
+    /** Cancel a pending breakpoint with optional reason. */
+    cancelBreakpoint(id: string, reason?: string): void;
+    /** Get all currently pending breakpoint requests. */
+    getPendingBreakpoints(): BreakpointRequest[];
+    /** Dispose of the orchestrator */
+    dispose(): void;
+}
+/**
+ * Create a constraint-driven agent orchestrator.
+ *
+ * @example
+ * ```typescript
+ * import { run as runner } from '@openai/agents'
+ *
+ * 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 };
+ *       },
+ *     ],
+ *   },
+ * });
+ *
+ * // Run with guardrails and constraint-driven orchestration
+ * const result = await orchestrator.run(myAgent, 'Hello, can you help me?');
+ * ```
+ *
+ * @throws {Error} If autoApproveToolCalls is false but no onApprovalRequest callback is provided
+ */
+declare function createAgentOrchestrator<F extends Record<string, unknown> = Record<string, never>>(options: OrchestratorOptions<F>): AgentOrchestrator<F>;
+
+/**
+ * Agent Reflection / Self-Improvement
+ *
+ * Quality-based iteration: agent produces output → evaluator checks it → retry
+ * with feedback until pass. Works with any AgentRunner.
+ *
+ * Shipped with aggressive safeguards to prevent silent budget burn:
+ * - maxIterations default: 2 (conservative)
+ * - Dev-mode warning for maxIterations > 3
+ * - onIteration fires on every iteration (observable by default)
+ * - Token usage accumulated across iterations
+ *
+ * @example
+ * ```typescript
+ * import { withReflection } from '@directive-run/ai';
+ *
+ * const reflective = withReflection(runner, {
+ *   evaluate: (output) => ({
+ *     passed: output.includes('conclusion'),
+ *     feedback: 'Missing conclusion section',
+ *   }),
+ *   maxIterations: 2,
+ * });
+ *
+ * const result = await reflective(agent, 'Write a report');
+ * ```
+ */
+
+/** Context passed to the reflection evaluator */
+interface ReflectionContext {
+    input: string;
+    /** 0-based iteration number */
+    iteration: number;
+    result: RunResult<unknown>;
+    history: ReflectionEvaluation[];
+}
+/** Result of a reflection evaluation */
+interface ReflectionEvaluation {
+    passed: boolean;
+    feedback?: string;
+    /** Quality score from 0 to 1, optional */
+    score?: number;
+}
+/** Evaluator function for reflection */
+type ReflectionEvaluator<T = unknown> = (output: T, context: ReflectionContext) => ReflectionEvaluation | Promise<ReflectionEvaluation>;
+/** Configuration for the reflection wrapper */
+interface ReflectionConfig<T = unknown> {
+    /** Evaluator function — decides if the output is acceptable */
+    evaluate: ReflectionEvaluator<T>;
+    /** Maximum iterations (including the first). Default: 2 (conservative) */
+    maxIterations?: number;
+    /** Build the retry input from original input + feedback */
+    buildRetryInput?: (input: string, feedback: string, iteration: number) => string;
+    /** Callback on each iteration */
+    onIteration?: (event: {
+        iteration: number;
+        passed: boolean;
+        feedback?: string;
+        score?: number;
+        durationMs: number;
+    }) => void;
+    /** Behavior when maxIterations exhausted. Default: "accept-last" */
+    onExhausted?: "accept-last" | "throw";
+    /** Stop early if budget remaining < threshold (tokens). Works with withBudget. */
+    budgetThreshold?: number;
+}
+/** Error thrown when reflection iterations are exhausted and onExhausted is "throw" */
+declare class ReflectionExhaustedError extends Error {
+    readonly iterations: number;
+    readonly history: ReflectionEvaluation[];
+    readonly lastResult: RunResult<unknown>;
+    readonly totalTokens: number;
+    constructor(options: {
+        iterations: number;
+        history: ReflectionEvaluation[];
+        lastResult: RunResult<unknown>;
+        totalTokens: number;
+    });
+}
+/**
+ * Wrap an AgentRunner with reflection (self-improvement) logic.
+ *
+ * The returned runner runs the agent, evaluates the output, and retries with
+ * feedback if the evaluation fails — up to `maxIterations` times.
+ *
+ * @example
+ * ```typescript
+ * const reflective = withReflection(runner, {
+ *   evaluate: (output) => ({
+ *     passed: typeof output === 'string' && output.length > 100,
+ *     feedback: 'Response too short, please elaborate',
+ *     score: Math.min(1, (output as string).length / 200),
+ *   }),
+ *   maxIterations: 3,
+ *   onExhausted: 'accept-last',
+ * });
+ * ```
+ */
+declare function withReflection<T = unknown>(runner: AgentRunner, config: ReflectionConfig<T>): AgentRunner;
+
+/**
+ * Health Monitor — tracks per-agent health metrics for self-healing networks.
+ *
+ * Pure computation module with zero Directive dependency.
+ * Maintains a rolling window of success/failure events and computes a health
+ * score from 0-100 based on configurable weights.
+ *
+ * @module
+ */
+
+/** Circuit state values */
+type HealthCircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/** Per-agent health metrics */
+interface AgentHealthMetrics {
+    agentId: string;
+    circuitState: HealthCircuitState;
+    successRate: number;
+    avgLatencyMs: number;
+    recentFailures: number;
+    recentSuccesses: number;
+    healthScore: number;
+    /** Last N error messages (most recent last) */
+    lastErrors: string[];
+}
+/** Health monitor instance */
+interface HealthMonitor {
+    recordSuccess(agentId: string, latencyMs: number): void;
+    recordFailure(agentId: string, latencyMs: number, error?: Error): void;
+    getMetrics(agentId: string): AgentHealthMetrics;
+    getAllMetrics(): Record<string, AgentHealthMetrics>;
+    /** Returns a 0-100 health score. Returns 50 (neutral) when no data is available for the agent. */
+    getHealthScore(agentId: string): number;
+    updateCircuitState(agentId: string, state: HealthCircuitState): void;
+    /** Reset all metrics. Useful for testing. */
+    reset(): void;
+}
+/**
+ * Create a health monitor that tracks per-agent metrics.
+ *
+ * @example
+ * ```typescript
+ * const monitor = createHealthMonitor({ windowMs: 30000 });
+ *
+ * monitor.recordSuccess("agent-a", 120);
+ * monitor.recordFailure("agent-a", 5000, new Error("timeout"));
+ *
+ * const score = monitor.getHealthScore("agent-a");
+ * console.log(score); // 0-100
+ * ```
+ */
+declare function createHealthMonitor(config?: HealthMonitorConfig): HealthMonitor;
+
+/** Get the current step/round/iteration count from a pattern checkpoint state */
+declare function getPatternStep(state: PatternCheckpointState): number;
+/** Compute progress from a pattern checkpoint state */
+declare function getCheckpointProgress(state: PatternCheckpointState): CheckpointProgress;
+/** Compute the diff between two checkpoint states */
+declare function diffCheckpoints(a: PatternCheckpointState, b: PatternCheckpointState): CheckpointDiff;
+/**
+ * Fork an orchestrator from a checkpoint — creates a new independent orchestrator
+ * restored to the checkpoint's state, ready to diverge from that point.
+ *
+ * @param options - The original orchestrator options used to create the orchestrator
+ * @param checkpointStore - The checkpoint store containing the checkpoint
+ * @param checkpointId - The ID of the checkpoint to fork from
+ * @returns A new independent MultiAgentOrchestrator restored to checkpoint state
+ *
+ * @example
+ * ```typescript
+ * const forked = await forkFromCheckpoint(orchestratorOptions, store, "ckpt_abc123");
+ * const result = await forked.replay("ckpt_abc123", pattern, { input: "new input" });
+ * ```
+ */
+declare function forkFromCheckpoint(options: MultiAgentOrchestratorOptions, checkpointStore: CheckpointStore, checkpointId: string): Promise<MultiAgentOrchestrator>;
+/**
+ * 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();
+ *   }
+ * }
+ * ```
+ */
+declare class Semaphore {
+    private count;
+    private readonly maxPermits;
+    private readonly queue;
+    constructor(max: number);
+    /** Create a one-shot release function that guards against double-release */
+    private createReleaseFn;
+    /** Acquire a permit, optionally with abort signal support */
+    acquire(signal?: AbortSignal): Promise<() => void>;
+    /** Non-blocking acquire — returns null if no permits available */
+    tryAcquire(): (() => void) | null;
+    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 guardrails (applied in addition to orchestrator-level guardrails) */
+    guardrails?: {
+        input?: Array<GuardrailFn<InputGuardrailData> | NamedGuardrail<InputGuardrailData>>;
+        output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
+        toolCall?: Array<GuardrailFn<ToolCallGuardrailData> | NamedGuardrail<ToolCallGuardrailData>>;
+    };
+    /** Per-agent retry config (overrides orchestrator-level agentRetry) */
+    retry?: AgentRetryConfig;
+    /** Per-agent constraints */
+    constraints?: Record<string, OrchestratorConstraint<Record<string, unknown>>>;
+    /** Per-agent resolvers */
+    resolvers?: Record<string, OrchestratorResolver<Record<string, unknown>, Requirement>>;
+    /** Per-agent memory (overrides orchestrator-level memory) */
+    memory?: AgentMemory;
+    /** Per-agent circuit breaker (overrides orchestrator-level circuitBreaker) */
+    circuitBreaker?: CircuitBreaker;
+    /** Per-agent output schema for structured output */
+    outputSchema?: SafeParseable<unknown>;
+    /** Max retries for structured output validation. @default 2 */
+    maxSchemaRetries?: number;
+    /** Custom JSON extractor for structured output */
+    extractJson?: (output: string) => unknown;
+    /** Description of the schema for structured output prompting */
+    schemaDescription?: string;
+}
+/** Agent registry configuration */
+interface AgentRegistry {
+    [agentId: string]: AgentRegistration;
+}
+/** 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 agents.length */
+    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 JSON.stringify */
+    transform?: (output: unknown, agentId: string, index: number) => string;
+    /** Final result extractor */
+    extract?: (output: unknown) => T;
+    /** Continue on error. @default false */
+    continueOnError?: boolean;
+    /** Checkpoint configuration for mid-execution fault tolerance */
+    checkpoint?: PatternCheckpointConfig;
+}
+/** 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. @default 5 */
+    maxRounds?: number;
+    /** Extract final result */
+    extract?: (supervisorOutput: unknown, workerResults: RunResult<unknown>[]) => T;
+    /** Checkpoint configuration for mid-execution fault tolerance */
+    checkpoint?: PatternCheckpointConfig;
+}
+/** Record of a single reflection iteration (for score history) */
+interface ReflectIterationRecord {
+    iteration: number;
+    passed: boolean;
+    score?: number;
+    feedback?: string;
+    durationMs: number;
+    producerTokens: number;
+    evaluatorTokens: number;
+}
+/**
+ * Reflect pattern - produce, evaluate, retry with feedback.
+ * @see reflect — factory helper
+ * @see ReflectIterationRecord — per-iteration history entries
+ */
+interface ReflectPattern<T = unknown> {
+    type: "reflect";
+    /** Producer agent ID */
+    agent: string;
+    /** Evaluator agent ID (receives output as input) */
+    evaluator: string;
+    /** Maximum iterations. @default 2 */
+    maxIterations?: number;
+    /** Parse evaluator output into ReflectionEvaluation. @default JSON.parse */
+    parseEvaluation?: (output: unknown) => ReflectionEvaluation;
+    /** Build retry input from original input + feedback */
+    buildRetryInput?: (input: string, feedback: string, iteration: number) => string;
+    /** Extract result from raw producer output. Unlike race's extract (which receives RunResult), this receives the output directly since the producer is already selected. */
+    extract?: (output: unknown) => T;
+    /** Behavior when maxIterations exhausted. @default "accept-last" */
+    onExhausted?: "accept-last" | "accept-best" | "throw";
+    /** Callback fired after each iteration with score/feedback data. @see ReflectIterationRecord */
+    onIteration?: (record: ReflectIterationRecord) => void;
+    /** AbortSignal for external cancellation of the reflection loop */
+    signal?: AbortSignal;
+    /** Overall timeout (ms). Creates an internal AbortSignal. */
+    timeout?: number;
+    /** Score threshold for acceptance. Number or function of iteration. When set, evaluator score >= threshold is treated as passed. */
+    threshold?: number | ((iteration: number) => number);
+    /** Checkpoint configuration for mid-execution fault tolerance */
+    checkpoint?: PatternCheckpointConfig;
+}
+/**
+ * Race pattern - first successful agent wins, rest cancelled.
+ * @see race — factory helper
+ * @see RaceResult — return type
+ */
+interface RacePattern<T = unknown> {
+    type: "race";
+    /** Agent IDs to race */
+    agents: string[];
+    /** Extract result from winning RunResult (receives full RunResult for access to tokens/metadata). @default output field */
+    extract?: (result: RunResult<unknown>) => T;
+    /** Overall timeout (ms) */
+    timeout?: number;
+    /** Require N successful results before resolving. @default 1 */
+    minSuccess?: number;
+    /** AbortSignal for external cancellation */
+    signal?: AbortSignal;
+}
+/** Return type from debate pattern execution */
+interface DebateResult<T = unknown> {
+    winnerId: string;
+    result: T;
+    rounds: Array<{
+        proposals: Array<{
+            agentId: string;
+            output: unknown;
+        }>;
+        judgement: {
+            winnerId: string;
+            feedback?: string;
+            score?: number;
+        };
+    }>;
+}
+/** Individual result entry returned when minSuccess > 1 */
+interface RaceSuccessEntry<T = unknown> {
+    agentId: string;
+    result: T;
+}
+/** Return type from race pattern execution */
+interface RaceResult<T = unknown> {
+    winnerId: string;
+    result: T;
+    allResults?: Array<RaceSuccessEntry<T>>;
+}
+/**
+ * Debate pattern - agents compete, evaluator judges across rounds.
+ * @see debate — factory helper
+ * @see runDebate — imperative API
+ * @see DebateResult — return type
+ */
+interface DebatePattern<T = unknown> {
+    type: "debate";
+    /** Agent IDs that will generate competing proposals */
+    agents: string[];
+    /** Evaluator agent ID that judges proposals */
+    evaluator: string;
+    /** Maximum rounds of debate. @default 2 */
+    maxRounds?: number;
+    /** Extract final result from the winning proposal */
+    extract?: (output: unknown) => T;
+    /** Parse evaluator output. @default JSON.parse expecting `{ winnerId, feedback }` */
+    parseJudgement?: (output: unknown) => {
+        winnerId: string;
+        feedback?: string;
+        score?: number;
+    };
+    /** AbortSignal for external cancellation */
+    signal?: AbortSignal;
+    /** Overall timeout (ms). Creates an internal AbortSignal. */
+    timeout?: number;
+    /** Checkpoint configuration for mid-execution fault tolerance */
+    checkpoint?: PatternCheckpointConfig;
+}
+
+/** Union of all patterns */
+type ExecutionPattern<T = unknown> = ParallelPattern<T> | SequentialPattern<T> | SupervisorPattern<T> | DagPattern<T> | ReflectPattern<T> | RacePattern<T> | DebatePattern<T> | GoalPattern<T>;
+/** Handoff request between agents */
+interface HandoffRequest {
+    id: string;
+    fromAgent: string;
+    toAgent: string;
+    input: string;
+    context?: Record<string, unknown>;
+    requestedAt: number;
+}
+/** Handoff result */
+interface HandoffResult {
+    request: HandoffRequest;
+    result: RunResult<unknown>;
+    completedAt: 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 — `true` for default debug, or config object for advanced options */
+    debug?: boolean | OrchestratorDebugConfig;
+    /** Orchestrator-level guardrails (applied to all agents) */
+    guardrails?: GuardrailsConfig;
+    /** Lifecycle hooks */
+    hooks?: MultiAgentLifecycleHooks;
+    /** Shared memory across all agents */
+    memory?: AgentMemory;
+    /** Default retry config for all agents (per-agent overrides this) */
+    agentRetry?: AgentRetryConfig;
+    /** Maximum token budget across all agent runs */
+    maxTokenBudget?: number;
+    /** Fires when token usage reaches this percentage of maxTokenBudget (0-1). @default 0.8 */
+    budgetWarningThreshold?: number;
+    /** Callback when budget warning threshold is reached */
+    onBudgetWarning?: (event: {
+        currentTokens: number;
+        maxBudget: number;
+        percentage: number;
+    }) => void;
+    /** Plugins to attach to the underlying Directive System */
+    plugins?: Plugin[];
+    /** Callback for approval requests */
+    onApprovalRequest?: (request: ApprovalRequest) => void;
+    /** Auto-approve tool calls. @default true */
+    autoApproveToolCalls?: boolean;
+    /** Approval timeout in milliseconds. @default 300000 */
+    approvalTimeoutMs?: number;
+    /** Orchestrator-level constraints */
+    constraints?: Record<string, OrchestratorConstraint<Record<string, unknown>>>;
+    /** Orchestrator-level resolvers */
+    resolvers?: Record<string, OrchestratorResolver<Record<string, unknown>, Requirement>>;
+    /** Orchestrator-level circuit breaker */
+    circuitBreaker?: CircuitBreaker;
+    /** Self-healing configuration for automatic agent rerouting */
+    selfHealing?: MultiAgentSelfHealingConfig;
+    /** Checkpoint store for persistent state */
+    checkpointStore?: CheckpointStore;
+    /** Breakpoints for human-in-the-loop pause/inspect/modify */
+    breakpoints?: BreakpointConfig<MultiAgentBreakpointType>[];
+    /** Callback when a breakpoint fires */
+    onBreakpoint?: (request: BreakpointRequest) => void;
+    /** Timeout for breakpoint resolution (ms). @default 300000 */
+    breakpointTimeoutMs?: number;
+    /** Cross-agent derivation functions — compute values from combined agent states */
+    derive?: Record<string, CrossAgentDerivationFn>;
+    /** Shared scratchpad configuration */
+    scratchpad?: {
+        init: Record<string, unknown>;
+    };
+}
+/** 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[];
+}
+/** Per-call options for multi-agent runAgent/run */
+interface MultiAgentRunCallOptions extends RunOptions {
+    /** Override structured output schema for this call. Set to `null` to opt out of per-agent schema. */
+    outputSchema?: SafeParseable<unknown> | null;
+    /** Override max schema retries for this call. */
+    maxSchemaRetries?: number;
+}
+/** Multi-agent orchestrator instance */
+interface MultiAgentOrchestrator {
+    /** The underlying Directive System */
+    system: System<any>;
+    /** Combined facts from all agent modules + coordinator */
+    facts: Record<string, unknown>;
+    /** Run a single agent */
+    runAgent<T>(agentId: string, input: string, options?: MultiAgentRunCallOptions): Promise<RunResult<T>>;
+    /** Run an agent with streaming support */
+    runAgentStream<T>(agentId: string, input: string, options?: {
+        signal?: AbortSignal;
+    }): OrchestratorStreamResult<T>;
+    /**
+     * Run an execution pattern by its registered pattern ID.
+     *
+     * Note: For race and debate patterns, `runPattern` returns only the extracted result value.
+     * Use `runRace()` or `runDebate()` to access full results including `winnerId` and `allResults`.
+     */
+    runPattern<T>(patternId: string, input: string): Promise<T>;
+    /** Run agents in parallel. Note: parallel does not support checkpoint/resume (single-step pattern). */
+    runParallel<T>(agentIds: string[], inputs: string | string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>, options?: {
+        minSuccess?: number;
+        timeout?: number;
+    }): 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>>;
+    /** 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;
+    /** Total tokens consumed across all agents */
+    readonly totalTokens: number;
+    /** Wait until all agents are idle */
+    waitForIdle(timeoutMs?: number): Promise<void>;
+    /** Alias for runAgent */
+    run<T>(agentId: string, input: string, options?: MultiAgentRunCallOptions): Promise<RunResult<T>>;
+    /** Alias for runAgentStream */
+    runStream<T>(agentId: string, input: string, options?: {
+        signal?: AbortSignal;
+    }): OrchestratorStreamResult<T>;
+    /** Register a new agent dynamically */
+    registerAgent(agentId: string, registration: AgentRegistration): void;
+    /** Unregister an agent (must be idle) */
+    unregisterAgent(agentId: string): void;
+    /** Get registered agent IDs */
+    getAgentIds(): string[];
+    /** 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;
+    /** Debug timeline (null when debug is false) */
+    readonly timeline: DebugTimeline | null;
+    /** Health monitor (null when selfHealing is not configured) */
+    readonly healthMonitor: HealthMonitor | null;
+    /** Create a checkpoint of the current state */
+    checkpoint(options?: {
+        label?: string;
+    }): Promise<Checkpoint>;
+    /** Restore from a checkpoint */
+    restore(checkpoint: Checkpoint, options?: {
+        restoreTimeline?: boolean;
+    }): void;
+    /** Run multiple agents with multiplexed streaming */
+    runParallelStream<T>(agentIds: string[], inputs: string | string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>, options?: {
+        minSuccess?: number;
+        timeout?: number;
+        signal?: AbortSignal;
+    }): MultiplexedStreamResult<T>;
+    /** Resume a paused breakpoint */
+    resumeBreakpoint(id: string, modifications?: BreakpointModifications): void;
+    /** Cancel a paused breakpoint */
+    cancelBreakpoint(id: string, reason?: string): void;
+    /** Get pending breakpoints */
+    getPendingBreakpoints(): BreakpointRequest[];
+    /** Race multiple agents — first successful result wins, rest cancelled. Note: race does not support checkpoint/resume (single-step pattern). */
+    runRace<T>(agentIds: string[], input: string, options?: {
+        extract?: (result: RunResult<unknown>) => T;
+        timeout?: number;
+        minSuccess?: number;
+        signal?: AbortSignal;
+    }): Promise<RaceResult<T>>;
+    /** Run a reflect pattern imperatively (no pre-registration needed) */
+    runReflect<T>(producerId: string, evaluatorId: string, input: string, options?: {
+        maxIterations?: number;
+        parseEvaluation?: (output: unknown) => ReflectionEvaluation;
+        buildRetryInput?: (input: string, feedback: string, iteration: number) => string;
+        extract?: (output: unknown) => T;
+        onExhausted?: "accept-last" | "accept-best" | "throw";
+        onIteration?: (record: ReflectIterationRecord) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        threshold?: number | ((iteration: number) => number);
+    }): Promise<{
+        result: T;
+        iterations: number;
+        history: ReflectIterationRecord[];
+        exhausted: boolean;
+    }>;
+    /** Run a debate imperatively (no pre-registration needed) */
+    runDebate<T>(agentIds: string[], evaluatorId: string, input: string, options?: {
+        maxRounds?: number;
+        extract?: (output: unknown) => T;
+        parseJudgement?: (output: unknown) => {
+            winnerId: string;
+            feedback?: string;
+            score?: number;
+        };
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<DebateResult<T>>;
+    /** Run a goal pattern imperatively — declare desired state, let the runtime resolve */
+    runGoal<T>(nodes: Record<string, GoalNode>, initialInput: string | Record<string, unknown>, when: (facts: Record<string, unknown>) => boolean, options?: {
+        satisfaction?: (facts: Record<string, unknown>) => number;
+        maxSteps?: number;
+        extract?: (facts: Record<string, unknown>) => T;
+        timeout?: number;
+        signal?: AbortSignal;
+        selectionStrategy?: AgentSelectionStrategy;
+        relaxation?: RelaxationTier[];
+        onStep?: GoalPattern["onStep"];
+        onStall?: GoalPattern["onStall"];
+        checkpoint?: PatternCheckpointConfig;
+    }): Promise<GoalResult<T>>;
+    /** Resume a goal pattern from a saved checkpoint */
+    resumeGoal<T>(checkpointState: GoalCheckpointState, pattern: GoalPattern<T>): Promise<GoalResult<T>>;
+    /** Resume a sequential pattern from a saved checkpoint */
+    resumeSequential<T>(checkpointState: SequentialCheckpointState, pattern: SequentialPattern<T>): Promise<T>;
+    /** Resume a supervisor pattern from a saved checkpoint */
+    resumeSupervisor<T>(checkpointState: SupervisorCheckpointState, pattern: SupervisorPattern<T>, options?: {
+        input?: string;
+    }): Promise<T>;
+    /** Resume a reflect pattern from a saved checkpoint */
+    resumeReflect<T>(checkpointState: ReflectCheckpointState, pattern: ReflectPattern<T>, options?: {
+        input?: string;
+    }): Promise<T>;
+    /** Resume a debate pattern from a saved checkpoint */
+    resumeDebate<T>(checkpointState: DebateCheckpointState, pattern: DebatePattern<T>): Promise<DebateResult<T>>;
+    /** Resume a DAG pattern from a saved checkpoint */
+    resumeDag<T>(checkpointState: DagCheckpointState, pattern: DagPattern<T>, options?: {
+        input?: string;
+    }): Promise<T>;
+    /** Replay from a saved checkpoint (auto-detects pattern type) */
+    replay<T>(checkpointId: string, pattern: ExecutionPattern, options?: {
+        input?: string;
+    }): Promise<T>;
+    /**
+     * Get reflection iteration history from last runReflectPattern call.
+     * @deprecated Use the `history` field on the return value from `runReflect()` instead.
+     */
+    getLastReflectionHistory(): ReflectIterationRecord[] | null;
+    /** Cross-agent derived values (frozen snapshot). Empty when derive not configured. */
+    readonly derived: Record<string, unknown>;
+    /** Subscribe to cross-agent derivation changes */
+    onDerivedChange(callback: (id: string, value: unknown) => void): () => void;
+    /** Shared scratchpad (null when not configured) */
+    readonly scratchpad: Scratchpad | null;
+    /** Dispose of the orchestrator, resetting all state */
+    dispose(): void;
+}
+/**
+ * Create a multi-agent orchestrator backed by a Directive System.
+ *
+ * Each registered agent becomes a namespaced Directive module with reactive state,
+ * constraint evaluation, guardrails, streaming, approval, memory, retry, budget,
+ * hooks, and time-travel debugging — all features at parity with `createAgentOrchestrator`.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   runner,
+ *   agents: {
+ *     researcher: { agent: researchAgent, maxConcurrent: 3 },
+ *     writer: { agent: writerAgent },
+ *     reviewer: { agent: reviewerAgent },
+ *   },
+ *   guardrails: {
+ *     input: [detectPII],
+ *     output: [checkToxicity],
+ *   },
+ *   hooks: {
+ *     onAgentStart: ({ agentId, input }) => console.log(`${agentId}: ${input}`),
+ *   },
+ *   maxTokenBudget: 50000,
+ *   debug: true,
+ * });
+ *
+ * // Run with full guardrails + approval + streaming
+ * const result = await orchestrator.runAgent('researcher', 'What is AI?');
+ *
+ * // Stream agent output
+ * const { stream } = orchestrator.runAgentStream('writer', 'Write about AI');
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'token') process.stdout.write(chunk.data);
+ * }
+ * ```
+ *
+ * @throws {Error} If a pattern references an agent that is not in the registry
+ * @throws {Error} If autoApproveToolCalls is false but no onApprovalRequest callback is provided
+ */
+declare function createMultiAgentOrchestrator(options: MultiAgentOrchestratorOptions): MultiAgentOrchestrator;
+/**
+ * Create a parallel pattern configuration.
+ *
+ * @param agents - Agent IDs to run concurrently
+ * @param merge - Combine all agent results into a single output
+ * @param config.merge - Receives all successful RunResults (array may be shorter than agents.length when minSuccess is set). Returns the merged result.
+ * @param options - Optional `minSuccess` and `timeout` overrides
+ *
+ * @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.
+ *
+ * @param agents - Agent IDs to run in order (output of each feeds into the next)
+ * @param options - Optional `transform`, `extract`, `continueOnError`
+ *
+ * @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.
+ *
+ * @param supervisorAgent - Agent ID that coordinates the workers
+ * @param workers - Agent IDs for the worker pool
+ * @param options - Optional `maxRounds` and `extract`
+ *
+ * @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 a DAG execution pattern.
+ *
+ * @param nodes - Node definitions keyed by ID, each with `agent` and optional `deps`
+ * @param merge - Combine DAG outputs into a single result (defaults to `context.outputs`)
+ * @param options - Optional `timeout`, `maxConcurrent`, `onNodeError`
+ *
+ * @example
+ * ```typescript
+ * const researchPipeline = dag(
+ *   {
+ *     fetch: { agent: 'fetcher' },
+ *     analyze: { agent: 'analyzer', deps: ['fetch'] },
+ *     summarize: { agent: 'summarizer', deps: ['analyze'] },
+ *   },
+ *   (context) => context.outputs.summarize,
+ * );
+ * ```
+ */
+declare function dag<T = Record<string, unknown>>(nodes: Record<string, DagNode>, merge?: (context: DagExecutionContext) => T | Promise<T>, options?: {
+    /** Overall timeout in ms for the entire DAG. */
+    timeout?: number;
+    /** Max nodes running concurrently. Default: Infinity */
+    maxConcurrent?: number;
+    /**
+     * Error handling strategy.
+     * - `"fail"` — abort entire DAG on first node error (default)
+     * - `"skip-downstream"` — mark downstream nodes as skipped, other branches continue
+     * - `"continue"` — ignore errors, other branches continue
+     */
+    onNodeError?: "fail" | "skip-downstream" | "continue";
+}): DagPattern<T>;
+/**
+ * Create a reflect pattern configuration.
+ *
+ * @param agent - Producer agent ID that generates output
+ * @param evaluator - Evaluator agent ID that judges quality
+ * @param options - Optional iteration, parsing, signal, and threshold config
+ *
+ * @example
+ * ```typescript
+ * const reviewPattern = reflect('writer', 'reviewer', { maxIterations: 2 });
+ * ```
+ */
+declare function reflect<T>(agent: string, evaluator: string, options?: {
+    maxIterations?: number;
+    parseEvaluation?: (output: unknown) => ReflectionEvaluation;
+    buildRetryInput?: (input: string, feedback: string, iteration: number) => string;
+    extract?: (output: unknown) => T;
+    onExhausted?: "accept-last" | "accept-best" | "throw";
+    onIteration?: (record: ReflectIterationRecord) => void;
+    signal?: AbortSignal;
+    timeout?: number;
+    threshold?: number | ((iteration: number) => number);
+}): ReflectPattern<T>;
+/**
+ * Create a race pattern configuration.
+ *
+ * @param agents - Agent IDs to race concurrently
+ * @param options - Optional `extract`, `timeout`, `minSuccess`, `signal`
+ *
+ * @example
+ * ```typescript
+ * const fastest = race(['fast-model', 'smart-model'], { timeout: 5000 });
+ * ```
+ */
+declare function race<T>(agents: string[], options?: {
+    extract?: (result: RunResult<unknown>) => T;
+    timeout?: number;
+    minSuccess?: number;
+    signal?: AbortSignal;
+}): RacePattern<T>;
+/**
+ * Create a goal execution pattern.
+ *
+ * Declare what each agent produces and requires. The runtime automatically
+ * infers the execution graph from dependency analysis and drives agents
+ * to goal achievement.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = goal(
+ *   {
+ *     researcher: {
+ *       agent: "researcher",
+ *       produces: ["research.findings"],
+ *       requires: ["research.topic"],
+ *       extractOutput: (r) => ({ "research.findings": r.output }),
+ *     },
+ *     writer: {
+ *       agent: "writer",
+ *       produces: ["article.draft"],
+ *       requires: ["research.findings"],
+ *       extractOutput: (r) => ({ "article.draft": r.output }),
+ *     },
+ *   },
+ *   (facts) => facts["article.draft"] != null,
+ *   { maxSteps: 10, extract: (facts) => facts["article.draft"] },
+ * );
+ * ```
+ */
+declare function goal<T = Record<string, unknown>>(nodes: Record<string, GoalNode>, when: (facts: Record<string, unknown>) => boolean, options?: {
+    satisfaction?: (facts: Record<string, unknown>) => number;
+    maxSteps?: number;
+    extract?: (facts: Record<string, unknown>) => T;
+    timeout?: number;
+    signal?: AbortSignal;
+    selectionStrategy?: AgentSelectionStrategy;
+    relaxation?: RelaxationTier[];
+    onStep?: (step: number, facts: Record<string, unknown>, readyNodes: string[]) => void;
+    onStall?: (step: number, metrics: GoalMetrics) => void;
+    checkpoint?: PatternCheckpointConfig;
+}): GoalPattern<T>;
+/**
+ * Selection strategy: run all ready agents (default).
+ */
+declare function allReadyStrategy(): AgentSelectionStrategy;
+/**
+ * Selection strategy: pick agents with the highest historical impact.
+ *
+ * Sorts by average satisfaction delta (descending) and picks the top N.
+ */
+declare function highestImpactStrategy(opts?: {
+    topN?: number;
+}): AgentSelectionStrategy;
+/**
+ * Selection strategy: prefer agents that consume fewer tokens per satisfaction delta.
+ */
+declare function costEfficientStrategy(): AgentSelectionStrategy;
+/**
+ * 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): OrchestratorConstraint<Record<string, unknown>>;
+/**
+ * Create a RUN_AGENT requirement.
+ *
+ * @example
+ * ```typescript
+ * constraints: {
+ *   needsResearch: {
+ *     when: (facts) => facts.hasUnknowns,
+ *     require: (facts) => runAgentRequirement('researcher', facts.query as string),
+ *   },
+ * }
+ * ```
+ */
+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;
+/**
+ * Compose multiple patterns into a pipeline where each pattern's
+ * output feeds as input to the next. Returns an async function
+ * that runs the pipeline on a given orchestrator.
+ *
+ * Between patterns, output is converted to a string input:
+ * - `string` output passes through directly
+ * - Objects are JSON-stringified
+ * - Optionally provide a `transform` to customize between steps
+ *
+ * @example
+ * ```typescript
+ * const workflow = composePatterns(
+ *   parallel(['researcher', 'researcher'], concatResults),
+ *   sequential(['writer', 'reviewer']),
+ * );
+ *
+ * const result = await workflow(orchestrator, 'Research topic X');
+ * ```
+ */
+declare function composePatterns(...patterns: ExecutionPattern[]): (orchestrator: MultiAgentOrchestrator, input: string) => Promise<unknown>;
+/**
+ * Create a capability-based agent selector.
+ *
+ * Given a registry and required capabilities, returns the agent IDs
+ * that match all required capabilities.
+ *
+ * @example
+ * ```typescript
+ * const agents = {
+ *   researcher: { agent: researchAgent, capabilities: ['search', 'summarize'] },
+ *   coder: { agent: coderAgent, capabilities: ['code', 'debug'] },
+ *   writer: { agent: writerAgent, capabilities: ['write', 'edit'] },
+ * };
+ *
+ * const matches = findAgentsByCapability(agents, ['search']);
+ * // Returns ['researcher']
+ *
+ * const matches2 = findAgentsByCapability(agents, ['write', 'edit']);
+ * // Returns ['writer']
+ * ```
+ */
+declare function findAgentsByCapability(registry: AgentRegistry, requiredCapabilities: string[]): string[];
+/**
+ * Create a constraint that auto-routes to an agent based on capabilities.
+ *
+ * @example
+ * ```typescript
+ * const routeByCapability = capabilityRoute(
+ *   agents,
+ *   (facts) => facts.requiredCapabilities as string[],
+ *   (facts) => facts.query as string,
+ * );
+ * ```
+ */
+declare function capabilityRoute(registry: AgentRegistry, getCapabilities: (facts: Record<string, unknown>) => string[], getInput: (facts: Record<string, unknown>) => string, options?: {
+    priority?: number;
+    select?: (matches: string[], registry: AgentRegistry) => string;
+}): OrchestratorConstraint<Record<string, unknown>>;
+/**
+ * Options for spawnOnCondition.
+ */
+interface SpawnOnConditionOptions {
+    /** Priority for the constraint (higher = evaluated first) */
+    priority?: number;
+    /** Additional context passed to the agent */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create a constraint that auto-runs an agent when a condition is met.
+ *
+ * The orchestrator's built-in RUN_AGENT resolver handles execution —
+ * you only need to add this to your `constraints` config.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   agents: { reviewer: { agent: reviewerAgent } },
+ *   constraints: {
+ *     autoReview: spawnOnCondition({
+ *       when: (facts) => (facts.confidence as number) < 0.7,
+ *       agent: 'reviewer',
+ *       input: (facts) => `Review this: ${facts.lastOutput}`,
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function spawnOnCondition(config: {
+    when: (facts: Record<string, unknown>) => boolean;
+    agent: string;
+    input: (facts: Record<string, unknown>) => string;
+    /** Priority for the constraint (higher = evaluated first) */
+    priority?: number;
+    /** Additional context passed to the agent */
+    context?: Record<string, unknown>;
+    /** @deprecated Use top-level `priority` and `context` instead */
+    options?: SpawnOnConditionOptions;
+}): OrchestratorConstraint<Record<string, unknown>>;
+/** Configuration for the debate() factory and runDebate() imperative API. @see DebatePattern */
+type DebateConfig<T = unknown> = Omit<DebatePattern<T>, "type">;
+/**
+ * Create a debate pattern where agents compete and an evaluator picks the best.
+ *
+ * Flow:
+ * 1. All agents produce proposals in parallel
+ * 2. Evaluator receives all proposals and picks a winner
+ * 3. Optionally repeat with evaluator feedback for refinement
+ *
+ * @param config - Debate configuration with `agents`, `evaluator`, and optional settings
+ * @see runDebate for the imperative API
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   agents: {
+ *     optimist: { agent: optimistAgent },
+ *     pessimist: { agent: pessimistAgent },
+ *     judge: { agent: judgeAgent },
+ *   },
+ *   patterns: {
+ *     debate: debate({
+ *       agents: ['optimist', 'pessimist'],
+ *       evaluator: 'judge',
+ *       maxRounds: 2,
+ *     }),
+ *   },
+ * });
+ *
+ * const result = await orchestrator.runPattern('debate', 'Should we invest in X?');
+ * ```
+ */
+declare function debate<T = unknown>(config: DebateConfig<T>): DebatePattern<T>;
+/**
+ * Run a debate imperatively on an orchestrator (no pattern registration needed).
+ * Delegates to `orchestrator.runDebate()` so that lifecycle hooks, debug timeline,
+ * and signal propagation all work correctly.
+ *
+ * @param orchestrator - The multi-agent orchestrator instance
+ * @param config - Debate configuration with agents, evaluator, and optional settings
+ * @param input - The initial input/prompt for the debate
+ * @see debate for the declarative pattern API
+ * @returns The winning agent's output, the winner ID, and all proposals from each round
+ */
+declare function runDebate<T>(orchestrator: MultiAgentOrchestrator, config: DebateConfig<T>, input: string): Promise<DebateResult<T>>;
+/**
+ * Create a constraint that fires when a cross-agent derivation meets a condition.
+ *
+ * Wire this into the orchestrator's `derive` config and `constraints` config together.
+ * The constraint's `when()` reads the derivation value from the orchestrator's derived snapshot.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   agents: { ... },
+ *   derive: {
+ *     totalCost: (snap) => snap.coordinator.globalTokens * 0.001,
+ *   },
+ *   constraints: {
+ *     budgetAlert: derivedConstraint('totalCost', (cost) => cost > 5.0, {
+ *       agent: 'budget-manager',
+ *       input: (value) => `Budget exceeded: $${value}`,
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function derivedConstraint(derivationId: string, condition: (value: unknown) => boolean, action: {
+    agent: string;
+    input: (value: unknown) => string;
+    priority?: number;
+    context?: Record<string, unknown>;
+}): OrchestratorConstraint<Record<string, unknown>>;
+/** Configuration for spawnPool constraint-driven auto-scaling */
+interface SpawnPoolConfig {
+    /** Agent ID to spawn (must be registered in the orchestrator) */
+    agent: string;
+    /** Build the input for each spawned agent. Receives current facts and spawn index (0-based). */
+    input: (facts: Record<string, unknown>, index: number) => string;
+    /** How many agents to spawn. Number or function of facts for dynamic scaling. */
+    count: number | ((facts: Record<string, unknown>) => number);
+    /** Priority for the constraint. @default undefined */
+    priority?: number;
+    /** Additional context passed to each spawned agent */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create a constraint that spawns a pool of agent instances when a condition is met.
+ *
+ * Unlike `spawnOnCondition` (which spawns one agent), `spawnPool` can target N agents.
+ * However, only **one requirement is emitted per constraint evaluation cycle** — the constraint
+ * re-fires on subsequent cycles as long as `when()` returns true, spawning one agent per cycle.
+ *
+ * @see spawnOnCondition — for spawning a single agent
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   agents: { worker: { agent: workerAgent } },
+ *   constraints: {
+ *     scaleWorkers: spawnPool(
+ *       (facts) => (facts.pendingTasks as number) > 0,
+ *       {
+ *         agent: 'worker',
+ *         count: (facts) => Math.min(facts.pendingTasks as number, 5),
+ *         input: (facts, i) => `Process task ${i + 1}`,
+ *       },
+ *     ),
+ *   },
+ * });
+ * ```
+ */
+declare function spawnPool(when: (facts: Record<string, unknown>) => boolean, config: SpawnPoolConfig): OrchestratorConstraint<Record<string, unknown>>;
+/** Serialized DAG node (functions stripped) */
+interface SerializedDagNode {
+    agent: string;
+    deps?: string[];
+    timeout?: number;
+    priority?: number;
+}
+/** JSON-safe representation of any execution pattern (all functions stripped) */
+type SerializedPattern = {
+    type: "parallel";
+    agents: string[];
+    minSuccess?: number;
+    timeout?: number;
+} | {
+    type: "sequential";
+    agents: string[];
+    continueOnError?: boolean;
+} | {
+    type: "supervisor";
+    supervisor: string;
+    workers: string[];
+    maxRounds?: number;
+} | {
+    type: "dag";
+    nodes: Record<string, SerializedDagNode>;
+    timeout?: number;
+    maxConcurrent?: number;
+    onNodeError?: "fail" | "skip-downstream" | "continue";
+} | {
+    type: "reflect";
+    agent: string;
+    evaluator: string;
+    maxIterations?: number;
+    onExhausted?: "accept-last" | "accept-best" | "throw";
+    timeout?: number;
+    threshold?: number;
+} | {
+    type: "race";
+    agents: string[];
+    timeout?: number;
+    minSuccess?: number;
+} | {
+    type: "debate";
+    agents: string[];
+    evaluator: string;
+    maxRounds?: number;
+    timeout?: number;
+} | {
+    type: "goal";
+    nodes: Record<string, SerializedGoalNode>;
+    maxSteps?: number;
+    timeout?: number;
+};
+/** Serialized goal node (functions stripped) */
+interface SerializedGoalNode {
+    agent: string;
+    produces: string[];
+    requires?: string[];
+    allowRerun?: boolean;
+    priority?: number;
+}
+/**
+ * Serialize an execution pattern to a JSON-safe object.
+ *
+ * Strips all function callbacks and runtime objects (AbortSignal) while
+ * preserving the topology — which agents, in what structure, with what
+ * numeric/string/boolean options.
+ *
+ * Use this for visual editors, LLM-generated plans, persistence, or
+ * debugging. Restore with {@link patternFromJSON}.
+ *
+ * Note: Function-form `threshold` on reflect patterns is not serializable and will be dropped.
+ * Re-supply it via `overrides` when calling {@link patternFromJSON}.
+ *
+ * @example
+ * ```typescript
+ * const p = parallel({ agents: ["a", "b"], merge: (r) => r });
+ * const json = patternToJSON(p);
+ * // { type: "parallel", agents: ["a", "b"] }
+ * localStorage.setItem("plan", JSON.stringify(json));
+ * ```
+ */
+declare function patternToJSON(pattern: ExecutionPattern<unknown>): SerializedPattern;
+/**
+ * Restore an execution pattern from its serialized form.
+ *
+ * Returns the data structure with all function fields set to `undefined`.
+ * Supply callbacks via the optional `overrides` parameter to re-attach
+ * runtime behavior.
+ *
+ * @example
+ * ```typescript
+ * const json = JSON.parse(localStorage.getItem("plan")!);
+ * const pattern = patternFromJSON<string[]>(json, {
+ *   merge: (results) => results.map(r => r.output as string),
+ * });
+ * // Use the imperative API — runPattern takes a registered pattern ID, not an object
+ * if (pattern.type === "parallel") {
+ *   const result = await orchestrator.runParallel(pattern.agents, input, pattern.merge);
+ * }
+ * ```
+ */
+declare function patternFromJSON<T = unknown>(json: SerializedPattern, overrides?: Partial<ExecutionPattern<T>>): ExecutionPattern<T>;
+
+export { type SafeParseResult as $, type AgentHealthMetrics as A, type BackpressureStrategy as B, type MultiplexedStreamChunk as C, type DebugTimeline as D, type ExecutionPattern as E, type MultiplexedStreamResult as F, type GuardrailTriggeredChunk as G, type HealthMonitor as H, type OrchestratorStreamChunk as I, type OrchestratorStreamResult as J, type ProgressChunk as K, type RaceResult as L, type MemoryManageResult as M, type RaceSuccessEntry as N, type OrchestratorOptions as O, type ParallelPattern as P, type ReflectIterationRecord as Q, type RacePattern as R, type SerializedPattern as S, type ReflectPattern as T, type ReflectionConfig as U, type ReflectionContext as V, type ReflectionEvaluation as W, type ReflectionEvaluator as X, ReflectionExhaustedError as Y, type RunAgentRequirement as Z, type RunCallOptions as _, type AgentMemory as a, race as a$, type SafeParseable as a0, Semaphore as a1, type SequentialPattern as a2, type SerializedDagNode as a3, type SerializedGoalNode as a4, type SpawnOnConditionOptions as a5, type SpawnPoolConfig as a6, type StreamChunk as a7, type StreamRunOptions as a8, type StreamRunner as a9, createLLMSummarizer as aA, createLengthStreamingGuardrail as aB, createMultiAgentOrchestrator as aC, createPatternStreamingGuardrail as aD, createSlidingWindowStrategy as aE, createStreamingRunner as aF, createTokenBasedStrategy as aG, createToxicityStreamingGuardrail as aH, createTruncationSummarizer as aI, dag as aJ, debate as aK, derivedConstraint as aL, diffCheckpoints as aM, extractJsonFromOutput as aN, filterStream as aO, findAgentsByCapability as aP, forkFromCheckpoint as aQ, getCheckpointProgress as aR, getPatternStep as aS, goal as aT, highestImpactStrategy as aU, mapStream as aV, mergeTaggedStreams as aW, parallel as aX, patternFromJSON as aY, patternToJSON as aZ, pickBestResult as a_, type StreamingGuardrail as aa, type StreamingGuardrailResult as ab, type StreamingRunResult as ac, type StructuredOutputConfig as ad, StructuredOutputError as ae, type SupervisorPattern as af, type TokenChunk as ag, type ToolEndChunk as ah, type ToolStartChunk as ai, adaptOutputGuardrail as aj, aggregateTokens as ak, allReadyStrategy as al, capabilityRoute as am, collectOutputs as an, collectTokens as ao, combineStreamingGuardrails as ap, composePatterns as aq, concatResults as ar, costEfficientStrategy as as, createAgentMemory as at, createAgentOrchestrator as au, createDebugTimeline as av, createDebugTimelinePlugin as aw, createHealthMonitor as ax, createHybridStrategy as ay, createKeyPointsSummarizer as az, type AgentMemoryConfig as b, reflect as b0, runAgentRequirement as b1, runDebate as b2, selectAgent as b3, sequential as b4, spawnOnCondition as b5, spawnPool as b6, supervisor as b7, tapStream as b8, withReflection as b9, withStructuredOutput as ba, type AgentOrchestrator as c, type AgentRegistration as d, type AgentRegistry as e, type DebateConfig as f, type DebatePattern as g, type DebateResult as h, type DebugTimelineListener as i, type DebugTimelineOptions as j, type DoneChunk as k, type ErrorChunk as l, type HandoffRequest as m, type HandoffResult as n, type HealthCircuitState as o, type MemoryState as p, type MemoryStrategy as q, type MemoryStrategyConfig as r, type MemoryStrategyResult as s, type MergedTaggedStreamResult as t, type MessageChunk as u, type MessageSummarizer as v, type MultiAgentOrchestrator as w, type MultiAgentOrchestratorOptions as x, type MultiAgentRunCallOptions as y, type MultiAgentState as z };