@directive-run/ai 1.13.0 → 1.14.0

package/dist/multi-agent.d.ts

@@ -0,0 +1,1429 @@
+import { a as MultiAgentOrchestratorOptions, M as MultiAgentOrchestrator, P as ParallelPattern, y as RacePattern, L as ReflectionEvaluation, F as ReflectIterationRecord, I as ReflectPattern, W as SequentialPattern, a3 as SupervisorPattern, i as ExecutionPattern, D as DebatePattern, f as AgentRegistry, Q as RunAgentRequirement, g as DebateResult } from './orchestrator-types-DGBhL6mc.js';
+export { e as AgentRegistration, H as HandoffRequest, j as HandoffResult, s as MultiAgentRunCallOptions, t as MultiAgentState, z as RaceResult, C as RaceSuccessEntry, J as ReflectionConfig, K as ReflectionContext, R as ReflectionEvaluator, N as ReflectionExhaustedError, a4 as TaskContext, T as TaskRegistration, as as withReflection } from './orchestrator-types-DGBhL6mc.js';
+import { aG as PatternCheckpointState, ah as CheckpointDiff, h as CheckpointStore, aj as CheckpointProgress, J as AgentSelectionStrategy, j as DagNode, D as DagExecutionContext, k as DagPattern, F as GoalNode, K as RelaxationTier, at as GoalMetrics, P as PatternCheckpointConfig, E as GoalPattern, q as RunResult, s as OrchestratorConstraint, L as GoalResult } from './types-DJ09LjZX.js';
+export { z as BreakpointConfig, ab as BreakpointContext, B as BreakpointModifications, d as BreakpointRequest, ae as BreakpointState, af as BreakpointType, C as Checkpoint, ai as CheckpointLocalState, au as GoalStepMetrics, i as InMemoryCheckpointStore, aB as InMemoryCheckpointStoreOptions, aC as MAX_BREAKPOINT_HISTORY, $ as MultiAgentBreakpointType, aD as MultiAgentCheckpointLocalState, aO as RelaxationContext, aP as RelaxationRecord, aQ as RelaxationStrategy, aY as SingleAgentCheckpointLocalState, b2 as createBreakpointId, b3 as createCheckpointId, b4 as createInitialBreakpointState, b6 as matchBreakpoint, b7 as validateCheckpoint } from './types-DJ09LjZX.js';
+import '@directive-run/core';
+import '@directive-run/core/plugins';
+import './debug-timeline-L13P-U2I.js';
+import './health-monitor-qL9RNMH3.js';
+
+/**
+ * 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;
+}
+/**
+ * Get the current step/round/iteration count from a pattern checkpoint state.
+ *
+ * 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.
+ *
+ * @param state - The pattern checkpoint state to inspect.
+ * @returns The current progress count for the pattern.
+ */
+declare function getPatternStep(state: PatternCheckpointState): number;
+/**
+ * Compute progress metrics from a pattern checkpoint state.
+ *
+ * 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.
+ *
+ * @param state - The pattern checkpoint state to analyze.
+ * @returns A {@link CheckpointProgress} object with completion metrics.
+ */
+declare function getCheckpointProgress(state: PatternCheckpointState): CheckpointProgress;
+/**
+ * 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
+ * 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>;
+
+/**
+ * Create a parallel execution pattern that runs handlers concurrently and merges results.
+ *
+ * @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'),
+ * );
+ * ```
+ */
+declare function parallel<T>(handlers: string[], merge: (results: RunResult<unknown>[]) => T | Promise<T>, options?: {
+    minSuccess?: number;
+    timeout?: number;
+}): ParallelPattern<T>;
+/**
+ * Create a sequential execution pattern that pipes output from one handler to the next.
+ *
+ * @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}` },
+ * );
+ * ```
+ */
+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 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` overrides.
+ * @returns A {@link SupervisorPattern} configuration object.
+ *
+ * @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 directed acyclic graph (DAG) execution pattern.
+ *
+ * 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: { handler: 'fetcher' },
+ *     analyze: { handler: 'analyzer', deps: ['fetch'] },
+ *     summarize: { handler: '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 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 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>(handler: 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 that runs handlers concurrently and returns the first successful result.
+ *
+ * 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>(handlers: string[], options?: {
+    extract?: (result: RunResult<unknown>) => T;
+    timeout?: number;
+    minSuccess?: number;
+    signal?: AbortSignal;
+}): RacePattern<T>;
+/**
+ * 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
+ * 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: {
+ *       handler: "researcher",
+ *       produces: ["research.findings"],
+ *       requires: ["research.topic"],
+ *       extractOutput: (r) => ({ "research.findings": r.output }),
+ *     },
+ *     writer: {
+ *       handler: "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>;
+/**
+ * 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;
+/**
+ * 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.
+ *
+ * @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;
+/**
+ * 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;
+
+/** Serialized DAG node (functions stripped) */
+interface SerializedDagNode {
+    handler: string;
+    agent?: string;
+    deps?: string[];
+    timeout?: number;
+    priority?: number;
+}
+/** JSON-safe representation of any execution pattern (all functions stripped) */
+type SerializedPattern = {
+    type: "parallel";
+    handlers: string[];
+    minSuccess?: number;
+    timeout?: number;
+} | {
+    type: "sequential";
+    handlers: 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";
+    handler: string;
+    evaluator: string;
+    maxIterations?: number;
+    onExhausted?: "accept-last" | "accept-best" | "throw";
+    timeout?: number;
+    threshold?: number;
+} | {
+    type: "race";
+    handlers: string[];
+    timeout?: number;
+    minSuccess?: number;
+} | {
+    type: "debate";
+    handlers: string[];
+    evaluator: string;
+    maxRounds?: number;
+    timeout?: number;
+} | {
+    type: "goal";
+    nodes: Record<string, SerializedGoalNode>;
+    maxSteps?: number;
+    timeout?: number;
+};
+/** Serialized goal node (functions stripped) */
+interface SerializedGoalNode {
+    handler: string;
+    agent?: string;
+    produces: string[];
+    requires?: string[];
+    allowRerun?: boolean;
+    priority?: number;
+}
+/**
+ * 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
+ * numeric/string/boolean options.
+ *
+ * Use this for visual editors, LLM-generated plans, persistence, or
+ * debugging. Restore with {@link patternFromJSON}.
+ *
+ * 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(['a', 'b'], (r) => r);
+ * const json = patternToJSON(p);
+ * // { 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 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.
+ *
+ * @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
+ * const json = JSON.parse(localStorage.getItem("plan")!);
+ * const pattern = patternFromJSON<string[]>(json, {
+ *   merge: (results) => results.map(r => r.output as string),
+ * });
+ * if (pattern.type === "parallel") {
+ *   const result = await orchestrator.runParallel(pattern.handlers, input, pattern.merge);
+ * }
+ * ```
+ */
+declare function patternFromJSON<T = unknown>(json: SerializedPattern, overrides?: Partial<ExecutionPattern<T>>): ExecutionPattern<T>;
+
+/**
+ * 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
+ * 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 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
+ * 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 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;
+/**
+ * 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>;
+/**
+ * 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[];
+/**
+ * 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 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(
+ *   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>;
+/**
+ * Find agents in a registry 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
+ * 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']
+ * ```
+ */
+declare function findAgentsByCapability(registry: AgentRegistry, requiredCapabilities: string[]): string[];
+/**
+ * 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
+ * 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 a single 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.
+ *
+ * @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({
+ *   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>;
+    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.
+ *
+ * @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 `handlers`, `evaluator`, and optional settings.
+ * @returns A {@link DebatePattern} configuration object.
+ * @see {@link runDebate} for the imperative API
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   agents: {
+ *     optimist: { agent: optimistAgent },
+ *     pessimist: { agent: pessimistAgent },
+ *     judge: { agent: judgeAgent },
+ *   },
+ *   patterns: {
+ *     debate: debate({
+ *       handlers: ['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 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 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({
+ *   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.
+ *
+ * @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.
+ *
+ * @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
+ * 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>>;
+
+/**
+ * Multi-Agent Orchestration Patterns
+ *
+ * Provides patterns for coordinating multiple AI agents:
+ * - Parallel execution with result merging
+ * - Sequential pipelines
+ * - Supervisor patterns with worker delegation
+ * - Constraint-driven agent selection
+ *
+ * @example
+ * ```typescript
+ * import { createMultiAgentOrchestrator } from '@directive-run/ai';
+ *
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   agents: {
+ *     researcher: { agent: researchAgent, maxConcurrent: 3 },
+ *     writer: { agent: writerAgent, maxConcurrent: 1 },
+ *     reviewer: { agent: reviewerAgent, maxConcurrent: 1 },
+ *   },
+ *   patterns: {
+ *     parallelResearch: {
+ *       type: 'parallel',
+ *       handlers: ['researcher', 'researcher', 'researcher'],
+ *       merge: (results) => combineResearch(results),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * 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 {@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
+ * const orchestrator = createMultiAgentOrchestrator({
+ *   runner,
+ *   agents: {
+ *     researcher: { agent: researchAgent, maxConcurrent: 3 },
+ *     writer: { agent: writerAgent },
+ *     reviewer: { agent: reviewerAgent },
+ *   },
+ *   guardrails: {
+ *     input: [createEnhancedPIIGuardrail()],
+ *     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 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;
+
+type MermaidDirection = "LR" | "TD" | "TB" | "RL" | "BT";
+interface MermaidNodeShapes {
+    /** Shape for agent nodes. @default "square" */
+    agent?: "square" | "round" | "stadium" | "hexagon";
+    /** Shape for task nodes. @default "hexagon" */
+    task?: "square" | "round" | "stadium" | "hexagon";
+    /** Shape for virtual nodes (Input, Output, Merge). @default "circle" */
+    virtual?: "circle" | "square" | "round" | "stadium";
+}
+interface MermaidOptions {
+    /** Graph flow direction. @default "LR" */
+    direction?: MermaidDirection;
+    /** Emits %%{init}%% preamble when set. */
+    theme?: "default" | "dark" | "forest" | "neutral";
+    /** Node shape overrides. */
+    shapes?: MermaidNodeShapes;
+    /** Set of task IDs — used to render task nodes with distinct shapes. */
+    taskIds?: ReadonlySet<string>;
+}
+/**
+ * Convert an execution pattern to a Mermaid diagram string.
+ *
+ * Accepts both runtime `ExecutionPattern` (with function callbacks) and
+ * pre-serialized `SerializedPattern`. Normalizes internally via `patternToJSON()`
+ * when it detects function-valued fields.
+ *
+ * @example
+ * ```typescript
+ * const p = dag({ fetch: { handler: "fetcher" }, report: { handler: "reporter", deps: ["fetch"] } });
+ * console.log(patternToMermaid(p, { direction: "TD" }));
+ * // graph TD
+ * //   fetch[fetcher]
+ * //   fetch[fetcher] --> report[reporter]
+ * ```
+ *
+ * @throws If pattern type is not one of the 8 known types.
+ */
+declare function patternToMermaid(pattern: ExecutionPattern<unknown> | SerializedPattern, options?: MermaidOptions): string;
+
+/**
+ * Agent-to-Agent Communication Protocol
+ *
+ * Provides structured communication channels between agents for coordination,
+ * delegation, and knowledge sharing without central orchestration.
+ *
+ * @example
+ * ```typescript
+ * import { createAgentNetwork, createMessageBus } from '@directive-run/ai';
+ *
+ * const messageBus = createMessageBus();
+ *
+ * const network = createAgentNetwork({
+ *   bus: messageBus,
+ *   agents: {
+ *     researcher: { capabilities: ['search', 'analyze'] },
+ *     writer: { capabilities: ['draft', 'edit'] },
+ *     reviewer: { capabilities: ['review', 'approve'] },
+ *   },
+ * });
+ *
+ * // Agents can send messages to each other
+ * await network.send('researcher', 'writer', {
+ *   type: 'DELEGATION',
+ *   task: 'Draft an article based on this research',
+ *   context: { findings: [...] },
+ * });
+ * ```
+ */
+/** Base message structure */
+interface AgentMessage {
+    id: string;
+    type: AgentMessageType;
+    from: string;
+    to: string | string[] | "*";
+    timestamp: number;
+    correlationId?: string;
+    replyTo?: string;
+    priority?: "low" | "normal" | "high" | "urgent";
+    ttlMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/** Message types for agent communication */
+type AgentMessageType = "REQUEST" | "RESPONSE" | "DELEGATION" | "DELEGATION_RESULT" | "QUERY" | "INFORM" | "SUBSCRIBE" | "UNSUBSCRIBE" | "UPDATE" | "ACK" | "NACK" | "PING" | "PONG" | "CUSTOM";
+/** Request message */
+interface RequestMessage extends AgentMessage {
+    type: "REQUEST";
+    action: string;
+    payload: Record<string, unknown>;
+    timeout?: number;
+}
+/** Response message */
+interface ResponseMessage extends AgentMessage {
+    type: "RESPONSE";
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+/** Delegation message */
+interface DelegationMessage extends AgentMessage {
+    type: "DELEGATION";
+    task: string;
+    context: Record<string, unknown>;
+    constraints?: {
+        deadline?: number;
+        maxCost?: number;
+        requiredCapabilities?: string[];
+    };
+}
+/** Delegation result message */
+interface DelegationResultMessage extends AgentMessage {
+    type: "DELEGATION_RESULT";
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    metrics?: {
+        durationMs: number;
+        tokensUsed?: number;
+        cost?: number;
+    };
+}
+/** Query message */
+interface QueryMessage extends AgentMessage {
+    type: "QUERY";
+    question: string;
+    context?: Record<string, unknown>;
+}
+/** Inform message */
+interface InformMessage extends AgentMessage {
+    type: "INFORM";
+    topic: string;
+    content: unknown;
+}
+/** Subscribe message */
+interface SubscribeMessage extends AgentMessage {
+    type: "SUBSCRIBE";
+    topics: string[];
+}
+/** Update message */
+interface UpdateMessage extends AgentMessage {
+    type: "UPDATE";
+    topic: string;
+    content: unknown;
+}
+/** Union of all message types */
+type TypedAgentMessage = RequestMessage | ResponseMessage | DelegationMessage | DelegationResultMessage | QueryMessage | InformMessage | SubscribeMessage | UpdateMessage | (AgentMessage & {
+    type: "UNSUBSCRIBE" | "ACK" | "NACK" | "PING" | "PONG" | "CUSTOM";
+});
+/** Message handler function */
+type MessageHandler = (message: TypedAgentMessage) => void | Promise<void>;
+/** Subscription to messages */
+interface Subscription {
+    id: string;
+    agentId: string;
+    handler: MessageHandler;
+    filter?: MessageFilter;
+    unsubscribe: () => void;
+}
+/** Message filter criteria */
+interface MessageFilter {
+    types?: AgentMessageType[];
+    from?: string | string[];
+    topics?: string[];
+    priority?: ("low" | "normal" | "high" | "urgent")[];
+    custom?: (message: TypedAgentMessage) => boolean;
+}
+/** Message bus configuration */
+interface MessageBusConfig {
+    /** Maximum messages to retain in history */
+    maxHistory?: number;
+    /** Default TTL for messages */
+    defaultTtlMs?: number;
+    /** Maximum pending messages per offline agent (prevents unbounded queue growth) */
+    maxPendingPerAgent?: number;
+    /** Enable message persistence */
+    persistence?: MessagePersistence;
+    /** Callback when message is delivered */
+    onDelivery?: (message: TypedAgentMessage, recipients: string[]) => void;
+    /** Callback when message delivery fails */
+    onDeliveryError?: (message: TypedAgentMessage, error: Error) => void;
+}
+/** Message persistence interface */
+interface MessagePersistence {
+    save(message: TypedAgentMessage): Promise<void>;
+    load(agentId: string, since?: number): Promise<TypedAgentMessage[]>;
+    delete(messageId: string): Promise<void>;
+    clear(agentId?: string): Promise<void>;
+}
+/** Message bus instance */
+interface MessageBus {
+    /** Publish a message */
+    publish(message: Omit<TypedAgentMessage, "id" | "timestamp">): string;
+    /** Subscribe to messages */
+    subscribe(agentId: string, handler: MessageHandler, filter?: MessageFilter): Subscription;
+    /** Get message history */
+    getHistory(filter?: MessageFilter, limit?: number): TypedAgentMessage[];
+    /** Get a specific message by ID */
+    getMessage(id: string): TypedAgentMessage | undefined;
+    /** Get pending messages for an agent */
+    getPending(agentId: string): TypedAgentMessage[];
+    /** Clear all messages and data */
+    clear(): void;
+    /** Destroy the message bus, clearing all data and subscriptions */
+    destroy(): void;
+}
+/**
+ * Create a message bus for agent communication.
+ *
+ * @example
+ * ```typescript
+ * const bus = createMessageBus({ maxHistory: 1000 });
+ *
+ * // Subscribe to messages
+ * bus.subscribe('writer', (msg) => {
+ *   console.log(`Writer received: ${msg.type}`);
+ * });
+ *
+ * // Publish a message
+ * bus.publish({
+ *   type: 'DELEGATION',
+ *   from: 'researcher',
+ *   to: 'writer',
+ *   task: 'Write summary',
+ *   context: { data: '...' },
+ * });
+ * ```
+ */
+/**
+ * Note: `publish()` is fire-and-forget -- it returns the message ID synchronously
+ * before delivery completes. Use `onDelivery` / `onDeliveryError` callbacks in
+ * config to track delivery status if needed.
+ */
+declare function createMessageBus(config?: MessageBusConfig): MessageBus;
+/** Agent registration info */
+interface AgentInfo {
+    id: string;
+    capabilities: string[];
+    status: "online" | "offline" | "busy";
+    lastSeen: number;
+    metadata?: Record<string, unknown>;
+}
+/** Agent network configuration */
+interface AgentNetworkConfig {
+    /** Message bus to use */
+    bus: MessageBus;
+    /** Registered agents */
+    agents?: Record<string, Omit<AgentInfo, "id" | "lastSeen" | "status">>;
+    /** Timeout for request-response patterns */
+    defaultTimeout?: number;
+    /** Callback when agent comes online */
+    onAgentOnline?: (agentId: string) => void;
+    /** Callback when agent goes offline */
+    onAgentOffline?: (agentId: string) => void;
+}
+/** Agent network instance */
+interface AgentNetwork {
+    /** Register an agent */
+    register(id: string, info: Omit<AgentInfo, "id" | "lastSeen" | "status">): void;
+    /** Unregister an agent */
+    unregister(id: string): void;
+    /** Get agent info */
+    getAgent(id: string): AgentInfo | undefined;
+    /** Get all agents */
+    getAgents(): AgentInfo[];
+    /** Find agents by capability */
+    findByCapability(capability: string): AgentInfo[];
+    /** Send a message */
+    send(from: string, to: string | string[], message: Partial<TypedAgentMessage>): string;
+    /** Send a request and wait for response */
+    request(from: string, to: string, action: string, payload: Record<string, unknown>, timeout?: number): Promise<ResponseMessage>;
+    /** Delegate a task */
+    delegate(from: string, to: string, task: string, context: Record<string, unknown>): Promise<DelegationResultMessage>;
+    /** Query an agent */
+    query(from: string, to: string, question: string, context?: Record<string, unknown>): Promise<ResponseMessage>;
+    /** Broadcast to all agents */
+    broadcast(from: string, message: Partial<TypedAgentMessage>): string;
+    /** Subscribe an agent to messages */
+    listen(agentId: string, handler: MessageHandler, filter?: MessageFilter): Subscription;
+    /** Get the message bus */
+    getBus(): MessageBus;
+    /** Destroy the network, clearing pending waiters and timers */
+    destroy(): void;
+}
+/**
+ * Create an agent network for coordinated communication.
+ *
+ * @example
+ * ```typescript
+ * const network = createAgentNetwork({
+ *   bus: createMessageBus(),
+ *   agents: {
+ *     researcher: { capabilities: ['search', 'summarize'] },
+ *     writer: { capabilities: ['draft', 'edit'] },
+ *     reviewer: { capabilities: ['review', 'approve'] },
+ *   },
+ * });
+ *
+ * // Delegate a task
+ * const result = await network.delegate(
+ *   'researcher',
+ *   'writer',
+ *   'Write an article about AI safety',
+ *   { research: findingsData }
+ * );
+ *
+ * // Query for information
+ * const answer = await network.query(
+ *   'writer',
+ *   'reviewer',
+ *   'Is this paragraph technically accurate?',
+ *   { text: '...' }
+ * );
+ * ```
+ */
+declare function createAgentNetwork(config: AgentNetworkConfig): AgentNetwork;
+/**
+ * Create a request-response helper for handling incoming requests.
+ *
+ * @example
+ * ```typescript
+ * const responder = createResponder(network, 'writer');
+ *
+ * responder.onRequest('draft', async (payload) => {
+ *   const draft = await generateDraft(payload.topic);
+ *   return { success: true, result: draft };
+ * });
+ * ```
+ */
+declare function createResponder(network: AgentNetwork, agentId: string): {
+    onRequest(action: string, handler: (payload: Record<string, unknown>) => Promise<{
+        success: boolean;
+        result?: unknown;
+        error?: string;
+    }>): void;
+    /** Remove a request handler */
+    offRequest(action: string): void;
+    /** Destroy this responder, unsubscribing from network */
+    destroy(): void;
+};
+/**
+ * Create a task delegator for handling incoming delegations.
+ *
+ * @example
+ * ```typescript
+ * const delegator = createDelegator(network, 'writer');
+ *
+ * delegator.onDelegation(async (task, context) => {
+ *   const result = await executeTask(task, context);
+ *   return {
+ *     success: true,
+ *     result,
+ *     metrics: { durationMs: 1500, tokensUsed: 500 },
+ *   };
+ * });
+ * ```
+ */
+declare function createDelegator(network: AgentNetwork, agentId: string): {
+    onDelegation(handler: (task: string, context: Record<string, unknown>) => Promise<{
+        success: boolean;
+        result?: unknown;
+        error?: string;
+        metrics?: {
+            durationMs: number;
+            tokensUsed?: number;
+            cost?: number;
+        };
+    }>): void;
+    /** Remove the delegation handler */
+    offDelegation(): void;
+    /** Destroy this delegator, unsubscribing from network */
+    destroy(): void;
+};
+/**
+ * Create a pub/sub helper for topic-based communication.
+ *
+ * @example
+ * ```typescript
+ * const pubsub = createPubSub(network, 'analyst');
+ *
+ * // Subscribe to topics
+ * pubsub.subscribe(['market-updates', 'alerts'], (topic, content) => {
+ *   console.log(`Received ${topic}:`, content);
+ * });
+ *
+ * // Publish to topics
+ * pubsub.publish('market-updates', { price: 100, change: 5 });
+ * ```
+ */
+declare function createPubSub(network: AgentNetwork, agentId: string): {
+    subscribe(topics: string[], handler: (topic: string, content: unknown) => void): () => void;
+    publish(topic: string, content: unknown): void;
+    /** Destroy this pub/sub, unsubscribing from network and clearing handlers */
+    destroy(): void;
+};
+
+/**
+ * Standalone utilities for goal planning and validation.
+ *
+ * These functions work with the same `produces` / `requires` agent
+ * declarations used by the goal pattern, without requiring an
+ * orchestrator instance.
+ *
+ * @example
+ * ```typescript
+ * import { validateGoal, planGoal, getDependencyGraph } from '@directive-run/ai';
+ *
+ * const agents = {
+ *   fetcher: { produces: ['data'], requires: [] },
+ *   analyzer: { produces: ['analysis'], requires: ['data'] },
+ *   reporter: { produces: ['report'], requires: ['analysis'] },
+ * };
+ *
+ * // Validate — cycle detection, missing deps, warnings
+ * const validation = validateGoal(agents);
+ *
+ * // Plan — dry-run without executing agents
+ * const plan = planGoal(agents, ['query']);
+ *
+ * // Graph — topological order, roots, leaves, edges
+ * const graph = getDependencyGraph(agents);
+ * ```
+ *
+ * @module
+ */
+
+/** Minimal agent declaration for goal utilities (subset of GoalNode) */
+interface GoalAgentDeclaration {
+    /** Fact keys this agent writes as output */
+    produces: string[];
+    /** Fact keys this agent reads as input */
+    requires?: string[];
+}
+/** Edge in the inferred dependency graph */
+interface GoalDependencyEdge {
+    from: string;
+    to: string;
+    /** Fact key that creates this dependency */
+    factKey: string;
+}
+/** Inferred dependency graph from produces/requires analysis */
+interface GoalDependencyGraph {
+    /** Agent IDs in topological order (roots first) */
+    order: string[];
+    /** Edges between agents */
+    edges: GoalDependencyEdge[];
+    /** Root agents (no unfulfilled requires from other agents) */
+    roots: string[];
+    /** Leaf agents (nothing depends on their produces) */
+    leaves: string[];
+    /** Map of fact key to agent ID that produces it */
+    producers: Map<string, string>;
+}
+/** Validation result */
+interface GoalValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/** A single step in an execution plan */
+interface GoalPlanStep {
+    /** Step number (1-based) */
+    step: number;
+    /** Agent IDs that would run in this step (parallel) */
+    agents: string[];
+    /** Fact keys available at the start of this step */
+    availableFacts: string[];
+    /** Fact keys produced after this step completes */
+    producedFacts: string[];
+}
+/** Result of a planGoal() dry-run */
+interface GoalExecutionPlan {
+    /** Ordered steps showing which agents run when */
+    steps: GoalPlanStep[];
+    /** Agents that can never run (requires never satisfiable) */
+    unreachableAgents: string[];
+    /** Required fact keys that no agent produces (must be in initial facts) */
+    externalDeps: string[];
+    /** Whether the plan can potentially reach all agents */
+    feasible: boolean;
+}
+/**
+ * Get the dependency graph for a set of agent declarations.
+ *
+ * Uses Kahn's algorithm (topological sort) to compute execution order
+ * and detect circular dependencies.
+ *
+ * @throws If agents form a circular dependency or a fact key has multiple producers.
+ *
+ * @example
+ * ```typescript
+ * const graph = getDependencyGraph({
+ *   fetcher: { produces: ['data'], requires: [] },
+ *   analyzer: { produces: ['analysis'], requires: ['data'] },
+ * });
+ *
+ * console.log(graph.order);  // ['fetcher', 'analyzer']
+ * console.log(graph.roots);  // ['fetcher']
+ * console.log(graph.leaves); // ['analyzer']
+ * ```
+ */
+declare function getDependencyGraph(agents: Record<string, GoalAgentDeclaration>): GoalDependencyGraph;
+/**
+ * Validate a set of agent declarations for goal execution.
+ *
+ * Checks for:
+ * - Circular dependencies
+ * - Duplicate producers (same fact key produced by multiple agents)
+ * - Agents with no `produces` (will never contribute)
+ * - Required fact keys that no agent produces (must be in initial facts)
+ *
+ * @example
+ * ```typescript
+ * const result = validateGoal({
+ *   fetcher: { produces: ['data'] },
+ *   analyzer: { produces: ['analysis'], requires: ['data'] },
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+declare function validateGoal(agents: Record<string, GoalAgentDeclaration>): GoalValidationResult;
+/**
+ * Dry-run goal execution to preview the plan without running agents.
+ *
+ * Shows which agents would run in each step, which facts would be produced,
+ * and whether any agents are unreachable.
+ *
+ * @param agents - Agent declarations with produces/requires
+ * @param initialFactKeys - Fact keys available at the start (not values, just keys)
+ * @param maxSteps - Maximum steps to simulate (default: 50)
+ *
+ * @example
+ * ```typescript
+ * const plan = planGoal(
+ *   {
+ *     fetcher: { produces: ['data'] },
+ *     analyzer: { produces: ['analysis'], requires: ['data'] },
+ *     reporter: { produces: ['report'], requires: ['analysis'] },
+ *   },
+ *   ['query'],
+ * );
+ *
+ * console.log(plan.feasible);  // true
+ * console.log(plan.steps);     // 3 steps: fetcher → analyzer → reporter
+ * ```
+ */
+declare function planGoal(agents: Record<string, GoalAgentDeclaration>, initialFactKeys?: string[], maxSteps?: number): GoalExecutionPlan;
+/** A single line in a goal execution explanation */
+interface GoalExplanationStep {
+    step: number;
+    agents: string[];
+    factsProduced: string[];
+    satisfaction: number;
+    satisfactionDelta: number;
+    durationMs: number;
+    tokensConsumed: number;
+    /** Human-readable description of what happened */
+    description: string;
+}
+/** Structured explanation of a goal execution */
+interface GoalExplanation {
+    /** Whether the goal was achieved */
+    achieved: boolean;
+    /** Human-readable summary */
+    summary: string;
+    /** Per-step explanations */
+    steps: GoalExplanationStep[];
+    /** Relaxation events with descriptions */
+    relaxations: Array<{
+        step: number;
+        label: string;
+        strategy: string;
+        description: string;
+    }>;
+    /** Total tokens consumed */
+    totalTokens: number;
+    /** Total duration (ms) */
+    durationMs: number;
+}
+/**
+ * Generate a human-readable explanation of a goal execution result.
+ *
+ * Takes a `GoalResult` and returns a structured explanation of why each
+ * agent ran, how satisfaction progressed, and what relaxations were applied.
+ *
+ * @example
+ * ```typescript
+ * const result = await orchestrator.runGoal(nodes, input, when, options);
+ * const explanation = explainGoal(result);
+ *
+ * console.log(explanation.summary);
+ * // "Goal achieved in 3 steps (1,247 tokens, 892ms). Satisfaction: 0 → 1."
+ *
+ * for (const step of explanation.steps) {
+ *   console.log(step.description);
+ *   // "Step 1: Ran fetcher. Produced: data. Satisfaction: 0 → 0.3 (+0.3)."
+ * }
+ * ```
+ */
+declare function explainGoal<T = unknown>(result: GoalResult<T>): GoalExplanation;
+
+export { type AgentInfo, type AgentMessage, type AgentMessageType, type AgentNetwork, type AgentNetworkConfig, AgentRegistry, AgentSelectionStrategy, CheckpointStore, type DebateConfig, DebatePattern, DebateResult, type DelegationMessage, type DelegationResultMessage, ExecutionPattern, type GoalAgentDeclaration, type GoalDependencyEdge, type GoalDependencyGraph, type GoalExecutionPlan, type GoalExplanation, type GoalExplanationStep, GoalMetrics, GoalNode, GoalPattern, type GoalPlanStep, GoalResult, type GoalValidationResult, type InformMessage, type MermaidDirection, type MermaidNodeShapes, type MermaidOptions, type MessageBus, type MessageBusConfig, type MessageFilter, type MessageHandler, MultiAgentOrchestrator, MultiAgentOrchestratorOptions, ParallelPattern, type QueryMessage, RacePattern, ReflectIterationRecord, ReflectPattern, ReflectionEvaluation, RelaxationTier, type RequestMessage, type ResponseMessage, RunAgentRequirement, Semaphore, SequentialPattern, type SerializedDagNode, type SerializedGoalNode, type SerializedPattern, type SpawnOnConditionOptions, type SpawnPoolConfig, type Subscription, SupervisorPattern, type TypedAgentMessage, type UpdateMessage, aggregateTokens, allReadyStrategy, capabilityRoute, collectOutputs, composePatterns, concatResults, costEfficientStrategy, createAgentNetwork, createDelegator, createMessageBus, createMultiAgentOrchestrator, createPubSub, createResponder, dag, debate, derivedConstraint, diffCheckpoints, explainGoal, findAgentsByCapability, forkFromCheckpoint, getCheckpointProgress, getDependencyGraph, getPatternStep, goal, highestImpactStrategy, parallel, patternFromJSON, patternToJSON, patternToMermaid, pickBestResult, planGoal, race, reflect, runAgentRequirement, runDebate, selectAgent, sequential, spawnOnCondition, spawnPool, supervisor, validateGoal };