@tangle-network/agent-eval 0.129.0 → 0.130.0

package/dist/index-2JJSA6-r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-2JJSA6-r2.d.ts","names":[],"sources":["../src/rollout/exporters.ts","../src/rollout/gate-checks.ts","../src/rollout/interchange/harbor.ts","../src/rollout/ledger.ts","../src/rollout/reward.ts","../src/rollout/mint.ts","../src/rollout/readers/claude-jsonl.ts","../src/rollout/readers/opencode-sqlite.ts","../src/rollout/release/gate-report.ts","../src/rollout/release/scrub.ts","../src/rollout/release/card.ts","../src/rollout/release/hf-dataset.ts"],"mappings":"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"}

package/dist/index-6N0aYmpW.d.ts

@@ -0,0 +1,217 @@
+import { f as Run } from "./schema-BtVldJ3T.js";
+import { s as TraceStore } from "./store-CT9YIIve.js";
+import { a as OutcomeFilter, o as OutcomeStore } from "./outcome-store-BYHIuO0e.js";
+import "./rubric-predictive-validity-Ku_clp_1.js";
+import { a as ContinuousCalibrationResult, n as CandidateScore, o as GoldenItem, r as ContinuousAgreement, t as CalibrationResult } from "./judge-calibration-DFtEMlde.js";
+import { n as SeriesConvergenceResult, t as SeriesConvergenceOptions } from "./series-convergence-ofsqPWhs.js";
+import { i as CorpusAgreementReport } from "./statistics-Cmj6nynr.js";
+//#region src/meta-eval/correlation-study.d.ts
+interface EvalMetricSpec {
+  id: string;
+  /** Extract a scalar from a run (defaults cover score/pass/durationMs/costUsd/tokens). */
+  extract?: (run: Run, store: TraceStore) => Promise<number | null>;
+}
+interface OutcomePair {
+  evalMetric: string;
+  outcomeMetric: string;
+}
+interface CorrelationResult {
+  evalMetric: string;
+  outcomeMetric: string;
+  n: number;
+  pearson: number;
+  spearman: number;
+  /** 95% bootstrap CI for Pearson. */
+  pearsonCi95: {
+    lower: number;
+    upper: number;
+  };
+  /** Rough verdict: 'strong' ≥ 0.7, 'moderate' ≥ 0.4, else 'weak'. */
+  verdict: 'strong' | 'moderate' | 'weak';
+}
+interface CorrelationStudyResult {
+  pairs: CorrelationResult[];
+  joinedSamples: number;
+  skippedRuns: number;
+}
+interface CorrelationStudyOptions {
+  /** Only join outcomes captured within this window after run.startedAt. */
+  maxCaptureLagMs?: number;
+  /** Restrict to a subset of outcomes (cohort, region, source). */
+  outcomeFilter?: OutcomeFilter;
+  /** Which outcome per run to use when multiple exist. Default 'latest'. */
+  reduction?: 'latest' | 'mean' | 'max';
+  /** Bootstrap iterations for the CI. Default 500. */
+  bootstrapIterations?: number;
+}
+declare function correlationStudy(traceStore: TraceStore, outcomeStore: OutcomeStore, evalMetrics: EvalMetricSpec[], outcomeMetricNames: string[], options?: CorrelationStudyOptions): Promise<CorrelationStudyResult>;
+//#endregion
+//#region src/meta-eval/calibration.d.ts
+interface CalibrationBin {
+  lower: number;
+  upper: number;
+  n: number;
+  evalMean: number;
+  outcomeMean: number;
+  /** |outcomeMean − evalMean|; contributes to ECE weighted by n/total. */
+  gap: number;
+}
+interface CalibrationReport {
+  evalMetric: string;
+  outcomeMetric: string;
+  n: number;
+  bins: CalibrationBin[];
+  /** Expected Calibration Error — Σ (n_i/N) × |outcomeMean_i − evalMean_i|. */
+  ece: number;
+  /** Max bin gap — upper bound on miscalibration. */
+  maxGap: number;
+}
+interface CalibrationOptions {
+  bins?: number;
+  /** Equal-width (fixed bin edges) or equal-frequency (quantile bins). */
+  binning?: 'equal-width' | 'equal-frequency';
+  /** Clip eval values to [lo, hi] before binning. */
+  range?: {
+    lo: number;
+    hi: number;
+  };
+}
+interface CalibrationPair {
+  evalScore: number;
+  outcome: number;
+}
+declare function calibrationCurve(traceStore: TraceStore, outcomeStore: OutcomeStore, evalMetric: EvalMetricSpec, outcomeMetric: string, options?: CalibrationOptions): Promise<CalibrationReport | null>;
+declare function calibrationFromPairs(inputPairs: CalibrationPair[], evalMetric: string, outcomeMetric: string, options?: CalibrationOptions): CalibrationReport | null;
+//#endregion
+//#region src/meta-eval/sentinel.d.ts
+declare const SENTINEL_METRIC_NAMES: readonly ['irr', 'calibrationKappa', 'sentinelPassRate'];
+type SentinelMetricName = (typeof SENTINEL_METRIC_NAMES)[number];
+interface SentinelMetrics {
+  /** Inter-rater reliability — ICC(2,1) from agreement instruments. */
+  irr?: number;
+  /** Weighted κ vs the human golden set (`calibrateJudge*`). */
+  calibrationKappa?: number;
+  /** Fraction of a fixed sentinel golden set the judge still scores within tolerance. */
+  sentinelPassRate?: number;
+}
+interface SentinelSnapshot {
+  /** Caller-supplied ISO-8601 timestamp — the module never reads a clock. */
+  at: string;
+  judgeId: string;
+  /** Exact model identity behind the judge (pin the full version string). */
+  judgeModel: string;
+  /**
+   * Metrics measured at `at`. May be empty: an empty-metrics snapshot is a
+   * model-change marker — it records the new `judgeModel` immediately and
+   * the silent-upgrade alarm stays raised until a golden-grounded snapshot
+   * (calibrationKappa or sentinelPassRate) follows.
+   */
+  metrics: SentinelMetrics;
+}
+/** Identity + timestamp the caller supplies alongside an instrument output. */
+interface SnapshotMeta {
+  at: string;
+  judgeId: string;
+  judgeModel: string;
+}
+/** Shape guard for snapshots crossing a boundary (store append, JSONL load, report input). */
+declare function validateSentinelSnapshot(snapshot: SentinelSnapshot, source?: string): void;
+/**
+ * From `calibrateJudge` / `calibrateJudgeContinuous` output. Prefers the
+ * un-rounded continuous κ_w when the report carries one (integer κ
+ * discards information for [0,1] judges).
+ */
+declare function snapshotFromCalibration(report: CalibrationResult | ContinuousCalibrationResult, meta: SnapshotMeta): SentinelSnapshot;
+/**
+ * From `corpusInterRaterAgreement` (statistics.ts) or `continuousAgreement`
+ * (judge-calibration.ts) output. IRR = ICC(2,1) — the reliability
+ * coefficient both instruments compute. For ensemble-level agreement,
+ * `meta.judgeId` names the ensemble and `meta.judgeModel` pins its
+ * composition (e.g. a joined list of member model strings).
+ */
+declare function snapshotFromAgreement(report: CorpusAgreementReport | ContinuousAgreement, meta: SnapshotMeta): SentinelSnapshot;
+interface SentinelSetOptions {
+  /** Max |judge − human| for an item to count as passed. Default 0.1 (tuned for [0,1] scores). */
+  tolerance?: number;
+}
+/**
+ * From a rerun of a fixed sentinel golden set: the same `GoldenItem`s the
+ * judge was originally calibrated on, re-scored periodically. Pass rate =
+ * fraction of joined items where the judge stays within `tolerance` of the
+ * human score. Items the judge didn't score are excluded from the
+ * denominator; zero joined items is an error, not a 0% pass rate.
+ */
+declare function snapshotFromSentinelSet(scores: CandidateScore[], golden: GoldenItem[], meta: SnapshotMeta, options?: SentinelSetOptions): SentinelSnapshot;
+interface SentinelStore {
+  append(snapshot: SentinelSnapshot): Promise<void>;
+  /** All snapshots (optionally for one judge), in append order. */
+  history(judgeId?: string): Promise<SentinelSnapshot[]>;
+}
+declare function inMemorySentinelStore(initial?: SentinelSnapshot[]): SentinelStore;
+/**
+ * JSONL store — one snapshot per line, appended atomically per call.
+ * A corrupt or shape-invalid line is a loud error naming the file and
+ * line number: a sentinel history that silently drops records would
+ * defeat the drift detection it exists to provide.
+ */
+declare function fileSentinelStore(path: string): SentinelStore;
+interface SentinelThresholds {
+  /** Floor for irr — below it the judge ensemble is unreliable regardless of trend. Default 0.6. */
+  minIrr?: number;
+  /** Max tolerated calibrationKappa drop vs the series baseline. Default 0.15. */
+  maxKappaDrop?: number;
+  /** Max tolerated sentinelPassRate drop vs the series baseline. Default 0.1. */
+  maxSentinelDrop?: number;
+  /** Newest snapshot older than this (days, vs asOf) = the sentinel itself went blind. Default 30. */
+  staleAfterDays?: number;
+}
+interface JudgeSentinelOptions {
+  /** Caller-supplied ISO timestamp staleness is measured against. */
+  asOf: string;
+  thresholds?: SentinelThresholds;
+  /** Forwarded to `analyzeSeries` (window, stableCv, driftRun). */
+  convergence?: SeriesConvergenceOptions;
+}
+interface SentinelTrend {
+  judgeId: string;
+  metric: SentinelMetricName;
+  /** Verbatim `analyzeSeries` state for this judge×metric history. */
+  state: SeriesConvergenceResult['state'];
+  /** Newest value in the series. */
+  current: number;
+  /** Oldest value in the series — the reference the drop thresholds compare against. */
+  baseline: number;
+  /** current − baseline (signed; negative = decayed). */
+  drift: number;
+  alarmed: boolean;
+  reason?: string;
+}
+interface SentinelReport {
+  perJudge: SentinelTrend[];
+  alarms: string[];
+  healthy: boolean;
+  /**
+   * `judgeId:metric` pairs with too few snapshots for the convergence
+   * machine. Named, not counted — a blind spot you can't see is a blind
+   * spot you won't fix. Floor/drop checks still apply to thin series, so
+   * insufficient history alone never masks an alarm.
+   */
+  insufficientHistory: string[];
+}
+declare function judgeSentinelReport(history: SentinelSnapshot[], opts: JudgeSentinelOptions): SentinelReport;
+interface EvalHealthStamp {
+  healthy: boolean;
+  alarms: string[];
+}
+/**
+ * The object a campaign attaches to its verdicts. Compute it from the
+ * sentinel report in a post-campaign hook (or a nightly job feeding the
+ * next day's campaigns) and store it alongside the verdict payload.
+ * `healthy: false` means the judges that produced those verdicts have an
+ * unresolved drift / decay / silent-upgrade / staleness alarm — treat the
+ * verdicts as carrying an integrity warning until recalibration clears it.
+ */
+declare function evalHealthStamp(report: SentinelReport): EvalHealthStamp;
+//#endregion
+export { EvalMetricSpec as A, CalibrationPair as C, CorrelationResult as D, calibrationFromPairs as E, correlationStudy as M, CorrelationStudyOptions as O, CalibrationOptions as S, calibrationCurve as T, snapshotFromAgreement as _, SentinelMetrics as a, validateSentinelSnapshot as b, SentinelSnapshot as c, SentinelTrend as d, SnapshotMeta as f, judgeSentinelReport as g, inMemorySentinelStore as h, SentinelMetricName as i, OutcomePair as j, CorrelationStudyResult as k, SentinelStore as l, fileSentinelStore as m, JudgeSentinelOptions as n, SentinelReport as o, evalHealthStamp as p, SENTINEL_METRIC_NAMES as r, SentinelSetOptions as s, EvalHealthStamp as t, SentinelThresholds as u, snapshotFromCalibration as v, CalibrationReport as w, CalibrationBin as x, snapshotFromSentinelSet as y };
+//# sourceMappingURL=index-6N0aYmpW.d.ts.map

package/dist/index-6N0aYmpW.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-6N0aYmpW.d.ts","names":[],"sources":["../src/meta-eval/correlation-study.ts","../src/meta-eval/calibration.ts","../src/meta-eval/sentinel.ts"],"mappings":";;;;;;;;UAiBiB;EACf;;EAEA,WAAW,KAAK,KAAK,OAAO,eAAe;;UAG5B;EACf;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;;EAEA;IAAe;IAAe;;;EAE9B;;UAGe;EACf,OAAO;EACP;EACA;;UAGe;;EAEf;;EAEA,gBAAgB;;EAEhB;;EAEA;;iBAGoB,iBACpB,YAAY,YACZ,cAAc,cACd,aAAa,kBACb,8BACA,UAAS,0BACR,QAAQ;;;UCjDM;EACf;EACA;EACA;EACA;EACA;;EAEA;;UAGe;EACf;EACA;EACA;EACA,MAAM;;EAEN;;EAEA;;UAGe;EACf;;EAEA;;EAEA;IAAU;IAAY;;;UAGP;EACf;EACA;;iBAGoB,iBACpB,YAAY,YACZ,cAAc,cACd,YAAY,gBACZ,uBACA,UAAS,qBACR,QAAQ;iBAgCK,qBACd,YAAY,mBACZ,oBACA,uBACA,UAAS,qBACR;;;cCtCU;KAED,6BAA6B;UAExB;;EAEf;;EAEA;;EAEA;;UAGe;;EAEf;EACA;;EAEA;;;;;;;EAOA,SAAS;;;UAIM;EACf;EACA;EACA;;;iBAcc,yBAAyB,UAAU,kBAAkB;;;;;;iBAiCrD,wBACd,QAAQ,oBAAoB,6BAC5B,MAAM,eACL;;;;;;;;iBAmBa,sBACd,QAAQ,wBAAwB,qBAChC,MAAM,eACL;UAYc;;EAEf;;;;;;;;;iBAUc,wBACd,QAAQ,kBACR,QAAQ,cACR,MAAM,cACN,UAAS,qBACR;UA4Cc;EACf,OAAO,UAAU,mBAAmB;;EAEpC,QAAQ,mBAAmB,QAAQ;;iBAGrB,sBAAsB,UAAS,qBAA0B;;;;;;;iBAqBzD,kBAAkB,eAAe;UA0ChC;;EAEf;;EAEA;;EAEA;;EAEA;;UAGe;;EAEf;EACA,aAAa;;EAEb,cAAc;;UAGC;EACf;EACA,QAAQ;;EAER,OAAO;;EAEP;;EAEA;;EAEA;EACA;EACA;;UAGe;EACf,UAAU;EACV;EACA;;;;;;;EAOA;;iBAKc,oBACd,SAAS,oBACT,MAAM,uBACL;UA6Gc;EACf;EACA;;;;;;;;;;iBAWc,gBAAgB,QAAQ,iBAAiB"}

package/dist/index-BAvgST_9.d.ts

@@ -0,0 +1,131 @@
+//#region src/ledger-core/atomic-file-lock.d.ts
+/** Crash-safe filesystem lock shared by campaign persistence and run exclusion. */
+interface AtomicFileLockOwner {
+  readonly pid: number;
+  readonly host: string;
+  readonly nonce: string;
+}
+interface AtomicFileLock {
+  readonly owner: AtomicFileLockOwner;
+  release(): void;
+}
+type AtomicFileLockUnavailable = {
+  readonly acquired: false;
+  readonly reason: 'held';
+  readonly holder: AtomicFileLockOwner;
+} | {
+  readonly acquired: false;
+  readonly reason: 'recovery';
+};
+type AtomicFileLockAcquisition = {
+  readonly acquired: true;
+  readonly lock: AtomicFileLock;
+} | AtomicFileLockUnavailable;
+interface AtomicFileLockOptions {
+  readonly lockPath: string;
+  readonly pid?: number;
+}
+declare class AtomicFileLockError extends Error {
+  readonly name = "AtomicFileLockError";
+}
+/** Report whether another lock path prevents acquisition without modifying it. */
+declare function probeAtomicFileLock(options: AtomicFileLockOptions): AtomicFileLockUnavailable | null;
+/**
+ * Try to acquire a complete, uniquely-owned lock inode.
+ *
+ * A hard link publishes fully-written owner metadata atomically. Stale-owner
+ * removal is serialized so one reclaimer cannot delete a new owner's lock.
+ */
+declare function tryAcquireAtomicFileLock(options: AtomicFileLockOptions): AtomicFileLockAcquisition;
+//#endregion
+//#region src/ledger-core/journal-file.d.ts
+/** Filesystem durability and cross-process exclusion for append-only journal files. */
+/** How a journal binding reports file-layer faults in its own error taxonomy. */
+interface LedgerFileContext {
+  /** Noun used in error messages, e.g. 'search ledger'. */
+  subject: string;
+  integrityError(message: string, options?: {
+    cause?: unknown;
+  }): Error;
+}
+/** Append one already-serialized line; the write is fsynced (file and directory)
+ * before returning so an acknowledged append survives a crash. */
+declare function appendLedgerLine(path: string, line: string, context: LedgerFileContext): void;
+declare function withLedgerFileLock<T>(path: string, context: LedgerFileContext, run: () => T): T;
+type FileLockResult<T> = {
+  acquired: true;
+  value: T;
+} | {
+  acquired: false;
+};
+declare function tryWithLedgerFileLock<T>(path: string, context: LedgerFileContext, run: () => T): FileLockResult<T>;
+//#endregion
+//#region src/ledger-core/journal.d.ts
+type LedgerHash = `sha256:${string}`;
+/** Canonical JSON encoding: object keys sorted recursively. This is the byte
+ * form that is hashed and stored, so identical values always encode identically. */
+declare function canonicalString(value: unknown): string;
+declare function hashCanonical(value: unknown): LedgerHash;
+/** Minimum shape of a journal event: the idempotency key. */
+interface LedgerEventBase {
+  eventId: string;
+}
+/** Chain envelope every entry carries in addition to the journal's constant
+ * header fields. `entryHash` covers the header, sequence, previous hash, and
+ * event, so any rewrite of history invalidates every later entry. */
+interface LedgerChainFields<Event extends LedgerEventBase> {
+  sequence: number;
+  previousHash: LedgerHash | null;
+  event: Event;
+  entryHash: LedgerHash;
+}
+type LedgerEntryOf<Header extends object, Event extends LedgerEventBase> = Header & LedgerChainFields<Event>;
+interface LedgerLineContext {
+  path: string;
+  line: number;
+}
+/** Domain state machine replayed over chain-verified entries in order.
+ * `apply` throws (via the codec's error taxonomy) on an invalid transition;
+ * `finish` builds the consumer's projection once every entry was applied. */
+interface LedgerProjector<Entry, Projection> {
+  apply(entry: Entry, index: number): void;
+  finish(entries: Entry[]): Projection;
+}
+interface LedgerJournalCodec<Header extends object, Event extends LedgerEventBase, Projection> extends LedgerFileContext {
+  /** Constant fields stamped into every entry and covered by its hash. */
+  header: Header;
+  conflictError(message: string): Error;
+  /** Validate one parsed JSON row into a typed entry. Must reject malformed
+   * rows and non-canonical event encodings with the binding's own errors;
+   * the journal itself verifies the stored bytes and the hash chain. */
+  parseEntry(raw: unknown, context: LedgerLineContext): LedgerEntryOf<Header, Event>;
+  /** Reject an entry whose constant header fields do not match this journal. */
+  checkEntryHeader(entry: LedgerEntryOf<Header, Event>, index: number): void;
+  createProjector(): LedgerProjector<LedgerEntryOf<Header, Event>, Projection>;
+}
+interface LedgerReplayResult<Entry, Projection> {
+  entries: Entry[];
+  projection: Projection;
+}
+interface LedgerAppendResult<Entry, Projection> {
+  entry: Entry;
+  /** False when the exact event was already durably present. */
+  appended: boolean;
+  projection: Projection;
+}
+/** Durable filesystem journal. Construction performs no I/O; `append` and
+ * `replay` validate the complete existing file under the locks. */
+declare class FileLedgerJournal<Header extends object, Event extends LedgerEventBase, Projection> {
+  readonly path: string;
+  private readonly codec;
+  private readonly mutex;
+  constructor(path: string, codec: LedgerJournalCodec<Header, Event, Projection>);
+  replay(): Promise<LedgerReplayResult<LedgerEntryOf<Header, Event>, Projection>>;
+  append(event: Event): Promise<LedgerAppendResult<LedgerEntryOf<Header, Event>, Projection>>;
+  private replayLocked;
+  private readEntries;
+  private project;
+}
+//#endregion
+export { AtomicFileLockUnavailable as C, AtomicFileLockOwner as S, tryAcquireAtomicFileLock as T, withLedgerFileLock as _, LedgerEventBase as a, AtomicFileLockError as b, LedgerLineContext as c, canonicalString as d, hashCanonical as f, tryWithLedgerFileLock as g, appendLedgerLine as h, LedgerEntryOf as i, LedgerProjector as l, LedgerFileContext as m, LedgerAppendResult as n, LedgerHash as o, FileLockResult as p, LedgerChainFields as r, LedgerJournalCodec as s, FileLedgerJournal as t, LedgerReplayResult as u, AtomicFileLock as v, probeAtomicFileLock as w, AtomicFileLockOptions as x, AtomicFileLockAcquisition as y };
+//# sourceMappingURL=index-BAvgST_9.d.ts.map

package/dist/index-BAvgST_9.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BAvgST_9.d.ts","names":[],"sources":["../src/ledger-core/atomic-file-lock.ts","../src/ledger-core/journal-file.ts","../src/ledger-core/journal.ts"],"mappings":";;UAiBiB;WACN;WACA;WACA;;UAGM;WACN,OAAO;EAChB;;KAGU;WACG;WAA0B;WAAyB,QAAQ;;WAC3D;WAA0B;;KAE7B;WACG;WAAyB,MAAM;IAC1C;UAEa;WACN;WACA;;cAGE,4BAA4B;WACrB;;;iBASJ,oBACd,SAAS,wBACR;;;;;;;iBAea,yBACd,SAAS,wBACR;;;;;UC/Dc;;EAEf;EACA,eAAe,iBAAiB;IAAY;MAAoB;;;;iBAKlD,iBAAiB,cAAc,cAAc,SAAS;iBAYtD,mBAAmB,GAAG,cAAc,SAAS,mBAAmB,WAAW,IAAI;KAQnF,eAAe;EAAO;EAAgB,OAAO;;EAAQ;;iBAEjD,sBAAsB,GACpC,cACA,SAAS,mBACT,WAAW,IACV,eAAe;;;KClBN;;;iBAII,gBAAgB;iBAIhB,cAAc,iBAAiB;;UAK9B;EACf;;;;;UAMe,kBAAkB,cAAc;EAC/C;EACA,cAAc;EACd,OAAO;EACP,WAAW;;KAGD,cAAc,uBAAuB,cAAc,mBAAmB,SAChF,kBAAkB;UAEH;EACf;EACA;;;;;UAMe,gBAAgB,OAAO;EACtC,MAAM,OAAO,OAAO;EACpB,OAAO,SAAS,UAAU;;UAGX,mBACf,uBACA,cAAc,iBACd,oBACQ;;EAER,QAAQ;EACR,cAAc,kBAAkB;;;;EAIhC,WAAW,cAAc,SAAS,oBAAoB,cAAc,QAAQ;;EAE5E,iBAAiB,OAAO,cAAc,QAAQ,QAAQ;EACtD,mBAAmB,gBAAgB,cAAc,QAAQ,QAAQ;;UAGlD,mBAAmB,OAAO;EACzC,SAAS;EACT,YAAY;;UAGG,mBAAmB,OAAO;EACzC,OAAO;;EAEP;EACA,YAAY;;;;cAiBD,kBAAkB,uBAAuB,cAAc,iBAAiB;WAC1E;mBACQ;mBACA;EAEjB,YAAY,cAAc,OAAO,mBAAmB,QAAQ,OAAO;EAM7D,UAAU,QAAQ,mBAAmB,cAAc,QAAQ,QAAQ;EAMnE,OACJ,OAAO,QACN,QAAQ,mBAAmB,cAAc,QAAQ,QAAQ;UA+BpD;UAKA;UAuCA"}

package/dist/index-BvnJuTGD.d.ts

@@ -0,0 +1,68 @@
+import { u as RunTokenUsage } from "./run-record-CnZu_gjl.js";
+import { l as RawProviderSink, o as ProviderRedactor } from "./raw-provider-sink-BU29Sh8h.js";
+//#region src/trace/extract-usage.d.ts
+type ExtractedUsage = RunTokenUsage;
+type SseUsageMode = 'cumulative' | 'delta';
+interface ExtractUsageFromSseOptions {
+  /** Provider usage events are cumulative snapshots unless explicitly marked as deltas. */
+  mode?: SseUsageMode;
+}
+/**
+ * Pull `{ input, output, cached?, cacheWrite? }` from a parsed response
+ * body. Accepts a top-level `usage` object (the common case) or a body that IS
+ * the usage object. Returns null only when none of those categories is present.
+ */
+declare function extractUsage(body: unknown): ExtractedUsage | null;
+/**
+ * Extract token usage from a complete SSE response body using the shared SSE
+ * frame parser. Cumulative snapshots are the fail-safe default because summing
+ * them inflates billing; callers with explicit delta events opt into `mode: 'delta'`.
+ */
+declare function extractUsageFromSse(text: string, options?: ExtractUsageFromSseOptions): ExtractedUsage | null;
+/**
+ * Extract usage from an HTTP `Response` without consuming the caller's body:
+ * clones, reads the text, and tries the JSON parser first, then the SSE
+ * accumulator. Best-effort — returns null on any read/parse miss so a usage tee
+ * never takes down the underlying call.
+ */
+declare function extractUsageFromResponse(response: Response, sseOptions?: ExtractUsageFromSseOptions): Promise<ExtractedUsage | null>;
+//#endregion
+//#region src/trace/capture-fetch.d.ts
+interface CaptureFetchContext {
+  /** Logical run id stamped on every captured event. Required — without it
+   *  the raw events can't be paired with their parent `Run`. */
+  runId: string;
+  /** Optional logical span id (enables span-level sink filtering). */
+  spanId?: string;
+  /** Resolved base URL (normalised, no trailing slash). Used for the event's
+   *  `baseUrl` and for endpoint-path extraction. */
+  baseUrl: string;
+  /** Model id the caller intends to invoke. Stamped on every event. */
+  model: string;
+  /** Provider override. When omitted, `providerFromBaseUrl(baseUrl)`. */
+  provider?: string;
+}
+interface CaptureFetchOptions {
+  /** Override the capture-time redactor. Default `defaultProviderRedactor`. */
+  redactor?: ProviderRedactor;
+  /** Cap on captured response-body bytes; beyond it the body is truncated and
+   *  `body_truncated` is added to `redactedFields`. Default 2 MiB. */
+  responseBodyByteCap?: number;
+  /** When true, a sink-write failure propagates to the caller. Default false
+   *  — capture is best-effort so a sink failure never kills the LLM call. */
+  failClosed?: boolean;
+  /**
+   * Invoked with the token usage parsed off each successful response (JSON or
+   * SSE), keyed by the captured context. Lets a caller fold usage → cost without
+   * re-cloning the response themselves. Not called when the response carries no
+   * usage. Best-effort: a throw here is swallowed (it never kills the LLM call)
+   * unless `failClosed` is set.
+   */
+  onUsage?: (usage: ExtractedUsage, ctx: CaptureFetchContext) => void;
+  /** How repeated SSE usage events should be reconciled. Default `cumulative`. */
+  sseUsageMode?: SseUsageMode;
+}
+declare function captureFetchToRawSink(fetch: typeof globalThis.fetch, sink: RawProviderSink, ctx: CaptureFetchContext, opts?: CaptureFetchOptions): typeof globalThis.fetch;
+//#endregion
+export { ExtractedUsage as a, extractUsageFromResponse as c, ExtractUsageFromSseOptions as i, extractUsageFromSse as l, CaptureFetchOptions as n, SseUsageMode as o, captureFetchToRawSink as r, extractUsage as s, CaptureFetchContext as t };
+//# sourceMappingURL=index-BvnJuTGD.d.ts.map

package/dist/index-BvnJuTGD.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BvnJuTGD.d.ts","names":[],"sources":["../src/trace/extract-usage.ts","../src/trace/capture-fetch.ts"],"mappings":";;;KAgBY,iBAAiB;KACjB;UAEK;;EAEf,OAAO;;;;;;;iBAuDO,aAAa,gBAAgB;;;;;;iBA6C7B,oBACd,cACA,UAAS,6BACR;;;;;;;iBA4DmB,yBACpB,UAAU,UACV,aAAa,6BACZ,QAAQ;;;UCrKM;;;EAGf;;EAEA;;;EAGA;;EAEA;;EAEA;;UAGe;;EAEf,WAAW;;;EAGX;;;EAGA;;;;;;;;EAQA,WAAW,OAAO,gBAAgB,KAAK;;EAEvC,eAAe;;iBAkDD,sBACd,cAAc,WAAW,OACzB,MAAM,iBACN,KAAK,qBACL,OAAM,6BACE,WAAW"}