@narumitw/pi-usage 0.61.1 → 0.62.0

package/docs/providers.md

@@ -5,6 +5,7 @@
 This reference preserves each provider's endpoint, authentication boundary, billing semantics, and contract evidence.
 The README contains the capability overview and shared security requirements.
 
+- [OpenAI native ChatGPT OAuth](#openai-native-chatgpt-oauth)
 - [OpenAI Codex](#openai-codex)
 - [Kimi For Coding](#kimi-for-coding)
 - [Moonshot AI](#moonshot-ai-api-balance)
@@ -21,9 +22,57 @@ The README contains the capability overview and shared security requirements.
 
 ## 📋 Provider semantics
 
+### OpenAI native ChatGPT OAuth
+
+- Provider ID: `openai`
+- Default semantics/source: verified native authentication through fresh Pi OAuth resolution and an exact complete credential match; no usage HTTP endpoint
+- Default display: **Connected (native OAuth)** and [ChatGPT usage settings](https://chatgpt.com/settings/usage)
+- Default statusline: `chatgpt usage: web only`
+- Opt-in source: experimental same-account Codex companion OAuth; distinct shared plan and app limits
+
+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.
+Equivalent duplicate candidates are accepted; conflicting, incomplete, or mismatched native grants fail closed.
+Stored OAuth alone and Pi's cached OAuth flag do not establish the active runtime account.
+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 default report verifies authentication, not the plan tier, allowance, remaining quota, or reset time.
+Default automatic refresh only revalidates auth; it does not poll a usage endpoint.
+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, 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.
+
+#### Experimental companion quotas
+
+Follow the [opt-in setup](../README.md#experimental-chatgpt-companion-usage): `openaiCompanionUsage` defaults to `false` and requires a same-account/workspace `/login openai-codex`.
+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.
+
+Disabled or missing-companion paths remain web-only without requests. Other enabled-mode 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 are undocumented; live availability and numerical agreement 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
 
-- Provider ID: `openai-codex`
+- Provider ID: `openai-codex` (legacy; not an alias for native `openai`)
 - Semantics: ChatGPT consumer subscription limits
 - Source: the Codex usage and earned-reset endpoints using Pi's resolved runtime authorization
 - Displayed data: returned duration-based windows, resets, credits, earned usage-limit resets, and additional model buckets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-usage",
-  "version": "0.61.1",
+  "version": "0.62.0",
   "description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
   "type": "module",
   "license": "MIT",
@@ -57,10 +57,10 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.86.0",
-    "@earendil-works/pi-coding-agent": "0.86.0",
-    "@earendil-works/pi-tui": "0.86.0",
-    "@types/node": "26.6.2",
+    "@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

@@ -21,12 +21,15 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
                 ? report.source === "minimax-account-balance"
                   ? `${report.providerName} API Balance`
                   : `${report.providerName} Token Plan`
-                : `${report.providerName} Usage`;
+                : report.source === "openai-chatgpt-auth"
+                  ? `${report.providerName} ChatGPT Plan Status`
+                  : `${report.providerName} Usage`;
   const lines = [`${title} · ${stateLabel}`];
   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);
@@ -57,6 +60,20 @@ export function formatUsageStatusline(
   showCodexResetCountdown = true,
   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);
+            return `${bucket.remaining === undefined ? "unavailable" : `${bucket.remaining.toFixed(0)}%`} ${reset ? `↻ ${reset}` : formatWindowLabel(bucket.windowMinutes, "weekly", true)}`;
+          });
+        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);
@@ -519,6 +536,19 @@ 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)) {
+      lines.push(
+        `${formatWindowLabel(bucket.windowMinutes, "weekly", false).padEnd(VALUE_COLUMN)}${formatPercentBucket(bucket)}`,
+      );
+    }
+  }
+  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(
@@ -665,6 +695,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,103 @@
+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 opt-in 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,
+    openaiCompanionEnabled: true,
+    fingerprint: fingerprintResolvedAuth(
+      { apiKey: JSON.stringify([native.fingerprint, native.openaiClientId, true, 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,
+    openaiCompanionEnabled: true,
+    openaiCompanion: { headers },
+    fingerprint: fingerprintResolvedAuth(
+      { apiKey: JSON.stringify([native.fingerprint, native.openaiClientId, true, 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

@@ -0,0 +1,122 @@
+import type { PiModel, ResolvedUsageAuth, UsageProviderAdapter } from "../types.js";
+
+export const CHATGPT_USAGE_SETTINGS_URL = "https://chatgpt.com/settings/usage";
+const DIRECT_TOKEN_SCOPE = "chatgpt.tokens.use.direct";
+
+type RequestAuth = {
+  apiKey?: string;
+  headers?: Record<string, string | null>;
+};
+
+export class UnsupportedOpenAIUsageAuthError extends Error {
+  override readonly name = "UnsupportedOpenAIUsageAuthError";
+
+  constructor() {
+    super("OpenAI API-key usage reporting is not supported; ChatGPT plan status requires native /login openai OAuth.");
+  }
+}
+
+// Native Sign in with ChatGPT grants access to api.openai.com, not the legacy wham contract.
+// Report only verified authentication, never invented quotas or backend endpoint compatibility.
+// https://developers.openai.com/siwc/token-sharing-open-source/token-reference
+// https://developers.openai.com/siwc/ui-ux-guidelines
+export const OPENAI_CHATGPT_ADAPTER: UsageProviderAdapter = {
+  id: "openai",
+  displayName: "OpenAI",
+  semantics: { kind: "consumer-subscription", label: "ChatGPT plan authentication status" },
+  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();
+    signal.throwIfAborted();
+    return {
+      providerId: "openai",
+      providerName: "OpenAI",
+      capturedAt: Date.now(),
+      source: "openai-chatgpt-auth",
+      semantics: { kind: "consumer-subscription", label: "ChatGPT plan authentication status" },
+      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.",
+        `Manage usage: ${CHATGPT_USAGE_SETTINGS_URL}`,
+        ...(auth.openaiCompanionEnabled
+          ? [
+              "Experimental companion usage requires /login openai-codex with the same ChatGPT account/workspace; native inference stays on openai.",
+            ]
+          : []),
+        "Fast mode and earned reset redemption remain legacy openai-codex features.",
+      ],
+    };
+  },
+};
+
+export function resolveOpenAIChatGPTAuth(
+  auth: RequestAuth,
+  providerAuth: RequestAuth | undefined,
+  source: string | undefined,
+  model: PiModel,
+  candidates: readonly unknown[],
+): ResolvedUsageAuth {
+  // 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 = 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, { 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>;
+    if (credential.type !== "oauth" || credential.access !== access) continue;
+    if (
+      typeof credential.refresh !== "string" ||
+      !credential.refresh ||
+      typeof credential.expires !== "number" ||
+      !Number.isFinite(credential.expires) ||
+      typeof credential.clientId !== "string" ||
+      !credential.clientId.trim() ||
+      !Array.isArray(credential.scopes) ||
+      !credential.scopes.every((scope) => typeof scope === "string") ||
+      !credential.scopes.includes(DIRECT_TOKEN_SCOPE)
+    ) {
+      throw new Error(
+        "The matching OpenAI OAuth credential is not a complete native ChatGPT grant; reconnect with /login openai.",
+      );
+    }
+    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 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, match.refresh, authorization, match.clientId],
+    model,
+  };
+}
+
+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.");
+  // Explicit null or non-Bearer overrides must not fall back to the underlying OAuth apiKey.
+  if (authorization.length === 1) return /^Bearer\s+(.+)$/iu.exec(authorization[0]?.[1] ?? "")?.[1];
+  return auth.apiKey;
+}

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

@@ -12,6 +12,11 @@ import { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.j
 import { normalizeKimiCodingUsagePayload } from "./providers/kimi-coding.js";
 import { type MiniMaxProviderId, miniMaxUsageKind, normalizeMiniMaxUsagePayload } from "./providers/minimax.js";
 import { normalizeMoonshotBalancePayload } from "./providers/moonshot.js";
+import {
+  OPENAI_CHATGPT_ADAPTER,
+  resolveOpenAIChatGPTAuth,
+  UnsupportedOpenAIUsageAuthError,
+} from "./providers/openai-chatgpt.js";
 import { normalizeOpenCodeZenPayload } from "./providers/opencode-zen.js";
 import { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
 import { normalizeVercelAIGatewayCreditsPayload } from "./providers/vercel-ai-gateway.js";
@@ -95,6 +100,7 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
       return normalizeBasetenBillingUsagePayload(payload, Date.now());
     },
   },
+  OPENAI_CHATGPT_ADAPTER,
   {
     id: "openai-codex",
     displayName: "OpenAI Codex",
@@ -334,6 +340,7 @@ export async function resolveUsageAuth(
   salt: Uint8Array = AUTH_FINGERPRINT_SALT,
   credentialReader: StoredCredentialReader = readStoredCredential,
   candidateReader?: OAuthCredentialCandidateReader,
+  openaiCompanionUsage = false,
 ): Promise<ResolvedUsageAuth | undefined> {
   if (ctx.model?.provider === adapter.id && !hasOfficialOrigin(ctx.model, adapter.id)) {
     throw new Error(
@@ -344,7 +351,7 @@ export async function resolveUsageAuth(
   const model = candidateModels(ctx, adapter.id).find((candidate) => hasOfficialOrigin(candidate, adapter.id));
   if (!model) return undefined;
   if (
-    ["github-copilot", "xai"].includes(adapter.id) &&
+    ["github-copilot", "openai", "xai"].includes(adapter.id) &&
     candidateReader?.waitUntilReady &&
     !(await candidateReader.waitUntilReady(ctx, adapter.id))
   ) {
@@ -364,9 +371,11 @@ export async function resolveUsageAuth(
     if (!currentModel || typeof registry.getApiKeyAndHeaders !== "function") return undefined;
     const result = await registry.getApiKeyAndHeaders(currentModel);
     if (!result.ok) throw new Error(redactUsageError(result.error));
-    return authorizationFrom(result) ? result : undefined;
+    // Native plan status must inspect explicit empty/null Authorization overrides, not fall
+    // back to provider OAuth when the selected model removes or replaces its authorization.
+    return adapter.id === "openai" || authorizationFrom(result) ? result : undefined;
   };
-  const resolveSelectedAuthLast = ["deepseek", "minimax", "minimax-cn"].includes(adapter.id);
+  const resolveSelectedAuthLast = ["deepseek", "minimax", "minimax-cn", "openai"].includes(adapter.id);
   if (!resolveSelectedAuthLast) modelAuth = await resolveCurrentModelAuth();
   if (typeof registry.getProviderAuth !== "function") {
     throw new Error("pi-usage requires Pi 0.81.0 or newer to validate resolved provider auth.");
@@ -421,6 +430,21 @@ export async function resolveUsageAuth(
       ),
     };
   };
+  if (adapter.id === "openai") {
+    // Pi can return empty compatibility model auth without any provider credential.
+    if (!providerResult) return undefined;
+    if (providerResult.source !== "OAuth") throw new UnsupportedOpenAIUsageAuthError();
+    const offered = candidateReader
+      ? await candidateReader(ctx, adapter.id)
+      : fallbackOAuthCredentialCandidates(adapter.id, credentialReader);
+    if (!offered.ok) throw new Error("OpenAI OAuth credential discovery failed closed.");
+    const native = finalize(
+      resolveOpenAIChatGPTAuth(auth, providerResult.auth, providerResult.source, model, offered.candidates),
+    );
+    if (!openaiCompanionUsage) return native;
+    const { resolveOpenAICompanionAuth } = await import("./openai-companion-auth.js");
+    return resolveOpenAICompanionAuth(ctx, native, salt, credentialReader, candidateReader);
+  }
   if (adapter.id === "github-copilot") {
     const offered = candidateReader
       ? await candidateReader(ctx, adapter.id)
@@ -897,6 +921,7 @@ function hasOfficialUrlOrigin(value: string, providerId: string): boolean {
     if (providerId === "baseten") {
       return ["https://inference.baseten.co", "https://api.baseten.co"].includes(url.origin);
     }
+    if (providerId === "openai") return url.origin === "https://api.openai.com";
     if (providerId === "openai-codex") return url.origin === "https://chatgpt.com";
     if (providerId === "deepseek") return url.origin === "https://api.deepseek.com";
     if (providerId === "fireworks") return url.origin === "https://api.fireworks.ai";

package/src/settings.ts

@@ -12,6 +12,8 @@ export const MAX_USAGE_SETTINGS_BYTES = 64 * 1024;
 export type CodexStatusPercentage = "remaining" | "used";
 
 export interface UsageSettings {
+  /** Omitted values preserve default-off compatibility for injected settings runtimes. */
+  openaiCompanionUsage?: boolean;
   codexFastMode: boolean;
   codexStatusResetCountdown: boolean;
   codexStatusPercentage: CodexStatusPercentage;
@@ -19,6 +21,7 @@ export interface UsageSettings {
 }
 
 export const DEFAULT_USAGE_SETTINGS: Readonly<UsageSettings> = Object.freeze({
+  openaiCompanionUsage: false,
   codexFastMode: false,
   codexStatusResetCountdown: true,
   codexStatusPercentage: "remaining",
@@ -64,6 +67,7 @@ export function usageSettingsPath(): string {
 
 export function normalizeUsageSettings(value: unknown): UsageSettings | undefined {
   if (!isRecord(value)) return undefined;
+  if (Object.hasOwn(value, "openaiCompanionUsage") && typeof value.openaiCompanionUsage !== "boolean") return undefined;
   if (Object.hasOwn(value, "codexFastMode") && typeof value.codexFastMode !== "boolean") {
     return undefined;
   }
@@ -87,6 +91,7 @@ export function normalizeUsageSettings(value: unknown): UsageSettings | undefine
     effectiveTargets.fireworks = value.fireworksAccountId;
   }
   return {
+    openaiCompanionUsage: value.openaiCompanionUsage === true,
     codexFastMode:
       typeof value.codexFastMode === "boolean" ? value.codexFastMode : DEFAULT_USAGE_SETTINGS.codexFastMode,
     codexStatusResetCountdown:

package/src/types.ts

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