sidekick-shared 0.28.2 → 0.29.0

package/dist/parsers/codexRolloutOrigin.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Where a Codex rollout came from, read from its `session_meta` record:
+ * a session a person started, a fork of another session, or a subagent.
+ *
+ * Codex writes `session_meta.source` as a plain string for sessions started
+ * from a surface (`cli`, `vscode`, `exec`, …) and as an object for subagents:
+ * `{ subagent: { thread_spawn: { parent_thread_id, … } } }` for a spawned
+ * agent, `{ subagent: { other: 'guardian' } }` for internal reviewers, or
+ * `{ subagent: 'review' }`. The same JSON appears as a string in the state
+ * database's `threads.source`. A forked rollout records `forked_from_id`, and
+ * embeds its parent's `session_meta` after its own, so only the first counts.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module parsers/codexRolloutOrigin
+ */
+export interface CodexRolloutOrigin {
+    /** `session_meta.forked_from_id`: the session this rollout was forked from. */
+    forkedFromId?: string;
+    /**
+     * `session_meta.source` when it is a string (`cli`, `vscode`, `exec`, …),
+     * or `'subagent'` when it is a subagent object.
+     */
+    source?: string;
+    /** The rollout was written by a subagent (`source: { subagent: … }`), not a person. */
+    isSubagent: boolean;
+    /**
+     * The parent session: `forkedFromId`, else the spawn's `parent_thread_id`,
+     * else (subagents only) the top-level `parent_thread_id`.
+     */
+    parentId?: string;
+    /**
+     * Subagent variant: `thread_spawn`, `review`, `compact`, or the name of an
+     * `other` subagent (for example `guardian`).
+     */
+    subagentKind?: string;
+}
+/**
+ * Parent thread id of a spawned subagent's `source` (object, or JSON text as
+ * stored in `threads.source`): `subagent.thread_spawn.parent_thread_id`.
+ */
+export declare function codexSpawnParentFromSource(source: unknown): string | undefined;
+/**
+ * Origin of a Codex rollout from its `session_meta`. Accepts the parsed
+ * `session_meta` record, its payload, or the rollout's records in order (the
+ * first `session_meta` wins: a fork embeds its parent's after its own).
+ * Anything else yields `{ isSubagent: false }`.
+ */
+export declare function codexRolloutOrigin(input: unknown | readonly unknown[]): CodexRolloutOrigin;

package/dist/parsers/codexRolloutOrigin.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Where a Codex rollout came from, read from its `session_meta` record:
+ * a session a person started, a fork of another session, or a subagent.
+ *
+ * Codex writes `session_meta.source` as a plain string for sessions started
+ * from a surface (`cli`, `vscode`, `exec`, …) and as an object for subagents:
+ * `{ subagent: { thread_spawn: { parent_thread_id, … } } }` for a spawned
+ * agent, `{ subagent: { other: 'guardian' } }` for internal reviewers, or
+ * `{ subagent: 'review' }`. The same JSON appears as a string in the state
+ * database's `threads.source`. A forked rollout records `forked_from_id`, and
+ * embeds its parent's `session_meta` after its own, so only the first counts.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module parsers/codexRolloutOrigin
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexSpawnParentFromSource = codexSpawnParentFromSource;
+exports.codexRolloutOrigin = codexRolloutOrigin;
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** A `source` value as an object: rollouts store it parsed, the database as JSON text. */
+function sourceObject(source) {
+    if (typeof source !== 'string')
+        return record(source);
+    if (!source.startsWith('{'))
+        return undefined;
+    try {
+        return record(JSON.parse(source));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parent thread id of a spawned subagent's `source` (object, or JSON text as
+ * stored in `threads.source`): `subagent.thread_spawn.parent_thread_id`.
+ */
+function codexSpawnParentFromSource(source) {
+    const spawn = record(record(sourceObject(source)?.subagent)?.thread_spawn);
+    const parent = spawn?.parent_thread_id;
+    return typeof parent === 'string' ? parent : undefined;
+}
+function subagentKindOf(subagent) {
+    if (typeof subagent === 'string')
+        return nonEmpty(subagent);
+    const variant = record(subagent);
+    if (!variant)
+        return undefined;
+    const other = nonEmpty(variant.other);
+    if (other)
+        return other;
+    return Object.keys(variant)[0];
+}
+/** The `session_meta` payload of a record, of a bare payload, or of the first in a list. */
+function metaPayload(input) {
+    if (Array.isArray(input)) {
+        for (const item of input) {
+            const row = record(item);
+            if (row?.type === 'session_meta')
+                return record(row.payload);
+        }
+        return undefined;
+    }
+    const row = record(input);
+    if (!row)
+        return undefined;
+    if (row.type === 'session_meta')
+        return record(row.payload);
+    // A payload on its own, as `readSessionMeta()` returns it.
+    if (row.type === undefined && row.payload === undefined)
+        return row;
+    return undefined;
+}
+/**
+ * Origin of a Codex rollout from its `session_meta`. Accepts the parsed
+ * `session_meta` record, its payload, or the rollout's records in order (the
+ * first `session_meta` wins: a fork embeds its parent's after its own).
+ * Anything else yields `{ isSubagent: false }`.
+ */
+function codexRolloutOrigin(input) {
+    const payload = metaPayload(input);
+    if (!payload)
+        return { isSubagent: false };
+    const forkedFromId = nonEmpty(payload.forked_from_id);
+    const object = sourceObject(payload.source);
+    const isSubagent = object !== undefined && 'subagent' in object;
+    const source = typeof payload.source === 'string' && object === undefined
+        ? nonEmpty(payload.source)
+        : isSubagent
+            ? 'subagent'
+            : undefined;
+    const parentId = forkedFromId ??
+        nonEmpty(codexSpawnParentFromSource(object)) ??
+        (isSubagent ? nonEmpty(payload.parent_thread_id) : undefined);
+    const subagentKind = isSubagent ? subagentKindOf(object?.subagent) : undefined;
+    return {
+        ...(forkedFromId ? { forkedFromId } : {}),
+        ...(source ? { source } : {}),
+        isSubagent,
+        ...(parentId ? { parentId } : {}),
+        ...(subagentKind ? { subagentKind } : {}),
+    };
+}

package/dist/parsers/openCodeParser.d.ts

@@ -12,6 +12,7 @@
  */
 import type { SessionEvent } from '../types/sessionEvent';
 import type { OpenCodeMessage, OpenCodePart, DbMessage, DbPart } from '../types/opencode';
+import { type NormalizedUsage } from '../usageNormalization';
 /**
  * Normalizes an OpenCode tool name to PascalCase.
  *
@@ -38,6 +39,43 @@ export declare function detectPlanModeFromText(text: string): 'enter' | 'exit' |
  * This adds snake_case aliases without removing the originals.
  */
 export declare function normalizeToolInput(input: Record<string, unknown>): Record<string, unknown>;
+/** OpenCode token counts as stored on an assistant message or step. */
+export interface OpenCodeTokenCounts {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    /** Provider-reported total, stored by OpenCode since late 2025. */
+    total?: number;
+}
+/**
+ * Token counts from a message in either storage shape: database rows are
+ * mapped to flat `cacheRead` / `cacheWrite`, while file-storage messages keep
+ * OpenCode's nested `cache: { read, write }`.
+ * @internal
+ */
+export declare function openCodeTokenCounts(tokens: unknown): OpenCodeTokenCounts;
+/**
+ * How a stored OpenCode message splits its tokens. Current OpenCode stores
+ * every bucket disjoint for every provider: `input` excludes cache reads and
+ * writes (since 2025-11) and `output` excludes `reasoning` (since 2026-04),
+ * with `total` equal to their sum. Older messages either counted cached input
+ * in `input` (OpenAI-compatible providers) or reasoning in `output`. The
+ * stored `total` tells the layouts apart; without it the current layout is
+ * assumed.
+ * @internal
+ */
+export declare function openCodeTokenLayout(tokens: OpenCodeTokenCounts): {
+    inputIncludesCache: boolean;
+    reasoningInOutput: boolean;
+};
+/** Normalizes one OpenCode message's or step's stored tokens. @internal */
+export declare function normalizeOpenCodeUsage(tokens: OpenCodeTokenCounts, providerID: string | undefined, extra?: {
+    source?: string;
+    model?: string;
+    reportedCostUsd?: number;
+}): NormalizedUsage;
 /**
  * Converts an OpenCode message and its parts into SessionEvent array.
  *

package/dist/parsers/openCodeParser.js

@@ -15,6 +15,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeToolName = normalizeToolName;
 exports.detectPlanModeFromText = detectPlanModeFromText;
 exports.normalizeToolInput = normalizeToolInput;
+exports.openCodeTokenCounts = openCodeTokenCounts;
+exports.openCodeTokenLayout = openCodeTokenLayout;
+exports.normalizeOpenCodeUsage = normalizeOpenCodeUsage;
 exports.convertOpenCodeMessage = convertOpenCodeMessage;
 exports.parseDbMessageData = parseDbMessageData;
 exports.parseDbPartData = parseDbPartData;
@@ -123,6 +126,78 @@ function toISOString(time) {
         return time;
     return new Date(time).toISOString();
 }
+/**
+ * Token counts from a message in either storage shape: database rows are
+ * mapped to flat `cacheRead` / `cacheWrite`, while file-storage messages keep
+ * OpenCode's nested `cache: { read, write }`.
+ * @internal
+ */
+function openCodeTokenCounts(tokens) {
+    const raw = (tokens ?? {});
+    const cache = (raw.cache ?? {});
+    const num = (value) => (typeof value === 'number' ? value : undefined);
+    return {
+        input: num(raw.input),
+        output: num(raw.output),
+        reasoning: num(raw.reasoning),
+        cacheRead: num(raw.cacheRead) ?? num(cache.read),
+        cacheWrite: num(raw.cacheWrite) ?? num(cache.write),
+        total: num(raw.total),
+    };
+}
+/**
+ * How a stored OpenCode message splits its tokens. Current OpenCode stores
+ * every bucket disjoint for every provider: `input` excludes cache reads and
+ * writes (since 2025-11) and `output` excludes `reasoning` (since 2026-04),
+ * with `total` equal to their sum. Older messages either counted cached input
+ * in `input` (OpenAI-compatible providers) or reasoning in `output`. The
+ * stored `total` tells the layouts apart; without it the current layout is
+ * assumed.
+ * @internal
+ */
+function openCodeTokenLayout(tokens) {
+    const n = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+    const input = n(tokens.input);
+    const output = n(tokens.output);
+    const reasoning = n(tokens.reasoning);
+    const cache = n(tokens.cacheRead) + n(tokens.cacheWrite);
+    const total = n(tokens.total);
+    if (total > 0 && total !== input + cache + output + reasoning) {
+        if (reasoning > 0 && total === input + cache + output) {
+            return { inputIncludesCache: false, reasoningInOutput: true };
+        }
+        if (cache > 0 && total === input + output + reasoning) {
+            return { inputIncludesCache: true, reasoningInOutput: false };
+        }
+        if (cache > 0 && reasoning > 0 && total === input + output) {
+            return { inputIncludesCache: true, reasoningInOutput: true };
+        }
+    }
+    return { inputIncludesCache: false, reasoningInOutput: false };
+}
+/** Normalizes one OpenCode message's or step's stored tokens. @internal */
+function normalizeOpenCodeUsage(tokens, providerID, extra = {}) {
+    const layout = openCodeTokenLayout(tokens);
+    return (0, usageNormalization_1.normalizeProviderUsage)({
+        // `openai` semantics subtract cache reads from input; only an old
+        // cache-inclusive message needs that.
+        semantics: layout.inputIncludesCache
+            ? 'openai'
+            : providerID === 'anthropic'
+                ? 'anthropic'
+                : 'sidekick',
+        provider: providerID ?? 'opencode',
+        ...(extra.source ? { source: extra.source } : {}),
+        ...(extra.model ? { model: extra.model } : {}),
+        inputTokens: tokens.input,
+        outputTokens: tokens.output,
+        cacheReadTokens: tokens.cacheRead,
+        cacheWriteTokens: tokens.cacheWrite,
+        reasoningTokens: tokens.reasoning,
+        reasoningIncludedInOutput: layout.reasoningInOutput,
+        ...(extra.reportedCostUsd !== undefined ? { reportedCostUsd: extra.reportedCostUsd } : {}),
+    });
+}
 /**
  * Converts an OpenCode message and its parts into SessionEvent array.
  *
@@ -328,31 +403,20 @@ function convertAssistantMessage(message, parts) {
         : stepFinishCost > 0
             ? stepFinishCost
             : undefined;
-    const usage = {
-        input_tokens: message.tokens.input || 0,
-        output_tokens: message.tokens.output || 0,
-        cache_creation_input_tokens: message.tokens.cacheWrite || 0,
-        cache_read_input_tokens: message.tokens.cacheRead || 0,
-        reported_cost: reportedCost,
-        reasoning_tokens: message.tokens.reasoning || 0,
-    };
-    const normalizedUsage = (0, usageNormalization_1.normalizeProviderUsage)({
-        semantics: message.providerID === 'openai'
-            ? 'openai'
-            : message.providerID === 'anthropic'
-                ? 'anthropic'
-                : 'sidekick',
-        provider: message.providerID ?? 'opencode',
+    const counts = openCodeTokenCounts(message.tokens);
+    const normalizedUsage = normalizeOpenCodeUsage(counts, message.providerID, {
         source: 'opencode-message',
         model: message.modelID,
-        inputTokens: message.tokens.input,
-        outputTokens: message.tokens.output,
-        cacheReadTokens: message.tokens.cacheRead,
-        cacheWriteTokens: message.tokens.cacheWrite,
-        reasoningTokens: message.tokens.reasoning,
-        reasoningIncludedInOutput: message.providerID === 'openai',
         reportedCostUsd: reportedCost,
     });
+    const usage = {
+        input_tokens: normalizedUsage.uncachedInputTokens,
+        output_tokens: counts.output || 0,
+        cache_creation_input_tokens: counts.cacheWrite || 0,
+        cache_read_input_tokens: counts.cacheRead || 0,
+        reported_cost: reportedCost,
+        reasoning_tokens: counts.reasoning || 0,
+    };
     const timestamp = toISOString(message.time.completed || message.time.created);
     const retryAttempts = parts
         .filter((part) => part.type === 'retry')
@@ -491,6 +555,7 @@ function parseDbMessageData(row) {
             cacheRead: cache?.read || 0,
             cacheWrite: cache?.write || 0,
             reasoning: tokens?.reasoning || 0,
+            ...(typeof tokens?.total === 'number' ? { total: tokens.total } : {}),
         },
         time: {
             created: time?.created || row.time_created,

package/dist/pricing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `sidekick-shared/pricing` — model pricing, model-id identity, usage
+ * normalization and cost, cost provenance, cost/token formatting, and text
+ * token estimates, as one small pure entry (no filesystem, network, or Zod).
+ *
+ * For hosts that price usage or format costs without session reading: it
+ * loads a handful of modules instead of the full browser surface. LiteLLM
+ * catalog hydration stays Node-only in `sidekick-shared/node`
+ * (`hydratePricingCatalog`); once hydrated, lookups here see the catalog.
+ * Everything here is also exported from the package root and
+ * `sidekick-shared/browser`.
+ *
+ * @module pricing
+ */
+export { MODEL_PROVIDER_IDS, canonicalModelId, isMovingModelAlias, parseModelId, compareModelIds, sortModelIds, shortModelName, getModelDisplayInfo, getModelInfo, getModelPricing, resolveModelPricing, registerModelPricing, clearRegisteredModelPricing, getPricingCatalogInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, costSourceFromPricingProvenance, mergeCostComponents, formatCost, } from './modelInfo';
+export type { ModelPricing, ModelPricingSource, ModelPricingMatch, ModelPricingProvenance, ResolvedModelPricing, ResolveModelPricingOptions, RegisterModelPricingOptions, PricingCatalogSource, PricingCatalogInfo, CostComponent, CostTokenUsage, ModelProvider, ParsedModelId, ModelInfo, CostSource, CostProvenanceInput, CostWithProvenance, ModelDisplayInfo, FormatCostOptions, } from './modelInfo';
+export { normalizeProviderUsage, extractNormalizedUsage, calculateNormalizedUsageCost, } from './usageNormalization';
+export type { UsageProvider, UsageSemantics, UsageNormalizationProvenance, AnthropicUsageInput, OpenAIUsageInput, SidekickUsageInput, ProviderUsageInput, NormalizedUsage, PricingProvenance, NormalizedUsageCostInput, NormalizedUsageCost, } from './usageNormalization';
+export { formatTokenCount, formatDurationMs } from './formatting';
+export type { FormatTokenCountOptions, FormatDurationMsOptions } from './formatting';
+export { ASCII_CHARS_PER_TOKEN, estimateTextTokens, estimateSerializedTokens, } from './tokenEstimation';
+export type { TokenEstimationMethod, TokenEstimationConfidence, ExactTokenCounterContext, ExactTokenCounter, TokenEstimationOptions, TokenEstimate, } from './tokenEstimation';

package/dist/pricing.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * `sidekick-shared/pricing` — model pricing, model-id identity, usage
+ * normalization and cost, cost provenance, cost/token formatting, and text
+ * token estimates, as one small pure entry (no filesystem, network, or Zod).
+ *
+ * For hosts that price usage or format costs without session reading: it
+ * loads a handful of modules instead of the full browser surface. LiteLLM
+ * catalog hydration stays Node-only in `sidekick-shared/node`
+ * (`hydratePricingCatalog`); once hydrated, lookups here see the catalog.
+ * Everything here is also exported from the package root and
+ * `sidekick-shared/browser`.
+ *
+ * @module pricing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateSerializedTokens = exports.estimateTextTokens = exports.ASCII_CHARS_PER_TOKEN = exports.formatDurationMs = exports.formatTokenCount = exports.calculateNormalizedUsageCost = exports.extractNormalizedUsage = exports.normalizeProviderUsage = exports.formatCost = exports.mergeCostComponents = exports.costSourceFromPricingProvenance = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getPricingCatalogInfo = exports.clearRegisteredModelPricing = exports.registerModelPricing = exports.resolveModelPricing = exports.getModelPricing = exports.getModelInfo = exports.getModelDisplayInfo = exports.shortModelName = exports.sortModelIds = exports.compareModelIds = exports.parseModelId = exports.isMovingModelAlias = exports.canonicalModelId = exports.MODEL_PROVIDER_IDS = void 0;
+var modelInfo_1 = require("./modelInfo");
+Object.defineProperty(exports, "MODEL_PROVIDER_IDS", { enumerable: true, get: function () { return modelInfo_1.MODEL_PROVIDER_IDS; } });
+Object.defineProperty(exports, "canonicalModelId", { enumerable: true, get: function () { return modelInfo_1.canonicalModelId; } });
+Object.defineProperty(exports, "isMovingModelAlias", { enumerable: true, get: function () { return modelInfo_1.isMovingModelAlias; } });
+Object.defineProperty(exports, "parseModelId", { enumerable: true, get: function () { return modelInfo_1.parseModelId; } });
+Object.defineProperty(exports, "compareModelIds", { enumerable: true, get: function () { return modelInfo_1.compareModelIds; } });
+Object.defineProperty(exports, "sortModelIds", { enumerable: true, get: function () { return modelInfo_1.sortModelIds; } });
+Object.defineProperty(exports, "shortModelName", { enumerable: true, get: function () { return modelInfo_1.shortModelName; } });
+Object.defineProperty(exports, "getModelDisplayInfo", { enumerable: true, get: function () { return modelInfo_1.getModelDisplayInfo; } });
+Object.defineProperty(exports, "getModelInfo", { enumerable: true, get: function () { return modelInfo_1.getModelInfo; } });
+Object.defineProperty(exports, "getModelPricing", { enumerable: true, get: function () { return modelInfo_1.getModelPricing; } });
+Object.defineProperty(exports, "resolveModelPricing", { enumerable: true, get: function () { return modelInfo_1.resolveModelPricing; } });
+Object.defineProperty(exports, "registerModelPricing", { enumerable: true, get: function () { return modelInfo_1.registerModelPricing; } });
+Object.defineProperty(exports, "clearRegisteredModelPricing", { enumerable: true, get: function () { return modelInfo_1.clearRegisteredModelPricing; } });
+Object.defineProperty(exports, "getPricingCatalogInfo", { enumerable: true, get: function () { return modelInfo_1.getPricingCatalogInfo; } });
+Object.defineProperty(exports, "calculateCost", { enumerable: true, get: function () { return modelInfo_1.calculateCost; } });
+Object.defineProperty(exports, "calculateCostWithPricing", { enumerable: true, get: function () { return modelInfo_1.calculateCostWithPricing; } });
+Object.defineProperty(exports, "calculateCostWithProvenance", { enumerable: true, get: function () { return modelInfo_1.calculateCostWithProvenance; } });
+Object.defineProperty(exports, "mergeCostSources", { enumerable: true, get: function () { return modelInfo_1.mergeCostSources; } });
+Object.defineProperty(exports, "costSourceFromPricingProvenance", { enumerable: true, get: function () { return modelInfo_1.costSourceFromPricingProvenance; } });
+Object.defineProperty(exports, "mergeCostComponents", { enumerable: true, get: function () { return modelInfo_1.mergeCostComponents; } });
+Object.defineProperty(exports, "formatCost", { enumerable: true, get: function () { return modelInfo_1.formatCost; } });
+var usageNormalization_1 = require("./usageNormalization");
+Object.defineProperty(exports, "normalizeProviderUsage", { enumerable: true, get: function () { return usageNormalization_1.normalizeProviderUsage; } });
+Object.defineProperty(exports, "extractNormalizedUsage", { enumerable: true, get: function () { return usageNormalization_1.extractNormalizedUsage; } });
+Object.defineProperty(exports, "calculateNormalizedUsageCost", { enumerable: true, get: function () { return usageNormalization_1.calculateNormalizedUsageCost; } });
+var formatting_1 = require("./formatting");
+Object.defineProperty(exports, "formatTokenCount", { enumerable: true, get: function () { return formatting_1.formatTokenCount; } });
+Object.defineProperty(exports, "formatDurationMs", { enumerable: true, get: function () { return formatting_1.formatDurationMs; } });
+var tokenEstimation_1 = require("./tokenEstimation");
+Object.defineProperty(exports, "ASCII_CHARS_PER_TOKEN", { enumerable: true, get: function () { return tokenEstimation_1.ASCII_CHARS_PER_TOKEN; } });
+Object.defineProperty(exports, "estimateTextTokens", { enumerable: true, get: function () { return tokenEstimation_1.estimateTextTokens; } });
+Object.defineProperty(exports, "estimateSerializedTokens", { enumerable: true, get: function () { return tokenEstimation_1.estimateSerializedTokens; } });

package/dist/pricingCatalog.d.ts

@@ -51,6 +51,12 @@ export interface HydrateResult {
     contextWindowEntries: number;
     /** ISO timestamp of the fetch that produced the cache. */
     fetchedAt: string;
+    /**
+     * `getPricingCatalogInfo().digest` after hydration: a stable fingerprint of
+     * every active pricing table, so callers can record which prices produced
+     * an estimate. See `getPricingCatalogInfo()` for the source and staleness.
+     */
+    digest: string;
 }
 export declare const LITELLM_CATALOG_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
 /**
@@ -61,6 +67,10 @@ export declare const LITELLM_CATALOG_URL = "https://raw.githubusercontent.com/Be
  *   2. Otherwise attempt a network fetch; on success, persist + apply.
  *   3. On any failure, load a stale cache if present; else leave overrides empty.
  *
+ * `getPricingCatalogInfo().source` afterwards reads `litellm` for a fresh fetch
+ * or a cache within `ttlMs`, and `stale-cache` for a cache older than `ttlMs`
+ * — whether the refresh failed or `offline` skipped it.
+ *
  * Always resolves — never throws. Offline-safe.
  */
 export declare function hydratePricingCatalog(options?: HydrateOptions): Promise<HydrateResult>;

package/dist/pricingCatalog.js

@@ -75,6 +75,10 @@ const DEFAULT_TIMEOUT_MS = 3_000;
  *   2. Otherwise attempt a network fetch; on success, persist + apply.
  *   3. On any failure, load a stale cache if present; else leave overrides empty.
  *
+ * `getPricingCatalogInfo().source` afterwards reads `litellm` for a fresh fetch
+ * or a cache within `ttlMs`, and `stale-cache` for a cache older than `ttlMs`
+ * — whether the refresh failed or `offline` skipped it.
+ *
  * Always resolves — never throws. Offline-safe.
  */
 async function hydratePricingCatalog(options = {}) {
@@ -83,8 +87,9 @@ async function hydratePricingCatalog(options = {}) {
     const now = Date.now();
     // 1. Fresh cache? (Offline callers take any cache, however old.)
     const cached = await readCache(cachePath);
-    if (cached && (offline || now - Date.parse(cached.fetchedAt) < ttlMs)) {
-        return applyCacheFile(cached, 'cache');
+    const cacheFresh = cached !== null && now - Date.parse(cached.fetchedAt) < ttlMs;
+    if (cached && (offline || cacheFresh)) {
+        return applyCacheFile(cached, 'cache', cacheFresh ? 'litellm' : 'stale-cache');
     }
     // 2. Try network.
     if (fetchImpl && !offline) {
@@ -97,12 +102,12 @@ async function hydratePricingCatalog(options = {}) {
                 contextWindows: normalizeLiteLlmContextWindows(fetched),
             };
             await writeCache(cachePath, payload, logger);
-            return applyCacheFile(payload, 'network');
+            return applyCacheFile(payload, 'network', 'litellm');
         }
     }
     // 3. Fall back to stale cache if present.
     if (cached) {
-        return applyCacheFile(cached, 'cache');
+        return applyCacheFile(cached, 'cache', 'stale-cache');
     }
     // 4. Nothing we can do — stay on static tables.
     return {
@@ -110,6 +115,7 @@ async function hydratePricingCatalog(options = {}) {
         entries: 0,
         contextWindowEntries: 0,
         fetchedAt: new Date(now).toISOString(),
+        digest: (0, modelInfo_1.getPricingCatalogInfo)().digest,
     };
 }
 /**
@@ -117,9 +123,9 @@ async function hydratePricingCatalog(options = {}) {
  * `contextWindows` is absent on caches written before context hydration; those
  * contribute no overrides rather than clearing whatever is already loaded.
  */
-function applyCacheFile(cache, source) {
+function applyCacheFile(cache, source, basis) {
     const contextWindows = cache.contextWindows ?? {};
-    (0, modelInfo_1._setPricingOverrides)(cache.overrides);
+    (0, modelInfo_1._setPricingOverrides)(cache.overrides, { source: basis, fetchedAt: cache.fetchedAt });
     if (Object.keys(contextWindows).length > 0) {
         (0, modelContext_1._setCatalogContextWindows)(contextWindows);
     }
@@ -128,6 +134,7 @@ function applyCacheFile(cache, source) {
         entries: Object.keys(cache.overrides).length,
         contextWindowEntries: Object.keys(contextWindows).length,
         fetchedAt: cache.fetchedAt,
+        digest: (0, modelInfo_1.getPricingCatalogInfo)().digest,
     };
 }
 /**

package/dist/promptHistory.d.ts

@@ -14,6 +14,10 @@
  * record over `maxRecordBytes` is skipped without being buffered and reported
  * in `exclusions`, the only way a record is permanently left out.
  *
+ * `includeText: false` returns the same entries, ordinals, timestamps,
+ * metadata, exclusions, and cursor without prompt text, for consumers that
+ * only count or attribute prompts. Cursors are interchangeable between modes.
+ *
  * A prompt can be written before its answer. The cursor then keeps the byte
  * offset of that prompt's line and its answer-tracking state (never text), and
  * the prompt is returned again under the same identity once its first
@@ -34,8 +38,14 @@ export interface PromptHistoryBounds {
     /** Bytes read across all files in this call. Default 256 MiB. */
     maxTotalBytes?: number;
     /**
-     * Largest single log record that is parsed. Default 16 MiB. A longer record
-     * is skipped without being buffered and reported in `exclusions`.
+     * Largest single log record that is parsed. Default 16 MiB
+     * (`PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES`). A longer record is skipped
+     * without being buffered and reported in `exclusions`.
+     *
+     * Ordinals depend on this bound: a prompt inside a skipped record is never
+     * seen, so later prompts in that file do not count it. Ordinals are only
+     * stable across runs and across consumers (for example usage events'
+     * `promptOrdinal`) when every reader uses the default.
      */
     maxRecordBytes?: number;
     /** Entries returned by one call. Default 10 000. */
@@ -139,8 +149,10 @@ export interface PromptHistoryEntry {
     ordinal: number;
     /** ISO timestamp from the log line; never synthesized. */
     timestamp: string;
-    /** Full prompt text, untruncated. */
+    /** Full prompt text, untruncated; `''` when the call passed `includeText: false`. */
     text: string;
+    /** Set when `text` was left out by `includeText: false`; the prompt was not empty. */
+    textOmitted?: true;
     /** Realpath of the working directory; always inside an allowed root. */
     cwd: string;
     gitBranch?: string;
@@ -170,7 +182,9 @@ export interface PromptHistorySessionRef {
 /**
  * A log record permanently left out. Records over `maxRecordBytes` and lines
  * that are not valid JSON are never parsed, so any prompt inside is lost, and
- * the ordinals of later prompts in that file do not count it.
+ * the ordinals of later prompts in that file do not count it. Because of
+ * that, ordinals are only stable across runs and consumers that all use the
+ * default `maxRecordBytes` (`PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES`).
  */
 export interface PromptHistoryExclusion {
     provider: PromptHistoryProvider;
@@ -213,6 +227,14 @@ export interface CollectPromptHistoryOptions {
     cursor?: PromptHistoryCursor;
     bounds?: PromptHistoryBounds;
     signal?: AbortSignal;
+    /**
+     * Return prompt text. Default true. With `false`, entries keep their
+     * ordinal, timestamp, cwd, branch, and answer metadata but carry `text: ''`
+     * and `textOmitted: true`, and no prompt text is kept past classifying its
+     * line. Ordinals, timestamps, exclusions, and the cursor are identical in
+     * both modes, so a cursor written in one mode resumes in the other.
+     */
+    includeText?: boolean;
 }
 export interface PromptHistoryResult {
     /** Ordered by provider, session, then ordinal. */
@@ -235,6 +257,13 @@ export interface PromptHistoryResult {
     /** Realpaths of the roots scanned, after worktree expansion. */
     roots?: string[];
 }
+/**
+ * The default `maxRecordBytes` (16 MiB). Prompt ordinals are only comparable
+ * between readers that skip the same records, so every reader that publishes
+ * or joins on ordinals (prompt history, session prompt history, usage events'
+ * `promptOrdinal`) uses this bound.
+ */
+export declare const PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES: number;
 /** @internal */
 export declare const DEFAULT_BOUNDS: Required<PromptHistoryBounds>;
 /** Test hooks; not part of the public entry points. */
@@ -257,6 +286,17 @@ export type RecordObserver = (record: Record<string, unknown>, info: {
     ordinal: number;
     lineOffset: number;
 }) => void;
+/**
+ * Sees every human prompt as it is given its ordinal, before the timestamp and
+ * scope checks, so prompts that are not returned are seen too. `timestamp` is
+ * undefined when the line has no usable one.
+ * @internal
+ */
+export type PromptObserver = (prompt: {
+    ordinal: number;
+    timestamp: string | undefined;
+    lineOffset: number;
+}) => void;
 /** @internal */
 export interface ScanContext {
     roots: string[];
@@ -269,6 +309,9 @@ export interface ScanContext {
     entriesSoFar: () => number;
     exclude: (exclusion: PromptHistoryExclusion) => void;
     observe?: RecordObserver;
+    onPrompt?: PromptObserver;
+    /** Keep prompt text on entries. Default true. */
+    includeText?: boolean;
 }
 /** @internal */
 export interface FileBudget {
@@ -293,6 +336,24 @@ export interface FileOutcome {
 }
 /** Collect human-typed prompts from Claude Code and Codex logs under the given roots. */
 export declare function collectPromptHistory(options: CollectPromptHistoryOptions): Promise<PromptHistoryResult>;
+/** One human prompt of a session file: its ordinal and parsed timestamp. @internal */
+export interface PromptOrdinalMark {
+    ordinal: number;
+    /** Prompt line timestamp, ms since epoch. */
+    timestampMs: number;
+}
+/**
+ * Every human prompt of one session file with its ordinal and timestamp, read
+ * whole in one pass with the default record bound, so the ordinals are the
+ * ones `collectPromptHistory()` returns with default bounds. No scope check
+ * and no text: prompts are counted wherever their cwd points. Prompts whose
+ * line has no usable timestamp still take an ordinal but are left out. A
+ * non-interactive Codex session (subagent, fork, unknown source) has none.
+ * In file order. Rejects when the file cannot be opened or changes while its
+ * head is read.
+ * @internal
+ */
+export declare function readPromptOrdinalMarks(provider: PromptHistoryProvider, sessionId: string, filePath: string): Promise<PromptOrdinalMark[]>;
 /** @internal */
 export declare function emptyStats(): PromptHistoryStats;
 /**