import { C as Cost, S as State, A as Action, F as Feedback, a as FailureType, P as ProbeData, b as ProbeResult, c as Signal, M as Middleware, L as Logger, d as StepContext, e as StepResult, V as VectorN, f as AggregateProbeResult } from './interfaces-BPfVSRPt.cjs';
export { G as GrassmannianSnapshot, j as ManifoldProvider, k as ManifoldSnapshot, m as MetadataChannels, g as SubspaceBasis, h as SubspaceComparison, i as SubspaceExtraction, l as SubspaceTrajectory } from './interfaces-BPfVSRPt.cjs';
import * as _openai_agents_core from '@openai/agents-core';

/**
 * A generic control subject that produces a sequence of semantic states.
 *
 * `Trajectory<S>` is the foundational abstraction for CyberLoop's control loop.
 * Any process that can be modeled as a sequence of states — agent reasoning,
 * document scanning, narrative evaluation, corpus analysis — can implement
 * this interface and be wrapped with `cyberloop()`.
 *
 * `SteppableAgent` extends this interface, so existing agent code continues
 * to work unchanged.
 *
 * @typeParam S - The state type carried through the trajectory.
 *
 * @example
 * ```ts
 * // A corpus scanner as a Trajectory
 * const scanner: Trajectory<ChunkState> = {
 *   getInitialState: (corpus) => loadFirstChunk(corpus),
 *   advance: (state) => embedAndScoreNextChunk(state),
 *   isTerminal: (state) => state.chunkIndex >= state.totalChunks,
 *   toOutput: (state) => state.manifoldReport,
 * };
 *
 * const controlled = cyberloop(scanner, {
 *   middleware: [manifoldMiddleware({ corpus: companyDocs })],
 * });
 * ```
 */
interface Trajectory<S> {
    /** Derive the initial state from the input. */
    getInitialState(input: unknown): Promise<S>;
    /** Advance the trajectory by one frame from the current state. */
    advance(state: S): Promise<TrajectoryFrame<S>>;
    /** Check whether the trajectory has reached a terminal state. */
    isTerminal(state: S): boolean;
    /** Convert the final state into an output value. */
    toOutput(state: S): unknown;
}
/**
 * A single frame in a trajectory — the result of one `advance()` call.
 */
interface TrajectoryFrame<S> {
    /** The new state after this frame. */
    state: S;
    /** The action taken (for logging/middleware). */
    action?: unknown;
    /** Cost incurred by this frame (for budget tracking). */
    cost?: number;
}
/**
 * Type guard: checks whether a value implements the Trajectory interface.
 */
declare function isTrajectory<S>(value: unknown): value is Trajectory<S>;

/**
 * Minimal agent interface. Any object with a `run()` method qualifies.
 *
 * This is the only requirement for using `cyberloop()` in opaque mode —
 * CyberLoop wraps the entire `run()` call with middleware.
 */
interface AgentLike<I = string, O extends AgentResult = AgentResult> {
    run(input: I): Promise<O>;
}
/**
 * Result returned by an agent's `run()` method.
 */
interface AgentResult {
    output: string;
    [key: string]: unknown;
}
/**
 * An agent that exposes step-level control, enabling per-step middleware.
 *
 * `SteppableAgent` extends both `AgentLike` (for `run()`) and `Trajectory`
 * (for frame-by-frame control). The `step`/`isDone`/`toResult` methods are
 * the agent-specific names; they map to the generic `Trajectory` methods:
 *
 * | SteppableAgent | Trajectory   |
 * |----------------|--------------|
 * | `step()`       | `advance()`  |
 * | `isDone()`     | `isTerminal()` |
 * | `toResult()`   | `toOutput()` |
 * | `getInitialState()` | `getInitialState()` |
 *
 * When wrapped with `cyberloop()`, the wrapper drives the step loop:
 * ```
 * state = getInitialState(input)
 * while (!isDone(state)) {
 *   // middleware beforeStep
 *   stepOutput = step(state)
 *   // middleware afterStep
 *   state = stepOutput.state
 * }
 * return toResult(state)
 * ```
 */
interface SteppableAgent<S = unknown, I = string, O extends AgentResult = AgentResult> extends AgentLike<I, O>, Trajectory<S> {
    /** Execute a single step from the current state. */
    step(state: S): Promise<StepOutput<S>>;
    /** Derive the initial state from the input. */
    getInitialState(input: I): Promise<S>;
    /** Check whether the agent has reached a terminal state. */
    isDone(state: S): boolean;
    /** Convert the final state into an AgentResult. */
    toResult(state: S): O;
    /** Alias for `step()` — advances the trajectory by one frame. */
    advance(state: S): Promise<TrajectoryFrame<S>>;
    /** Alias for `isDone()` — checks if the trajectory is terminal. */
    isTerminal(state: S): boolean;
    /** Alias for `toResult()` — converts final state to output. */
    toOutput(state: S): O;
}
/**
 * Output of a single agent step.
 */
interface StepOutput<S> {
    /** The new state after this step. */
    state: S;
    /** The action taken (for logging/middleware). */
    action?: unknown;
    /** Cost incurred by this step (for budget tracking). */
    cost?: number;
}
/**
 * Type guard: checks whether an agent implements SteppableAgent.
 */
declare function isSteppable<S, I, O extends AgentResult>(agent: AgentLike<I, O>): agent is SteppableAgent<S, I, O>;

/**
 * BudgetTracker enforces a finite control horizon by tracking cumulative cost.
 */
interface BudgetTracker {
    /** Record cost for the current step (API call, token, time units, etc.). */
    record(cost: Cost): void;
    /** Remaining budget (arbitrary units decided by adapter). */
    remaining(): number;
    /** Whether budget is exhausted and the loop should stop. */
    shouldStop(): boolean;
    /** Reset to an initial budget value (optional). */
    reset?(value?: Cost): void;
}

/**
 * Environment provides observable state and executes actions.
 * It should be a thin, deterministic adapter to the external world or simulator.
 */
interface Environment<S = State, A = Action> {
    /** Observe the current state snapshot. Should NOT have side effects. */
    observe(): Promise<S> | S;
    /** Apply an action and return the next state. May be async. */
    apply(action: A): Promise<S>;
}

/**
 * Evaluator measures progress / stability and emits a feedback signal.
 * It can be cheap (deterministic) or expensive (semantic), depending on the adapter.
 */
interface Evaluator<S = State, F = Feedback> {
    /** Evaluate transition from prev -> next (and optionally action inside adapter) */
    evaluate(prev: S, next: S): F | Promise<F>;
}

/**
 * FailureClassifier categorizes failures into types for routing decisions.
 *
 * NOTE: Currently not used in Inner/Outer Loop architecture.
 * ProbePolicy directly examines state instead of classifying failures.
 * Kept for future scenarios with complex failure modes (e.g., distributed system debugging).
 * See docs/implementation/unused-interfaces.md for details.
 */
interface FailureClassifier<S, A> {
    classify(input: {
        prev: S;
        next?: S;
        action?: A;
        probeReason?: string;
        metrics?: Record<string, unknown>;
    }): FailureType;
}

/**
 * Ladder is the internal gradient that regulates exploration intensity.
 * Implementations should be pure and small-state to keep control stable.
 */
interface Ladder<F = Feedback> {
    /** Update internal level from feedback */
    update(feedback: F): void;
    /** Current ladder level (e.g., 0..1 or discrete stage index) */
    level(): number;
}

/**
 * Planner - Strategic planning and replanning (outer control loop)
 *
 * Part of the outer control loop. Makes expensive, deliberative decisions
 * using LLM or other reasoning systems.
 *
 * Inspired by:
 * - Agentic systems: High-level planning
 * - Control theory: Slow outer loop / supervisory control
 * - Hierarchical control: Strategic layer above reactive layer
 *
 * @template S - State type
 */
interface Planner<S = State> {
    /**
     * Create initial plan from user input
     * Called once at the start to initialize exploration
     *
     * Example: Convert "node graceful shutdown" into SearchFilters
     *
     * @param input - User's natural language input
     * @returns Initial state to begin exploration
     */
    plan(input: string): Promise<S>;
    /**
     * Evaluate exploration results and produce final output
     * Called when exploration finds a stable state
     *
     * Example: Summarize found repositories into recommendations
     *
     * @param state - Final state after successful exploration
     * @param history - History of states during exploration
     * @returns Final output for user (e.g., summary, recommendations)
     */
    evaluate(state: S, history: S[]): Promise<string>;
    /**
     * Replan when exploration fails or gets stuck
     * Called when exploration budget exhausted without finding stable state
     *
     * Example: Suggest completely different search strategy
     *
     * @param state - Current state where exploration failed
     * @param history - History of states during failed exploration
     * @returns New initial state to try different strategy, or null if can't replan
     */
    replan(state: S, history: S[]): Promise<S | null>;
}

/**
 * Policy decides the next action and can adapt from feedback & ladder signals.
 *
 * NOTE: Currently not used directly in Inner/Outer Loop architecture.
 * Only ProbePolicy (which extends this) is used.
 * Kept for future scenarios requiring multiple policy types (e.g., bug localization, triaging).
 * See docs/implementation/unused-interfaces.md for details.
 */
interface Policy<S = State, A = Action, F = Feedback> {
    id: string;
    /** Declarative metadata used by StrategySelector for routing. */
    capabilities?(): {
        handles?: string[];
        explorationRange?: [number, number];
        cost?: {
            step: number;
            expected?: number;
        };
    };
    /** Decide the next action given the current state & ladder level. */
    decide(state: S, ladder: Ladder<F>): Promise<A> | A;
    /** Optional adaptation hook with latest feedback. */
    adapt?(feedback: F, ladder: Ladder<F>): void;
}
/**
 * ProbePolicy - Fast, reflexive control policy for inner loop
 *
 * Part of the inner control loop. Makes deterministic decisions based on
 * probe signals (gradient information) without expensive LLM calls.
 *
 * Inspired by AICL whitepaper: "Probe performs low-cost checks to confirm direction"
 *
 * @template S - State type
 * @template A - Action type
 * @template F - Feedback type (typically number for gradient)
 */
interface ProbePolicy<S = State, A = Action, F = Feedback> extends Policy<S, A, F> {
    /**
     * Initialize policy with the initial state from planner
     * Called once at the start of exploration
     */
    initialize(state: S): void;
    /**
     * Check if current state is stable/good enough to stop exploration
     * Returns true when state is in acceptable range
     */
    isStable(state: S): boolean;
}

/**
 * Probe performs a cheap, deterministic feasibility check before full execution.
 * Examples: hit count, distribution entropy, guard conditions.
 */
interface Probe<S = State, D = ProbeData, R extends ProbeResult<D> = ProbeResult<D>> {
    id: string;
    /** Optional declaration for routing & budgeting */
    capabilities?(): {
        cost?: number;
        supports?: string[];
    };
    /** Deterministic canary test. MUST be cheap. */
    test(state: S): Promise<R> | R;
    /** Optional state inspection for debugging */
    inspectState?(state: S): Record<string, unknown>;
}

/**
 * StrategySelector is the meta-controller that routes between probes and policies
 * based on failure categories, ladder level, and remaining budget.
 *
 * NOTE: Currently not used in Inner/Outer Loop architecture.
 * The Planner handles strategic decisions in the outer loop.
 * Kept for future scenarios requiring dynamic policy selection (e.g., multi-domain agents).
 * See docs/implementation/unused-interfaces.md for details.
 */
interface StrategySelector<S = unknown, A = unknown> {
    select(input: {
        failure: FailureType;
        ladderLevel: number;
        budgetRemaining: number;
        probes: Probe<S>[];
        policies: Policy<S, A>[];
        context?: Signal;
    }): {
        probe: Probe<S>;
        policy: Policy<S, A>;
    };
}

/**
 * TerminationPolicy decides when to stop exploration based on various signals.
 *
 * NOTE: Currently not used in Inner/Outer Loop architecture.
 * ProbePolicy.isStable() and budget checks handle termination.
 * Kept for future scenarios with complex stopping criteria (e.g., multi-objective optimization).
 * See docs/implementation/unused-interfaces.md for details.
 */
interface TerminationPolicy {
    shouldStop(input: {
        t: number;
        budgetRemaining: number;
        noImprovementSteps: number;
        lastFeedback?: number;
    }): {
        stop: boolean;
        reason?: string;
    };
}

/**
 * Configuration for `cyberloop()`.
 */
interface CyberLoopOpts<S = unknown> {
    /** Budget constraints. Currently supports max steps. */
    budget?: {
        /** Maximum number of steps before halting. Default: 50 */
        maxSteps?: number;
    };
    /** Additional middleware to register (runs after built-in budget/telemetry). */
    middleware?: Middleware<S>[];
    /** Logger for built-in telemetry middleware. If omitted, no telemetry. */
    logger?: Logger;
    /** Event hooks for lightweight observation without writing full middleware. */
    on?: {
        beforeStep?: (ctx: StepContext<S>) => void;
        afterStep?: (ctx: StepContext<S>, result: StepResult<S>) => void;
        onHalt?: (reason: string) => void;
    };
}

/**
 * Wrap any agent or trajectory with CyberLoop middleware.
 *
 * This is the **Assistive SDK** entry point (v2.2+). It instruments the inner
 * loop with composable middleware (budget, policy, kinematics, telemetry)
 * while leaving the outer loop (failure handling, replanning, orchestration
 * topology) entirely in user code.
 *
 * Accepts three kinds of control subjects:
 *
 * - **Opaque agents** (`AgentLike`): middleware runs once around the entire `run()` call.
 * - **Steppable agents** (`SteppableAgent`): middleware runs around each `step()` call.
 * - **Trajectories** (`Trajectory<S>`): middleware runs around each `advance()` call.
 *   Returns an `AgentLike` whose `run()` drives the trajectory loop.
 *
 * Returns a new `AgentLike` with the same `run()` signature.
 *
 * For the prescriptive inner/outer loop controller where CyberLoop owns the
 * full plan → explore → evaluate → replan cycle, see {@link Orchestrator}
 * in `./orchestrator.ts`.
 *
 * @see docs/guide/choosing-your-api.md — When to use cyberloop() vs Orchestrator
 *
 * @example
 * ```ts
 * // Agent usage (existing)
 * const wrapped = cyberloop(myAgent, {
 *   budget: { maxSteps: 20 },
 *   middleware: [probeMiddleware(myProbe)],
 *   logger: pino(),
 * });
 * const result = await wrapped.run("find the answer");
 *
 * // Trajectory usage (v2.3+)
 * const controlled = cyberloop(myTrajectory, {
 *   budget: { maxSteps: 100 },
 *   middleware: [manifoldMiddleware({ corpus })],
 * });
 * const result = await controlled.run(corpusInput);
 * ```
 */
declare function cyberloop<S, I = string, O extends AgentResult = AgentResult>(subject: AgentLike<I, O> | Trajectory<S>, opts?: CyberLoopOpts<S>): AgentLike<I, O>;

/**
 * Riemannian manifold operations for CyberLoop v3.0.
 *
 * This module approximates the local geometry of a data manifold using
 * Principal Component Analysis on k nearest neighbors. It enables the
 * control layer to distinguish between on-manifold motion (tangent) and
 * off-manifold drift (normal).
 *
 * **Key optimization:** Uses the Gramian dual trick — instead of
 * diagonalizing the d×d covariance matrix (O(d³)), we diagonalize the
 * k×k Gramian matrix (O(k³) where k << d). The non-zero eigenvalues
 * are identical.
 *
 * @module geometry/manifold
 */

/**
 * Local geometry at a point on the data manifold.
 */
interface LocalGeometry {
    /** Orthonormal basis spanning the tangent plane (valid directions). */
    tangentBasis: VectorN[];
    /** Orthonormal basis spanning the normal space (drift directions). */
    normalBasis: VectorN[];
    /** Eigenvalues from PCA (descending order). */
    eigenvalues: number[];
    /** Local curvature κ (0 = flat, 1 = maximally curved / isotropic). */
    curvature: number;
    /** Explained variance ratio of the tangent space (0–1). */
    explainedVariance: number;
    /** Mean of the neighborhood (centroid). */
    centroid: VectorN;
}

/**
 * Middleware that enforces a budget by delegating to an existing BudgetTracker.
 *
 * - `beforeStep`: halts if budget is exhausted, populates ctx.budget snapshot.
 * - `afterStep`: records the step cost (defaults to 1 if not specified).
 */
declare function budgetMiddleware<S>(tracker: BudgetTracker): Middleware<S>;

/**
 * Middleware that computes feedback after each step using an Evaluator.
 *
 * - `afterStep`: if `prevState` exists, calls `evaluator.evaluate(prev, next)`
 *   and stores the feedback in `ctx.metadata['feedback']`.
 */
declare function evaluatorMiddleware<S>(evaluator: Evaluator<S>): Middleware<S>;

/**
 * Middleware that runs a Probe before each step and attaches the result to metadata.
 *
 * - `beforeStep`: runs `probe.test(state)`, stores result in `ctx.metadata[probe.id]`.
 */
declare function probeMiddleware<S>(probe: Probe<S>): Middleware<S>;

/**
 * Executes a chain of middleware around agent steps.
 *
 * - `beforeStep` hooks run in registration order (first registered → first to run).
 * - `afterStep` hooks run in reverse order (Koa-style onion model).
 * - `setup` and `teardown` run in registration order.
 *
 * If any `beforeStep` returns `'halt'`, the step is skipped and the loop should stop.
 */
declare class MiddlewareRunner<S = unknown> {
    private readonly stack;
    constructor(middleware?: Middleware<S>[]);
    /** Add a middleware to the end of the chain. */
    use(mw: Middleware<S>): void;
    /** Number of middleware in the chain. */
    get size(): number;
    /**
     * Run all `setup` hooks in registration order.
     */
    runSetup(ctx: {
        input: unknown;
    }): Promise<void>;
    /**
     * Run all `teardown` hooks in registration order.
     */
    runTeardown(ctx: {
        reason: string;
    }): Promise<void>;
    /**
     * Run all `beforeStep` hooks in registration order.
     *
     * Each middleware receives the (possibly modified) context from the previous one.
     * If any middleware returns `'halt'`, execution stops immediately and `'halt'` is returned.
     *
     * @returns The final `StepContext` to pass to the agent, or `'halt'` to stop the loop.
     */
    runBeforeStep(ctx: StepContext<S>): Promise<StepContext<S> | 'halt'>;
    /**
     * Run all `afterStep` hooks in reverse registration order (onion model).
     */
    runAfterStep(ctx: StepContext<S>, result: StepResult<S>): Promise<void>;
}

interface StagnationOpts {
    /** Number of consecutive non-improving steps before halting. Default: 5 */
    maxStagnantSteps?: number;
    /** Minimum feedback value to count as improvement. Default: 0 */
    minImprovement?: number;
}
/**
 * Middleware that halts the loop when feedback stagnates.
 *
 * - `afterStep`: reads `ctx.metadata['feedback']` (typically set by evaluatorMiddleware).
 *   If feedback ≤ minImprovement, increments stagnation counter. Resets on improvement.
 * - `beforeStep`: halts if stagnation counter ≥ maxStagnantSteps.
 * - `setup`: resets counter.
 */
declare function stagnationMiddleware<S>(opts?: StagnationOpts): Middleware<S>;

/**
 * Middleware that logs structured telemetry for each lifecycle event.
 *
 * - `setup`: logs loop start.
 * - `beforeStep`: logs step start with state and budget.
 * - `afterStep`: logs step end with action, cost, and feedback.
 * - `teardown`: logs loop end with reason.
 */
declare function telemetryMiddleware<S>(logger: Logger): Middleware<S>;

/**
 * ControlBudget - Hierarchical budget for inner/outer control loops
 *
 * Separates cheap operations (inner loop: probes, local adjustments)
 * from expensive operations (outer loop: LLM calls, planning).
 *
 * Inspired by hierarchical control theory where fast inner loops
 * operate at high frequency with low cost, while slow outer loops
 * provide strategic guidance at low frequency with high cost.
 */
interface ControlBudget {
    /** Inner loop budget - cheap, high-frequency operations */
    innerLoop: BudgetTracker;
    /** Outer loop budget - expensive, low-frequency operations */
    outerLoop: BudgetTracker;
    /** Check if any budget is exhausted */
    shouldStop(): boolean;
}
/**
 * Create a control budget with specified initial values
 */
declare function createControlBudget(innerLoopBudget: Cost, outerLoopBudget: Cost): ControlBudget;

/**
 * @module Orchestrator (Legacy / Full Control)
 *
 * Prescriptive inner/outer loop controller. You provide Planner, ProbePolicy,
 * Environment, Evaluator, Ladder, Budget, and Probes — the Orchestrator
 * coordinates the full plan → explore → evaluate → replan cycle.
 *
 * CyberLoop owns both loops: the outer loop (Planner) decides strategy,
 * the inner loop (ProbePolicy + Ladder) handles cheap, deterministic exploration.
 *
 * For a lighter-weight approach where you keep your existing agent and add
 * control via composable middleware, see {@link cyberloop} in `./wrapper.ts`.
 *
 * @see docs/guide/choosing-your-api.md — When to use Orchestrator vs cyberloop()
 */

/**
 * ExplorationResult - Result of inner loop exploration
 */
interface ExplorationResult<S, D, R extends ProbeResult<D>> {
    status: 'stable' | 'budget-exhausted';
    state: S;
    history: S[];
    probeResults: AggregateProbeResult<D, R>[];
}
/**
 * StepLog - Log entry for each inner loop iteration
 */
interface StepLog<S, A, F, D, R extends ProbeResult<D>> {
    t: number;
    state: S;
    action?: A;
    next?: S;
    feedback?: F;
    ladderLevel: number;
    innerBudgetRemaining: number;
    probeResult?: AggregateProbeResult<D, R>;
    isStable: boolean;
}
/**
 * OrchestratorResult - Final result from orchestrator
 */
interface OrchestratorResult<S, A, F, D, R extends ProbeResult<D>> {
    output: string;
    explorationAttempts: number;
    innerLoopSteps: number;
    outerLoopCalls: number;
    logs: StepLog<S, A, F, D, R>[];
}
/**
 * OrchestratorOpts - Configuration for orchestrator
 */
interface OrchestratorOpts<S, A, F, D, R extends ProbeResult<D>> {
    env: Environment<S, A>;
    probePolicy: ProbePolicy<S, A, F>;
    planner: Planner<S>;
    probes: Probe<S, D, R>[];
    evaluator: Evaluator<S, F>;
    ladder: Ladder<F>;
    budget: ControlBudget;
    maxInnerSteps?: number;
    logger?: Logger;
}
/**
 * Orchestrator - Hierarchical control loop with inner/outer loops
 *
 * Architecture:
 * - Inner loop: Fast, reflexive control using ProbePolicy
 * - Outer loop: Slow, strategic control using Planner
 *
 * Flow:
 * 1. Planner creates initial plan from user input (outer loop call #1)
 * 2. Inner loop explores deterministically until stable or budget exhausted
 * 3. If stable: Planner evaluates results (outer loop call #2)
 * 4. If budget exhausted: Planner replans (outer loop call #3), goto step 2
 * 5. Return final output
 */
declare class Orchestrator<S = State, A = Action, F = Feedback, D = ProbeData, R extends ProbeResult<D> = ProbeResult<D>> {
    private readonly env;
    private readonly probePolicy;
    private readonly planner;
    private readonly probes;
    private readonly evaluator;
    private readonly ladder;
    private readonly budget;
    private readonly maxInnerSteps;
    private readonly logger;
    logs: StepLog<S, A, F, D, R>[];
    constructor(opts: OrchestratorOpts<S, A, F, D, R>);
    /**
     * Run the orchestrator with user input
     *
     * @param userInput - User's natural language input
     * @returns Final output and statistics
     */
    run(userInput: string): Promise<OrchestratorResult<S, A, F, D, R>>;
    /**
     * Inner loop: Fast, deterministic exploration
     *
     * Uses ProbePolicy to make quick adjustments based on probe signals
     * until state is stable or inner loop budget exhausted.
     */
    private exploreInnerLoop;
    /**
     * Run all probes and combine results
     */
    private runProbes;
}

/** Tracks multiple resource caps (e.g., steps, tokens, latency) simultaneously. */
declare class MultiBudget implements BudgetTracker {
    private readonly caps;
    private readonly used;
    constructor(caps: Record<string, number>);
    record(cost: Cost): void;
    remaining(): number;
    shouldStop(): boolean;
    reset(valueMap?: Record<string, number>): void;
    snapshot(): {
        used: Record<string, number>;
        caps: Record<string, number>;
    };
}

/**
 * Turns an arbitrary scoring function into an evaluator compatible with the loop.
 */
declare const DeltaScoreEvaluator: <S>(score: (prev: S, next: S) => number) => {
    evaluate: (prev: S, next: S) => number;
};

/**
 * Proportional controller that scales ladder level by feedback signal.
 * Positive feedback raises the level, negative lowers it.
 */
declare class ProportionalLadder implements Ladder<number> {
    private readonly opts;
    private levelValue;
    constructor(opts?: {
        gainUp?: number;
        gainDown?: number;
        max?: number;
    });
    update(feedback: number): void;
    level(): number;
}

/**
 * Reference Implementations for Optional Meta-Control Components
 *
 * This module provides example implementations of optional AICL interfaces.
 * These are educational examples showing how to implement advanced meta-control
 * components like StrategySelector, FailureClassifier, and TerminationPolicy.
 *
 * ## When to use these
 *
 * Most applications DON'T need these components. They're for advanced scenarios:
 * - Multi-strategy routing across different domains
 * - Complex failure diagnosis and recovery
 * - Multi-objective termination criteria
 *
 * ## Recommended approach
 *
 * Instead of using these generic implementations, create domain-specific components
 * tailored to your use case. See `src/adapters/github` for the recommended pattern:
 * - Custom ProbePolicy (DeterministicSearchPolicy)
 * - Domain-specific probes (hasHitsProbe, dropGuardProbe, entropyGuardProbe)
 * - Simple evaluators and ladders from core/
 *
 * ## What's in this module
 *
 * - SimpleBudgetTracker - Basic budget tracking (use ControlBudget instead)
 * - RuleBasedStrategySelector - Multi-strategy routing example
 * - CheapPassProbe - No-op probe for testing
 * - ThresholdEvaluator - Placeholder evaluator for testing
 * - StagnationTerminationPolicy - Multi-objective stopping criteria
 * - ReasonFailureClassifier - Rule-based failure diagnosis
 */

/**
 * Reference implementation: Simple budget tracker.
 * Tracks a finite total budget. Decrements each time `record()` is called.
 * Note: Production code should use ControlBudget for hierarchical inner/outer loop tracking.
 */
declare class SimpleBudgetTracker implements BudgetTracker {
    private total;
    private current;
    constructor(total: number);
    record(cost: number | Record<string, number>): void;
    remaining(): number;
    shouldStop(): boolean;
    reset(v?: number): void;
}
/**
 * Reference implementation: Rule-based strategy selector.
 * Optional meta-control component for multi-strategy routing.
 * Chooses the cheapest probe/policy pair based on failure type and ladder level.
 * Most applications use a single policy and don't need this.
 */
declare class RuleBasedStrategySelector<S, A> implements StrategySelector<S, A> {
    select(input: {
        failure: FailureType;
        ladderLevel: number;
        budgetRemaining: number;
        probes: Probe<S>[];
        policies: Policy<S, A>[];
    }): {
        probe: Probe<S>;
        policy: Policy<S, A>;
    };
}
/**
 * Reference implementation: No-op probe for testing.
 * Always passes with zero cost. Useful for quick experiments and testing.
 */
declare const CheapPassProbe: <S>(id?: string) => Probe<S>;
/**
 * Reference implementation: Constant-score evaluator.
 * Placeholder for testing. Production code should implement domain-specific evaluation logic.
 */
declare class ThresholdEvaluator<S> {
    private threshold;
    constructor(threshold?: number);
    evaluate(_prev: S, _next: S): number;
}
/**
 * Reference implementation: Stagnation-based termination policy.
 * Optional meta-control component for complex stopping criteria.
 * Stops when budget exhausted or improvements stall.
 * Most applications use ControlBudget's built-in termination.
 */
declare class StagnationTerminationPolicy implements TerminationPolicy {
    private opts;
    constructor(opts?: {
        maxStagnantSteps?: number;
        minFeedback?: number;
    });
    shouldStop(input: {
        t: number;
        budgetRemaining: number;
        noImprovementSteps: number;
        lastFeedback?: number;
    }): {
        stop: boolean;
        reason?: string;
    };
}
/**
 * Reference implementation: Rule-based failure classifier.
 * Optional meta-control component for diagnosing complex failure modes.
 * Classifies failures based on probe reasons and metrics (entropy, hit counts, etc.).
 * Most applications handle failures directly in their ProbePolicy.
 */
declare class ReasonFailureClassifier<S, A> implements FailureClassifier<S, A> {
    private opts;
    constructor(opts?: {
        entropyHigh?: number;
        entropyLow?: number;
        sparseHits?: number;
        denseHits?: number;
    });
    classify(input: {
        prev: S;
        next?: S;
        action?: A;
        probeReason?: string;
        metrics?: Record<string, unknown>;
    }): FailureType;
}

interface EntropyProbeOpts {
    id?: string;
    max?: number;
    min?: number;
    cost?: number;
}
/**
 * Rejects states whose entropy suggests over-broad or over-narrow exploration.
 */
declare const EntropyProbe: <S>(getEntropy: (state: S) => number, opts?: EntropyProbeOpts, inspector?: (state: S) => Record<string, unknown>) => Probe<S>;

interface HitCountProbeOpts {
    id?: string;
    min?: number;
    max?: number;
    cost?: number;
}
/**
 * Rejects states whose hit count is zero or outside desired bounds.
 * Useful as a cheap guard before executing wider exploration policies.
 */
declare const HitCountProbe: <S>(getCount: (state: S) => number, opts?: HitCountProbeOpts, inspector?: (state: S) => Record<string, unknown>) => Probe<S>;

interface GitHubSearchItem {
    title: string;
    url: string;
    labels: string[];
    stars: number;
}
interface GitHubSearchResult {
    hits: number;
    entropy: number;
    items: GitHubSearchItem[];
}
interface SearchFilters {
    keywords: string[];
    orKeywords?: string[];
    language?: string;
    minStars?: number;
    maxStars?: number;
    topic?: string;
    inName?: boolean;
    inDescription?: boolean;
}
interface GitHubSearchApi {
    search(query: string | SearchFilters, opts?: {
        perPage?: number;
    }): Promise<GitHubSearchResult>;
}
declare function createGitHubSearchApi(token?: string | undefined): GitHubSearchApi;
declare function createGitHubSearchTool(api: GitHubSearchApi): _openai_agents_core.FunctionTool<unknown, {
    readonly type: "object";
    readonly properties: {
        readonly keywords: {
            readonly type: "array";
            readonly items: {
                readonly type: "string";
            };
            readonly description: "Main search keywords (AND combined). E.g. [\"rust\", \"async\", \"runtime\"]";
        };
        readonly or_keywords: {
            readonly type: "array";
            readonly items: {
                readonly type: "string";
            };
            readonly description: "Alternative keywords (OR combined). E.g. [\"tokio\", \"async-std\"]";
        };
        readonly language: {
            readonly type: "string";
            readonly description: "Filter by programming language. E.g. \"rust\", \"python\", \"javascript\"";
        };
        readonly min_stars: {
            readonly type: "integer";
            readonly description: "Minimum star count";
        };
        readonly max_stars: {
            readonly type: "integer";
            readonly description: "Maximum star count";
        };
        readonly topic: {
            readonly type: "string";
            readonly description: "GitHub topic filter. E.g. \"async\", \"web-framework\"";
        };
        readonly in_name: {
            readonly type: "boolean";
            readonly description: "Search only in repository name";
        };
        readonly in_description: {
            readonly type: "boolean";
            readonly description: "Search only in repository description";
        };
    };
    readonly required: ["keywords"];
    readonly additionalProperties: true;
}, string>;

interface GhState {
    query: string;
    filters: SearchFilters;
    hits: number;
    entropy: number;
    items?: {
        title: string;
        url: string;
        labels?: string[];
        stars?: number;
    }[];
    history?: {
        filters: SearchFilters;
        hits: number;
    }[];
    probes?: {
        id: string;
        pass: boolean;
        reason?: string;
        data?: unknown;
    }[];
}
type GhAction = {
    type: 'broaden';
    payload?: {
        synonyms?: string[];
    };
} | {
    type: 'narrow';
    payload?: {
        exact?: string[];
    };
} | {
    type: 'rephrase';
    payload?: {
        pattern?: string;
    };
};
declare const GitHubSearchEnv: (api: GitHubSearchApi, initialFilters: SearchFilters, options?: {
    initialFetch?: boolean;
    log?: boolean;
}) => Environment<GhState, GhAction>;

declare class AgentRelevanceEvaluator implements Evaluator<GhState, number> {
    evaluate(prev: GhState, next: GhState): Promise<number>;
}

declare class AgentQueryPolicy implements Policy<GhState, GhAction, number> {
    private readonly api;
    readonly id = "agent-query-policy";
    private readonly githubTool;
    constructor(api: GitHubSearchApi);
    capabilities(): {
        explorationRange: [number, number];
        cost: {
            step: number;
        };
        handles: string[];
    };
    decide(state: GhState, ladder: Ladder<number>): Promise<GhAction>;
    adapt(_feedback: number, _ladder: Ladder<number>): void;
}

declare const HitGainEvaluator: {
    evaluate: (prev: {
        hits: number;
    }, next: {
        hits: number;
    }) => number;
};

declare const QueryMutatePolicy: Policy<GhState, GhAction, number>;

declare const hasHitsProbe: Probe<GhState, unknown, ProbeResult<unknown>>;
declare const dropGuardProbe: Probe<GhState>;
declare const entropyGuardProbe: Probe<GhState, unknown, ProbeResult<unknown>>;

declare class SearchFailureSelector implements StrategySelector<GhState, GhAction> {
    private readonly opts;
    constructor(opts?: {
        preferLlm?: boolean;
    });
    select(input: {
        failure: FailureType;
        ladderLevel: number;
        budgetRemaining: number;
        probes: Probe<GhState>[];
        policies: Policy<GhState, GhAction>[];
    }): {
        probe: Probe<GhState>;
        policy: Policy<GhState, GhAction>;
    };
}

declare const logger: Logger;

type index_AgentQueryPolicy = AgentQueryPolicy;
declare const index_AgentQueryPolicy: typeof AgentQueryPolicy;
type index_AgentRelevanceEvaluator = AgentRelevanceEvaluator;
declare const index_AgentRelevanceEvaluator: typeof AgentRelevanceEvaluator;
type index_GhAction = GhAction;
type index_GhState = GhState;
type index_GitHubSearchApi = GitHubSearchApi;
declare const index_GitHubSearchEnv: typeof GitHubSearchEnv;
type index_GitHubSearchItem = GitHubSearchItem;
type index_GitHubSearchResult = GitHubSearchResult;
declare const index_HitGainEvaluator: typeof HitGainEvaluator;
declare const index_QueryMutatePolicy: typeof QueryMutatePolicy;
type index_SearchFailureSelector = SearchFailureSelector;
declare const index_SearchFailureSelector: typeof SearchFailureSelector;
type index_SearchFilters = SearchFilters;
declare const index_createGitHubSearchApi: typeof createGitHubSearchApi;
declare const index_createGitHubSearchTool: typeof createGitHubSearchTool;
declare const index_dropGuardProbe: typeof dropGuardProbe;
declare const index_entropyGuardProbe: typeof entropyGuardProbe;
declare const index_hasHitsProbe: typeof hasHitsProbe;
declare const index_logger: typeof logger;
declare namespace index {
  export { index_AgentQueryPolicy as AgentQueryPolicy, index_AgentRelevanceEvaluator as AgentRelevanceEvaluator, type index_GhAction as GhAction, type index_GhState as GhState, type index_GitHubSearchApi as GitHubSearchApi, index_GitHubSearchEnv as GitHubSearchEnv, type index_GitHubSearchItem as GitHubSearchItem, type index_GitHubSearchResult as GitHubSearchResult, index_HitGainEvaluator as HitGainEvaluator, index_QueryMutatePolicy as QueryMutatePolicy, index_SearchFailureSelector as SearchFailureSelector, type index_SearchFilters as SearchFilters, index_createGitHubSearchApi as createGitHubSearchApi, index_createGitHubSearchTool as createGitHubSearchTool, index_dropGuardProbe as dropGuardProbe, index_entropyGuardProbe as entropyGuardProbe, index_hasHitsProbe as hasHitsProbe, index_logger as logger };
}

export { Action, type AgentLike, type AgentResult, type BudgetTracker, CheapPassProbe, type ControlBudget, Cost, type CyberLoopOpts, DeltaScoreEvaluator, EntropyProbe, type Environment, type Evaluator, type ExplorationResult, type FailureClassifier, FailureType, Feedback, index as GitHub, HitCountProbe, type Ladder, type LocalGeometry, Middleware, MiddlewareRunner, MultiBudget, Orchestrator, type OrchestratorOpts, type OrchestratorResult, type Planner, type Policy, type Probe, type ProbePolicy, ProbeResult, ProportionalLadder, ReasonFailureClassifier, RuleBasedStrategySelector, Signal, SimpleBudgetTracker, type StagnationOpts, StagnationTerminationPolicy, State, StepContext, type StepLog, type StepOutput, StepResult, type SteppableAgent, type StrategySelector, type TerminationPolicy, ThresholdEvaluator, type Trajectory, type TrajectoryFrame, budgetMiddleware, createControlBudget, cyberloop, evaluatorMiddleware, isSteppable, isTrajectory, probeMiddleware, stagnationMiddleware, telemetryMiddleware };