@tangle-network/agent-eval 0.129.0 → 0.130.0

package/dist/control.d.ts

@@ -1,1030 +1,3 @@
-type RunStatus = 'running' | 'completed' | 'failed' | 'aborted';
-interface BudgetSpec {
-    tokens?: number;
-    wallMs?: number;
-    calls?: number;
-    usd?: number;
-}
-interface RunOutcome$1 {
-    score?: number;
-    pass?: boolean;
-    failureClass?: FailureClass;
-    notes?: string;
-}
-/**
- * Layer — optional classification in a nested build workflow.
- * `builder`: the meta-agent editing a project (e.g. agent-builder Forge chat).
- * `app-build`: sandbox harness that compiled + tested the generated scaffold.
- * `app-runtime`: a run of the generated agent against a domain scenario.
- * `meta`: any meta-eval (judge replay, correlation analysis).
- */
-type RunLayer = 'builder' | 'app-build' | 'app-runtime' | 'meta' | 'custom';
-interface Run {
-    runId: string;
-    /**
-     * Stable identifier of the scenario being executed.
-     *
-     * Always populated on the persisted Run — but `TraceEmitter.startRun` accepts
-     * input WITHOUT this field, substituting a sensible default
-     * (`run.layer ?? run.tags?.['kind'] ?? 'runtime'`) when the caller has no
-     * curated scenario to anchor to (runtime / operator / meta-eval runs). This
-     * keeps the persisted shape unambiguous for downstream filters + aggregations
-     * while removing the boilerplate of inventing placeholder ids at the call site.
-     */
-    scenarioId: string;
-    variantId?: string;
-    datasetVersion?: string;
-    /** Git SHA of agent code at run time. */
-    codeSha?: string;
-    /** Hash of the prompt template + any system prompt. */
-    promptSha?: string;
-    /** Model id + date + system-prompt hash, concatenated. */
-    modelFingerprint?: string;
-    seed?: number;
-    /** Arbitrary environment markers (shell, docker version, tz). */
-    envFingerprint?: Record<string, string>;
-    /** Version of the redaction rules applied to this run. */
-    redactionVersion?: string;
-    /** Parent run in a nested build workflow. A builder run's children are
-     *  app-build runs; those children are app-runtime runs. */
-    parentRunId?: string;
-    /** Stable project identifier — groups runs across chats + sessions. */
-    projectId?: string;
-    /** Chat/conversation identifier within a project. */
-    chatId?: string;
-    /** Layer classification — hint for aggregation; not enforced. */
-    layer?: RunLayer;
-    startedAt: number;
-    endedAt?: number;
-    status: RunStatus;
-    outcome?: RunOutcome$1;
-    budget?: BudgetSpec;
-    /** Free-form labels for downstream grouping. */
-    tags?: Record<string, string>;
-}
-type SpanKind = 'agent' | 'llm' | 'tool' | 'retrieval' | 'judge' | 'sandbox' | 'custom';
-type SpanStatus = 'ok' | 'error';
-interface SpanBase {
-    spanId: string;
-    parentSpanId?: string;
-    runId: string;
-    kind: SpanKind;
-    name: string;
-    startedAt: number;
-    endedAt?: number;
-    status?: SpanStatus;
-    error?: string;
-    /** Anything not covered by typed fields. Kept deliberately free-form. */
-    attributes?: Record<string, unknown>;
-}
-interface Message {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string;
-    tokens?: number;
-    /** Multi-modal content descriptors; blobs themselves live in Artifacts. */
-    images?: Array<{
-        artifactId?: string;
-        url?: string;
-        mime?: string;
-    }>;
-}
-interface LlmSpan extends SpanBase {
-    kind: 'llm';
-    model: string;
-    messages: Message[];
-    output?: string;
-    inputTokens?: number;
-    /** All generated tokens, including the reasoning subset when present. */
-    outputTokens?: number;
-    cachedTokens?: number;
-    cacheWriteTokens?: number;
-    /** Reasoning-token subset of `outputTokens`. */
-    reasoningTokens?: number;
-    costUsd?: number;
-    finishReason?: string;
-}
-interface ToolSpan extends SpanBase {
-    kind: 'tool';
-    toolName: string;
-    args: unknown;
-    /** False when the source observed the call but did not capture its arguments. */
-    argsCaptured?: boolean;
-    result?: unknown;
-    latencyMs?: number;
-}
-interface RetrievalSpan extends SpanBase {
-    kind: 'retrieval';
-    query: string;
-    hits: Array<{
-        docId: string;
-        score: number;
-        content?: string;
-    }>;
-}
-interface JudgeSpan extends SpanBase {
-    kind: 'judge';
-    judgeId: string;
-    /** Span this judgment applies to. */
-    targetSpanId: string;
-    dimension: string;
-    /** Numeric score (free-range; interpretation up to the judge). */
-    score: number;
-    rationale?: string;
-    evidence?: string;
-}
-interface SandboxSpan extends SpanBase {
-    kind: 'sandbox';
-    image?: string;
-    command?: string;
-    exitCode?: number;
-    testsTotal?: number;
-    testsPassed?: number;
-    stdoutHash?: string;
-    stderrHash?: string;
-    /** Duration in ms; the harness fills this explicitly (endedAt - startedAt may miss setup). */
-    wallMs?: number;
-}
-interface GenericSpan extends SpanBase {
-    kind: 'agent' | 'custom';
-}
-type Span = LlmSpan | ToolSpan | RetrievalSpan | JudgeSpan | SandboxSpan | GenericSpan;
-type EventKind = 'log' | 'error' | 'budget_decrement' | 'budget_breach' | 'state_mutation' | 'policy_violation' | 'redaction_applied' | 'custom';
-interface TraceEvent {
-    eventId: string;
-    runId: string;
-    spanId?: string;
-    kind: EventKind;
-    timestamp: number;
-    payload: Record<string, unknown>;
-}
-interface BudgetLedgerEntry {
-    runId: string;
-    dimension: keyof BudgetSpec;
-    limit: number;
-    consumed: number;
-    remaining: number;
-    timestamp: number;
-    breached: boolean;
-    /** Span that triggered this entry, if any. */
-    spanId?: string;
-}
-interface Artifact {
-    artifactId: string;
-    runId: string;
-    spanId?: string;
-    contentType: string;
-    sizeBytes: number;
-    /** sha256 in hex. */
-    hash: string;
-    /** External storage URL (R2, S3, filesystem path). */
-    storageUrl?: string;
-    /** Inline content for small blobs — keep under ~64KB. */
-    inlineContent?: string;
-}
-type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'tool_argument_error' | 'tool_recovery_failure' | 'hallucination' | 'instruction_following' | 'safety_refusal_miss' | 'policy_violation' | 'budget_exceeded' | 'format_drift' | 'permission_escalation' | 'pii_leak' | 'cost_overrun' | 'timeout' | 'sandbox_failure' | 'missing_user_data' | 'missing_domain_data' | 'missing_codebase_context' | 'missing_runtime_context' | 'missing_credentials' | 'missing_integration_connection' | 'missing_integration_scope' | 'integration_approval_required' | 'integration_auth_expired' | 'integration_provider_failure' | 'bad_integration_manifest' | 'unsafe_integration_write_denied' | 'stale_external_data' | 'bad_retrieval' | 'insufficient_evidence' | 'contradictory_evidence' | 'ambiguous_user_intent' | 'knowledge_readiness_blocked' | 'unknown';
-
-interface RunFilter {
-    scenarioId?: string;
-    variantId?: string;
-    status?: RunStatus;
-    since?: number;
-    until?: number;
-    tag?: {
-        key: string;
-        value: string;
-    };
-    parentRunId?: string;
-    projectId?: string;
-    chatId?: string;
-    layer?: RunLayer;
-}
-interface SpanFilter {
-    runId?: string;
-    parentSpanId?: string;
-    kind?: SpanKind;
-    name?: string;
-    toolName?: string;
-    judgeId?: string;
-    since?: number;
-    until?: number;
-}
-interface EventFilter {
-    runId?: string;
-    spanId?: string;
-    kind?: EventKind;
-    since?: number;
-    until?: number;
-}
-interface TraceStore {
-    appendRun(run: Run): Promise<void>;
-    updateRun(runId: string, patch: Partial<Run>): Promise<void>;
-    appendSpan(span: Span): Promise<void>;
-    updateSpan(spanId: string, patch: Partial<Span>): Promise<void>;
-    appendEvent(event: TraceEvent): Promise<void>;
-    appendArtifact(artifact: Artifact): Promise<void>;
-    appendBudgetEntry(entry: BudgetLedgerEntry): Promise<void>;
-    getRun(runId: string): Promise<Run | undefined>;
-    listRuns(filter?: RunFilter): Promise<Run[]>;
-    spans(filter?: SpanFilter): Promise<Span[]>;
-    events(filter?: EventFilter): Promise<TraceEvent[]>;
-    budget(runId: string): Promise<BudgetLedgerEntry[]>;
-    artifacts(runId: string): Promise<Artifact[]>;
-}
-
-/**
- * TraceEmitter — hierarchical span builder that auto-parents using an
- * internal stack. One emitter per Run; emitters do NOT share state.
- *
- * Convenience methods (`llm`, `tool`, `retrieval`, `judge`, `sandbox`)
- * return a `SpanHandle` with `.end()` / `.fail()` so callers don't
- * have to thread spanIds manually. For async workflows that can't use
- * the stack (e.g. fan-out parallel calls), pass `parentSpanId`
- * explicitly.
- */
-
-interface SpanHandle<S extends Span = Span> {
-    span: S;
-    end(patch?: Partial<S>): Promise<void>;
-    fail(error: string | Error, patch?: Partial<S>): Promise<void>;
-}
-interface RunCompleteHookContext {
-    runId: string;
-    emitter: TraceEmitter;
-    store: TraceStore;
-    /** Outcome the caller passed to `endRun` (undefined for `abortRun`). */
-    outcome?: RunOutcome$1;
-    /** Final run status. */
-    status: 'completed' | 'failed' | 'aborted';
-}
-type RunCompleteHook = (ctx: RunCompleteHookContext) => Promise<void> | void;
-interface TraceEmitterOptions {
-    runId?: string;
-    /** Inject a clock for deterministic tests. */
-    now?: () => number;
-    /** Inject an id generator for deterministic tests. */
-    id?: () => string;
-    /**
-     * Hooks fired after `endRun` / `abortRun` writes the final run state.
-     * Designed for trace-analyst auto-execution, integrity assertions, and
-     * outbound notifications. Hooks run sequentially in the order supplied.
-     *
-     * By default a hook that throws is swallowed and logged as a `note` event
-     * on the run — auto-orchestration must not crash the underlying flow.
-     * Set `hookErrors: 'throw'` to propagate.
-     */
-    onRunComplete?: RunCompleteHook[];
-    /** `'swallow'` (default) | `'throw'`. */
-    hookErrors?: 'swallow' | 'throw';
-}
-declare class TraceEmitter {
-    private store;
-    private stack;
-    private _runId;
-    private now;
-    private id;
-    private hooks;
-    private hookErrors;
-    constructor(store: TraceStore, options?: TraceEmitterOptions);
-    get runId(): string;
-    get traceStore(): TraceStore;
-    /** Append a hook after construction (e.g. attach the trace analyst). */
-    addRunCompleteHook(hook: RunCompleteHook): void;
-    /**
-     * Begin a Run.
-     *
-     * `scenarioId` is required on the persisted Run shape — every Run downstream
-     * gets a non-empty scenarioId so filters and aggregations stay simple — but
-     * the INPUT here accepts it as optional. When omitted, startRun substitutes
-     * a sensible default (`run.layer ?? run.tags?.['kind'] ?? 'runtime'`) so
-     * runtime / operator / meta-eval runs that have no curated-scenario corpus
-     * to anchor to don't have to invent placeholder strings at the call site.
-     */
-    startRun(run: Omit<Run, 'runId' | 'scenarioId' | 'startedAt' | 'status'> & {
-        scenarioId?: string;
-    }): Promise<Run>;
-    endRun(outcome?: RunOutcome$1): Promise<void>;
-    abortRun(reason: string): Promise<void>;
-    private runHooks;
-    span<S extends Span = Span>(init: {
-        kind: SpanKind;
-        name: string;
-        parentSpanId?: string;
-        attributes?: Record<string, unknown>;
-    } & Partial<Omit<S, 'spanId' | 'runId' | 'startedAt' | 'kind' | 'name'>>): Promise<SpanHandle<S>>;
-    private handle;
-    private pop;
-    llm(init: Omit<LlmSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<LlmSpan>>;
-    tool(init: Omit<ToolSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<ToolSpan>>;
-    retrieval(init: Omit<RetrievalSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<RetrievalSpan>>;
-    recordJudge(verdict: Omit<JudgeSpan, 'spanId' | 'runId' | 'kind' | 'startedAt' | 'endedAt'>): Promise<JudgeSpan>;
-    sandbox(init: Omit<SandboxSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<SandboxSpan>>;
-    emit(event: {
-        kind: EventKind;
-        spanId?: string;
-        payload?: Record<string, unknown>;
-    }): Promise<TraceEvent>;
-    recordBudget(entry: Omit<BudgetLedgerEntry, 'runId' | 'timestamp'> & {
-        timestamp?: number;
-    }): Promise<BudgetLedgerEntry>;
-    recordArtifact(artifact: Omit<Artifact, 'artifactId' | 'runId'>): Promise<Artifact>;
-    /**
-     * Runs `fn` inside a span; auto-ends on success, auto-fails on throw.
-     * Returns the fn's return value. Use this for the 95% case.
-     */
-    within<T>(init: Parameters<TraceEmitter['span']>[0], fn: (handle: SpanHandle) => Promise<T>): Promise<T>;
-}
-
-/**
- * Policy-based agent control runtime.
- *
- * This is the minimal reusable loop behind driver-agent patterns:
- *
- *   observe state -> validate -> decide next action -> act -> observe -> ...
- *
- * It deliberately does not model named "topologies". Direct execution,
- * critic/revise, driver intervention, specialist calls, and human escalation
- * are all just actions chosen by the control policy.
- */
-
-type ControlSeverity = 'info' | 'warning' | 'error' | 'critical';
-type ControlActionFailureMode = 'continue' | 'stop';
-interface ControlEvalResult {
-    /** Stable validator or judge id. */
-    id: string;
-    /** Whether this check passed. */
-    passed: boolean;
-    /** Optional normalized score. 1 = best, 0 = worst. */
-    score?: number;
-    /** Objective validators should usually be "error" or "critical" when failed. */
-    severity?: ControlSeverity;
-    /** Human-readable result. */
-    detail?: string;
-    /** Small evidence string or pointer. Avoid large payloads. */
-    evidence?: string;
-    /** True when the result came from deterministic state, not LLM judgment. */
-    objective?: boolean;
-    /** Structured details for downstream control policies and reports. */
-    metadata?: Record<string, unknown>;
-}
-interface ControlBudget {
-    maxSteps: number;
-    maxWallMs?: number;
-    maxCostUsd?: number;
-}
-interface ControlStopPolicies<TState, TAction> {
-    /**
-     * Stop after N consecutive steps with no state fingerprint change and
-     * less than `minScoreDelta` score movement. Disabled when omitted.
-     */
-    maxNoProgressSteps?: number;
-    /**
-     * Stop after the same action fingerprint is selected N consecutive
-     * times. Disabled when omitted.
-     */
-    maxRepeatedActions?: number;
-    /** Minimum score movement that counts as progress. Default 0.001. */
-    minScoreDelta?: number;
-    /** Override the default JSON/string fingerprint for state comparisons. */
-    stateFingerprint?: (state: TState) => string;
-    /** Override the default JSON/string fingerprint for repeated-action checks. */
-    actionFingerprint?: (action: TAction) => string;
-}
-interface ControlContext<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
-    intent: string;
-    state: TState;
-    evals: TEval[];
-    history: ControlStep<TState, TAction, TActionResult, TEval>[];
-    budget: ControlBudget;
-    stepIndex: number;
-    wallMs: number;
-    spentCostUsd: number;
-    remainingCostUsd?: number;
-    abortSignal: AbortSignal;
-    emitter?: TraceEmitter;
-}
-type ControlDecision<TAction> = {
-    type: 'continue';
-    action: TAction;
-    reason?: string;
-} | {
-    type: 'stop';
-    reason: string;
-    pass?: boolean;
-    score?: number;
-    /** Canonical task-failure class when this stop represents a failed task. */
-    failureClass?: FailureClass;
-};
-interface StopDecision {
-    stop: boolean;
-    pass: boolean;
-    reason: string;
-    score?: number;
-    failureClass?: FailureClass;
-}
-interface ControlActionOutcome<TActionResult> {
-    ok: boolean;
-    result?: TActionResult;
-    error?: string;
-    costUsd?: number;
-    durationMs: number;
-}
-interface ControlRuntimeError {
-    phase: 'observe' | 'validate' | 'decide' | 'act' | 'stop-policy' | 'on-step' | 'trace';
-    stepIndex: number;
-    message: string;
-}
-interface ControlStep<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
-    index: number;
-    decision: ControlDecision<TAction>;
-    beforeState: TState;
-    afterState: TState;
-    evalsBefore: TEval[];
-    evalsAfter: TEval[];
-    actionOutcome?: ControlActionOutcome<TActionResult>;
-    startedAt: string;
-    endedAt: string;
-}
-interface ControlRunResult<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
-    intent: string;
-    pass: boolean;
-    completed: boolean;
-    reason: string;
-    score?: number;
-    steps: ControlStep<TState, TAction, TActionResult, TEval>[];
-    finalState: TState | undefined;
-    finalEvals: TEval[];
-    wallMs: number;
-    spentCostUsd: number;
-    /** null when the run executed without a TraceEmitter wired (no run record was persisted). */
-    runId: string | null;
-    failureClass?: FailureClass;
-    runtimeErrors: ControlRuntimeError[];
-    stoppedBy: 'policy' | 'stop-policy' | 'budget' | 'abort' | 'runtime-error';
-}
-interface ControlRuntimeConfig<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
-    intent: string;
-    budget?: Partial<ControlBudget>;
-    signal?: AbortSignal;
-    /** Defaults to `continue`: action failures are recorded, then the policy gets another chance. */
-    actionFailure?: ControlActionFailureMode;
-    /**
-     * Extract cost from an action result. Used for `maxCostUsd` budget
-     * enforcement and trace budget ledger emission.
-     */
-    getActionCostUsd?: (ctx: {
-        action: TAction;
-        result: TActionResult;
-        state: TState;
-        evals: TEval[];
-        history: ControlStep<TState, TAction, TActionResult, TEval>[];
-    }) => number | undefined;
-    /** Read typed task/product state. Prefer structured state over transcript-only context. */
-    observe: (ctx: {
-        history: ControlStep<TState, TAction, TActionResult, TEval>[];
-        abortSignal: AbortSignal;
-    }) => Promise<TState> | TState;
-    /** Objective validators first, subjective judges only where objective state is insufficient. */
-    validate: (ctx: {
-        intent: string;
-        state: TState;
-        history: ControlStep<TState, TAction, TActionResult, TEval>[];
-        abortSignal: AbortSignal;
-    }) => Promise<TEval[]> | TEval[];
-    /** Choose the next control action. Can call a worker, ask user, run critic, inspect state, or stop. */
-    decide: (ctx: ControlContext<TState, TAction, TActionResult, TEval>) => Promise<ControlDecision<TAction>> | ControlDecision<TAction>;
-    /** Execute the action selected by the policy. */
-    act: (action: TAction, ctx: ControlContext<TState, TAction, TActionResult, TEval>) => Promise<TActionResult> | TActionResult;
-    /** Final stopping policy. Called before decide and after each action. */
-    shouldStop?: (ctx: ControlContext<TState, TAction, TActionResult, TEval>) => Promise<StopDecision> | StopDecision;
-    /** Optional hook for tracing or live progress updates. */
-    onStep?: (step: ControlStep<TState, TAction, TActionResult, TEval>) => Promise<void> | void;
-    /** Optional generic stuck-loop policies. Custom `shouldStop` still runs first. */
-    stopPolicies?: ControlStopPolicies<TState, TAction>;
-    /** Optional trace sink. Emits one run plus one span per control step. */
-    store?: TraceStore;
-    scenarioId?: string;
-    projectId?: string;
-    variantId?: string;
-}
-declare function runAgentControlLoop<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(config: ControlRuntimeConfig<TState, TAction, TActionResult, TEval>): Promise<ControlRunResult<TState, TAction, TActionResult, TEval>>;
-declare function stopOnNoProgress<TState, TAction>(maxNoProgressSteps: number, options?: Omit<ControlStopPolicies<TState, TAction>, 'maxNoProgressSteps'>): ControlStopPolicies<TState, TAction>;
-declare function stopOnRepeatedAction<TState, TAction>(maxRepeatedActions: number, options?: Omit<ControlStopPolicies<TState, TAction>, 'maxRepeatedActions'>): ControlStopPolicies<TState, TAction>;
-declare function objectiveEval(input: Omit<ControlEvalResult, 'objective'>): ControlEvalResult;
-declare function subjectiveEval(input: Omit<ControlEvalResult, 'objective'>): ControlEvalResult;
-declare function allCriticalPassed(evals: ControlEvalResult[]): boolean;
-
-type FeedbackLabelSource = 'user' | 'judge' | 'environment' | 'metric' | 'policy' | 'system';
-type FeedbackLabelKind = 'approve' | 'reject' | 'select' | 'edit' | 'rank' | 'rate' | 'comment' | 'metric_outcome' | 'policy_block' | 'revision_request';
-type FeedbackSeverity = 'info' | 'warning' | 'error' | 'critical';
-interface ProposedSideEffect {
-    type: string;
-    risk?: 'low' | 'medium' | 'high';
-    costUsd?: number;
-    externalSideEffect?: boolean;
-    requiresApproval?: boolean;
-    metadata?: Record<string, unknown>;
-}
-interface FeedbackLabel {
-    id?: string;
-    source: FeedbackLabelSource;
-    kind: FeedbackLabelKind;
-    value: unknown;
-    reason?: string;
-    severity?: FeedbackSeverity;
-    createdAt: string;
-    metadata?: Record<string, unknown>;
-}
-
-interface ActionExecutionPolicy {
-    allowedTypes?: string[];
-    blockedTypes?: string[];
-    alwaysRequireApprovalTypes?: string[];
-    autoApproveTypes?: string[];
-    requireApprovalForExternalSideEffects?: boolean;
-    requireApprovalAboveCostUsd?: number;
-    maxActionCostUsd?: number;
-    remainingBudgetUsd?: number;
-    expectedOutcomeRequired?: boolean;
-    killCriteriaRequired?: boolean;
-}
-interface ActionPolicyDecision {
-    allowed: boolean;
-    blocked: boolean;
-    requiresApproval: boolean;
-    reasons: string[];
-    label?: FeedbackLabel;
-}
-declare function evaluateActionPolicy(action: ProposedSideEffect, policy?: ActionExecutionPolicy, options?: {
-    createdAt?: string;
-}): ActionPolicyDecision;
-
-/**
- * Propose / Verify / Review — the core multi-shot primitive.
- *
- *   shot N:  propose(state, priorReview) → new state
- *            verify(state)               → pass/fail, optional layers
- *            review(state, verification, memory) → observations + next-shot
- *                                                   instruction + shouldContinue
- *            memory.append(entry)
- *
- * Roles are strictly separated:
- *
- *   - The WORKER is whatever the caller wraps in `propose`. It is
- *     stateful — caller owns its resume/session mechanism.
- *   - The VERIFIER grades the state. It produces the ground truth.
- *     The reviewer cannot overturn or downgrade a verification layer.
- *   - The REVIEWER is stateless per call. Its continuity is the
- *     `ReviewMemoryStore` — durable JSONL by default, or any store
- *     implementing the interface. It reads memory + trace summary +
- *     verification and directs the NEXT proposer shot.
- *
- * This shape is load-bearing. The reviewer never grades; the verifier
- * never directs. Two processes, two prompts, two concerns — which is
- * what keeps the loop from confirmation-biasing itself into "all
- * passed" when it didn't.
- *
- * Short-circuits and soft-fails are both first-class:
- *   - verify.pass === true  → reviewer LLM call is skipped, memory
- *     records a success entry, loop exits.
- *   - review throws         → the shot still counts; the loop uses the
- *     last-known instruction (or `fallbackInstruction`) for the next
- *     propose call. A transient reviewer failure must NEVER abort a
- *     valid arc.
- *
- * Composable: `propose` itself can be another `runProposeReview` call.
- * That's the dogfooding path — a harness built on this primitive is in
- * turn evaluable by it.
- */
-
-interface Verification {
-    pass: boolean;
-    score?: number;
-    failingLayers?: string[];
-    details?: unknown;
-}
-interface Review {
-    observations: string;
-    diagnosis: string;
-    nextShotInstruction: string;
-    shouldContinue: boolean;
-    confidence: number;
-}
-interface ReviewMemoryEntry extends Review {
-    shot: number;
-    timestamp: number;
-    verification: {
-        pass: boolean;
-        score?: number;
-        failingLayers?: string[];
-    };
-}
-interface ProposeInput<State> {
-    shot: number;
-    goal: string;
-    state: State;
-    priorReview: Review | null;
-    abortSignal: AbortSignal;
-    emitter?: TraceEmitter;
-}
-interface ProposeOutput<State, Summary = unknown> {
-    state: State;
-    traceSummary?: Summary;
-}
-interface ReviewInput<State, Summary = unknown> {
-    shot: number;
-    goal: string;
-    state: State;
-    verification: Verification;
-    traceSummary: Summary | undefined;
-    memory: ReviewMemoryEntry[];
-}
-type ProposeFn<State, Summary = unknown> = (input: ProposeInput<State>) => Promise<ProposeOutput<State, Summary>>;
-type VerifyFn<State> = (state: State) => Promise<Verification>;
-type ReviewFn<State, Summary = unknown> = (input: ReviewInput<State, Summary>) => Promise<Review>;
-interface ReviewMemoryStore {
-    load(): Promise<ReviewMemoryEntry[]>;
-    append(entry: ReviewMemoryEntry): Promise<void>;
-}
-interface ProposeReviewConfig<State, Summary = unknown> {
-    goal: string;
-    initialState: State;
-    propose: ProposeFn<State, Summary>;
-    verify: VerifyFn<State>;
-    review: ReviewFn<State, Summary>;
-    /** Hard shot cap. Default 10. */
-    maxShots?: number;
-    /** Wall-clock cap in ms. Default 10 min. */
-    maxWallMs?: number;
-    /**
-     * If the reviewer returns confidence ≤ floor on `confidenceFloorWindow`
-     * consecutive shots, terminate early. Default floor 0.3, window 2.
-     * Set window to 0 or floor to <0 to disable.
-     */
-    confidenceFloor?: number;
-    confidenceFloorWindow?: number;
-    /** Defaults to an in-memory store if omitted. */
-    memory?: ReviewMemoryStore;
-    /** If provided, emit a Run + per-shot spans. */
-    store?: TraceStore;
-    scenarioId?: string;
-    projectId?: string;
-    variantId?: string;
-    /**
-     * Used when the reviewer soft-fails on shot 1 (no prior instruction to
-     * fall back to). Default is a generic "inspect failures and fix".
-     */
-    fallbackInstruction?: string;
-}
-interface ProposeReviewShot<State, Summary = unknown> {
-    shot: number;
-    state: State;
-    verification: Verification;
-    traceSummary: Summary | undefined;
-    review: Review;
-    reviewAvailable: boolean;
-    reviewError?: string;
-    durationMs: number;
-}
-interface ProposeReviewReport<State, Summary = unknown> {
-    runId: string | null;
-    completed: boolean;
-    shots: ProposeReviewShot<State, Summary>[];
-    finalState: State;
-    finalVerification: Verification;
-    failureClass?: FailureClass;
-    wallMs: number;
-    score: number;
-}
-declare function runProposeReview<State, Summary = unknown>(config: ProposeReviewConfig<State, Summary>): Promise<ProposeReviewReport<State, Summary>>;
-
-interface ProposeReviewControlState<State, Summary = unknown> {
-    shot: number;
-    state: State;
-    priorReview: Review | null;
-    verification: Verification;
-    traceSummary?: Summary;
-    memory: ReviewMemoryEntry[];
-    completed: boolean;
-    reviewAvailable: boolean;
-    reviewError?: string;
-}
-interface ProposeReviewControlAction {
-    type: 'propose-review-shot';
-    shot: number;
-}
-interface ProposeReviewControlResult<State, Summary = unknown> {
-    state: State;
-    verification: Verification;
-    traceSummary?: Summary;
-    review: Review | null;
-    reviewAvailable: boolean;
-    reviewError?: string;
-}
-interface ProposeReviewControlConfig<State, Summary = unknown> {
-    goal: string;
-    initialState: State;
-    propose: ProposeFn<State, Summary>;
-    verify: VerifyFn<State>;
-    review: ReviewFn<State, Summary>;
-    maxShots?: number;
-    maxWallMs?: number;
-    memory?: ReviewMemoryStore;
-    store?: TraceStore;
-    scenarioId?: string;
-    projectId?: string;
-    variantId?: string;
-    fallbackInstruction?: string;
-    confidenceFloor?: number;
-    confidenceFloorWindow?: number;
-    failureClassFromVerification?: (verification: Verification) => FailureClass | undefined;
-    actionFailure?: ControlRuntimeConfig<ProposeReviewControlState<State, Summary>, ProposeReviewControlAction, ProposeReviewControlResult<State, Summary>>['actionFailure'];
-}
-declare function runProposeReviewAsControlLoop<State, Summary = unknown>(config: ProposeReviewControlConfig<State, Summary>): Promise<ControlRunResult<ProposeReviewControlState<State, Summary>, ProposeReviewControlAction, ProposeReviewControlResult<State, Summary>>>;
-
-type AgentProfileCellSchemaVersion = 'agent-profile-cell/v1';
-type AgentProfileDimensionValue = string | number | boolean | null;
-interface AgentProfileSource {
-    /** Runtime/profile contract being fingerprinted, e.g. `agent-interface-profile`. */
-    kind: string;
-    /** sha256 over the canonical source profile object. */
-    hash: string;
-}
-interface AgentProfileHarness {
-    id: string;
-    version?: string;
-    hash?: string;
-}
-interface AgentProfileCell {
-    schemaVersion: AgentProfileCellSchemaVersion;
-    cellId: string;
-    profileId: string;
-    sourceProfile: AgentProfileSource;
-    harness?: AgentProfileHarness;
-    model?: string;
-    promptHash?: string;
-    dimensions?: Record<string, AgentProfileDimensionValue>;
-}
-
-/**
- * Paper-grade RunRecord schema + runtime validator.
- *
- * Every run that participates in a promotion gate, paper table, or
- * researcher loop SHOULD be recorded as a `RunRecord`. The mandatory
- * fields are exactly those the paper "Two Loops, Three Roles" requires
- * for reproducibility: who/what/when/cost/seed/hash, plus the search vs
- * holdout split tag. A task score is optional because execution-only records
- * must preserve missing labels instead of converting errors into zero quality.
- *
- * This is intentionally NOT a replacement for the rich `Run` /
- * `ProposeReviewReport` / `ScenarioResult` types already in the
- * package. Those are runtime structures with full provenance. A
- * `RunRecord` is the analysis-time projection — the JSON-friendly
- * row you'd put in a parquet file or paste into a notebook.
- *
- * Validate at the boundary:
- *
- *   const rec = validateRunRecord(rawJson)         // throws on missing
- *   const ok  = isRunRecord(rawJson)               // boolean check
- *   const rec = parseRunRecordSafe(rawJson)        // { ok, value | error }
- *
- * The validator runs in pure TS — zod is intentionally NOT a
- * dependency. Round-trip tested in `tests/run-record.test.ts`.
- */
-
-/** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
- *  combined train+test pool that the optimizer is allowed to read. */
-type RunSplitTag = 'search' | 'dev' | 'holdout';
-/**
- * Explicit execution-lifecycle result for a run.
- *
- * This is separate from task quality (`outcome`) and failure classification.
- * Producers set it only from root-run or process evidence.
- */
-type RunTerminalOutcome = 'succeeded' | 'failed' | 'cancelled' | 'incomplete' | 'unknown';
-interface RunTokenUsage {
-    input: number;
-    /** All generated tokens charged as output, including reasoning tokens. */
-    output: number;
-    /** Reasoning-token subset of `output`, when the provider reports it. */
-    reasoning?: number;
-    /** Prompt tokens served from a provider cache. */
-    cached?: number;
-    /** Prompt tokens written into a provider cache. */
-    cacheWrite?: number;
-}
-/**
- * How a run's USD amount was obtained.
- */
-type RunCostProvenance = {
-    kind: 'observed';
-    usd: number;
-} | {
-    kind: 'estimated';
-    usd: number;
-} | {
-    kind: 'uncaptured';
-    usd: null;
-};
-interface RunJudgeMetadata {
-    model: string;
-    promptVersion: string;
-    /** [0,1] confidence the judge declared. Constant judge confidence
-     *  across many runs is a fallback signal (see `canary.ts`). */
-    confidence: number;
-    /** True if the judge degraded to a fallback path (rules-only,
-     *  prior-call cache, etc.). The canary uses this to alert. */
-    fallback: boolean;
-}
-/**
- * Per-judge / per-dimension breakdown for runs scored by an ensemble of
- * judges over a multi-dimensional rubric.
- *
- * The collapsed `outcome.searchScore` / `holdoutScore` carries the
- * composite the gate uses. The full breakdown belongs here so consumers
- * can answer "which judge disagreed?", "which dimension dragged the
- * composite down?", and "did half the panel fail?" without re-running.
- *
- * `perJudge[judgeId][dim]` is the canonical source; `perDimMean` and
- * `composite` are convenience projections — derivable but precomputed so
- * downstream IRR primitives (`interRaterReliability`,
- * `corpusInterRaterAgreement`) and reporters don't pay the same
- * aggregation twice.
- *
- * Fail-loud discipline: judges that errored out land in `failedJudges`
- * by id. A missing key in `perJudge` is ambiguous (silent zero vs not
- * run); the explicit list makes a partial-failure recorded as such.
- */
-interface JudgeScoresRecord {
-    /** Per-judge per-dimension scores. `{ "kimi-k2.6": { helpfulness: 0.8, clarity: 0.7 }, ... }`. */
-    perJudge: Record<string, Record<string, number>>;
-    /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
-    perDimMean: Record<string, number>;
-    /** Composite mean across successful judges. Mirrors the task score only
-     *  when `failedJudges` is empty. */
-    composite: number;
-    /** Judges that errored or returned an unparseable verdict. Recorded
-     *  by id (e.g. `['glm-5.1']`) so a partial-failure case is explicit,
-     *  not inferred from missing keys in `perJudge`. */
-    failedJudges?: string[];
-    /** Free-form notes the judges emitted (joined across judges or
-     *  first-judge only — consumer's choice). */
-    notes?: string;
-}
-interface RunOutcome {
-    /** Score on the search/optimization split. Optional for holdout-only and
-     *  execution-only records. */
-    searchScore?: number;
-    /** Score on the held-out split. Optional for search-only and execution-only
-     *  records. When both scores are absent, the run is explicitly unlabeled. */
-    holdoutScore?: number;
-    /** Bag of any other metric the run produced — judge dimensions,
-     *  pass/fail counters, latency stats, etc. Numeric only — keeps
-     *  reporters honest. */
-    raw: Record<string, number>;
-    /** Per-judge / per-dim breakdown. Consumers writing ensemble
-     *  judgements populate this; substrate primitives like
-     *  `interRaterReliability` and `corpusInterRaterAgreement` accept
-     *  these records as input. Optional — single-judge or scalar-only
-     *  runs leave it unset. */
-    judgeScores?: JudgeScoresRecord;
-    /** Authenticity / realness verdict — did the run build the REAL thing on the
-     *  intended infra, or fake it (see `./authenticity`)? Optional: only domains
-     *  with an authenticity config populate it. Carried in the corpus so the
-     *  flywheel / off-policy learning can optimize for real completion, not gamed
-     *  pass-rate. `score` is 0-1; `gated` is the anti-Goodhart flag — a gated run
-     *  must not count as a real success regardless of `score`. */
-    realness?: {
-        score: number;
-        gated: boolean;
-        reason?: string;
-    };
-}
-/**
- * Mandatory paper-grade fields for a single evaluation run. Optional
- * fields are extension points; mandatory fields throw if missing.
- *
- * Hash discipline:
- *   - `promptHash` is the sha256 of the EFFECTIVE prompt sent to the
- *     model (after any steering bundle merge).
- *   - `configHash` is the sha256 of the effective run config (model,
- *     temperature, tools, judges, splits). The pair (promptHash,
- *     configHash) uniquely identifies an experiment cell.
- *
- * Model snapshot discipline:
- *   - `model` MUST encode a snapshot version. Bare aliases like
- *     `claude-sonnet-4` or `gpt-4o` are banned — they remap silently.
- *     Use `claude-sonnet-4-6@2025-04-15` or `gpt-4o-2024-11-20`.
- */
-interface RunRecord {
-    /** UUID for the run. */
-    runId: string;
-    /** Logical experiment grouping (a treatment vs a baseline within
-     *  the same sweep should share `experimentId`). */
-    experimentId: string;
-    /** Stable identifier for the candidate (variant) being run. The
-     *  promotion gate compares two `candidateId`s on matched items. */
-    candidateId: string;
-    /** RNG seed for the run. Always recorded — silent re-seeding is
-     *  the most common cause of non-reproducible numbers. */
-    seed: number;
-    /** Model identifier WITH snapshot version. */
-    model: string;
-    /** sha256 of the effective prompt (post-steering). */
-    promptHash: string;
-    /** sha256 of the effective config. */
-    configHash: string;
-    /** Git SHA the harness was run from. */
-    commitSha: string;
-    /** End-to-end wall-clock duration in milliseconds. */
-    wallMs: number;
-    /** Time spent queued before execution started, if known. */
-    queueMs?: number;
-    /** Total USD cost, or null when the producer could not capture one. */
-    costUsd: number | null;
-    /** Whether `costUsd` came from billing data, a price calculation, or is unavailable. */
-    costProvenance: RunCostProvenance;
-    /** Token usage breakdown. */
-    tokenUsage: RunTokenUsage;
-    /** Root-run or process terminal result. Never inferred from a child span. */
-    terminalOutcome: RunTerminalOutcome;
-    /** Root-run or process failure reason. Valid only for a failed, cancelled,
-     *  or incomplete terminal result; never populated from a child span. */
-    terminalFailureReason?: string;
-    /** Judge-side metadata, if a judge was used. */
-    judgeMetadata?: RunJudgeMetadata;
-    /** Per-split scores + raw bag. */
-    outcome: RunOutcome;
-    /** Canonical task-failure class drawn from the shared
-     *  `FAILURE_CLASSES` taxonomy. Producers set it only from task-result
-     *  evidence. Execution errors belong in
-     *  `outcome.raw.execution_error_count`. */
-    failureClass?: FailureClass;
-    /** Free-form task-failure detail scoped under a non-success
-     *  `failureClass`. It is invalid without that class. */
-    failureMode?: string;
-    /** Which split this run was drawn from. */
-    splitTag: RunSplitTag;
-    /**
-     * Stable scenario identifier the run observed or was scored against.
-     * Comparison primitives match this identity rather than input order.
-     */
-    scenarioId: string;
-    /**
-     * Canonical identity for the agent profile cell that produced this row:
-     * profile artifact hash plus optional harness/model/prompt/reporting
-     * dimensions. Use `agentProfile.cellId` to group persona sweeps and
-     * longitudinal reports by the complete source profile, not by a loose
-     * candidate label or opaque config hash.
-     */
-    agentProfile?: AgentProfileCell;
-}
-/**
- * Canonical task-result classification.
- *
- * A producer may omit classification, record explicit success, or attach
- * domain-specific detail to a non-success class. Detail can never stand alone.
- * Execution errors belong in `outcome.raw.execution_error_count`.
- */
-type RunTaskFailure = {
-    failureClass?: undefined;
-    failureMode?: undefined;
-} | {
-    failureClass: 'success';
-    failureMode?: undefined;
-} | {
-    failureClass: Exclude<FailureClass, 'success'>;
-    failureMode?: string;
-};
-
-interface RunEvidenceMetadata {
-    experimentId: string;
-    scenarioId: string;
-    candidateId: string;
-    seed: number;
-    model: string;
-    promptHash: string;
-    configHash: string;
-    commitSha: string;
-    splitTag: RunSplitTag;
-    tokenUsage: RunTokenUsage;
-    costProvenance: RunRecord['costProvenance'];
-    queueMs?: number;
-    judgeMetadata?: RunRecord['judgeMetadata'];
-    raw?: Record<string, number>;
-}
-type ControlRunToRunRecordOptions = RunEvidenceMetadata & RunTaskFailure & {
-    runId?: string;
-    score?: number;
-};
-/**
- * Project a completed control-loop run into the strict RunRecord shape used by
- * release gates, optimizer tables, and research reports.
- *
- * The control loop owns live execution evidence. The caller still supplies the
- * experiment-cell metadata because prompt/config hashes, split assignment,
- * model snapshot, and commit SHA are product/harness concerns.
- */
-declare function controlRunToRunRecord<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(run: ControlRunResult<TState, TAction, TActionResult, TEval>, options: ControlRunToRunRecordOptions): RunRecord;
-declare function scoreFromEvals(evals: readonly ControlEvalResult[]): number | undefined;
-
-export { type ActionExecutionPolicy, type ActionPolicyDecision, type ControlActionFailureMode, type ControlActionOutcome, type ControlBudget, type ControlContext, type ControlDecision, type ControlEvalResult, type ControlRunResult, type ControlRunToRunRecordOptions, type ControlRuntimeConfig, type ControlRuntimeError, type ControlSeverity, type ControlStep, type ControlStopPolicies, type ProposeReviewConfig, type ProposeReviewControlAction, type ProposeReviewControlConfig, type ProposeReviewControlResult, type ProposeReviewControlState, type ProposeReviewReport, type RunEvidenceMetadata, type StopDecision, allCriticalPassed, controlRunToRunRecord, evaluateActionPolicy, objectiveEval, runAgentControlLoop, runProposeReview, runProposeReviewAsControlLoop, scoreFromEvals, stopOnNoProgress, stopOnRepeatedAction, subjectiveEval };
+import { B as ControlRunResult, F as ControlActionOutcome, G as ControlStopPolicies, H as ControlRuntimeError, I as ControlBudget, J as objectiveEval, K as StopDecision, L as ControlContext, P as ControlActionFailureMode, Q as subjectiveEval, R as ControlDecision, U as ControlSeverity, V as ControlRuntimeConfig, W as ControlStep, X as stopOnNoProgress, Y as runAgentControlLoop, Z as stopOnRepeatedAction, q as allCriticalPassed, z as ControlEvalResult } from "./feedback-trajectory-CVaeREXV.js";
+import { A as ActionExecutionPolicy, M as evaluateActionPolicy, _ as ProposeReviewReport, a as ProposeReviewControlAction, c as ProposeReviewControlState, g as ProposeReviewConfig, i as scoreFromEvals, j as ActionPolicyDecision, k as runProposeReview, n as RunEvidenceMetadata, o as ProposeReviewControlConfig, r as controlRunToRunRecord, s as ProposeReviewControlResult, t as ControlRunToRunRecordOptions, u as runProposeReviewAsControlLoop } from "./run-evidence-ClRX_8A9.js";
+export { type ActionExecutionPolicy, type ActionPolicyDecision, type ControlActionFailureMode, type ControlActionOutcome, type ControlBudget, type ControlContext, type ControlDecision, type ControlEvalResult, type ControlRunResult, type ControlRunToRunRecordOptions, type ControlRuntimeConfig, type ControlRuntimeError, type ControlSeverity, type ControlStep, type ControlStopPolicies, type ProposeReviewConfig, type ProposeReviewControlAction, type ProposeReviewControlConfig, type ProposeReviewControlResult, type ProposeReviewControlState, type ProposeReviewReport, type RunEvidenceMetadata, type StopDecision, allCriticalPassed, controlRunToRunRecord, evaluateActionPolicy, objectiveEval, runAgentControlLoop, runProposeReview, runProposeReviewAsControlLoop, scoreFromEvals, stopOnNoProgress, stopOnRepeatedAction, subjectiveEval };