@bitkyc08/opencodex 2.41.0 → 2.42.0

package/src/providers/muse-subscription-usage.ts

@@ -0,0 +1,95 @@
+/**
+ * Meta's subscription-usage SSE frame.
+ *
+ * Meta publishes no quota endpoint — 17 plausible REST paths were probed and every one
+ * 404s, and no `x-ratelimit-*` header appears on any of three measured request shapes
+ * (devlog/_plan/260903_muse_spark_plan_oauth/003 §E). The only machine-readable usage
+ * Meta emits arrives mid-stream, as one extra event alongside the ordinary
+ * `response.*` sequence on a streaming `POST /v1/responses`.
+ *
+ * That inverts the usual seam: this module is fed by the request path, not by a probe,
+ * and nothing can refresh its output on demand — obtaining a newer value would mean
+ * spending a real inference turn.
+ *
+ * Measured payload (2026-09-03):
+ *
+ * ```json
+ * { "type": "response.subscription_usage",
+ *   "subscription": {
+ *     "tier": "27681393394859588",
+ *     "window": { "used_percent": 0, "resets_at": 1788431188, "window_duration_mins": 300 },
+ *     "weekly": { "used_percent": 0, "resets_at": 1788739200 } } }
+ * ```
+ */
+import { asRecord, normalizePercent, normalizeResetAt, toFiniteNumber } from "./quota-wire";
+import type { ProviderQuota, ProviderQuotaWindow } from "./quota-types";
+
+/** The SSE frame type Meta emits on streaming turns. */
+export const MUSE_SUBSCRIPTION_USAGE_TYPE = "response.subscription_usage";
+
+/** Meta's five-hour window, identified by its declared duration rather than assumed. */
+const FIVE_HOUR_WINDOW_MINS = 300;
+
+/** True when a parsed SSE payload is the subscription-usage frame. */
+export function isMuseSubscriptionUsagePayload(payload: unknown): boolean {
+  return asRecord(payload)?.type === MUSE_SUBSCRIPTION_USAGE_TYPE;
+}
+
+/**
+ * Translate the frame into a `ProviderQuota`.
+ *
+ * Returns null — never throws — for anything unrecognizable. This runs inside SSE
+ * inspection on a live request, where the only acceptable failure is silence: a parse
+ * error must not cost the user their turn.
+ *
+ * `subscription.tier` is deliberately dropped. It is an opaque numeric id, not the plan
+ * label the Muse CLI prints, so surfacing it would show a meaningless number.
+ */
+export function parseMuseSubscriptionUsage(payload: unknown): ProviderQuota | null {
+  const subscription = asRecord(asRecord(payload)?.subscription);
+  if (!subscription) return null;
+
+  const quota: ProviderQuota = { updatedAt: Date.now() };
+  let sawWindow = false;
+
+  const window = asRecord(subscription.window);
+  if (window) {
+    const percent = normalizePercent(window.used_percent);
+    const resetAt = normalizeResetAt(window.resets_at);
+    const durationMins = toFiniteNumber(window.window_duration_mins);
+    if (percent !== undefined) {
+      if (durationMins === FIVE_HOUR_WINDOW_MINS) {
+        quota.fiveHourPercent = percent;
+        if (resetAt !== undefined) quota.fiveHourResetAt = resetAt;
+        sawWindow = true;
+      } else {
+        // A window of some other length is NOT forced into the five-hour slot: filing a
+        // ten-hour window there would understate usage by the ratio of the two windows,
+        // and would do so with full confidence. Carry it with its real duration instead.
+        const custom: ProviderQuotaWindow = {
+          label: durationMins === undefined ? "subscription" : `${durationMins}m`,
+          percent,
+          ...(resetAt !== undefined ? { resetAt } : {}),
+        };
+        quota.customWindows = [...(quota.customWindows ?? []), custom];
+        sawWindow = true;
+      }
+    }
+  }
+
+  const weekly = asRecord(subscription.weekly);
+  if (weekly) {
+    const percent = normalizePercent(weekly.used_percent);
+    if (percent !== undefined) {
+      quota.weeklyPercent = percent;
+      const resetAt = normalizeResetAt(weekly.resets_at);
+      if (resetAt !== undefined) quota.weeklyResetAt = resetAt;
+      sawWindow = true;
+    }
+  }
+
+  // Either window may be absent independently, but a payload carrying neither says
+  // nothing — returning a bare `updatedAt` would publish an empty row that the GUI
+  // would render as a quota with no bars.
+  return sawWindow ? quota : null;
+}

package/src/providers/quota.ts

@@ -1409,6 +1409,27 @@ async function fetchKiroQuota(provider: string): Promise<ProviderQuotaReport | n
   return report(provider, "kiro:usage-limits", snapshot.quota);
 }
 
+/**
+ * Provider-level row for a passive provider: the ACTIVE account's last observed
+ * subscription windows, the same shape `fetchAnthropicQuota` and `fetchKiroQuota`
+ * return.
+ *
+ * Cache-only. A dashboard load or `ocx account refresh` must never spend an inference
+ * turn, so `forceRefresh` does not exist on this path — there is nothing to refresh.
+ * `report.updatedAt` is the observation time, which is what both GUI surfaces render
+ * as the relative age of the row.
+ */
+async function fetchPassiveProviderQuota(provider: string): Promise<ProviderQuotaReport | null> {
+  const activeId = getAccountSet(provider)?.activeAccountId;
+  if (!activeId) return null;
+  // Idempotent; without it a proxy restart shows nothing until the next streaming turn
+  // even though the last observation is on disk.
+  hydrateAccountQuotaCache();
+  const entry = accountQuotaCache.get(accountCacheKey(provider, activeId));
+  if (!entry?.quota) return null;
+  return report(provider, `${provider}:subscription-observation`, entry.quota);
+}
+
 // ---------------------------------------------------------------------------
 // Per-account quota (multiauth)
 // ---------------------------------------------------------------------------
@@ -1505,6 +1526,78 @@ export function setCachedProviderAccountQuotaForTests(
   accountQuotaCache.set(key, { ts: Date.now(), quota });
 }
 
+/**
+ * Providers whose per-account quota is OBSERVED in-band, never probed.
+ *
+ * Deliberately separate from `supportsPerAccountQuota` rather than folded into it. That
+ * predicate gates `fetchAccountQuota`, whose fallback branch sends any
+ * non-Kiro/non-Antigravity bearer to Anthropic's usage endpoint — so adding `meta-muse`
+ * there without a dedicated branch would ship a Meta credential to Anthropic. And even
+ * with a branch it would be the wrong predicate: it means "this provider can be probed",
+ * and Meta publishes no quota endpoint to probe.
+ */
+export function hasPassiveAccountQuota(provider: string): boolean {
+  return provider === "meta-muse";
+}
+
+/**
+ * Record a quota observed in-band on a streaming turn.
+ *
+ * The CALLER captures `writerGeneration` when it resolves the serving credential, not
+ * this function at write time. A streaming turn is a long await, and a generation
+ * captured immediately before the write cannot see a config or account change that
+ * happened EARLIER in the same turn — which is exactly the case the fence exists for.
+ */
+export function recordPassiveAccountQuota(
+  provider: string,
+  accountId: string,
+  quota: ProviderQuota,
+  writerGeneration: number,
+): void {
+  if (!hasPassiveAccountQuota(provider) || !accountId) return;
+  const key = accountCacheKey(provider, accountId);
+  if (!mayCommitAccountQuotaKey(key, writerGeneration)) return;
+  // Hydrate BEFORE writing, not only on the read path. `persistAccountQuotaCache`
+  // serializes the whole in-memory map, so a passive write that lands before anything
+  // has read the cache would persist this one row and erase every other provider's
+  // saved row -- and `diskHydrated` would then stop any later reader from recovering
+  // them. A probe writer cannot hit this because its own read hydrates first; an
+  // observation arrives unprompted, so it must hydrate itself.
+  hydrateAccountQuotaCache();
+  accountQuotaCache.set(key, { ts: Date.now(), quota });
+  // Persisted so a restart keeps the last observation: with no probe to re-establish it,
+  // a forgotten row stays forgotten until the user happens to run another streaming turn.
+  persistAccountQuotaCache();
+  // sweepExpiredOnWrite is deliberately NOT called. Existing probe writers call it
+  // because they run on a poll; this runs on the request path, where a state sweep does
+  // not belong. Passive rows are still reclaimed by generation reconciliation
+  // (reconcileProviderAccountQuotaRows) and by the disk reader's age bound.
+}
+
+/**
+ * Cache-only per-account rows for a passive provider. Never probes, never refreshes.
+ *
+ * An account with no observation is OMITTED rather than returned with `quota: null` and
+ * `unavailable`: that pair means "a probe was attempted and failed", and no probe was
+ * ever attempted here. A user who has not yet run a streaming turn simply has no
+ * measurement, which is not an error state.
+ */
+export function readPassiveProviderAccountQuotas(provider: string): ProviderAccountQuota[] {
+  if (!hasPassiveAccountQuota(provider)) return [];
+  // Idempotent, and otherwise only reached from probe paths a passive provider never
+  // enters — without it a restart shows nothing until the next streaming turn, even
+  // though the row is sitting on disk.
+  hydrateAccountQuotaCache();
+  const set = getAccountSet(provider);
+  if (!set) return [];
+  const rows: ProviderAccountQuota[] = [];
+  for (const account of set.accounts) {
+    const entry = accountQuotaCache.get(accountCacheKey(provider, account.id));
+    if (entry?.quota) rows.push({ accountId: account.id, quota: entry.quota });
+  }
+  return rows;
+}
+
 export function sweepExpiredProviderAccountQuotaRows(now = Date.now()): number {
   let removed = 0;
   for (const [key, entry] of accountQuotaCache) {
@@ -2299,6 +2392,9 @@ async function maybeFetchProviderQuota(
     if (provider.authMode === "oauth" && name === "cursor") return fetchCursorQuota(name);
     if (provider.authMode === "oauth" && name === "google-antigravity") return fetchAntigravityQuota(name, provider);
     if (provider.authMode === "oauth" && name === "kiro") return fetchKiroQuota(name);
+    // Passive providers (meta-muse): Meta publishes no quota endpoint, so there is no
+    // probe to run — the row is the active account's last in-band observation.
+    if (provider.authMode === "oauth" && hasPassiveAccountQuota(name)) return fetchPassiveProviderQuota(name);
     // Kimi Code `/usages` accepts OAuth or coding-plan API keys, but only on the canonical
     // host and only for real key auth — forward/local modes carry no credential of ours.
     if (provider.authMode === "oauth" && name === "kimi") return fetchKimiQuota(name, provider);

package/src/providers/registry.ts

@@ -1540,7 +1540,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelInputModalities: Object.fromEntries(META_MUSE_MODELS.map(id => [id, ["text", "image"] as ["text", "image"]])),
     modelReasoningEfforts: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_REASONING_EFFORTS])),
     modelReasoningEffortMap: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_REASONING_EFFORT_MAP])),
-    note: "Reuses the API key the Muse Code CLI stores after `muse login` (macOS only; requires the CLI installed and signed in). Meta scopes that credential to the Muse Code CLI, so this is an UNSUPPORTED use: Meta does not authorize subscription coverage outside its own CLI, how these calls settle is not observable from the API, and you should treat every call as billable against your account. The imported key is copied into OpenCodex's auth store. Meta reports subscription window usage inside streaming responses, but OpenCodex does not yet read or display it, and there is no endpoint to query it on demand. Rate limits apply per team, not per key. For a supported path use the meta-model provider with your own key (export it as META_MODEL_API_KEY).",
+    note: "Reuses the API key the Muse Code CLI stores after `muse login` (macOS only; requires the CLI installed and signed in). Meta scopes that credential to the Muse Code CLI, so this is an UNSUPPORTED use: Meta does not authorize subscription coverage outside its own CLI, how these calls settle is not observable from the API, and you should treat every call as billable against your account. The imported key is copied into OpenCodex's auth store. OpenCodex reads Meta's subscription windows from streaming responses and shows the last observed value with its age; there is no endpoint to query them on demand, so refreshing one requires another streaming turn, and translated (non-passthrough) turns report none. Rate limits apply per team, not per key. For a supported path use the meta-model provider with your own key (export it as META_MODEL_API_KEY).",
   },
   {
     id: "umans",

package/src/server/index.ts

@@ -812,13 +812,21 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     if (path === "/v1/responses/compact") return req.method === "POST";
     if (path === "/v1/alpha/search") return req.method === "POST";
     if (path === "/v1/models") return req.method === "GET";
-    // Standalone realtime voice sessions (codex-rs thread/realtime/start, WebSocket
-    // transport) — a directly-spawned `codex app-server` needs these for desktop
-    // voice the same way it needs /v1/responses. WebSocket upgrades only; plain
-    // HTTP on these paths stays rejected.
-    if (path === "/v1/realtime" || path === "/v1/live") {
-      return req.headers.get("upgrade")?.toLowerCase() === "websocket";
-    }
+    // Realtime voice — a directly-spawned `codex app-server` needs these for desktop voice
+    // the same way it needs /v1/responses. Two shapes, same trust model as /v1/responses:
+    //  - standalone sessions (codex-rs thread/realtime/start, WebSocket transport):
+    //    WebSocket upgrades on the bare /v1/realtime and /v1/live paths only;
+    //  - WebRTC calls (desktop v3 voice): POST call-create on /v1/live or
+    //    /v1/realtime/calls, then the sideband join as a WebSocket upgrade on the keyed
+    //    /v1/live/{callId}, /v1/realtime/calls/{callId}, or /v1/realtime?call_id= form
+    //    (the join reaches this listener through the injected
+    //    experimental_realtime_ws_base_url; openai/codex #35830).
+    // Plain HTTP on the upgrade paths stays rejected.
+    const isWebSocketUpgrade = req.headers.get("upgrade")?.toLowerCase() === "websocket";
+    if (path === "/v1/realtime") return isWebSocketUpgrade;
+    if (path === "/v1/live") return isWebSocketUpgrade || req.method === "POST";
+    if (path === "/v1/realtime/calls") return req.method === "POST";
+    if (/^\/v1\/(?:live|realtime\/calls)\/[^/]+\/?$/.test(path)) return isWebSocketUpgrade;
     return false;
   }
 

package/src/server/live.ts

@@ -147,6 +147,20 @@ function clientProtocolHeaders(reqHeaders: Headers): Record<string, string> {
 
 const LIVE_CALL_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 
+/**
+ * Decode one path-segment call id. A malformed percent escape (`%ZZ`) makes
+ * `decodeURIComponent` throw; that must read as "not a sideband target" (JSON 404),
+ * never escape the router as a 500.
+ */
+function decodeLiveCallId(segment: string): string | null {
+  try {
+    const callId = decodeURIComponent(segment);
+    return LIVE_CALL_ID_RE.test(callId) ? callId : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Credential-shaped query keys never forwarded upstream on a standalone realtime
  * relay. Auth on the upstream socket is proxy-owned (headers resolved by
@@ -238,8 +252,8 @@ function httpsToWss(httpUrl: string): string {
 export function parseLiveSidebandTarget(pathname: string, searchParams: URLSearchParams, rawQuery = ""): LiveSidebandTarget | null {
   const liveMatch = pathname.match(/^\/v1\/live\/([^/]+)\/?$/);
   if (liveMatch) {
-    const callId = decodeURIComponent(liveMatch[1]!);
-    if (!LIVE_CALL_ID_RE.test(callId)) return null;
+    const callId = decodeLiveCallId(liveMatch[1]!);
+    if (!callId) return null;
     return { style: "frameless-path", callId };
   }
   // Standalone Frameless session (no call-create): `GET /v1/live?model=`.
@@ -248,8 +262,8 @@ export function parseLiveSidebandTarget(pathname: string, searchParams: URLSearc
   }
   const callsMatch = pathname.match(/^\/v1\/realtime\/calls\/([^/]+)\/?$/);
   if (callsMatch) {
-    const callId = decodeURIComponent(callsMatch[1]!);
-    if (!LIVE_CALL_ID_RE.test(callId)) return null;
+    const callId = decodeLiveCallId(callsMatch[1]!);
+    if (!callId) return null;
     return { style: "realtime-calls-path", callId };
   }
   if (pathname === "/v1/realtime" || pathname === "/v1/realtime/") {

package/src/server/management/oauth-account-routes.ts

@@ -30,7 +30,7 @@ import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/ke
 import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
-import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderAccountQuotas, fetchProviderQuotaReports, supportsPerAccountQuota } from "../../providers/quota";
+import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderAccountQuotas, fetchProviderQuotaReports, hasPassiveAccountQuota, readPassiveProviderAccountQuotas, supportsPerAccountQuota } from "../../providers/quota";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { clearThreadAccountMap } from "../../codex/routing";
 import {
@@ -282,11 +282,18 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     // account can show its own 5h/weekly bars (not just the active one). Opt-in via ?quota=1
     // so the plain account list stays a cheap local read; ?refresh=1 bypasses the TTL.
     const wantQuota = url.searchParams.get("quota") === "1" && supportsPerAccountQuota(provider);
-    if (!wantQuota) return jsonResponse(projectAccounts());
+    // Meta publishes no quota endpoint: its usage is observed in-band on streaming turns
+    // and read back from the cache here. `?refresh=1` is accepted and ignored on this
+    // path rather than rejected -- the GUI sends it for every provider on a manual
+    // refresh, and a 400 would report an error for what is simply a no-op.
+    const passiveQuota = url.searchParams.get("quota") === "1" && hasPassiveAccountQuota(provider);
+    if (!wantQuota && !passiveQuota) return jsonResponse(projectAccounts());
     const forceRefresh = url.searchParams.get("refresh") === "1";
     // Probing may refresh the active credential and mark needsReauth — project health
     // from the post-probe store so the response is not stale.
-    const rows = await fetchProviderAccountQuotas(provider, forceRefresh);
+    const rows = passiveQuota
+      ? readPassiveProviderAccountQuotas(provider)
+      : await fetchProviderAccountQuotas(provider, forceRefresh);
     const byId = new Map(rows.map(row => [row.accountId, row]));
     const projected = projectAccounts();
     return jsonResponse({

package/src/server/responses/core.ts

@@ -219,6 +219,9 @@ import {
   waitForProviderRequestSlot,
 } from "../../providers/request-pacing";
 import { slugsEquivalent } from "../../providers/slug-codec";
+import { isMuseSubscriptionUsagePayload, parseMuseSubscriptionUsage } from "../../providers/muse-subscription-usage";
+import { hasPassiveAccountQuota, recordPassiveAccountQuota } from "../../providers/quota";
+import { captureConfigGeneration } from "../../lib/state-store-sweeper";
 import { applyOpenAiVirtualModel, resolveOpenAiCompactModel } from "../../providers/openai-virtual-models";
 import { isUsageDebugEnabled } from "../../usage/debug";
 import { readJsonRequestBody, DecompressedBodyTooLargeError, UnsupportedContentEncodingError } from "../request-decompress";
@@ -3308,6 +3311,13 @@ async function handleResponsesInner(
   // the request actually used, so a concurrent rotation cannot cool an innocent replacement.
   let genericFailoverAccountId: string | null = null;
   let genericFailovers = 0;
+  /**
+   * Config generation captured where the serving credential is RESOLVED, not where the
+   * quota is written. A streaming turn is a long await, so a generation captured at write
+   * time cannot see a config or account change that happened earlier in the same turn —
+   * the case the fence exists for. Stays 0 for every provider without a passive quota.
+   */
+  let passiveQuotaWriterGeneration = 0;
   /**
    * Apply a rotated account's FULL credential snapshot to the live route (#2568d).
    *
@@ -3443,6 +3453,10 @@ async function handleResponsesInner(
         if (isGenericFailoverProvider(route.providerName, route.provider)) {
           genericFailoverAccountId = resolved.accountId;
         }
+        // Captured beside the account it fences, so the two can never disagree.
+        if (hasPassiveAccountQuota(route.providerName)) {
+          passiveQuotaWriterGeneration = captureConfigGeneration();
+        }
         if (route.providerName === "kiro") {
           // `{}` is intentional: this is an account-scoped request with no stored routing metadata.
           // Only genuinely accountless adapter calls leave the context undefined and use local/env fallback.
@@ -3888,7 +3902,27 @@ async function handleResponsesInner(
     // check sees nothing undeclared, and the refused turn enters continuation state anyway. So the
     // rejection is sticky for the whole turn, set from every parsed payload on the inspection side.
     let inspectionSawUndeclaredTool = false;
+    const passiveQuotaObserved = hasPassiveAccountQuota(route.providerName)
+      && route.provider.authMode === "oauth";
     const noteInspectedPayload = (payload: unknown) => {
+      // Meta reports subscription usage ONLY as an in-stream event; there is no endpoint
+      // to poll (003 §E probed 17 paths, all 404). Observed here rather than behind a
+      // dedicated inspector handler because onParsedPayload already reaches every
+      // passthrough shape -- eager relay and both tee consumers -- through this one
+      // function.
+      //
+      // Placed BEFORE the undeclared-tool early return below, which is load-bearing: that
+      // guard latches for the rest of the turn once it fires, and a turn that tripped it
+      // still legitimately reports usage.
+      if (passiveQuotaObserved && isMuseSubscriptionUsagePayload(payload)) {
+        const quota = parseMuseSubscriptionUsage(payload);
+        // Read at EVENT time, not at handler construction: failover rebinds this, and the
+        // quota belongs to the account that actually served the turn.
+        const servingAccountId = genericFailoverAccountId;
+        if (quota && servingAccountId) {
+          recordPassiveAccountQuota(route.providerName, servingAccountId, quota, passiveQuotaWriterGeneration);
+        }
+      }
       // Gated on the same flag as the guard itself: with no readable catalog (or a forward-auth
       // provider) every name looks undeclared, and flipping this would stop recording continuation
       // state for exactly the passthrough traffic the guard deliberately stands down for.

package/src/server/responses/empty-completion-guard.ts

@@ -176,6 +176,9 @@ export function mergeUsage(
   const contextTotalTokens = second.contextTotalTokens ?? first.contextTotalTokens;
   const inputTokens = first.inputTokens + second.inputTokens;
   const outputTokens = first.outputTokens + second.outputTokens;
+  // The attempt that produced the content owns the raw wire usage (openai/codex#41980);
+  // an empty first attempt may still be the only one that saw it.
+  const rawUsage = second.rawUsage ?? first.rawUsage;
   return {
     inputTokens,
     outputTokens,
@@ -186,6 +189,7 @@ export function mergeUsage(
     ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
     ...(reasoningOutputTokens !== undefined ? { reasoningOutputTokens } : {}),
     ...(first.estimated || second.estimated ? { estimated: true } : {}),
+    ...(rawUsage !== undefined ? { rawUsage } : {}),
   };
 }
 

package/src/types/request.ts

@@ -396,4 +396,12 @@ export interface OcxUsage {
   cacheCreationInputTokens?: number;
   reasoningOutputTokens?: number;
   estimated?: boolean;
+  /**
+   * The raw upstream usage object for Responses-shaped upstreams (openai/codex#41980 parity):
+   * codex-rs preserves the complete `response.usage` object through its own pipeline, so fields
+   * the proxy does not model (subscription metadata, future counters) must survive the bridged /
+   * rebuilt `response.completed` too. Accounting paths read only the canonical fields above; the
+   * wire rebuild merges this object's unknown keys back under the normalized values.
+   */
+  rawUsage?: Record<string, unknown>;
 }