@tangle-network/agent-eval 0.118.3 → 0.119.0

package/dist/contract/index.d.ts

@@ -28,6 +28,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 +643,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;
@@ -1131,6 +1149,10 @@ interface AnalystContext {
     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 +1170,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 +1207,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 +1226,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 +1247,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
@@ -3961,7 +4017,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,13 +4030,36 @@ 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.
@@ -3985,9 +4067,9 @@ type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
  * 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.
+ * 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
@@ -4033,10 +4115,14 @@ interface TraceAnalystKindSpec {
     maxTurns?: number;
     /** Runtime char cap. Default 6000. */
     maxRuntimeChars?: number;
+    /** Maximum output tokens for every actor, responder, and recursive 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 +4134,7 @@ interface TraceAnalystKindSpec {
  */
 interface TraceAnalystGolden {
     question: string;
-    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
+    expected: ReadonlyArray<Omit<CanonicalRawAnalystFinding, 'confidence'>>;
 }
 
 /**
@@ -4106,7 +4192,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;
@@ -4136,6 +4223,10 @@ interface RegistryRunOpts {
     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 +4234,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 +4287,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[];

package/dist/contract/index.js

@@ -13,7 +13,7 @@ import {
 import {
   analyzeRuns,
   summarizeExecution
-} from "../chunk-7V3QDWNL.js";
+} from "../chunk-XJ7JVCHB.js";
 import {
   REFERENCE_EQUIVALENCE_INPUT_LIMITS,
   REFERENCE_EQUIVALENCE_JUDGE_VERSION,
@@ -34,20 +34,20 @@ import {
   runReferenceEquivalenceJudge,
   surfaceContentHash,
   surfaceHash
-} from "../chunk-QWRLW4CT.js";
+} from "../chunk-RLCJQ6VZ.js";
 import {
   createRunCostLedger,
   fsCampaignStorage,
   inMemoryCampaignStorage,
   resolveRunDir,
   runCampaign
-} from "../chunk-EGNRE7VA.js";
+} from "../chunk-PAHNGS65.js";
 import {
   buildDefaultAnalystRegistry,
   createChatClient
-} from "../chunk-267UCQWI.js";
+} from "../chunk-GERDAIAL.js";
 import "../chunk-HHWE3POT.js";
-import "../chunk-VNLWDTDA.js";
+import "../chunk-7A4LIMMY.js";
 import {
   FileSystemOutcomeStore,
   InMemoryOutcomeStore
@@ -56,7 +56,7 @@ import "../chunk-ARU2PZFM.js";
 import "../chunk-NJC7U437.js";
 import "../chunk-DPZAEKA6.js";
 import "../chunk-PJQFMIOX.js";
-import "../chunk-MLHRFWQK.js";
+import "../chunk-JHOJHHU7.js";
 import "../chunk-VI2UW6B6.js";
 import {
   recordAggregateMeasurements,

package/dist/fuzz.d.ts

@@ -1,8 +1,14 @@
 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;
@@ -69,7 +75,9 @@ interface ChannelRollup {
     calls: number;
     inputTokens: number;
     outputTokens: number;
+    reasoningTokens?: number;
     cachedTokens: number;
+    cacheWriteTokens?: number;
     costUsd: number;
     unpricedCalls: number;
     unknownUsageCalls: number;
@@ -81,7 +89,9 @@ interface CostLedgerSummary {
     reservedCostUsd: number;
     inputTokens: number;
     outputTokens: number;
+    reasoningTokens?: number;
     cachedTokens: number;
+    cacheWriteTokens?: number;
     totalCostUsd: number;
     byChannel: ChannelRollup[];
     unpricedModels: string[];
@@ -95,6 +105,10 @@ interface CostLedgerFilter {
     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(): {
@@ -114,6 +128,7 @@ declare class CostLedger {
     private readonly records;
     private readonly activeCallIds;
     private readonly lateCallIds;
+    private readonly idleWaiters;
     private completedTasks;
     private revision;
     private costLimitPersisted;
@@ -121,6 +136,8 @@ declare class CostLedger {
     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;
@@ -131,6 +148,7 @@ declare class CostLedger {
     costPerCompletedTask(): number | null;
     private execute;
     private captureLateOutcome;
+    private releaseActiveCall;
     private commitOutcome;
     private captureFailure;
     private commitReceipt;
@@ -146,7 +164,7 @@ declare class CostLedger {
  * Keeping callback contracts structural lets those subpaths compose while the
  * concrete {@link CostLedger} retains its private durable state.
  */
-type CostLedgerHandle = Pick<CostLedger, keyof CostLedger>;
+type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'waitForIdle'>> & Partial<Pick<CostLedger, 'waitForIdle'>>;
 
 /**
  * Adversarial mutation contract.

package/dist/fuzz.js

@@ -1,7 +1,7 @@
 import {
   CostLedger,
   CostReceiptCaptureError
-} from "./chunk-MLHRFWQK.js";
+} from "./chunk-JHOJHHU7.js";
 import "./chunk-VI2UW6B6.js";
 import {
   varianceBasedCurriculum