@tangle-network/agent-runtime 0.53.0 → 0.54.0

package/dist/driver-B2RKkVJW.d.ts

@@ -1,221 +0,0 @@
-import { AnalystFinding } from '@tangle-network/agent-eval';
-import { I as Iteration, D as Driver } from './types-CklkW4Eh.js';
-
-/**
- * @experimental
- *
- * Completion / satisfiability — the OTHER output of the pluggable analyst (the steer output
- * is `AnalystFinding[]` via the `analyze` hook; this is the "is it done?" output via the
- * `complete` hook). A `CompletionAnalyst` reads a node's trace and returns a `CompletionVerdict`
- * the PARENT (driver) acts on: end the node, or keep going. It fits ANY node and composes to
- * any depth — a 1-deep loop has one; an N-deep tree has one per node.
- *
- * The verdict's authority scales with its DETERMINISM (the thing that varies by task):
- *   - `deterministic` — build/test/lint pass, a proof checks, every claim's citation resolves:
- *     ground truth, the driver TRUSTS it and ends. Not an opinion.
- *   - `probabilistic` — a quality/soundness judgment (marketing, "the experiment is sound"):
- *     ADVISORY. It passes to the driver with its reasons; the driver validates (here: a
- *     confidence threshold; a richer driver may re-examine the reasons) before ending.
- *
- * Two stop-signal mechanisms, by node mode, both → one `CompletionVerdict`:
- *   - sandbox-agent (text stream): a unique per-node STOP SENTINEL the agent emits when done
- *     (`stopSentinel` / `sentinelCompletion`) — ralph-loop style; the seed makes it
- *     unguessable + attributable, so it can't be spuriously emitted or confused with content.
- *   - deterministic check (compile/test/citation/proof): `deterministicCompletion(check)` —
- *     a verifier over the output, never the judge verdict (selector ≠ judge holds).
- */
-
-/** Trace-derived evidence for a completion claim — an artifact (output) or a verifier metric,
- *  never the judge's own verdict. Mirrors the steer-firewall's provenance discipline. */
-interface CompletionEvidence {
-    kind: 'artifact' | 'metric';
-    uri: string;
-}
-/** The "is it done?" verdict an analyst returns to the parent. */
-interface CompletionVerdict {
-    done: boolean;
-    /** How verifiable the claim is — sets whether the driver trusts it or validates it. */
-    determinism: 'deterministic' | 'probabilistic';
-    /** Why the analyst believes it is (or isn't) done — what the driver validates. */
-    reasons?: string;
-    /** 0..1, for probabilistic verdicts; the driver's validation threshold reads this. */
-    confidence?: number;
-    evidence?: ReadonlyArray<CompletionEvidence>;
-}
-/** Reads a node's trace → a completion verdict. Same input shape as the `analyze` hook, so
- *  ONE analyst node can back both channels (findings for steer, a verdict for stop). */
-interface CompletionAnalyst<Task, Output> {
-    assess(input: {
-        task: Task;
-        history: ReadonlyArray<Iteration<Task, Output>>;
-    }): CompletionVerdict | Promise<CompletionVerdict>;
-}
-/** When a verdict authorizes the driver to END. Deterministic → trust (ground truth);
- *  probabilistic → validate by confidence threshold (the driver's check). */
-interface CompletionPolicy {
-    /** Minimum confidence a PROBABILISTIC verdict must clear to end. Default 0.8. */
-    minConfidence?: number;
-}
-declare function completionAuthorizes(v: CompletionVerdict, policy?: CompletionPolicy): boolean;
-/**
- * A unique, attributable stop sentinel for a node (ralph-loop style). Deterministic from the
- * seed (no Math.random — reproducible + attributable to the node); the agent is instructed to
- * emit it VERBATIM when it judges itself done. Unguessable enough that content never trips it.
- */
-declare function stopSentinel(seed: string): string;
-/**
- * Completion for a sandbox-agent node: done iff the latest output carries the node's stop
- * sentinel. PROBABILISTIC (the agent's own self-judgment) — the driver validates it.
- */
-declare function sentinelCompletion<Task>(sentinel: string, opts?: {
-    confidence?: number;
-}): CompletionAnalyst<Task, string>;
-/**
- * Completion for a DETERMINISTIC check (build/test/lint/citation/proof): done iff the check
- * passes. Ground truth — the driver ends directly, no validation. The check reads the output
- * (a verifier), never the judge verdict — selector ≠ judge stays intact.
- */
-declare function deterministicCompletion<Task, Output>(check: (output: Output, history: ReadonlyArray<Iteration<Task, Output>>) => {
-    passed: boolean;
-    reasons?: string;
-}): CompletionAnalyst<Task, Output>;
-
-/**
- * @experimental
- *
- * Dynamic driver — the agent authors the loop topology at runtime.
- *
- * Where a fixed-shape driver encodes one topology as a pure function of
- * history, this driver delegates the per-round shape to an injected
- * `TopologyPlanner`. Each round the planner inspects the task + iteration
- * history and emits one `TopologyMove`:
- *   - `refine` → one task next round (optionally rewritten from the prior attempt)
- *   - `fanout` → N tasks next round (the kernel round-robins `agentRuns`, so a
- *     2-harness fanout dispatches branch 0 to harness A and branch 1 to harness B)
- *   - `stop`   → terminate; the kernel selects the winner across all iterations
- *
- * The planner is the brain; this driver is the structure. It maps moves onto
- * the kernel's `plan`/`decide` contract, enforces the iteration + fanout caps,
- * and fails loud on a malformed move. The planner is injected — so a test can
- * drive a deterministic policy through the real kernel, and production can wire
- * it to an LLM-backed, agent-authored planner.
- *
- * Topology is orthogonal to harness: the planner never names a backend. Which
- * harness runs a branch is decided by the `AgentRunSpec` the kernel round-robins
- * to, so one dynamic driver works across claude-code, codex, opencode, pi —
- * including fanning a single round across several at once.
- */
-
-/** Terminal once `decide` returns `'done'` (a kernel terminal decision). */
-type DriverDecision = 'continue' | 'done';
-/**
- * One topology decision for the next round. `fanout` carries explicit tasks
- * rather than a count so the planner can issue heterogeneous branches (a
- * different sub-task per harness); pass N copies of one task for a homogeneous
- * fanout that relies on `agentRuns` diversity instead.
- *
- * @experimental
- */
-type TopologyMove<Task> = {
-    kind: 'refine';
-    task: Task;
-    rationale?: string;
-    parentIndex?: number;
-} | {
-    kind: 'fanout';
-    tasks: Task[];
-    rationale?: string;
-    parentIndex?: number;
-} | {
-    kind: 'stop';
-    rationale?: string;
-} | {
-    kind: 'select';
-    index: number;
-    rationale?: string;
-};
-/** @experimental */
-interface PlannerContext<Task, Output> {
-    /** The root task the loop was invoked with — stable across rounds. */
-    task: Task;
-    /** Every iteration so far, in dispatch order, with outputs + verdicts. */
-    history: ReadonlyArray<Iteration<Task, Output>>;
-    /** `history.length` — iterations already spent. */
-    iterationsSpent: number;
-    /** Iterations left before the driver's `maxIterations` cap forces a stop. */
-    iterationsRemaining: number;
-    /**
-     * Trace-analyst findings about the attempts so far — populated only when an
-     * `analyze` hook is wired into the driver (see CreateDriverOptions).
-     * This is the channel that lets the planner steer from the DIAGNOSIS
-     * (`f(trace, findings)`), not the verdict score alone. Undefined = no analyst
-     * wired (the planner runs exactly as before). @experimental
-     */
-    analyses?: ReadonlyArray<AnalystFinding>;
-}
-/**
- * Chooses the next topology move from the task + history. Sync or async; an
- * async planner is where an LLM call goes (an agent-authored topology planner).
- *
- * @experimental
- */
-type TopologyPlanner<Task, Output> = (ctx: PlannerContext<Task, Output>) => TopologyMove<Task> | Promise<TopologyMove<Task>>;
-/**
- * Input to the optional `analyze` hook: the root task + the trace so far. The
- * hook turns this into `AnalystFinding[]` — the caller's seam to `runAnalystLoop`.
- * @experimental
- */
-interface AnalyzeInput<Task, Output> {
-    task: Task;
-    history: ReadonlyArray<Iteration<Task, Output>>;
-}
-/** @experimental */
-interface CreateDriverOptions<Task, Output> {
-    /** The agent-authored topology policy. Invoked once per round in `plan`. */
-    planner: TopologyPlanner<Task, Output>;
-    /**
-     * Optional trace-analyst hook. When set, the driver calls it each round AFTER
-     * the first (a trace must exist) and BEFORE the planner, then passes the
-     * findings to the planner via `PlannerContext.analyses` — so the planner
-     * decides from the diagnosis, not the verdict score alone. This is the seam to
-     * `runAnalystLoop`; it lives on the driver so `run-loop` stays analyst-free
-     * (the layering rule). Fail-loud: a throwing or non-array hook aborts the round
-     * (no silent empty findings).
-     */
-    analyze?: (input: AnalyzeInput<Task, Output>) => ReadonlyArray<AnalystFinding> | Promise<ReadonlyArray<AnalystFinding>>;
-    /**
-     * Optional completion analyst — the DEPLOYABLE, non-oracle stop. Each round (after a
-     * trace exists) the driver asks "is it done?"; if the verdict AUTHORIZES ending
-     * (deterministic = trust ground truth; probabilistic = clears `completionPolicy`'s
-     * confidence), the driver stops BEFORE consulting the planner. This is the satisfiability
-     * primitive — usable at 1 deep, composing to any depth (one per node). Fail-loud: a
-     * throwing or non-verdict assess aborts the round. Distinct from `analyze` (the steer
-     * channel) though one analyst node may back both.
-     */
-    complete?: CompletionAnalyst<Task, Output>;
-    /** Validation policy for a probabilistic completion verdict (the driver's check). */
-    completionPolicy?: CompletionPolicy;
-    /**
-     * Hard safety cap on total iterations. When reached, the driver stops before
-     * consulting the planner. Default 8. Set the kernel's `runLoop`
-     * `maxIterations >= ` this so the driver's cap governs and the loop closes on
-     * a clean `'done'` rather than a truncated `'continue'`.
-     */
-    maxIterations?: number;
-    /** Max branches a single `fanout` move may dispatch. Default 4. */
-    maxFanout?: number;
-    /** Stable identifier surfaced in trace events. Default `'dynamic'`. */
-    name?: string;
-}
-/** @experimental */
-declare function createDriver<Task, Output>(options: CreateDriverOptions<Task, Output>): Driver<Task, Output, DriverDecision>;
-/**
- * Compact, planner-facing rendering of trace-analyst findings — the diagnosis the
- * planner steers from. Empty input renders to '' (callers omit the section). Shows
- * severity·area·claim·recommended_action·confidence; raw evidence_refs/metadata are
- * for renderers that know the analyst, not the topology decision.
- * @experimental
- */
-declare function renderAnalyses(findings: ReadonlyArray<AnalystFinding>): string;
-
-export { type AnalyzeInput as A, type CreateDriverOptions as C, type DriverDecision as D, type PlannerContext as P, type TopologyPlanner as T, type CompletionAnalyst as a, type CompletionEvidence as b, type CompletionPolicy as c, type CompletionVerdict as d, type TopologyMove as e, completionAuthorizes as f, createDriver as g, deterministicCompletion as h, stopSentinel as i, renderAnalyses as r, sentinelCompletion as s };