@omnicross/core 0.1.9 → 0.2.0

package/dist/usage.d.ts

@@ -6,3 +6,157 @@ 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;
+    /** `totalTokens` per minute over `windowMs`. */
+    tokensPerMinute: number;
+    inputTokensPerMinute: number;
+    outputTokensPerMinute: number;
+    /** cacheRead + cacheCreation per minute over `windowMs`. */
+    cacheTokensPerMinute: 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;
+    /** input + output + cacheRead + cacheCreation (same basis as `totalTokens`). */
+    tokens: number;
+    /** Output tokens alone, so a card headlining output can trend in step. */
+    outputTokens: 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-QIIAMBTM.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,64 +1,69 @@
-{
-  "name": "@omnicross/core",
-  "version": "0.1.9",
-  "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",
-  "keywords": [
-    "omnicross",
-    "llm",
-    "openai",
-    "anthropic",
-    "gemini",
-    "proxy",
-    "router",
-    "completion",
-    "transformer"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Dumoedss/omnicross.git",
-    "directory": "packages/core"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js",
-      "require": "./dist/*.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "LICENSE",
-    "NOTICE",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
-  },
-  "dependencies": {
-    "@mozilla/readability": "^0.6.0",
-    "@omnicross/contracts": "^0.1.0",
-    "jsdom": "^24.1.3",
-    "socks": "^2.8.3",
-    "turndown": "^7.2.2",
-    "undici": "^6.21.1"
-  }
-}
+{
+  "name": "@omnicross/core",
+  "version": "0.2.0",
+  "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",
+  "keywords": [
+    "omnicross",
+    "llm",
+    "openai",
+    "anthropic",
+    "gemini",
+    "proxy",
+    "router",
+    "completion",
+    "transformer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DumoeDss/omnicross",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9"
+  },
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "@omnicross/contracts": "^0.2.0",
+    "busboy": "^1.6.0",
+    "jsdom": "^24.1.3",
+    "sharp": "^0.35.4",
+    "socks": "^2.8.3",
+    "turndown": "^7.2.2",
+    "undici": "^6.28.0"
+  },
+  "devDependencies": {
+    "@types/busboy": "^1.5.4"
+  }
+}

package/dist/chunk-7C7DET6S.js

@@ -1,154 +0,0 @@
-import {
-  redactAuditText
-} from "./chunk-K5NM7VAH.js";
-import {
-  getAuditCaptureConfig,
-  recordAudit
-} from "./chunk-WNY4WMRF.js";
-import {
-  readAuditUsage
-} from "./chunk-OZFM4X3S.js";
-
-// src/outbound-api/auditCapture.ts
-import { randomUUID } from "crypto";
-function completeUtf8PrefixLength(buf) {
-  if (buf.length === 0) return 0;
-  let leadIndex = buf.length - 1;
-  while (leadIndex >= 0 && (buf[leadIndex] & 192) === 128) leadIndex -= 1;
-  if (leadIndex < 0) return 0;
-  const lead = buf[leadIndex];
-  let expectedLength = 1;
-  if ((lead & 224) === 192) expectedLength = 2;
-  else if ((lead & 240) === 224) expectedLength = 3;
-  else if ((lead & 248) === 240) expectedLength = 4;
-  return buf.length - leadIndex < expectedLength ? leadIndex : buf.length;
-}
-function truncateToBytes(text, maxBytes) {
-  if (maxBytes < 0) return text;
-  const buf = Buffer.from(text, "utf8");
-  if (buf.length <= maxBytes) return text;
-  const head = buf.subarray(0, maxBytes);
-  return head.subarray(0, completeUtf8PrefixLength(head)).toString("utf8");
-}
-function decodeCapturedBody(body, truncated) {
-  if (!truncated) return body.toString("utf8");
-  return body.subarray(0, completeUtf8PrefixLength(body)).toString("utf8");
-}
-function resolveClientIp(req, trustForwardedFor) {
-  if (trustForwardedFor) {
-    const xff = req.headers["x-forwarded-for"];
-    const raw = Array.isArray(xff) ? xff[0] : xff;
-    if (typeof raw === "string" && raw.trim()) {
-      const first = raw.split(",")[0]?.trim();
-      if (first) return first;
-    }
-  }
-  return req.socket?.remoteAddress ?? void 0;
-}
-function beginAuditCapture(req, res, now) {
-  const config = getAuditCaptureConfig();
-  if (!config) return null;
-  let requestBody;
-  const responseChunks = [];
-  let responseBytes = 0;
-  let responseTruncated = false;
-  let finished = false;
-  const ctx = {
-    setRequestBody(raw) {
-      if (config.captureBodies) {
-        requestBody = truncateToBytes(redactAuditText(raw), config.maxBodyBytes);
-      }
-    }
-  };
-  if (config.captureBodies) {
-    installResponseCapture(res, {
-      push(chunk) {
-        if (config.maxBodyBytes < 0) {
-          responseChunks.push(chunk);
-          responseBytes += chunk.length;
-          return;
-        }
-        const remaining = config.maxBodyBytes - responseBytes;
-        if (remaining <= 0) {
-          responseTruncated = true;
-          return;
-        }
-        if (chunk.length > remaining) {
-          responseChunks.push(chunk.subarray(0, remaining));
-          responseBytes += remaining;
-          responseTruncated = true;
-          return;
-        }
-        responseChunks.push(chunk);
-        responseBytes += chunk.length;
-      }
-    });
-  }
-  const finalize = () => {
-    if (finished) return;
-    finished = true;
-    try {
-      const record = {
-        id: randomUUID(),
-        ts: now,
-        method: req.method ?? "",
-        path: (req.url ?? "").split("?")[0] ?? "",
-        status: res.statusCode,
-        latencyMs: Math.max(0, Date.now() - now)
-      };
-      if (ctx.keyId != null) record.keyId = ctx.keyId;
-      const ip = resolveClientIp(req, config.trustForwardedFor);
-      if (ip) record.ip = ip;
-      const ua = req.headers["user-agent"];
-      if (typeof ua === "string" && ua) record.ua = ua;
-      if (ctx.model) record.model = ctx.model;
-      if (ctx.provider) record.provider = ctx.provider;
-      const usage = readAuditUsage(res);
-      if (usage) {
-        if (typeof usage.inputTokens === "number") record.inputTokens = usage.inputTokens;
-        if (typeof usage.outputTokens === "number") record.outputTokens = usage.outputTokens;
-        if (typeof usage.costUsd === "number") record.costUsd = usage.costUsd;
-        if (!record.model && usage.model) record.model = usage.model;
-        if (!record.provider && usage.provider) record.provider = usage.provider;
-      }
-      if (ctx.error) record.error = redactAuditText(ctx.error);
-      if (config.captureBodies) {
-        if (requestBody != null && requestBody.length > 0) {
-          record.requestBody = requestBody;
-        }
-        if (responseChunks.length > 0) {
-          const captured = Buffer.concat(responseChunks, responseBytes);
-          const body = decodeCapturedBody(captured, responseTruncated);
-          record.responseBody = truncateToBytes(redactAuditText(body), config.maxBodyBytes);
-        }
-      }
-      recordAudit(record);
-    } catch {
-    }
-  };
-  res.once("close", finalize);
-  return ctx;
-}
-function installResponseCapture(res, sink) {
-  const capture = (chunk) => {
-    let buf = null;
-    if (Buffer.isBuffer(chunk)) buf = chunk;
-    else if (typeof chunk === "string") buf = Buffer.from(chunk, "utf8");
-    if (!buf || buf.length === 0) return;
-    sink.push(buf);
-  };
-  const originalWrite = res.write.bind(res);
-  const originalEnd = res.end.bind(res);
-  res.write = ((chunk, ...args) => {
-    if (chunk != null) capture(chunk);
-    return originalWrite(chunk, ...args);
-  });
-  res.end = ((chunk, ...args) => {
-    if (chunk != null && typeof chunk !== "function") capture(chunk);
-    return originalEnd(chunk, ...args);
-  });
-}
-
-export {
-  beginAuditCapture
-};

package/dist/chunk-EYZYXJTJ.cjs

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

package/dist/chunk-FCR77GYM.cjs

@@ -1,33 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/outbound-api/auditRedact.ts
-var AUDIT_REDACTED = "***REDACTED***";
-var RULES = [
-  // `sk-…` family (Anthropic sk-ant-, omnicross sk-omnicross-, OpenAI sk-proj-/sk-).
-  { re: /\bsk-[A-Za-z0-9_-]{6,}/g, replace: AUDIT_REDACTED },
-  // Google API keys.
-  { re: /\bAIza[A-Za-z0-9_-]{10,}/g, replace: AUDIT_REDACTED },
-  // `Bearer <token>` (auth headers echoed into a body / SSE error).
-  { re: /\bBearer\s+[A-Za-z0-9._~+/=-]{6,}/gi, replace: `Bearer ${AUDIT_REDACTED}` },
-  // Inline `x-api-key` / `api-key` / `authorization` label followed by a value.
-  {
-    re: /\b(x-api-key|api[_-]?key|authorization)(["']?\s*[:=]\s*["']?)[A-Za-z0-9._~+/=-]{6,}/gi,
-    replace: `$1$2${AUDIT_REDACTED}`
-  },
-  // `x-goog-api-key` header echoed inline.
-  {
-    re: /\b(x-goog-api-key)(["']?\s*[:=]\s*["']?)[A-Za-z0-9._~+/=-]{6,}/gi,
-    replace: `$1$2${AUDIT_REDACTED}`
-  }
-];
-function redactAuditText(text) {
-  if (typeof text !== "string" || text.length === 0) return _nullishCoalesce(text, () => ( ""));
-  let out = text;
-  for (const { re, replace } of RULES) {
-    out = out.replace(re, replace);
-  }
-  return out;
-}
-
-
-
-
-exports.AUDIT_REDACTED = AUDIT_REDACTED; exports.redactAuditText = redactAuditText;

package/dist/chunk-K5NM7VAH.js

@@ -1,33 +0,0 @@
-// src/outbound-api/auditRedact.ts
-var AUDIT_REDACTED = "***REDACTED***";
-var RULES = [
-  // `sk-…` family (Anthropic sk-ant-, omnicross sk-omnicross-, OpenAI sk-proj-/sk-).
-  { re: /\bsk-[A-Za-z0-9_-]{6,}/g, replace: AUDIT_REDACTED },
-  // Google API keys.
-  { re: /\bAIza[A-Za-z0-9_-]{10,}/g, replace: AUDIT_REDACTED },
-  // `Bearer <token>` (auth headers echoed into a body / SSE error).
-  { re: /\bBearer\s+[A-Za-z0-9._~+/=-]{6,}/gi, replace: `Bearer ${AUDIT_REDACTED}` },
-  // Inline `x-api-key` / `api-key` / `authorization` label followed by a value.
-  {
-    re: /\b(x-api-key|api[_-]?key|authorization)(["']?\s*[:=]\s*["']?)[A-Za-z0-9._~+/=-]{6,}/gi,
-    replace: `$1$2${AUDIT_REDACTED}`
-  },
-  // `x-goog-api-key` header echoed inline.
-  {
-    re: /\b(x-goog-api-key)(["']?\s*[:=]\s*["']?)[A-Za-z0-9._~+/=-]{6,}/gi,
-    replace: `$1$2${AUDIT_REDACTED}`
-  }
-];
-function redactAuditText(text) {
-  if (typeof text !== "string" || text.length === 0) return text ?? "";
-  let out = text;
-  for (const { re, replace } of RULES) {
-    out = out.replace(re, replace);
-  }
-  return out;
-}
-
-export {
-  AUDIT_REDACTED,
-  redactAuditText
-};