@narumitw/pi-usage 0.61.1 → 0.61.2

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,35 @@ The README contains the capability overview and shared security requirements.
 
 ## 📋 Provider semantics
 
+### 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`
+
+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 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.
+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`.
+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.
+
 ### 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.61.2",
   "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.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
+    "@types/node": "26.6.4",
     "esbuild": "0.28.2",
     "typescript": "7.0.2"
   },

package/src/format.ts

@@ -21,7 +21,9 @@ 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}`, "");
@@ -57,6 +59,7 @@ 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.providerId === "baseten") return formatBasetenStatusline(report);
   if (report.providerId === "openai-codex") {
     return formatCodexStatusline(report, model, now, showCodexResetCountdown, codexStatusPercentage);

package/src/providers/openai-chatgpt.ts

@@ -0,0 +1,107 @@
+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" },
+  async query(_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}`,
+        "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 = accessToken(auth);
+  if (!access || access !== accessToken(providerAuth)) {
+    throw new Error("The active OpenAI model authorization does not match its resolved OAuth credential.");
+  }
+  const matches = new Map<string, 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]), credential.refresh);
+  }
+  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)
+    throw new Error("The active OpenAI runtime account does not match an available native ChatGPT OAuth credential.");
+  const authorization = `Bearer ${access}`;
+  return {
+    apiKey: access,
+    headers: { Authorization: authorization },
+    fingerprint: "",
+    secrets: [access, refresh, authorization],
+    model,
+  };
+}
+
+function accessToken(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/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",
@@ -344,7 +350,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 +370,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 +429,18 @@ 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.");
+    return finalize(
+      resolveOpenAIChatGPTAuth(auth, providerResult.auth, providerResult.source, model, offered.candidates),
+    );
+  }
   if (adapter.id === "github-copilot") {
     const offered = candidateReader
       ? await candidateReader(ctx, adapter.id)
@@ -897,6 +917,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/usage.ts

@@ -21,6 +21,7 @@ import {
 import { abortError, awaitWithDeadline, errorMessage, runWithConcurrency, UsageCache } from "./core.js";
 import { formatProviderStates, formatUsageStatusline } from "./format.js";
 import { createOAuthCredentialCandidateReader } from "./oauth-credential-source.js";
+import { UnsupportedOpenAIUsageAuthError } from "./providers/openai-chatgpt.js";
 import { adapterForProvider, isStaleExtensionContextError, queryProviderUsage, resolveUsageAuth } from "./query.js";
 import { createUsageSettingsRuntime, type UsageSettingsRuntime, type UsageSettingsState } from "./settings.js";
 import type {
@@ -65,7 +66,7 @@ type UsageExtensionDependencies = {
 type QueryOutcome = {
   state: ProviderUsageState;
   fingerprint?: string;
-  authState?: "unavailable";
+  authState?: "unavailable" | "unsupported" | "failed";
   rememberedTargetId?: string;
 };
 
@@ -243,6 +244,12 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
       );
     } catch (error) {
       if (isStaleExtensionContextError(error) || isAbortError(error)) throw error;
+      const authState =
+        error instanceof UnsupportedOpenAIUsageAuthError
+          ? "unsupported"
+          : adapter.id === "openai" && !isTimeoutError(error)
+            ? "failed"
+            : undefined;
       if (displayState === "current") {
         transitionCurrentIdentity(`${adapter.id}:auth-error`, adapter.id);
       }
@@ -251,9 +258,11 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
           providerId: adapter.id,
           providerName,
           displayState,
-          status: isTimeoutError(error) ? "query-failed" : "auth-unavailable",
+          status:
+            authState === "unsupported" ? "unsupported" : isTimeoutError(error) ? "query-failed" : "auth-unavailable",
           message: errorMessage(error),
         },
+        ...(authState ? { authState } : {}),
       };
     }
     const requiresRequestBoundaryGuard =
@@ -265,6 +274,7 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
         "minimax-cn",
         "moonshotai",
         "moonshotai-cn",
+        "openai",
         "vercel-ai-gateway",
         "xai",
         "zai",
@@ -598,11 +608,11 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
     if (generation !== statusGeneration || modelIdentity(ctx.model) !== modelIdentity(model)) {
       return false;
     }
-    const adapter = adapterForProvider(model?.provider);
+    const adapter = adapterForProvider(outcome.state.providerId);
     const selectionStillCurrent =
       !adapter?.targets || settingsRuntime.get().settings.selectedTargets[adapter.id] === outcome.rememberedTargetId;
     if (!selectionStillCurrent) return false;
-    if (outcome.authState === "unavailable") {
+    if (outcome.authState) {
       if (!adapter) return false;
       try {
         const auth = await awaitWithDeadline(
@@ -616,11 +626,27 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
           modelIdentity(ctx.model) === modelIdentity(model) &&
           (!adapter.targets ||
             settingsRuntime.get().settings.selectedTargets[adapter.id] === outcome.rememberedTargetId) &&
+          outcome.authState === "unavailable" &&
           auth === undefined
         );
       } catch (error) {
         if (isAbortError(error) || isStaleExtensionContextError(error)) throw error;
-        return false;
+        // Stable failures are still useful. A recovered credential or changed reason must
+        // retry, but confirming the same native failure must not create a refresh loop.
+        const unchangedFailure =
+          (outcome.authState === "unsupported" && error instanceof UnsupportedOpenAIUsageAuthError) ||
+          (outcome.authState === "failed" &&
+            outcome.state.status === "auth-unavailable" &&
+            !(error instanceof UnsupportedOpenAIUsageAuthError) &&
+            !isTimeoutError(error) &&
+            errorMessage(error) === outcome.state.message);
+        return (
+          unchangedFailure &&
+          generation === statusGeneration &&
+          modelIdentity(ctx.model) === modelIdentity(model) &&
+          (!adapter.targets ||
+            settingsRuntime.get().settings.selectedTargets[adapter.id] === outcome.rememberedTargetId)
+        );
       }
     }
     if (!outcome.fingerprint) return true;
@@ -645,6 +671,27 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
     }
   };
 
+  const queryStableAdapterState = async (
+    ctx: ExtensionContext,
+    adapter: UsageProviderAdapter,
+    displayState: UsageDisplayState,
+    force: boolean,
+    signal: AbortSignal,
+  ): Promise<QueryOutcome> => {
+    if (adapter.id !== "openai") return queryAdapterState(ctx, adapter, displayState, force, signal);
+    // Configured/all-provider views must confirm native auth failures too, independently
+    // of the selected provider's subsequent revalidation.
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const model = ctx.model;
+      const generation = statusGeneration;
+      const outcome = await queryAdapterState(ctx, adapter, displayState, force, signal);
+      if (signal.aborted) throw abortError();
+      if (!outcome.authState || (await outcomeStillCurrent(ctx, model, generation, outcome, signal))) return outcome;
+      force = false;
+    }
+    throw new Error("OpenAI runtime authentication kept changing; reopen /usage to retry.");
+  };
+
   const queryStableCurrent = async (
     ctx: ExtensionCommandContext,
     force: boolean,
@@ -976,7 +1023,7 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
                 ctx,
                 `Checking ${providerDisplayName(ctx, adapter.id)} usage…`,
                 controller.signal,
-                (signal) => queryAdapterState(ctx, adapter, "configured", true, signal),
+                (signal) => queryStableAdapterState(ctx, adapter, "configured", true, signal),
               );
               if (!outcome) return { kind: "stay" };
               const revalidated = await queryStableCurrent(ctx, false, controller, "Revalidating current usage…");
@@ -1189,7 +1236,7 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
               ctx,
               `Checking ${providerDisplayName(ctx, adapter.id)} usage…`,
               controller.signal,
-              (signal) => queryAdapterState(ctx, adapter, "configured", false, signal),
+              (signal) => queryStableAdapterState(ctx, adapter, "configured", false, signal),
             );
             if (!outcome) return { kind: "back" };
             if (outcome.state.status === "selection-required") {
@@ -1200,7 +1247,7 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
                 ctx,
                 `Checking ${providerDisplayName(ctx, adapter.id)} usage…`,
                 controller.signal,
-                (signal) => queryAdapterState(ctx, adapter, "configured", true, signal),
+                (signal) => queryStableAdapterState(ctx, adapter, "configured", true, signal),
               );
               if (!outcome) return { kind: "back" };
             }
@@ -1227,7 +1274,7 @@ export default function usageExtension(pi: ExtensionAPI, dependencies: UsageExte
                   adapters,
                   ALL_PROVIDER_CONCURRENCY,
                   (adapter, _index, workerSignal) =>
-                    queryAdapterState(
+                    queryStableAdapterState(
                       ctx,
                       adapter,
                       adapter.id === currentProviderId ? "current" : "configured",