@tangle-network/agent-eval 0.118.3 → 0.119.1

package/dist/cli.js

@@ -5,9 +5,9 @@ import {
   runRpcBatch,
   runRpcOnce,
   startServer
-} from "./chunk-JTMFT5QZ.js";
+} from "./chunk-4I2E3LLO.js";
 import "./chunk-NJC7U437.js";
-import "./chunk-MLHRFWQK.js";
+import "./chunk-JHOJHHU7.js";
 import "./chunk-VI2UW6B6.js";
 import "./chunk-PC4UYEBM.js";
 import "./chunk-ONWEPEDO.js";

package/dist/contract/index.d.ts

@@ -1,3 +1,4 @@
+import { AgentImprovementMeasuredComparison, Sha256Digest } from '@tangle-network/agent-interface';
 import { AxFunction, AxAIService } from '@ax-llm/ax';
 import { z } from 'zod';
 
@@ -28,6 +29,174 @@ interface AgentProfileCell {
     dimensions?: Record<string, AgentProfileDimensionValue>;
 }
 
+type CostChannel = 'agent' | 'judge' | 'verifier' | 'analyst' | 'driver' | (string & {});
+interface CostUsage {
+    inputTokens: number;
+    /** Includes reasoning tokens when the provider bills them as output. */
+    outputTokens: number;
+    /** Reasoning-token subset of outputTokens, when reported. */
+    reasoningTokens?: number;
+    /** Prompt tokens served from a provider cache. */
+    cachedTokens?: number;
+    /** Prompt tokens written into a provider cache. */
+    cacheWriteTokens?: number;
+}
+interface CostCallBase {
+    callId: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    model: string;
+    maximumCostUsd?: number;
+    tags?: Record<string, string>;
+    timestamp: number;
+}
+interface CostReceipt extends CostCallBase, CostUsage {
+    status: 'settled';
+    costUsd: number;
+    costUnknown: boolean;
+    usageUnknown?: boolean;
+    pricing?: {
+        inputUsdPerThousand: number;
+        outputUsdPerThousand: number;
+    };
+    actualCostUsd?: number;
+    error?: string;
+}
+interface CostReceiptInput extends CostUsage {
+    model: string;
+    actualCostUsd?: number;
+    costUnknown?: boolean;
+    usageUnknown?: boolean;
+}
+type MaximumCharge = {
+    externallyEnforcedMaximumUsd: number;
+} | ({
+    model: string;
+} & CostUsage);
+interface RunPaidCallInput<T> {
+    callId?: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    /** Used before a provider receipt exists and on failures without one. */
+    model?: string;
+    tags?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Provider-enforced dollar maximum, or maximum priced token usage. Required when capped. */
+    maximumCharge?: MaximumCharge;
+    /** `callId` can be forwarded as the provider's idempotency key. */
+    execute(signal: AbortSignal, callId: string): Promise<T>;
+    receipt(value: T): CostReceiptInput;
+    receiptFromError?(error: Error): CostReceiptInput | undefined;
+}
+type PaidCallResult<T> = {
+    succeeded: true;
+    callId: string;
+    value: T;
+    receipt: CostReceipt;
+} | {
+    succeeded: false;
+    callId?: string;
+    error: Error;
+    receipt?: CostReceipt;
+};
+interface ChannelRollup {
+    channel: CostChannel;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens: number;
+    cacheWriteTokens?: number;
+    costUsd: number;
+    unpricedCalls: number;
+    unknownUsageCalls: number;
+}
+interface CostLedgerSummary {
+    totalCalls: number;
+    pendingCalls: number;
+    unresolvedCalls: number;
+    reservedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens: number;
+    cacheWriteTokens?: number;
+    totalCostUsd: number;
+    byChannel: ChannelRollup[];
+    unpricedModels: string[];
+    fullyPriced: boolean;
+    usageComplete: boolean;
+    accountingComplete: boolean;
+    incompleteReasons: string[];
+}
+interface CostLedgerFilter {
+    channel?: CostChannel;
+    phase?: string;
+    tags?: Record<string, string>;
+}
+interface CostLedgerWaitOptions {
+    /** Maximum time to wait for active provider calls. Default 5 seconds. */
+    timeoutMs?: number;
+}
+/** Append-only storage. `append` must atomically reject stale revisions. */
+interface CostLedgerPersistence {
+    read(): {
+        revision: string;
+        events: string;
+    };
+    append(expectedRevision: string, event: string): string | undefined;
+}
+interface CostLedgerOptions {
+    costCeilingUsd?: number;
+    persistence?: CostLedgerPersistence;
+    /** Import already-settled receipts without admitting new paid work. */
+    receipts?: readonly CostReceipt[];
+}
+/** Run-wide paid-call admission, durable call state, receipts, and summaries. */
+declare class CostLedger {
+    private readonly records;
+    private readonly activeCallIds;
+    private readonly lateCallIds;
+    private readonly idleWaiters;
+    private completedTasks;
+    private revision;
+    private costLimitPersisted;
+    readonly costCeilingUsd?: number;
+    private readonly persistence?;
+    constructor(input?: number | CostLedgerOptions);
+    runPaidCall<T>(input: RunPaidCallInput<T>): Promise<PaidCallResult<T>>;
+    /** Wait until every call started by this ledger has produced a durable outcome. */
+    waitForIdle(options?: CostLedgerWaitOptions): Promise<boolean>;
+    /** Settle a call left pending by a crashed process after reconciling with the provider. */
+    reconcile(callId: string, observed: CostReceiptInput, options?: {
+        error?: string;
+    }): CostReceipt;
+    list(filter?: CostLedgerFilter): CostReceipt[];
+    summary(filter?: CostLedgerFilter): CostLedgerSummary;
+    markCompleted(count?: number): void;
+    costPerCompletedTask(): number | null;
+    private execute;
+    private captureLateOutcome;
+    private releaseActiveCall;
+    private commitOutcome;
+    private captureFailure;
+    private commitReceipt;
+    private resolveMaximum;
+    private hasIncompleteSettledCall;
+    private appendRecord;
+    private ensureCostLimitPersisted;
+    private appendEvent;
+}
+/** Public callback surface for a shared cost ledger.
+ *
+ * Declaration bundles may expose this type through multiple package subpaths.
+ * Keeping callback contracts structural lets those subpaths compose while the
+ * concrete {@link CostLedger} retains its private durable state.
+ */
+type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'waitForIdle'>> & Partial<Pick<CostLedger, 'waitForIdle'>>;
+
 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';
 
 /**
@@ -475,156 +644,6 @@ interface TraceAnalysisStore {
     }): Promise<SearchSpanResult>;
 }
 
-type CostChannel = 'agent' | 'judge' | 'verifier' | 'analyst' | 'driver' | (string & {});
-interface CostUsage {
-    inputTokens: number;
-    outputTokens: number;
-    cachedTokens?: number;
-}
-interface CostCallBase {
-    callId: string;
-    channel: CostChannel;
-    phase: string;
-    actor: string;
-    model: string;
-    maximumCostUsd?: number;
-    tags?: Record<string, string>;
-    timestamp: number;
-}
-interface CostReceipt extends CostCallBase, CostUsage {
-    status: 'settled';
-    costUsd: number;
-    costUnknown: boolean;
-    usageUnknown?: boolean;
-    pricing?: {
-        inputUsdPerThousand: number;
-        outputUsdPerThousand: number;
-    };
-    actualCostUsd?: number;
-    error?: string;
-}
-interface CostReceiptInput extends CostUsage {
-    model: string;
-    actualCostUsd?: number;
-    costUnknown?: boolean;
-    usageUnknown?: boolean;
-}
-type MaximumCharge = {
-    externallyEnforcedMaximumUsd: number;
-} | ({
-    model: string;
-} & CostUsage);
-interface RunPaidCallInput<T> {
-    callId?: string;
-    channel: CostChannel;
-    phase: string;
-    actor: string;
-    /** Used before a provider receipt exists and on failures without one. */
-    model?: string;
-    tags?: Record<string, string>;
-    signal?: AbortSignal;
-    /** Provider-enforced dollar maximum, or maximum priced token usage. Required when capped. */
-    maximumCharge?: MaximumCharge;
-    /** `callId` can be forwarded as the provider's idempotency key. */
-    execute(signal: AbortSignal, callId: string): Promise<T>;
-    receipt(value: T): CostReceiptInput;
-    receiptFromError?(error: Error): CostReceiptInput | undefined;
-}
-type PaidCallResult<T> = {
-    succeeded: true;
-    callId: string;
-    value: T;
-    receipt: CostReceipt;
-} | {
-    succeeded: false;
-    callId?: string;
-    error: Error;
-    receipt?: CostReceipt;
-};
-interface ChannelRollup {
-    channel: CostChannel;
-    calls: number;
-    inputTokens: number;
-    outputTokens: number;
-    cachedTokens: number;
-    costUsd: number;
-    unpricedCalls: number;
-    unknownUsageCalls: number;
-}
-interface CostLedgerSummary {
-    totalCalls: number;
-    pendingCalls: number;
-    unresolvedCalls: number;
-    reservedCostUsd: number;
-    inputTokens: number;
-    outputTokens: number;
-    cachedTokens: number;
-    totalCostUsd: number;
-    byChannel: ChannelRollup[];
-    unpricedModels: string[];
-    fullyPriced: boolean;
-    usageComplete: boolean;
-    accountingComplete: boolean;
-    incompleteReasons: string[];
-}
-interface CostLedgerFilter {
-    channel?: CostChannel;
-    phase?: string;
-    tags?: Record<string, string>;
-}
-/** Append-only storage. `append` must atomically reject stale revisions. */
-interface CostLedgerPersistence {
-    read(): {
-        revision: string;
-        events: string;
-    };
-    append(expectedRevision: string, event: string): string | undefined;
-}
-interface CostLedgerOptions {
-    costCeilingUsd?: number;
-    persistence?: CostLedgerPersistence;
-    /** Import already-settled receipts without admitting new paid work. */
-    receipts?: readonly CostReceipt[];
-}
-/** Run-wide paid-call admission, durable call state, receipts, and summaries. */
-declare class CostLedger {
-    private readonly records;
-    private readonly activeCallIds;
-    private readonly lateCallIds;
-    private completedTasks;
-    private revision;
-    private costLimitPersisted;
-    readonly costCeilingUsd?: number;
-    private readonly persistence?;
-    constructor(input?: number | CostLedgerOptions);
-    runPaidCall<T>(input: RunPaidCallInput<T>): Promise<PaidCallResult<T>>;
-    /** Settle a call left pending by a crashed process after reconciling with the provider. */
-    reconcile(callId: string, observed: CostReceiptInput, options?: {
-        error?: string;
-    }): CostReceipt;
-    list(filter?: CostLedgerFilter): CostReceipt[];
-    summary(filter?: CostLedgerFilter): CostLedgerSummary;
-    markCompleted(count?: number): void;
-    costPerCompletedTask(): number | null;
-    private execute;
-    private captureLateOutcome;
-    private commitOutcome;
-    private captureFailure;
-    private commitReceipt;
-    private resolveMaximum;
-    private hasIncompleteSettledCall;
-    private appendRecord;
-    private ensureCostLimitPersisted;
-    private appendEvent;
-}
-/** Public callback surface for a shared cost ledger.
- *
- * Declaration bundles may expose this type through multiple package subpaths.
- * Keeping callback contracts structural lets those subpaths compose while the
- * concrete {@link CostLedger} retains its private durable state.
- */
-type CostLedgerHandle = Pick<CostLedger, keyof CostLedger>;
-
 interface Scenario$1 {
     id: string;
     persona: string;
@@ -1104,6 +1123,8 @@ interface AnalystCost {
     est_usd_per_run?: number;
     /** Models the analyst expects to use (informational). */
     models?: string[];
+    /** Maximum post-cancellation wait for provider usage. Model analysts default to 5 seconds. */
+    settlement_timeout_ms?: number;
 }
 interface AnalystRequirements {
     /** Min number of shots / samples the analyst needs to produce signal. */
@@ -1127,10 +1148,14 @@ interface AnalystContext {
     runId: string;
     /** Stable correlation id so logs from a single registry.run() share a tag. */
     correlationId: string;
-    /** Wall-clock deadline (epoch ms). Analysts SHOULD honor for graceful cancel. */
+    /** Enforced wall-clock deadline (epoch ms). */
     deadlineMs?: number;
     /** Per-analyst USD budget. Analysts MAY check before issuing LLM calls. */
     budgetUsd?: number;
+    /** Shared paid-call account when the analyst runs inside a larger campaign. */
+    costLedger?: CostLedgerHandle;
+    /** Attribution phase used when writing to the shared paid-call account. */
+    costPhase?: string;
     /**
      * Shared chat client. Analysts that call an LLM go through this so
      * the operator picks transport (sandbox-sdk | router | cli-bridge |
@@ -1148,6 +1173,18 @@ interface AnalystContext {
      * filter. Empty / absent means no cross-run context.
      */
     priorFindings?: ReadonlyArray<AnalystFinding>;
+    /**
+     * Findings emitted by analysts that completed earlier in this registry run.
+     * This is separate from `priorFindings`: upstream findings are dependency
+     * context for the current pass, while prior findings are cross-run memory.
+     * The registry populates this only when `RegistryRunOpts.chainFindings` is on.
+     */
+    upstreamFindings?: ReadonlyArray<AnalystFinding>;
+    /**
+     * Report metered work independently of findings. This keeps an empty finding
+     * set from erasing token/cost telemetry. Multiple receipts are accumulated.
+     */
+    recordUsage?: (receipt: AnalystUsageReceipt) => void;
     /** Free-form runtime tags (env, host, op). Findings can echo these into metadata. */
     tags?: Record<string, string>;
     /** Logger callback — analysts SHOULD prefer this over console.* for testability. */
@@ -1173,6 +1210,17 @@ interface Analyst<TInput = unknown> {
     readonly version: string;
     analyze(input: TInput, ctx: AnalystContext): Promise<AnalystFinding[]>;
 }
+/** Metered work performed by one analyst call. */
+interface AnalystUsageReceipt {
+    /** Number of model-usage records observed at the provider boundary. */
+    calls: number | null;
+    /** Null when the provider did not return token accounting. */
+    tokens: RunTokenUsage | null;
+    /** Observed, estimated, or explicitly uncaptured dollar cost. */
+    cost: RunCostProvenance;
+    /** Known lower bound when one or more calls have uncaptured cost. */
+    knownCostUsd?: number;
+}
 interface AnalystRunSummary {
     analyst_id: string;
     status: 'ok' | 'skipped' | 'failed';
@@ -1181,6 +1229,12 @@ interface AnalystRunSummary {
     findings_count: number;
     latency_ms: number;
     cost_usd: number;
+    /**
+     * Additive receipt for model usage. Registry-produced summaries populate it
+     * even when the analyst emits no findings. `cost_usd` remains the legacy
+     * numeric field; inspect `usage.cost` before treating zero as observed.
+     */
+    usage?: AnalystUsageReceipt;
     /** When `status='failed'`: the error class + message, never the full stack. */
     error?: {
         class: string;
@@ -1196,6 +1250,11 @@ interface AnalystRunResult {
     per_analyst: AnalystRunSummary[];
     /** Total LLM cost in USD across all analysts in this registry.run(). */
     total_cost_usd: number;
+    /**
+     * Provenance for `total_cost_usd`. When uncaptured, the numeric field is only
+     * the known subtotal and must not be treated as the run's total spend.
+     */
+    total_cost_provenance?: RunCostProvenance;
 }
 /**
  * Events emitted by `AnalystRegistry.runStream(...)` in real time as
@@ -3944,6 +4003,15 @@ interface DefinedAgentEval<TScenario extends Scenario, TArtifact> {
  */
 declare function defineAgentEval<TScenario extends Scenario, TArtifact>(defaults: DefineAgentEvalOptions<TScenario, TArtifact>): DefinedAgentEval<TScenario, TArtifact>;
 
+interface MeasuredComparisonFromSelfImproveResultOptions<TScenario extends Scenario, TArtifact> {
+    result: SelfImproveResult<TScenario, TArtifact>;
+    benchmark: AgentImprovementMeasuredComparison['benchmark'];
+    baselineProfileDigest: Sha256Digest;
+    candidateBundleDigest: Sha256Digest;
+}
+/** Convert one paired self-improvement result into the portable Interface evidence record. */
+declare function measuredComparisonFromSelfImproveResult<TScenario extends Scenario, TArtifact>(options: MeasuredComparisonFromSelfImproveResultOptions<TScenario, TArtifact>): AgentImprovementMeasuredComparison;
+
 /**
  * Typed Ax output for analyst findings.
  *
@@ -3961,7 +4029,10 @@ declare function defineAgentEval<TScenario extends Scenario, TArtifact>(defaults
  * validation surface independent of which Ax version is installed.
  */
 
+/** Original public schema retained for stored rows and callback contracts. */
 declare const RawAnalystFindingSchema: z.ZodObject<{
+    evidence_uri: z.ZodString;
+    evidence_excerpt: z.ZodOptional<z.ZodString>;
     severity: z.ZodEnum<{
         low: "low";
         high: "high";
@@ -3971,23 +4042,46 @@ declare const RawAnalystFindingSchema: z.ZodObject<{
     }>;
     claim: z.ZodString;
     subject: z.ZodOptional<z.ZodString>;
-    evidence_uri: z.ZodString;
-    evidence_excerpt: z.ZodOptional<z.ZodString>;
     confidence: z.ZodNumber;
     rationale: z.ZodOptional<z.ZodString>;
     recommended_action: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
+/**
+ * Canonical plural-evidence contract. The preprocessor accepts the original
+ * `evidence_uri` / `evidence_excerpt` pair and normalizes it into one evidence
+ * item so persisted rows and older model fixtures remain readable. New output
+ * always receives the plural shape.
+ */
+declare const CanonicalRawAnalystFindingSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
+    evidence: z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        excerpt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    severity: z.ZodEnum<{
+        low: "low";
+        high: "high";
+        critical: "critical";
+        medium: "medium";
+        info: "info";
+    }>;
+    claim: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    recommended_action: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+type CanonicalRawAnalystFinding = z.infer<typeof CanonicalRawAnalystFindingSchema>;
 
 /**
  * Analyst-kind factory — the typed way to define trace analysts.
  *
  * A "kind" is a specialized analyst whose actor prompt, tool subset,
- * and Ax recursion config target one failure-mode lens (failure-mode
- * classification, knowledge gap discovery, knowledge poisoning, recursive
- * self-improvement, ...). Kinds emit findings in the typed `RawAnalystFinding`
- * shape via a JSON-array Ax output; the factory validates each row with
- * Zod and lifts it into `AnalystFinding[]` with no shape guessing.
+ * and bounded Ax subqueries target one failure-mode lens (failure-mode
+ * classification, knowledge gap discovery, knowledge poisoning,
+ * self-improvement, ...). Kinds emit findings in the typed
+ * `CanonicalRawAnalystFinding` shape via a JSON-array Ax output; the factory
+ * validates each row with Zod and lifts it into `AnalystFinding[]`.
  *
  * Composition rules:
  *   - Each kind owns its actor description. No generic "answer this
@@ -3995,12 +4089,11 @@ type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
  *   - Each kind picks a narrow tool subset from `ANALYST_TOOL_GROUPS`.
  *     A kind that never needs full-trace dumps can drop `viewTrace` /
  *     `viewSpans` and stay cheap.
- *   - Each kind declares its recursion + parallelism budget. Discovery-
- *     heavy kinds (failure-mode) get higher `maxDepth`; lens kinds
- *     (poisoning) usually stay at 0 since they have a tighter brief.
+ *   - Each kind declares its subquery + parallelism budget. Discovery-heavy
+ *     kinds can fan out more bounded semantic questions than narrow lenses.
  *
  * Optimizer hook: kinds may declare `goldens` — labeled examples used
- * by `AxMiPRO` / `AxBootstrapFewShot` / `AxGEPA` to fit the actor
+ * by `AxBootstrapFewShot` / `AxGEPA` to fit the actor
  * description programmatically. Stored on the kind, not the registry,
  * because the right metric is kind-specific.
  */
@@ -4020,23 +4113,25 @@ interface TraceAnalystKindSpec {
     version: string;
     /** Actor system prompt. Must instruct the LLM to emit `findings` per the schema. */
     actorDescription: string;
-    /** Responder system prompt; falls back to a minimal "format the findings" instruction. */
-    responderDescription?: string;
     /** Tool functions the actor may call. Pick narrow subsets via `ANALYST_TOOL_GROUPS`. */
     buildTools: (store: TraceAnalysisStore) => AxFunction[];
-    /** Recursion budget. `maxDepth: 0` disables subagents. */
-    recursion?: {
-        maxDepth: number;
-        maxParallelSubagents?: number;
+    /** Bounded semantic subqueries. `maxCalls: 0` disables model fan-out. */
+    subqueries?: {
+        maxCalls: number;
+        maxParallel?: number;
     };
     /** Actor turn cap. Default 12. */
     maxTurns?: number;
     /** Runtime char cap. Default 6000. */
     maxRuntimeChars?: number;
+    /** Maximum output tokens for every actor and subquery model call. Default 4096. */
+    maxOutputTokens?: number;
     /** Cost classification surfaced in `registry.list()` and budget enforcement. */
     cost: AnalystCost;
     /** Per-finding-row hook — kinds may reject / rewrite before lifting. */
     postProcess?: (row: RawAnalystFinding, ctx: AnalystContext) => RawAnalystFinding | null;
+    /** Minimum citations per finding. Default 1; rows below it are rejected. */
+    minimumEvidenceCitations?: number;
     /** Optional optimizer hook — populated when a kind wants to fit its prompt against labeled examples. */
     goldens?: TraceAnalystGolden[];
 }
@@ -4048,7 +4143,7 @@ interface TraceAnalystKindSpec {
  */
 interface TraceAnalystGolden {
     question: string;
-    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
+    expected: ReadonlyArray<Omit<CanonicalRawAnalystFinding, 'confidence'>>;
 }
 
 /**
@@ -4106,7 +4201,8 @@ interface BudgetPolicy {
     /**
      * Custom allocator — receives the analyst, remaining/total budget, and
      * the count of analysts that will run. Returns the per-analyst budget
-     * (or undefined to leave it uncapped). Overrides weights when set.
+     * (or undefined only when the run has no overall cap). Overrides weights
+     * when set.
      */
     allocate?: (args: {
         analyst: Analyst;
@@ -4132,10 +4228,14 @@ interface RegistryRunOpts {
     skip?: string[];
     /** Budget policy — totalUsd + optional weights/allocator. Falls back to options.defaultBudget. */
     budget?: BudgetPolicy;
-    /** Wall-clock cap. Analysts SHOULD honor `ctx.deadlineMs`. */
+    /** Active-work cap for the complete registry run. Model receipt settlement may follow. */
     timeoutMs?: number;
     /** Abort signal — forwarded into every analyst's context. */
     signal?: AbortSignal;
+    /** Shared paid-call account forwarded to every analyst. */
+    costLedger?: CostLedgerHandle;
+    /** Attribution phase for calls written to `costLedger`. */
+    costPhase?: string;
     /** Tags echoed into AnalystContext.tags — useful for tracking environment/version in findings. */
     tags?: Record<string, string>;
     /**
@@ -4143,10 +4243,16 @@ interface RegistryRunOpts {
      * analyst via `ctx.priorFindings`. The registry forwards the slice
      * whose `analyst_id` matches each registered analyst so a kind sees
      * only its own history. Pass `{ '*': findings }` to broadcast to
-     * every analyst (useful for cross-kind chaining where the improvement
-     * analyst consumes upstream failure findings).
+     * every analyst (useful when several kinds share the same historical
+     * context). For findings from this run, use `chainFindings` instead.
      */
     priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+    /**
+     * Pass findings produced earlier in this registry run to each later analyst
+     * via `ctx.upstreamFindings`. Registration order is dependency order.
+     * Disabled by default because independent analyst suites must opt in.
+     */
+    chainFindings?: boolean;
 }
 declare class AnalystRegistry {
     private readonly analysts;
@@ -4190,7 +4296,7 @@ declare class AnalystRegistry {
 interface DefaultAnalystRegistryOptions {
     /** Ax service for the agentic RLM kinds. Omit → only the deterministic analyst. */
     ai?: AxAIService;
-    /** Model for the agentic kinds (falls back to the ai service default). */
+    /** Required unless `ai` was created by `createAnalystAi`. */
     model?: string;
     /** Which agentic kinds to register when `ai` is present. Default = the shipped suite. */
     kinds?: readonly TraceAnalystKindSpec[];
@@ -4836,4 +4942,4 @@ interface FromOtelSpansOptions {
 }
 declare function fromOtelSpans(opts: FromOtelSpansOptions): RunRecord[];
 
-export { type AgentEvalAgent, type AgentEvalEvaluateOptions, type AgentEvalImproveOptions, type AgentTraceContributor, type AgentTraceContributorType, type AgentTraceConversation, type AgentTraceFile, type AgentTraceIndex, type AgentTraceRange, type AgentTraceRecord, type AnalystFinding, type AnalyzeRunsOptions, type AuthoringProvenance, type AxisEvidence, type AxisVerdict, type BuildEvidenceVectorOptions, type CampaignAggregates, type CampaignArtifactWriter, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignStorage, type CampaignTraceWriter, type ChatClient, type CodeAgentSessionDiagnostic, type CodeAgentSessionIntakeOptions, type CodeAgentSessionIntakeResult, type CodeAgentSessionMetrics, type CodeAgentSessionSource, type CodeSurface, type CostLedgerHandle, type CostProvenanceSummary, type CreateChatClientOpts, type DefaultAnalystRegistryOptions, type DefaultProductionGateOptions, type DefineAgentEvalOptions, type DefinedAgentEval, type DeploymentOutcome, type DispatchFn as Dispatch, type DispatchContext, type EvalCellScoreDelta, type EvalDimensionDelta, type EvalGenerationDiff, type EvalReportingSuiteInput, type EvalReportingSuiteOptions, type EvalReportingSuiteResult, type EvalRunDiff, type EvidenceVector, type EvolutionaryProposerOptions, type ExecutionInsight, type ExecutionReport, type FailureClusterInsight, type FeedbackTableMeta, type FeedbackTableRow, FileSystemOutcomeStore, type FileSystemOutcomeStoreOptions, type FromFeedbackTableOptions, type FromFeedbackTableResult, type FromOtelSpansOptions, type FromRunRecordDirOptions, type FromRunRecordDirResult, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaProposerOptions, type HeldOutGateOptions, type HostedTenant, InMemoryOutcomeStore, type InsightReport, type InterRaterInsight, type JudgeConfig, type JudgeDimension, type JudgeInsight, type JudgeScore, type LiftInsight, type MutableSurface, type Mutator, type ObjectiveSource, type OptimizationProposer, type OptimizerConfig, type OutcomeCorrelationInsight, type OutcomeStore, type ParetoSignificanceGateOptions, type ParsedCodeAgentJsonl, type PartitionByAuthoringModelResult, type PromotionObjective, type PromotionPolicy, REFERENCE_EQUIVALENCE_INPUT_LIMITS, REFERENCE_EQUIVALENCE_JUDGE_VERSION, type Recommendation, type ReferenceEquivalenceJudgeInput, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceJudgeResult, type ReferenceEquivalenceScenario, type ReleaseSummary, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunRecordRejection, type ScalarDistribution, type Scenario, type SelfImproveBudget, type SelfImproveLlm, type SelfImproveOptions, type SelfImproveProgressEvent, type SelfImproveResult, SelfImproveRunError, type SessionScript, type SummarizeExecutionOptions, type SurfaceProposer, type TokenUsageInsight, analyzeRuns, buildDefaultAnalystRegistry, buildEvidenceVector, composeGate, createChatClient, createReferenceEquivalenceJudge, defaultProductionGate, defineAgentEval, diffGenerations, diffRunBaselineToWinner, diffRuns, evalReportingSuite, evolutionaryProposer, fromClaudeCodeSession, fromCodexSession, fromFeedbackTable, fromKimiCodeSession, fromOpenCodeSession, fromOtelSpans, fromPiSession, fromPigraphSession, fromRunRecordDir, fsCampaignStorage, gepaProposer, heldOutGate, inMemoryCampaignStorage, paretoPolicy, paretoSignificanceGate, parseAgentTrace, parseCodeAgentJsonl, partitionRunsByAuthoringModel, runCampaign, runEval, runImprovementLoop, runReferenceEquivalenceJudge, selfImprove, summarizeExecution };
+export { type AgentEvalAgent, type AgentEvalEvaluateOptions, type AgentEvalImproveOptions, type AgentTraceContributor, type AgentTraceContributorType, type AgentTraceConversation, type AgentTraceFile, type AgentTraceIndex, type AgentTraceRange, type AgentTraceRecord, type AnalystFinding, type AnalyzeRunsOptions, type AuthoringProvenance, type AxisEvidence, type AxisVerdict, type BuildEvidenceVectorOptions, type CampaignAggregates, type CampaignArtifactWriter, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignStorage, type CampaignTraceWriter, type ChatClient, type CodeAgentSessionDiagnostic, type CodeAgentSessionIntakeOptions, type CodeAgentSessionIntakeResult, type CodeAgentSessionMetrics, type CodeAgentSessionSource, type CodeSurface, type CostLedgerHandle, type CostProvenanceSummary, type CreateChatClientOpts, type DefaultAnalystRegistryOptions, type DefaultProductionGateOptions, type DefineAgentEvalOptions, type DefinedAgentEval, type DeploymentOutcome, type DispatchFn as Dispatch, type DispatchContext, type EvalCellScoreDelta, type EvalDimensionDelta, type EvalGenerationDiff, type EvalReportingSuiteInput, type EvalReportingSuiteOptions, type EvalReportingSuiteResult, type EvalRunDiff, type EvidenceVector, type EvolutionaryProposerOptions, type ExecutionInsight, type ExecutionReport, type FailureClusterInsight, type FeedbackTableMeta, type FeedbackTableRow, FileSystemOutcomeStore, type FileSystemOutcomeStoreOptions, type FromFeedbackTableOptions, type FromFeedbackTableResult, type FromOtelSpansOptions, type FromRunRecordDirOptions, type FromRunRecordDirResult, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaProposerOptions, type HeldOutGateOptions, type HostedTenant, InMemoryOutcomeStore, type InsightReport, type InterRaterInsight, type JudgeConfig, type JudgeDimension, type JudgeInsight, type JudgeScore, type LiftInsight, type MeasuredComparisonFromSelfImproveResultOptions, type MutableSurface, type Mutator, type ObjectiveSource, type OptimizationProposer, type OptimizerConfig, type OutcomeCorrelationInsight, type OutcomeStore, type ParetoSignificanceGateOptions, type ParsedCodeAgentJsonl, type PartitionByAuthoringModelResult, type PromotionObjective, type PromotionPolicy, REFERENCE_EQUIVALENCE_INPUT_LIMITS, REFERENCE_EQUIVALENCE_JUDGE_VERSION, type Recommendation, type ReferenceEquivalenceJudgeInput, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceJudgeResult, type ReferenceEquivalenceScenario, type ReleaseSummary, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunRecordRejection, type ScalarDistribution, type Scenario, type SelfImproveBudget, type SelfImproveLlm, type SelfImproveOptions, type SelfImproveProgressEvent, type SelfImproveResult, SelfImproveRunError, type SessionScript, type SummarizeExecutionOptions, type SurfaceProposer, type TokenUsageInsight, analyzeRuns, buildDefaultAnalystRegistry, buildEvidenceVector, composeGate, createChatClient, createReferenceEquivalenceJudge, defaultProductionGate, defineAgentEval, diffGenerations, diffRunBaselineToWinner, diffRuns, evalReportingSuite, evolutionaryProposer, fromClaudeCodeSession, fromCodexSession, fromFeedbackTable, fromKimiCodeSession, fromOpenCodeSession, fromOtelSpans, fromPiSession, fromPigraphSession, fromRunRecordDir, fsCampaignStorage, gepaProposer, heldOutGate, inMemoryCampaignStorage, measuredComparisonFromSelfImproveResult, paretoPolicy, paretoSignificanceGate, parseAgentTrace, parseCodeAgentJsonl, partitionRunsByAuthoringModel, runCampaign, runEval, runImprovementLoop, runReferenceEquivalenceJudge, selfImprove, summarizeExecution };