@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/quota/reset-notify-config.ts

@@ -0,0 +1,162 @@
+/**
+ * Read-time resolution of the optional quotaResetNotify config section.
+ *
+ * Cached, because loadConfig is a readFileSync plus a full configSchema.safeParse with no
+ * memoization and the enable check runs once per pooled response — a config parse per request
+ * for a feature nobody enabled.
+ *
+ * Keyed on the config file's mtime and size, NOT on captureConfigGeneration. The generation
+ * counter only advances when state-store reconciliation runs
+ * (src/lib/state-store-sweeper.ts:149, reached from reconcileLiveStateStores on
+ * account/provider changes), so editing quotaResetNotify alone would never bump it and the
+ * cached answer would stay stale until an unrelated account edit happened to occur. A short
+ * TTL bounds the stat call so the hot path does not stat on every single write.
+ */
+
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "../config";
+import { getConfigDir } from "../config/paths";
+import type { QuotaResetKind } from "./reset-detector";
+
+export type ResolvedQuotaResetNotify = {
+  readonly enabled: boolean;
+  readonly kinds: ReadonlySet<QuotaResetKind>;
+  /** 0 means passive-only: observe live refreshes, never poll. */
+  readonly pollMs: number;
+  readonly webhookUrl?: string;
+  readonly allowPrivateNetwork: boolean;
+  readonly timeoutMs: number;
+  readonly command?: readonly string[];
+};
+
+const ALL_KINDS: ReadonlySet<QuotaResetKind> = new Set(["scheduled", "surprise"]);
+const DEFAULT_POLL_SECONDS = 900;
+/**
+ * Matches MIN_INTERVAL_MS in ./reset-poller. The two floors must move together: the resolver's
+ * value now reaches setInterval, so a lower floor here would be silently overridden by the
+ * poller and an accepted config value would not be the cadence that runs.
+ */
+const MIN_POLL_SECONDS = 600;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 30_000;
+
+const DISABLED: ResolvedQuotaResetNotify = Object.freeze({
+  enabled: false,
+  kinds: ALL_KINDS,
+  pollMs: 0,
+  allowPrivateNetwork: false,
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+});
+
+type RawNotify = {
+  enabled?: unknown;
+  kinds?: unknown;
+  pollSeconds?: unknown;
+  webhookUrl?: unknown;
+  allowPrivateNetwork?: unknown;
+  timeoutMs?: unknown;
+  command?: unknown;
+};
+
+function positiveInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+function nonBlankStrings(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter((item): item is string => typeof item === "string" && item.trim() !== "");
+  return out.length > 0 ? out : undefined;
+}
+
+export function resolveQuotaResetNotify(raw: unknown): ResolvedQuotaResetNotify {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return DISABLED;
+  const value = raw as RawNotify;
+
+  const webhookUrl = typeof value.webhookUrl === "string" && value.webhookUrl.trim() !== ""
+    ? value.webhookUrl.trim()
+    : undefined;
+  const command = nonBlankStrings(value.command);
+
+  // An "enabled" subsystem with nowhere to send is a misconfiguration. Reporting it as off
+  // keeps the default-OFF guarantee honest: no sink means no timer and no observation.
+  const enabled = value.enabled === true && (webhookUrl !== undefined || command !== undefined);
+  if (!enabled) return DISABLED;
+
+  const requestedKinds = Array.isArray(value.kinds)
+    ? value.kinds.filter((kind): kind is QuotaResetKind => kind === "scheduled" || kind === "surprise")
+    : [];
+  const kinds: ReadonlySet<QuotaResetKind> = requestedKinds.length > 0
+    ? new Set(requestedKinds)
+    : ALL_KINDS;
+
+  const pollSeconds = value.pollSeconds === 0
+    ? 0
+    : positiveInt(value.pollSeconds, DEFAULT_POLL_SECONDS, MIN_POLL_SECONDS, 24 * 60 * 60);
+
+  return Object.freeze({
+    enabled: true,
+    kinds,
+    pollMs: pollSeconds * 1_000,
+    ...(webhookUrl !== undefined ? { webhookUrl } : {}),
+    allowPrivateNetwork: value.allowPrivateNetwork === true,
+    timeoutMs: positiveInt(value.timeoutMs, DEFAULT_TIMEOUT_MS, 100, MAX_TIMEOUT_MS),
+    ...(command !== undefined ? { command } : {}),
+  });
+}
+
+/** Bounds how often the hot path stats the config file. */
+const STAT_TTL_MS = 5_000;
+
+type Cached = {
+  checkedAt: number;
+  signature: string;
+  resolved: ResolvedQuotaResetNotify;
+};
+
+let cached: Cached | null = null;
+
+/** mtime + size of the config file. Cheap, and changes on any edit including an in-place one. */
+function configSignature(): string {
+  try {
+    const stat = statSync(join(getConfigDir(), "config.json"));
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return "absent";
+  }
+}
+
+export function currentQuotaResetNotify(): ResolvedQuotaResetNotify {
+  const now = Date.now();
+  if (cached && now - cached.checkedAt < STAT_TTL_MS) return cached.resolved;
+
+  const signature = configSignature();
+  if (cached && cached.signature === signature) {
+    cached.checkedAt = now;
+    return cached.resolved;
+  }
+
+  let resolved = DISABLED;
+  try {
+    resolved = resolveQuotaResetNotify(
+      (loadConfig() as { quotaResetNotify?: unknown }).quotaResetNotify,
+    );
+  } catch {
+    // An unreadable config must not enable a notifier, and must not throw on a quota write.
+  }
+  cached = { checkedAt: now, signature, resolved };
+  return resolved;
+}
+
+export function isQuotaResetNotificationEnabled(): boolean {
+  return currentQuotaResetNotify().enabled;
+}
+
+export function resolveQuotaResetPollMs(): number {
+  return currentQuotaResetNotify().pollMs;
+}
+
+export function resetQuotaResetNotifyCacheForTests(): void {
+  cached = null;
+}

package/src/quota/reset-observer.ts

@@ -0,0 +1,125 @@
+/**
+ * The one place a quota snapshot becomes a delivered reset notification.
+ *
+ * Kept behind a lazy import from both quota subsystems: src/codex/quota.ts and
+ * src/providers/quota.ts are both statically reachable from
+ * src/server/responses/core.ts, so a static edge here would load this module, its config
+ * resolution, and its sink registry into every install — the failure AGENTS.md documents for
+ * Compatibility Lab, where a six-hop chain pulled ~69 modules onto the core path.
+ *
+ * Never throws. A detection or delivery failure must not break the quota write that
+ * triggered it.
+ */
+
+import {
+  detectQuotaResets,
+  quotaAccountTag,
+  type QuotaResetEvent,
+  type QuotaWindowObservation,
+} from "./reset-detector";
+import {
+  claimQuotaReset,
+  forgetLastObservedWindows,
+  quotaResetAccountSalt,
+  recordQuotaResetEvent,
+  swapLastObservedWindows,
+} from "./reset-seen-store";
+
+export type QuotaResetSink = (event: QuotaResetEvent) => void;
+
+let sink: QuotaResetSink | null = null;
+
+/**
+ * Install the delivery sink. Core owns the slot; wp4 registers into it at activation.
+ *
+ * Until something registers, detection still runs its bookkeeping but delivers nowhere,
+ * which is what keeps the subsystem inert on a default install.
+ */
+export function setQuotaResetSink(next: QuotaResetSink | null): void {
+  sink = next;
+}
+
+/** True when a sink is installed. Used by the seams to skip work entirely. */
+export function hasQuotaResetSink(): boolean {
+  return sink !== null;
+}
+
+/**
+ * Observe one committed snapshot for a (scope, account) pair.
+ *
+ * The baseline comes from the detector's own persisted last-seen map, not from the caller:
+ * see swapLastObservedWindows for why neither upstream cache can supply one.
+ */
+export function observeQuotaSnapshot(input: {
+  readonly scope: string;
+  readonly accountKey: string;
+  readonly windows: ReadonlyArray<QuotaWindowObservation>;
+  readonly now?: number;
+}): QuotaResetEvent[] {
+  try {
+    if (!sink) return [];
+    if (input.windows.length === 0) return [];
+    const now = input.now ?? Date.now();
+    const accountTag = quotaAccountTag(input.accountKey, quotaResetAccountSalt());
+    // Stamp the observation time as it becomes the baseline. The detector needs the gap
+    // between two observations to tell a rolling window's natural decay from a real reset,
+    // and only this layer knows when the snapshot was taken.
+    const stamped = input.windows.map(window => ({ ...window, observedAt: now }));
+    const previous = swapLastObservedWindows(input.scope, accountTag, stamped);
+    if (!previous) return [];
+
+    const detected = detectQuotaResets({
+      scope: input.scope,
+      accountTag,
+      previous,
+      next: input.windows,
+      now,
+    });
+
+    const delivered: QuotaResetEvent[] = [];
+    for (const event of detected) {
+      // Claim BEFORE dispatch. A sink that fails must not cause a re-notification storm on
+      // the next poll, and two observers racing one transition must produce one notification.
+      if (!claimQuotaReset(event.key, now, event.resetAt)) continue;
+      recordQuotaResetEvent(event);
+      delivered.push(event);
+      try {
+        sink(event);
+      } catch {
+        // A sink is best-effort by contract; its failure is recorded by the sink layer.
+      }
+    }
+    return delivered;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Forget the baseline for a (scope, accountKey) whose quota row was deliberately cleared.
+ *
+ * Lives here rather than in the store because the account TAG is derived from the account
+ * key with the per-install salt, and callers hold the key, not the tag. Runs regardless of
+ * whether a sink is installed: a stale baseline written while notifications were enabled
+ * must not survive to fire a false reset after they are re-enabled.
+ *
+ * Never throws, for the same reason observeQuotaSnapshot does not: this is called from
+ * sign-out and reauth paths that must complete.
+ */
+export function forgetQuotaBaseline(input: {
+  readonly scope: string;
+  readonly accountKey?: string;
+}): void {
+  try {
+    if (input.accountKey === undefined) {
+      forgetLastObservedWindows(input.scope);
+      return;
+    }
+    forgetLastObservedWindows(
+      input.scope,
+      quotaAccountTag(input.accountKey, quotaResetAccountSalt()),
+    );
+  } catch {
+    // Best-effort: a failure here can only cost a re-baseline.
+  }
+}

package/src/quota/reset-poller.ts

@@ -0,0 +1,160 @@
+/**
+ * Opt-in idle refresh so a reset is noticed while nobody is looking.
+ *
+ * This is load-bearing, not a convenience. fetchProviderQuotaReports has exactly one caller
+ * — the GET /api/provider-quotas route — so with no dashboard open and no CLI invocation it
+ * never runs, no second snapshot exists, and an overnight reset passes unobserved. That
+ * overnight case is the whole reason the subsystem exists.
+ *
+ * Shape follows src/storage/policy-scheduler.ts: a module-singleton unref'd interval whose
+ * config gate lives in the callee, so toggling `enabled` takes effect on the next tick
+ * without a restart (the rationale spelled out at src/oauth/token-guardian.ts:276).
+ */
+
+const DEFAULT_INTERVAL_MS = 15 * 60_000;
+/**
+ * Above the 5-minute provider cache TTL and the 10-minute per-account TTL, so one tick costs
+ * at most one upstream probe per window rather than hammering a quota endpoint that
+ * rate-limits (src/providers/quota.ts:1425 records an observed 429 under repeated probing).
+ */
+export const MIN_INTERVAL_MS = 10 * 60_000;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let detachShutdownHook: (() => void) | null = null;
+/** The bounded cadence the live timer was created with, so a tick can notice config drift. */
+let liveIntervalMs: number | null = null;
+/**
+ * Bumped by every start and stop. A tick captures it on entry and re-checks before publishing,
+ * so a probe still in flight when the poller stops cannot publish into the next generation.
+ */
+let generation = 0;
+/** setInterval does not skip a firing while the previous callback is still awaiting. */
+let inFlight = false;
+
+/** Number of ticks that have run. Test-only observability; carries no quota data. */
+let tickCount = 0;
+
+function boundedInterval(value: number): number {
+  return Math.max(MIN_INTERVAL_MS, Math.floor(value));
+}
+
+/** Re-arm the timer when the operator changed the cadence since it was created. */
+function restartIfCadenceChanged(configured: number): void {
+  if (timer === null || boundedInterval(configured) === liveIntervalMs) return;
+  stopQuotaResetPoller();
+  startQuotaResetPoller(configured);
+}
+
+async function tick(): Promise<void> {
+  // An interval firing while the previous probe is still awaiting would double the upstream
+  // load precisely when it is already slow.
+  if (inFlight) return;
+  inFlight = true;
+  const entryGeneration = generation;
+  try {
+    const { isQuotaResetNotificationEnabled, resolveQuotaResetPollMs } = await import(
+      "./reset-notify-config"
+    );
+    // Re-sync the sink on every tick, before the enable check bails out. This is what makes
+    // enabling or disabling notifications take effect without a restart: an install that starts
+    // with the section absent has no sink, and the seams therefore skip all work, so something
+    // has to notice the operator turned it on. Cheap — the resolver is mtime-cached.
+    const { syncQuotaResetActivation } = await import("./reset-activation");
+    await syncQuotaResetActivation();
+    if (!isQuotaResetNotificationEnabled()) return;
+    const configured = resolveQuotaResetPollMs();
+    if (configured === 0) return;
+    // A stop or restart landed while the config resolved: this tick no longer owns the timer,
+    // so it must neither count as a probe nor adopt a cadence for a generation that is gone.
+    if (entryGeneration !== generation) return;
+    // Adopt a changed cadence without a restart, which is why the config gate lives in the
+    // callee at all. Only while this tick still owns the timer.
+    restartIfCadenceChanged(configured);
+    tickCount += 1;
+    const [{ loadConfig }, { fetchProviderQuotaReports }] = await Promise.all([
+      import("../config"),
+      import("../providers/quota"),
+    ]);
+    // A stop or restart landed while this probe was in flight: the result belongs to a
+    // generation that no longer owns the timer, so it must not publish.
+    if (entryGeneration !== generation) return;
+    // Forced: an unforced call would be served from the 5-minute cache and produce no new
+    // observation at all.
+    await fetchProviderQuotaReports(loadConfig(), true);
+  } catch {
+    // A failed probe is not an error worth surfacing: the next tick tries again.
+  } finally {
+    inFlight = false;
+  }
+}
+
+/** Idempotent. A second call while running is a no-op, matching startStorageCleanupScheduler. */
+export function startQuotaResetPoller(intervalMs = DEFAULT_INTERVAL_MS): void {
+  if (timer) return;
+  const bounded = boundedInterval(intervalMs);
+  generation += 1;
+  liveIntervalMs = bounded;
+  timer = setInterval(() => void tick(), bounded);
+  // Never keep the process alive for a quota probe.
+  timer.unref?.();
+  void import("../lib/optional-shutdown-hooks")
+    .then(hooks => {
+      detachShutdownHook = hooks.registerOptionalShutdownHook(
+        "quota-reset-poller",
+        stopQuotaResetPoller,
+      );
+    })
+    .catch(() => {
+      // Without the hook the unref'd timer still cannot delay exit.
+    });
+}
+
+export function stopQuotaResetPoller(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+  liveIntervalMs = null;
+  generation += 1;
+  detachShutdownHook?.();
+  detachShutdownHook = null;
+}
+
+export function isQuotaResetPollerRunning(): boolean {
+  return timer !== null;
+}
+
+/**
+ * Adopt the operator's configured cadence at startup.
+ *
+ * The caller starts the poller synchronously with the default interval, because resolving the
+ * config here would mean a static edge to ../config from a module the quota boundary guard
+ * requires to have none. Resolving it through import() keeps that edge dynamic, at the cost of
+ * the timer running at the default for the few microtasks before this settles.
+ */
+export async function syncQuotaResetPollerCadence(): Promise<void> {
+  const { resolveQuotaResetPollMs } = await import("./reset-notify-config");
+  const configured = resolveQuotaResetPollMs();
+  // 0 is passive-only: tick() already returns before probing, and the timer stays unref'd.
+  if (configured === 0) return;
+  restartIfCadenceChanged(configured);
+}
+
+/** Test-only: run one tick synchronously rather than waiting out the interval. */
+export async function runQuotaResetPollerTickForTests(): Promise<void> {
+  await tick();
+}
+
+export function quotaResetPollerTickCountForTests(): number {
+  return tickCount;
+}
+
+/** Test-only: the bounded cadence the live timer is running at, or null when stopped. */
+export function quotaResetPollerIntervalForTests(): number | null {
+  return liveIntervalMs;
+}
+
+export function resetQuotaResetPollerForTests(): void {
+  stopQuotaResetPoller();
+  tickCount = 0;
+}