@directive-run/ai 0.2.0 → 0.4.0

package/dist/types-D5veI9su.d.ts

@@ -0,0 +1,1456 @@
+import { Requirement } from '@directive-run/core';
+
+/**
+ * Persistent Checkpointing — Serialize/restore full orchestrator state.
+ *
+ * Enables long-running workflows, process restarts, and fork-and-replay by
+ * capturing a complete snapshot of orchestrator state at rest.
+ *
+ * @module
+ */
+/** Checkpoint local state for single-agent orchestrators */
+interface SingleAgentCheckpointLocalState {
+    type: "single";
+}
+/** Checkpoint local state for multi-agent orchestrators */
+interface MultiAgentCheckpointLocalState {
+    type: "multi";
+    globalTokenCount: number;
+    globalStatus: "idle" | "paused";
+    agentStates: Record<string, {
+        status: "idle" | "running" | "completed" | "error";
+        lastInput?: string;
+        lastOutput?: unknown;
+        lastError?: string;
+        runCount: number;
+        totalTokens: number;
+    }>;
+    handoffCounter: number;
+    pendingHandoffs: unknown[];
+    handoffResults: unknown[];
+    roundRobinCounters: Record<string, number> | null;
+    /** Serialized task states (task run functions are closures, not serializable) */
+    taskStates?: Record<string, {
+        lastOutput?: string;
+        lastError?: string;
+    }>;
+}
+/** Union of local state types */
+type CheckpointLocalState = SingleAgentCheckpointLocalState | MultiAgentCheckpointLocalState;
+/** Full checkpoint data */
+interface Checkpoint {
+    version: 1;
+    id: string;
+    createdAt: string;
+    label?: string;
+    systemExport: string;
+    timelineExport: string | null;
+    localState: CheckpointLocalState;
+    memoryExport: unknown | null;
+    orchestratorType: "single" | "multi";
+    /** Associated time-travel snapshot ID */
+    snapshotId?: number;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Checkpoint store interface */
+interface CheckpointStore {
+    save(checkpoint: Checkpoint): Promise<string>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    list(): Promise<Array<{
+        id: string;
+        label?: string;
+        createdAt: string;
+    }>>;
+    delete(checkpointId: string): Promise<boolean>;
+    clear(): Promise<void>;
+    /** Prune old checkpoints based on retention policy. Returns number pruned. */
+    prune(): Promise<number>;
+}
+/** Create a unique checkpoint ID */
+declare function createCheckpointId(): string;
+/** Validate that an unknown value is a valid Checkpoint */
+declare function validateCheckpoint(data: unknown): data is Checkpoint;
+/** Options for InMemoryCheckpointStore */
+interface InMemoryCheckpointStoreOptions {
+    /** Maximum checkpoints to retain before FIFO eviction. @default 100 */
+    maxCheckpoints?: number;
+    /** Time-based retention: prune checkpoints older than this (ms). @default Infinity */
+    retentionMs?: number;
+    /** When true, labeled checkpoints are exempt from auto-prune. @default false */
+    preserveLabeled?: boolean;
+}
+/**
+ * In-memory checkpoint store with FIFO eviction and time-based retention.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryCheckpointStore({
+ *   maxCheckpoints: 50,
+ *   retentionMs: 3600000, // 1 hour
+ *   preserveLabeled: true,
+ * });
+ *
+ * const id = await store.save(checkpoint);
+ * const pruned = await store.prune();
+ * ```
+ */
+declare class InMemoryCheckpointStore implements CheckpointStore {
+    private readonly store;
+    private readonly order;
+    private readonly maxCheckpoints;
+    private readonly retentionMs;
+    private readonly preserveLabeled;
+    constructor(options?: InMemoryCheckpointStoreOptions);
+    save(checkpoint: Checkpoint): Promise<string>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    list(): Promise<Array<{
+        id: string;
+        label?: string;
+        createdAt: string;
+    }>>;
+    delete(checkpointId: string): Promise<boolean>;
+    clear(): Promise<void>;
+    prune(): Promise<number>;
+    /** Evict the oldest non-labeled checkpoint. Returns true if one was evicted. */
+    private evictOldest;
+}
+
+/**
+ * Human-in-the-Loop Breakpoints — Pause/inspect/modify/resume at arbitrary execution points.
+ *
+ * Separate from approvals (which are safety gates for tool calls). Breakpoints are
+ * general-purpose pause points for debugging, inspection, and input modification.
+ *
+ * Zero overhead when breakpoints array is empty — guard at each insertion point.
+ *
+ * @module
+ */
+/** Breakpoint types for single-agent orchestrator */
+type BreakpointType = "pre_input_guardrails" | "pre_agent_run" | "pre_output_guardrails" | "post_run";
+/** Extended breakpoint types for multi-agent orchestrator */
+type MultiAgentBreakpointType = BreakpointType | "pre_handoff" | "pre_pattern_step";
+/** Breakpoint configuration */
+interface BreakpointConfig<T extends string = BreakpointType> {
+    type: T;
+    when?: (context: BreakpointContext) => boolean;
+    label?: string;
+}
+/** Context available when a breakpoint fires */
+interface BreakpointContext {
+    agentId: string;
+    agentName: string;
+    input: string;
+    state: Record<string, unknown>;
+    breakpointType: string;
+    patternId?: string;
+    handoff?: {
+        fromAgent: string;
+        toAgent: string;
+    };
+}
+/** A pending breakpoint request */
+interface BreakpointRequest {
+    id: string;
+    type: string;
+    agentId: string;
+    input: string;
+    label?: string;
+    requestedAt: number;
+}
+/** Modifications that can be applied when resuming a breakpoint */
+interface BreakpointModifications {
+    input?: string;
+    skip?: boolean;
+}
+/** Breakpoint state stored in facts */
+interface BreakpointState$1 {
+    pending: BreakpointRequest[];
+    resolved: string[];
+    cancelled: string[];
+}
+
+/** Maximum number of resolved/cancelled breakpoint IDs to retain (FIFO eviction) */
+declare const MAX_BREAKPOINT_HISTORY = 200;
+/** Create a unique breakpoint ID */
+declare function createBreakpointId(): string;
+/**
+ * Match a breakpoint configuration against the current execution point.
+ * Returns the matching config or null if no match.
+ */
+declare function matchBreakpoint<T extends string>(breakpoints: BreakpointConfig<T>[], type: T, context: BreakpointContext): BreakpointConfig<T> | null;
+/** Create initial breakpoint state */
+declare function createInitialBreakpointState(): BreakpointState$1;
+
+/** Simplified Agent interface */
+interface AgentLike {
+    name: string;
+    instructions?: string;
+    model?: string;
+    tools?: unknown[];
+}
+/** Agent run result */
+interface RunResult<T = unknown> {
+    output: T;
+    messages: Message[];
+    toolCalls: ToolCall[];
+    totalTokens: number;
+    /** Breakdown of input vs output tokens, when available from the provider */
+    tokenUsage?: TokenUsage;
+    /** True when result was served from semantic cache */
+    isCached?: boolean;
+}
+/** Breakdown of token usage by input/output */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Message from agent run */
+interface Message {
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    toolCallId?: string;
+}
+/** Tool call record */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+    result?: string;
+}
+/** Run function type */
+type AgentRunner = <T = unknown>(agent: AgentLike, input: string, options?: RunOptions) => Promise<RunResult<T>>;
+/** Callback-based streaming run function (e.g. for SSE-based LLM APIs) */
+type StreamingCallbackRunner = (agent: AgentLike, input: string, callbacks: {
+    onToken?: (token: string) => void;
+    onToolStart?: (tool: string, id: string, args: string) => void;
+    onToolEnd?: (tool: string, id: string, result: string) => void;
+    onMessage?: (message: Message) => void;
+    signal?: AbortSignal;
+}) => Promise<RunResult<unknown>>;
+/** Run options */
+interface RunOptions {
+    maxTurns?: number;
+    signal?: AbortSignal;
+    onMessage?: (message: Message) => void;
+    onToolCall?: (toolCall: ToolCall) => void | Promise<void>;
+}
+/**
+ * Lifecycle hooks for adapter-level observability.
+ *
+ * Attach to any adapter (runner or streaming runner) to trace, log,
+ * or measure individual LLM calls without modifying application code.
+ *
+ * @example
+ * ```typescript
+ * const runner = createOpenAIRunner({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   hooks: {
+ *     onBeforeCall: ({ agent, input }) => console.log(`→ ${agent.name}`, input.slice(0, 50)),
+ *     onAfterCall: ({ durationMs, tokenUsage }) => {
+ *       metrics.track('llm_call', { durationMs, ...tokenUsage });
+ *     },
+ *     onError: ({ error }) => Sentry.captureException(error),
+ *   },
+ * });
+ * ```
+ */
+interface AdapterHooks {
+    /** Fires before each LLM API call. */
+    onBeforeCall?: (event: {
+        agent: AgentLike;
+        input: string;
+        timestamp: number;
+    }) => void;
+    /** Fires after a successful LLM API call. */
+    onAfterCall?: (event: {
+        agent: AgentLike;
+        input: string;
+        output: string;
+        totalTokens: number;
+        tokenUsage: TokenUsage;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    /** Fires when an LLM API call fails. */
+    onError?: (event: {
+        agent: AgentLike;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+}
+/** Guardrail function */
+type GuardrailFn<T = unknown> = (data: T, context: GuardrailContext) => GuardrailResult | Promise<GuardrailResult>;
+/** Guardrail context */
+interface GuardrailContext {
+    agentName: string;
+    input: string;
+    facts: Record<string, unknown>;
+}
+/** Guardrail result */
+interface GuardrailResult {
+    passed: boolean;
+    reason?: string;
+    transformed?: unknown;
+}
+/** Input guardrail data */
+interface InputGuardrailData {
+    input: string;
+    agentName: string;
+}
+/** Output guardrail data */
+interface OutputGuardrailData {
+    output: unknown;
+    agentName: string;
+    input: string;
+    messages: Message[];
+}
+/** Tool call guardrail data */
+interface ToolCallGuardrailData {
+    toolCall: ToolCall;
+    agentName: string;
+    input: string;
+}
+/** Retry configuration for guardrails */
+interface GuardrailRetryConfig {
+    /** Total attempts (1 = no retries, 2 = one retry, etc.). @default 1 */
+    attempts?: number;
+    /** @default "exponential" */
+    backoff?: "exponential" | "linear" | "fixed";
+    /** @default 100 */
+    baseDelayMs?: number;
+    /** @default 5000 */
+    maxDelayMs?: number;
+}
+/** Named guardrail for better debugging */
+interface NamedGuardrail<T = unknown> {
+    name: string;
+    fn: GuardrailFn<T>;
+    /** @default true */
+    critical?: boolean;
+    retry?: GuardrailRetryConfig;
+}
+/** Guardrails configuration */
+interface GuardrailsConfig {
+    input?: Array<GuardrailFn<InputGuardrailData> | NamedGuardrail<InputGuardrailData>>;
+    output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
+    toolCall?: Array<GuardrailFn<ToolCallGuardrailData> | NamedGuardrail<ToolCallGuardrailData>>;
+}
+/** Retry configuration for agent runs */
+interface AgentRetryConfig {
+    /** @default 1 */
+    attempts?: number;
+    /** @default "exponential" */
+    backoff?: "exponential" | "linear" | "fixed";
+    /** @default 1000 */
+    baseDelayMs?: number;
+    /** @default 30000 */
+    maxDelayMs?: number;
+    isRetryable?: (error: Error) => boolean;
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+/** Agent state in facts */
+interface AgentState {
+    status: "idle" | "running" | "paused" | "completed" | "error";
+    currentAgent: string | null;
+    input: string | null;
+    output: unknown | null;
+    error: string | null;
+    tokenUsage: number;
+    turnCount: number;
+    startedAt: number | null;
+    completedAt: number | null;
+}
+/** Approval state */
+interface ApprovalState {
+    pending: ApprovalRequest[];
+    approved: string[];
+    rejected: RejectedRequest[];
+}
+/** Rejected request with tracking information */
+interface RejectedRequest {
+    id: string;
+    reason?: string;
+    rejectedAt: number;
+}
+/** Approval request */
+interface ApprovalRequest {
+    id: string;
+    type: "tool_call" | "output" | "handoff";
+    agentName: string;
+    description: string;
+    data: unknown;
+    requestedAt: number;
+}
+/** Combined orchestrator state */
+interface OrchestratorState {
+    agent: AgentState;
+    approval: ApprovalState;
+    conversation: Message[];
+    toolCalls: ToolCall[];
+}
+/** Constraint for orchestrator */
+interface OrchestratorConstraint<F extends Record<string, unknown>> {
+    when: (facts: F & OrchestratorState) => boolean | Promise<boolean>;
+    require: Requirement | ((facts: F & OrchestratorState) => Requirement);
+    priority?: number;
+}
+/** Resolver context for orchestrator */
+interface OrchestratorResolverContext<F extends Record<string, unknown>> {
+    facts: F & OrchestratorState;
+    runAgent: <T>(agent: AgentLike, input: string, options?: RunOptions) => Promise<RunResult<T>>;
+    signal: AbortSignal;
+}
+/** Resolver for orchestrator */
+interface OrchestratorResolver<F extends Record<string, unknown>, R extends Requirement = Requirement> {
+    requirement: (req: Requirement) => req is R;
+    key?: (req: R) => string;
+    resolve: (req: R, context: OrchestratorResolverContext<F>) => void | Promise<void>;
+}
+/** Lifecycle hooks for observability */
+interface OrchestratorLifecycleHooks {
+    onAgentStart?: (event: {
+        agentName: string;
+        input: string;
+        timestamp: number;
+    }) => void;
+    onAgentComplete?: (event: {
+        agentName: string;
+        input: string;
+        output: unknown;
+        tokenUsage: number;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentError?: (event: {
+        agentName: string;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onGuardrailCheck?: (event: {
+        agentId?: string;
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        passed: boolean;
+        reason?: string;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentRetry?: (event: {
+        agentName: string;
+        input: string;
+        attempt: number;
+        error: Error;
+        delayMs: number;
+        timestamp: number;
+    }) => void;
+    /** Called when a breakpoint is hit and waiting for resolution. */
+    onBreakpoint?: (request: BreakpointRequest) => void;
+}
+/** Lifecycle hooks for multi-agent orchestrator observability */
+interface MultiAgentLifecycleHooks {
+    onAgentStart?: (event: {
+        agentId: string;
+        agentName: string;
+        input: string;
+        timestamp: number;
+    }) => void;
+    onAgentComplete?: (event: {
+        agentId: string;
+        agentName: string;
+        input: string;
+        output: unknown;
+        tokenUsage: number;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentError?: (event: {
+        agentId: string;
+        agentName: string;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onGuardrailCheck?: (event: {
+        agentId: string;
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        passed: boolean;
+        reason?: string;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentRetry?: (event: {
+        agentId: string;
+        agentName: string;
+        input: string;
+        attempt: number;
+        error: Error;
+        delayMs: number;
+        timestamp: number;
+    }) => void;
+    onHandoff?: (request: {
+        id: string;
+        fromAgent: string;
+        toAgent: string;
+        input: string;
+        requestedAt: number;
+    }) => void;
+    onHandoffComplete?: (result: {
+        request: {
+            id: string;
+            fromAgent: string;
+            toAgent: string;
+        };
+        completedAt: number;
+    }) => void;
+    onPatternStart?: (event: {
+        patternId: string;
+        patternType: "parallel" | "sequential" | "supervisor" | "dag" | "reflect" | "race" | "debate" | "goal";
+        input: string;
+        timestamp: number;
+    }) => void;
+    onPatternComplete?: (event: {
+        patternId: string;
+        patternType: "parallel" | "sequential" | "supervisor" | "dag" | "reflect" | "race" | "debate" | "goal";
+        durationMs: number;
+        timestamp: number;
+        error?: Error;
+    }) => void;
+    onDagNodeStart?: (event: {
+        patternId: string;
+        nodeId: string;
+        agentId: string;
+        nodeType: "agent" | "task";
+        timestamp: number;
+    }) => void;
+    onDagNodeComplete?: (event: {
+        patternId: string;
+        nodeId: string;
+        agentId: string;
+        nodeType: "agent" | "task";
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onDagNodeError?: (event: {
+        patternId: string;
+        nodeId: string;
+        agentId: string;
+        nodeType: "agent" | "task";
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onDagNodeSkipped?: (event: {
+        patternId: string;
+        nodeId: string;
+        agentId: string;
+        nodeType: "agent" | "task";
+        reason: string;
+        timestamp: number;
+    }) => void;
+    onHealthChange?: (event: {
+        agentId: string;
+        oldScore: number;
+        newScore: number;
+        timestamp: number;
+    }) => void;
+    onReroute?: (event: RerouteEvent) => void;
+    /** Called when a breakpoint is hit and waiting for resolution. */
+    onBreakpoint?: (request: BreakpointRequest) => void;
+    /** Called when a cross-agent derivation value updates */
+    onDerivationUpdate?: (event: {
+        derivationId: string;
+        value: unknown;
+        timestamp: number;
+    }) => void;
+    /** Called when a cross-agent derivation throws an error */
+    onDerivationError?: (event: {
+        derivationId: string;
+        error: Error;
+        timestamp: number;
+    }) => void;
+    /** Called when scratchpad values are updated */
+    onScratchpadUpdate?: (event: {
+        keys: string[];
+        timestamp: number;
+    }) => void;
+    /** Called when a task starts executing */
+    onTaskStart?: (event: {
+        patternId: string;
+        taskId: string;
+        label: string;
+        timestamp: number;
+    }) => void;
+    /** Called when a task completes successfully */
+    onTaskComplete?: (event: {
+        patternId: string;
+        taskId: string;
+        label: string;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    /** Called when a task fails */
+    onTaskError?: (event: {
+        patternId: string;
+        taskId: string;
+        label: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    /** Called when a task reports progress */
+    onTaskProgress?: (event: {
+        patternId: string;
+        taskId: string;
+        label: string;
+        percent: number;
+        message?: string;
+        timestamp: number;
+    }) => void;
+    /** Called when a pattern checkpoint is saved */
+    onCheckpointSave?: (event: {
+        checkpointId: string;
+        patternType: string;
+        step: number;
+        timestamp: number;
+    }) => void;
+    /** Called when a checkpoint save fails */
+    onCheckpointError?: (event: {
+        patternType: string;
+        step: number;
+        error: Error;
+        timestamp: number;
+    }) => void;
+}
+/** Error codes for guardrail errors */
+type GuardrailErrorCode = "INPUT_GUARDRAIL_FAILED" | "OUTPUT_GUARDRAIL_FAILED" | "TOOL_CALL_GUARDRAIL_FAILED" | "APPROVAL_REJECTED" | "BUDGET_EXCEEDED" | "RATE_LIMIT_EXCEEDED" | "AGENT_ERROR";
+/**
+ * Structured error for guardrail failures.
+ *
+ * **Security:** The `input` and `data` properties are non-enumerable to prevent
+ * accidental leakage of sensitive data via JSON.stringify or console.log.
+ */
+declare class GuardrailError extends Error {
+    readonly code: GuardrailErrorCode;
+    readonly guardrailName: string;
+    readonly guardrailType: "input" | "output" | "toolCall";
+    readonly userMessage: string;
+    readonly data: unknown;
+    readonly agentName: string;
+    readonly input: string;
+    constructor(options: {
+        code: GuardrailErrorCode;
+        message: string;
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        userMessage?: string;
+        data?: unknown;
+        agentName: string;
+        input: string;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/** Check if an error is a GuardrailError. */
+declare function isGuardrailError(error: unknown): error is GuardrailError;
+/** Schema validation result */
+interface SchemaValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+/** Schema validator function type */
+type SchemaValidator<_T = unknown> = (value: unknown) => SchemaValidationResult | boolean;
+/** Status of a DAG node during execution */
+type DagNodeStatus = "pending" | "ready" | "running" | "completed" | "error" | "skipped";
+/** Execution context available to DAG node callbacks */
+interface DagExecutionContext {
+    /** Original input to the DAG */
+    input: string;
+    /** Outputs keyed by node ID (populated as nodes complete) */
+    outputs: Record<string, unknown>;
+    /** Statuses keyed by node ID */
+    statuses: Record<string, DagNodeStatus>;
+    /** Error messages keyed by node ID */
+    errors: Record<string, string>;
+    /** Full RunResult keyed by node ID */
+    results: Record<string, RunResult<unknown>>;
+}
+/** A node in a DAG execution pattern */
+interface DagNode {
+    /** Registered handler ID (agent or task) to run for this node */
+    handler: string;
+    /** Upstream node IDs this node depends on */
+    deps?: string[];
+    /** Conditional edge — evaluated when deps are met. @default unconditional */
+    when?: (context: DagExecutionContext) => boolean;
+    /** Build input string for this node's agent. @default JSON.stringify(upstream outputs) */
+    transform?: (context: DagExecutionContext) => string;
+    /** Per-node timeout (ms) */
+    timeout?: number;
+    /** Tiebreaker when multiple nodes are ready (higher = first). @default 0 */
+    priority?: number;
+}
+/** DAG execution pattern — nodes are agents, edges are reactive conditions */
+interface DagPattern<T = unknown> {
+    type: "dag";
+    /** Nodes keyed by node ID */
+    nodes: Record<string, DagNode>;
+    /** Merge all node outputs into the final result */
+    merge: (context: DagExecutionContext) => T | Promise<T>;
+    /** Overall DAG timeout (ms) */
+    timeout?: number;
+    /** Maximum nodes running concurrently. @default Infinity. Consider setting this to avoid API rate limits. */
+    maxConcurrent?: number;
+    /** Error handling strategy. @default "fail" */
+    onNodeError?: "fail" | "skip-downstream" | "continue";
+    /** Checkpoint configuration for mid-execution fault tolerance */
+    checkpoint?: PatternCheckpointConfig;
+}
+/** Debug configuration for orchestrators */
+interface OrchestratorDebugConfig {
+    verboseTimeline?: boolean;
+}
+/** All debug event types */
+type DebugEventType = "agent_start" | "agent_complete" | "agent_error" | "agent_retry" | "guardrail_check" | "constraint_evaluate" | "resolver_start" | "resolver_complete" | "resolver_error" | "approval_request" | "approval_response" | "handoff_start" | "handoff_complete" | "pattern_start" | "pattern_complete" | "dag_node_update" | "breakpoint_hit" | "breakpoint_resumed" | "derivation_update" | "scratchpad_update" | "reflection_iteration" | "race_start" | "race_winner" | "race_cancelled" | "debate_round" | "reroute" | "checkpoint_save" | "checkpoint_restore" | "task_start" | "task_complete" | "task_error" | "task_progress" | "goal_step";
+/** Base debug event */
+interface DebugEventBase {
+    id: number;
+    type: DebugEventType;
+    timestamp: number;
+    agentId?: string;
+    snapshotId: number | null;
+}
+/** Agent start event */
+interface AgentStartEvent extends DebugEventBase {
+    type: "agent_start";
+    agentId: string;
+    inputLength: number;
+    /** Truncated input text (max 5000 chars) */
+    input?: string;
+}
+/** Agent complete event */
+interface AgentCompleteEvent extends DebugEventBase {
+    type: "agent_complete";
+    agentId: string;
+    outputLength: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
+    modelId?: string;
+    /** Truncated output text (max 5000 chars) */
+    output?: string;
+}
+/** Agent error event */
+interface AgentErrorEvent extends DebugEventBase {
+    type: "agent_error";
+    agentId: string;
+    errorMessage: string;
+    durationMs: number;
+}
+/** Agent retry event */
+interface AgentRetryEvent extends DebugEventBase {
+    type: "agent_retry";
+    agentId: string;
+    attempt: number;
+    errorMessage: string;
+    delayMs: number;
+}
+/** Guardrail check event */
+interface GuardrailCheckEvent extends DebugEventBase {
+    type: "guardrail_check";
+    guardrailName: string;
+    guardrailType: "input" | "output" | "toolCall";
+    passed: boolean;
+    reason?: string;
+    durationMs: number;
+}
+/** Constraint evaluate event */
+interface ConstraintEvaluateEvent extends DebugEventBase {
+    type: "constraint_evaluate";
+    constraintId: string;
+    fired: boolean;
+}
+/** Resolver start event */
+interface ResolverStartEvent extends DebugEventBase {
+    type: "resolver_start";
+    resolverId: string;
+    requirementType: string;
+}
+/** Resolver complete event */
+interface ResolverCompleteEvent extends DebugEventBase {
+    type: "resolver_complete";
+    resolverId: string;
+    durationMs: number;
+}
+/** Resolver error event */
+interface ResolverErrorEvent extends DebugEventBase {
+    type: "resolver_error";
+    resolverId: string;
+    errorMessage: string;
+    durationMs: number;
+}
+/** Approval request event */
+interface ApprovalRequestEvent extends DebugEventBase {
+    type: "approval_request";
+    requestId: string;
+    approvalType: "tool_call" | "output" | "handoff";
+}
+/** Approval response event */
+interface ApprovalResponseEvent extends DebugEventBase {
+    type: "approval_response";
+    requestId: string;
+    approved: boolean;
+    reason?: string;
+}
+/** Handoff start event */
+interface HandoffStartEvent extends DebugEventBase {
+    type: "handoff_start";
+    fromAgent: string;
+    toAgent: string;
+}
+/** Handoff complete event */
+interface HandoffCompleteEvent extends DebugEventBase {
+    type: "handoff_complete";
+    fromAgent: string;
+    toAgent: string;
+    durationMs: number;
+}
+/** Pattern start event */
+interface PatternStartEvent extends DebugEventBase {
+    type: "pattern_start";
+    patternId: string;
+    patternType: "parallel" | "sequential" | "supervisor" | "dag" | "reflect" | "race" | "debate" | "goal";
+    /** All handler IDs in this pattern (agents + tasks) */
+    handlers?: string[];
+    /** Which handler IDs are tasks (rest are agents) */
+    taskIds?: string[];
+}
+/** Pattern complete event */
+interface PatternCompleteEvent extends DebugEventBase {
+    type: "pattern_complete";
+    patternId: string;
+    patternType: "parallel" | "sequential" | "supervisor" | "dag" | "reflect" | "race" | "debate" | "goal";
+    durationMs: number;
+    error?: string;
+}
+/** DAG node update event */
+interface DagNodeUpdateEvent extends DebugEventBase {
+    type: "dag_node_update";
+    nodeId: string;
+    status: DagNodeStatus;
+    deps?: string[];
+}
+/** Breakpoint hit event */
+interface BreakpointHitEvent extends DebugEventBase {
+    type: "breakpoint_hit";
+    breakpointId: string;
+    breakpointType: string;
+    label?: string;
+}
+/** Breakpoint resumed event */
+interface BreakpointResumedEvent extends DebugEventBase {
+    type: "breakpoint_resumed";
+    breakpointId: string;
+    modified: boolean;
+    skipped: boolean;
+}
+/** Derivation update event */
+interface DerivationUpdateEvent extends DebugEventBase {
+    type: "derivation_update";
+    derivationId: string;
+    valueType: string;
+}
+/** Scratchpad update event */
+interface ScratchpadUpdateEvent extends DebugEventBase {
+    type: "scratchpad_update";
+    keys: string[];
+}
+/** Reflection iteration event */
+interface ReflectionIterationEvent extends DebugEventBase {
+    type: "reflection_iteration";
+    iteration: number;
+    passed: boolean;
+    score?: number;
+    durationMs: number;
+    producerTokens: number;
+    evaluatorTokens: number;
+}
+/** Race start event */
+interface RaceStartEvent extends DebugEventBase {
+    type: "race_start";
+    patternId: string;
+    agents: string[];
+}
+/** Race winner event */
+interface RaceWinnerEvent extends DebugEventBase {
+    type: "race_winner";
+    patternId: string;
+    winnerId: string;
+    durationMs: number;
+}
+/** Race cancelled event */
+interface RaceCancelledEvent extends DebugEventBase {
+    type: "race_cancelled";
+    patternId: string;
+    cancelledIds: string[];
+    reason: "winner_found" | "timeout" | "all_failed";
+}
+/** Debate round event — emitted after each round's judgement */
+interface DebateRoundEvent extends DebugEventBase {
+    type: "debate_round";
+    patternId: string;
+    round: number;
+    totalRounds: number;
+    winnerId: string;
+    score?: number;
+    agentCount: number;
+}
+/** Reroute debug event recorded when self-healing reroutes to an alternate agent */
+interface RerouteDebugEvent extends DebugEventBase {
+    type: "reroute";
+    agentId: string;
+    from: string;
+    to: string;
+    reason: string;
+}
+/** Checkpoint save event */
+interface CheckpointSaveEvent extends DebugEventBase {
+    type: "checkpoint_save";
+    checkpointId: string;
+    patternType: string;
+    step: number;
+}
+/** Checkpoint restore event */
+interface CheckpointRestoreEvent extends DebugEventBase {
+    type: "checkpoint_restore";
+    checkpointId: string;
+    patternType: string;
+    step: number;
+}
+/** Task start event */
+interface TaskStartEvent extends DebugEventBase {
+    type: "task_start";
+    taskId: string;
+    label: string;
+    description?: string;
+    inputLength: number;
+}
+/** Task complete event */
+interface TaskCompleteEvent extends DebugEventBase {
+    type: "task_complete";
+    taskId: string;
+    label: string;
+    durationMs: number;
+}
+/** Task error event */
+interface TaskErrorEvent extends DebugEventBase {
+    type: "task_error";
+    taskId: string;
+    label: string;
+    error: string;
+    durationMs: number;
+    attempt?: number;
+}
+/** Task progress event */
+interface TaskProgressEvent extends DebugEventBase {
+    type: "task_progress";
+    taskId: string;
+    label: string;
+    percent: number;
+    message?: string;
+}
+/** Goal step event — emitted for each agent invocation within a goal step */
+interface GoalStepEvent extends DebugEventBase {
+    type: "goal_step";
+    agentId: string;
+    step: number;
+    nodeId: string;
+    satisfaction: number;
+    satisfactionDelta: number;
+}
+/** Union of all debug event types */
+type DebugEvent = AgentStartEvent | AgentCompleteEvent | AgentErrorEvent | AgentRetryEvent | GuardrailCheckEvent | ConstraintEvaluateEvent | ResolverStartEvent | ResolverCompleteEvent | ResolverErrorEvent | ApprovalRequestEvent | ApprovalResponseEvent | HandoffStartEvent | HandoffCompleteEvent | PatternStartEvent | PatternCompleteEvent | DagNodeUpdateEvent | BreakpointHitEvent | BreakpointResumedEvent | DerivationUpdateEvent | ScratchpadUpdateEvent | ReflectionIterationEvent | RaceStartEvent | RaceWinnerEvent | RaceCancelledEvent | DebateRoundEvent | RerouteDebugEvent | CheckpointSaveEvent | CheckpointRestoreEvent | TaskStartEvent | TaskCompleteEvent | TaskErrorEvent | TaskProgressEvent | GoalStepEvent;
+/** Health state for an agent stored in facts */
+interface AgentHealthState {
+    circuitState: "CLOSED" | "OPEN" | "HALF_OPEN";
+    healthScore: number;
+    lastUpdated: number;
+}
+/** Reroute event fired when an agent is rerouted */
+interface RerouteEvent {
+    originalAgent: string;
+    reroutedTo: string;
+    reason: string;
+    timestamp: number;
+}
+/** Health monitor configuration */
+interface HealthMonitorConfig {
+    /** Rolling window for metrics (ms). @default 60000 */
+    windowMs?: number;
+    /** Weights for health score computation (must sum to ~1.0) */
+    weights?: {
+        /** Weight for success rate (0-1). @default 0.5 */
+        successRate?: number;
+        /** Weight for latency (0-1). @default 0.3 */
+        latency?: number;
+        /** Weight for circuit state (0-1). @default 0.2 */
+        circuitState?: number;
+    };
+    /** Max latency considered "normal" (ms). @default 5000 */
+    maxNormalLatencyMs?: number;
+    /** Max events per agent before FIFO eviction. @default 1000 */
+    maxEventsPerAgent?: number;
+}
+/** Self-healing configuration for single-agent orchestrator */
+interface SelfHealingConfig {
+    /** Fallback runners to try in order when primary CB is open */
+    fallbackRunners?: AgentRunner[];
+    /** Fallback agent to try when all runners fail */
+    fallbackAgent?: AgentLike;
+    /** Circuit breaker config for primary runner */
+    circuitBreaker?: AgentCircuitBreakerConfig;
+    /** Health score below which to trigger reroute. @default 30 */
+    healthThreshold?: number;
+    /** Behavior when all fallbacks exhausted */
+    degradation?: "reject" | "fallback-response";
+    /** Static response to return when degradation is "fallback-response" */
+    fallbackResponse?: unknown;
+    /** Callback when reroute occurs */
+    onReroute?: (event: RerouteEvent) => void;
+}
+/** Self-healing configuration for multi-agent orchestrator */
+interface MultiAgentSelfHealingConfig {
+    /** Default circuit breaker config for agents without their own */
+    circuitBreakerDefaults?: AgentCircuitBreakerConfig;
+    /** Health score below which to trigger reroute. @default 30 */
+    healthThreshold?: number;
+    /** Explicit equivalency groups (group name → agent IDs) */
+    equivalencyGroups?: Record<string, string[]>;
+    /** Use capability matching for implicit equivalency. @default true */
+    useCapabilities?: boolean;
+    /** Strategy for selecting equivalent agent */
+    selectionStrategy?: "healthiest" | "round-robin";
+    /** Behavior when all equivalents are down */
+    degradation?: "reject" | "fallback-response";
+    /** Static response for "fallback-response" degradation */
+    fallbackResponse?: unknown;
+    /** Callback when reroute occurs */
+    onReroute?: (event: RerouteEvent) => void;
+    /** Callback when agent health changes */
+    onHealthChange?: (event: {
+        agentId: string;
+        oldScore: number;
+        newScore: number;
+    }) => void;
+    /** Health monitor configuration */
+    healthMonitor?: HealthMonitorConfig;
+}
+/** Circuit breaker config for AI agent self-healing (simplified subset of core CircuitBreakerConfig) */
+interface AgentCircuitBreakerConfig {
+    /** Number of failures before opening. @default 5 */
+    failureThreshold?: number;
+    /** Time before trying half-open (ms). @default 30000 */
+    resetTimeoutMs?: number;
+    /** Successes needed to close from half-open. @default 2 */
+    halfOpenSuccesses?: number;
+    /** State change callback */
+    onStateChange?: (from: string, to: string) => void;
+}
+/** Breakpoint state stored in bridge schema — canonical definition in breakpoints.ts */
+type BreakpointState = BreakpointState$1;
+/** Snapshot of all agent states for cross-agent derivations */
+interface CrossAgentSnapshot {
+    agents: Record<string, {
+        status: "idle" | "running" | "completed" | "error";
+        lastInput?: string;
+        lastOutput?: unknown;
+        lastError?: string;
+        runCount: number;
+        totalTokens: number;
+    }>;
+    coordinator: {
+        globalTokens: number;
+        status: string;
+    };
+    scratchpad?: Record<string, unknown>;
+}
+/** Function that computes a derived value from a cross-agent snapshot */
+type CrossAgentDerivationFn<T = unknown> = (snapshot: CrossAgentSnapshot) => T;
+/** Shared scratchpad interface for multi-agent collaboration */
+interface Scratchpad<T extends Record<string, unknown> = Record<string, unknown>> {
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    /** Check if a key exists in the scratchpad */
+    has<K extends keyof T>(key: K): boolean;
+    /** Delete a key from the scratchpad */
+    delete<K extends keyof T>(key: K): void;
+    update(values: Partial<T>): void;
+    getAll(): T;
+    subscribe(keys: (keyof T)[], callback: (key: keyof T, value: unknown) => void): () => void;
+    onChange(callback: (key: string, value: unknown) => void): () => void;
+    reset(): void;
+}
+/** A node in a goal execution pattern */
+interface GoalNode {
+    /** Handler ID — agent or task registered on the orchestrator */
+    handler: string;
+    /** Fact keys this node can produce */
+    produces: string[];
+    /** Fact keys this node needs (must be satisfied before running) */
+    requires?: string[];
+    /** Allow re-run if input facts change after completion */
+    allowRerun?: boolean;
+    /** Priority for selection when multiple nodes are ready. Higher = first */
+    priority?: number;
+    /** Build the input string from current facts */
+    buildInput?: (facts: Record<string, unknown>) => string;
+    /** Extract output facts from the agent's result */
+    extractOutput?: (result: RunResult<unknown>) => Record<string, unknown>;
+}
+/** Goal step metrics */
+interface GoalStepMetrics {
+    step: number;
+    durationMs: number;
+    nodesRun: string[];
+    factsProduced: string[];
+    satisfaction: number;
+    satisfactionDelta: number;
+    tokensConsumed: number;
+}
+/** Goal progress metrics */
+interface GoalMetrics {
+    satisfaction: number;
+    progressRate: number;
+    estimatedStepsRemaining: number | null;
+    decelerating: boolean;
+}
+/** Agent selection strategy for goal pattern */
+interface AgentSelectionStrategy {
+    /**
+     * Select which ready agents to run this step.
+     *
+     * @param readyAgents - Agent IDs whose `requires` are satisfied
+     * @param metrics - Per-agent performance metrics (runs, avgSatisfactionDelta, tokens)
+     * @param goalMetrics - Global goal progress metrics. Built-in strategies use per-agent
+     *   metrics only; this parameter enables custom strategies that account for overall goal
+     *   progress (e.g., switching to cheaper agents as satisfaction approaches 1.0).
+     */
+    select: (readyAgents: string[], metrics: Record<string, {
+        runs: number;
+        avgSatisfactionDelta: number;
+        tokens: number;
+    }>, goalMetrics: GoalMetrics) => string[];
+}
+/** Relaxation context passed to custom relaxation strategies */
+interface RelaxationContext {
+    step: number;
+    facts: Record<string, unknown>;
+    metrics: GoalMetrics;
+    completedNodes: Set<string>;
+    failedNodes: Map<string, number>;
+}
+/** Relaxation strategy for when goal pursuit stalls */
+type RelaxationStrategy = {
+    type: "allow_rerun";
+    nodes: string[];
+} | {
+    type: "alternative_nodes";
+    nodes: GoalNode[];
+} | {
+    type: "inject_facts";
+    facts: Record<string, unknown>;
+} | {
+    type: "accept_partial";
+} | {
+    type: "custom";
+    apply: (context: RelaxationContext) => void | Promise<void>;
+};
+/** Relaxation tier — progressively applied when goal pursuit stalls */
+interface RelaxationTier {
+    label: string;
+    /** Steps of no progress before applying. @default 3 */
+    afterStallSteps?: number;
+    strategy: RelaxationStrategy;
+}
+/** Record of a relaxation event */
+interface RelaxationRecord {
+    step: number;
+    tierIndex: number;
+    label: string;
+    strategy: RelaxationStrategy["type"];
+}
+/** Goal execution pattern — declare desired state, let the runtime resolve */
+interface GoalPattern<T = unknown> {
+    type: "goal";
+    /** Nodes with produces/requires declarations */
+    nodes: Record<string, GoalNode>;
+    /** Goal condition — when this returns true, the goal is achieved */
+    when: (facts: Record<string, unknown>) => boolean;
+    /** Quantitative satisfaction: 0.0 to 1.0. Enables progress tracking.
+     *  If omitted, binary: 0.0 when when() is false, 1.0 when true. */
+    satisfaction?: (facts: Record<string, unknown>) => number;
+    /** Max goal steps. @default 50 */
+    maxSteps?: number;
+    /** Extract final result from achieved facts */
+    extract?: (facts: Record<string, unknown>) => T;
+    /** Timeout in ms. @default 300000 */
+    timeout?: number;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Agent selection strategy. @default "all-ready" */
+    selectionStrategy?: AgentSelectionStrategy;
+    /** Relaxation tiers — progressively applied when goal pursuit stalls */
+    relaxation?: RelaxationTier[];
+    /** Lifecycle hooks */
+    onStep?: (step: number, facts: Record<string, unknown>, readyAgents: string[]) => void;
+    onStall?: (step: number, metrics: GoalMetrics) => void;
+    /** Checkpoint configuration for mid-execution fault tolerance */
+    checkpoint?: PatternCheckpointConfig;
+}
+/** Result of a goal pattern execution */
+interface GoalResult<T = unknown> {
+    /** Whether the when() condition was satisfied */
+    achieved: boolean;
+    /** Final value (from extract, or raw facts) */
+    result: T;
+    /** Final facts state */
+    facts: Record<string, unknown>;
+    /** Nodes that ran, in execution order */
+    executionOrder: string[];
+    /** Per-node results */
+    nodeResults: Record<string, RunResult<unknown>>;
+    /** Total goal steps taken */
+    steps: number;
+    /** Total tokens consumed */
+    totalTokens: number;
+    /** Total duration (ms) */
+    durationMs: number;
+    /** Per-step metrics (satisfaction, nodes run, etc.) */
+    stepMetrics: GoalStepMetrics[];
+    /** Relaxation events applied */
+    relaxations: RelaxationRecord[];
+    /** Error message if goal was not achieved */
+    error?: string;
+}
+/** Universal checkpoint configuration for all execution patterns */
+interface PatternCheckpointConfig {
+    /** Save a checkpoint every N steps/rounds/iterations. @default 5 */
+    everyN?: number;
+    /** Checkpoint store. Uses the orchestrator's store if not provided. */
+    store?: CheckpointStore;
+    /** Label prefix for checkpoints. @default pattern type name */
+    labelPrefix?: string;
+    /** Conditional: only save when this returns true */
+    when?: (context: CheckpointContext) => boolean;
+}
+/** Context passed to conditional checkpoint predicates */
+interface CheckpointContext {
+    /** Current step/round/iteration number */
+    step: number;
+    /** Pattern type identifier */
+    patternType: string;
+    /** Pattern-specific facts (goal only) */
+    facts?: Record<string, unknown>;
+    /** Satisfaction score 0-1 (goal only) */
+    satisfaction?: number;
+}
+type GoalCheckpointConfig = PatternCheckpointConfig;
+/** Common fields present on all pattern checkpoint states */
+interface PatternCheckpointBase {
+    /** Checkpoint format version */
+    version: 1;
+    /** Unique ID */
+    id: string;
+    /** ISO timestamp */
+    createdAt: string;
+    /** User label */
+    label?: string;
+    /** Pattern ID */
+    patternId: string;
+    /** Total expected steps/rounds/iterations (null for unbounded) */
+    stepsTotal?: number | null;
+}
+/** Checkpoint state for sequential pattern */
+interface SequentialCheckpointState extends PatternCheckpointBase {
+    type: "sequential";
+    /** Next agent index to run */
+    step: number;
+    /** Current input for the next agent */
+    currentInput: string;
+    /** Results collected so far (output + tokens) */
+    results: Array<{
+        agentId: string;
+        output: unknown;
+        totalTokens: number;
+    }>;
+}
+/** Checkpoint state for supervisor pattern */
+interface SupervisorCheckpointState extends PatternCheckpointBase {
+    type: "supervisor";
+    /** Next round number */
+    round: number;
+    /** Last supervisor output */
+    supervisorOutput: unknown;
+    /** Worker results so far */
+    workerResults: Array<{
+        output: unknown;
+        totalTokens: number;
+    }>;
+    /** Current input to supervisor */
+    currentInput: string;
+}
+/** Checkpoint state for reflect pattern */
+interface ReflectCheckpointState extends PatternCheckpointBase {
+    type: "reflect";
+    /** Next iteration number */
+    iteration: number;
+    /** Current effective input */
+    effectiveInput: string;
+    /** Iteration history */
+    history: Array<{
+        iteration: number;
+        passed: boolean;
+        score?: number;
+        feedback?: string;
+        durationMs: number;
+        producerTokens: number;
+        evaluatorTokens: number;
+    }>;
+    /** Producer outputs so far */
+    producerOutputs: Array<{
+        output: unknown;
+        score?: number;
+    }>;
+    /** Last producer output */
+    lastProducerOutput: unknown | null;
+}
+/** Checkpoint state for debate pattern */
+interface DebateCheckpointState extends PatternCheckpointBase {
+    type: "debate";
+    /** Next round number */
+    round: number;
+    /** Current input for the round */
+    currentInput: string;
+    /** Completed rounds */
+    rounds: Array<{
+        proposals: Array<{
+            agentId: string;
+            output: unknown;
+        }>;
+        judgement: {
+            winnerId: string;
+            feedback?: string;
+            score?: number;
+        };
+    }>;
+    /** Last winning agent ID */
+    lastWinnerId: string;
+    /** Last winning output */
+    lastWinnerOutput: unknown;
+    /** Tokens consumed so far */
+    tokensConsumed: number;
+}
+/** Checkpoint state for DAG pattern */
+interface DagCheckpointState extends PatternCheckpointBase {
+    type: "dag";
+    /** Per-node statuses */
+    statuses: Record<string, DagNodeStatus>;
+    /** Per-node outputs */
+    outputs: Record<string, unknown>;
+    /** Per-node errors */
+    errors: Record<string, string>;
+    /** Number of completed nodes */
+    completedCount: number;
+    /** Full results (output + tokens per node) */
+    nodeResults: Record<string, {
+        output: unknown;
+        totalTokens: number;
+    }>;
+    /** Original input */
+    input: string;
+}
+/** Serializable mid-goal state for save/resume */
+interface GoalCheckpointState extends PatternCheckpointBase {
+    /** Pattern type discriminator */
+    type: "goal";
+    /** Current step */
+    step: number;
+    /** Current facts snapshot */
+    facts: Record<string, unknown>;
+    /** Completed node IDs */
+    completedNodes: string[];
+    /** Failed node IDs with consecutive failure counts */
+    failedNodes: Record<string, number>;
+    /** Node input hashes (for allowRerun detection) */
+    nodeInputHashes: Record<string, string>;
+    /** Per-node results (serialized — output only, not the full RunResult) */
+    nodeOutputs: Record<string, {
+        output: unknown;
+        totalTokens: number;
+    }>;
+    /** Execution order so far */
+    executionOrder: string[];
+    /** Step metrics collected so far */
+    stepMetrics: GoalStepMetrics[];
+    /** Relaxations applied so far */
+    relaxations: RelaxationRecord[];
+    /** Applied relaxation tier index */
+    appliedRelaxationTiers: number;
+    /** Stall step counter */
+    stallSteps: number;
+    /** Last satisfaction value */
+    lastSatisfaction: number;
+    /** Per-agent metrics */
+    agentMetrics: Record<string, {
+        runs: number;
+        totalDelta: number;
+        tokens: number;
+    }>;
+}
+/** Discriminated union of all pattern checkpoint states */
+type PatternCheckpointState = SequentialCheckpointState | SupervisorCheckpointState | ReflectCheckpointState | DebateCheckpointState | DagCheckpointState | GoalCheckpointState;
+/** Progress computed from a checkpoint state */
+interface CheckpointProgress {
+    /** 0-100 percentage complete */
+    percentage: number;
+    /** Steps/rounds/iterations completed */
+    stepsCompleted: number;
+    /** Total expected steps (null for unbounded patterns) */
+    stepsTotal: number | null;
+    /** Tokens consumed so far */
+    tokensConsumed: number;
+    /** Estimated tokens remaining (null when unknowable) */
+    estimatedTokensRemaining: number | null;
+    /** Estimated steps remaining (null when unknowable) */
+    estimatedStepsRemaining: number | null;
+}
+/** Diff between two checkpoint states */
+interface CheckpointDiff {
+    /** Pattern type */
+    patternType: string;
+    /** Step/round/iteration difference */
+    stepDelta: number;
+    /** Token difference */
+    tokensDelta: number;
+    /** Fact changes (goal only) */
+    facts?: {
+        added: string[];
+        removed: string[];
+        changed: Array<{
+            key: string;
+            before: unknown;
+            after: unknown;
+        }>;
+    };
+    /** Nodes completed between checkpoints (DAG/goal) */
+    nodesCompleted?: string[];
+}
+
+export { type DebateRoundEvent as $, type AgentLike as A, type BreakpointState as B, type Checkpoint as C, type DebugEvent as D, type CheckpointDiff as E, type CheckpointLocalState as F, type GuardrailFn as G, type CheckpointProgress as H, type InputGuardrailData as I, type CheckpointRestoreEvent as J, type CheckpointSaveEvent as K, type CheckpointStore as L, type Message as M, type ConstraintEvaluateEvent as N, type OutputGuardrailData as O, type CrossAgentDerivationFn as P, type CrossAgentSnapshot as Q, type RunOptions as R, type SchemaValidator as S, type ToolCallGuardrailData as T, type DagCheckpointState as U, type DagExecutionContext as V, type DagNode as W, type DagNodeStatus as X, type DagNodeUpdateEvent as Y, type DagPattern as Z, type DebateCheckpointState as _, type AdapterHooks as a, type TaskProgressEvent as a$, type DebugEventBase as a0, type DebugEventType as a1, type DerivationUpdateEvent as a2, type GoalCheckpointConfig as a3, type GoalCheckpointState as a4, type GoalMetrics as a5, type GoalNode as a6, type GoalPattern as a7, type GoalStepMetrics as a8, type GuardrailCheckEvent as a9, type PatternCompleteEvent as aA, type PatternStartEvent as aB, type RaceCancelledEvent as aC, type RaceStartEvent as aD, type RaceWinnerEvent as aE, type ReflectCheckpointState as aF, type ReflectionIterationEvent as aG, type RejectedRequest as aH, type RelaxationContext as aI, type RelaxationRecord as aJ, type RelaxationStrategy as aK, type RelaxationTier as aL, type RerouteDebugEvent as aM, type RerouteEvent as aN, type ResolverCompleteEvent as aO, type ResolverErrorEvent as aP, type ResolverStartEvent as aQ, type SchemaValidationResult as aR, type Scratchpad as aS, type ScratchpadUpdateEvent as aT, type SelfHealingConfig as aU, type SequentialCheckpointState as aV, type SingleAgentCheckpointLocalState as aW, type StreamingCallbackRunner as aX, type SupervisorCheckpointState as aY, type TaskCompleteEvent as aZ, type TaskErrorEvent as a_, type GuardrailContext as aa, GuardrailError as ab, type GuardrailErrorCode as ac, type GuardrailResult as ad, type GuardrailRetryConfig as ae, type GuardrailsConfig as af, type HandoffCompleteEvent as ag, type HandoffStartEvent as ah, type HealthMonitorConfig as ai, InMemoryCheckpointStore as aj, type InMemoryCheckpointStoreOptions as ak, MAX_BREAKPOINT_HISTORY as al, type MultiAgentBreakpointType as am, type MultiAgentCheckpointLocalState as an, type MultiAgentLifecycleHooks as ao, type MultiAgentSelfHealingConfig as ap, type NamedGuardrail as aq, type OrchestratorConstraint as ar, type OrchestratorDebugConfig as as, type OrchestratorLifecycleHooks as at, type OrchestratorResolver as au, type OrchestratorResolverContext as av, type OrchestratorState as aw, type PatternCheckpointBase as ax, type PatternCheckpointConfig as ay, type PatternCheckpointState as az, type AgentRunner as b, type TaskStartEvent as b0, type TokenUsage as b1, type ToolCall as b2, createBreakpointId as b3, createCheckpointId as b4, createInitialBreakpointState as b5, isGuardrailError as b6, matchBreakpoint as b7, validateCheckpoint as b8, type ApprovalState as c, type AgentState as d, type RunResult as e, type GoalResult as f, type AgentCircuitBreakerConfig as g, type AgentCompleteEvent as h, type AgentErrorEvent as i, type AgentHealthState as j, type AgentRetryConfig as k, type AgentRetryEvent as l, type AgentSelectionStrategy as m, type AgentStartEvent as n, type ApprovalRequest as o, type ApprovalRequestEvent as p, type ApprovalResponseEvent as q, type BreakpointConfig as r, type BreakpointContext as s, type BreakpointHitEvent as t, type BreakpointModifications as u, type BreakpointRequest as v, type BreakpointResumedEvent as w, type BreakpointState$1 as x, type BreakpointType as y, type CheckpointContext as z };