@kontourai/flow-agents 2.0.0 → 2.1.0

package/scripts/hooks/stop-goal-fit.js

@@ -803,17 +803,30 @@ function canonicalJsonForVerify(record) {
 
 /**
  * Verify the hash chain of command-log.jsonl.
- * Returns { status, brokenAt } where:
- *   status  = "ok" | "legacy" | "broken"
+ * Returns { status, brokenAt, forkAt } where:
+ *   status  = "ok" | "legacy" | "broken" | "forked"
  *   brokenAt = index (0-based) of the first broken entry, or null
+ *   forkAt   = index (0-based) of the first concurrent-fork sibling, or null
+ *
+ * "forked" is a BENIGN concurrent-append race, not tampering: two PostToolUse
+ * captures appended off the same parent tip (e.g. parallel agents sharing one
+ * log) before the writer lock (flow-agents#232) serialized them. It is
+ * distinguished from "broken" because:
+ *   - every entry's hash is still self-consistent (no content was edited), and
+ *   - every entry's parent is reachable (nothing was reordered or removed);
+ *   - the only anomaly is a parent claimed by >1 capture-sourced sibling.
+ * Tamper — a content edit (self-hash mismatch), a reorder, or a deletion
+ * (unreachable parent) — still returns "broken". A fork cannot be used to
+ * launder a content edit: editing a record breaks its self-hash, which is
+ * checked before fork classification.
  */
 function verifyCommandLogChain(artifactDir) {
   const file = path.join(artifactDir, 'command-log.jsonl');
   let raw = '';
-  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { status: 'legacy', brokenAt: null }; }
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { status: 'legacy', brokenAt: null, forkAt: null }; }
 
   const lines = raw.split('\n').filter(l => l.trim());
-  if (lines.length === 0) return { status: 'legacy', brokenAt: null };
+  if (lines.length === 0) return { status: 'legacy', brokenAt: null, forkAt: null };
 
   // Parse all entries, tolerating unparseable lines (they count as legacy/unchained).
   const entries = [];
@@ -823,18 +836,25 @@ function verifyCommandLogChain(artifactDir) {
       if (entry && typeof entry === 'object') entries.push(entry);
     } catch { /* skip malformed lines */ }
   }
-  if (entries.length === 0) return { status: 'legacy', brokenAt: null };
+  if (entries.length === 0) return { status: 'legacy', brokenAt: null, forkAt: null };
 
   // Classify: are there any chained entries?
   const hasAnyChain = entries.some(e => e._chain && typeof e._chain.hash === 'string');
-  if (!hasAnyChain) return { status: 'legacy', brokenAt: null };
-
-  // Verify chain linkage. Legacy entries (no _chain) that precede the first
-  // chained entry are tolerated (mixed log during the upgrade transition).
-  // However, a chain entry following another chain entry must link correctly.
-  let prevHash = CHAIN_GENESIS_VERIFY;
+  if (!hasAnyChain) return { status: 'legacy', brokenAt: null, forkAt: null };
+
+  // Walk in file order. A chained entry is ACCEPTED when both:
+  //   (a) self-consistent: hash === sha256(prevHash + canonicalJson(record)),
+  //       so a content edit (e.g. flipping exitCode) without rehashing fails; and
+  //   (b) reachable: prevHash is genesis or the hash of any prior accepted entry.
+  // We track the SET of reachable hashes (not just the latest tip) so that
+  // concurrent-fork siblings — which share a still-reachable parent — are
+  // tolerated, while a reorder/deletion (parent not reachable) is caught.
+  const reachable = new Set([CHAIN_GENESIS_VERIFY]);
+  const parentSources = new Map(); // prevHash -> [source, ...] (fork detection)
   let prevWasChained = false;
-  let chainedCount = 0;
+  let forked = false;
+  let firstForkAt = null;
+
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i];
     const chain = entry._chain;
@@ -842,26 +862,43 @@ function verifyCommandLogChain(artifactDir) {
       // Legacy entry without _chain. If we have already seen a chained entry,
       // a gap in the chain (a legacy entry in the middle) counts as broken
       // (it could indicate a removed chained entry was replaced by a legacy one).
-      if (prevWasChained) return { status: 'broken', brokenAt: i };
+      if (prevWasChained) return { status: 'broken', brokenAt: i, forkAt: null };
       // Before any chained entry: tolerate (legacy prefix).
       continue;
     }
 
-    // This is a chained entry. Verify hash.
-    const expectedHash = crypto.createHash('sha256')
-      .update(prevHash + canonicalJsonForVerify(entry), 'utf8')
+    // (a) Self-consistency. A content edit without rehashing fails here.
+    if (typeof chain.prevHash !== 'string') return { status: 'broken', brokenAt: i, forkAt: null };
+    const selfHash = crypto.createHash('sha256')
+      .update(chain.prevHash + canonicalJsonForVerify(entry), 'utf8')
       .digest('hex');
-    if (chain.hash !== expectedHash) return { status: 'broken', brokenAt: i };
-
-    // Verify linkage: prevHash must match what this entry claims.
-    if (chain.prevHash !== prevHash) return { status: 'broken', brokenAt: i };
+    if (chain.hash !== selfHash) return { status: 'broken', brokenAt: i, forkAt: null };
+
+    // (b) Reachability. An unreachable parent means a reorder or a removed
+    // predecessor — structural tamper, not a benign concurrent append.
+    if (!reachable.has(chain.prevHash)) return { status: 'broken', brokenAt: i, forkAt: null };
+
+    // Fork detection: a parent claimed by more than one entry is a fork. It is
+    // benign only when EVERY sibling on that parent is a PostToolUse capture
+    // (two captures racing on the same tip). Any non-capture sibling on a
+    // shared parent is treated as tamper (conservative).
+    const sources = parentSources.get(chain.prevHash) || [];
+    sources.push(entry.source);
+    parentSources.set(chain.prevHash, sources);
+    if (sources.length > 1) {
+      if (!sources.every(s => s === 'postToolUse-capture')) {
+        return { status: 'broken', brokenAt: i, forkAt: null };
+      }
+      if (firstForkAt === null) firstForkAt = i;
+      forked = true;
+    }
 
-    prevHash = chain.hash;
+    reachable.add(chain.hash);
     prevWasChained = true;
-    chainedCount += 1;
   }
 
-  return { status: 'ok', brokenAt: null };
+  if (forked) return { status: 'forked', brokenAt: null, forkAt: firstForkAt };
+  return { status: 'ok', brokenAt: null, forkAt: null };
 }
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -1065,6 +1102,11 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
   //
   // ok     → proceed normally (chain is valid, log is trustworthy).
   // legacy → proceed normally (pre-B2 log, no chain to verify, existing behavior).
+  // forked → benign concurrent-append race (not tampering): emit a loud but
+  //          NON-blocking advisory and keep trusting the records. The capture
+  //          contradiction teeth still run (the records are genuine, just not
+  //          linearly ordered); the operator can re-linearize with the repair
+  //          tool. This is what stops honest parallel work from being trapped.
   // broken → emit a loud warning and treat ALL claimed-pass commands relying on
   //          this log as NOT_VERIFIED/blocking — do not let them sail through.
   let chainBroken = false;
@@ -1079,6 +1121,17 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
         'This is tamper-EVIDENCE (hash-chain broken); alteration, removal, or reordering detected. ' +
         'NOT_VERIFIED: cannot confirm or deny claimed passes.'
       );
+    } else if (chainResult.status === 'forked') {
+      // NOT a hard block: this string must not match HARD_BLOCK/FULL_BLOCK. A
+      // concurrent fork is benign — no content was edited and nothing was
+      // removed — so honest parallel work proceeds. We surface it loudly and
+      // point at the deterministic repair.
+      const forkIdx = chainResult.forkAt !== null ? ` (entry ${chainResult.forkAt})` : '';
+      warnings.push(
+        `${base} command-log shows a concurrent-capture fork${forkIdx} — two PostToolUse captures appended off the same parent ` +
+        '(parallel writers before the writer lock). This is NOT tampering: every record is self-consistent and reachable. ' +
+        'Records remain trusted; re-linearize with: node scripts/repair-command-log.js <artifact-dir>'
+      );
     }
   }
 

package/scripts/repair-command-log.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * repair-command-log.js — deterministic re-linearization of a concurrent-fork
+ * command-log.jsonl.
+ *
+ * A "fork" happens when two PostToolUse captures append off the same parent tip
+ * (parallel writers before the writer lock, flow-agents#232). The records are
+ * all genuine and self-consistent; only their linear order is ambiguous. This
+ * tool produces THE canonical order — sort chained entries by (capturedAt, then
+ * hash) — and re-chains them, so any party re-running it gets the identical
+ * result. It is therefore a verifiable repair, not a judgement call.
+ *
+ * SAFETY: it refuses to run unless verifyCommandLogChain() reports "forked".
+ *   - "broken" (real tamper: edited content, reorder, deletion) → REFUSE. The
+ *     repair must never be usable to launder tampering.
+ *   - "ok" / "legacy" → nothing to do.
+ * No record content is altered — only the _chain wrappers and line order. The
+ * original is backed up, and an in-chain `chain-repair` marker records that the
+ * re-linearization happened (so the repair is itself auditable).
+ *
+ * Usage: node scripts/repair-command-log.js <artifact-dir> [--reason "..."]
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const gate = require(path.join(__dirname, 'hooks', 'stop-goal-fit.js'));
+const GENESIS = gate.CHAIN_GENESIS_VERIFY;
+
+function canon(rec) {
+  const keys = Object.keys(rec).filter((k) => k !== '_chain').sort();
+  const obj = {};
+  for (const k of keys) obj[k] = rec[k];
+  return JSON.stringify(obj);
+}
+function hashLink(prev, rec) {
+  return crypto.createHash('sha256').update(prev + canon(rec), 'utf8').digest('hex');
+}
+
+function main() {
+  const dir = process.argv[2];
+  if (!dir) { console.error('usage: repair-command-log.js <artifact-dir> [--reason "..."]'); process.exit(2); }
+  const reasonIdx = process.argv.indexOf('--reason');
+  const reason = reasonIdx !== -1 ? (process.argv[reasonIdx + 1] || '') : 'deterministic concurrent-fork re-linearization';
+
+  const verdict = gate.verifyCommandLogChain(dir);
+  if (verdict.status === 'ok' || verdict.status === 'legacy') {
+    console.log(`nothing to repair: chain status is "${verdict.status}"`);
+    return;
+  }
+  if (verdict.status !== 'forked') {
+    console.error(`REFUSING to repair: chain status is "${verdict.status}" (entry ${verdict.brokenAt}). ` +
+      'This tool only re-linearizes benign concurrent forks; it will not touch a tampered chain.');
+    process.exit(1);
+  }
+
+  const file = path.join(dir, 'command-log.jsonl');
+  const lines = fs.readFileSync(file, 'utf8').split('\n').filter((l) => l.trim());
+
+  // Preserve legacy prefix verbatim; collect the chained records (content only).
+  const legacyPrefix = [];
+  const records = [];
+  let started = false;
+  for (const line of lines) {
+    let e;
+    try { e = JSON.parse(line); } catch { if (!started) { legacyPrefix.push(line); } continue; }
+    const isChained = e._chain && typeof e._chain.hash === 'string';
+    if (!started && !isChained) { legacyPrefix.push(line); continue; }
+    started = true;
+    const rec = { ...e };
+    delete rec._chain;
+    records.push(rec);
+  }
+
+  // Canonical deterministic order: capturedAt asc, then a stable content hash.
+  records.sort((a, b) => {
+    const ta = String(a.capturedAt || ''), tb = String(b.capturedAt || '');
+    if (ta !== tb) return ta < tb ? -1 : 1;
+    const ha = crypto.createHash('sha256').update(canon(a)).digest('hex');
+    const hb = crypto.createHash('sha256').update(canon(b)).digest('hex');
+    return ha < hb ? -1 : ha > hb ? 1 : 0;
+  });
+
+  // Re-chain from genesis.
+  const out = [...legacyPrefix];
+  let prev = GENESIS;
+  let seq = 0;
+  for (const rec of records) {
+    const h = hashLink(prev, rec);
+    out.push(JSON.stringify({ ...rec, _chain: { seq, prevHash: prev, hash: h } }));
+    prev = h; seq += 1;
+  }
+  // Append an in-chain repair marker so the re-linearization is itself auditable.
+  const marker = {
+    command: '(chain-repair marker)',
+    observedResult: `re-linearized ${records.length} entries from concurrent fork`,
+    exitCode: 0,
+    capturedAt: new Date().toISOString(),
+    source: 'chain-repair',
+    repair: { reason, entries: records.length, forkAt: verdict.forkAt },
+  };
+  const mh = hashLink(prev, marker);
+  out.push(JSON.stringify({ ...marker, _chain: { seq, prevHash: prev, hash: mh } }));
+
+  fs.copyFileSync(file, file + '.prebackup-repair');
+  fs.writeFileSync(file, out.join('\n') + '\n');
+
+  const after = gate.verifyCommandLogChain(dir);
+  console.log(`repaired: re-linearized ${records.length} entries (legacy prefix: ${legacyPrefix.length}); ` +
+    `chain status now "${after.status}". backup: command-log.jsonl.prebackup-repair`);
+  if (after.status !== 'ok') { console.error('repair did not produce a clean chain'); process.exit(1); }
+}
+
+main();

package/scripts/telemetry/lib/config.sh

@@ -38,6 +38,11 @@ CONSOLE_TELEMETRY_URL="${CONSOLE_TELEMETRY_URL:-${CONSOLE_URL:-}}"
 CONSOLE_TELEMETRY_ENDPOINT_URL="${CONSOLE_TELEMETRY_ENDPOINT_URL:-}"
 CONSOLE_TELEMETRY_TOKEN="${CONSOLE_TELEMETRY_TOKEN:-${CONSOLE_AUTH_TOKEN:-}}"
 CONSOLE_TENANT_ID="${CONSOLE_TENANT_ID:-}"
+# Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
+# otherwise the URL is derived from the console below so all runtimes read one
+# live pricing source. Falls back to the bundled pricing.json offline.
+TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
+TELEMETRY_PRICING_URL="${TELEMETRY_PRICING_URL:-${FLOW_AGENTS_PRICING_URL:-}}"
 
 # Load config file if it exists
 if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
@@ -78,6 +83,9 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
         console_telemetry_token) CONSOLE_TELEMETRY_TOKEN="$value" ;;
         console_tenant_id) CONSOLE_TENANT_ID="$value" ;;
         console_telemetry_redact) CONSOLE_TELEMETRY_REDACT="$value" ;;
+        console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
+        pricing_url) TELEMETRY_PRICING_URL="$value" ;;
+        pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
       esac
     fi
   done < "$TELEMETRY_CONFIG_FILE"
@@ -85,5 +93,12 @@ fi
 
 CONSOLE_TELEMETRY_REDACT="${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT}}"
 
+# Derive the live pricing source from the console when not set explicitly, the
+# same way the transport derives /api/telemetry/records. One live source for
+# bash/Python/TS runtimes; lib/pricing.sh caches it and falls back to bundled.
+if [[ -z "${TELEMETRY_PRICING_URL:-}" && -n "${CONSOLE_TELEMETRY_URL:-}" ]]; then
+  TELEMETRY_PRICING_URL="${CONSOLE_TELEMETRY_URL%/}/api/telemetry/pricing"
+fi
+
 # Ensure directories exist
 mkdir -p "$TELEMETRY_DATA_DIR" "$TELEMETRY_SESSION_DIR" 2>/dev/null

package/scripts/telemetry/lib/pricing.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# pricing.sh — single-source pricing registry loader.
+#
+# Resolves the versioned pricing registry (pricing.json) from, in priority:
+#   1. explicit local file   TELEMETRY_PRICING_FILE / FLOW_AGENTS_PRICING_FILE
+#   2. remote URL (cached)   TELEMETRY_PRICING_URL  / FLOW_AGENTS_PRICING_URL
+#   3. bundled snapshot      <telemetry>/pricing.json
+# This is the one source every runtime + the console read from — local for
+# air-gapped use, remote for a single live registry shared across machines.
+
+PRICING_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Echo the raw registry JSON. Returns non-zero if nothing resolvable.
+pricing_registry() {
+  local f="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
+  if [[ -n "$f" && -f "$f" ]]; then cat "$f"; return 0; fi
+
+  local url="${TELEMETRY_PRICING_URL:-${FLOW_AGENTS_PRICING_URL:-}}"
+  if [[ -n "$url" ]] && command -v curl >/dev/null 2>&1; then
+    local cache="${TMPDIR:-/tmp}/flow-agents-pricing-cache.json"
+    local ttl="${TELEMETRY_PRICING_TTL_SEC:-3600}"
+    if [[ -f "$cache" ]]; then
+      local mtime now age
+      mtime=$(stat -f %m "$cache" 2>/dev/null || stat -c %Y "$cache" 2>/dev/null || echo 0)
+      now=$(date +%s)
+      age=$(( now - mtime ))
+      if [[ "$age" -lt "$ttl" ]]; then cat "$cache"; return 0; fi
+    fi
+    if curl -fsS --max-time 5 "$url" -o "${cache}.tmp" 2>/dev/null && [[ -s "${cache}.tmp" ]]; then
+      mv "${cache}.tmp" "$cache"
+      cat "$cache"
+      return 0
+    fi
+    rm -f "${cache}.tmp" 2>/dev/null
+    [[ -f "$cache" ]] && { cat "$cache"; return 0; }  # stale cache beats nothing
+  fi
+
+  local bundled
+  bundled="$(cd "${PRICING_LIB_DIR}/.." && pwd)/pricing.json"
+  [[ -f "$bundled" ]] && { cat "$bundled"; return 0; }
+  return 1
+}

package/scripts/telemetry/lib/usage.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # usage.sh — Session usage metric functions
 
+# Module directory, resolved once at source time (cwd-independent).
+USAGE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Single-source pricing registry loader (local / remote / bundled).
+source "${USAGE_LIB_DIR}/pricing.sh"
+
 # Resolve model from agent-spec.json
 usage_get_model() {
   local agent_name="$1"
@@ -27,3 +33,105 @@ usage_count_delegations() {
   [[ ! -f "$jsonl_path" ]] && echo 0 && return
   grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"agent.delegate\"" "$jsonl_path" 2>/dev/null || echo 0
 }
+
+# Parse a runtime transcript (JSONL) into real per-model token + cost usage.
+# Ground truth lives in each assistant message's `.message.usage` block:
+#   input_tokens (uncached), output_tokens, cache_creation_input_tokens,
+#   cache_read_input_tokens — plus `.message.model`.
+# Cost is derived from the versioned pricing registry: cache writes bill at
+# input*write_5m, cache reads at input*read. Cost uses the registry's
+# current_version (override with arg $2) and the result stamps `pricing_version`
+# so the console can reproduce or recompute it. Emits a compact JSON object:
+#   { by_model: [ {model, input_tokens, output_tokens,
+#                  cache_creation_input_tokens, cache_read_input_tokens,
+#                  estimated_cost_usd} ],
+#     input_tokens, output_tokens, cache_creation_input_tokens,
+#     cache_read_input_tokens, estimated_cost_usd, pricing_version }
+# Prints nothing (non-zero) when the transcript is missing/unparseable so the
+# caller can fall back to null usage. Never blocks agent work.
+# Expected transcript usage path (Claude Code / Anthropic usage object). Bumped
+# if the on-disk schema changes so drift is logged rather than silently zeroed.
+USAGE_TRANSCRIPT_SCHEMA="message.usage.input_tokens"
+
+# Append a one-line schema-drift warning (transcript carried usage data we could
+# not parse). Goes to TELEMETRY_DRIFT_LOG if set, else stderr. Never fatal.
+usage_log_drift() {
+  local transcript="$1"
+  local msg="[telemetry] pricing/usage drift: ${transcript} has usage data but expected path '${USAGE_TRANSCRIPT_SCHEMA}' parsed 0 tokens — transcript schema may have changed"
+  if [[ -n "${TELEMETRY_DRIFT_LOG:-}" ]]; then
+    echo "$msg" >> "${TELEMETRY_DRIFT_LOG}" 2>/dev/null || echo "$msg" >&2
+  else
+    echo "$msg" >&2
+  fi
+}
+
+usage_parse_transcript() {
+  local transcript="$1" version="${2:-}"
+  [[ -z "$transcript" || ! -f "$transcript" ]] && return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  local registry
+  registry="$(pricing_registry)" || return 1
+  [[ -z "$registry" ]] && return 1
+
+  local out
+  out="$(jq -n --argjson registry "$registry" --arg version "$version" '
+    $registry as $reg
+    | (if $version == "" then ($reg.current_version) else $version end) as $ver
+    | ($reg.versions[$ver]) as $p
+    | if $p == null then empty else . end
+    | ($p.cache_multipliers) as $cm
+    | (reduce inputs as $l ({};
+        ($l.message.usage) as $u
+        | if $u then
+            (($l.message.model) // "unknown") as $m
+            | .[$m].input          = ((.[$m].input // 0)          + (($u.input_tokens) // 0))
+            | .[$m].output         = ((.[$m].output // 0)         + (($u.output_tokens) // 0))
+            | .[$m].cache_creation = ((.[$m].cache_creation // 0) + (($u.cache_creation_input_tokens) // 0))
+            | .[$m].cache_read     = ((.[$m].cache_read // 0)     + (($u.cache_read_input_tokens) // 0))
+          else . end)) as $agg
+    | ($agg | to_entries
+        | map(
+            .key as $m | .value as $u
+            | (($p.models[$m]) // $p.default) as $rate
+            | (if ([$m] | inside($p.zero_cost_models)) then 0 else 1 end) as $billable
+            | {
+                model: $m,
+                input_tokens: ($u.input // 0),
+                output_tokens: ($u.output // 0),
+                cache_creation_input_tokens: ($u.cache_creation // 0),
+                cache_read_input_tokens: ($u.cache_read // 0),
+                estimated_cost_usd: (
+                  $billable * (
+                    ($u.input // 0)          * $rate.input
+                    + ($u.output // 0)         * $rate.output
+                    + ($u.cache_creation // 0) * $rate.input * $cm.write_5m
+                    + ($u.cache_read // 0)     * $rate.input * $cm.read
+                  ) / 1000000
+                )
+              })) as $by_model
+    | {
+        by_model: $by_model,
+        input_tokens: ([$by_model[].input_tokens] | add // 0),
+        output_tokens: ([$by_model[].output_tokens] | add // 0),
+        cache_creation_input_tokens: ([$by_model[].cache_creation_input_tokens] | add // 0),
+        cache_read_input_tokens: ([$by_model[].cache_read_input_tokens] | add // 0),
+        estimated_cost_usd: (([$by_model[].estimated_cost_usd] | add // 0) * 1000000 | round / 1000000),
+        pricing_version: $ver
+      }
+  ' < "$transcript" 2>/dev/null)"
+
+  [[ -z "$out" ]] && return 1
+
+  # Drift / emptiness check: if we parsed zero tokens but the transcript clearly
+  # contains usage data, the schema drifted — warn and fall back to null usage.
+  local total
+  total="$(printf '%s' "$out" | jq -r '((.input_tokens // 0) + (.output_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0))' 2>/dev/null)"
+  if [[ -z "$total" || "$total" == "0" ]]; then
+    if grep -q '"input_tokens"' "$transcript" 2>/dev/null; then
+      usage_log_drift "$transcript"
+    fi
+    return 1
+  fi
+
+  printf '%s\n' "$out"
+}

package/scripts/telemetry/pricing.golden.json

@@ -0,0 +1,15 @@
+{
+  "_note": "Cross-runtime cost golden vectors. Keep IN SYNC with console-telemetry/test/golden-vectors.json (identical content). Asserted by the flow-agents bash usage tests, the Python sink tests, and the console-telemetry package so every runtime that prices tokens produces the SAME cost. If these drift between repos, a runtime's cost math has diverged.",
+  "pricing_version": "2026-06-28",
+  "cases": [
+    { "name": "opus cache-read-dominated", "model": "claude-opus-4-8", "tokens": { "input": 1000, "output": 2000, "cache_creation": 0, "cache_read": 500000 }, "expected_cost_usd": 0.305 },
+    { "name": "opus output only", "model": "claude-opus-4-8", "tokens": { "input": 0, "output": 1000, "cache_creation": 0, "cache_read": 0 }, "expected_cost_usd": 0.025 },
+    { "name": "fable output", "model": "claude-fable-5", "tokens": { "input": 0, "output": 100, "cache_creation": 0, "cache_read": 0 }, "expected_cost_usd": 0.005 },
+    { "name": "haiku output", "model": "claude-haiku-4-5", "tokens": { "input": 0, "output": 1000, "cache_creation": 0, "cache_read": 0 }, "expected_cost_usd": 0.005 },
+    { "name": "sonnet input 1M", "model": "claude-sonnet-4-6", "tokens": { "input": 1000000, "output": 0, "cache_creation": 0, "cache_read": 0 }, "expected_cost_usd": 3.0 },
+    { "name": "opus cache-write 5m tier", "model": "claude-opus-4-8", "tokens": { "input": 0, "output": 0, "cache_creation": 1000000, "cache_read": 0 }, "expected_cost_usd": 6.25 },
+    { "name": "opus billion-scale", "model": "claude-opus-4-8", "tokens": { "input": 200000, "output": 1600000, "cache_creation": 9000000, "cache_read": 1000000000 }, "expected_cost_usd": 597.25 },
+    { "name": "synthetic is free", "model": "<synthetic>", "tokens": { "input": 999, "output": 999, "cache_creation": 999, "cache_read": 999 }, "expected_cost_usd": 0 },
+    { "name": "unknown model uses default rate", "model": "some-unlisted-model", "tokens": { "input": 1000000, "output": 0, "cache_creation": 0, "cache_read": 0 }, "expected_cost_usd": 5.0 }
+  ]
+}

package/scripts/telemetry/pricing.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": "2.0",
+  "current_version": "2026-06-28",
+  "source": "Anthropic public list pricing; cache multipliers per prompt-caching docs",
+  "versions": {
+    "2026-06-28": {
+      "effective_date": "2026-06-28",
+      "currency": "USD",
+      "unit": "per_1m_tokens",
+      "cache_multipliers": {
+        "write_5m": 1.25,
+        "write_1h": 2.0,
+        "read": 0.1
+      },
+      "models": {
+        "claude-fable-5": { "input": 10.0, "output": 50.0 },
+        "claude-mythos-5": { "input": 10.0, "output": 50.0 },
+        "claude-opus-4-8": { "input": 5.0, "output": 25.0 },
+        "claude-opus-4-7": { "input": 5.0, "output": 25.0 },
+        "claude-opus-4-6": { "input": 5.0, "output": 25.0 },
+        "claude-opus-4-5": { "input": 5.0, "output": 25.0 },
+        "claude-opus-4-1": { "input": 15.0, "output": 75.0 },
+        "claude-sonnet-4-6": { "input": 3.0, "output": 15.0 },
+        "claude-sonnet-4-5": { "input": 3.0, "output": 15.0 },
+        "claude-haiku-4-5": { "input": 1.0, "output": 5.0 }
+      },
+      "default": { "input": 5.0, "output": 25.0 },
+      "zero_cost_models": ["<synthetic>", "synthetic", "unknown", ""]
+    }
+  }
+}

package/scripts/telemetry/telemetry.conf

@@ -8,6 +8,10 @@ channel.analytics.redact=tool.input,tool.output,turn.prompt_text,delegation.targ
 # The transport derives /api/telemetry/records from console_telemetry_url.
 # console_telemetry_token=
 # console_tenant_id=
+# Live pricing registry source. If unset, derived from console_telemetry_url as
+# <console>/api/telemetry/pricing so bash/Python/TS runtimes read one live
+# source; lib/pricing.sh caches it and falls back to bundled pricing.json.
+# console_pricing_url=https://console.kontourai.io/api/telemetry/pricing
 enrich_system=true
 enrich_workspace=true
 enrich_auth=true

package/scripts/telemetry/telemetry.sh

@@ -309,13 +309,35 @@ add_stop_data_and_emit_usage() {
     tool_count=$(usage_count_tool_calls "$session_id" "$full_log")
     delegation_count=$(usage_count_delegations "$session_id" "$full_log")
 
+    # Ground-truth token + cost usage from the runtime transcript, when the
+    # runtime exposes one (Claude Code, Codex, etc. set hook.transcript_path).
+    # Tokens are source-of-truth; estimated_cost_usd is derived from pricing.json
+    # (recomputed authoritatively console-side, so pricing updates are retroactive).
+    local transcript_path transcript_usage
+    transcript_path=$(echo "$event" | jq -r '.hook.transcript_path // ""')
+    transcript_usage=$(usage_parse_transcript "$transcript_path")
+    [[ -z "$transcript_usage" ]] && transcript_usage='null'
+
     local usage_event
     usage_event=$(echo "$event" | jq -c \
       --arg m "$model" \
       --argjson tc "$tool_count" \
       --argjson dc "$delegation_count" \
+      --argjson tu "$transcript_usage" \
       '.event_type = "session.usage" | .event_id = (.event_id + "-usage") | . + {
-        usage: {model: $m, duration_s: .session.duration_s, tool_invocations: $tc, delegations: $dc, input_tokens: null, output_tokens: null, estimated_cost_usd: null}
+        usage: ({
+          model: $m,
+          duration_s: .session.duration_s,
+          tool_invocations: $tc,
+          delegations: $dc,
+          input_tokens: ($tu.input_tokens // null),
+          output_tokens: ($tu.output_tokens // null),
+          cache_creation_input_tokens: ($tu.cache_creation_input_tokens // null),
+          cache_read_input_tokens: ($tu.cache_read_input_tokens // null),
+          estimated_cost_usd: ($tu.estimated_cost_usd // null),
+          pricing_version: ($tu.pricing_version // null),
+          by_model: ($tu.by_model // null)
+        })
       }')
     transport_emit "$usage_event"
   fi