@omnicross/contracts 0.1.1 → 0.1.2

package/dist/account-tokens-types.d.cts

@@ -25,6 +25,18 @@ type SubscriptionLevel = 'Free' | 'Pro' | 'Max';
  * Token configuration status
  */
 type TokenStatus = 'unconfigured' | 'authorized' | 'configured' | 'expired' | 'error';
+/**
+ * Machine-readable credential-sync warning code (external-cli-sync).
+ *
+ * - `external-divergent`: the external CLI's native credential file (e.g.
+ *   `~/.claude/.credentials.json`) holds a DIFFERENT, fresher credential than
+ *   the stored account — the stored refresh token may have been rotated out.
+ * - `external-not-rotated`: a refresh failed and the external file holds the
+ *   SAME dead credential — a genuine revocation, re-login is required.
+ * - `duplicate-token`: two accounts of one provider share the same credential —
+ *   refreshing one will invalidate the other (single-use refresh tokens).
+ */
+type SyncWarningCode = 'external-divergent' | 'external-not-rotated' | 'duplicate-token';
 /**
  * Claude token configuration
  */
@@ -40,6 +52,9 @@ type ClaudeTokenConfig = {
     setupTokenExpiresAt?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Codex (OpenAI) token configuration
@@ -56,6 +71,9 @@ type CodexTokenConfig = {
     organizationId?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Gemini token configuration
@@ -125,6 +143,12 @@ type SubscriptionAccountSanitized = {
     isSetupToken?: boolean;
     hasAccessToken: boolean;
     isActive: boolean;
+    /**
+     * Credential-sync warning for this account (external-cli-sync). Carries the
+     * persisted code when one was recorded by a failed refresh, plus the
+     * list-time computed codes (`external-divergent` / `duplicate-token`).
+     */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * OAuth authorization parameters
@@ -143,4 +167,4 @@ type TokenExchangeRequest = {
     state: string;
 };
 
-export type { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, TokenExchangeRequest, TokenStatus };
+export type { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus };

package/dist/account-tokens-types.d.ts

@@ -25,6 +25,18 @@ type SubscriptionLevel = 'Free' | 'Pro' | 'Max';
  * Token configuration status
  */
 type TokenStatus = 'unconfigured' | 'authorized' | 'configured' | 'expired' | 'error';
+/**
+ * Machine-readable credential-sync warning code (external-cli-sync).
+ *
+ * - `external-divergent`: the external CLI's native credential file (e.g.
+ *   `~/.claude/.credentials.json`) holds a DIFFERENT, fresher credential than
+ *   the stored account — the stored refresh token may have been rotated out.
+ * - `external-not-rotated`: a refresh failed and the external file holds the
+ *   SAME dead credential — a genuine revocation, re-login is required.
+ * - `duplicate-token`: two accounts of one provider share the same credential —
+ *   refreshing one will invalidate the other (single-use refresh tokens).
+ */
+type SyncWarningCode = 'external-divergent' | 'external-not-rotated' | 'duplicate-token';
 /**
  * Claude token configuration
  */
@@ -40,6 +52,9 @@ type ClaudeTokenConfig = {
     setupTokenExpiresAt?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Codex (OpenAI) token configuration
@@ -56,6 +71,9 @@ type CodexTokenConfig = {
     organizationId?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Gemini token configuration
@@ -125,6 +143,12 @@ type SubscriptionAccountSanitized = {
     isSetupToken?: boolean;
     hasAccessToken: boolean;
     isActive: boolean;
+    /**
+     * Credential-sync warning for this account (external-cli-sync). Carries the
+     * persisted code when one was recorded by a failed refresh, plus the
+     * list-time computed codes (`external-divergent` / `duplicate-token`).
+     */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * OAuth authorization parameters
@@ -143,4 +167,4 @@ type TokenExchangeRequest = {
     state: string;
 };
 
-export type { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, TokenExchangeRequest, TokenStatus };
+export type { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus };

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   CANNOT_DISABLE_THINKING_PATTERNS: () => CANNOT_DISABLE_THINKING_PATTERNS,
   CATALOG_VERSION: () => CATALOG_VERSION,
   CODING_PLAN_URL_PRESETS: () => CODING_PLAN_URL_PRESETS,
+  DEFAULT_LITELLM_PRICING_URL: () => DEFAULT_LITELLM_PRICING_URL,
   DEFAULT_MAX_TOKENS: () => DEFAULT_MAX_TOKENS,
   DEFAULT_MCP_SESSION_CONFIG: () => DEFAULT_MCP_SESSION_CONFIG,
   DEFAULT_SEED_PRESET_IDS: () => DEFAULT_SEED_PRESET_IDS,
@@ -333,6 +334,9 @@ var DEFAULT_MCP_SESSION_CONFIG = {
   selectedServers: []
 };
 
+// src/pricing-types.ts
+var DEFAULT_LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+
 // src/provider-presets/catalog.json
 var catalog_default = {
   version: 1,
@@ -2683,6 +2687,7 @@ function isLocalProvider(id) {
   CANNOT_DISABLE_THINKING_PATTERNS,
   CATALOG_VERSION,
   CODING_PLAN_URL_PRESETS,
+  DEFAULT_LITELLM_PRICING_URL,
   DEFAULT_MAX_TOKENS,
   DEFAULT_MCP_SESSION_CONFIG,
   DEFAULT_SEED_PRESET_IDS,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, TokenExchangeRequest, TokenStatus } from './account-tokens-types.cjs';
+export { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus } from './account-tokens-types.cjs';
 export { KNOWN_MODELS, KnownModelCapabilities, MODEL_ALIASES, ResolvedModelCapabilities, applyAlias, lookupCanonicalCapabilities, normalizeModelId, resolveModelCapabilities } from './canonical-models.cjs';
 export { AnthropicAudioContent, AnthropicChatRequest, AnthropicChatResponse, AnthropicContentPart, AnthropicImageContent, AnthropicMessage, AnthropicSystemContent, AnthropicTextContent, AnthropicThinkingContent, AnthropicTool, AnthropicToolResultContent, AnthropicToolUseContent, AnthropicVideoContent, ConversionConfig, OpenAIChatRequest, OpenAIChatResponse, OpenAIContentPart, OpenAIMessage, OpenAIStreamChunk, OpenAITool, OpenAIToolCall, SimpleChatAudio, SimpleChatImage, SimpleChatMessage, SimpleChatSession, SimpleChatVideo } from './completion-types.cjs';
 export { R as ReasoningConfig, T as ThinkLevel, a as ThinkingContent } from './thinking-CBWSLel8.cjs';
@@ -7,8 +7,10 @@ export { EXTENDED_CONTEXT_CAPABLE_MODELS, isExtendedContextCapable } from './ext
 export { A as API_MODE_IDS, a as AgentDefaultModels, b as ApiFormat, c as ApiKeyEntry, d as ApiMode, e as ApiModeId, C as ChatApiFormat, f as CodingPlanConfig, g as CompletionSettings, G as GlobalModelParameters, L as LLMProvider, M as ModelConfig, h as ModelGroup, i as ModelParameter, j as ModelRef, O as OpenRouterDataCollection, k as OpenRouterMaxPrice, l as OpenRouterProviderRouting, m as OpenRouterProviderSort, n as OpenRouterQuantization, P as PresetProviderTemplate, o as ProviderApiType, p as ProviderModelMapping, q as ProviderSearchConfig, r as ProviderTemplate, S as SearchCapability, T as TransformerConfig, s as TransformerEntry } from './llm-config-CQjOimv2.cjs';
 export { DEFAULT_MCP_SESSION_CONFIG, MCPCallToolResponse, MCPTool, MCPToolResponseContent, McpActionResult, McpDiscoverResult, McpMode, McpServerConfig, McpServerInput, McpServerJsonInput, McpServerList, McpServerRecord, McpServerRemoveInput, McpServerScope, McpServerTransport, McpSessionConfig, McpTestResult, McpToolInfo } from './mcp-types.cjs';
 export { MessageBlock, MessageBlockBase, MessageBlockType, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock } from './message-blocks.cjs';
+export { DEFAULT_LITELLM_PRICING_URL, PricingConflict, PricingConflictDecision, PricingEntry, PricingEntryInput, PricingFetchResult, PricingResolution, PricingSource } from './pricing-types.cjs';
 export { CATALOG_VERSION, CODING_PLAN_URL_PRESETS, DEFAULT_SEED_PRESET_IDS, LLM_PROVIDER_PRESETS, MAX_CONCURRENCY_DEFAULTS, PROVIDER_MODEL_MAPPINGS, PROVIDER_SEARCH_CONFIGS, getAllProviderPresets, getCodingPlanBaseUrl, getPresetById, getPresetRevision, getProviderSearchConfig, resolveFollowProviderModel } from './provider-presets/index.cjs';
 export { OpenCodeGoModelEntry, OpenCodeGoScenario, OpenCodeGoTokenConfig, OpenCodeGoTokenSanitized, ProviderChannel, SubscriptionListEntry, SubscriptionProviderId, SubscriptionStatusEntry, legacyCliBackendToSubscriptionProvider, subscriptionTargetForSession } from './subscription-types.cjs';
 export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel } from './thinking-config.cjs';
+export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTotals } from './usage-stats-types.cjs';
 export { UsageEngineOrigin, UsageTokens } from './usage-types.cjs';
 export { JinaReaderResponse, WebSearchOptions, WebSearchProviderConfig, WebSearchProviderId, WebSearchProviderType, WebSearchResponse, WebSearchResult, isApiProvider, isLocalProvider } from './websearch-types.cjs';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, TokenExchangeRequest, TokenStatus } from './account-tokens-types.js';
+export { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus } from './account-tokens-types.js';
 export { KNOWN_MODELS, KnownModelCapabilities, MODEL_ALIASES, ResolvedModelCapabilities, applyAlias, lookupCanonicalCapabilities, normalizeModelId, resolveModelCapabilities } from './canonical-models.js';
 export { AnthropicAudioContent, AnthropicChatRequest, AnthropicChatResponse, AnthropicContentPart, AnthropicImageContent, AnthropicMessage, AnthropicSystemContent, AnthropicTextContent, AnthropicThinkingContent, AnthropicTool, AnthropicToolResultContent, AnthropicToolUseContent, AnthropicVideoContent, ConversionConfig, OpenAIChatRequest, OpenAIChatResponse, OpenAIContentPart, OpenAIMessage, OpenAIStreamChunk, OpenAITool, OpenAIToolCall, SimpleChatAudio, SimpleChatImage, SimpleChatMessage, SimpleChatSession, SimpleChatVideo } from './completion-types.js';
 export { R as ReasoningConfig, T as ThinkLevel, a as ThinkingContent } from './thinking-CBWSLel8.js';
@@ -7,8 +7,10 @@ export { EXTENDED_CONTEXT_CAPABLE_MODELS, isExtendedContextCapable } from './ext
 export { A as API_MODE_IDS, a as AgentDefaultModels, b as ApiFormat, c as ApiKeyEntry, d as ApiMode, e as ApiModeId, C as ChatApiFormat, f as CodingPlanConfig, g as CompletionSettings, G as GlobalModelParameters, L as LLMProvider, M as ModelConfig, h as ModelGroup, i as ModelParameter, j as ModelRef, O as OpenRouterDataCollection, k as OpenRouterMaxPrice, l as OpenRouterProviderRouting, m as OpenRouterProviderSort, n as OpenRouterQuantization, P as PresetProviderTemplate, o as ProviderApiType, p as ProviderModelMapping, q as ProviderSearchConfig, r as ProviderTemplate, S as SearchCapability, T as TransformerConfig, s as TransformerEntry } from './llm-config-D1jKQLVp.js';
 export { DEFAULT_MCP_SESSION_CONFIG, MCPCallToolResponse, MCPTool, MCPToolResponseContent, McpActionResult, McpDiscoverResult, McpMode, McpServerConfig, McpServerInput, McpServerJsonInput, McpServerList, McpServerRecord, McpServerRemoveInput, McpServerScope, McpServerTransport, McpSessionConfig, McpTestResult, McpToolInfo } from './mcp-types.js';
 export { MessageBlock, MessageBlockBase, MessageBlockType, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock } from './message-blocks.js';
+export { DEFAULT_LITELLM_PRICING_URL, PricingConflict, PricingConflictDecision, PricingEntry, PricingEntryInput, PricingFetchResult, PricingResolution, PricingSource } from './pricing-types.js';
 export { CATALOG_VERSION, CODING_PLAN_URL_PRESETS, DEFAULT_SEED_PRESET_IDS, LLM_PROVIDER_PRESETS, MAX_CONCURRENCY_DEFAULTS, PROVIDER_MODEL_MAPPINGS, PROVIDER_SEARCH_CONFIGS, getAllProviderPresets, getCodingPlanBaseUrl, getPresetById, getPresetRevision, getProviderSearchConfig, resolveFollowProviderModel } from './provider-presets/index.js';
 export { OpenCodeGoModelEntry, OpenCodeGoScenario, OpenCodeGoTokenConfig, OpenCodeGoTokenSanitized, ProviderChannel, SubscriptionListEntry, SubscriptionProviderId, SubscriptionStatusEntry, legacyCliBackendToSubscriptionProvider, subscriptionTargetForSession } from './subscription-types.js';
 export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel } from './thinking-config.js';
+export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTotals } from './usage-stats-types.js';
 export { UsageEngineOrigin, UsageTokens } from './usage-types.js';
 export { JinaReaderResponse, WebSearchOptions, WebSearchProviderConfig, WebSearchProviderId, WebSearchProviderType, WebSearchResponse, WebSearchResult, isApiProvider, isLocalProvider } from './websearch-types.js';

package/dist/index.js

@@ -266,6 +266,9 @@ var DEFAULT_MCP_SESSION_CONFIG = {
   selectedServers: []
 };
 
+// src/pricing-types.ts
+var DEFAULT_LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+
 // src/provider-presets/catalog.json
 var catalog_default = {
   version: 1,
@@ -2615,6 +2618,7 @@ export {
   CANNOT_DISABLE_THINKING_PATTERNS,
   CATALOG_VERSION,
   CODING_PLAN_URL_PRESETS,
+  DEFAULT_LITELLM_PRICING_URL,
   DEFAULT_MAX_TOKENS,
   DEFAULT_MCP_SESSION_CONFIG,
   DEFAULT_SEED_PRESET_IDS,

package/dist/pricing-types.cjs

@@ -0,0 +1,30 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/pricing-types.ts
+var pricing_types_exports = {};
+__export(pricing_types_exports, {
+  DEFAULT_LITELLM_PRICING_URL: () => DEFAULT_LITELLM_PRICING_URL
+});
+module.exports = __toCommonJS(pricing_types_exports);
+var DEFAULT_LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_LITELLM_PRICING_URL
+});

package/dist/pricing-types.d.cts

@@ -0,0 +1,84 @@
+/**
+ * Model pricing types — provider-generic pricing-table contracts.
+ *
+ * Pricing rows are keyed by (providerId, modelId) and persisted by the
+ * embedding host's own store. The serving core's pricing engine uses them to
+ * derive `costUsd` for each captured usage event; hosts may also surface the
+ * rows in their own pricing-management UI.
+ *
+ * @module pricing-types
+ */
+/** Where this pricing entry came from. */
+type PricingSource = 
+/** Built-in fallback shipped by the host, seeded on first run. */
+'builtin'
+/** Auto-fetched from the LiteLLM JSON URL. */
+ | 'litellm'
+/** Hand-edited by the user; protected from auto-overwrite. */
+ | 'user';
+/**
+ * Per-model pricing row keyed by (providerId, modelId). Prices are in USD per
+ * 1,000,000 tokens. `cache_read` / `cache_write` are optional — providers
+ * without prompt caching leave them null.
+ */
+interface PricingEntry {
+    providerId: string;
+    modelId: string;
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    cacheReadPricePer1m: number | null;
+    cacheWritePricePer1m: number | null;
+    source: PricingSource;
+    /** True when the row has been hand-edited. Protects it from auto-overwrite during a source refresh. */
+    userEdited: boolean;
+    /** Unix-millis of the most recent user edit, or null if never. */
+    editedAt: number | null;
+    /** Unix-millis of the most recent write of any kind. */
+    updatedAt: number;
+}
+/** Upsert input shape (manual edits and parsed source entries). */
+type PricingEntryInput = {
+    providerId: string;
+    modelId: string;
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    cacheReadPricePer1m?: number | null;
+    cacheWritePricePer1m?: number | null;
+};
+/** Conflict reported during a source refresh — local row was user-edited. */
+interface PricingConflict {
+    providerId: string;
+    modelId: string;
+    /** Existing row in the local store (before any change). */
+    current: PricingEntry;
+    /** Incoming row from the pricing source. */
+    incoming: PricingEntryInput;
+}
+/** Result of a source refresh. The auto-applied entries are already written. */
+interface PricingFetchResult {
+    /** Rows that were upserted automatically (new or non-userEdited). */
+    applied: PricingEntry[];
+    /** Rows where the local copy is userEdited — surfaced to the UI for resolution. */
+    conflicts: PricingConflict[];
+    /** When the fetch started (unix-millis). */
+    fetchedAt: number;
+    /** Source URL that was fetched. */
+    sourceUrl: string;
+}
+/** Per-row decision passed back from the host's conflict-resolution UI. */
+interface PricingConflictDecision {
+    providerId: string;
+    modelId: string;
+    action: 'overwrite' | 'skip';
+}
+/** Outcome of resolving a list of conflict decisions. */
+interface PricingResolution {
+    /** Number of rows overwritten with the incoming source values. */
+    overwrittenCount: number;
+    /** Number of rows left unchanged (skipped). */
+    skippedCount: number;
+}
+/** Default LiteLLM source URL — public model_prices_and_context_window.json. */
+declare const DEFAULT_LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+
+export { DEFAULT_LITELLM_PRICING_URL, type PricingConflict, type PricingConflictDecision, type PricingEntry, type PricingEntryInput, type PricingFetchResult, type PricingResolution, type PricingSource };

package/dist/pricing-types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Model pricing types — provider-generic pricing-table contracts.
+ *
+ * Pricing rows are keyed by (providerId, modelId) and persisted by the
+ * embedding host's own store. The serving core's pricing engine uses them to
+ * derive `costUsd` for each captured usage event; hosts may also surface the
+ * rows in their own pricing-management UI.
+ *
+ * @module pricing-types
+ */
+/** Where this pricing entry came from. */
+type PricingSource = 
+/** Built-in fallback shipped by the host, seeded on first run. */
+'builtin'
+/** Auto-fetched from the LiteLLM JSON URL. */
+ | 'litellm'
+/** Hand-edited by the user; protected from auto-overwrite. */
+ | 'user';
+/**
+ * Per-model pricing row keyed by (providerId, modelId). Prices are in USD per
+ * 1,000,000 tokens. `cache_read` / `cache_write` are optional — providers
+ * without prompt caching leave them null.
+ */
+interface PricingEntry {
+    providerId: string;
+    modelId: string;
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    cacheReadPricePer1m: number | null;
+    cacheWritePricePer1m: number | null;
+    source: PricingSource;
+    /** True when the row has been hand-edited. Protects it from auto-overwrite during a source refresh. */
+    userEdited: boolean;
+    /** Unix-millis of the most recent user edit, or null if never. */
+    editedAt: number | null;
+    /** Unix-millis of the most recent write of any kind. */
+    updatedAt: number;
+}
+/** Upsert input shape (manual edits and parsed source entries). */
+type PricingEntryInput = {
+    providerId: string;
+    modelId: string;
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    cacheReadPricePer1m?: number | null;
+    cacheWritePricePer1m?: number | null;
+};
+/** Conflict reported during a source refresh — local row was user-edited. */
+interface PricingConflict {
+    providerId: string;
+    modelId: string;
+    /** Existing row in the local store (before any change). */
+    current: PricingEntry;
+    /** Incoming row from the pricing source. */
+    incoming: PricingEntryInput;
+}
+/** Result of a source refresh. The auto-applied entries are already written. */
+interface PricingFetchResult {
+    /** Rows that were upserted automatically (new or non-userEdited). */
+    applied: PricingEntry[];
+    /** Rows where the local copy is userEdited — surfaced to the UI for resolution. */
+    conflicts: PricingConflict[];
+    /** When the fetch started (unix-millis). */
+    fetchedAt: number;
+    /** Source URL that was fetched. */
+    sourceUrl: string;
+}
+/** Per-row decision passed back from the host's conflict-resolution UI. */
+interface PricingConflictDecision {
+    providerId: string;
+    modelId: string;
+    action: 'overwrite' | 'skip';
+}
+/** Outcome of resolving a list of conflict decisions. */
+interface PricingResolution {
+    /** Number of rows overwritten with the incoming source values. */
+    overwrittenCount: number;
+    /** Number of rows left unchanged (skipped). */
+    skippedCount: number;
+}
+/** Default LiteLLM source URL — public model_prices_and_context_window.json. */
+declare const DEFAULT_LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+
+export { DEFAULT_LITELLM_PRICING_URL, type PricingConflict, type PricingConflictDecision, type PricingEntry, type PricingEntryInput, type PricingFetchResult, type PricingResolution, type PricingSource };

package/dist/pricing-types.js

@@ -0,0 +1,5 @@
+// src/pricing-types.ts
+var DEFAULT_LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+export {
+  DEFAULT_LITELLM_PRICING_URL
+};

package/dist/usage-stats-types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/usage-stats-types.ts
+var usage_stats_types_exports = {};
+module.exports = __toCommonJS(usage_stats_types_exports);

package/dist/usage-stats-types.d.cts

@@ -0,0 +1,143 @@
+import { UsageEngineOrigin } from './usage-types.cjs';
+
+/**
+ * Usage-statistics DTOs — provider-generic stats row + aggregation views.
+ *
+ * The persisted usage-event row shape and the aggregate query views shared by
+ * embedders that record per-request usage. Storage itself is host-owned (the
+ * serving core only defines the seam); `engineOrigin` uses the OPEN
+ * `UsageEngineOrigin` union from `usage-types` so hosts may narrow it to their
+ * own closed engine list at their boundary.
+ *
+ * @module usage-stats-types
+ */
+
+/**
+ * One captured LLM request, as persisted by the host store.
+ *
+ * `messageId` is nullable because indirect call paths (e.g. subagent-internal
+ * requests) may not map to a host message row. `parentMessageId` is
+ * best-effort — populated when the caller knows the parent, NULL otherwise.
+ */
+interface UsageEventRecord {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    /** Hypothetical-input-cost − actual-cost difference attributable to cache_read tokens. */
+    costSavedByCacheUsd: number;
+    /** JSON-serialised raw provider usage object. Kept for forensics. */
+    rawUsage: string | null;
+    /** Host run-correlation id (owning agent-run, when the host has one). Additive / nullable. */
+    runId?: string | null;
+    /** Host event-correlation id for this LLM call. NULL when unknown. Additive / nullable. */
+    eventId?: string | null;
+}
+/** Input shape for inserting a new event. `id` and `ts` are filled by the recorder/store. */
+type UsageEventInput = Omit<UsageEventRecord, 'id' | 'ts'> & {
+    ts?: number;
+};
+/** Date range for queries. Both bounds are unix-millis; `endTs` is exclusive. */
+interface UsageDateRange {
+    startTs: number;
+    endTs: number;
+}
+interface UsageQueryParams {
+    range: UsageDateRange;
+    /** Optional filter — restrict to a particular session. */
+    sessionId?: string;
+}
+/** Aggregated totals over a date range. */
+interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** Number of events contributing to these totals. */
+    eventCount: number;
+}
+/** One row of the per-model breakdown. */
+interface ModelUsageRow {
+    providerId: string;
+    model: string;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** True when no pricing row exists for (providerId, model) — UIs may show an "unpriced" badge. */
+    unpriced: boolean;
+}
+/** One row of the per-API-key breakdown. NULL apiKeyId is mapped to a sentinel. */
+interface ApiKeyUsageRow {
+    /** `null` represents the unattributed sentinel group. */
+    apiKeyId: string | null;
+    /** Display label resolved by the host store (its key registry, or an "unattributed" fallback). */
+    label: string;
+    providerId: string | null;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/**
+ * Cumulative cache stats for ONE session — a SUM over the session's usage
+ * events. `hitRate` is the cost-oriented aggregate `ΣcacheRead / Σ(prompt-side
+ * tokens)` where the prompt-side total is `input + cacheRead + cacheCreation`
+ * (output excluded).
+ */
+interface SessionCacheStats {
+    sessionId: string;
+    /** Σ uncached prompt tokens (cache miss). */
+    inputTokens: number;
+    /** Σ cache-read (hit) tokens. */
+    cacheReadTokens: number;
+    /** Σ cache-creation (write) tokens — Anthropic; 0 for auto-caching providers. */
+    cacheCreationTokens: number;
+    /** Σ output tokens (not part of the hit-rate denominator). */
+    outputTokens: number;
+    /** Number of usage-event rows for the session. */
+    eventCount: number;
+    /**
+     * ΣcacheRead / Σ(input + cacheRead + cacheCreation), in [0, 1]. 0 when the
+     * session has no prompt-side tokens yet (avoids divide-by-zero).
+     */
+    hitRate: number;
+}
+/** One row in the message-level list (used by message-drilldown UI components). */
+interface MessageUsageRow {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+}
+
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTotals };

package/dist/usage-stats-types.d.ts

@@ -0,0 +1,143 @@
+import { UsageEngineOrigin } from './usage-types.js';
+
+/**
+ * Usage-statistics DTOs — provider-generic stats row + aggregation views.
+ *
+ * The persisted usage-event row shape and the aggregate query views shared by
+ * embedders that record per-request usage. Storage itself is host-owned (the
+ * serving core only defines the seam); `engineOrigin` uses the OPEN
+ * `UsageEngineOrigin` union from `usage-types` so hosts may narrow it to their
+ * own closed engine list at their boundary.
+ *
+ * @module usage-stats-types
+ */
+
+/**
+ * One captured LLM request, as persisted by the host store.
+ *
+ * `messageId` is nullable because indirect call paths (e.g. subagent-internal
+ * requests) may not map to a host message row. `parentMessageId` is
+ * best-effort — populated when the caller knows the parent, NULL otherwise.
+ */
+interface UsageEventRecord {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    /** Hypothetical-input-cost − actual-cost difference attributable to cache_read tokens. */
+    costSavedByCacheUsd: number;
+    /** JSON-serialised raw provider usage object. Kept for forensics. */
+    rawUsage: string | null;
+    /** Host run-correlation id (owning agent-run, when the host has one). Additive / nullable. */
+    runId?: string | null;
+    /** Host event-correlation id for this LLM call. NULL when unknown. Additive / nullable. */
+    eventId?: string | null;
+}
+/** Input shape for inserting a new event. `id` and `ts` are filled by the recorder/store. */
+type UsageEventInput = Omit<UsageEventRecord, 'id' | 'ts'> & {
+    ts?: number;
+};
+/** Date range for queries. Both bounds are unix-millis; `endTs` is exclusive. */
+interface UsageDateRange {
+    startTs: number;
+    endTs: number;
+}
+interface UsageQueryParams {
+    range: UsageDateRange;
+    /** Optional filter — restrict to a particular session. */
+    sessionId?: string;
+}
+/** Aggregated totals over a date range. */
+interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** Number of events contributing to these totals. */
+    eventCount: number;
+}
+/** One row of the per-model breakdown. */
+interface ModelUsageRow {
+    providerId: string;
+    model: string;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** True when no pricing row exists for (providerId, model) — UIs may show an "unpriced" badge. */
+    unpriced: boolean;
+}
+/** One row of the per-API-key breakdown. NULL apiKeyId is mapped to a sentinel. */
+interface ApiKeyUsageRow {
+    /** `null` represents the unattributed sentinel group. */
+    apiKeyId: string | null;
+    /** Display label resolved by the host store (its key registry, or an "unattributed" fallback). */
+    label: string;
+    providerId: string | null;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/**
+ * Cumulative cache stats for ONE session — a SUM over the session's usage
+ * events. `hitRate` is the cost-oriented aggregate `ΣcacheRead / Σ(prompt-side
+ * tokens)` where the prompt-side total is `input + cacheRead + cacheCreation`
+ * (output excluded).
+ */
+interface SessionCacheStats {
+    sessionId: string;
+    /** Σ uncached prompt tokens (cache miss). */
+    inputTokens: number;
+    /** Σ cache-read (hit) tokens. */
+    cacheReadTokens: number;
+    /** Σ cache-creation (write) tokens — Anthropic; 0 for auto-caching providers. */
+    cacheCreationTokens: number;
+    /** Σ output tokens (not part of the hit-rate denominator). */
+    outputTokens: number;
+    /** Number of usage-event rows for the session. */
+    eventCount: number;
+    /**
+     * ΣcacheRead / Σ(input + cacheRead + cacheCreation), in [0, 1]. 0 when the
+     * session has no prompt-side tokens yet (avoids divide-by-zero).
+     */
+    hitRate: number;
+}
+/** One row in the message-level list (used by message-drilldown UI components). */
+interface MessageUsageRow {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+}
+
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTotals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnicross/contracts",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Dependency-light, host-agnostic contract types + runtime-value helpers shared by the @omnicross/* packages.",
   "license": "MIT",
   "author": "Sayo (https://github.com/Dumoedss)",
@@ -75,6 +75,11 @@
       "import": "./dist/message-blocks.js",
       "require": "./dist/message-blocks.cjs"
     },
+    "./pricing-types": {
+      "types": "./dist/pricing-types.d.ts",
+      "import": "./dist/pricing-types.js",
+      "require": "./dist/pricing-types.cjs"
+    },
     "./provider-presets": {
       "types": "./dist/provider-presets/index.d.ts",
       "import": "./dist/provider-presets/index.js",
@@ -90,6 +95,11 @@
       "import": "./dist/thinking-config.js",
       "require": "./dist/thinking-config.cjs"
     },
+    "./usage-stats-types": {
+      "types": "./dist/usage-stats-types.d.ts",
+      "import": "./dist/usage-stats-types.js",
+      "require": "./dist/usage-stats-types.cjs"
+    },
     "./usage-types": {
       "types": "./dist/usage-types.d.ts",
       "import": "./dist/usage-types.js",