@omnicross/core 0.1.0 → 0.1.2

package/dist/types-BScIHmPr.d.cts

@@ -0,0 +1,153 @@
+import { MessageBlock } from '@omnicross/contracts/message-blocks';
+import { SimpleChatMessage, ThinkLevel, SimpleChatAudio, SimpleChatVideo } from '@omnicross/contracts/completion-types';
+
+/**
+ * Native Search Types
+ *
+ * Type definitions for provider-native web search capabilities.
+ * Used by NativeSearchInjector to detect and configure built-in
+ * search for OpenAI, Anthropic, Google, xAI, and OpenRouter.
+ *
+ * @module completion/native-search-types
+ */
+
+/** Providers that support native/built-in web search */
+type NativeSearchProvider = 'openai' | 'anthropic' | 'google' | 'xai' | 'openrouter';
+/** Result of detecting native search support for a model */
+interface NativeSearchDetectionResult {
+    /** Whether the model supports native search */
+    supported: boolean;
+    /** Which native provider to use, if supported */
+    nativeProvider: NativeSearchProvider | null;
+}
+/**
+ * Model ID patterns for detecting native search support.
+ * OpenRouter is detected via provider metadata, not model ID.
+ */
+declare const NATIVE_SEARCH_MODEL_PATTERNS: Record<NativeSearchProvider, RegExp[]>;
+/**
+ * OpenAI models that use Chat Completion endpoint (not Response API).
+ * These models use `web_search_options` instead of a `web_search` tool.
+ */
+declare const OPENAI_CHAT_COMPLETION_SEARCH_MODELS: string[];
+/**
+ * Models that match a native search pattern but do NOT support web search.
+ * These are excluded from auto-detection (but can still be user-overridden).
+ *
+ * - `gpt-4.1-nano`: Matches `/^gpt-4/` but OpenAI explicitly excludes it
+ *   from web search support in the Responses API.
+ */
+declare const NATIVE_SEARCH_EXCLUDED_MODELS: string[];
+/** Native search tool names that should NOT be executed locally */
+declare const NATIVE_SEARCH_TOOL_NAMES: string[];
+/** User-facing configuration for native search */
+interface NativeSearchUserConfig {
+    /** Whether native search is enabled */
+    enabled: boolean;
+    /** Max search results / uses (maps to provider-specific settings) */
+    maxResults?: number;
+    /** Domains to block (Anthropic) */
+    blockedDomains?: string[];
+    /** xAI search mode override */
+    searchMode?: 'on' | 'off' | 'auto';
+    /** xAI search sources */
+    sources?: Array<{
+        type: 'web' | 'x' | 'news';
+    }>;
+}
+/**
+ * Request body augmentation produced by NativeSearchInjector.
+ *
+ * - `additionalTools`: Appended to the tools array in the request body.
+ * - `bodyFields`: Merged into the top-level request body.
+ */
+interface NativeSearchAugmentation {
+    /** Extra tools to append (OpenAI web_search, Anthropic web_search_20250305, Gemini grounding) */
+    additionalTools?: unknown[];
+    /** Top-level body fields (xAI search_parameters, OpenRouter plugins, OpenAI web_search_options) */
+    bodyFields?: Record<string, unknown>;
+}
+/**
+ * Map from API format to potential native search providers.
+ *
+ * Note: `openai` (Chat Completions) is NOT mapped here because regular models
+ * (gpt-4o, o1, etc.) don't support native search via Chat Completions API.
+ * Only `gpt-4o-search-preview` models support it (via `web_search_options` body
+ * field), and those are handled by a special case in `detectNativeSearch()`.
+ *
+ * `openai-response` (Responses API) DOES support native `web_search` tool
+ * for gpt-4o, o1, o3, o4-mini, etc.
+ */
+declare const API_FORMAT_PROVIDER_MAP: Partial<Record<ApiFormat, NativeSearchProvider>>;
+
+/**
+ * Completion Service Types
+ *
+ * Type definitions for completion options, results, and callbacks.
+ */
+
+interface CompletionOptions {
+    providerId: string;
+    model: string;
+    messages: SimpleChatMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+    /** Thinking effort level for reasoning models */
+    thinkLevel?: ThinkLevel;
+    /** Native search augmentation to apply to the request body */
+    nativeSearchAugmentation?: NativeSearchAugmentation;
+    /** Session ID for API key pool affinity (preserves prompt cache) and usage attribution. */
+    sessionId?: string;
+    /**
+     * Assistant-message id this request is producing — used to attribute
+     * recorded usage rows back to host messages. Optional; if absent the row is
+     * still recorded but won't be linked.
+     */
+    messageId?: string;
+    /**
+     * Parent message id (for subagent-style nested calls). Best-effort: callers
+     * that know the parent should fill this; otherwise leave unset.
+     */
+    parentMessageId?: string;
+    /**
+     * Opt into the Anthropic 1M-context tier for this request. The transformer
+     * pipeline (and any direct Anthropic-format paths) inject the
+     * `'context-1m-2025-08-07'` beta into the outbound request body when this
+     * is true AND the resolved model is in the 1M-capable allowlist.
+     */
+    useExtendedContext?: boolean;
+}
+interface CompletionResult {
+    success: boolean;
+    message?: SimpleChatMessage;
+    error?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Provider finish reason (e.g. 'stop', 'tool_use', 'max_tokens') */
+    finishReason?: string;
+}
+interface StreamCallbacks {
+    onStart?: (messageId: string) => void;
+    onDelta?: (content: string) => void;
+    onReasoning?: (reasoning: string) => void;
+    onAudio?: (audio: SimpleChatAudio) => void;
+    onVideo?: (video: SimpleChatVideo) => void;
+    /** Called when a new content block is created (thinking, text, tool_use, tool_result) */
+    onBlock?: (block: MessageBlock) => void;
+    onDone?: (message: SimpleChatMessage, usage?: CompletionResult['usage'], metrics?: {
+        completionTokens: number;
+        timeCompletionMs: number;
+        timeFirstTokenMs?: number;
+    }) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * API format type for determining endpoint structure
+ */
+type ApiFormat = 'openai' | 'anthropic' | 'google' | 'azure-openai' | 'openai-response';
+
+export { type ApiFormat as A, type CompletionOptions as C, NATIVE_SEARCH_TOOL_NAMES as N, OPENAI_CHAT_COMPLETION_SEARCH_MODELS as O, type StreamCallbacks as S, type CompletionResult as a, type NativeSearchAugmentation as b, type NativeSearchDetectionResult as c, type NativeSearchProvider as d, type NativeSearchUserConfig as e, API_FORMAT_PROVIDER_MAP as f, NATIVE_SEARCH_EXCLUDED_MODELS as g, NATIVE_SEARCH_MODEL_PATTERNS as h };

package/dist/types-BScIHmPr.d.ts

@@ -0,0 +1,153 @@
+import { MessageBlock } from '@omnicross/contracts/message-blocks';
+import { SimpleChatMessage, ThinkLevel, SimpleChatAudio, SimpleChatVideo } from '@omnicross/contracts/completion-types';
+
+/**
+ * Native Search Types
+ *
+ * Type definitions for provider-native web search capabilities.
+ * Used by NativeSearchInjector to detect and configure built-in
+ * search for OpenAI, Anthropic, Google, xAI, and OpenRouter.
+ *
+ * @module completion/native-search-types
+ */
+
+/** Providers that support native/built-in web search */
+type NativeSearchProvider = 'openai' | 'anthropic' | 'google' | 'xai' | 'openrouter';
+/** Result of detecting native search support for a model */
+interface NativeSearchDetectionResult {
+    /** Whether the model supports native search */
+    supported: boolean;
+    /** Which native provider to use, if supported */
+    nativeProvider: NativeSearchProvider | null;
+}
+/**
+ * Model ID patterns for detecting native search support.
+ * OpenRouter is detected via provider metadata, not model ID.
+ */
+declare const NATIVE_SEARCH_MODEL_PATTERNS: Record<NativeSearchProvider, RegExp[]>;
+/**
+ * OpenAI models that use Chat Completion endpoint (not Response API).
+ * These models use `web_search_options` instead of a `web_search` tool.
+ */
+declare const OPENAI_CHAT_COMPLETION_SEARCH_MODELS: string[];
+/**
+ * Models that match a native search pattern but do NOT support web search.
+ * These are excluded from auto-detection (but can still be user-overridden).
+ *
+ * - `gpt-4.1-nano`: Matches `/^gpt-4/` but OpenAI explicitly excludes it
+ *   from web search support in the Responses API.
+ */
+declare const NATIVE_SEARCH_EXCLUDED_MODELS: string[];
+/** Native search tool names that should NOT be executed locally */
+declare const NATIVE_SEARCH_TOOL_NAMES: string[];
+/** User-facing configuration for native search */
+interface NativeSearchUserConfig {
+    /** Whether native search is enabled */
+    enabled: boolean;
+    /** Max search results / uses (maps to provider-specific settings) */
+    maxResults?: number;
+    /** Domains to block (Anthropic) */
+    blockedDomains?: string[];
+    /** xAI search mode override */
+    searchMode?: 'on' | 'off' | 'auto';
+    /** xAI search sources */
+    sources?: Array<{
+        type: 'web' | 'x' | 'news';
+    }>;
+}
+/**
+ * Request body augmentation produced by NativeSearchInjector.
+ *
+ * - `additionalTools`: Appended to the tools array in the request body.
+ * - `bodyFields`: Merged into the top-level request body.
+ */
+interface NativeSearchAugmentation {
+    /** Extra tools to append (OpenAI web_search, Anthropic web_search_20250305, Gemini grounding) */
+    additionalTools?: unknown[];
+    /** Top-level body fields (xAI search_parameters, OpenRouter plugins, OpenAI web_search_options) */
+    bodyFields?: Record<string, unknown>;
+}
+/**
+ * Map from API format to potential native search providers.
+ *
+ * Note: `openai` (Chat Completions) is NOT mapped here because regular models
+ * (gpt-4o, o1, etc.) don't support native search via Chat Completions API.
+ * Only `gpt-4o-search-preview` models support it (via `web_search_options` body
+ * field), and those are handled by a special case in `detectNativeSearch()`.
+ *
+ * `openai-response` (Responses API) DOES support native `web_search` tool
+ * for gpt-4o, o1, o3, o4-mini, etc.
+ */
+declare const API_FORMAT_PROVIDER_MAP: Partial<Record<ApiFormat, NativeSearchProvider>>;
+
+/**
+ * Completion Service Types
+ *
+ * Type definitions for completion options, results, and callbacks.
+ */
+
+interface CompletionOptions {
+    providerId: string;
+    model: string;
+    messages: SimpleChatMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+    /** Thinking effort level for reasoning models */
+    thinkLevel?: ThinkLevel;
+    /** Native search augmentation to apply to the request body */
+    nativeSearchAugmentation?: NativeSearchAugmentation;
+    /** Session ID for API key pool affinity (preserves prompt cache) and usage attribution. */
+    sessionId?: string;
+    /**
+     * Assistant-message id this request is producing — used to attribute
+     * recorded usage rows back to host messages. Optional; if absent the row is
+     * still recorded but won't be linked.
+     */
+    messageId?: string;
+    /**
+     * Parent message id (for subagent-style nested calls). Best-effort: callers
+     * that know the parent should fill this; otherwise leave unset.
+     */
+    parentMessageId?: string;
+    /**
+     * Opt into the Anthropic 1M-context tier for this request. The transformer
+     * pipeline (and any direct Anthropic-format paths) inject the
+     * `'context-1m-2025-08-07'` beta into the outbound request body when this
+     * is true AND the resolved model is in the 1M-capable allowlist.
+     */
+    useExtendedContext?: boolean;
+}
+interface CompletionResult {
+    success: boolean;
+    message?: SimpleChatMessage;
+    error?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Provider finish reason (e.g. 'stop', 'tool_use', 'max_tokens') */
+    finishReason?: string;
+}
+interface StreamCallbacks {
+    onStart?: (messageId: string) => void;
+    onDelta?: (content: string) => void;
+    onReasoning?: (reasoning: string) => void;
+    onAudio?: (audio: SimpleChatAudio) => void;
+    onVideo?: (video: SimpleChatVideo) => void;
+    /** Called when a new content block is created (thinking, text, tool_use, tool_result) */
+    onBlock?: (block: MessageBlock) => void;
+    onDone?: (message: SimpleChatMessage, usage?: CompletionResult['usage'], metrics?: {
+        completionTokens: number;
+        timeCompletionMs: number;
+        timeFirstTokenMs?: number;
+    }) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * API format type for determining endpoint structure
+ */
+type ApiFormat = 'openai' | 'anthropic' | 'google' | 'azure-openai' | 'openai-response';
+
+export { type ApiFormat as A, type CompletionOptions as C, NATIVE_SEARCH_TOOL_NAMES as N, OPENAI_CHAT_COMPLETION_SEARCH_MODELS as O, type StreamCallbacks as S, type CompletionResult as a, type NativeSearchAugmentation as b, type NativeSearchDetectionResult as c, type NativeSearchProvider as d, type NativeSearchUserConfig as e, API_FORMAT_PROVIDER_MAP as f, NATIVE_SEARCH_EXCLUDED_MODELS as g, NATIVE_SEARCH_MODEL_PATTERNS as h };

package/dist/usage/pricing-engine.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkYMFAJFQTcjs = require('../chunk-YMFAJFQT.cjs');
+
+
+exports.PricingEngine = _chunkYMFAJFQTcjs.PricingEngine;

package/dist/usage/pricing-engine.d.cts

@@ -0,0 +1,83 @@
+import { PricingEntry, PricingEntryInput, PricingFetchResult, PricingConflictDecision, PricingResolution } from '@omnicross/contracts/pricing-types';
+import { UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.cjs';
+import { PricingStore } from '../ports/pricing-store.cjs';
+
+/**
+ * PricingEngine — manages model pricing and computes per-event cost.
+ *
+ * Persistence goes through the injected `PricingStore` port. Sources of
+ * pricing rows:
+ *  - 'builtin'  — bundled fallback prices, seeded by the host
+ *  - 'litellm'  — refreshed on user demand from LiteLLM's public JSON
+ *  - 'user'     — hand-edited; protected from auto-overwrite
+ *
+ * @module usage/pricing-engine
+ */
+
+/** Output of `calculateCost`. */
+interface CostCalculation {
+    costUsd: number;
+    /**
+     * Difference between hypothetical-no-cache cost (charging cacheReadTokens at
+     * the full input price) and the actual cost (charging at the cache_read price).
+     * Always ≥ 0.
+     */
+    costSavedByCacheUsd: number;
+}
+/** Optional knobs (mostly for tests). */
+interface PricingEngineOptions {
+    /** Override the pricing-source JSON URL — useful for testing. */
+    sourceUrl?: string;
+    /** Override `fetch` — useful for testing. */
+    fetchImpl?: typeof fetch;
+}
+declare class PricingEngine {
+    private store;
+    private logger;
+    private options;
+    private cache;
+    /**
+     * Secondary index keyed by modelId alone. Used as a fallback when no exact
+     * (providerId, modelId) match exists — usage may be recorded under a
+     * runtime provider alias while pricing rows use the canonical provider id,
+     * so matching by model name lets the price still resolve. First
+     * non-wildcard entry per model wins.
+     */
+    private cacheByModel;
+    private cacheLoaded;
+    constructor(store: PricingStore, logger: Logger, options?: PricingEngineOptions);
+    /** Lazy-load and cache the full pricing table. */
+    private ensureCache;
+    /** Force a cache refresh — call after any write. */
+    invalidateCache(): Promise<void>;
+    getAll(): Promise<PricingEntry[]>;
+    /**
+     * Look up a price for (provider, model). Resolution order:
+     *   1. exact (providerId, modelId)
+     *   2. wildcard provider ('*', modelId)
+     *   3. model name alone (any provider) — tolerates a runtime-alias vs
+     *      canonical provider-id mismatch for the same model.
+     */
+    getEntry(providerId: string, modelId: string): Promise<PricingEntry | null>;
+    /**
+     * Compute the cost (and cache savings) for a single response.
+     *
+     * Cost formula (USD):
+     *   cost = (input  * inputPrice
+     *         + output * outputPrice
+     *         + cacheRead  * (cacheReadPrice  ?? inputPrice)
+     *         + cacheWrite * (cacheWritePrice ?? inputPrice)
+     *        ) / 1e6
+     *
+     * Cache savings:
+     *   savings = cacheRead * (inputPrice - cacheReadPrice) / 1e6
+     *           — clamped at 0 if cacheReadPrice is null or ≥ inputPrice.
+     */
+    calculateCost(providerId: string, modelId: string, usage: UsageTokens): Promise<CostCalculation>;
+    upsertManual(input: PricingEntryInput): Promise<PricingEntry>;
+    fetchLatestFromSource(): Promise<PricingFetchResult>;
+    resolveConflicts(decisions: PricingConflictDecision[], pendingIncoming: Map<string, PricingEntryInput>): Promise<PricingResolution>;
+}
+
+export { type CostCalculation, PricingEngine, type PricingEngineOptions };

package/dist/usage/pricing-engine.d.ts

@@ -0,0 +1,83 @@
+import { PricingEntry, PricingEntryInput, PricingFetchResult, PricingConflictDecision, PricingResolution } from '@omnicross/contracts/pricing-types';
+import { UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.js';
+import { PricingStore } from '../ports/pricing-store.js';
+
+/**
+ * PricingEngine — manages model pricing and computes per-event cost.
+ *
+ * Persistence goes through the injected `PricingStore` port. Sources of
+ * pricing rows:
+ *  - 'builtin'  — bundled fallback prices, seeded by the host
+ *  - 'litellm'  — refreshed on user demand from LiteLLM's public JSON
+ *  - 'user'     — hand-edited; protected from auto-overwrite
+ *
+ * @module usage/pricing-engine
+ */
+
+/** Output of `calculateCost`. */
+interface CostCalculation {
+    costUsd: number;
+    /**
+     * Difference between hypothetical-no-cache cost (charging cacheReadTokens at
+     * the full input price) and the actual cost (charging at the cache_read price).
+     * Always ≥ 0.
+     */
+    costSavedByCacheUsd: number;
+}
+/** Optional knobs (mostly for tests). */
+interface PricingEngineOptions {
+    /** Override the pricing-source JSON URL — useful for testing. */
+    sourceUrl?: string;
+    /** Override `fetch` — useful for testing. */
+    fetchImpl?: typeof fetch;
+}
+declare class PricingEngine {
+    private store;
+    private logger;
+    private options;
+    private cache;
+    /**
+     * Secondary index keyed by modelId alone. Used as a fallback when no exact
+     * (providerId, modelId) match exists — usage may be recorded under a
+     * runtime provider alias while pricing rows use the canonical provider id,
+     * so matching by model name lets the price still resolve. First
+     * non-wildcard entry per model wins.
+     */
+    private cacheByModel;
+    private cacheLoaded;
+    constructor(store: PricingStore, logger: Logger, options?: PricingEngineOptions);
+    /** Lazy-load and cache the full pricing table. */
+    private ensureCache;
+    /** Force a cache refresh — call after any write. */
+    invalidateCache(): Promise<void>;
+    getAll(): Promise<PricingEntry[]>;
+    /**
+     * Look up a price for (provider, model). Resolution order:
+     *   1. exact (providerId, modelId)
+     *   2. wildcard provider ('*', modelId)
+     *   3. model name alone (any provider) — tolerates a runtime-alias vs
+     *      canonical provider-id mismatch for the same model.
+     */
+    getEntry(providerId: string, modelId: string): Promise<PricingEntry | null>;
+    /**
+     * Compute the cost (and cache savings) for a single response.
+     *
+     * Cost formula (USD):
+     *   cost = (input  * inputPrice
+     *         + output * outputPrice
+     *         + cacheRead  * (cacheReadPrice  ?? inputPrice)
+     *         + cacheWrite * (cacheWritePrice ?? inputPrice)
+     *        ) / 1e6
+     *
+     * Cache savings:
+     *   savings = cacheRead * (inputPrice - cacheReadPrice) / 1e6
+     *           — clamped at 0 if cacheReadPrice is null or ≥ inputPrice.
+     */
+    calculateCost(providerId: string, modelId: string, usage: UsageTokens): Promise<CostCalculation>;
+    upsertManual(input: PricingEntryInput): Promise<PricingEntry>;
+    fetchLatestFromSource(): Promise<PricingFetchResult>;
+    resolveConflicts(decisions: PricingConflictDecision[], pendingIncoming: Map<string, PricingEntryInput>): Promise<PricingResolution>;
+}
+
+export { type CostCalculation, PricingEngine, type PricingEngineOptions };

package/dist/usage/pricing-engine.js

@@ -0,0 +1,6 @@
+import {
+  PricingEngine
+} from "../chunk-ZLX3KGXX.js";
+export {
+  PricingEngine
+};

package/dist/usage/usage-recorder.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkXBSYYZIYcjs = require('../chunk-XBSYYZIY.cjs');
+
+
+exports.UsageRecorder = _chunkXBSYYZIYcjs.UsageRecorder;

package/dist/usage/usage-recorder.d.cts

@@ -0,0 +1,73 @@
+import { PricingEngine } from './pricing-engine.cjs';
+import { UsageDateRange, UsageTotals, ModelUsageRow, ApiKeyUsageRow, MessageUsageRow, SessionCacheStats } from '@omnicross/contracts/usage-stats-types';
+import { UsageEngineOrigin, UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.cjs';
+import { UsageEventStore } from '../ports/usage-event-store.cjs';
+import '@omnicross/contracts/pricing-types';
+import '../ports/pricing-store.cjs';
+
+/**
+ * UsageRecorder — funnels every captured LLM-request event through cost
+ * calculation and persists it via the injected `UsageEventStore`.
+ *
+ * Capture taps call `record()` synchronously with the parsed usage data. The
+ * store insert is enqueued via an injectable deferral function (default: a
+ * zero-delay timer; Node hosts may inject `setImmediate`) so the response path
+ * is never blocked on disk I/O.
+ *
+ * @module usage/usage-recorder
+ */
+
+/** Subset of fields the caller MUST provide. Recorder fills cost (store fills ts). */
+interface UsageRecordInput {
+    messageId?: string | null;
+    parentMessageId?: string | null;
+    sessionId?: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId?: string | null;
+    engineOrigin: UsageEngineOrigin;
+    usage: UsageTokens;
+    /** Optional raw provider usage block — kept verbatim for forensics. */
+    rawUsage?: unknown;
+    /** Host run-correlation id. Optional / additive. */
+    runId?: string | null;
+    /** Host event-correlation id for this call. Optional / additive. */
+    eventId?: string | null;
+}
+/** Optional knobs (mostly for hosts/tests). */
+interface UsageRecorderOptions {
+    /**
+     * Deferral function used by `record()` to schedule the async persist off
+     * the caller's path. Defaults to a zero-delay timer; Node hosts may inject
+     * `setImmediate` to preserve their exact scheduling.
+     */
+    defer?: (fn: () => void) => void;
+}
+declare class UsageRecorder {
+    private store;
+    private pricing;
+    private logger;
+    private defer;
+    constructor(store: UsageEventStore, pricing: PricingEngine, logger: Logger, options?: UsageRecorderOptions);
+    /**
+     * Record one LLM request. Returns immediately — the actual store insert is
+     * deferred so the caller's response path is unblocked.
+     *
+     * Errors during the insert are logged but never thrown.
+     */
+    record(input: UsageRecordInput): void;
+    /**
+     * Same as `record()` but awaitable — preferred in tests so they can assert
+     * after the row exists.
+     */
+    recordAsync(input: UsageRecordInput): Promise<string | null>;
+    getTotals(range: UsageDateRange): Promise<UsageTotals>;
+    getByModel(range: UsageDateRange): Promise<ModelUsageRow[]>;
+    getByApiKey(range: UsageDateRange): Promise<ApiKeyUsageRow[]>;
+    getMessagesForSession(sessionId: string): Promise<MessageUsageRow[]>;
+    /** Cumulative cache hit/miss stats for one session. */
+    getSessionCacheStats(sessionId: string): Promise<SessionCacheStats>;
+}
+
+export { type UsageRecordInput, UsageRecorder, type UsageRecorderOptions };

package/dist/usage/usage-recorder.d.ts

@@ -0,0 +1,73 @@
+import { PricingEngine } from './pricing-engine.js';
+import { UsageDateRange, UsageTotals, ModelUsageRow, ApiKeyUsageRow, MessageUsageRow, SessionCacheStats } from '@omnicross/contracts/usage-stats-types';
+import { UsageEngineOrigin, UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.js';
+import { UsageEventStore } from '../ports/usage-event-store.js';
+import '@omnicross/contracts/pricing-types';
+import '../ports/pricing-store.js';
+
+/**
+ * UsageRecorder — funnels every captured LLM-request event through cost
+ * calculation and persists it via the injected `UsageEventStore`.
+ *
+ * Capture taps call `record()` synchronously with the parsed usage data. The
+ * store insert is enqueued via an injectable deferral function (default: a
+ * zero-delay timer; Node hosts may inject `setImmediate`) so the response path
+ * is never blocked on disk I/O.
+ *
+ * @module usage/usage-recorder
+ */
+
+/** Subset of fields the caller MUST provide. Recorder fills cost (store fills ts). */
+interface UsageRecordInput {
+    messageId?: string | null;
+    parentMessageId?: string | null;
+    sessionId?: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId?: string | null;
+    engineOrigin: UsageEngineOrigin;
+    usage: UsageTokens;
+    /** Optional raw provider usage block — kept verbatim for forensics. */
+    rawUsage?: unknown;
+    /** Host run-correlation id. Optional / additive. */
+    runId?: string | null;
+    /** Host event-correlation id for this call. Optional / additive. */
+    eventId?: string | null;
+}
+/** Optional knobs (mostly for hosts/tests). */
+interface UsageRecorderOptions {
+    /**
+     * Deferral function used by `record()` to schedule the async persist off
+     * the caller's path. Defaults to a zero-delay timer; Node hosts may inject
+     * `setImmediate` to preserve their exact scheduling.
+     */
+    defer?: (fn: () => void) => void;
+}
+declare class UsageRecorder {
+    private store;
+    private pricing;
+    private logger;
+    private defer;
+    constructor(store: UsageEventStore, pricing: PricingEngine, logger: Logger, options?: UsageRecorderOptions);
+    /**
+     * Record one LLM request. Returns immediately — the actual store insert is
+     * deferred so the caller's response path is unblocked.
+     *
+     * Errors during the insert are logged but never thrown.
+     */
+    record(input: UsageRecordInput): void;
+    /**
+     * Same as `record()` but awaitable — preferred in tests so they can assert
+     * after the row exists.
+     */
+    recordAsync(input: UsageRecordInput): Promise<string | null>;
+    getTotals(range: UsageDateRange): Promise<UsageTotals>;
+    getByModel(range: UsageDateRange): Promise<ModelUsageRow[]>;
+    getByApiKey(range: UsageDateRange): Promise<ApiKeyUsageRow[]>;
+    getMessagesForSession(sessionId: string): Promise<MessageUsageRow[]>;
+    /** Cumulative cache hit/miss stats for one session. */
+    getSessionCacheStats(sessionId: string): Promise<SessionCacheStats>;
+}
+
+export { type UsageRecordInput, UsageRecorder, type UsageRecorderOptions };

package/dist/usage/usage-recorder.js

@@ -0,0 +1,6 @@
+import {
+  UsageRecorder
+} from "../chunk-MNYKI4CI.js";
+export {
+  UsageRecorder
+};

package/dist/usage.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});require('./chunk-EYZYXJTJ.cjs');
+
+
+var _chunkYMFAJFQTcjs = require('./chunk-YMFAJFQT.cjs');
+
+
+var _chunkXBSYYZIYcjs = require('./chunk-XBSYYZIY.cjs');
+
+
+
+exports.PricingEngine = _chunkYMFAJFQTcjs.PricingEngine; exports.UsageRecorder = _chunkXBSYYZIYcjs.UsageRecorder;

package/dist/usage.d.cts

@@ -0,0 +1,8 @@
+export { CostCalculation, PricingEngine, PricingEngineOptions } from './usage/pricing-engine.cjs';
+export { UsageRecordInput, UsageRecorder, UsageRecorderOptions } from './usage/usage-recorder.cjs';
+import '@omnicross/contracts/pricing-types';
+import '@omnicross/contracts/usage-types';
+import './logger-4GvQNzhE.cjs';
+import './ports/pricing-store.cjs';
+import '@omnicross/contracts/usage-stats-types';
+import './ports/usage-event-store.cjs';