@directive-run/ai 0.3.0 → 0.4.1

package/dist/{multi-agent-orchestrator-uMp8bLfV.d.ts → multi-agent-orchestrator-CH-4Fqzg.d.ts}

@@ -1,4 +1,4 @@
-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 { 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-D5veI9su.js';
 import { Plugin, System, Requirement } from '@directive-run/core';
 import { CircuitBreaker } from '@directive-run/core/plugins';
 
@@ -130,9 +130,13 @@ interface AgentMemory {
     import(state: MemoryState): void;
 }
 /**
- * Create a sliding window memory strategy.
+ * Create a sliding window memory strategy that keeps the most recent N messages.
  *
- * Keeps the most recent N messages, moving older ones to summarization.
+ * Messages beyond `maxMessages` are moved to the summarization queue.
+ * The most recent `preserveRecentCount` messages are always kept.
+ *
+ * @param defaultConfig - Default strategy configuration (can be overridden per-call).
+ * @returns A {@link MemoryStrategy} function.
  *
  * @example
  * ```typescript
@@ -141,12 +145,17 @@ interface AgentMemory {
  *   preserveRecentCount: 10,
  * });
  * ```
+ * @public
  */
 declare function createSlidingWindowStrategy(defaultConfig?: MemoryStrategyConfig): MemoryStrategy;
 /**
- * Create a token-based memory strategy.
+ * Create a token-based memory strategy that keeps messages until a token limit is reached.
+ *
+ * Adds messages from newest to oldest until `maxTokens` would be exceeded,
+ * then moves the remaining older messages to the summarization queue.
  *
- * Keeps messages until a token limit is reached, then moves older ones to summarization.
+ * @param defaultConfig - Default strategy configuration (can be overridden per-call).
+ * @returns A {@link MemoryStrategy} function.
  *
  * @example
  * ```typescript
@@ -155,11 +164,18 @@ declare function createSlidingWindowStrategy(defaultConfig?: MemoryStrategyConfi
  *   preserveRecentCount: 5,
  * });
  * ```
+ * @public
  */
 declare function createTokenBasedStrategy(defaultConfig?: MemoryStrategyConfig): MemoryStrategy;
 /**
  * Create a hybrid strategy that combines message count and token limits.
  *
+ * Applies both {@link createSlidingWindowStrategy} and {@link createTokenBasedStrategy},
+ * then uses whichever result keeps fewer messages (the more restrictive outcome).
+ *
+ * @param defaultConfig - Default strategy configuration (can be overridden per-call).
+ * @returns A {@link MemoryStrategy} function.
+ *
  * @example
  * ```typescript
  * const strategy = createHybridStrategy({
@@ -168,10 +184,18 @@ declare function createTokenBasedStrategy(defaultConfig?: MemoryStrategyConfig):
  *   preserveRecentCount: 5,
  * });
  * ```
+ * @public
  */
 declare function createHybridStrategy(defaultConfig?: MemoryStrategyConfig): MemoryStrategy;
 /**
- * Create an agent memory instance.
+ * Create an agent memory instance for managing conversation history.
+ *
+ * Provides sliding window management, automatic summarization of older messages,
+ * and import/export for persistence. Pass the returned instance to an orchestrator's
+ * `memory` option to auto-inject context and auto-store results.
+ *
+ * @param config - Memory configuration including strategy, optional summarizer, and auto-manage settings.
+ * @returns An {@link AgentMemory} instance with `addMessage`, `getContextMessages`, `manage`, and `export`/`import` APIs.
  *
  * @example
  * ```typescript
@@ -190,20 +214,38 @@ declare function createHybridStrategy(defaultConfig?: MemoryStrategyConfig): Mem
  *   autoManage: true,
  * });
  * ```
+ * @public
  */
 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.
+ * Create a simple truncation summarizer that clips messages to a maximum length.
+ *
+ * Useful for testing or when LLM-based summarization is not needed.
+ * Concatenates non-system messages with role prefixes and truncates to `maxLength`.
+ *
+ * @param maxLength - Maximum character length of the summary (default: 500).
+ * @returns A {@link MessageSummarizer} function.
+ * @public
  */
 declare function createTruncationSummarizer(maxLength?: number): MessageSummarizer;
 /**
- * Create a summarizer that extracts only user questions and key assistant answers.
+ * Create a summarizer that extracts user questions from messages.
+ *
+ * Scans for sentences ending with `?` in user messages and lists them as key topics.
+ *
+ * @returns A {@link MessageSummarizer} function.
+ * @public
  */
 declare function createKeyPointsSummarizer(): MessageSummarizer;
 /**
- * Create a summarizer factory for LLM-based summarization.
- * You provide the LLM call function, this handles the prompt.
+ * Create a summarizer that delegates to an LLM for conversation compression.
+ *
+ * You provide the LLM call function; this handles prompt construction
+ * including length limits and key-fact preservation instructions.
+ *
+ * @param llmCall - Async function that sends a prompt to an LLM and returns the response text.
+ * @param options - Optional `maxSummaryLength` and `preserveKeyFacts` settings.
+ * @returns A {@link MessageSummarizer} function.
  *
  * @example
  * ```typescript
@@ -215,6 +257,7 @@ declare function createKeyPointsSummarizer(): MessageSummarizer;
  *   return response.choices[0].message.content ?? '';
  * });
  * ```
+ * @public
  */
 declare function createLLMSummarizer(llmCall: (prompt: string) => Promise<string>, options?: {
     maxSummaryLength?: number;
@@ -549,6 +592,12 @@ interface MergedTaggedStreamResult {
     /** Number of chunks dropped due to buffer overflow */
     getDroppedCount: () => number;
 }
+/**
+ * Merge multiple tagged async iterables into a single multiplexed stream.
+ *
+ * @param sources - Array of tagged source streams to merge.
+ * @returns A merged stream result with a `getDroppedCount` accessor.
+ */
 declare function mergeTaggedStreams(sources: TaggedSource[]): MergedTaggedStreamResult;
 
 /**
@@ -953,11 +1002,19 @@ interface AgentOrchestrator<F extends Record<string, unknown>> {
     dispose(): void;
 }
 /**
- * Create a constraint-driven agent orchestrator.
+ * Create a constraint-driven agent orchestrator backed by a Directive System.
+ *
+ * Wraps a single agent runner with reactive state, guardrails, streaming,
+ * approval workflows, breakpoints, structured output, and lifecycle hooks.
+ * Constraints and resolvers let you declaratively control agent behavior
+ * based on runtime facts.
+ *
+ * @param options - Orchestrator configuration including runner, guardrails, constraints, and plugins.
+ * @returns An {@link AgentOrchestrator} instance with `run`, `runStream`, `approve`/`reject`, and checkpoint APIs.
  *
  * @example
  * ```typescript
- * import { run as runner } from '@openai/agents'
+ * import { run as runner } from '@openai/agents';
  *
  * const orchestrator = createAgentOrchestrator({
  *   runner,
@@ -994,10 +1051,63 @@ interface AgentOrchestrator<F extends Record<string, unknown>> {
  * const result = await orchestrator.run(myAgent, 'Hello, can you help me?');
  * ```
  *
- * @throws {Error} If autoApproveToolCalls is false but no onApprovalRequest callback is provided
+ * @throws If autoApproveToolCalls is false but no onApprovalRequest callback is provided
+ * @public
  */
 declare function createAgentOrchestrator<F extends Record<string, unknown> = Record<string, never>>(options: OrchestratorOptions<F>): AgentOrchestrator<F>;
 
+/**
+ * Health Monitor — tracks per-agent health metrics for self-healing networks.
+ *
+ * Pure computation module with zero Directive dependency.
+ * Maintains a rolling window of success/failure events and computes a health
+ * score from 0-100 based on configurable weights.
+ *
+ * @module
+ */
+
+/** Circuit state values */
+type HealthCircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/** Per-agent health metrics */
+interface AgentHealthMetrics {
+    agentId: string;
+    circuitState: HealthCircuitState;
+    successRate: number;
+    avgLatencyMs: number;
+    recentFailures: number;
+    recentSuccesses: number;
+    healthScore: number;
+    /** Last N error messages (most recent last) */
+    lastErrors: string[];
+}
+/** Health monitor instance */
+interface HealthMonitor {
+    recordSuccess(agentId: string, latencyMs: number): void;
+    recordFailure(agentId: string, latencyMs: number, error?: Error): void;
+    getMetrics(agentId: string): AgentHealthMetrics;
+    getAllMetrics(): Record<string, AgentHealthMetrics>;
+    /** Returns a 0-100 health score. Returns 50 (neutral) when no data is available for the agent. */
+    getHealthScore(agentId: string): number;
+    updateCircuitState(agentId: string, state: HealthCircuitState): void;
+    /** Reset all metrics. Useful for testing. */
+    reset(): void;
+}
+/**
+ * Create a health monitor that tracks per-agent metrics.
+ *
+ * @example
+ * ```typescript
+ * const monitor = createHealthMonitor({ windowMs: 30000 });
+ *
+ * monitor.recordSuccess("agent-a", 120);
+ * monitor.recordFailure("agent-a", 5000, new Error("timeout"));
+ *
+ * const score = monitor.getHealthScore("agent-a");
+ * console.log(score); // 0-100
+ * ```
+ */
+declare function createHealthMonitor(config?: HealthMonitorConfig): HealthMonitor;
+
 /**
  * Agent Reflection / Self-Improvement
  *
@@ -1099,62 +1209,38 @@ declare class ReflectionExhaustedError extends Error {
 declare function withReflection<T = unknown>(runner: AgentRunner, config: ReflectionConfig<T>): AgentRunner;
 
 /**
- * Health Monitor — tracks per-agent health metrics for self-healing networks.
+ * Get the current step/round/iteration count from a pattern checkpoint state.
  *
- * 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.
+ * Maps each pattern type to its natural progress counter: `step` for sequential
+ * and goal, `round` for supervisor and debate, `iteration` for reflect, and
+ * `completedCount` for DAG.
  *
- * @module
+ * @param state - The pattern checkpoint state to inspect.
+ * @returns The current progress count for the pattern.
  */
-
-/** 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;
-}
+declare function getPatternStep(state: PatternCheckpointState): number;
 /**
- * Create a health monitor that tracks per-agent metrics.
- *
- * @example
- * ```typescript
- * const monitor = createHealthMonitor({ windowMs: 30000 });
+ * Compute progress metrics from a pattern checkpoint state.
  *
- * monitor.recordSuccess("agent-a", 120);
- * monitor.recordFailure("agent-a", 5000, new Error("timeout"));
+ * Returns percentage complete, steps completed/remaining, tokens consumed,
+ * and estimated tokens remaining (when computable). Each pattern type
+ * calculates these metrics from its own state structure.
  *
- * const score = monitor.getHealthScore("agent-a");
- * console.log(score); // 0-100
- * ```
+ * @param state - The pattern checkpoint state to analyze.
+ * @returns A {@link CheckpointProgress} object with completion metrics.
  */
-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 */
+/**
+ * Compute the diff between two checkpoint states of the same pattern type.
+ *
+ * Returns the delta in steps, tokens, and time between checkpoints.
+ * Useful for understanding how much progress occurred between saves.
+ *
+ * @param a - The earlier checkpoint state.
+ * @param b - The later checkpoint state.
+ * @returns A {@link CheckpointDiff} with step, token, and time deltas.
+ * @throws If the two checkpoints have different pattern types.
+ */
 declare function diffCheckpoints(a: PatternCheckpointState, b: PatternCheckpointState): CheckpointDiff;
 /**
  * Fork an orchestrator from a checkpoint — creates a new independent orchestrator
@@ -1256,25 +1342,25 @@ interface AgentRegistration {
 interface AgentRegistry {
     [agentId: string]: AgentRegistration;
 }
-/** Parallel execution pattern - run agents concurrently and merge results */
+/** Parallel execution pattern - run handlers 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 */
+    /** Handler IDs (agents or tasks) to run in parallel (can repeat for multiple instances) */
+    handlers: string[];
+    /** Function to merge results from all handlers */
     merge: (results: RunResult<unknown>[]) => T | Promise<T>;
-    /** Minimum successful results required. @default agents.length */
+    /** Minimum successful results required. @default handlers.length */
     minSuccess?: number;
     /** Overall timeout (ms) */
     timeout?: number;
 }
-/** Sequential execution pattern - pipeline of agents */
+/** Sequential execution pattern - pipeline of handlers */
 interface SequentialPattern<T = unknown> {
     type: "sequential";
-    /** Agent IDs in execution order */
-    agents: string[];
+    /** Handler IDs (agents or tasks) in execution order */
+    handlers: string[];
     /** Transform output to next input. @default JSON.stringify */
-    transform?: (output: unknown, agentId: string, index: number) => string;
+    transform?: (output: unknown, handlerId: string, index: number) => string;
     /** Final result extractor */
     extract?: (output: unknown) => T;
     /** Continue on error. @default false */
@@ -1313,8 +1399,8 @@ interface ReflectIterationRecord {
  */
 interface ReflectPattern<T = unknown> {
     type: "reflect";
-    /** Producer agent ID */
-    agent: string;
+    /** Producer handler ID (agent or task) */
+    handler: string;
     /** Evaluator agent ID (receives output as input) */
     evaluator: string;
     /** Maximum iterations. @default 2 */
@@ -1345,8 +1431,8 @@ interface ReflectPattern<T = unknown> {
  */
 interface RacePattern<T = unknown> {
     type: "race";
-    /** Agent IDs to race */
-    agents: string[];
+    /** Handler IDs (agents or tasks) to race */
+    handlers: 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) */
@@ -1391,8 +1477,8 @@ interface RaceResult<T = unknown> {
  */
 interface DebatePattern<T = unknown> {
     type: "debate";
-    /** Agent IDs that will generate competing proposals */
-    agents: string[];
+    /** Handler IDs (agents or tasks) that will generate competing proposals */
+    handlers: string[];
     /** Evaluator agent ID that judges proposals */
     evaluator: string;
     /** Maximum rounds of debate. @default 2 */
@@ -1437,12 +1523,57 @@ interface RunAgentRequirement extends Requirement {
     input: string;
     context?: Record<string, unknown>;
 }
+/** Read-only context passed to task functions */
+interface TaskContext {
+    /** The ID of this task */
+    taskId: string;
+    /** Conversation history from orchestrator memory (read-only deep copy) */
+    memory: ReadonlyArray<{
+        role: string;
+        content: string;
+    }>;
+    /** Current scratchpad state (read-only deep copy) */
+    scratchpad: Readonly<Record<string, unknown>>;
+    /** Read the state of any registered agent or task (status, lastOutput, lastError, totalTokens) */
+    readAgentState: (nodeId: string) => Readonly<{
+        status: string;
+        lastOutput?: string;
+        lastError?: string;
+        totalTokens: number;
+    }> | undefined;
+    /** Report intermediate progress (0-100) for DevTools timeline */
+    reportProgress: (percent: number, message?: string) => void;
+}
+/** Configuration for a registered task (imperative code) */
+interface TaskRegistration {
+    /** The function to execute. Receives input, abort signal, and context. */
+    run: (input: string, signal: AbortSignal, context: TaskContext) => unknown | Promise<unknown>;
+    /** Display label for DevTools graph. Defaults to task ID. */
+    label?: string;
+    /** Description for DevTools tooltip/detail panel. */
+    description?: string;
+    /** Timeout (ms) */
+    timeout?: number;
+    /** Max concurrent executions of this task. @default 1 */
+    maxConcurrent?: number;
+    /** Optional retry configuration for transient failures */
+    retry?: {
+        /** Max number of attempts (including the first try) */
+        attempts: number;
+        /** Backoff strategy between retries. @default 'fixed' */
+        backoff?: "fixed" | "exponential";
+        /** Base delay between retries (ms). @default 1000 */
+        delayMs?: number;
+    };
+}
 /** Multi-agent orchestrator options */
 interface MultiAgentOrchestratorOptions {
     /** Base run function */
     runner: AgentRunner;
     /** Registered agents */
     agents: AgentRegistry;
+    /** Imperative code tasks, referenced by ID in patterns (same namespace as agents) */
+    tasks?: Record<string, TaskRegistration>;
     /** Execution patterns */
     patterns?: Record<string, ExecutionPattern>;
     /** Handoff callbacks */
@@ -1524,6 +1655,8 @@ interface MultiAgentRunCallOptions extends RunOptions {
     outputSchema?: SafeParseable<unknown> | null;
     /** Override max schema retries for this call. */
     maxSchemaRetries?: number;
+    /** Pattern ID that initiated this run (for lifecycle hooks). Set internally by pattern executors. */
+    patternId?: string;
 }
 /** Multi-agent orchestrator instance */
 interface MultiAgentOrchestrator {
@@ -1579,6 +1712,35 @@ interface MultiAgentOrchestrator {
     unregisterAgent(agentId: string): void;
     /** Get registered agent IDs */
     getAgentIds(): string[];
+    /** Register a new task dynamically */
+    registerTask(taskId: string, registration: TaskRegistration): void;
+    /** Unregister a task */
+    unregisterTask(taskId: string): void;
+    /** Get registered task IDs */
+    getTaskIds(): string[];
+    /** Get task registry info (labels + descriptions) */
+    getTaskRegistry(): Record<string, {
+        label?: string;
+        description?: string;
+    }>;
+    /** Get task state */
+    getTaskState(taskId: string): {
+        status: string;
+        lastOutput?: unknown;
+        lastError?: string;
+        startTime?: number;
+        durationMs?: number;
+    } | undefined;
+    /** Get all task states */
+    getAllTaskStates(): Record<string, {
+        status: string;
+        lastOutput?: unknown;
+        lastError?: string;
+        startTime?: number;
+        durationMs?: number;
+    }>;
+    /** Get all handler IDs (agents + tasks combined) */
+    getNodeIds(): string[];
     /** Get agent state */
     getAgentState(agentId: string): MultiAgentState["__agents"][string] | undefined;
     /** Get all agent states */
@@ -1684,7 +1846,6 @@ interface MultiAgentOrchestrator {
     }): 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. */
@@ -1701,7 +1862,10 @@ interface MultiAgentOrchestrator {
  *
  * 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`.
+ * hooks, and time-travel debugging -- all features at parity with {@link createAgentOrchestrator}.
+ *
+ * @param options - Orchestrator configuration including runner, agent registry, patterns, guardrails, and plugins.
+ * @returns A {@link MultiAgentOrchestrator} instance with `runAgent`, `runPattern`, `handoff`, and checkpoint APIs.
  *
  * @example
  * ```typescript
@@ -1733,62 +1897,68 @@ interface MultiAgentOrchestrator {
  * }
  * ```
  *
- * @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
+ * @throws If a pattern references an agent that is not in the registry
+ * @throws If autoApproveToolCalls is false but no onApprovalRequest callback is provided
+ * @public
  */
 declare function createMultiAgentOrchestrator(options: MultiAgentOrchestratorOptions): MultiAgentOrchestrator;
 /**
- * Create a parallel pattern configuration.
+ * Create a parallel execution pattern that runs handlers concurrently and merges results.
  *
- * @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
+ * @param handlers - Handler IDs (agents or tasks) to run concurrently.
+ * @param merge - Combine all handler results into a single output (array may be shorter than handlers when `minSuccess` is set).
+ * @param options - Optional `minSuccess` and `timeout` overrides.
+ * @returns A {@link ParallelPattern} configuration object.
  *
  * @example
  * ```typescript
  * const researchPattern = parallel(
  *   ['researcher', 'researcher', 'researcher'],
- *   (results) => results.map(r => r.output).join('\n')
+ *   (results) => results.map(r => r.output).join('\n'),
  * );
  * ```
  */
-declare function parallel<T>(agents: string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>, options?: {
+declare function parallel<T>(handlers: string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>, options?: {
     minSuccess?: number;
     timeout?: number;
 }): ParallelPattern<T>;
 /**
- * Create a sequential pattern configuration.
+ * Create a sequential execution pattern that pipes output from one handler to the next.
  *
- * @param agents - Agent IDs to run in order (output of each feeds into the next)
- * @param options - Optional `transform`, `extract`, `continueOnError`
+ * @param handlers - Handler IDs (agents or tasks) to run in order, where each handler's output feeds as input to the next.
+ * @param options - Optional `transform`, `extract`, and `continueOnError` overrides.
+ * @returns A {@link SequentialPattern} configuration object.
  *
  * @example
  * ```typescript
  * const writeReviewPattern = sequential(
  *   ['writer', 'reviewer'],
- *   { transform: (output) => `Review this: ${output}` }
+ *   { transform: (output) => `Review this: ${output}` },
  * );
  * ```
  */
-declare function sequential<T>(agents: string[], options?: {
-    transform?: (output: unknown, agentId: string, index: number) => string;
+declare function sequential<T>(handlers: string[], options?: {
+    transform?: (output: unknown, handlerId: string, index: number) => string;
     extract?: (output: unknown) => T;
     continueOnError?: boolean;
 }): SequentialPattern<T>;
 /**
- * Create a supervisor pattern configuration.
+ * Create a supervisor pattern where a coordinating agent delegates work to a pool of workers.
+ *
+ * The supervisor runs first, then dispatches tasks to workers based on its output.
+ * This repeats for up to `maxRounds` until the supervisor signals completion.
  *
- * @param supervisorAgent - Agent ID that coordinates the workers
- * @param workers - Agent IDs for the worker pool
- * @param options - Optional `maxRounds` and `extract`
+ * @param supervisorAgent - Agent ID that coordinates the workers.
+ * @param workers - Agent IDs for the worker pool.
+ * @param options - Optional `maxRounds` and `extract` overrides.
+ * @returns A {@link SupervisorPattern} configuration object.
  *
  * @example
  * ```typescript
  * const managedPattern = supervisor(
  *   'manager',
  *   ['worker1', 'worker2'],
- *   { maxRounds: 3 }
+ *   { maxRounds: 3 },
  * );
  * ```
  */
@@ -1797,19 +1967,23 @@ declare function supervisor<T>(supervisorAgent: string, workers: string[], optio
     extract?: (supervisorOutput: unknown, workerResults: RunResult<unknown>[]) => T;
 }): SupervisorPattern<T>;
 /**
- * Create a DAG execution pattern.
+ * Create a directed acyclic graph (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`
+ * Nodes run concurrently when their dependencies are satisfied. The runtime
+ * validates the graph is acyclic and that all dependency references are valid.
+ *
+ * @param nodes - Node definitions keyed by ID, each with a `handler` and optional `deps` array.
+ * @param merge - Combine DAG outputs into a single result (defaults to `context.outputs`).
+ * @param options - Optional `timeout`, `maxConcurrent`, and `onNodeError` strategy.
+ * @returns A {@link DagPattern} configuration object.
  *
  * @example
  * ```typescript
  * const researchPipeline = dag(
  *   {
- *     fetch: { agent: 'fetcher' },
- *     analyze: { agent: 'analyzer', deps: ['fetch'] },
- *     summarize: { agent: 'summarizer', deps: ['analyze'] },
+ *     fetch: { handler: 'fetcher' },
+ *     analyze: { handler: 'analyzer', deps: ['fetch'] },
+ *     summarize: { handler: 'summarizer', deps: ['analyze'] },
  *   },
  *   (context) => context.outputs.summarize,
  * );
@@ -1829,18 +2003,23 @@ declare function dag<T = Record<string, unknown>>(nodes: Record<string, DagNode>
     onNodeError?: "fail" | "skip-downstream" | "continue";
 }): DagPattern<T>;
 /**
- * Create a reflect pattern configuration.
+ * Create a reflect pattern that iterates between a producer and evaluator until quality is met.
+ *
+ * The producer generates output, then the evaluator scores it. If the score
+ * is below the threshold, the producer retries with evaluator feedback,
+ * up to `maxIterations` times.
  *
- * @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
+ * @param handler - Producer handler ID (agent or task) that generates output.
+ * @param evaluator - Evaluator handler ID that judges quality and provides feedback.
+ * @param options - Optional iteration, parsing, signal, and threshold configuration.
+ * @returns A {@link ReflectPattern} configuration object.
  *
  * @example
  * ```typescript
  * const reviewPattern = reflect('writer', 'reviewer', { maxIterations: 2 });
  * ```
  */
-declare function reflect<T>(agent: string, evaluator: string, options?: {
+declare function reflect<T>(handler: string, evaluator: string, options?: {
     maxIterations?: number;
     parseEvaluation?: (output: unknown) => ReflectionEvaluation;
     buildRetryInput?: (input: string, feedback: string, iteration: number) => string;
@@ -1852,41 +2031,51 @@ declare function reflect<T>(agent: string, evaluator: string, options?: {
     threshold?: number | ((iteration: number) => number);
 }): ReflectPattern<T>;
 /**
- * Create a race pattern configuration.
+ * Create a race pattern that runs handlers concurrently and returns the first successful result.
  *
- * @param agents - Agent IDs to race concurrently
- * @param options - Optional `extract`, `timeout`, `minSuccess`, `signal`
+ * All handlers start simultaneously. The first to complete successfully wins;
+ * remaining handlers are aborted. Use `minSuccess` to wait for N results before picking.
+ *
+ * @param handlers - Handler IDs (agents or tasks) to race concurrently.
+ * @param options - Optional `extract`, `timeout`, `minSuccess`, and `signal` overrides.
+ * @returns A {@link RacePattern} configuration object.
  *
  * @example
  * ```typescript
  * const fastest = race(['fast-model', 'smart-model'], { timeout: 5000 });
  * ```
  */
-declare function race<T>(agents: string[], options?: {
+declare function race<T>(handlers: string[], options?: {
     extract?: (result: RunResult<unknown>) => T;
     timeout?: number;
     minSuccess?: number;
     signal?: AbortSignal;
 }): RacePattern<T>;
 /**
- * Create a goal execution pattern.
+ * Create a goal-driven execution pattern where agents are selected and run
+ * until a goal condition is satisfied.
  *
  * Declare what each agent produces and requires. The runtime automatically
  * infers the execution graph from dependency analysis and drives agents
- * to goal achievement.
+ * toward goal achievement, with optional satisfaction scoring and relaxation tiers.
+ *
+ * @param nodes - Goal node definitions keyed by ID, each declaring `produces`, `requires`, and a `handler`.
+ * @param when - Predicate that returns `true` when the goal is achieved.
+ * @param options - Optional `satisfaction`, `maxSteps`, `extract`, `timeout`, `selectionStrategy`, and `relaxation` config.
+ * @returns A {@link GoalPattern} configuration object.
  *
  * @example
  * ```typescript
  * const pipeline = goal(
  *   {
  *     researcher: {
- *       agent: "researcher",
+ *       handler: "researcher",
  *       produces: ["research.findings"],
  *       requires: ["research.topic"],
  *       extractOutput: (r) => ({ "research.findings": r.output }),
  *     },
  *     writer: {
- *       agent: "writer",
+ *       handler: "writer",
  *       produces: ["article.draft"],
  *       requires: ["research.findings"],
  *       extractOutput: (r) => ({ "article.draft": r.output }),
@@ -1910,23 +2099,40 @@ declare function goal<T = Record<string, unknown>>(nodes: Record<string, GoalNod
     checkpoint?: PatternCheckpointConfig;
 }): GoalPattern<T>;
 /**
- * Selection strategy: run all ready agents (default).
+ * Create a selection strategy that runs all ready agents concurrently.
+ *
+ * This is the default strategy for {@link goal} patterns.
+ *
+ * @returns An {@link AgentSelectionStrategy} that selects every ready agent.
  */
 declare function allReadyStrategy(): AgentSelectionStrategy;
 /**
- * Selection strategy: pick agents with the highest historical impact.
+ * Create a selection strategy that picks agents with the highest historical impact.
+ *
+ * Sorts ready agents by average satisfaction delta (descending) and selects the top N.
  *
- * Sorts by average satisfaction delta (descending) and picks the top N.
+ * @param opts - Optional `topN` to limit how many agents are selected (default: 3).
+ * @returns An {@link AgentSelectionStrategy} that prioritizes high-impact agents.
  */
 declare function highestImpactStrategy(opts?: {
     topN?: number;
 }): AgentSelectionStrategy;
 /**
- * Selection strategy: prefer agents that consume fewer tokens per satisfaction delta.
+ * Create a selection strategy that prefers agents with lower token cost per satisfaction delta.
+ *
+ * Agents without historical metrics are prioritized first (to gather data).
+ *
+ * @returns An {@link AgentSelectionStrategy} that optimizes for cost efficiency.
  */
 declare function costEfficientStrategy(): AgentSelectionStrategy;
 /**
- * Create an agent selection constraint.
+ * Create a constraint that routes to a specific agent when a condition is met.
+ *
+ * @param when - Predicate that triggers the constraint (may be async).
+ * @param agent - Agent ID or function returning an agent ID to route to.
+ * @param input - Input string or function returning the input for the selected agent.
+ * @param priority - Optional constraint priority (higher = evaluated first).
+ * @returns An {@link OrchestratorConstraint} that emits a `RUN_AGENT` requirement.
  *
  * @example
  * ```typescript
@@ -1934,14 +2140,19 @@ declare function costEfficientStrategy(): AgentSelectionStrategy;
  *   routeToExpert: selectAgent(
  *     (facts) => facts.complexity > 0.8,
  *     'expert',
- *     (facts) => facts.query
+ *     (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.
+ * Create a `RUN_AGENT` requirement object for use in constraint `require()` functions.
+ *
+ * @param agent - The agent ID to run.
+ * @param input - The input string for the agent.
+ * @param context - Optional additional context passed to the agent runner.
+ * @returns A `RUN_AGENT` {@link RunAgentRequirement} object.
  *
  * @example
  * ```typescript
@@ -1955,31 +2166,49 @@ declare function selectAgent(when: (facts: Record<string, unknown>) => boolean |
  */
 declare function runAgentRequirement(agent: string, input: string, context?: Record<string, unknown>): RunAgentRequirement;
 /**
- * Merge results by concatenating outputs.
+ * Merge run results by concatenating their outputs into a single string.
+ *
+ * @param results - Array of run results to concatenate.
+ * @param separator - String inserted between outputs (default: `"\n\n"`).
+ * @returns The concatenated output string.
  */
 declare function concatResults(results: RunResult<unknown>[], separator?: string): string;
 /**
- * Merge results by picking the best one based on a scoring function.
+ * Pick the highest-scoring result from an array using a scoring function.
+ *
+ * @param results - Array of run results to compare.
+ * @param score - Function that assigns a numeric score to each result (higher wins).
+ * @returns The {@link RunResult} with the highest score.
+ * @throws If the results array is empty.
  */
 declare function pickBestResult<T>(results: RunResult<T>[], score: (result: RunResult<T>) => number): RunResult<T>;
 /**
- * Merge results into an array of outputs.
+ * Extract the `output` value from each run result into an array.
+ *
+ * @param results - Array of run results to collect from.
+ * @returns An array of output values in the same order as the input results.
  */
 declare function collectOutputs<T>(results: RunResult<T>[]): T[];
 /**
- * Aggregate token counts from results.
+ * Sum the total token counts from an array of run results.
+ *
+ * @param results - Array of run results to aggregate.
+ * @returns The total number of tokens consumed across all 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.
+ * Compose multiple execution patterns into a pipeline where each pattern's
+ * output feeds as input to the next.
  *
+ * @remarks
  * 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
  *
+ * @param patterns - One or more execution patterns to chain together.
+ * @returns An async function that runs the pipeline on a given orchestrator.
+ *
  * @example
  * ```typescript
  * const workflow = composePatterns(
@@ -1992,10 +2221,11 @@ declare function aggregateTokens(results: RunResult<unknown>[]): number;
  */
 declare function composePatterns(...patterns: ExecutionPattern[]): (orchestrator: MultiAgentOrchestrator, input: string) => Promise<unknown>;
 /**
- * Create a capability-based agent selector.
+ * Find agents in a registry that match all required capabilities.
  *
- * Given a registry and required capabilities, returns the agent IDs
- * that match all required capabilities.
+ * @param registry - The agent registry to search.
+ * @param requiredCapabilities - Capabilities that each matching agent must have.
+ * @returns An array of agent IDs whose `capabilities` include every required capability.
  *
  * @example
  * ```typescript
@@ -2007,14 +2237,20 @@ declare function composePatterns(...patterns: ExecutionPattern[]): (orchestrator
  *
  * 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.
+ * Create a constraint that auto-routes to an agent based on required capabilities.
+ *
+ * When the condition fires, it finds agents matching the capabilities returned by
+ * `getCapabilities`, then emits a `RUN_AGENT` requirement for the best match.
+ *
+ * @param registry - The agent registry to search for matching capabilities.
+ * @param getCapabilities - Function that extracts required capabilities from facts.
+ * @param getInput - Function that extracts the input string from facts.
+ * @param options - Optional `priority` and custom `select` function.
+ * @returns An {@link OrchestratorConstraint} that routes to a capability-matched agent.
  *
  * @example
  * ```typescript
@@ -2039,11 +2275,14 @@ interface SpawnOnConditionOptions {
     context?: Record<string, unknown>;
 }
 /**
- * Create a constraint that auto-runs an agent when a condition is met.
+ * Create a constraint that auto-runs a single agent when a condition is met.
  *
- * The orchestrator's built-in RUN_AGENT resolver handles execution —
+ * The orchestrator's built-in `RUN_AGENT` resolver handles execution --
  * you only need to add this to your `constraints` config.
  *
+ * @param config - Condition, agent ID, input builder, and optional priority/context.
+ * @returns An {@link OrchestratorConstraint} that emits a `RUN_AGENT` requirement.
+ *
  * @example
  * ```typescript
  * const orchestrator = createMultiAgentOrchestrator({
@@ -2066,7 +2305,6 @@ declare function spawnOnCondition(config: {
     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 */
@@ -2074,13 +2312,15 @@ type DebateConfig<T = unknown> = Omit<DebatePattern<T>, "type">;
 /**
  * Create a debate pattern where agents compete and an evaluator picks the best.
  *
+ * @remarks
  * 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
+ * @param config - Debate configuration with `handlers`, `evaluator`, and optional settings.
+ * @returns A {@link DebatePattern} configuration object.
+ * @see {@link runDebate} for the imperative API
  *
  * @example
  * ```typescript
@@ -2092,7 +2332,7 @@ type DebateConfig<T = unknown> = Omit<DebatePattern<T>, "type">;
  *   },
  *   patterns: {
  *     debate: debate({
- *       agents: ['optimist', 'pessimist'],
+ *       handlers: ['optimist', 'pessimist'],
  *       evaluator: 'judge',
  *       maxRounds: 2,
  *     }),
@@ -2104,23 +2344,30 @@ type DebateConfig<T = unknown> = Omit<DebatePattern<T>, "type">;
  */
 declare function debate<T = unknown>(config: DebateConfig<T>): DebatePattern<T>;
 /**
- * Run a debate imperatively on an orchestrator (no pattern registration needed).
+ * Run a debate imperatively on an orchestrator without pattern registration.
+ *
  * 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
+ * @param orchestrator - The multi-agent orchestrator instance to run the debate on.
+ * @param config - Debate configuration with agents, evaluator, and optional settings.
+ * @param input - The initial input/prompt for the debate.
+ * @returns The winning agent's output, the winner ID, and all proposals from each round.
+ * @see {@link debate} for the declarative pattern API
  */
 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.
  *
+ * @remarks
  * 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.
  *
+ * @param derivationId - The ID of the cross-agent derivation to watch.
+ * @param condition - Predicate that receives the derivation value and returns `true` when the constraint should fire.
+ * @param action - Agent ID, input builder, and optional priority/context for the emitted requirement.
+ * @returns An {@link OrchestratorConstraint} that emits a `RUN_AGENT` requirement when the derivation condition is met.
+ *
  * @example
  * ```typescript
  * const orchestrator = createMultiAgentOrchestrator({
@@ -2159,11 +2406,15 @@ interface SpawnPoolConfig {
 /**
  * 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
+ * @remarks
+ * Unlike {@link 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
+ * @param when - Predicate that triggers the pool spawn.
+ * @param config - Pool configuration with agent ID, input builder, count, and optional priority/context.
+ * @returns An {@link OrchestratorConstraint} that emits `RUN_AGENT` requirements.
+ * @see {@link spawnOnCondition} for spawning a single agent
  *
  * @example
  * ```typescript
@@ -2185,7 +2436,8 @@ interface SpawnPoolConfig {
 declare function spawnPool(when: (facts: Record<string, unknown>) => boolean, config: SpawnPoolConfig): OrchestratorConstraint<Record<string, unknown>>;
 /** Serialized DAG node (functions stripped) */
 interface SerializedDagNode {
-    agent: string;
+    handler: string;
+    agent?: string;
     deps?: string[];
     timeout?: number;
     priority?: number;
@@ -2193,12 +2445,12 @@ interface SerializedDagNode {
 /** JSON-safe representation of any execution pattern (all functions stripped) */
 type SerializedPattern = {
     type: "parallel";
-    agents: string[];
+    handlers: string[];
     minSuccess?: number;
     timeout?: number;
 } | {
     type: "sequential";
-    agents: string[];
+    handlers: string[];
     continueOnError?: boolean;
 } | {
     type: "supervisor";
@@ -2213,7 +2465,7 @@ type SerializedPattern = {
     onNodeError?: "fail" | "skip-downstream" | "continue";
 } | {
     type: "reflect";
-    agent: string;
+    handler: string;
     evaluator: string;
     maxIterations?: number;
     onExhausted?: "accept-last" | "accept-best" | "throw";
@@ -2221,12 +2473,12 @@ type SerializedPattern = {
     threshold?: number;
 } | {
     type: "race";
-    agents: string[];
+    handlers: string[];
     timeout?: number;
     minSuccess?: number;
 } | {
     type: "debate";
-    agents: string[];
+    handlers: string[];
     evaluator: string;
     maxRounds?: number;
     timeout?: number;
@@ -2238,7 +2490,8 @@ type SerializedPattern = {
 };
 /** Serialized goal node (functions stripped) */
 interface SerializedGoalNode {
-    agent: string;
+    handler: string;
+    agent?: string;
     produces: string[];
     requires?: string[];
     allowRerun?: boolean;
@@ -2247,31 +2500,42 @@ interface SerializedGoalNode {
 /**
  * Serialize an execution pattern to a JSON-safe object.
  *
+ * @remarks
  * Strips all function callbacks and runtime objects (AbortSignal) while
- * preserving the topology — which agents, in what structure, with what
+ * 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.
+ * Function-form `threshold` on reflect patterns is not serializable and will be dropped.
  * Re-supply it via `overrides` when calling {@link patternFromJSON}.
  *
+ * @param pattern - The execution pattern to serialize.
+ * @returns A {@link SerializedPattern} safe for `JSON.stringify`.
+ *
  * @example
  * ```typescript
- * const p = parallel({ agents: ["a", "b"], merge: (r) => r });
+ * const p = parallel(['a', 'b'], (r) => r);
  * const json = patternToJSON(p);
- * // { type: "parallel", agents: ["a", "b"] }
+ * // { type: "parallel", handlers: ["a", "b"] }
  * localStorage.setItem("plan", JSON.stringify(json));
  * ```
  */
 declare function patternToJSON(pattern: ExecutionPattern<unknown>): SerializedPattern;
 /**
- * Restore an execution pattern from its serialized form.
+ * Restore an execution pattern from its serialized JSON form.
  *
+ * @remarks
  * Returns the data structure with all function fields set to `undefined`.
  * Supply callbacks via the optional `overrides` parameter to re-attach
- * runtime behavior.
+ * runtime behavior. Handles legacy field migrations (`agent` to `handler`,
+ * `agents` to `handlers`, `converge` to `goal`).
+ *
+ * @param json - The serialized pattern from {@link patternToJSON} or persisted storage.
+ * @param overrides - Optional partial pattern to re-attach function callbacks (e.g. `merge`, `extract`).
+ * @returns A fully typed {@link ExecutionPattern} ready for use with the imperative API.
+ * @throws If the pattern type is invalid or unknown.
  *
  * @example
  * ```typescript
@@ -2279,12 +2543,11 @@ declare function patternToJSON(pattern: ExecutionPattern<unknown>): SerializedPa
  * 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);
+ *   const result = await orchestrator.runParallel(pattern.handlers, 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 };
+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, patternToJSON 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, createHybridStrategy as aA, createKeyPointsSummarizer as aB, createLLMSummarizer as aC, createLengthStreamingGuardrail as aD, createMultiAgentOrchestrator as aE, createPatternStreamingGuardrail as aF, createSlidingWindowStrategy as aG, createStreamingRunner as aH, createTokenBasedStrategy as aI, createToxicityStreamingGuardrail as aJ, createTruncationSummarizer as aK, dag as aL, debate as aM, derivedConstraint as aN, diffCheckpoints as aO, extractJsonFromOutput as aP, filterStream as aQ, findAgentsByCapability as aR, forkFromCheckpoint as aS, getCheckpointProgress as aT, getPatternStep as aU, goal as aV, highestImpactStrategy as aW, mapStream as aX, mergeTaggedStreams as aY, parallel as aZ, patternFromJSON 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 TaskContext as ag, type TaskRegistration as ah, type TokenChunk as ai, type ToolEndChunk as aj, type ToolStartChunk as ak, adaptOutputGuardrail as al, aggregateTokens as am, allReadyStrategy as an, capabilityRoute as ao, collectOutputs as ap, collectTokens as aq, combineStreamingGuardrails as ar, composePatterns as as, concatResults as at, costEfficientStrategy as au, createAgentMemory as av, createAgentOrchestrator as aw, createDebugTimeline as ax, createDebugTimelinePlugin as ay, createHealthMonitor as az, type AgentMemoryConfig as b, pickBestResult as b0, race as b1, reflect as b2, runAgentRequirement as b3, runDebate as b4, selectAgent as b5, sequential as b6, spawnOnCondition as b7, spawnPool as b8, supervisor as b9, tapStream as ba, withReflection as bb, withStructuredOutput as bc, 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 };