@omnicross/core 0.1.9 → 0.2.0

package/dist/{types-C2MwkLah.d.cts → types-jjU24eYG.d.cts}

@@ -1,3 +1,4 @@
+import { e as ImageApiLimits } from './types-CbglB73l.cjs';
 import { ProxyConfig } from '@omnicross/contracts/account-tokens-types';
 import { AuditConfig } from '@omnicross/contracts/audit-types';
 import { BillingConfig } from '@omnicross/contracts/billing-types';
@@ -6,11 +7,49 @@ import { VoucherRecord, VoucherGrant, VoucherInfo, VoucherConfig } from '@omnicr
 import { WebhookConfig } from '@omnicross/contracts/webhook-types';
 import { L as Logger } from './logger-4GvQNzhE.cjs';
 import { ProviderConfigSource } from './ports/provider-config-source.cjs';
-import { P as ProviderProxy } from './ProviderProxy-QdwNV6l1.cjs';
-import { ProviderProxyDeps } from './provider-proxy/types.cjs';
+import { P as ProviderProxy } from './ProviderProxy-CgIcCVwk.cjs';
+import { W as ProviderProxyDeps } from './types-DsHBBk3h.cjs';
 import { BoundAccountFallbackPolicy } from './pipeline/BoundAccountSelectionError.cjs';
 import { c as KeySpend } from './keyPolicy-zdWTu3CQ.cjs';
 
+/**
+ * anthropicCountTokens — the `POST /v1/messages/count_tokens` handler
+ * (`claude-api-routing-errors`, R2 passthrough+reject subset).
+ *
+ * Before this module, the substring `/v1/messages` match routed count_tokens
+ * into the FULL generation pipeline — every context-stats call burned a real
+ * upstream inference (BYO money, subscription 5h-window quota) and returned a
+ * Message JSON instead of `{"input_tokens":N}` (audit F-1, P0).
+ *
+ * Strategies (portfolio-locked default: `'auto'`):
+ *  - **passthrough** (Anthropic-wire upstream — `plan.sameFormat`): strip the
+ *    generation-only fields the count_tokens endpoint rejects (`stream`,
+ *    `max_tokens`), rewrite `model` to the resolved upstream model, and POST to
+ *    `<upstream>/v1/messages/count_tokens` via the SAME same-format fetches the
+ *    generation path uses (credential injection, beta merge, claude header
+ *    baseline all inherited). The response — success OR failure — relays
+ *    verbatim with its real status (an Anthropic-wire error body already IS
+ *    the official shape; wrapping it would violate the verbatim moat).
+ *  - **estimate** (Change B; explicit config, or `auto` on a translation
+ *    upstream): a PURE-LOCAL heuristic estimate (`anthropicCountEstimate.ts`)
+ *    answered as `{"input_tokens":N}` with the `x-omnicross-count-estimate:
+ *    true` marker header — zero upstream calls, never recorded as usage.
+ *  - **reject** (explicit config, or `passthrough` degraded on a translation
+ *    upstream): a clean Anthropic 404 `not_found_error` with ZERO upstream
+ *    calls — Claude Code treats it as "endpoint absent" and falls back to its
+ *    local usage estimation.
+ *
+ * A free endpoint: no usage recording, no concurrency gate (the outbound face
+ * bypasses its gate before dispatch), single attempt — no 401 refresh retry,
+ * no subscription health marking (a failed count_tokens must not cool an
+ * account that serves inference; the inference path drives those itself).
+ *
+ * @module provider-proxy/ingress/anthropicCountTokens
+ */
+
+/** The operator-facing strategy config (§10 `anthropic.countTokens.mode`). */
+type CountTokensMode = 'auto' | 'passthrough' | 'estimate' | 'reject';
+
 /**
  * keySpendTracker — a cheap in-memory per-key accumulated-spend cache
  * (`outbound-key-policy`, design D3).
@@ -201,23 +240,56 @@ interface VoucherDb {
     voucherList(): Promise<VoucherRecord[]>;
 }
 
-/**
- * Shared contract types for the outbound API server (`outbound-api-server`).
- *
- * The outbound server is a SEPARATE long-lived HTTP listener (distinct from the
- * resident loopback `ProviderProxy`) that authenticates external callers via
- * named API keys and routes their requests through the EXISTING `provider-proxy`
- * ingress parsers + transformer — there is exactly one conversion stack.
- *
- * These types are kept in their own module so the server, router, auth, rate
- * limiter, role detection, and route resolver can share shapes without circular
- * imports.
- *
- * @module outbound-api/types
- */
-
 /** The four endpoints, 1:1 with the four wire-format ingress parsers. */
 type OutboundEndpoint = 'chat' | 'responses' | 'messages' | 'gemini';
+/** Named-key authorization vocabulary. Images is deliberately not a text route. */
+type OutboundPermission = OutboundEndpoint | 'images';
+interface ImagesServerConfig {
+    enabled: boolean;
+    provider: 'codex-subscription';
+    defaultModel: string;
+    modelAliases: Record<string, string>;
+    account: {
+        id?: string;
+        group?: string;
+        fallback: 'strict' | 'pool';
+    };
+    queue: {
+        maxConcurrentJobsPerAccount: number;
+        maxQueuedJobs: number;
+        queueTimeoutMs: number;
+        generationTimeoutMs: number;
+    };
+    temporary: {
+        maxActiveScopes: number;
+        maxTotalBytes: number;
+        maxTenantBytes: number;
+        staleAfterMs: number;
+        cleanupIntervalMs: number;
+    };
+    limits: ImageApiLimits;
+    references: {
+        ttlMs: number;
+        maxArtifactBytes: number;
+        maxTotalBytes: number;
+        maxTenantBytes: number;
+        maxEntries: number;
+        maxCalls: number;
+        maxResponses: number;
+        maxTombstones: number;
+        tombstoneTtlMs: number;
+        cleanupIntervalMs: number;
+        storageRoot?: string;
+    };
+    remote: {
+        enabled: boolean;
+    };
+    evidenceTtlMs: number;
+}
+/** Non-consuming, account-bound image model discovery injected by the daemon. */
+interface ImageModelCatalogReader {
+    listAvailableModels(apiKeyId: string): Promise<readonly string[]>;
+}
 /** A `"providerId,modelId"` model reference (mirrors `RouterConfig` vocab). */
 type ModelRef = string;
 /** The detected request role; precedence background > default. */
@@ -513,6 +585,69 @@ interface FingerprintConfig {
     /** Operator UA baseline for un-captured accounts (piece 4). Absent ⇒ none. */
     ua?: string;
 }
+/**
+ * count_tokens strategy mode (§10 `anthropic.countTokens.mode`). ONE canonical
+ * union lives with the handler (`provider-proxy/ingress/anthropicCountTokens`);
+ * this alias re-exports it so the config-segment types and the runtime
+ * resolver can never drift apart (review B-M2).
+ */
+type AnthropicCountTokensMode = CountTokensMode;
+/** `GET /v1/models` response shape selector (§10 `anthropic.modelsShape`). */
+type AnthropicModelsShape = 'auto' | 'anthropic' | 'openai';
+/**
+ * Anthropic-protocol tuning segment (`claude-api-protocol-fidelity`, §10
+ * skeleton — count_tokens strategy/budget, /v1/models shape, synthetic-SSE
+ * heartbeat). Persisted + normalized like the other segments; read live per
+ * request (count_tokens/models) or hot-applied via the module setter
+ * (heartbeat). `proxyOauthUsage` / `apiHello` land in the follow-up change.
+ */
+interface AnthropicConfigSegment {
+    /**
+     * `/v1/messages/count_tokens` strategy. `mode` absent ⇒ `'auto'`
+     * (Anthropic-wire upstream → passthrough; translation upstream → local
+     * estimate). `estimateBudgetMs` bounds the local estimator walk (default
+     * 2000; a pathological input degrades to a coarser estimate, never fails).
+     */
+    countTokens?: {
+        mode?: AnthropicCountTokensMode;
+        estimateBudgetMs?: number;
+    };
+    /**
+     * `GET /v1/models` response shape. `'auto'` (default): a key authorized for
+     * the messages endpoint gets the Anthropic list shape, everyone else keeps
+     * the OpenAI shape; `'anthropic'` / `'openai'` force one shape (escape
+     * hatch for dual-protocol consumers).
+     */
+    modelsShape?: AnthropicModelsShape;
+    /**
+     * Synthetic-SSE ping heartbeat interval (ms) for the TRANSLATION path only.
+     * Default 20000; ≤0 disables. Hot-applied at `applyConfig` — in-flight
+     * streams pick the new value at their next timer arm.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Translate-path PDF text extraction budget (`claude-api-transform-fidelity`,
+     * R7). `budgetMs` default 2000 — bounds the synchronous zero-dependency
+     * text-layer walk; over-budget documents 400 explicitly (never silently
+     * dropped, never unbounded work).
+     */
+    pdfTextExtraction?: {
+        budgetMs?: number;
+    };
+    /**
+     * Serve `GET /api/oauth/usage` on the outbound listener as a PURE-CACHE read
+     * of the shared Claude allowance store (R9). Default FALSE — off, the path
+     * keeps its current generic 404 byte-for-byte. When on, a messages-authorized
+     * key bound to a Claude subscription receives the api.anthropic.com usage
+     * wire shape; NO upstream call or refresh is ever triggered by the query.
+     */
+    proxyOauthUsage?: boolean;
+    /**
+     * Answer `HEAD /api/hello` with a bare 200 at the listener level (R10 —
+     * clients probe "can this endpoint be safely rejected"). Default TRUE.
+     */
+    apiHello?: boolean;
+}
 /**
  * Layered upstream-proxy segment (upstream-proxy). Global + per-provider proxy
  * config for outbound EGRESS to upstreams (NOT the inbound listener). Resolved
@@ -627,6 +762,14 @@ interface OutboundApiServerConfig {
      * byte-identical zero regression, purely additive on the #4 key-policy.
      */
     voucher?: VoucherConfig;
+    /**
+     * Anthropic-protocol tuning segment (claude-api-protocol-fidelity, §10).
+     * Optional in the persisted shape; `normalizeServerConfig` always fills it
+     * with the frozen defaults (auto/auto/20000).
+     */
+    anthropic?: AnthropicConfigSegment;
+    /** Default-off Images serving policy; capability still requires fresh evidence. */
+    images?: ImagesServerConfig;
 }
 /** A live status snapshot the Settings tab renders. */
 interface OutboundApiServerStatus {
@@ -641,6 +784,15 @@ interface OutboundApiServerStatus {
     formats: OutboundFormatUrls | null;
     /** The four format endpoint URLs over the LAN (only when network binding on). */
     lanFormats: OutboundFormatUrls | null;
+    /** Additive Images endpoints; absent while Images is disabled. */
+    images?: {
+        generations: string;
+        edits: string;
+    } | null;
+    lanImages?: {
+        generations: string;
+        edits: string;
+    } | null;
 }
 /** The four format endpoint URLs for one base. */
 interface OutboundFormatUrls {
@@ -667,8 +819,10 @@ interface OutboundApiKeyInfo {
     revoked: boolean;
     /** Intended consumer. Existing rows default to a general client key. */
     kind?: 'client' | 'integration';
-    /** Optional endpoint allow-list. Absent means every outbound endpoint. */
-    allowedEndpoints?: OutboundEndpoint[];
+    /** Exact effective permission list; legacy absent rows project to text-only permissions. */
+    allowedEndpoints: OutboundPermission[];
+    /** True when the stored row omitted permissions and compatibility defaults were projected. */
+    legacyPermissions: boolean;
     /** When true the key is rejected unless the TCP peer is loopback. */
     loopbackOnly?: boolean;
     /**
@@ -746,6 +900,8 @@ interface OutboundApiKeyCreated {
     name: string;
     keyPrefix: string;
     createdAt: number;
+    /** Exact effective permission list assigned to the new key. */
+    allowedEndpoints: OutboundPermission[];
     plaintextOnce: string;
 }
 /**
@@ -773,8 +929,8 @@ interface OutboundKeyDbRow {
     revokedAt: number | null;
     /** Intended consumer. Existing rows without this field remain client keys. */
     kind?: 'client' | 'integration';
-    /** Optional endpoint allow-list for least-privilege integration keys. */
-    allowedEndpoints?: OutboundEndpoint[];
+    /** Persisted exact permission list. Absent is a legacy text-only row. */
+    allowedEndpoints?: OutboundPermission[];
     /** Restrict use to requests whose direct socket peer is loopback. */
     loopbackOnly?: boolean;
     /**
@@ -817,7 +973,7 @@ interface OutboundKeyDb {
         keyPrefix: string;
         createdAt?: number;
         kind?: 'client' | 'integration';
-        allowedEndpoints?: OutboundEndpoint[];
+        allowedEndpoints?: OutboundPermission[];
         loopbackOnly?: boolean;
         /**
          * The generated plaintext secret. When the DB holds a `SecretBox` it
@@ -831,6 +987,8 @@ interface OutboundKeyDb {
     outboundApiKeysRevoke(id: string): Promise<boolean>;
     outboundApiKeysTouchLastUsed(id: string): Promise<boolean>;
     outboundApiKeysSetEnabled(id: string, enabled: boolean): Promise<boolean>;
+    /** Atomically replace the exact key permission list. */
+    outboundApiKeysSetPermissions(id: string, permissions: OutboundPermission[]): Promise<boolean>;
     /**
      * Set (or clear) a key's per-key concurrency ceiling. `null` clears the field
      * → unlimited (gate bypassed). Mirrors `outboundApiKeysSetEnabled`; returns
@@ -890,6 +1048,8 @@ interface OutboundApiDeps {
     readonly providerProxy: ProviderProxy;
     /** The proxy's app-session deps (reused verbatim for `routeRequest`). */
     readonly proxyDeps: ProviderProxyDeps;
+    /** Optional fail-closed Images catalog; absent means no image model is advertised. */
+    readonly imageModelCatalog?: ImageModelCatalogReader;
     /**
      * OPTIONAL unauthenticated `/health` provider (daemon-health-endpoint, D1
      * secondary mount). When wired (by the daemon bootstrap — core NEVER imports
@@ -917,4 +1077,4 @@ interface OutboundApiDeps {
     readonly logger?: Logger;
 }
 
-export { type AccountProbeConfig as A, computeVoucherGrant as B, type ChatDispatchMode as C, generateVoucherCode as D, ENDPOINT_MODEL_KINDS as E, type FingerprintConfig as F, type GatewayBinding as G, hashVoucherCode as H, newVoucherId as I, startOfLocalDay as J, type KeySpendReader as K, startOfLocalWeek as L, type MessagesModelKind as M, toVoucherInfo as N, type OutboundKeyDb as O, voucherCodePrefix as P, type ModelRef as Q, type RequestRole as R, type AccountHealthConfig as S, type OutboundKeyModelRestrictionMode as T, type UserMessageQueueConfig as U, type VoucherCreateInput as V, type AllowanceSchedulingConfig as a, type ConcurrencyQueueConfig as b, type EndpointRoutingConfig as c, type GatewayBindingFallback as d, type GatewayBindingKeyScope as e, type GatewayBindingModelMode as f, type GatewayBindingTarget as g, type GatewayModelMapping as h, type KeySpendSeeder as i, KeySpendTracker as j, type KindMappedEndpoint as k, type ModelKind as l, type ModelPrefixTargets as m, type OutboundApiDeps as n, type OutboundApiKeyCreated as o, type OutboundApiKeyInfo as p, type OutboundApiServerConfig as q, type OutboundApiServerStatus as r, type OutboundEndpoint as s, type OutboundFormatUrls as t, type OutboundKeyActivationMode as u, type OutboundKeyDbRow as v, type OutboundKeyPolicy as w, type OutboundProxyConfig as x, type ResponsesModelKind as y, type VoucherDb as z };
+export { type OutboundKeyModelRestrictionMode as $, type AccountProbeConfig as A, type VoucherDb as B, type ChatDispatchMode as C, computeVoucherGrant as D, ENDPOINT_MODEL_KINDS as E, type FingerprintConfig as F, type GatewayBinding as G, generateVoucherCode as H, type ImagesServerConfig as I, hashVoucherCode as J, type KeySpendReader as K, newVoucherId as L, type MessagesModelKind as M, startOfLocalDay as N, type OutboundKeyDb as O, startOfLocalWeek as P, toVoucherInfo as Q, type RequestRole as R, voucherCodePrefix as S, type ModelRef as T, type UserMessageQueueConfig as U, type VoucherCreateInput as V, type AnthropicConfigSegment as W, type AccountHealthConfig as X, type AnthropicCountTokensMode as Y, type AnthropicModelsShape as Z, type ImageModelCatalogReader as _, type AllowanceSchedulingConfig as a, type ConcurrencyQueueConfig as b, type EndpointRoutingConfig as c, type GatewayBindingFallback as d, type GatewayBindingKeyScope as e, type GatewayBindingModelMode as f, type GatewayBindingTarget as g, type GatewayModelMapping as h, type KeySpendSeeder as i, KeySpendTracker as j, type KindMappedEndpoint as k, type ModelKind as l, type ModelPrefixTargets as m, type OutboundApiDeps as n, type OutboundApiKeyCreated as o, type OutboundApiKeyInfo as p, type OutboundApiServerConfig as q, type OutboundApiServerStatus as r, type OutboundEndpoint as s, type OutboundFormatUrls as t, type OutboundKeyActivationMode as u, type OutboundKeyDbRow as v, type OutboundKeyPolicy as w, type OutboundPermission as x, type OutboundProxyConfig as y, type ResponsesModelKind as z };

package/dist/usage/usage-recorder.cjs

@@ -1,7 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkEPN67EGPcjs = require('../chunk-EPN67EGP.cjs');
+var _chunk5UK3KLE2cjs = require('../chunk-5UK3KLE2.cjs');
 require('../chunk-XSVNC2UD.cjs');
 
 
-exports.UsageRecorder = _chunkEPN67EGPcjs.UsageRecorder;
+exports.UsageRecorder = _chunk5UK3KLE2cjs.UsageRecorder;

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

@@ -1,8 +1,8 @@
-import { PricingEngine } from './pricing-engine.cjs';
-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.cjs';
 import { UsageEventStore } from '../ports/usage-event-store.cjs';
+import { PricingEngine } from './pricing-engine.cjs';
 import '@omnicross/contracts/pricing-types';
 import '../ports/pricing-store.cjs';
 
@@ -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.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 _chunk32SRZFFPcjs = require('./chunk-32SRZFFP.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 = _chunk32SRZFFPcjs.THROUGHPUT_BUCKET_COUNT; exports.THROUGHPUT_RETENTION_MS = _chunk32SRZFFPcjs.THROUGHPUT_RETENTION_MS; exports.THROUGHPUT_SAMPLE_LIMIT = _chunk32SRZFFPcjs.THROUGHPUT_SAMPLE_LIMIT; exports.THROUGHPUT_WINDOWS_MS = _chunk32SRZFFPcjs.THROUGHPUT_WINDOWS_MS; exports.UsageRecorder = _chunk5UK3KLE2cjs.UsageRecorder; exports.UsageThroughputTracker = _chunk32SRZFFPcjs.UsageThroughputTracker; exports.__resetSharedUsageThroughputTrackerForTests = _chunk32SRZFFPcjs.__resetSharedUsageThroughputTrackerForTests; exports.getSharedUsageThroughputTracker = _chunk32SRZFFPcjs.getSharedUsageThroughputTracker; exports.setSharedUsageThroughputTracker = _chunk32SRZFFPcjs.setSharedUsageThroughputTracker;

package/dist/usage.d.cts

@@ -6,3 +6,157 @@ 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;
+    /** `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 };