sidekick-shared 0.23.1 → 0.24.0

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,11 +54,7 @@ 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;
     /** Whether this is a subagent/sidechain event */
@@ -83,6 +81,8 @@ export interface SessionEvent {
     };
     /** Provider-specific signals normalized for shared analytics. */
     providerMetadata?: {
+        providerId?: string;
+        source?: string;
         retryAttempts?: number[];
         finishReasons?: string[];
         providerError?: {
@@ -91,18 +91,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.0",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",