sidekick-shared 0.23.1 → 0.24.1

package/dist/transcript.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectSessionTranscript = projectSessionTranscript;
+const usageNormalization_1 = require("./usageNormalization");
+const EMPTY_TOTALS = {
+    uncachedInputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    cacheInclusiveInputTokens: 0,
+    billableOutputTokens: 0,
+    totalTokens: 0,
+};
+/** Project canonical provider events into a bounded or full-fidelity transcript. */
+function projectSessionTranscript(events, options = {}) {
+    const fidelity = options.fidelity ?? 'snippet';
+    const requestedMax = options.maxContentChars ?? 2_000;
+    const maxContentChars = Number.isFinite(requestedMax) ? Math.max(0, requestedMax) : 2_000;
+    const messages = [];
+    const tools = [];
+    const commands = [];
+    const models = new Set();
+    const usageEvents = [];
+    const usageCosts = [];
+    const totals = { ...EMPTY_TOTALS };
+    const toolsById = new Map();
+    let cwd;
+    let gitBranch;
+    events.forEach((event, eventIndex) => {
+        if (nonEmpty(event.cwd))
+            cwd = event.cwd;
+        if (nonEmpty(event.gitBranch))
+            gitBranch = event.gitBranch;
+        const message = event.message;
+        const source = {
+            provider: options.provider ?? event.providerMetadata?.providerId,
+            sessionId: options.sessionId,
+            sourcePath: options.sourcePath,
+            source: event.providerMetadata?.source,
+            entrypoint: event.entrypoint,
+            isMeta: event.isMeta,
+            isSidechain: event.isSidechain,
+            originalRole: message?.role,
+            eventIndex,
+            eventType: event.type,
+            eventId: message?.id,
+        };
+        const usage = (0, usageNormalization_1.extractNormalizedUsage)(event) ?? undefined;
+        if (usage) {
+            usageEvents.push(usage);
+            addUsage(totals, usage);
+        }
+        const cost = usage
+            ? (0, usageNormalization_1.calculateNormalizedUsageCost)({ usage, modelId: message?.model })
+            : undefined;
+        if (cost)
+            usageCosts.push(cost);
+        if (message?.model)
+            models.add(message.model);
+        const blocks = contentBlocks(message?.content, fidelity, maxContentChars, options.includeUnknownBlocks);
+        if (event.type === 'summary' && event.summary && blocks.length === 0) {
+            blocks.push({ type: 'text', ...boundedText(event.summary, fidelity, maxContentChars) });
+        }
+        if (event.type === 'tool_use') {
+            blocks.push({
+                type: 'tool_use',
+                toolName: event.tool.name,
+                input: boundedValue(event.tool.input, fidelity, maxContentChars),
+            });
+        }
+        if (event.type === 'tool_result') {
+            blocks.push({
+                type: 'tool_result',
+                toolUseId: event.result.tool_use_id,
+                output: boundedValue(event.result.output, fidelity, maxContentChars),
+                isError: event.result.is_error,
+            });
+        }
+        const messageTools = [];
+        for (const block of blocks) {
+            if (block.type === 'tool_use' && block.toolName) {
+                const command = block.command ?? commandFromTool(block.toolName, block.input);
+                const call = {
+                    id: block.toolUseId,
+                    name: block.toolName,
+                    timestamp: event.timestamp,
+                    input: block.input,
+                    command,
+                    source,
+                };
+                tools.push(call);
+                messageTools.push(call);
+                if (call.id)
+                    toolsById.set(call.id, call);
+                if (command)
+                    commands.push(command);
+            }
+            else if (block.type === 'tool_result' && block.toolUseId) {
+                const call = toolsById.get(block.toolUseId);
+                if (call) {
+                    call.output = block.output;
+                    call.isError = block.isError;
+                }
+            }
+        }
+        if (blocks.length === 0 && !usage && event.type !== 'summary')
+            return;
+        messages.push({
+            id: message?.id,
+            role: roleForEvent(event),
+            timestamp: event.timestamp,
+            model: message?.model,
+            sourceLabel: message?.sourceLabel,
+            content: blocks,
+            text: blocks
+                .filter((block) => block.type === 'text' || block.type === 'thinking')
+                .map((block) => block.text ?? '')
+                .filter(Boolean)
+                .join('\n'),
+            usage,
+            cost,
+            tools: messageTools,
+            commands: messageTools.flatMap((tool) => (tool.command ? [tool.command] : [])),
+            source,
+        });
+    });
+    return {
+        provider: options.provider,
+        sessionId: options.sessionId,
+        sourcePath: options.sourcePath,
+        cwd,
+        gitBranch,
+        startedAt: events[0]?.timestamp,
+        endedAt: events.at(-1)?.timestamp,
+        models: [...models],
+        messages,
+        tools,
+        commands: [...new Set(commands)],
+        usage: {
+            events: usageEvents,
+            costs: usageCosts,
+            totals,
+            totalCostUsd: usageCosts.length > 0 && usageCosts.every((cost) => cost.costUsd !== null)
+                ? usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0)
+                : null,
+        },
+        provenance: { source: 'session-events', fidelity, eventCount: events.length },
+    };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function roleForEvent(event) {
+    if (event.type === 'summary')
+        return 'summary';
+    if (event.type === 'system')
+        return 'system';
+    if (event.type === 'tool_use' || event.type === 'tool_result')
+        return 'tool';
+    return event.type;
+}
+function contentBlocks(content, fidelity, maxChars, includeUnknown = false) {
+    if (typeof content === 'string')
+        return [{ type: 'text', ...boundedText(content, fidelity, maxChars) }];
+    if (!Array.isArray(content))
+        return [];
+    const result = [];
+    for (const raw of content) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const block = raw;
+        if (block.type === 'text' && typeof block.text === 'string') {
+            result.push({ type: 'text', ...boundedText(block.text, fidelity, maxChars) });
+        }
+        else if ((block.type === 'thinking' || block.type === 'reasoning') &&
+            (typeof block.thinking === 'string' || typeof block.text === 'string')) {
+            result.push({
+                type: 'thinking',
+                ...boundedText(String(block.thinking ?? block.text), fidelity, maxChars),
+            });
+        }
+        else if (block.type === 'tool_use' && typeof block.name === 'string') {
+            result.push({
+                type: 'tool_use',
+                toolName: block.name,
+                toolUseId: typeof block.id === 'string' ? block.id : undefined,
+                input: boundedValue(block.input, fidelity, maxChars),
+                command: commandFromTool(block.name, block.input),
+            });
+        }
+        else if (block.type === 'tool_result') {
+            result.push({
+                type: 'tool_result',
+                toolUseId: typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined,
+                output: boundedValue(block.content, fidelity, maxChars),
+                isError: block.is_error === true,
+            });
+        }
+        else if (block.type === 'image') {
+            result.push({
+                type: 'image',
+                text: '[Image content]',
+                ...(fidelity === 'full' ? { raw } : {}),
+            });
+        }
+        else if (includeUnknown) {
+            result.push({ type: 'unknown', raw: boundedValue(raw, fidelity, maxChars) });
+        }
+    }
+    return result;
+}
+function boundedText(text, fidelity, maxChars) {
+    if (fidelity === 'full' || text.length <= maxChars)
+        return { text, truncated: false };
+    return { text: text.slice(0, maxChars), truncated: true };
+}
+function boundedValue(value, fidelity, maxChars) {
+    if (fidelity === 'full' || value === undefined)
+        return value;
+    if (typeof value === 'string')
+        return boundedText(value, fidelity, maxChars).text;
+    try {
+        const json = JSON.stringify(value);
+        return json.length <= maxChars ? value : json.slice(0, maxChars);
+    }
+    catch {
+        return String(value).slice(0, maxChars);
+    }
+}
+function commandFromTool(name, input) {
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const value = input;
+    if (!['bash', 'shell', 'execcommand', 'exec_command', 'local_shell'].includes(name.toLowerCase())) {
+        return undefined;
+    }
+    if (typeof value.command === 'string')
+        return value.command;
+    if (Array.isArray(value.command))
+        return value.command.map(String).join(' ');
+    if (typeof value.cmd === 'string')
+        return value.cmd;
+    return undefined;
+}
+function addUsage(total, usage) {
+    total.uncachedInputTokens += usage.uncachedInputTokens;
+    total.cacheReadTokens += usage.cacheReadTokens;
+    total.cacheWriteTokens += usage.cacheWriteTokens;
+    total.outputTokens += usage.outputTokens;
+    total.reasoningTokens += usage.reasoningTokens;
+    total.cacheInclusiveInputTokens += usage.cacheInclusiveInputTokens;
+    total.billableOutputTokens += usage.billableOutputTokens;
+    total.totalTokens += usage.totalTokens;
+}

package/dist/types/observedSessionV1.d.ts

@@ -1,5 +1,6 @@
 import type { SessionEvent } from './sessionEvent';
 import type { ProviderId, SessionProviderBase } from '../providers/types';
+import type { CanonicalTranscriptUsageTotals } from '../transcript';
 export type ObservationProvenanceV1 = 'reported' | 'estimated' | 'inferred';
 export interface SessionEvidenceRefV1 {
     schemaVersion: 1;
@@ -40,7 +41,8 @@ export interface ObservedAgentSessionV1 {
         outputTokens: ObservedValueV1<number>;
         cacheReadTokens: ObservedValueV1<number>;
         cacheWriteTokens: ObservedValueV1<number>;
-        costUsd: ObservedValueV1<number>;
+        normalized?: ObservedValueV1<CanonicalTranscriptUsageTotals>;
+        costUsd: ObservedValueV1<number | null>;
     };
     pendingUserRequest: PendingUserRequestV1 | null;
     observedAt: string;

package/dist/types/observedSessionV1.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.derivePendingUserRequestV1 = derivePendingUserRequestV1;
 exports.createProviderSessionAdapterV1 = createProviderSessionAdapterV1;
+const transcript_1 = require("../transcript");
 function evidence(provider, sessionId, sourcePath, event, eventIndex) {
     return [
         {
@@ -121,11 +122,18 @@ function createProviderSessionAdapterV1(sessionProvider, options = {}) {
         async read(sessionPath, cwd = '') {
             const stats = sessionProvider.readSessionStats(sessionPath);
             const events = sessionProvider.createReader(sessionPath).readAll();
+            const transcript = (0, transcript_1.projectSessionTranscript)(events, {
+                provider: sessionProvider.id,
+                sessionId: stats.sessionId,
+                sourcePath: sessionPath,
+            });
             const refs = evidence(sessionProvider.id, stats.sessionId, sessionPath);
             const model = Object.entries(stats.modelUsage).sort((left, right) => right[1].calls - left[1].calls)[0]?.[0] ?? null;
             const metadata = sessionProvider.getSessionMetadata?.(sessionPath);
             const modifiedAt = metadata?.mtime.getTime() ?? Date.parse(stats.endTime);
             const recent = Number.isFinite(modifiedAt) && Date.now() - modifiedAt < 2 * 60_000;
+            const allCostsReported = transcript.usage.costs.length > 0 &&
+                transcript.usage.costs.every((cost) => cost.source === 'provider-reported');
             return {
                 schemaVersion: 1,
                 identity: {
@@ -141,7 +149,12 @@ function createProviderSessionAdapterV1(sessionProvider, options = {}) {
                     outputTokens: observed(stats.tokens.output, 'reported', 1, refs),
                     cacheReadTokens: observed(stats.tokens.cacheRead, 'reported', 1, refs),
                     cacheWriteTokens: observed(stats.tokens.cacheWrite, 'reported', 1, refs),
-                    costUsd: observed(stats.reportedCost, stats.reportedCost > 0 ? 'reported' : 'estimated', stats.reportedCost > 0 ? 1 : 0.5, refs),
+                    normalized: observed(transcript.usage.totals, 'reported', 1, refs),
+                    costUsd: observed(transcript.usage.totalCostUsd, allCostsReported
+                        ? 'reported'
+                        : transcript.usage.totalCostUsd === null
+                            ? 'inferred'
+                            : 'estimated', allCostsReported ? 1 : transcript.usage.totalCostUsd === null ? 0.5 : 0.9, refs),
                 },
                 pendingUserRequest: derivePendingUserRequestV1(sessionProvider.id, stats.sessionId, sessionPath, events),
                 observedAt: new Date().toISOString(),

package/dist/types/sessionEvent.d.ts

@@ -43,6 +43,8 @@ export interface SessionMessage {
     model?: string;
     /** Token usage statistics (only present in assistant messages) */
     usage?: MessageUsage;
+    /** Authoritative disjoint usage projection, when normalized by a provider parser. */
+    normalizedUsage?: import('../usageNormalization').NormalizedUsage;
     /** Message content (may be string or structured content) */
     content?: unknown;
 }
@@ -52,15 +54,19 @@ export interface SessionMessage {
  * Events are normalized from provider-specific formats into this common shape.
  * Each event represents a single interaction in a CLI agent session.
  */
-export interface SessionEvent {
-    /** Event type discriminator */
-    type: 'user' | 'assistant' | 'tool_use' | 'tool_result' | 'summary' | 'system';
-    /** Message data containing role, model, usage */
-    message: SessionMessage;
+export interface SessionEventBase {
     /** ISO 8601 timestamp of event */
     timestamp: string;
+    /** Provider-reported entrypoint that produced this event. */
+    entrypoint?: string;
+    /** Whether the provider identifies this as orchestration or metadata. */
+    isMeta?: boolean;
     /** Whether this is a subagent/sidechain event */
     isSidechain?: boolean;
+    /** Provider-reported working directory for this event/session. */
+    cwd?: string;
+    /** Provider-reported git branch for this event/session. */
+    gitBranch?: string;
     /** Permission mode active when this event occurred */
     permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
     /** Subscription rate limits, when provided by the session source. */
@@ -83,6 +89,8 @@ export interface SessionEvent {
     };
     /** Provider-specific signals normalized for shared analytics. */
     providerMetadata?: {
+        providerId?: string;
+        source?: string;
         retryAttempts?: number[];
         finishReasons?: string[];
         providerError?: {
@@ -91,18 +99,76 @@ export interface SessionEvent {
             code?: string | number;
         };
     };
-    /** Tool use details (when type is 'tool_use') */
+    /** Optional on the base so consumers can inspect legacy enriched events. */
     tool?: {
         name: string;
         input: Record<string, unknown>;
     };
-    /** Tool result details (when type is 'tool_result') */
+    /** Optional on the base so consumers can inspect legacy enriched events. */
     result?: {
         tool_use_id: string;
         output?: unknown;
         is_error?: boolean;
     };
 }
+export interface UserSessionEvent extends SessionEventBase {
+    type: 'user';
+    message: SessionMessage;
+}
+export interface AssistantSessionEvent extends SessionEventBase {
+    type: 'assistant';
+    message: SessionMessage;
+}
+export type MessageSessionEvent = UserSessionEvent | AssistantSessionEvent;
+/** Providers must emit textual summary data, exact compaction counts, or both. */
+export type SummarySessionEvent = SessionEventBase & {
+    type: 'summary';
+} & ({
+    message: SessionMessage;
+    summary?: string;
+    compaction?: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
+} | {
+    message?: SessionMessage;
+    summary: string;
+    compaction?: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
+} | {
+    message?: SessionMessage;
+    summary?: string;
+    compaction: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
+});
+export interface SystemSessionEvent extends SessionEventBase {
+    type: 'system';
+    /** Bookkeeping-only system rows legitimately have no message. */
+    message?: SessionMessage;
+}
+export interface ToolUseSessionEvent extends SessionEventBase {
+    type: 'tool_use';
+    message?: SessionMessage;
+    tool: {
+        name: string;
+        input: Record<string, unknown>;
+    };
+}
+export interface ToolResultSessionEvent extends SessionEventBase {
+    type: 'tool_result';
+    message?: SessionMessage;
+    result: {
+        tool_use_id: string;
+        output?: unknown;
+        is_error?: boolean;
+    };
+}
+/** Canonical provider-neutral event contract. */
+export type SessionEvent = UserSessionEvent | AssistantSessionEvent | SummarySessionEvent | SystemSessionEvent | ToolUseSessionEvent | ToolResultSessionEvent;
 /**
  * Permission mode values from Claude Code JSONL.
  */

package/dist/usageNormalization.d.ts

@@ -0,0 +1,69 @@
+import { type ModelPricing } from './modelInfo';
+import type { SessionEvent } from './types/sessionEvent';
+export type UsageProvider = 'anthropic' | 'openai' | 'sidekick' | (string & {});
+export type UsageSemantics = 'anthropic-additive-cache' | 'openai-inclusive-cache' | 'sidekick-disjoint';
+export interface UsageNormalizationProvenance {
+    provider?: UsageProvider;
+    semantics: UsageSemantics;
+    source?: string;
+}
+interface ProviderUsageBase {
+    provider?: UsageProvider;
+    source?: string;
+    model?: string;
+    reportedCostUsd?: number | null;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/** Anthropic input and cache categories are additive. */
+export interface AnthropicUsageInput extends ProviderUsageBase {
+    semantics: 'anthropic';
+    reasoningIncludedInOutput?: boolean;
+}
+/** OpenAI cached input is a subset of input and reasoning is normally a subset of output. */
+export interface OpenAIUsageInput extends ProviderUsageBase {
+    semantics: 'openai';
+    reasoningIncludedInOutput?: boolean;
+}
+/** Already-disjoint usage. Reasoning inclusion must be stated explicitly. */
+export interface SidekickUsageInput extends ProviderUsageBase {
+    semantics: 'sidekick';
+    reasoningIncludedInOutput: boolean;
+}
+export type ProviderUsageInput = AnthropicUsageInput | OpenAIUsageInput | SidekickUsageInput;
+export interface NormalizedUsage {
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    reasoningIncludedInOutput: boolean;
+    cacheInclusiveInputTokens: number;
+    billableOutputTokens: number;
+    totalTokens: number;
+    model?: string;
+    reportedCostUsd?: number;
+    provenance: UsageNormalizationProvenance;
+}
+export type PricingProvenance = 'provider-reported' | 'explicit-pricing' | 'model-catalog' | 'unpriced';
+export interface NormalizedUsageCostInput {
+    usage: NormalizedUsage;
+    modelId?: string;
+    pricing?: ModelPricing | null;
+}
+export interface NormalizedUsageCost {
+    costUsd: number | null;
+    source: PricingProvenance;
+    modelId?: string;
+    usage: NormalizedUsage;
+}
+/** Convert provider-specific counters into finite, nonnegative, disjoint categories. */
+export declare function normalizeProviderUsage(input: ProviderUsageInput): NormalizedUsage;
+/** Extract normalized usage from an event, preserving parser-owned semantics when present. */
+export declare function extractNormalizedUsage(event: SessionEvent): NormalizedUsage | null;
+/** Price normalized, disjoint usage without double-counting reasoning tokens. */
+export declare function calculateNormalizedUsageCost(input: NormalizedUsageCostInput): NormalizedUsageCost;
+export {};

package/dist/usageNormalization.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeProviderUsage = normalizeProviderUsage;
+exports.extractNormalizedUsage = extractNormalizedUsage;
+exports.calculateNormalizedUsageCost = calculateNormalizedUsageCost;
+const modelInfo_1 = require("./modelInfo");
+function tokenCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(value))
+        : 0;
+}
+function reportedCost(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** Convert provider-specific counters into finite, nonnegative, disjoint categories. */
+function normalizeProviderUsage(input) {
+    const rawInput = tokenCount(input.inputTokens);
+    const cacheReadTokens = tokenCount(input.cacheReadTokens);
+    const cacheWriteTokens = tokenCount(input.cacheWriteTokens);
+    const outputTokens = tokenCount(input.outputTokens);
+    const reasoningTokens = tokenCount(input.reasoningTokens);
+    const isOpenAI = input.semantics === 'openai';
+    const uncachedInputTokens = isOpenAI ? Math.max(0, rawInput - cacheReadTokens) : rawInput;
+    const reasoningIncludedInOutput = input.reasoningIncludedInOutput ?? input.semantics === 'openai';
+    const cacheInclusiveInputTokens = uncachedInputTokens + cacheReadTokens + cacheWriteTokens;
+    const billableOutputTokens = outputTokens + (reasoningIncludedInOutput ? 0 : reasoningTokens);
+    const totalTokens = cacheInclusiveInputTokens + billableOutputTokens;
+    const semantics = isOpenAI
+        ? 'openai-inclusive-cache'
+        : input.semantics === 'anthropic'
+            ? 'anthropic-additive-cache'
+            : 'sidekick-disjoint';
+    return {
+        uncachedInputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        outputTokens,
+        reasoningTokens,
+        reasoningIncludedInOutput,
+        cacheInclusiveInputTokens,
+        billableOutputTokens,
+        totalTokens,
+        ...(input.model ? { model: input.model } : {}),
+        ...(reportedCost(input.reportedCostUsd) !== undefined
+            ? { reportedCostUsd: reportedCost(input.reportedCostUsd) }
+            : {}),
+        provenance: {
+            semantics,
+            ...(input.provider ? { provider: input.provider } : {}),
+            ...(input.source ? { source: input.source } : {}),
+        },
+    };
+}
+/** Extract normalized usage from an event, preserving parser-owned semantics when present. */
+function extractNormalizedUsage(event) {
+    if (event.message?.normalizedUsage)
+        return event.message.normalizedUsage;
+    const usage = event.message?.usage;
+    if (!usage)
+        return null;
+    const providerId = event.providerMetadata?.providerId;
+    return normalizeProviderUsage({
+        semantics: 'sidekick',
+        provider: providerId,
+        source: event.providerMetadata?.source ?? 'legacy-message-usage',
+        model: event.message?.model,
+        inputTokens: usage.input_tokens,
+        outputTokens: usage.output_tokens,
+        cacheReadTokens: usage.cache_read_input_tokens,
+        cacheWriteTokens: usage.cache_creation_input_tokens,
+        reasoningTokens: usage.reasoning_tokens,
+        reasoningIncludedInOutput: providerId === 'codex' || providerId === 'openai',
+        reportedCostUsd: usage.reported_cost,
+    });
+}
+/** Price normalized, disjoint usage without double-counting reasoning tokens. */
+function calculateNormalizedUsageCost(input) {
+    const { usage } = input;
+    const modelId = input.modelId ?? usage.model;
+    if (usage.reportedCostUsd !== undefined) {
+        return { costUsd: usage.reportedCostUsd, source: 'provider-reported', modelId, usage };
+    }
+    const explicit = input.pricing !== undefined;
+    const pricing = explicit ? input.pricing : modelId ? (0, modelInfo_1.getModelPricing)(modelId) : null;
+    if (!pricing)
+        return { costUsd: null, source: 'unpriced', modelId, usage };
+    const costUsd = (usage.uncachedInputTokens / 1_000_000) * pricing.inputCostPerMillion +
+        (usage.cacheReadTokens / 1_000_000) * pricing.cacheReadCostPerMillion +
+        (usage.cacheWriteTokens / 1_000_000) * pricing.cacheWriteCostPerMillion +
+        (usage.billableOutputTokens / 1_000_000) * pricing.outputCostPerMillion;
+    if (!Number.isFinite(costUsd) || costUsd < 0) {
+        return { costUsd: null, source: 'unpriced', modelId, usage };
+    }
+    return {
+        costUsd,
+        source: explicit ? 'explicit-pricing' : 'model-catalog',
+        modelId,
+        usage,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",