@omnicross/core 0.1.8 → 0.1.10

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

@@ -1,8 +1,8 @@
-import { PricingEngine } from './pricing-engine.js';
-import { UsageCacheKeySource, UsageDateRange, UsageTotals, ModelUsageRow, ApiKeyUsageRow, UsageTimeBucket, UsageTimeSeriesBucket, MessageUsageRow, SessionCacheStats } from '@omnicross/contracts/usage-stats-types';
+import { UsageCacheKeySource, UsageEventInput, UsageDateRange, UsageTotals, ModelUsageRow, ApiKeyUsageRow, UsageTimeBucket, UsageTimeSeriesBucket, 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 { PricingEngine } from './pricing-engine.js';
 import '@omnicross/contracts/pricing-types';
 import '../ports/pricing-store.js';
 
@@ -69,6 +69,15 @@ interface UsageRecorderOptions {
      * Absent ⇒ no-op (byte-identical for hosts/tests that do not wire it).
      */
     onRecord?: (apiKeyId: string, costUsd: number, now: number) => void;
+    /**
+     * OPTIONAL per-request hook (live-throughput). Called synchronously with the
+     * FINISHED row, immediately before the store insert, for EVERY recorded
+     * request — attributed or not. Distinct from `onRecord`, which is gated on
+     * `apiKeyId` and carries only the cost: a rate metric must see subscription-
+     * account traffic too, and needs the token counts. Absent ⇒ no-op
+     * (byte-identical for hosts/tests that do not wire it).
+     */
+    onEvent?: (row: UsageEventInput, at: number) => void;
 }
 declare class UsageRecorder {
     private store;
@@ -76,6 +85,7 @@ declare class UsageRecorder {
     private logger;
     private defer;
     private onRecord?;
+    private onEvent?;
     constructor(store: UsageEventStore, pricing: PricingEngine, logger: Logger, options?: UsageRecorderOptions);
     /**
      * Record one LLM request. Returns immediately — the actual store insert is

package/dist/usage/usage-recorder.js

@@ -1,6 +1,6 @@
 import {
   UsageRecorder
-} from "../chunk-UAPBLNN2.js";
+} from "../chunk-AQDON6MB.js";
 import "../chunk-OZFM4X3S.js";
 export {
   UsageRecorder

package/dist/usage.cjs

@@ -1,12 +1,29 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});require('./chunk-EYZYXJTJ.cjs');
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+var _chunkQUSEZNYScjs = require('./chunk-QUSEZNYS.cjs');
 
 
 var _chunk2E42SAW3cjs = require('./chunk-2E42SAW3.cjs');
 
 
-var _chunkEPN67EGPcjs = require('./chunk-EPN67EGP.cjs');
+var _chunk5UK3KLE2cjs = require('./chunk-5UK3KLE2.cjs');
 require('./chunk-XSVNC2UD.cjs');
 
 
 
-exports.PricingEngine = _chunk2E42SAW3cjs.PricingEngine; exports.UsageRecorder = _chunkEPN67EGPcjs.UsageRecorder;
+
+
+
+
+
+
+
+
+exports.PricingEngine = _chunk2E42SAW3cjs.PricingEngine; exports.THROUGHPUT_BUCKET_COUNT = _chunkQUSEZNYScjs.THROUGHPUT_BUCKET_COUNT; exports.THROUGHPUT_RETENTION_MS = _chunkQUSEZNYScjs.THROUGHPUT_RETENTION_MS; exports.THROUGHPUT_SAMPLE_LIMIT = _chunkQUSEZNYScjs.THROUGHPUT_SAMPLE_LIMIT; exports.THROUGHPUT_WINDOWS_MS = _chunkQUSEZNYScjs.THROUGHPUT_WINDOWS_MS; exports.UsageRecorder = _chunk5UK3KLE2cjs.UsageRecorder; exports.UsageThroughputTracker = _chunkQUSEZNYScjs.UsageThroughputTracker; exports.__resetSharedUsageThroughputTrackerForTests = _chunkQUSEZNYScjs.__resetSharedUsageThroughputTrackerForTests; exports.getSharedUsageThroughputTracker = _chunkQUSEZNYScjs.getSharedUsageThroughputTracker; exports.setSharedUsageThroughputTracker = _chunkQUSEZNYScjs.setSharedUsageThroughputTracker;

package/dist/usage.d.cts

@@ -6,3 +6,152 @@ import './logger-4GvQNzhE.cjs';
 import './ports/pricing-store.cjs';
 import '@omnicross/contracts/usage-stats-types';
 import './ports/usage-event-store.cjs';
+
+/**
+ * throughputTracker — a bounded, in-memory sliding window of recently recorded
+ * usage events, answering "how fast is the gateway serving RIGHT NOW".
+ *
+ * WHY a dedicated in-memory store (not a `UsageEventStore` range query): the
+ * daemon's `JsonlUsageEventStore.getTotals()` reads and parses the ENTIRE
+ * `usage-events.jsonl` synchronously on every call (a deliberate simplification
+ * documented there). That is fine for an on-demand stats page, but a live rate
+ * widget polls every few seconds, and a periodic synchronous full-file scan
+ * would stall the same event loop that is relaying gateway requests. This
+ * tracker is fed O(1) per recorded request from `UsageRecorder`'s `onEvent`
+ * hook and read in O(samples-in-window) — it never touches disk.
+ *
+ * Shaped like `pipeline/ServerOverloadCounter`: process-local, cleared on
+ * restart, an injectable `now` clock, no external deps. It carries ONLY token
+ * counts, costs, and epoch timestamps — never a prompt, header, model secret,
+ * or key id — so no snapshot of it can leak one.
+ *
+ * TWO MEASUREMENT DECISIONS worth stating explicitly, because both are easy to
+ * get subtly wrong:
+ *
+ *  1. `totalTokens` deliberately EXCLUDES `reasoningTokens`. Providers report
+ *     reasoning tokens as a SUBSET of the completion/output tokens, so adding
+ *     them would double-count. They are still reported separately.
+ *
+ *  2. Rates always divide by the FULL requested window, never by "how long this
+ *     process has been up". A daemon that was down served no traffic, so the
+ *     honest rate over that wall-clock window really is lower; after a restart
+ *     the number climbs back from zero on its own. `startedAt` is reported so a
+ *     reader can say "this process started less than a window ago" without the
+ *     rate itself being fudged.
+ *
+ * @module usage/throughputTracker
+ */
+/** Longest window a snapshot can answer; also the sample-retention horizon. */
+declare const THROUGHPUT_RETENTION_MS: number;
+/**
+ * Hard memory ceiling on retained samples (~20k x a few dozen bytes). Reaching
+ * it means sustained >22 req/s for a full 15 minutes; past that the OLDEST
+ * samples are evicted and the affected windows report `complete: false` rather
+ * than quietly under-reporting.
+ */
+declare const THROUGHPUT_SAMPLE_LIMIT = 20000;
+/** Windows every snapshot reports, shortest first. The last must be <= retention. */
+declare const THROUGHPUT_WINDOWS_MS: readonly [60000, 300000, 900000];
+/** Trend-series resolution: 30 buckets across the retention horizon (30s each). */
+declare const THROUGHPUT_BUCKET_COUNT = 30;
+/**
+ * One recorded request's contribution. Structurally satisfied by the recorder's
+ * `UsageEventInput` row, so the daemon can forward it verbatim.
+ */
+interface UsageThroughputInput {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    /** Epoch-ms of the event. Omit to use the `now` argument. */
+    ts?: number;
+}
+/** Aggregates + rates for one trailing window. */
+interface UsageThroughputWindow {
+    /** Trailing window this row covers, in ms. */
+    windowMs: number;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    /** input + output + cacheRead + cacheCreation (reasoning is a subset of output). */
+    totalTokens: number;
+    costUsd: number;
+    requestsPerMinute: number;
+    /** The headline TPM: `totalTokens` per minute over `windowMs`. */
+    tokensPerMinute: number;
+    inputTokensPerMinute: number;
+    outputTokensPerMinute: number;
+    costUsdPerMinute: number;
+    /**
+     * False when the sample cap evicted events that fall inside this window, so
+     * every figure above is a LOWER BOUND rather than an exact count.
+     */
+    complete: boolean;
+}
+/** One fixed-width bucket of the trend series. */
+interface UsageThroughputBucket {
+    /** Epoch-ms of the bucket's (grid-aligned) start. */
+    startTs: number;
+    requests: number;
+    tokens: number;
+}
+/** The `GET /admin/api/usage/throughput` payload. */
+interface UsageThroughputSnapshot {
+    /** Always true here; the UI's fallback shape uses `false` for older daemons. */
+    available: true;
+    collectedAt: number;
+    /** Epoch-ms this tracker began observing (effectively the daemon's start). */
+    startedAt: number;
+    retentionMs: number;
+    /** Width of one `buckets` entry, in ms. */
+    bucketMs: number;
+    /** One row per {@link THROUGHPUT_WINDOWS_MS} entry, shortest window first. */
+    windows: UsageThroughputWindow[];
+    /**
+     * Oldest to newest, exactly {@link THROUGHPUT_BUCKET_COUNT} entries covering
+     * `retentionMs` on a `bucketMs` grid. Empty buckets are present and zeroed;
+     * the final bucket is still in progress. Grid alignment (rather than
+     * "now minus retention") keeps boundaries stable between polls so a sparkline
+     * does not shimmer.
+     */
+    buckets: UsageThroughputBucket[];
+}
+declare class UsageThroughputTracker {
+    private samples;
+    /** Index of the oldest live sample; slots before it are consumed. */
+    private head;
+    private readonly startedAt;
+    /** Newest ts dropped by the sample CAP (not by retention). Null when none. */
+    private evictedThroughTs;
+    constructor(now?: number);
+    /** Record one served request. O(1) amortised; never touches disk. */
+    record(input: UsageThroughputInput, now?: number): void;
+    /** Aggregate every reported window plus the shared trend series. */
+    snapshot(now?: number): UsageThroughputSnapshot;
+    /** Drop all samples (tests / teardown). `startedAt` is unchanged. */
+    clear(): void;
+    /**
+     * Drop samples past the retention horizon, then enforce the sample cap.
+     *
+     * Retention pruning uses the CALLER's `now`, which is never later than a
+     * subsequent snapshot's `now`, so it can only ever keep MORE than the widest
+     * window needs — it can never shave data off the 15-minute window.
+     */
+    private prune;
+    private window;
+    private buckets;
+}
+declare function getSharedUsageThroughputTracker(): UsageThroughputTracker;
+/**
+ * TEST SEAM — swap the singleton (e.g. with a fixed-clock instance). Mirrors the
+ * `setShared…`/`__reset…ForTests` discipline of the sibling in-memory stores.
+ */
+declare function setSharedUsageThroughputTracker(instance: UsageThroughputTracker): void;
+declare function __resetSharedUsageThroughputTrackerForTests(): void;
+
+export { THROUGHPUT_BUCKET_COUNT, THROUGHPUT_RETENTION_MS, THROUGHPUT_SAMPLE_LIMIT, THROUGHPUT_WINDOWS_MS, type UsageThroughputBucket, type UsageThroughputInput, type UsageThroughputSnapshot, UsageThroughputTracker, type UsageThroughputWindow, __resetSharedUsageThroughputTrackerForTests, getSharedUsageThroughputTracker, setSharedUsageThroughputTracker };

package/dist/usage.d.ts

@@ -6,3 +6,152 @@ import './logger-4GvQNzhE.js';
 import './ports/pricing-store.js';
 import '@omnicross/contracts/usage-stats-types';
 import './ports/usage-event-store.js';
+
+/**
+ * throughputTracker — a bounded, in-memory sliding window of recently recorded
+ * usage events, answering "how fast is the gateway serving RIGHT NOW".
+ *
+ * WHY a dedicated in-memory store (not a `UsageEventStore` range query): the
+ * daemon's `JsonlUsageEventStore.getTotals()` reads and parses the ENTIRE
+ * `usage-events.jsonl` synchronously on every call (a deliberate simplification
+ * documented there). That is fine for an on-demand stats page, but a live rate
+ * widget polls every few seconds, and a periodic synchronous full-file scan
+ * would stall the same event loop that is relaying gateway requests. This
+ * tracker is fed O(1) per recorded request from `UsageRecorder`'s `onEvent`
+ * hook and read in O(samples-in-window) — it never touches disk.
+ *
+ * Shaped like `pipeline/ServerOverloadCounter`: process-local, cleared on
+ * restart, an injectable `now` clock, no external deps. It carries ONLY token
+ * counts, costs, and epoch timestamps — never a prompt, header, model secret,
+ * or key id — so no snapshot of it can leak one.
+ *
+ * TWO MEASUREMENT DECISIONS worth stating explicitly, because both are easy to
+ * get subtly wrong:
+ *
+ *  1. `totalTokens` deliberately EXCLUDES `reasoningTokens`. Providers report
+ *     reasoning tokens as a SUBSET of the completion/output tokens, so adding
+ *     them would double-count. They are still reported separately.
+ *
+ *  2. Rates always divide by the FULL requested window, never by "how long this
+ *     process has been up". A daemon that was down served no traffic, so the
+ *     honest rate over that wall-clock window really is lower; after a restart
+ *     the number climbs back from zero on its own. `startedAt` is reported so a
+ *     reader can say "this process started less than a window ago" without the
+ *     rate itself being fudged.
+ *
+ * @module usage/throughputTracker
+ */
+/** Longest window a snapshot can answer; also the sample-retention horizon. */
+declare const THROUGHPUT_RETENTION_MS: number;
+/**
+ * Hard memory ceiling on retained samples (~20k x a few dozen bytes). Reaching
+ * it means sustained >22 req/s for a full 15 minutes; past that the OLDEST
+ * samples are evicted and the affected windows report `complete: false` rather
+ * than quietly under-reporting.
+ */
+declare const THROUGHPUT_SAMPLE_LIMIT = 20000;
+/** Windows every snapshot reports, shortest first. The last must be <= retention. */
+declare const THROUGHPUT_WINDOWS_MS: readonly [60000, 300000, 900000];
+/** Trend-series resolution: 30 buckets across the retention horizon (30s each). */
+declare const THROUGHPUT_BUCKET_COUNT = 30;
+/**
+ * One recorded request's contribution. Structurally satisfied by the recorder's
+ * `UsageEventInput` row, so the daemon can forward it verbatim.
+ */
+interface UsageThroughputInput {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    /** Epoch-ms of the event. Omit to use the `now` argument. */
+    ts?: number;
+}
+/** Aggregates + rates for one trailing window. */
+interface UsageThroughputWindow {
+    /** Trailing window this row covers, in ms. */
+    windowMs: number;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    /** input + output + cacheRead + cacheCreation (reasoning is a subset of output). */
+    totalTokens: number;
+    costUsd: number;
+    requestsPerMinute: number;
+    /** The headline TPM: `totalTokens` per minute over `windowMs`. */
+    tokensPerMinute: number;
+    inputTokensPerMinute: number;
+    outputTokensPerMinute: number;
+    costUsdPerMinute: number;
+    /**
+     * False when the sample cap evicted events that fall inside this window, so
+     * every figure above is a LOWER BOUND rather than an exact count.
+     */
+    complete: boolean;
+}
+/** One fixed-width bucket of the trend series. */
+interface UsageThroughputBucket {
+    /** Epoch-ms of the bucket's (grid-aligned) start. */
+    startTs: number;
+    requests: number;
+    tokens: number;
+}
+/** The `GET /admin/api/usage/throughput` payload. */
+interface UsageThroughputSnapshot {
+    /** Always true here; the UI's fallback shape uses `false` for older daemons. */
+    available: true;
+    collectedAt: number;
+    /** Epoch-ms this tracker began observing (effectively the daemon's start). */
+    startedAt: number;
+    retentionMs: number;
+    /** Width of one `buckets` entry, in ms. */
+    bucketMs: number;
+    /** One row per {@link THROUGHPUT_WINDOWS_MS} entry, shortest window first. */
+    windows: UsageThroughputWindow[];
+    /**
+     * Oldest to newest, exactly {@link THROUGHPUT_BUCKET_COUNT} entries covering
+     * `retentionMs` on a `bucketMs` grid. Empty buckets are present and zeroed;
+     * the final bucket is still in progress. Grid alignment (rather than
+     * "now minus retention") keeps boundaries stable between polls so a sparkline
+     * does not shimmer.
+     */
+    buckets: UsageThroughputBucket[];
+}
+declare class UsageThroughputTracker {
+    private samples;
+    /** Index of the oldest live sample; slots before it are consumed. */
+    private head;
+    private readonly startedAt;
+    /** Newest ts dropped by the sample CAP (not by retention). Null when none. */
+    private evictedThroughTs;
+    constructor(now?: number);
+    /** Record one served request. O(1) amortised; never touches disk. */
+    record(input: UsageThroughputInput, now?: number): void;
+    /** Aggregate every reported window plus the shared trend series. */
+    snapshot(now?: number): UsageThroughputSnapshot;
+    /** Drop all samples (tests / teardown). `startedAt` is unchanged. */
+    clear(): void;
+    /**
+     * Drop samples past the retention horizon, then enforce the sample cap.
+     *
+     * Retention pruning uses the CALLER's `now`, which is never later than a
+     * subsequent snapshot's `now`, so it can only ever keep MORE than the widest
+     * window needs — it can never shave data off the 15-minute window.
+     */
+    private prune;
+    private window;
+    private buckets;
+}
+declare function getSharedUsageThroughputTracker(): UsageThroughputTracker;
+/**
+ * TEST SEAM — swap the singleton (e.g. with a fixed-clock instance). Mirrors the
+ * `setShared…`/`__reset…ForTests` discipline of the sibling in-memory stores.
+ */
+declare function setSharedUsageThroughputTracker(instance: UsageThroughputTracker): void;
+declare function __resetSharedUsageThroughputTrackerForTests(): void;
+
+export { THROUGHPUT_BUCKET_COUNT, THROUGHPUT_RETENTION_MS, THROUGHPUT_SAMPLE_LIMIT, THROUGHPUT_WINDOWS_MS, type UsageThroughputBucket, type UsageThroughputInput, type UsageThroughputSnapshot, UsageThroughputTracker, type UsageThroughputWindow, __resetSharedUsageThroughputTrackerForTests, getSharedUsageThroughputTracker, setSharedUsageThroughputTracker };

package/dist/usage.js

@@ -1,12 +1,29 @@
-import "./chunk-7VU7V2E4.js";
+import {
+  THROUGHPUT_BUCKET_COUNT,
+  THROUGHPUT_RETENTION_MS,
+  THROUGHPUT_SAMPLE_LIMIT,
+  THROUGHPUT_WINDOWS_MS,
+  UsageThroughputTracker,
+  __resetSharedUsageThroughputTrackerForTests,
+  getSharedUsageThroughputTracker,
+  setSharedUsageThroughputTracker
+} from "./chunk-6D4W22P4.js";
 import {
   PricingEngine
 } from "./chunk-FXR6N3SR.js";
 import {
   UsageRecorder
-} from "./chunk-UAPBLNN2.js";
+} from "./chunk-AQDON6MB.js";
 import "./chunk-OZFM4X3S.js";
 export {
   PricingEngine,
-  UsageRecorder
+  THROUGHPUT_BUCKET_COUNT,
+  THROUGHPUT_RETENTION_MS,
+  THROUGHPUT_SAMPLE_LIMIT,
+  THROUGHPUT_WINDOWS_MS,
+  UsageRecorder,
+  UsageThroughputTracker,
+  __resetSharedUsageThroughputTrackerForTests,
+  getSharedUsageThroughputTracker,
+  setSharedUsageThroughputTracker
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@omnicross/core",
-  "version": "0.1.8",
-  "description": "Omnicross LLM serving core 鈥?provider dispatch, completion pipeline, transformers, and the provider proxy.",
+  "version": "0.1.10",
+  "description": "Omnicross LLM serving core — provider dispatch, completion pipeline, transformers, and the provider proxy.",
   "license": "MIT",
   "author": "Sayo (https://github.com/Dumoedss)",
   "homepage": "https://github.com/Dumoedss/omnicross#readme",

package/dist/chunk-FZ46M34D.cjs

@@ -1 +0,0 @@
-"use strict";