@tangle-network/agent-eval 0.128.2 → 0.130.0

package/dist/exporters-q9iL-2Jf.js

@@ -0,0 +1,148 @@
+import { l as assertRewardGate } from "./schema-C6DW4ZHR.js";
+//#region src/rollout/exporters.ts
+function realnessLabels(line) {
+	return {
+		realness_gated: line.outcome.realness_gated === true,
+		realness_screened: line.outcome.realness_screened ?? null
+	};
+}
+/**
+* Supervised fine-tune rows: the completed conversation of each qualifying
+* line. Fail-closed filters: trainable split only (never holdout/canary),
+* reward strictly above `minimumQualityExclusive` (default 0), realness-gated
+* lines never qualify, gap lines carry no trainable content, and
+* copied-context turns are dropped from the transcript (Harbor ATIF RFC 0001
+* rule 7 — see `ChatMessage.is_copied_context`).
+*
+* `realness_gated` is therefore always `false` on an emitted row. It is carried
+* anyway: an SFT row is a pure imitation target, so the row states its realness
+* claims instead of making the reader know the format's policy, and carrying
+* both flags on all four shapes is what lets the release accounting measure
+* every config with one rule rather than skipping the one whose row shape
+* happened to omit the field.
+*/
+function toSftRows(lines, options = {}) {
+	for (const line of lines) assertRewardGate(line, "SFT export");
+	return lines.filter((line) => isTrainingLineEligible(line, options) && line.messages.length > 0).map((line) => ({
+		messages: line.messages.filter((message) => message.is_copied_context !== true),
+		metadata: {
+			rollout_id: line.rollout_id,
+			run_id: line.run_id,
+			candidate_id: line.candidate_id ?? null,
+			instance_id: line.task.instance_id,
+			reward: line.outcome.reward,
+			...realnessLabels(line)
+		}
+	})).filter((row) => row.messages.length > 0);
+}
+/**
+* Reward-labeled rows for completed, positive-quality training runs.
+*/
+function toRewardRows(lines, options = {}) {
+	for (const line of lines) assertRewardGate(line, "reward-row export");
+	return lines.filter((line) => isTrainingLineEligible(line, options) && line.messages.some((message) => message.role === "user" && typeof message.content === "string" && message.content.length > 0)).map((line) => ({
+		prompt: line.messages.find((m) => m.role === "user")?.content ?? "",
+		steps: line.steps ?? [],
+		reward: line.outcome.reward,
+		metadata: {
+			rollout_id: line.rollout_id,
+			run_id: line.run_id,
+			candidate_id: line.candidate_id ?? null,
+			instance_id: line.task.instance_id,
+			split: line.task.split,
+			...realnessLabels(line)
+		}
+	}));
+}
+/** Index of the first assistant turn; messages.length when none exists. */
+function firstAssistantIndex(messages) {
+	const index = messages.findIndex((m) => m.role === "assistant");
+	return index === -1 ? messages.length : index;
+}
+function toVerifiersRolloutOutput(line) {
+	assertRewardGate(line, "verifiers export");
+	const split = firstAssistantIndex(line.messages);
+	return {
+		prompt: line.messages.slice(0, split),
+		completion: line.messages.slice(split),
+		reward: line.outcome.reward,
+		metrics: line.outcome.metrics,
+		tool_defs: line.tool_defs,
+		token_usage: {
+			input_tokens: line.cost.tokens_in,
+			output_tokens: line.cost.tokens_out,
+			reasoning_tokens: line.cost.tokens_reasoning,
+			cache_read_tokens: line.cost.cache_read,
+			cache_write_tokens: line.cost.cache_write
+		},
+		info: {
+			task: line.task,
+			policy: line.policy,
+			rollout_id: line.rollout_id,
+			run_id: line.run_id,
+			experiment_id: line.experiment_id ?? null,
+			candidate_id: line.candidate_id ?? null,
+			generation: line.generation,
+			candidate_index: line.candidate_index,
+			role: line.role,
+			...realnessLabels(line)
+		}
+	};
+}
+function toVerifiersRolloutOutputs(lines, options = {}) {
+	if (options.gatedLines === "zero-and-flag") return lines.filter((line) => isSplitEligible(line, options) && line.messages.length > 0).map(toVerifiersRolloutOutput);
+	return lines.filter((line) => isTrainingLineEligible(line, options) && firstAssistantIndex(line.messages) > 0 && firstAssistantIndex(line.messages) < line.messages.length).map(toVerifiersRolloutOutput);
+}
+function toRftItem(line) {
+	assertRewardGate(line, "RFT export");
+	const split = firstAssistantIndex(line.messages);
+	return {
+		messages: line.messages.slice(0, split),
+		reference: {
+			reward: line.outcome.reward,
+			reward_source: line.outcome.reward_source,
+			verdict: line.outcome.verdict,
+			instance_id: line.task.instance_id,
+			suite: line.task.suite,
+			split: line.task.split,
+			rollout_id: line.rollout_id,
+			...realnessLabels(line)
+		}
+	};
+}
+/** RFT needs a real prompt: lines whose transcript starts with prompt turns. */
+function toRftItems(lines, options = {}) {
+	return lines.filter((line) => (options.gatedLines === "zero-and-flag" ? isSplitEligible(line, options) : isTrainingLineEligible(line, options)) && line.messages.length > 0 && firstAssistantIndex(line.messages) > 0).map(toRftItem);
+}
+function toJsonl(rows) {
+	return rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : "");
+}
+/**
+* The split half of the training policy alone: `search` is trainable, held-out
+* needs the named opt-in, `dev` and `canary` never ship. This is the ONE check
+* `'zero-and-flag'` does not relax — a gated line is shipped as a labeled
+* negative, not as a licence to train on evaluation data.
+*
+* Exported as the single implementation of that rule: `rl/exporters` applies
+* it on its line paths too, so the two waists cannot drift on which splits are
+* trainable.
+*/
+function isSplitEligible(line, options) {
+	if (line.task.split === "search") return true;
+	return line.task.split === "holdout" && options.allowHeldOutTrainingData === true;
+}
+function isTrainingLineEligible(line, options) {
+	const minimumQualityExclusive = options.minimumQualityExclusive ?? 0;
+	if (!Number.isFinite(minimumQualityExclusive)) throw new Error("minimumQualityExclusive must be finite");
+	const reward = line.outcome.reward;
+	if (reward === null) return false;
+	if (!Number.isFinite(reward)) throw new Error(`training reward for rollout "${line.rollout_id}" must be finite`);
+	if (reward <= minimumQualityExclusive) return false;
+	if (!line.outcome.is_completed || line.outcome.is_truncated || line.outcome.error !== null) return false;
+	if (line.outcome.realness_gated === true) return false;
+	return isSplitEligible(line, options);
+}
+//#endregion
+export { toRftItem as a, toVerifiersRolloutOutput as c, toRewardRows as i, toVerifiersRolloutOutputs as l, realnessLabels as n, toRftItems as o, toJsonl as r, toSftRows as s, isSplitEligible as t };
+
+//# sourceMappingURL=exporters-q9iL-2Jf.js.map

package/dist/exporters-q9iL-2Jf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporters-q9iL-2Jf.js","names":[],"sources":["../src/rollout/exporters.ts"],"sourcesContent":["/**\n * Pure exporters over `tangle.rollout.v1` lines → the training-data shapes\n * the improvement loops feed:\n *   - SFT chat JSONL           (clean trainable successes, {messages, metadata})\n *   - reward rows              (every scored line, success or failure, with steps)\n *   - Prime Intellect verifiers RolloutOutput (prompt/completion split + reward)\n *   - OpenAI RFT items         (prompt turns + verdict reference fields)\n *\n * All exporters are pure functions of the lines — filtering (never train on\n * holdout, reward thresholds, the realness gate) happens HERE, on inline\n * labels, no joins.\n *\n * Every exporter takes `MintedRolloutLine[]`, not `RolloutLine[]`: the reward\n * on a minted line has been checked against the anti-Goodhart invariant, and\n * the brand is what stops a hand-built object literal claiming a positive\n * reward on a gamed run from being handed to an exporter that copies it\n * verbatim into training data.\n */\n\nimport type {\n  ChatMessage,\n  MintedRolloutLine,\n  RolloutLine,\n  RolloutSplit,\n  RolloutStep,\n  ToolDef,\n} from './schema'\nimport { assertRewardGate } from './schema'\n\n// ---------------------------------------------------------------------------\n// The realness claims every emitted row carries.\n// ---------------------------------------------------------------------------\n\n/**\n * The gate's two claims, which travel TOGETHER on every emitted row.\n *\n * `realness_gated` alone is ambiguous, and the ambiguity is exploitable:\n * `false` reads as \"we screened it and nothing fired\", so a producer that has no\n * screen at all emitted rows indistinguishable from screened-clean ones, and\n * every consumer of the published dataset read them as clean. The second field\n * is what separates the two claims, and it only removes the ambiguity if it\n * reaches the WIRE — for a round it existed on `RolloutOutcome` and on no\n * exported row shape at all, which left the published rows exactly as ambiguous\n * as before.\n *\n * So there is one helper and every row shape spreads it. A row that states one\n * claim without the other is not constructible by copying the pattern, and\n * `exporters.test.ts` walks every emitted shape to prove none does.\n */\nexport interface RealnessLabels {\n  /** The screen's VERDICT: the run faked its success signal. */\n  realness_gated: boolean\n  /**\n   * Whether a screen RAN at all. `true` = it ran, so `realness_gated` is its\n   * verdict. `false` = the producer declares it has none. `null` = not stated\n   * (pre-unification producers), which is \"unknown\" and never \"clean\".\n   */\n  realness_screened: boolean | null\n}\n\nexport function realnessLabels(line: MintedRolloutLine): RealnessLabels {\n  return {\n    realness_gated: line.outcome.realness_gated === true,\n    // `?? null` rather than `?? false`: absent means the producer never stated\n    // it, and `false` is a load-bearing claim (\"no screen exists\") that would be\n    // an invention here.\n    realness_screened: line.outcome.realness_screened ?? null,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// (a) SFT chat JSONL\n// ---------------------------------------------------------------------------\n\nexport interface TrainingExportOptions {\n  /** Include held-out evaluation data in training output. Default false. */\n  allowHeldOutTrainingData?: boolean\n  /** Require reward to be strictly greater than this value. Default 0. */\n  minimumQualityExclusive?: number\n}\n\n/**\n * What a signed-signal exporter (verifiers, RFT) does with lines that are not\n * clean trainable successes — realness-gated lines above all.\n *\n *   - 'exclude'       — the default, the same fail-closed policy as every\n *                       other training export: positive, completed,\n *                       non-gated rows on a trainable split.\n *   - 'zero-and-flag' — keep them, at their non-positive (or null) reward,\n *                       with `RealnessLabels` on the row. The dataset release\n *                       sets this per `FORMAT_GATE_DISPOSITION`: in these\n *                       formats the reward is a signed learning signal, so a\n *                       gamed trajectory at reward 0 is a correct negative,\n *                       and dropping it would bias the negative population\n *                       toward honest failures and leave a trainer no example\n *                       of gaming being penalized. The split policy is NOT\n *                       relaxed: held-out lines still need the named opt-in.\n *\n * SFT deliberately has no such option — an SFT row is an imitation target and\n * a gamed trajectory must never appear in one at any weight.\n */\nexport type GatedLineDisposition = 'exclude' | 'zero-and-flag'\n\nexport interface SignedSignalExportOptions extends TrainingExportOptions {\n  /** Disposition for non-trainable lines. Default 'exclude'. */\n  gatedLines?: GatedLineDisposition\n}\n\nexport type SftExportOptions = TrainingExportOptions\n\nexport interface SftRow {\n  messages: ChatMessage[]\n  metadata: {\n    rollout_id: string\n    run_id: string\n    candidate_id: string | null\n    instance_id: string\n    reward: number\n  } & RealnessLabels\n}\n\n/**\n * Supervised fine-tune rows: the completed conversation of each qualifying\n * line. Fail-closed filters: trainable split only (never holdout/canary),\n * reward strictly above `minimumQualityExclusive` (default 0), realness-gated\n * lines never qualify, gap lines carry no trainable content, and\n * copied-context turns are dropped from the transcript (Harbor ATIF RFC 0001\n * rule 7 — see `ChatMessage.is_copied_context`).\n *\n * `realness_gated` is therefore always `false` on an emitted row. It is carried\n * anyway: an SFT row is a pure imitation target, so the row states its realness\n * claims instead of making the reader know the format's policy, and carrying\n * both flags on all four shapes is what lets the release accounting measure\n * every config with one rule rather than skipping the one whose row shape\n * happened to omit the field.\n */\nexport function toSftRows(lines: MintedRolloutLine[], options: SftExportOptions = {}): SftRow[] {\n  for (const line of lines) assertRewardGate(line, 'SFT export')\n  return lines\n    .filter((line) => isTrainingLineEligible(line, options) && line.messages.length > 0)\n    .map((line) => ({\n      // Dropped, not kept-and-masked: a copied-context turn was authored by\n      // another agent, and an SFT trainer has no notion of \"present but not a\n      // target\" — every message it is handed is something to imitate.\n      messages: line.messages.filter((message) => message.is_copied_context !== true),\n      metadata: {\n        rollout_id: line.rollout_id,\n        run_id: line.run_id,\n        candidate_id: line.candidate_id ?? null,\n        instance_id: line.task.instance_id,\n        reward: line.outcome.reward as number,\n        ...realnessLabels(line),\n      },\n    }))\n    .filter((row) => row.messages.length > 0)\n}\n\n// ---------------------------------------------------------------------------\n// (b) Reward rows\n// ---------------------------------------------------------------------------\n\nexport interface RewardRow {\n  /** First user turn — the task prompt. */\n  prompt: string\n  steps: RolloutStep[]\n  reward: number\n  metadata: {\n    rollout_id: string\n    run_id: string\n    candidate_id: string | null\n    instance_id: string\n    split: RolloutSplit\n    /**\n     * The anti-Goodhart verdict AND whether a screen produced it, carried on the\n     * row rather than left implicit in a reward of 0. Zeroing alone is lossy: it\n     * makes a run that FAKED its success indistinguishable from one that\n     * honestly failed, so a consumer can neither drop the gamed population nor\n     * mine it (a labeled gamed trajectory is the training signal for a gaming\n     * detector). `realness_gated` alone is lossy the same way in the other\n     * direction — see `RealnessLabels`.\n     */\n  } & RealnessLabels\n}\n\n/**\n * Reward-labeled rows for completed, positive-quality training runs.\n */\nexport function toRewardRows(\n  lines: MintedRolloutLine[],\n  options: TrainingExportOptions = {},\n): RewardRow[] {\n  for (const line of lines) assertRewardGate(line, 'reward-row export')\n  return lines\n    .filter(\n      (line) =>\n        isTrainingLineEligible(line, options) &&\n        line.messages.some(\n          (message) =>\n            message.role === 'user' &&\n            typeof message.content === 'string' &&\n            message.content.length > 0,\n        ),\n    )\n    .map((line) => ({\n      prompt: line.messages.find((m) => m.role === 'user')?.content ?? '',\n      steps: line.steps ?? [],\n      reward: line.outcome.reward as number,\n      metadata: {\n        rollout_id: line.rollout_id,\n        run_id: line.run_id,\n        candidate_id: line.candidate_id ?? null,\n        instance_id: line.task.instance_id,\n        split: line.task.split,\n        ...realnessLabels(line),\n      },\n    }))\n}\n\n// ---------------------------------------------------------------------------\n// (c) Prime Intellect verifiers RolloutOutput\n// ---------------------------------------------------------------------------\n\nexport interface VerifiersTokenUsage {\n  input_tokens: number | null\n  output_tokens: number | null\n  reasoning_tokens: number | null\n  cache_read_tokens: number | null\n  cache_write_tokens: number | null\n}\n\nexport interface VerifiersRolloutOutput {\n  /** Messages through the last turn BEFORE the first assistant turn. */\n  prompt: ChatMessage[]\n  /** The first assistant turn onward — what the policy produced. */\n  completion: ChatMessage[]\n  reward: number | null\n  metrics: Record<string, unknown>\n  tool_defs: ToolDef[]\n  token_usage: VerifiersTokenUsage\n  info: {\n    task: RolloutLine['task']\n    policy: RolloutLine['policy']\n    rollout_id: string\n    run_id: string\n    experiment_id: string | null\n    candidate_id: string | null\n    generation: number | null\n    candidate_index: number | null\n    role: RolloutLine['role']\n  } & RealnessLabels\n}\n\n/** Index of the first assistant turn; messages.length when none exists. */\nfunction firstAssistantIndex(messages: ChatMessage[]): number {\n  const index = messages.findIndex((m) => m.role === 'assistant')\n  return index === -1 ? messages.length : index\n}\n\nexport function toVerifiersRolloutOutput(line: MintedRolloutLine): VerifiersRolloutOutput {\n  assertRewardGate(line, 'verifiers export')\n  const split = firstAssistantIndex(line.messages)\n  return {\n    prompt: line.messages.slice(0, split),\n    completion: line.messages.slice(split),\n    reward: line.outcome.reward,\n    metrics: line.outcome.metrics,\n    tool_defs: line.tool_defs,\n    token_usage: {\n      input_tokens: line.cost.tokens_in,\n      output_tokens: line.cost.tokens_out,\n      reasoning_tokens: line.cost.tokens_reasoning,\n      cache_read_tokens: line.cost.cache_read,\n      cache_write_tokens: line.cost.cache_write,\n    },\n    info: {\n      task: line.task,\n      policy: line.policy,\n      rollout_id: line.rollout_id,\n      run_id: line.run_id,\n      experiment_id: line.experiment_id ?? null,\n      candidate_id: line.candidate_id ?? null,\n      generation: line.generation,\n      candidate_index: line.candidate_index,\n      role: line.role,\n      ...realnessLabels(line),\n    },\n  }\n}\n\nexport function toVerifiersRolloutOutputs(\n  lines: MintedRolloutLine[],\n  options: SignedSignalExportOptions = {},\n): VerifiersRolloutOutput[] {\n  if (options.gatedLines === 'zero-and-flag') {\n    return lines\n      .filter((line) => isSplitEligible(line, options) && line.messages.length > 0)\n      .map(toVerifiersRolloutOutput)\n  }\n  return lines\n    .filter(\n      (line) =>\n        isTrainingLineEligible(line, options) &&\n        firstAssistantIndex(line.messages) > 0 &&\n        firstAssistantIndex(line.messages) < line.messages.length,\n    )\n    .map(toVerifiersRolloutOutput)\n}\n\n// ---------------------------------------------------------------------------\n// (d) OpenAI RFT items\n// ---------------------------------------------------------------------------\n\nexport interface RftItem {\n  /** Prompt turns only — the graded completion is re-sampled during RFT. */\n  messages: ChatMessage[]\n  /** Verdict/label fields the grader references as item.reference.* */\n  reference: {\n    reward: number | null\n    reward_source: string | null\n    verdict: unknown\n    instance_id: string\n    suite: string\n    split: RolloutSplit\n    rollout_id: string\n  } & RealnessLabels\n}\n\nexport function toRftItem(line: MintedRolloutLine): RftItem {\n  assertRewardGate(line, 'RFT export')\n  const split = firstAssistantIndex(line.messages)\n  return {\n    messages: line.messages.slice(0, split),\n    reference: {\n      reward: line.outcome.reward,\n      reward_source: line.outcome.reward_source,\n      verdict: line.outcome.verdict,\n      instance_id: line.task.instance_id,\n      suite: line.task.suite,\n      split: line.task.split,\n      rollout_id: line.rollout_id,\n      ...realnessLabels(line),\n    },\n  }\n}\n\n/** RFT needs a real prompt: lines whose transcript starts with prompt turns. */\nexport function toRftItems(\n  lines: MintedRolloutLine[],\n  options: SignedSignalExportOptions = {},\n): RftItem[] {\n  return lines\n    .filter(\n      (line) =>\n        (options.gatedLines === 'zero-and-flag'\n          ? isSplitEligible(line, options)\n          : isTrainingLineEligible(line, options)) &&\n        line.messages.length > 0 &&\n        firstAssistantIndex(line.messages) > 0,\n    )\n    .map(toRftItem)\n}\n\n// ---------------------------------------------------------------------------\n// Serialization — one JSON object per line, the interchange format for\n// every export. `tangle.rollout.v1` lines and export rows alike.\n// ---------------------------------------------------------------------------\n\nexport function toJsonl(rows: ReadonlyArray<unknown>): string {\n  return rows.map((r) => JSON.stringify(r)).join('\\n') + (rows.length ? '\\n' : '')\n}\n\n/**\n * The split half of the training policy alone: `search` is trainable, held-out\n * needs the named opt-in, `dev` and `canary` never ship. This is the ONE check\n * `'zero-and-flag'` does not relax — a gated line is shipped as a labeled\n * negative, not as a licence to train on evaluation data.\n *\n * Exported as the single implementation of that rule: `rl/exporters` applies\n * it on its line paths too, so the two waists cannot drift on which splits are\n * trainable.\n */\nexport function isSplitEligible(\n  line: RolloutLine,\n  options: Pick<TrainingExportOptions, 'allowHeldOutTrainingData'>,\n): boolean {\n  if (line.task.split === 'search') return true\n  return line.task.split === 'holdout' && options.allowHeldOutTrainingData === true\n}\n\nfunction isTrainingLineEligible(\n  line: RolloutLine,\n  options: TrainingExportOptions,\n): line is RolloutLine & { outcome: RolloutLine['outcome'] & { reward: number } } {\n  const minimumQualityExclusive = options.minimumQualityExclusive ?? 0\n  if (!Number.isFinite(minimumQualityExclusive)) {\n    throw new Error('minimumQualityExclusive must be finite')\n  }\n\n  const reward = line.outcome.reward\n  if (reward === null) return false\n  if (!Number.isFinite(reward)) {\n    throw new Error(`training reward for rollout \"${line.rollout_id}\" must be finite`)\n  }\n  if (reward <= minimumQualityExclusive) return false\n  if (!line.outcome.is_completed || line.outcome.is_truncated || line.outcome.error !== null) {\n    return false\n  }\n  if (line.outcome.realness_gated === true) return false\n  return isSplitEligible(line, options)\n}\n"],"mappings":"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"}

package/dist/extract-usage-BrQ8mCLX.js

@@ -0,0 +1,155 @@
+import { TOKEN_USAGE_INPUT_KEYS, TOKEN_USAGE_OUTPUT_KEYS, firstTokenCount, tokenUsageSource } from "@tangle-network/agent-core/telemetry";
+import { SSEChunkParser } from "@tangle-network/agent-core/sse";
+//#region src/trace/extract-usage.ts
+/**
+* Provider response and SSE usage extraction.
+*
+* Missing usage returns `null`; reported zeroes and cache-only activity remain
+* distinguishable from absent telemetry.
+*/
+const INPUT_OTHER_KEYS = ["input_other"];
+const EXCLUSIVE_REASONING_KEYS = [
+	"reasoning",
+	"reasoning_tokens",
+	"reasoningTokens"
+];
+const INCLUSIVE_REASONING_KEYS = ["reasoning_output_tokens", "reasoningOutputTokens"];
+const INPUT_DETAIL_KEYS = ["prompt_tokens_details", "input_tokens_details"];
+const OUTPUT_DETAIL_KEYS = ["completion_tokens_details", "output_tokens_details"];
+const CACHED_KEYS = [
+	"cache",
+	"cached_tokens",
+	"cached_input_tokens",
+	"cache_read_tokens",
+	"cache_read_input_tokens",
+	"cachedTokens",
+	"cachedInputTokens",
+	"cacheReadTokens",
+	"cacheReadInputTokens",
+	"input_cache_read"
+];
+const CACHE_WRITE_KEYS = [
+	"cache_creation_tokens",
+	"cache_creation_input_tokens",
+	"cacheCreationTokens",
+	"cacheCreationInputTokens",
+	"input_cache_creation"
+];
+function nestedRecord(source, key) {
+	const value = source[key];
+	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function nestedNumber(source, recordKeys, valueKeys) {
+	for (const recordKey of recordKeys) {
+		const value = firstTokenCount(nestedRecord(source, recordKey), valueKeys);
+		if (value !== void 0) return value;
+	}
+}
+/**
+* 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.
+*/
+function extractUsage(body) {
+	if (!body || typeof body !== "object") return null;
+	const usage = tokenUsageSource(body);
+	const input = firstTokenCount(usage, TOKEN_USAGE_INPUT_KEYS);
+	const inputOther = firstTokenCount(usage, INPUT_OTHER_KEYS);
+	const output = firstTokenCount(usage, TOKEN_USAGE_OUTPUT_KEYS);
+	const exclusiveReasoning = firstTokenCount(usage, EXCLUSIVE_REASONING_KEYS);
+	const inclusiveReasoning = firstTokenCount(usage, INCLUSIVE_REASONING_KEYS) ?? nestedNumber(usage, OUTPUT_DETAIL_KEYS, ["reasoning_tokens", "reasoningTokens"]);
+	const reasoning = exclusiveReasoning ?? inclusiveReasoning;
+	const nestedCache = nestedRecord(usage, "cache");
+	const cached = firstTokenCount(usage, CACHED_KEYS) ?? firstTokenCount(nestedCache, ["read"]) ?? nestedNumber(usage, INPUT_DETAIL_KEYS, ["cached_tokens", "cachedTokens"]);
+	const cacheWrite = firstTokenCount(usage, CACHE_WRITE_KEYS) ?? firstTokenCount(nestedCache, ["write"]);
+	if (input === void 0 && inputOther === void 0 && output === void 0 && reasoning === void 0 && cached === void 0 && cacheWrite === void 0) return null;
+	const result = {
+		input: (input ?? 0) + (inputOther ?? 0),
+		output: (output ?? (inclusiveReasoning !== void 0 ? inclusiveReasoning : 0)) + (exclusiveReasoning ?? 0)
+	};
+	if (reasoning !== void 0) result.reasoning = reasoning;
+	if (cached !== void 0) result.cached = cached;
+	if (cacheWrite !== void 0) result.cacheWrite = cacheWrite;
+	return result;
+}
+/**
+* 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'`.
+*/
+function extractUsageFromSse(text, options = {}) {
+	const mode = options.mode ?? "cumulative";
+	let input = 0;
+	let output = 0;
+	let reasoning = 0;
+	let sawReasoning = false;
+	let cached = 0;
+	let sawCached = false;
+	let cacheWrite = 0;
+	let sawCacheWrite = false;
+	let found = false;
+	const parser = new SSEChunkParser({ transform: parseSseJson });
+	const events = [...parser.push(text), ...parser.flush()];
+	const merge = mode === "delta" ? (current, next) => current + next : Math.max;
+	for (const event of events) {
+		const usage = extractUsage(event.data);
+		if (!usage) continue;
+		input = merge(input, usage.input);
+		output = merge(output, usage.output);
+		if (usage.reasoning !== void 0) {
+			reasoning = merge(reasoning, usage.reasoning);
+			sawReasoning = true;
+		}
+		if (usage.cached !== void 0) {
+			cached = merge(cached, usage.cached);
+			sawCached = true;
+		}
+		if (usage.cacheWrite !== void 0) {
+			cacheWrite = merge(cacheWrite, usage.cacheWrite);
+			sawCacheWrite = true;
+		}
+		found = true;
+	}
+	if (!found) return null;
+	return {
+		input,
+		output,
+		...sawReasoning ? { reasoning } : {},
+		...sawCached ? { cached } : {},
+		...sawCacheWrite ? { cacheWrite } : {}
+	};
+}
+function parseSseJson(raw) {
+	const payload = raw.trim();
+	if (!payload || payload === "[DONE]") return null;
+	try {
+		return JSON.parse(payload);
+	} catch {
+		return 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.
+*/
+async function extractUsageFromResponse(response, sseOptions) {
+	let text;
+	try {
+		text = await response.clone().text();
+	} catch {
+		return null;
+	}
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		json = void 0;
+	}
+	return extractUsage(json) ?? extractUsageFromSse(text, sseOptions);
+}
+//#endregion
+export { extractUsageFromResponse as n, extractUsageFromSse as r, extractUsage as t };
+
+//# sourceMappingURL=extract-usage-BrQ8mCLX.js.map

package/dist/extract-usage-BrQ8mCLX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-usage-BrQ8mCLX.js","names":["obj"],"sources":["../src/trace/extract-usage.ts"],"sourcesContent":["/**\n * Provider response and SSE usage extraction.\n *\n * Missing usage returns `null`; reported zeroes and cache-only activity remain\n * distinguishable from absent telemetry.\n */\n\nimport { SSEChunkParser } from '@tangle-network/agent-core/sse'\nimport {\n  firstTokenCount,\n  TOKEN_USAGE_INPUT_KEYS,\n  TOKEN_USAGE_OUTPUT_KEYS,\n  tokenUsageSource,\n} from '@tangle-network/agent-core/telemetry'\nimport type { RunTokenUsage } from '../run-record'\n\nexport type ExtractedUsage = RunTokenUsage\nexport type SseUsageMode = 'cumulative' | 'delta'\n\nexport interface ExtractUsageFromSseOptions {\n  /** Provider usage events are cumulative snapshots unless explicitly marked as deltas. */\n  mode?: SseUsageMode\n}\n\nconst INPUT_OTHER_KEYS = ['input_other'] as const\nconst EXCLUSIVE_REASONING_KEYS = ['reasoning', 'reasoning_tokens', 'reasoningTokens'] as const\nconst INCLUSIVE_REASONING_KEYS = ['reasoning_output_tokens', 'reasoningOutputTokens'] as const\nconst INPUT_DETAIL_KEYS = ['prompt_tokens_details', 'input_tokens_details'] as const\nconst OUTPUT_DETAIL_KEYS = ['completion_tokens_details', 'output_tokens_details'] as const\nconst CACHED_KEYS = [\n  'cache',\n  'cached_tokens',\n  'cached_input_tokens',\n  'cache_read_tokens',\n  'cache_read_input_tokens',\n  'cachedTokens',\n  'cachedInputTokens',\n  'cacheReadTokens',\n  'cacheReadInputTokens',\n  'input_cache_read',\n] as const\nconst CACHE_WRITE_KEYS = [\n  'cache_creation_tokens',\n  'cache_creation_input_tokens',\n  'cacheCreationTokens',\n  'cacheCreationInputTokens',\n  'input_cache_creation',\n] as const\n\nfunction nestedRecord(\n  source: Record<string, unknown>,\n  key: string,\n): Record<string, unknown> | undefined {\n  const value = source[key]\n  return value && typeof value === 'object' && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined\n}\n\nfunction nestedNumber(\n  source: Record<string, unknown>,\n  recordKeys: readonly string[],\n  valueKeys: readonly string[],\n): number | undefined {\n  for (const recordKey of recordKeys) {\n    const value = firstTokenCount(nestedRecord(source, recordKey), valueKeys)\n    if (value !== undefined) return value\n  }\n  return undefined\n}\n\n/**\n * Pull `{ input, output, cached?, cacheWrite? }` from a parsed response\n * body. Accepts a top-level `usage` object (the common case) or a body that IS\n * the usage object. Returns null only when none of those categories is present.\n */\nexport function extractUsage(body: unknown): ExtractedUsage | null {\n  if (!body || typeof body !== 'object') return null\n  const obj = body as Record<string, unknown>\n  const usage = tokenUsageSource(obj)\n  const input = firstTokenCount(usage, TOKEN_USAGE_INPUT_KEYS)\n  const inputOther = firstTokenCount(usage, INPUT_OTHER_KEYS)\n  const output = firstTokenCount(usage, TOKEN_USAGE_OUTPUT_KEYS)\n  const exclusiveReasoning = firstTokenCount(usage, EXCLUSIVE_REASONING_KEYS)\n  const inclusiveReasoning =\n    firstTokenCount(usage, INCLUSIVE_REASONING_KEYS) ??\n    nestedNumber(usage, OUTPUT_DETAIL_KEYS, ['reasoning_tokens', 'reasoningTokens'])\n  const reasoning = exclusiveReasoning ?? inclusiveReasoning\n  const nestedCache = nestedRecord(usage, 'cache')\n  const cached =\n    firstTokenCount(usage, CACHED_KEYS) ??\n    firstTokenCount(nestedCache, ['read']) ??\n    nestedNumber(usage, INPUT_DETAIL_KEYS, ['cached_tokens', 'cachedTokens'])\n  const cacheWrite =\n    firstTokenCount(usage, CACHE_WRITE_KEYS) ?? firstTokenCount(nestedCache, ['write'])\n  if (\n    input === undefined &&\n    inputOther === undefined &&\n    output === undefined &&\n    reasoning === undefined &&\n    cached === undefined &&\n    cacheWrite === undefined\n  )\n    return null\n  const result: ExtractedUsage = {\n    input: (input ?? 0) + (inputOther ?? 0),\n    output:\n      (output ?? (inclusiveReasoning !== undefined ? inclusiveReasoning : 0)) +\n      (exclusiveReasoning ?? 0),\n  }\n  if (reasoning !== undefined) result.reasoning = reasoning\n  if (cached !== undefined) result.cached = cached\n  if (cacheWrite !== undefined) result.cacheWrite = cacheWrite\n  return result\n}\n\n/**\n * Extract token usage from a complete SSE response body using the shared SSE\n * frame parser. Cumulative snapshots are the fail-safe default because summing\n * them inflates billing; callers with explicit delta events opt into `mode: 'delta'`.\n */\nexport function extractUsageFromSse(\n  text: string,\n  options: ExtractUsageFromSseOptions = {},\n): ExtractedUsage | null {\n  const mode = options.mode ?? 'cumulative'\n  let input = 0\n  let output = 0\n  let reasoning = 0\n  let sawReasoning = false\n  let cached = 0\n  let sawCached = false\n  let cacheWrite = 0\n  let sawCacheWrite = false\n  let found = false\n  const parser = new SSEChunkParser<unknown>({ transform: parseSseJson })\n  const events = [...parser.push(text), ...parser.flush()]\n  const merge = mode === 'delta' ? (current: number, next: number) => current + next : Math.max\n\n  for (const event of events) {\n    const usage = extractUsage(event.data)\n    if (!usage) continue\n    input = merge(input, usage.input)\n    output = merge(output, usage.output)\n    if (usage.reasoning !== undefined) {\n      reasoning = merge(reasoning, usage.reasoning)\n      sawReasoning = true\n    }\n    if (usage.cached !== undefined) {\n      cached = merge(cached, usage.cached)\n      sawCached = true\n    }\n    if (usage.cacheWrite !== undefined) {\n      cacheWrite = merge(cacheWrite, usage.cacheWrite)\n      sawCacheWrite = true\n    }\n    found = true\n  }\n  if (!found) return null\n  return {\n    input,\n    output,\n    ...(sawReasoning ? { reasoning } : {}),\n    ...(sawCached ? { cached } : {}),\n    ...(sawCacheWrite ? { cacheWrite } : {}),\n  }\n}\n\nfunction parseSseJson(raw: string): unknown | null {\n  const payload = raw.trim()\n  if (!payload || payload === '[DONE]') return null\n  try {\n    return JSON.parse(payload)\n  } catch {\n    return null\n  }\n}\n\n/**\n * Extract usage from an HTTP `Response` without consuming the caller's body:\n * clones, reads the text, and tries the JSON parser first, then the SSE\n * accumulator. Best-effort — returns null on any read/parse miss so a usage tee\n * never takes down the underlying call.\n */\nexport async function extractUsageFromResponse(\n  response: Response,\n  sseOptions?: ExtractUsageFromSseOptions,\n): Promise<ExtractedUsage | null> {\n  let text: string\n  try {\n    text = await response.clone().text()\n  } catch {\n    return null\n  }\n  let json: unknown\n  try {\n    json = JSON.parse(text)\n  } catch {\n    json = undefined\n  }\n  return extractUsage(json) ?? extractUsageFromSse(text, sseOptions)\n}\n"],"mappings":"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"}

package/dist/failure-cluster-CqcvCcdR.d.ts

@@ -0,0 +1,59 @@
+import { C as TraceEvent, _ as Span, f as Run, o as FailureClass } from "./schema-BtVldJ3T.js";
+import { s as TraceStore } from "./store-CT9YIIve.js";
+//#region src/failure-taxonomy.d.ts
+interface FailureContext {
+  run: Run;
+  spans: Span[];
+  events: TraceEvent[];
+}
+interface FailureClassification {
+  failureClass: FailureClass;
+  reason: string;
+  triggerSpanId?: string;
+  triggerEventId?: string;
+}
+/** Ordered rules — first match wins. */
+interface FailureRule {
+  id: string;
+  match: (ctx: FailureContext) => {
+    failureClass: FailureClass;
+    reason: string;
+    triggerSpanId?: string;
+    triggerEventId?: string;
+  } | null;
+}
+declare const DEFAULT_RULES: FailureRule[];
+/** Classify the failure mode of a run using an ordered rule list. */
+declare function classifyFailure(ctx: FailureContext, rules?: FailureRule[]): FailureClassification;
+//#endregion
+//#region src/pipelines/failure-cluster.d.ts
+interface FailureCluster {
+  failureClass: FailureClass;
+  /** Tool name when the trigger was a tool span, else undefined. */
+  toolName?: string;
+  /** First 16 chars of argHash — clusters similar args. */
+  argPrefix?: string;
+  /**
+   * Source dimension when the trigger was a judge span (e.g. `'format'`,
+   * `'safety'`, `'correctness'`). Lets cross-template aggregators
+   * group failures by the dimension that fired without overloading
+   * `argPrefix`. Optional — clusters without this field deserialize cleanly.
+   */
+  dimension?: string;
+  runCount: number;
+  scenarioIds: string[];
+  exampleError?: string;
+  exampleRunId: string;
+}
+interface FailureClusterReport {
+  clusters: FailureCluster[];
+  totalFailures: number;
+  totalRuns: number;
+}
+declare function failureClusterView(store: TraceStore, options?: {
+  rules?: FailureRule[];
+  minClusterSize?: number;
+}): Promise<FailureClusterReport>;
+//#endregion
+export { FailureClassification as a, classifyFailure as c, DEFAULT_RULES as i, FailureClusterReport as n, FailureContext as o, failureClusterView as r, FailureRule as s, FailureCluster as t };
+//# sourceMappingURL=failure-cluster-CqcvCcdR.d.ts.map

package/dist/failure-cluster-CqcvCcdR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-cluster-CqcvCcdR.d.ts","names":[],"sources":["../src/failure-taxonomy.ts","../src/pipelines/failure-cluster.ts"],"mappings":";;;UAgBiB;EACf,KAAK;EACL,OAAO;EACP,QAAQ;;UAGO;EACf,cAAc;EACd;EACA;EACA;;;UAIe;EACf;EACA,QAAQ,KAAK;IACX,cAAc;IACd;IACA;IACA;;;cAIS,eAAe;;iBAyZZ,gBACd,KAAK,gBACL,QAAO,gBACN;;;UCvbc;EACf,cAAc;;EAEd;;EAEA;;;;;;;EAOA;EACA;EACA;EACA;EACA;;UAGe;EACf,UAAU;EACV;EACA;;iBAGoB,mBACpB,OAAO,YACP;EAAW,QAAQ;EAAe;IACjC,QAAQ"}