@bli-cockpit/telemetry-core 0.1.46 → 0.1.48

package/dist/evidence-upload.d.ts

@@ -528,6 +528,39 @@ export declare const CodexSessionAttributionSchema: z.ZodObject<{
     signals: z.ZodDefault<z.ZodArray<z.ZodString>>;
     session_file_hash_sha256: z.ZodOptional<z.ZodString>;
     session_file_byte_size: z.ZodOptional<z.ZodNumber>;
+    session_facts: z.ZodOptional<z.ZodObject<{
+        extractor_version: z.ZodString;
+        source: z.ZodEnum<{
+            codex: "codex";
+            claude_code: "claude_code";
+        }>;
+        usage_by_model: z.ZodRecord<z.ZodString, z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+            cache_read_input_tokens: z.ZodNumber;
+            cache_creation_input_tokens: z.ZodNumber;
+        }, z.core.$strict>>;
+        models: z.ZodArray<z.ZodString>;
+        input_tokens: z.ZodNumber;
+        output_tokens: z.ZodNumber;
+        cache_read_tokens: z.ZodNumber;
+        cache_creation_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+        record_count: z.ZodNumber;
+        turn_count: z.ZodNumber;
+        user_prompt_count: z.ZodNumber;
+        assistant_response_count: z.ZodNumber;
+        tool_calls_by_name: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        tool_call_count: z.ZodNumber;
+        first_timestamp: z.ZodNullable<z.ZodString>;
+        last_timestamp: z.ZodNullable<z.ZodString>;
+        wall_duration_seconds: z.ZodNullable<z.ZodNumber>;
+        transcript_bytes: z.ZodNumber;
+        transcript_lines: z.ZodNumber;
+        transcript_files: z.ZodNumber;
+        truncated_models: z.ZodNumber;
+        truncated_tool_names: z.ZodNumber;
+    }, z.core.$strict>>;
     session_file_mtime: z.ZodOptional<z.ZodString>;
     repo_fingerprint: z.ZodOptional<z.ZodString>;
     worktree_fingerprint: z.ZodOptional<z.ZodString>;
@@ -599,6 +632,39 @@ export declare const CodexSessionAttributionReportRequestSchema: z.ZodObject<{
         signals: z.ZodDefault<z.ZodArray<z.ZodString>>;
         session_file_hash_sha256: z.ZodOptional<z.ZodString>;
         session_file_byte_size: z.ZodOptional<z.ZodNumber>;
+        session_facts: z.ZodOptional<z.ZodObject<{
+            extractor_version: z.ZodString;
+            source: z.ZodEnum<{
+                codex: "codex";
+                claude_code: "claude_code";
+            }>;
+            usage_by_model: z.ZodRecord<z.ZodString, z.ZodObject<{
+                input_tokens: z.ZodNumber;
+                output_tokens: z.ZodNumber;
+                cache_read_input_tokens: z.ZodNumber;
+                cache_creation_input_tokens: z.ZodNumber;
+            }, z.core.$strict>>;
+            models: z.ZodArray<z.ZodString>;
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+            cache_read_tokens: z.ZodNumber;
+            cache_creation_tokens: z.ZodNumber;
+            total_tokens: z.ZodNumber;
+            record_count: z.ZodNumber;
+            turn_count: z.ZodNumber;
+            user_prompt_count: z.ZodNumber;
+            assistant_response_count: z.ZodNumber;
+            tool_calls_by_name: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            tool_call_count: z.ZodNumber;
+            first_timestamp: z.ZodNullable<z.ZodString>;
+            last_timestamp: z.ZodNullable<z.ZodString>;
+            wall_duration_seconds: z.ZodNullable<z.ZodNumber>;
+            transcript_bytes: z.ZodNumber;
+            transcript_lines: z.ZodNumber;
+            transcript_files: z.ZodNumber;
+            truncated_models: z.ZodNumber;
+            truncated_tool_names: z.ZodNumber;
+        }, z.core.$strict>>;
         session_file_mtime: z.ZodOptional<z.ZodString>;
         repo_fingerprint: z.ZodOptional<z.ZodString>;
         worktree_fingerprint: z.ZodOptional<z.ZodString>;

package/dist/evidence-upload.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { CaptureProvenanceSchema, IsoDateTimeSchema, NonEmptyStringSchema, Sha256Schema, } from "./common.js";
 import { RawEvidencePointerSchema } from "./privacy.js";
 import { RawEvidenceRedactionMetadataSchema } from "./secret-guards.js";
+import { SessionFactsSchema } from "./session-facts.js";
 /**
  * Chunked raw-evidence upload wire contract.
  *
@@ -285,6 +286,16 @@ export const CodexSessionAttributionSchema = z
     signals: z.array(SafeLabelSchema).max(20).default([]),
     session_file_hash_sha256: Sha256Schema.optional(),
     session_file_byte_size: z.number().int().nonnegative().optional(),
+    /**
+     * Everything deterministic about the transcript, counted by the collector
+     * while the file was in its hands (BLI-4341). Token totals per model, turn
+     * and tool counts, first/last timestamps, size. Metadata only.
+     *
+     * Optional because a CLI published before this change sends none, and its
+     * uploads must keep validating; the server extractor is the safety net for
+     * exactly those.
+     */
+    session_facts: SessionFactsSchema.optional(),
     session_file_mtime: IsoDateTimeSchema.optional(),
     repo_fingerprint: SafeLabelSchema.optional(),
     worktree_fingerprint: SafeLabelSchema.optional(),

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./paths.js";
 export * from "./privacy.js";
 export * from "./risk-flags.js";
 export * from "./secret-guards.js";
+export * from "./session-facts.js";
 export * from "./source-adapter.js";
 export * from "./ticket-id.js";
 export * from "./trace-sink.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./paths.js";
 export * from "./privacy.js";
 export * from "./risk-flags.js";
 export * from "./secret-guards.js";
+export * from "./session-facts.js";
 export * from "./source-adapter.js";
 export * from "./ticket-id.js";
 export * from "./trace-sink.js";

package/dist/memory-hook-stats.d.ts

@@ -93,8 +93,8 @@ export declare const MEMORY_HOOK_BUCKET_PATTERN: RegExp;
 export declare const MemoryHookStatsFileSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"memory-hook-stats.v1">;
     buckets: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodEnum<{
-        "session-start": "session-start";
         prompt: "prompt";
+        "session-start": "session-start";
         stop: "stop";
     }> & z.core.$partial, z.ZodObject<{
         runs: z.ZodNumber;

package/dist/session-facts-text.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plain-text reads of one transcript record.
+ *
+ * Moved here from `@bli-cockpit/harvest-analysis` `extract/turn-text.ts`
+ * (BLI-4341) so the collector and the server ask the same question of a record
+ * ("did this turn carry any text?") with one implementation. The extractor now
+ * re-exports these; there is no second copy to drift.
+ *
+ * Nothing here leaves the process: callers use the text to decide a COUNT.
+ */
+export declare function claudeUserTurnText(record: Record<string, unknown>): string | null;
+export declare function codexUserTurnText(payload: Record<string, unknown>): string | null;
+export declare function claudeAssistantText(record: Record<string, unknown>): string | null;
+export declare function codexAssistantText(payload: Record<string, unknown>): string | null;
+export declare function textFromPlainTextBlocks(value: unknown): string | null;
+export declare function normalizeTurnText(value: string): string;

package/dist/session-facts-text.js

@@ -0,0 +1,62 @@
+/**
+ * Plain-text reads of one transcript record.
+ *
+ * Moved here from `@bli-cockpit/harvest-analysis` `extract/turn-text.ts`
+ * (BLI-4341) so the collector and the server ask the same question of a record
+ * ("did this turn carry any text?") with one implementation. The extractor now
+ * re-exports these; there is no second copy to drift.
+ *
+ * Nothing here leaves the process: callers use the text to decide a COUNT.
+ */
+const TEXT_BLOCK_TYPES = new Set(["text", "input_text", "output_text"]);
+const NON_TEXT_BLOCK_TYPES = new Set([
+    "tool_result",
+    "tool_use",
+    "function_call",
+    "function_call_output",
+]);
+export function claudeUserTurnText(record) {
+    const message = record["message"];
+    return (textFromPlainTextBlocks(message) ??
+        textFromPlainTextBlocks(record["content"]) ??
+        textFromPlainTextBlocks(record["text"]) ??
+        textFromPlainTextBlocks(record["prompt"]));
+}
+export function codexUserTurnText(payload) {
+    return (textFromPlainTextBlocks(payload["content"]) ??
+        textFromPlainTextBlocks(payload["text"]) ??
+        textFromPlainTextBlocks(payload["message"]));
+}
+export function claudeAssistantText(record) {
+    const message = record["message"];
+    return textFromPlainTextBlocks(message);
+}
+export function codexAssistantText(payload) {
+    return (textFromPlainTextBlocks(payload["content"]) ??
+        textFromPlainTextBlocks(payload["text"]) ??
+        textFromPlainTextBlocks(payload["message"]));
+}
+export function textFromPlainTextBlocks(value) {
+    if (typeof value === "string")
+        return value;
+    if (!value || typeof value !== "object")
+        return null;
+    if (Array.isArray(value)) {
+        const text = value
+            .map((item) => textFromPlainTextBlocks(item))
+            .filter((item) => Boolean(item))
+            .join("\n");
+        return text || null;
+    }
+    const record = value;
+    const blockType = typeof record["type"] === "string" ? record["type"] : null;
+    if (blockType && NON_TEXT_BLOCK_TYPES.has(blockType))
+        return null;
+    if (blockType && !TEXT_BLOCK_TYPES.has(blockType))
+        return null;
+    const direct = textFromPlainTextBlocks(record["text"]) ?? textFromPlainTextBlocks(record["content"]);
+    return direct;
+}
+export function normalizeTurnText(value) {
+    return value.toLowerCase().replace(/\s+/g, " ").trim();
+}

package/dist/session-facts.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Session facts: everything deterministic about one transcript, counted once,
+ * where the file already is.
+ *
+ * BLI-4341 part A. Until now the only place a session's token totals were
+ * computed was the server: `@bli-cockpit/harvest-analysis` downloaded the
+ * transcript back out of Storage and summed it (`det.v5`). The collector holds
+ * the same bytes at harvest time and had already read every line, so the
+ * download was pure re-work, and a session with no analysis run had no token
+ * count at all.
+ *
+ * This module is the ONE implementation of those rules. The collector feeds it
+ * at upload; the server extractor feeds it the same records during its own
+ * pass, so both sides count identically by construction rather than by review.
+ * `det.v6` is `det.v5`'s rules with one owner.
+ *
+ * Contract:
+ *   - Pure. No filesystem, no network, no clock. Content in, numbers out.
+ *   - METADATA ONLY on the way out: token counts, turn counts, tool NAMES and
+ *     their counts, timestamps, byte/line sizes. Text is read in-process to
+ *     decide whether a turn counted; it is never returned.
+ *   - Two feeds, one rulebook: `observeSessionFactsRecord` for a caller that
+ *     is already parsing the JSONL (the server extractor), and
+ *     `computeSessionFacts` for a caller holding whole file contents (the
+ *     collector).
+ *
+ * Counting rules, both verified against real transcripts:
+ *   - Claude Code writes PER-TURN usage on each assistant record, repeated
+ *     across the several records of one API request, so usage is summed with a
+ *     dedupe on `message.id` (fallback `requestId`).
+ *   - Codex writes a CUMULATIVE `total_token_usage` on every `token_count`
+ *     event, so the last one wins, attributed to the `turn_context` model. Its
+ *     `input_tokens` includes cached input and its `output_tokens` already
+ *     includes reasoning, so input is normalized to fresh-only, matching the
+ *     Anthropic-shaped usage the price table expects.
+ */
+import { z } from "zod";
+/** Bump when a counting rule changes, never when a field is added. */
+export declare const SESSION_FACTS_VERSION = "det.v6";
+/** How many distinct models and tool names one session may report. */
+export declare const SESSION_FACTS_MAX_MODELS = 50;
+export declare const SESSION_FACTS_MAX_TOOL_NAMES = 200;
+export type SessionFactsSource = "codex" | "claude_code";
+export interface SessionFactsUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+}
+export interface SessionFacts {
+    /** The rules that produced these numbers. */
+    extractor_version: string;
+    source: SessionFactsSource;
+    usage_by_model: Record<string, SessionFactsUsage>;
+    models: string[];
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_creation_tokens: number;
+    total_tokens: number;
+    /** JSONL records that parsed. Unreadable lines are counted in `transcript_lines` only. */
+    record_count: number;
+    /** User prompts plus assistant responses; the two are also reported apart. */
+    turn_count: number;
+    user_prompt_count: number;
+    assistant_response_count: number;
+    tool_calls_by_name: Record<string, number>;
+    tool_call_count: number;
+    first_timestamp: string | null;
+    last_timestamp: string | null;
+    wall_duration_seconds: number | null;
+    transcript_bytes: number;
+    transcript_lines: number;
+    /** Main plus any sidecars the caller fed in. */
+    transcript_files: number;
+    /** Distinct models dropped by the cap. A truncation that says nothing is a silent failure. */
+    truncated_models: number;
+    /** Distinct tool names dropped by the cap. */
+    truncated_tool_names: number;
+}
+export interface SessionFactsAccumulator {
+    source: SessionFactsSource;
+    usage_by_model: Record<string, SessionFactsUsage>;
+    seen_usage_ids: Set<string>;
+    record_count: number;
+    user_prompt_count: number;
+    assistant_response_count: number;
+    tool_calls_by_name: Record<string, number>;
+    first_timestamp_ms: number | null;
+    last_timestamp_ms: number | null;
+    transcript_bytes: number;
+    transcript_lines: number;
+    transcript_files: number;
+    /** Codex only: the newest cumulative total and the model to attribute it to. */
+    codex_total_usage: Record<string, unknown> | null;
+    codex_model_hint: string | null;
+}
+export declare function newSessionFactsAccumulator(source: SessionFactsSource): SessionFactsAccumulator;
+/** One transcript file's size, for callers that never hold its whole text. */
+export declare function observeSessionFactsFile(acc: SessionFactsAccumulator, file: {
+    bytes: number;
+    lines: number;
+}): void;
+/** One parsed JSONL record. The caller owns parsing; this owns the rules. */
+export declare function observeSessionFactsRecord(acc: SessionFactsAccumulator, record: Record<string, unknown>): void;
+/**
+ * OpenAI semantics differ from the Anthropic-shaped usage the price table
+ * assumes: `input_tokens` INCLUDES `cached_input_tokens` and `output_tokens`
+ * already INCLUDES `reasoning_output_tokens`. Normalizing input to fresh-only
+ * is what keeps the list-price equivalent from inflating several-fold.
+ */
+export declare function codexUsageFromCumulativeTotal(total: Record<string, unknown>): SessionFactsUsage;
+export declare function finalizeSessionFacts(acc: SessionFactsAccumulator): SessionFacts;
+/**
+ * One whole file into an existing accumulator, for a caller that has the text
+ * but is not already walking its records (a Claude subagent sidecar, say).
+ * Returns the line total so the caller can report what it read.
+ */
+export declare function observeSessionFactsContent(acc: SessionFactsAccumulator, content: string): {
+    lines: number;
+};
+/**
+ * The whole-file door: give it every file of one session (the Claude main plus
+ * its subagent sidecars, or the one Codex rollout) and it returns the facts.
+ * Unparseable lines are counted in `transcript_lines` and skipped, exactly as
+ * the server extractor skips them.
+ */
+export declare function computeSessionFacts(options: {
+    source: SessionFactsSource;
+    contents: readonly string[];
+}): SessionFacts;
+export declare const SessionFactsUsageSchema: z.ZodObject<{
+    input_tokens: z.ZodNumber;
+    output_tokens: z.ZodNumber;
+    cache_read_input_tokens: z.ZodNumber;
+    cache_creation_input_tokens: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * The wire shape. Optional wherever it rides an envelope: a CLI published
+ * before this change sends no block at all, and its uploads must still
+ * validate.
+ */
+export declare const SessionFactsSchema: z.ZodObject<{
+    extractor_version: z.ZodString;
+    source: z.ZodEnum<{
+        codex: "codex";
+        claude_code: "claude_code";
+    }>;
+    usage_by_model: z.ZodRecord<z.ZodString, z.ZodObject<{
+        input_tokens: z.ZodNumber;
+        output_tokens: z.ZodNumber;
+        cache_read_input_tokens: z.ZodNumber;
+        cache_creation_input_tokens: z.ZodNumber;
+    }, z.core.$strict>>;
+    models: z.ZodArray<z.ZodString>;
+    input_tokens: z.ZodNumber;
+    output_tokens: z.ZodNumber;
+    cache_read_tokens: z.ZodNumber;
+    cache_creation_tokens: z.ZodNumber;
+    total_tokens: z.ZodNumber;
+    record_count: z.ZodNumber;
+    turn_count: z.ZodNumber;
+    user_prompt_count: z.ZodNumber;
+    assistant_response_count: z.ZodNumber;
+    tool_calls_by_name: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    tool_call_count: z.ZodNumber;
+    first_timestamp: z.ZodNullable<z.ZodString>;
+    last_timestamp: z.ZodNullable<z.ZodString>;
+    wall_duration_seconds: z.ZodNullable<z.ZodNumber>;
+    transcript_bytes: z.ZodNumber;
+    transcript_lines: z.ZodNumber;
+    transcript_files: z.ZodNumber;
+    truncated_models: z.ZodNumber;
+    truncated_tool_names: z.ZodNumber;
+}, z.core.$strict>;
+export type SessionFactsWire = z.infer<typeof SessionFactsSchema>;
+export { claudeAssistantText, claudeUserTurnText, codexAssistantText, codexUserTurnText, normalizeTurnText, textFromPlainTextBlocks, } from "./session-facts-text.js";

package/dist/session-facts.js

@@ -0,0 +1,356 @@
+/**
+ * Session facts: everything deterministic about one transcript, counted once,
+ * where the file already is.
+ *
+ * BLI-4341 part A. Until now the only place a session's token totals were
+ * computed was the server: `@bli-cockpit/harvest-analysis` downloaded the
+ * transcript back out of Storage and summed it (`det.v5`). The collector holds
+ * the same bytes at harvest time and had already read every line, so the
+ * download was pure re-work, and a session with no analysis run had no token
+ * count at all.
+ *
+ * This module is the ONE implementation of those rules. The collector feeds it
+ * at upload; the server extractor feeds it the same records during its own
+ * pass, so both sides count identically by construction rather than by review.
+ * `det.v6` is `det.v5`'s rules with one owner.
+ *
+ * Contract:
+ *   - Pure. No filesystem, no network, no clock. Content in, numbers out.
+ *   - METADATA ONLY on the way out: token counts, turn counts, tool NAMES and
+ *     their counts, timestamps, byte/line sizes. Text is read in-process to
+ *     decide whether a turn counted; it is never returned.
+ *   - Two feeds, one rulebook: `observeSessionFactsRecord` for a caller that
+ *     is already parsing the JSONL (the server extractor), and
+ *     `computeSessionFacts` for a caller holding whole file contents (the
+ *     collector).
+ *
+ * Counting rules, both verified against real transcripts:
+ *   - Claude Code writes PER-TURN usage on each assistant record, repeated
+ *     across the several records of one API request, so usage is summed with a
+ *     dedupe on `message.id` (fallback `requestId`).
+ *   - Codex writes a CUMULATIVE `total_token_usage` on every `token_count`
+ *     event, so the last one wins, attributed to the `turn_context` model. Its
+ *     `input_tokens` includes cached input and its `output_tokens` already
+ *     includes reasoning, so input is normalized to fresh-only, matching the
+ *     Anthropic-shaped usage the price table expects.
+ */
+import { z } from "zod";
+import { claudeAssistantText, claudeUserTurnText, codexAssistantText, codexUserTurnText, } from "./session-facts-text.js";
+/** Bump when a counting rule changes, never when a field is added. */
+export const SESSION_FACTS_VERSION = "det.v6";
+/** How many distinct models and tool names one session may report. */
+export const SESSION_FACTS_MAX_MODELS = 50;
+export const SESSION_FACTS_MAX_TOOL_NAMES = 200;
+const MAX_MODEL_NAME_CHARS = 200;
+const MAX_TOOL_NAME_CHARS = 120;
+export function newSessionFactsAccumulator(source) {
+    return {
+        source,
+        usage_by_model: {},
+        seen_usage_ids: new Set(),
+        record_count: 0,
+        user_prompt_count: 0,
+        assistant_response_count: 0,
+        tool_calls_by_name: {},
+        first_timestamp_ms: null,
+        last_timestamp_ms: null,
+        transcript_bytes: 0,
+        transcript_lines: 0,
+        transcript_files: 0,
+        codex_total_usage: null,
+        codex_model_hint: null,
+    };
+}
+/** One transcript file's size, for callers that never hold its whole text. */
+export function observeSessionFactsFile(acc, file) {
+    acc.transcript_files += 1;
+    acc.transcript_bytes += Math.max(0, Math.trunc(file.bytes));
+    acc.transcript_lines += Math.max(0, Math.trunc(file.lines));
+}
+/** One parsed JSONL record. The caller owns parsing; this owns the rules. */
+export function observeSessionFactsRecord(acc, record) {
+    acc.record_count += 1;
+    const ms = parseTimestampMs(record["timestamp"]);
+    if (ms != null) {
+        acc.first_timestamp_ms =
+            acc.first_timestamp_ms == null ? ms : Math.min(acc.first_timestamp_ms, ms);
+        acc.last_timestamp_ms =
+            acc.last_timestamp_ms == null ? ms : Math.max(acc.last_timestamp_ms, ms);
+    }
+    if (acc.source === "claude_code")
+        observeClaudeRecord(acc, record);
+    else
+        observeCodexRecord(acc, record);
+}
+function observeClaudeRecord(acc, record) {
+    const type = typeof record["type"] === "string" ? record["type"] : "";
+    if (type === "user") {
+        if (record["isMeta"] === true)
+            return;
+        const text = claudeUserTurnText(record);
+        if (text?.trim())
+            acc.user_prompt_count += 1;
+        return;
+    }
+    if (type !== "assistant")
+        return;
+    const message = record["message"];
+    if (!message || typeof message !== "object")
+        return;
+    const msg = message;
+    const model = typeof msg["model"] === "string" ? msg["model"] : null;
+    const usage = msg["usage"];
+    // One API request emits several records repeating the same usage; the id is
+    // what makes summing them safe.
+    const usageId = (typeof msg["id"] === "string" && msg["id"]) ||
+        (typeof record["requestId"] === "string" && record["requestId"]) ||
+        null;
+    if (model && usage && typeof usage === "object" && usageId && !acc.seen_usage_ids.has(usageId)) {
+        acc.seen_usage_ids.add(usageId);
+        addClaudeUsage(acc, model, usage);
+    }
+    if (claudeAssistantText(record)?.trim())
+        acc.assistant_response_count += 1;
+    const content = msg["content"];
+    if (!Array.isArray(content))
+        return;
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b["type"] !== "tool_use")
+            continue;
+        countTool(acc, typeof b["name"] === "string" ? b["name"] : "unknown");
+    }
+}
+function observeCodexRecord(acc, record) {
+    const type = String(record["type"] ?? "");
+    const payload = record["payload"];
+    const p = payload && typeof payload === "object" ? payload : {};
+    if (type === "turn_context") {
+        if (typeof p["model"] === "string")
+            acc.codex_model_hint = p["model"];
+        return;
+    }
+    if (type === "response_item") {
+        const itemType = String(p["type"] ?? "");
+        if ((itemType === "message" || itemType === "user_message") && p["role"] === "user") {
+            if (codexUserTurnText(p)?.trim())
+                acc.user_prompt_count += 1;
+            return;
+        }
+        if (itemType === "message" && p["role"] === "assistant") {
+            if (codexAssistantText(p)?.trim())
+                acc.assistant_response_count += 1;
+            return;
+        }
+        if (itemType === "function_call") {
+            countTool(acc, typeof p["name"] === "string" ? p["name"] : "unknown");
+        }
+        return;
+    }
+    if (type !== "event_msg")
+        return;
+    if (String(p["type"] ?? "") !== "token_count")
+        return;
+    const info = p["info"];
+    if (!info || typeof info !== "object")
+        return;
+    const total = info["total_token_usage"];
+    // Cumulative: the last event of the session is the session total.
+    if (total && typeof total === "object") {
+        acc.codex_total_usage = total;
+    }
+}
+function countTool(acc, name) {
+    const key = name.slice(0, MAX_TOOL_NAME_CHARS) || "unknown";
+    acc.tool_calls_by_name[key] = (acc.tool_calls_by_name[key] ?? 0) + 1;
+}
+function addClaudeUsage(acc, model, usage) {
+    const key = model.slice(0, MAX_MODEL_NAME_CHARS);
+    const current = acc.usage_by_model[key] ?? emptyUsage();
+    current.input_tokens += num(usage["input_tokens"]);
+    current.output_tokens += num(usage["output_tokens"]);
+    current.cache_read_input_tokens += num(usage["cache_read_input_tokens"]);
+    current.cache_creation_input_tokens += num(usage["cache_creation_input_tokens"]);
+    acc.usage_by_model[key] = current;
+}
+/**
+ * OpenAI semantics differ from the Anthropic-shaped usage the price table
+ * assumes: `input_tokens` INCLUDES `cached_input_tokens` and `output_tokens`
+ * already INCLUDES `reasoning_output_tokens`. Normalizing input to fresh-only
+ * is what keeps the list-price equivalent from inflating several-fold.
+ */
+export function codexUsageFromCumulativeTotal(total) {
+    const input = num(total["input_tokens"]);
+    const cached = num(total["cached_input_tokens"]);
+    return {
+        input_tokens: Math.max(0, input - cached),
+        output_tokens: num(total["output_tokens"]),
+        cache_read_input_tokens: cached,
+        cache_creation_input_tokens: 0,
+    };
+}
+export function finalizeSessionFacts(acc) {
+    // A Codex session whose usage never named a model is left uncounted rather
+    // than filed under a guess: det.v5 did the same, and a token total on the
+    // wrong model is money attributed to the wrong place.
+    if (acc.codex_total_usage && acc.codex_model_hint) {
+        acc.usage_by_model[acc.codex_model_hint.slice(0, MAX_MODEL_NAME_CHARS)] =
+            codexUsageFromCumulativeTotal(acc.codex_total_usage);
+    }
+    const usageEntries = Object.entries(acc.usage_by_model).sort((a, b) => usageTotal(b[1]) - usageTotal(a[1]) || a[0].localeCompare(b[0]));
+    const keptUsage = usageEntries.slice(0, SESSION_FACTS_MAX_MODELS);
+    const toolEntries = Object.entries(acc.tool_calls_by_name).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const keptTools = toolEntries.slice(0, SESSION_FACTS_MAX_TOOL_NAMES);
+    const usage_by_model = Object.fromEntries(keptUsage);
+    const tool_calls_by_name = Object.fromEntries(keptTools);
+    const totals = keptUsage.reduce((sum, [, usage]) => ({
+        input_tokens: sum.input_tokens + usage.input_tokens,
+        output_tokens: sum.output_tokens + usage.output_tokens,
+        cache_read_input_tokens: sum.cache_read_input_tokens + usage.cache_read_input_tokens,
+        cache_creation_input_tokens: sum.cache_creation_input_tokens + usage.cache_creation_input_tokens,
+    }), emptyUsage());
+    const first = acc.first_timestamp_ms;
+    const last = acc.last_timestamp_ms;
+    return {
+        extractor_version: SESSION_FACTS_VERSION,
+        source: acc.source,
+        usage_by_model,
+        models: keptUsage.map(([model]) => model).sort((a, b) => a.localeCompare(b)),
+        input_tokens: totals.input_tokens,
+        output_tokens: totals.output_tokens,
+        cache_read_tokens: totals.cache_read_input_tokens,
+        cache_creation_tokens: totals.cache_creation_input_tokens,
+        total_tokens: usageTotal(totals),
+        record_count: acc.record_count,
+        turn_count: acc.user_prompt_count + acc.assistant_response_count,
+        user_prompt_count: acc.user_prompt_count,
+        assistant_response_count: acc.assistant_response_count,
+        tool_calls_by_name,
+        tool_call_count: keptTools.reduce((sum, [, count]) => sum + count, 0),
+        first_timestamp: first == null ? null : new Date(first).toISOString(),
+        last_timestamp: last == null ? null : new Date(last).toISOString(),
+        wall_duration_seconds: first == null || last == null ? null : Math.max(0, Math.round((last - first) / 1000)),
+        transcript_bytes: acc.transcript_bytes,
+        transcript_lines: acc.transcript_lines,
+        transcript_files: acc.transcript_files,
+        truncated_models: usageEntries.length - keptUsage.length,
+        truncated_tool_names: toolEntries.length - keptTools.length,
+    };
+}
+/**
+ * One whole file into an existing accumulator, for a caller that has the text
+ * but is not already walking its records (a Claude subagent sidecar, say).
+ * Returns the line total so the caller can report what it read.
+ */
+export function observeSessionFactsContent(acc, content) {
+    let lines = 0;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        lines += 1;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            // Silent by design: the parser's message quotes the offending line,
+            // which is transcript content. The line still counts toward the file's
+            // line total, so the loss is visible as a number.
+            continue;
+        }
+        if (!record || typeof record !== "object" || Array.isArray(record))
+            continue;
+        observeSessionFactsRecord(acc, record);
+    }
+    observeSessionFactsFile(acc, { bytes: byteLength(content), lines });
+    return { lines };
+}
+/**
+ * The whole-file door: give it every file of one session (the Claude main plus
+ * its subagent sidecars, or the one Codex rollout) and it returns the facts.
+ * Unparseable lines are counted in `transcript_lines` and skipped, exactly as
+ * the server extractor skips them.
+ */
+export function computeSessionFacts(options) {
+    const acc = newSessionFactsAccumulator(options.source);
+    for (const content of options.contents) {
+        observeSessionFactsContent(acc, content);
+    }
+    return finalizeSessionFacts(acc);
+}
+function usageTotal(usage) {
+    return (usage.input_tokens +
+        usage.output_tokens +
+        usage.cache_read_input_tokens +
+        usage.cache_creation_input_tokens);
+}
+function emptyUsage() {
+    return {
+        input_tokens: 0,
+        output_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+    };
+}
+function byteLength(value) {
+    return typeof Buffer === "undefined"
+        ? new TextEncoder().encode(value).length
+        : Buffer.byteLength(value, "utf8");
+}
+function parseTimestampMs(value) {
+    if (typeof value !== "string")
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+const TokenCountSchema = z.number().int().nonnegative().max(1_000_000_000_000);
+export const SessionFactsUsageSchema = z
+    .object({
+    input_tokens: TokenCountSchema,
+    output_tokens: TokenCountSchema,
+    cache_read_input_tokens: TokenCountSchema,
+    cache_creation_input_tokens: TokenCountSchema,
+})
+    .strict();
+/**
+ * The wire shape. Optional wherever it rides an envelope: a CLI published
+ * before this change sends no block at all, and its uploads must still
+ * validate.
+ */
+export const SessionFactsSchema = z
+    .object({
+    extractor_version: z.string().trim().min(1).max(40),
+    source: z.enum(["codex", "claude_code"]),
+    usage_by_model: z
+        .record(z.string().min(1).max(MAX_MODEL_NAME_CHARS), SessionFactsUsageSchema)
+        .refine((value) => Object.keys(value).length <= SESSION_FACTS_MAX_MODELS, { message: "too many models" }),
+    models: z.array(z.string().min(1).max(MAX_MODEL_NAME_CHARS)).max(SESSION_FACTS_MAX_MODELS),
+    input_tokens: TokenCountSchema,
+    output_tokens: TokenCountSchema,
+    cache_read_tokens: TokenCountSchema,
+    cache_creation_tokens: TokenCountSchema,
+    total_tokens: TokenCountSchema,
+    record_count: z.number().int().nonnegative(),
+    turn_count: z.number().int().nonnegative(),
+    user_prompt_count: z.number().int().nonnegative(),
+    assistant_response_count: z.number().int().nonnegative(),
+    tool_calls_by_name: z
+        .record(z.string().min(1).max(MAX_TOOL_NAME_CHARS), z.number().int().nonnegative())
+        .refine((value) => Object.keys(value).length <= SESSION_FACTS_MAX_TOOL_NAMES, { message: "too many tool names" }),
+    tool_call_count: z.number().int().nonnegative(),
+    first_timestamp: z.string().datetime({ offset: true }).nullable(),
+    last_timestamp: z.string().datetime({ offset: true }).nullable(),
+    wall_duration_seconds: z.number().int().nonnegative().nullable(),
+    transcript_bytes: z.number().int().nonnegative(),
+    transcript_lines: z.number().int().nonnegative(),
+    transcript_files: z.number().int().nonnegative(),
+    truncated_models: z.number().int().nonnegative(),
+    truncated_tool_names: z.number().int().nonnegative(),
+})
+    .strict();
+export { claudeAssistantText, claudeUserTurnText, codexAssistantText, codexUserTurnText, normalizeTurnText, textFromPlainTextBlocks, } from "./session-facts-text.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -17,11 +17,13 @@
     },
     "./memory-experience": {
       "types": "./dist/memory-experience.d.ts",
-      "import": "./dist/memory-experience.js"
+      "import": "./dist/memory-experience.js",
+      "default": "./dist/memory-experience.js"
     },
     "./evidence-storage-encoding": {
       "types": "./dist/evidence-storage-encoding.d.ts",
-      "import": "./dist/evidence-storage-encoding.js"
+      "import": "./dist/evidence-storage-encoding.js",
+      "default": "./dist/evidence-storage-encoding.js"
     }
   },
   "publishConfig": {