@narumitw/pi-usage 0.61.2 → 0.63.0

package/docs/providers.md

@@ -25,10 +25,10 @@ The README contains the capability overview and shared security requirements.
 ### OpenAI native ChatGPT OAuth
 
 - Provider ID: `openai`
-- Semantics: verified ChatGPT plan authentication, not measured subscription usage
-- Source: Pi's fresh native OAuth resolution and an exact complete credential match; no usage HTTP endpoint
-- Displayed data: **Connected (native OAuth)**, an explicit numerical-usage/reset-time limitation, and [ChatGPT usage settings](https://chatgpt.com/settings/usage)
-- Statusline: `chatgpt usage: web only`
+- Source: verified native OAuth plus automatic same-account Codex companion OAuth; distinct shared plan and app windows
+- Display: plan percentages and plan/app resets; app used/remaining percentages are hidden
+- Missing-companion fallback: **Connected (native OAuth)**, same-account login guidance, and [ChatGPT usage settings](https://chatgpt.com/settings/usage)
+- Fallback statusline: `chatgpt usage: web only`
 
 Use `/login openai` in a Pi runtime that supports native Sign in with ChatGPT, then select an official `https://api.openai.com` model.
 Authentication requires Pi's freshly resolved provider source to be `OAuth`, matching effective model and provider authorization, and a complete matching credential with `clientId` and the `chatgpt.tokens.use.direct` scope.
@@ -37,16 +37,40 @@ Stored OAuth alone and Pi's cached OAuth flag do not establish the active runtim
 Runtime/API-key overrides, model-level Authorization replacements or removals, and custom/proxy origins cannot inherit native subscription status.
 OpenAI API-key usage reporting remains unsupported.
 
-The report verifies authentication, not the plan tier, allowance, remaining quota, or reset time.
-Automatic refresh only revalidates auth; it does not poll a usage endpoint.
+Without companion credentials, the report verifies authentication, not the plan tier, allowance, remaining quota, or reset time.
+With valid companion credentials, queries and automatic refreshes read both companion endpoints; otherwise no usage request is made.
 The settings link is guidance, not an automatically opened browser or a promise that the browser is signed into Pi's account.
 Native tokens are never sent to `/backend-api/wham`, and opaque native metadata is not decoded as a legacy Codex account ID.
-Legacy Fast payload rewriting, pricing correction, reset countdowns, and earned reset redemption do not apply to native `openai`.
+Legacy Fast payload rewriting, pricing correction, and earned reset redemption do not apply to native `openai`.
 Existing `openai-codex` behavior below is unchanged.
 
 The boundary is verified against Pi's [`openai-chatgpt.ts`](https://github.com/earendil-works/pi/blob/d86654abb8862e201933517d6f1fce9f88dd117f/packages/ai/src/auth/oauth/openai-chatgpt.ts) at `d86654abb8862e201933517d6f1fce9f88dd117f` and OpenAI's [models and inference](https://developers.openai.com/siwc/token-sharing-open-source/models-and-inference), [token reference](https://developers.openai.com/siwc/token-sharing-open-source/token-reference), and [UI/UX guidelines](https://developers.openai.com/siwc/ui-ux-guidelines).
 These contracts establish the public inference and authentication boundary, not a numerical usage API.
-Verification uses synthetic credentials with Pi's real auth resolver; live browser login and account-specific quota retrieval have not been verified.
+Deterministic verification uses synthetic credentials with Pi's real auth resolver. A user reported one plan weekly remaining percentage and reset time matching the web overview; browser login, app numerical agreement, and broader live coverage remain unverified.
+
+#### Automatic companion quotas
+
+Follow the [companion setup](../README.md#chatgpt-companion-usage): a same-account/workspace `/login openai-codex` is required.
+The former opt-in setting and confirmation are removed; stored `openaiCompanionUsage` values, including `false`, no longer disable requests and are preserved without rewriting on reads.
+Fresh companion OAuth must match a complete grant with its own account ID; custom origins, API-key overrides, conflicting grants, and effective Authorization overrides fail closed.
+Only the companion bearer and matching `ChatGPT-Account-Id` reach these fixed, redirect-rejecting GET routes:
+
+- `https://chatgpt.com/backend-api/wham/usage/chatpass/apps`
+- `https://chatgpt.com/backend-api/wham/usage`
+
+The app list must be complete and bounded to 128 registrations, with a readable nonempty string `id` on every entry, exactly one `id` equal to the native grant's `clientId`, and 1–32 valid windows on that matched entry.
+Unknown envelope fields or pagination markers fail closed rather than assuming uniqueness on one page.
+Only plan primary/secondary windows are used; Codex model-specific limits are not native app quotas.
+Each window requires a finite 0–100 used percentage and positive whole-second duration; optional remaining percentages must agree within one percentage point, and reset timestamps must be valid nonnegative epoch seconds.
+`allowed_usage_percent` is **App allowance**, a cap on shared plan usage, not remaining quota.
+Plan/app windows and reset boundaries stay separate in reports and the statusline; Codex display preferences do not apply.
+App used/remaining values are validated internally but not displayed; app reset/window information and the separately labeled allowance cap remain visible.
+
+Missing-companion paths remain web-only without requests. Other companion failures invalidate numerical data and remain observable.
+No native token, refresh token, app name, or account ID is rendered or persisted by this feature.
+An exact registration match is not independent identity proof; users must choose the same account/workspace for both logins.
+The endpoints remain an experimental, undocumented source despite automatic querying. One user-reported plan weekly comparison matched the web; app numerical agreement and broader live availability remain unverified.
+Contract fixtures derive from [Specode's pinned implementation](https://github.com/specode/pi-subscription-usage/blob/1015f9f419dfef9ac27c9845ec2318394928fa38/src/providers/openai.ts) and [OpenAI's shared-plan/app-limit explanation](https://help.openai.com/en/articles/20001542-using-your-chatgpt-plan-in-other-apps-and-sites), not a public native quota API.
 
 ### OpenAI Codex
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-usage",
-  "version": "0.61.2",
+  "version": "0.63.0",
   "description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
   "type": "module",
   "license": "MIT",
@@ -57,9 +57,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.0",
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.2",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-tui": "1.0.2",
     "@types/node": "26.6.4",
     "esbuild": "0.28.2",
     "typescript": "7.0.2"

package/src/format.ts

@@ -28,7 +28,8 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
   if (report.accountLabel) lines.push(`Account: ${report.accountLabel}`);
   lines.push(`Semantics: ${report.semantics.label}`, "");
 
-  if (report.providerId === "baseten") formatBasetenReport(lines, report);
+  if (report.source === "openai-chatgpt-companion") formatOpenAICompanionReport(lines, report);
+  else if (report.providerId === "baseten") formatBasetenReport(lines, report);
   else if (report.providerId === "openai-codex") formatCodexReport(lines, report);
   else if (report.providerId === "deepseek") formatDeepSeekReport(lines, report);
   else if (report.providerId === "fireworks") formatFireworksReport(lines, report);
@@ -60,6 +61,21 @@ export function formatUsageStatusline(
   codexStatusPercentage: CodexStatusPercentage = "remaining",
 ): string | undefined {
   if (report.providerId === "openai" && report.source === "openai-chatgpt-auth") return "chatgpt usage: web only";
+  if (report.source === "openai-chatgpt-companion") {
+    return `chatgpt ${["chatgpt-plan", "chatgpt-app"]
+      .map((group) => {
+        const windows = report.buckets
+          .filter((bucket) => bucket.groupId === group)
+          .map((bucket) => {
+            const reset = formatResetCountdown(bucket.resetsAt, now);
+            const window = reset ? `↻ ${reset}` : formatWindowLabel(bucket.windowMinutes, "weekly", true);
+            if (group === "chatgpt-app") return window;
+            return `${bucket.remaining === undefined ? "unavailable" : `${bucket.remaining.toFixed(0)}%`} ${window}`;
+          });
+        return `${group === "chatgpt-plan" ? "plan" : "app"} ${windows.join(" ")}`;
+      })
+      .join(" · ")}`;
+  }
   if (report.providerId === "baseten") return formatBasetenStatusline(report);
   if (report.providerId === "openai-codex") {
     return formatCodexStatusline(report, model, now, showCodexResetCountdown, codexStatusPercentage);
@@ -522,6 +538,23 @@ function formatZaiReport(lines: string[], report: UsageReport): void {
   }
 }
 
+function formatOpenAICompanionReport(lines: string[], report: UsageReport): void {
+  for (const group of ["chatgpt-plan", "chatgpt-app"]) {
+    lines.push(group === "chatgpt-plan" ? "Plan limits:" : "App limits:");
+    for (const bucket of report.buckets.filter((bucket) => bucket.groupId === group)) {
+      const value =
+        group === "chatgpt-app"
+          ? bucket.resetsAt === undefined
+            ? "Reset time unavailable"
+            : `resets ${formatReset(bucket.resetsAt)}`
+          : formatPercentBucket(bucket);
+      lines.push(`${formatWindowLabel(bucket.windowMinutes, "weekly", false).padEnd(VALUE_COLUMN)}${value}`);
+    }
+  }
+  for (const metric of report.metrics)
+    lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`);
+}
+
 function formatGenericReport(lines: string[], report: UsageReport): void {
   for (const bucket of report.buckets) {
     lines.push(
@@ -668,6 +701,7 @@ function formatResetCountdown(resetsAt: number | undefined, now: number): string
 
 function formatMetricValue(value: number | string, unit: UsageBucket["unit"] | undefined): string {
   if (unit === "usd" && typeof value === "number") return formatUsd(value);
+  if (unit === "percent" && typeof value === "number") return `${value}%`;
   return String(value);
 }
 

package/src/openai-companion-auth.ts

@@ -0,0 +1,101 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fingerprintResolvedAuth } from "./core.js";
+import { fallbackOAuthCredentialCandidates, type OAuthCredentialCandidateReader } from "./oauth-credential-source.js";
+import { openAIAuthAccessToken } from "./providers/openai-chatgpt.js";
+import { adapterForProvider, resolveUsageAuth } from "./query.js";
+import type { ResolvedUsageAuth } from "./types.js";
+
+// A native app registration is routing metadata, not cryptographic same-account proof.
+// Keep this read-only boundary separate from legacy Codex querying and reset mutation policy.
+export async function resolveOpenAICompanionAuth(
+  ctx: ExtensionContext,
+  native: ResolvedUsageAuth,
+  salt: Uint8Array,
+  credentialReader: (providerId: string) => unknown,
+  candidateReader?: OAuthCredentialCandidateReader,
+): Promise<ResolvedUsageAuth> {
+  const unavailable = () => ({
+    ...native,
+    fingerprint: fingerprintResolvedAuth(
+      { apiKey: JSON.stringify([native.fingerprint, native.openaiClientId, null]) },
+      salt,
+    ),
+  });
+  if (candidateReader?.waitUntilReady && !(await candidateReader.waitUntilReady(ctx, "openai-codex"))) {
+    throw new Error("Companion Codex OAuth credential readiness failed closed.");
+  }
+  const adapter = adapterForProvider("openai-codex");
+  if (!adapter) throw new Error("Companion Codex usage support is unavailable.");
+  const companion = await resolveUsageAuth(ctx, adapter, salt, credentialReader);
+  if (!companion) return unavailable();
+  if (companion.source !== "OAuth")
+    throw new Error("Companion usage requires /login openai-codex OAuth, not an API key.");
+  // Legacy querying is more permissive. Enforce explicit Authorization removals and duplicates
+  // against preserved fresh provider auth before using its normalized request headers.
+  const access = openAIAuthAccessToken(companion.auth);
+  if (ctx.model?.provider === "openai-codex") {
+    const selected = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+    if (
+      !selected.ok ||
+      (selected.baseUrl && new URL(selected.baseUrl).origin !== "https://chatgpt.com") ||
+      openAIAuthAccessToken(selected) !== access
+    ) {
+      throw new Error("Selected Codex model authorization does not match the companion OAuth credential.");
+    }
+  }
+  if (!access || access !== openAIAuthAccessToken(companion)) {
+    throw new Error("Companion Codex runtime authorization did not match its OAuth credential.");
+  }
+  const accountId = codexAccountId(access);
+  if (!accountId) throw new Error("Companion Codex token did not contain a valid account ID.");
+  const offered = candidateReader
+    ? await candidateReader(ctx, "openai-codex")
+    : fallbackOAuthCredentialCandidates("openai-codex", credentialReader);
+  if (!offered.ok) throw new Error("Companion Codex OAuth credential discovery failed closed.");
+  const matches = new Set<string>();
+  for (const candidate of offered.candidates) {
+    const credential = object(candidate);
+    if (credential?.type !== "oauth" || credential.access !== access) continue;
+    if (
+      credential.accountId !== accountId ||
+      typeof credential.refresh !== "string" ||
+      !credential.refresh ||
+      typeof credential.expires !== "number" ||
+      !Number.isFinite(credential.expires)
+    ) {
+      throw new Error("The matching companion Codex OAuth credential was incomplete or had a different account ID.");
+    }
+    matches.add(credential.refresh);
+  }
+  if (matches.size !== 1) throw new Error("Companion Codex OAuth must uniquely match the fresh runtime credential.");
+  const headers = { Authorization: `Bearer ${access}`, "ChatGPT-Account-Id": accountId };
+  return {
+    ...native,
+    openaiCompanion: { headers },
+    fingerprint: fingerprintResolvedAuth(
+      { apiKey: JSON.stringify([native.fingerprint, native.openaiClientId, companion.fingerprint, headers]) },
+      salt,
+    ),
+    secrets: [
+      ...new Set([...native.secrets, ...companion.secrets, ...matches, access, accountId, headers.Authorization]),
+    ],
+  };
+}
+
+function codexAccountId(access: string): string | undefined {
+  try {
+    const parts = access.split(".");
+    if (parts.length !== 3 || !parts[1]) return undefined;
+    const payload = object(JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")));
+    const account = object(payload?.["https://api.openai.com/auth"])?.chatgpt_account_id;
+    return typeof account === "string" && account.length > 0 && account.length <= 512 && /^[\x21-\x7e]+$/u.test(account)
+      ? account
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}

package/src/providers/openai-chatgpt.ts

@@ -24,7 +24,13 @@ export const OPENAI_CHATGPT_ADAPTER: UsageProviderAdapter = {
   id: "openai",
   displayName: "OpenAI",
   semantics: { kind: "consumer-subscription", label: "ChatGPT plan authentication status" },
-  async query(_auth, signal, _timeoutMs, guard) {
+  invalidateCacheOnFailure: true,
+  async query(auth, signal, timeoutMs, guard) {
+    if (auth.openaiCompanion) {
+      const { queryOpenAICompanionUsage } = await import("./openai-companion-usage.js");
+      signal.throwIfAborted();
+      return queryOpenAICompanionUsage(auth, signal, timeoutMs, guard);
+    }
     if (!guard) throw new Error("ChatGPT plan status requires runtime-auth revalidation.");
     signal.throwIfAborted();
     await guard();
@@ -38,8 +44,9 @@ export const OPENAI_CHATGPT_ADAPTER: UsageProviderAdapter = {
       buckets: [],
       metrics: [{ id: "plan-auth", label: "ChatGPT plan authentication", value: "Connected (native OAuth)" }],
       notes: [
-        "Numerical usage and reset times are unavailable in pi-usage for native OpenAI OAuth.",
+        "Numerical usage requires a companion /login openai-codex with the same ChatGPT account/workspace; native inference stays on openai.",
         `Manage usage: ${CHATGPT_USAGE_SETTINGS_URL}`,
+        "Companion usage uses undocumented ChatGPT endpoints; registration matching is not independent identity proof.",
         "Fast mode and earned reset redemption remain legacy openai-codex features.",
       ],
     };
@@ -56,11 +63,11 @@ export function resolveOpenAIChatGPTAuth(
   // isUsingOAuth() is a cached snapshot; source alone is also insufficient when a model header
   // overrides Authorization. Match both freshly resolved credentials and the exact native grant.
   if (source !== "OAuth") throw new UnsupportedOpenAIUsageAuthError();
-  const access = accessToken(auth);
-  if (!access || access !== accessToken(providerAuth)) {
+  const access = openAIAuthAccessToken(auth);
+  if (!access || access !== openAIAuthAccessToken(providerAuth)) {
     throw new Error("The active OpenAI model authorization does not match its resolved OAuth credential.");
   }
-  const matches = new Map<string, string>();
+  const matches = new Map<string, { refresh: string; clientId: string }>();
   for (const candidate of candidates) {
     if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
     const credential = candidate as Record<string, unknown>;
@@ -80,24 +87,28 @@ export function resolveOpenAIChatGPTAuth(
         "The matching OpenAI OAuth credential is not a complete native ChatGPT grant; reconnect with /login openai.",
       );
     }
-    matches.set(JSON.stringify([credential.clientId, credential.refresh]), credential.refresh);
+    matches.set(JSON.stringify([credential.clientId, credential.refresh]), {
+      refresh: credential.refresh,
+      clientId: credential.clientId,
+    });
   }
   if (matches.size > 1)
     throw new Error("Conflicting native ChatGPT credentials match the active OpenAI runtime account.");
-  const refresh = matches.values().next().value;
-  if (!refresh)
+  const match = matches.values().next().value;
+  if (!match)
     throw new Error("The active OpenAI runtime account does not match an available native ChatGPT OAuth credential.");
   const authorization = `Bearer ${access}`;
   return {
+    openaiClientId: match.clientId,
     apiKey: access,
     headers: { Authorization: authorization },
     fingerprint: "",
-    secrets: [access, refresh, authorization],
+    secrets: [access, match.refresh, authorization, match.clientId],
     model,
   };
 }
 
-function accessToken(auth: RequestAuth | undefined): string | undefined {
+export function openAIAuthAccessToken(auth: RequestAuth | undefined): string | undefined {
   if (!auth) return undefined;
   const authorization = Object.entries(auth.headers ?? {}).filter(([name]) => name.toLowerCase() === "authorization");
   if (authorization.length > 1) throw new Error("OpenAI runtime authorization headers are ambiguous.");

package/src/providers/openai-companion-usage.ts

@@ -0,0 +1,146 @@
+import { fetchProviderJson } from "../query.js";
+import type { ResolvedUsageAuth, UsageBucket, UsageReport, UsageRequestGuard } from "../types.js";
+import { CHATGPT_USAGE_SETTINGS_URL } from "./openai-chatgpt.js";
+
+const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const MAX_APPS = 128;
+const MAX_WINDOWS = 32;
+
+// Evidence: pinned Specode openai.ts at 1015f9f419dfef9ac27c9845ec2318394928fa38
+// and OpenAI's Help Center article 20001542. Backend shapes remain undocumented.
+// Accept only a complete list; unknown list envelope fields fail closed, including pagination.
+export function matchingOpenAIAppBuckets(
+  payload: unknown,
+  clientId: string,
+): { buckets: UsageBucket[]; allowance?: number } {
+  const root = object(payload);
+  if (
+    !root ||
+    !Array.isArray(root.items) ||
+    root.items.length > MAX_APPS ||
+    Object.keys(root).some((key) => !["items", "has_more", "next_cursor"].includes(key)) ||
+    (root.has_more !== undefined && root.has_more !== false) ||
+    (root.next_cursor !== undefined && root.next_cursor !== null && root.next_cursor !== "")
+  ) {
+    throw new Error("ChatGPT app usage requires a complete, bounded registration list; pagination is unsupported.");
+  }
+  const apps = root.items.map(object);
+  if (apps.some((app) => !app || typeof app.id !== "string" || !app.id.trim())) {
+    throw new Error(
+      "ChatGPT app usage returned an unreadable registration identity; uniqueness cannot be established.",
+    );
+  }
+  const matches = apps.filter((app) => app?.id === clientId);
+  if (!clientId || matches.length !== 1) {
+    throw new Error(
+      "The native registration was not uniquely found in the companion Codex account; use the same ChatGPT account/workspace for both logins.",
+    );
+  }
+  const app = matches[0];
+  if (!Array.isArray(app?.windows) || app.windows.length === 0 || app.windows.length > MAX_WINDOWS) {
+    throw new Error("ChatGPT app usage returned no bounded, displayable windows.");
+  }
+  const allowance = app.allowed_usage_percent;
+  if (allowance !== undefined && !percent(allowance)) throw new Error("ChatGPT app allowance was invalid.");
+  return {
+    buckets: app.windows.map((window, index) => normalizeWindow(window, `app:${index}`, "chatgpt-app", "App limits")),
+    ...(allowance === undefined ? {} : { allowance: allowance as number }),
+  };
+}
+
+export async function queryOpenAICompanionUsage(
+  auth: ResolvedUsageAuth,
+  signal: AbortSignal,
+  timeoutMs: number,
+  guard?: UsageRequestGuard,
+): Promise<UsageReport> {
+  if (!guard) throw new Error("Companion ChatGPT usage requires request-boundary revalidation.");
+  if (!auth.openaiCompanion || !auth.openaiClientId)
+    throw new Error("Companion ChatGPT usage authentication was incomplete.");
+  const startedAt = Date.now();
+  // Never pass native apiKey/auth/env to transport: the only request credential is the companion.
+  const backend: ResolvedUsageAuth = {
+    headers: { ...auth.openaiCompanion.headers },
+    fingerprint: auth.fingerprint,
+    secrets: auth.secrets,
+    model: auth.model,
+  };
+  const read = async (url: string, description: string) => {
+    signal.throwIfAborted();
+    await guard();
+    signal.throwIfAborted();
+    const remaining = timeoutMs - (Date.now() - startedAt);
+    if (remaining <= 0) throw new Error("Timed out while fetching companion ChatGPT usage.");
+    const payload = await fetchProviderJson(url, backend, signal, remaining, description, { redirect: "error" });
+    await guard();
+    signal.throwIfAborted();
+    return payload;
+  };
+  const appPayload = await read(`${USAGE_URL}/chatpass/apps`, "ChatGPT companion app usage endpoint");
+  const app = matchingOpenAIAppBuckets(appPayload, auth.openaiClientId);
+  // Match and validate the app before reading plan data; never substitute Codex-only quotas.
+  const planPayload = await read(USAGE_URL, "ChatGPT companion plan usage endpoint");
+  const rateLimit = object(planPayload.rate_limit);
+  const planBuckets: UsageBucket[] = [];
+  for (const position of ["primary", "secondary"] as const) {
+    const window = rateLimit?.[`${position}_window`];
+    if (window !== undefined && window !== null)
+      planBuckets.push(normalizeWindow(window, `plan:${position}`, "chatgpt-plan", "Plan limits"));
+  }
+  if (planBuckets.length === 0) throw new Error("ChatGPT plan usage returned no displayable windows.");
+  return {
+    providerId: "openai",
+    providerName: "OpenAI",
+    capturedAt: Date.now(),
+    source: "openai-chatgpt-companion",
+    semantics: { kind: "consumer-subscription", label: "ChatGPT plan and app limits (experimental companion source)" },
+    buckets: [...planBuckets, ...app.buckets],
+    metrics:
+      app.allowance === undefined
+        ? []
+        : [{ id: "app-allowance", label: "App allowance", value: app.allowance, unit: "percent" }],
+    notes: [
+      "Source: companion Codex OAuth; registration matching is not independent proof of the same user/workspace.",
+      "App allowance caps shared plan usage; it is not remaining or reserved quota.",
+      `Manage usage: ${CHATGPT_USAGE_SETTINGS_URL}`,
+    ],
+  };
+}
+
+function normalizeWindow(raw: unknown, id: string, groupId: string, groupLabel: string): UsageBucket {
+  const window = object(raw);
+  const used = window?.used_percent;
+  const remaining = window?.remaining_percent;
+  const seconds = window?.limit_window_seconds;
+  const resetsAt = window?.reset_at;
+  if (
+    !percent(used) ||
+    (remaining !== undefined && (!percent(remaining) || Math.abs(used + remaining - 100) > 1)) ||
+    typeof seconds !== "number" ||
+    !Number.isSafeInteger(seconds) ||
+    seconds <= 0 ||
+    (resetsAt !== undefined &&
+      (typeof resetsAt !== "number" || !Number.isSafeInteger(resetsAt) || resetsAt < 0 || resetsAt > 8_640_000_000_000))
+  ) {
+    throw new Error("ChatGPT usage returned an invalid or contradictory window.");
+  }
+  return {
+    id,
+    label: "Subscription limit",
+    groupId,
+    groupLabel,
+    used,
+    remaining: remaining === undefined ? 100 - used : (remaining as number),
+    limit: 100,
+    unit: "percent",
+    windowMinutes: Math.ceil(seconds / 60),
+    ...(resetsAt === undefined ? {} : { resetsAt: resetsAt as number }),
+  };
+}
+
+function percent(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100;
+}
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}

package/src/query.ts

@@ -340,6 +340,8 @@ export async function resolveUsageAuth(
   salt: Uint8Array = AUTH_FINGERPRINT_SALT,
   credentialReader: StoredCredentialReader = readStoredCredential,
   candidateReader?: OAuthCredentialCandidateReader,
+  /** @deprecated Companion resolution is automatic; this argument is ignored. */
+  _openaiCompanionUsage?: boolean,
 ): Promise<ResolvedUsageAuth | undefined> {
   if (ctx.model?.provider === adapter.id && !hasOfficialOrigin(ctx.model, adapter.id)) {
     throw new Error(
@@ -437,9 +439,11 @@ export async function resolveUsageAuth(
       ? await candidateReader(ctx, adapter.id)
       : fallbackOAuthCredentialCandidates(adapter.id, credentialReader);
     if (!offered.ok) throw new Error("OpenAI OAuth credential discovery failed closed.");
-    return finalize(
+    const native = finalize(
       resolveOpenAIChatGPTAuth(auth, providerResult.auth, providerResult.source, model, offered.candidates),
     );
+    const { resolveOpenAICompanionAuth } = await import("./openai-companion-auth.js");
+    return resolveOpenAICompanionAuth(ctx, native, salt, credentialReader, candidateReader);
   }
   if (adapter.id === "github-copilot") {
     const offered = candidateReader

package/src/types.ts

@@ -48,6 +48,9 @@ export interface UsageReport {
 }
 
 export interface ResolvedUsageAuth {
+  /** Native registration metadata stays local; only companion headers reach ChatGPT. */
+  openaiClientId?: string;
+  openaiCompanion?: { headers: Record<string, string> };
   apiKey?: string;
   headers: Record<string, string>;
   fingerprint: string;