@bitkyc08/opencodex 2.40.0 → 2.42.0

package/src/server/management/usage-aggregate-cache.ts

@@ -0,0 +1,464 @@
+import { enforceAppOwnedMemoryBudget } from "../../lib/app-owned-memory";
+import {
+  currentUsageLogRevision,
+  usageLogIdentityKey,
+  usageLogRevisionKey,
+  type UsageLogRevision,
+} from "../../usage/log";
+import {
+  scanUsageLedgerCooperatively,
+  UsageLedgerRebuildRequiredError,
+} from "../../usage/ledger-scanner";
+import {
+  createUsageSummaryAccumulator,
+  type UsageSummaryAccumulator,
+} from "../../usage/summary";
+import { userCostOverlayVersion } from "../../usage/user-cost-overlays";
+
+import {
+  cacheApiKeyUsageFromRollup,
+  createApiKeyUsageAccumulator,
+} from "./api-key-usage";
+
+interface RetainedUsageAggregate {
+  accumulator: UsageSummaryAccumulator;
+  revision: UsageLogRevision | null;
+  identityKey: string;
+  revisionKey: string;
+  processedThroughBytes: number;
+  processedThroughDigest: string;
+  overlayVersion: number;
+  timeZone: string;
+  retainedAt: number;
+}
+
+export interface UsageAggregateResult {
+  accumulator: UsageSummaryAccumulator;
+  revision: UsageLogRevision | null;
+  processedThroughBytes: number;
+  overlayVersion: number;
+  timeZone: string;
+  update: "unchanged" | "append" | "rebuild";
+}
+
+export interface UsageAggregateOptions {
+  now?: number;
+  configuredApiKeyIds?: string[];
+  managementUsageMaxReadBytes?: number;
+}
+
+export interface UsageAggregateRetainedStats {
+  count: number;
+  bytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  oldestAt: number | null;
+}
+
+const MAX_REBUILD_ATTEMPTS = 2;
+const MAX_RETAINED_FILTERED_AGGREGATES = 4;
+
+let retainedAggregate: RetainedUsageAggregate | null = null;
+const pinnedAggregates = new Set<RetainedUsageAggregate>();
+let baseFlight: Promise<UsageAggregateResult> | null = null;
+const filteredFlights = new Map<string, Promise<UsageAggregateResult>>();
+const retainedFilteredAggregates = new Map<string, RetainedUsageAggregate>();
+
+function currentTimeZone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+function resultFrom(
+  state: RetainedUsageAggregate,
+  update: UsageAggregateResult["update"],
+): UsageAggregateResult {
+  return {
+    accumulator: state.accumulator,
+    revision: state.revision,
+    processedThroughBytes: state.processedThroughBytes,
+    overlayVersion: state.overlayVersion,
+    timeZone: state.timeZone,
+    update,
+  };
+}
+
+function publishRetainedAggregate(state: RetainedUsageAggregate): UsageAggregateResult {
+  retainedAggregate = state;
+  // The budget may evict the state immediately. The request that built it still
+  // owns the returned accumulator and can finish this response safely.
+  enforceAppOwnedMemoryBudget();
+  return resultFrom(state, "rebuild");
+}
+
+function makeRetainedAggregate(
+  accumulator: UsageSummaryAccumulator,
+  scan: Awaited<ReturnType<typeof scanUsageLedgerCooperatively>>,
+  overlayVersion: number,
+  timeZone: string,
+): RetainedUsageAggregate {
+  return {
+    accumulator,
+    revision: scan.revision,
+    identityKey: usageLogIdentityKey(scan.revision),
+    revisionKey: usageLogRevisionKey(scan.revision),
+    processedThroughBytes: scan.processedThroughBytes,
+    processedThroughDigest: scan.processedThroughDigest,
+    overlayVersion,
+    timeZone,
+    retainedAt: Date.now(),
+  };
+}
+
+async function rebuildAggregate(options: UsageAggregateOptions): Promise<UsageAggregateResult> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_REBUILD_ATTEMPTS; attempt += 1) {
+    const overlayVersion = userCostOverlayVersion();
+    const timeZone = currentTimeZone();
+    const accumulator = createUsageSummaryAccumulator({ mode: "row-unique" });
+    const apiKeyAccumulator = options.configuredApiKeyIds
+      ? createApiKeyUsageAccumulator(options.configuredApiKeyIds, options.now)
+      : null;
+    try {
+      const scan = await scanUsageLedgerCooperatively({
+        onEntry(entry) {
+          accumulator.add(entry);
+          apiKeyAccumulator?.add(entry);
+        },
+      });
+      if (scan.oversizedRows > 0) {
+        throw new Error("usage ledger contains an oversized row");
+      }
+      if (userCostOverlayVersion() !== overlayVersion || currentTimeZone() !== timeZone) {
+        lastError = new Error("usage aggregation inputs changed during rebuild");
+        continue;
+      }
+
+      const state = makeRetainedAggregate(accumulator, scan, overlayVersion, timeZone);
+      const result = publishRetainedAggregate(state);
+      if (apiKeyAccumulator && options.configuredApiKeyIds) {
+        cacheApiKeyUsageFromRollup(
+          apiKeyAccumulator.snapshot(),
+          options.configuredApiKeyIds,
+          state.identityKey,
+          state.revision?.size ?? 0,
+          options.managementUsageMaxReadBytes,
+          options.now,
+        );
+      }
+      return result;
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof UsageLedgerRebuildRequiredError) || attempt + 1 >= MAX_REBUILD_ATTEMPTS) {
+        throw error;
+      }
+    }
+  }
+  throw lastError ?? new Error("usage aggregate rebuild did not settle");
+}
+
+function requiresRebuild(
+  state: RetainedUsageAggregate,
+  observed: UsageLogRevision | null,
+  overlayVersion: number,
+  timeZone: string,
+): boolean {
+  if (state.overlayVersion !== overlayVersion || state.timeZone !== timeZone) return true;
+  if (state.identityKey !== usageLogIdentityKey(observed)) return true;
+  if (!state.revision || !observed) return state.revision !== observed;
+  if (observed.size < state.revision.size) return true;
+  // At the same size, metadata movement cannot be an append. Rebuild so a
+  // detectable same-inode replacement/edit never extends stale counters.
+  return observed.size === state.revision.size && usageLogRevisionKey(observed) !== state.revisionKey;
+}
+
+async function appendAggregate(
+  state: RetainedUsageAggregate,
+  options: UsageAggregateOptions,
+): Promise<UsageAggregateResult> {
+  pinnedAggregates.add(state);
+  let rebuildAfterUnpin = false;
+  try {
+    // Clone first and publish only after the scanner verifies the captured
+    // suffix. A callback error, mutation, or oversized row leaves retained
+    // state byte-for-byte untouched.
+    const candidate = state.accumulator.clone();
+    const scan = await scanUsageLedgerCooperatively({
+      startAtBytes: state.processedThroughBytes,
+      expectedIdentityKey: state.identityKey,
+      expectedProcessedThroughDigest: state.processedThroughDigest,
+      onEntry: entry => candidate.add(entry),
+    });
+    if (scan.oversizedRows > 0) {
+      if (retainedAggregate === state) retainedAggregate = null;
+      throw new Error("usage ledger contains an oversized row");
+    }
+    if (userCostOverlayVersion() !== state.overlayVersion || currentTimeZone() !== state.timeZone) {
+      if (retainedAggregate === state) retainedAggregate = null;
+      rebuildAfterUnpin = true;
+    } else {
+      const next: RetainedUsageAggregate = {
+        ...state,
+        accumulator: candidate,
+        revision: scan.revision,
+        identityKey: usageLogIdentityKey(scan.revision),
+        revisionKey: usageLogRevisionKey(scan.revision),
+        processedThroughBytes: scan.processedThroughBytes,
+        processedThroughDigest: scan.processedThroughDigest,
+        retainedAt: Date.now(),
+      };
+      retainedAggregate = next;
+      enforceAppOwnedMemoryBudget();
+      return resultFrom(next, "append");
+    }
+  } catch (error) {
+    if (retainedAggregate === state) retainedAggregate = null;
+    if (error instanceof UsageLedgerRebuildRequiredError) rebuildAfterUnpin = true;
+    else throw error;
+  } finally {
+    pinnedAggregates.delete(state);
+  }
+  if (rebuildAfterUnpin) return rebuildAggregate(options);
+  throw new Error("usage aggregate append did not settle");
+}
+
+async function refreshAggregate(options: UsageAggregateOptions): Promise<UsageAggregateResult> {
+  const state = retainedAggregate;
+  if (!state) return rebuildAggregate(options);
+
+  const observed = currentUsageLogRevision();
+  const overlayVersion = userCostOverlayVersion();
+  const timeZone = currentTimeZone();
+  if (requiresRebuild(state, observed, overlayVersion, timeZone)) {
+    retainedAggregate = null;
+    return rebuildAggregate(options);
+  }
+  if (usageLogRevisionKey(observed) === state.revisionKey) return resultFrom(state, "unchanged");
+  return appendAggregate(state, options);
+}
+
+export async function getUsageAggregate(
+  options: UsageAggregateOptions = {},
+): Promise<UsageAggregateResult> {
+  if (baseFlight) return baseFlight;
+  const flight = refreshAggregate(options);
+  baseFlight = flight;
+  try {
+    return await flight;
+  } finally {
+    if (baseFlight === flight) baseFlight = null;
+  }
+}
+
+function normalizeFilterValue(value: string | null | undefined): string | null {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return normalized || null;
+}
+
+function normalizeExactFilterValue(value: string | null | undefined): string | null {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  return normalized || null;
+}
+
+export async function getFilteredUsageAggregate(filter: {
+  provider?: string | null;
+  model?: string | null;
+  apiKeyId?: string | null;
+}): Promise<UsageAggregateResult> {
+  const normalizedFilter = {
+    provider: normalizeFilterValue(filter.provider),
+    model: normalizeFilterValue(filter.model),
+    apiKeyId: normalizeExactFilterValue(filter.apiKeyId),
+  };
+  const key = JSON.stringify([
+    normalizedFilter.provider,
+    normalizedFilter.model,
+    normalizedFilter.apiKeyId,
+  ]);
+  const existing = filteredFlights.get(key);
+  if (existing) return existing;
+
+  const flight = refreshFilteredAggregate(key, normalizedFilter);
+  filteredFlights.set(key, flight);
+  try {
+    return await flight;
+  } finally {
+    if (filteredFlights.get(key) === flight) filteredFlights.delete(key);
+  }
+}
+
+type NormalizedUsageFilter = {
+  provider: string | null;
+  model: string | null;
+  apiKeyId: string | null;
+};
+
+function trimRetainedFilteredAggregates(): void {
+  while (retainedFilteredAggregates.size > MAX_RETAINED_FILTERED_AGGREGATES) {
+    const oldest = [...retainedFilteredAggregates]
+      .filter(([, state]) => !pinnedAggregates.has(state))
+      .sort(([, left], [, right]) => left.retainedAt - right.retainedAt)[0];
+    if (!oldest) return;
+    retainedFilteredAggregates.delete(oldest[0]);
+  }
+}
+
+function publishFilteredAggregate(
+  key: string,
+  state: RetainedUsageAggregate,
+  update: UsageAggregateResult["update"],
+): UsageAggregateResult {
+  retainedFilteredAggregates.set(key, state);
+  trimRetainedFilteredAggregates();
+  enforceAppOwnedMemoryBudget();
+  return resultFrom(state, update);
+}
+
+async function rebuildFilteredAggregate(
+  key: string,
+  filter: NormalizedUsageFilter,
+): Promise<UsageAggregateResult> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_REBUILD_ATTEMPTS; attempt += 1) {
+    const overlayVersion = userCostOverlayVersion();
+    const timeZone = currentTimeZone();
+    const accumulator = createUsageSummaryAccumulator({ filter, mode: "row-unique" });
+    try {
+      const scan = await scanUsageLedgerCooperatively({ onEntry: entry => accumulator.add(entry) });
+      if (scan.oversizedRows > 0) throw new Error("usage ledger contains an oversized row");
+      if (userCostOverlayVersion() !== overlayVersion || currentTimeZone() !== timeZone) {
+        lastError = new Error("usage aggregation inputs changed during filtered scan");
+        continue;
+      }
+      const state = makeRetainedAggregate(accumulator, scan, overlayVersion, timeZone);
+      return publishFilteredAggregate(key, state, "rebuild");
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof UsageLedgerRebuildRequiredError) || attempt + 1 >= MAX_REBUILD_ATTEMPTS) {
+        throw error;
+      }
+    }
+  }
+  throw lastError ?? new Error("filtered usage scan did not settle");
+}
+
+async function appendFilteredAggregate(
+  key: string,
+  state: RetainedUsageAggregate,
+  filter: NormalizedUsageFilter,
+): Promise<UsageAggregateResult> {
+  pinnedAggregates.add(state);
+  let rebuildAfterUnpin = false;
+  try {
+    const candidate = state.accumulator.clone();
+    const scan = await scanUsageLedgerCooperatively({
+      startAtBytes: state.processedThroughBytes,
+      expectedIdentityKey: state.identityKey,
+      expectedProcessedThroughDigest: state.processedThroughDigest,
+      onEntry: entry => candidate.add(entry),
+    });
+    if (scan.oversizedRows > 0) {
+      if (retainedFilteredAggregates.get(key) === state) retainedFilteredAggregates.delete(key);
+      throw new Error("usage ledger contains an oversized row");
+    }
+    if (userCostOverlayVersion() !== state.overlayVersion || currentTimeZone() !== state.timeZone) {
+      if (retainedFilteredAggregates.get(key) === state) retainedFilteredAggregates.delete(key);
+      rebuildAfterUnpin = true;
+    } else {
+      const next: RetainedUsageAggregate = {
+        ...state,
+        accumulator: candidate,
+        revision: scan.revision,
+        identityKey: usageLogIdentityKey(scan.revision),
+        revisionKey: usageLogRevisionKey(scan.revision),
+        processedThroughBytes: scan.processedThroughBytes,
+        processedThroughDigest: scan.processedThroughDigest,
+        retainedAt: Date.now(),
+      };
+      return publishFilteredAggregate(key, next, "append");
+    }
+  } catch (error) {
+    if (retainedFilteredAggregates.get(key) === state) retainedFilteredAggregates.delete(key);
+    if (error instanceof UsageLedgerRebuildRequiredError) rebuildAfterUnpin = true;
+    else throw error;
+  } finally {
+    pinnedAggregates.delete(state);
+    trimRetainedFilteredAggregates();
+  }
+  if (rebuildAfterUnpin) return rebuildFilteredAggregate(key, filter);
+  throw new Error("filtered usage append did not settle");
+}
+
+async function refreshFilteredAggregate(
+  key: string,
+  filter: NormalizedUsageFilter,
+): Promise<UsageAggregateResult> {
+  const state = retainedFilteredAggregates.get(key);
+  if (!state) return rebuildFilteredAggregate(key, filter);
+  const observed = currentUsageLogRevision();
+  const overlayVersion = userCostOverlayVersion();
+  const timeZone = currentTimeZone();
+  if (requiresRebuild(state, observed, overlayVersion, timeZone)) {
+    retainedFilteredAggregates.delete(key);
+    return rebuildFilteredAggregate(key, filter);
+  }
+  if (state.revisionKey === usageLogRevisionKey(observed)) {
+    state.retainedAt = Date.now();
+    return resultFrom(state, "unchanged");
+  }
+  return appendFilteredAggregate(key, state, filter);
+}
+
+export function usageAggregateRetainedStats(): UsageAggregateRetainedStats {
+  const states = [
+    ...(retainedAggregate ? [retainedAggregate] : []),
+    ...retainedFilteredAggregates.values(),
+  ];
+  if (states.length === 0) {
+    return { count: 0, bytes: 0, evictableBytes: 0, pinnedBytes: 0, oldestAt: null };
+  }
+  let bytes = 0;
+  let evictableBytes = 0;
+  let pinnedBytes = 0;
+  let oldestAt: number | null = null;
+  for (const state of states) {
+    const stateBytes = state.accumulator.estimatedBytes;
+    bytes += stateBytes;
+    if (pinnedAggregates.has(state)) pinnedBytes += stateBytes;
+    else {
+      evictableBytes += stateBytes;
+      oldestAt = oldestAt === null ? state.retainedAt : Math.min(oldestAt, state.retainedAt);
+    }
+  }
+  return {
+    count: states.length,
+    bytes,
+    evictableBytes,
+    pinnedBytes,
+    oldestAt,
+  };
+}
+
+export function discardRetainedUsageAggregate(): number {
+  const candidates: Array<{ key: string | null; state: RetainedUsageAggregate }> = [
+    ...(retainedAggregate && !pinnedAggregates.has(retainedAggregate)
+      ? [{ key: null, state: retainedAggregate }]
+      : []),
+    ...[...retainedFilteredAggregates]
+      .filter(([, state]) => !pinnedAggregates.has(state))
+      .map(([key, state]) => ({ key, state })),
+  ];
+  const oldest = candidates.sort((left, right) => left.state.retainedAt - right.state.retainedAt)[0];
+  if (!oldest) return 0;
+  const released = oldest.state.accumulator.estimatedBytes;
+  if (oldest.key === null) retainedAggregate = null;
+  else retainedFilteredAggregates.delete(oldest.key);
+  return released;
+}
+
+export function resetUsageAggregateCacheForTests(): void {
+  retainedAggregate = null;
+  pinnedAggregates.clear();
+  baseFlight = null;
+  filteredFlights.clear();
+  retainedFilteredAggregates.clear();
+}

package/src/server/management/usage-summary-cache.ts

@@ -6,6 +6,8 @@ export type CachedUsageSummary = UsageSummary & {
   truncatedPrefixBytes: number;
   entriesTruncated: boolean;
   entriesDropped: number;
+  snapshotWindowStart: number | null;
+  snapshotWindowEnd: number | null;
 };
 
 export interface UsageSummaryCacheEntry {
@@ -15,6 +17,8 @@ export interface UsageSummaryCacheEntry {
   maxReadBytes: number;
   /** userCostOverlayVersion() when the summary was computed; overlay edits invalidate the entry. */
   overlayVersion: number;
+  /** Local calendar zone used to build day/range buckets. */
+  timeZone: string;
   expiresAt: number;
   /** Generation freshness: ignore size/mtime until this instant. */
   freshUntil: number;

package/src/server/models-capabilities.ts

@@ -1,3 +1,5 @@
+import type { CursorEffortTable } from "../integrations/cursor-effort-table";
+
 /**
  * Extended capability advertisement for the OpenAI-shape `GET /v1/models` list.
  *
@@ -23,7 +25,8 @@ export const OPENAI_FAMILY_API_TYPES: ReadonlySet<string> = new Set(["chat_compl
  * The reasoning-effort ladder Cursor's local-agent runtime attaches to a model, keyed by the
  * model id after its last `/`. Cursor decides this from its own table rather than from the
  * gateway's `reasoning_effort` list, so the dashboard can only PREDICT it; the values here
- * mirror that table (read from the 3.18.25 bundle) and carry no Cursor behavior of their own.
+ * form the fallback mirror of the 3.18.25 table; the live table is read by
+ * `src/integrations/cursor-effort-table.ts`. These values carry no Cursor behavior of their own.
  * Null means Cursor shows no Reasoning control for the id. Distinct from
  * `src/adapters/cursor/effort-map.ts`, which maps opencodex efforts onto Cursor's *backend*
  * tiers for the outbound provider; this is what Cursor's *local* picker renders.
@@ -43,15 +46,62 @@ const CURSOR_EFFORT_FAMILIES: ReadonlyArray<{ test: RegExp; ladder: readonly str
 ];
 
 export function cursorEffortFamily(modelId: string): string[] | null {
+  const id = normalizeCursorPickerId(modelId);
+  for (const family of CURSOR_EFFORT_FAMILIES) {
+    if (family.test.test(id)) return family.ladder.length > 0 ? [...family.ladder] : null;
+  }
+  return null;
+}
+
+export interface CursorEffortPrediction {
+  ladder: string[] | null;
+  source: "bundle" | "static";
+  /** Bundle family id when one matched (e.g. "anthropic-opus-5"); null otherwise. */
+  family: string | null;
+  outputCap?: number;
+}
+
+export function normalizeCursorPickerId(modelId: string): string {
   let id = modelId.trim().toLowerCase();
   const slash = id.lastIndexOf("/");
   if (slash !== -1) id = id.slice(slash + 1);
   const at = id.indexOf("@");
   if (at !== -1) id = id.slice(0, at);
-  for (const family of CURSOR_EFFORT_FAMILIES) {
-    if (family.test.test(id)) return family.ladder.length > 0 ? [...family.ladder] : null;
+  return id;
+}
+
+/**
+ * `supportsReasoning` is what the gateway row will advertise in
+ * `capabilities.supports_reasoning`; Cursor's gemini family withholds its control when that is
+ * false (`effortRequiresReasoningCapability`). Callers that do not know the row pass nothing
+ * and get the id-only prediction.
+ */
+export function predictCursorEffort(
+  modelId: string,
+  table: CursorEffortTable | null,
+  supportsReasoning?: boolean,
+): CursorEffortPrediction {
+  const id = normalizeCursorPickerId(modelId);
+  if (table) {
+    for (const family of table.families) {
+      if (family.pattern.test(id)) {
+        if (family.requiresReasoningCapability && supportsReasoning === false) {
+          return { ladder: null, source: "bundle", family: family.id };
+        }
+        return {
+          ladder: family.ladder.length > 0 ? [...family.ladder] : null,
+          source: "bundle",
+          family: family.id,
+          ...(family.outputCap !== undefined ? { outputCap: family.outputCap } : {}),
+        };
+      }
+    }
+    if (table.bareGpt5?.pattern.test(id)) return { ladder: [...table.bareGpt5.ladder], source: "bundle", family: "gpt-5" };
+    return { ladder: null, source: "bundle", family: null };
   }
-  return null;
+  const staticLadder = cursorEffortFamily(modelId);
+  const gated = supportsReasoning === false && id.startsWith("gemini-") ? null : staticLadder;
+  return { ladder: gated, source: "static", family: null };
 }
 
 export interface ModelCapabilityInput {
@@ -64,6 +114,7 @@ export interface ModelCapabilityInput {
    * as costing more).
    */
   longContextWindow?: number;
+  maxOutputTokens?: number;
   inputModalities?: readonly string[];
 }
 
@@ -71,6 +122,7 @@ export interface ModelCapabilityFields {
   api_types: readonly string[];
   capabilities: {
     context_length?: number;
+    max_output_tokens?: number;
     /** Cursor's extended-row filter REQUIRES this to contain "text"; every route emits text. */
     output_modalities: string[];
     input_modalities?: string[];
@@ -91,13 +143,15 @@ export interface ModelCapabilityFields {
 function positiveInt(value: unknown): number | undefined {
   if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
   const floored = Math.floor(value);
-  return floored > 0 ? floored : undefined;
+  // Catalog limits are safe integers everywhere else; an unsafe finite value is a bad row.
+  return floored > 0 && Number.isSafeInteger(floored) ? floored : undefined;
 }
 
 export function modelCapabilityFields(input: ModelCapabilityInput): ModelCapabilityFields {
   const efforts = (input.reasoningEfforts ?? []).filter(effort => typeof effort === "string" && effort.length > 0);
   const contextLength = positiveInt(input.contextWindow);
   const longContextLength = positiveInt(input.longContextWindow);
+  const maxOutputTokens = positiveInt(input.maxOutputTokens);
   const hasLongTier = contextLength !== undefined && longContextLength !== undefined && longContextLength > contextLength;
   const modalities = Array.isArray(input.inputModalities)
     ? input.inputModalities.filter(modality => typeof modality === "string" && modality.length > 0)
@@ -109,6 +163,7 @@ export function modelCapabilityFields(input: ModelCapabilityInput): ModelCapabil
       ...(hasLongTier
         ? { context_length: longContextLength }
         : contextLength !== undefined ? { context_length: contextLength } : {}),
+      ...(maxOutputTokens !== undefined ? { max_output_tokens: maxOutputTokens } : {}),
       // Once a gateway advertises api_types, Cursor keeps only rows whose output_modalities
       // include "text"; omitting the key drops the row from the extended catalog.
       output_modalities: ["text"],