@justjoshn/pi-anthropic-oauth-v2 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Adds `/claude-usage`, which shows how much of each Claude subscription limit you have used and when it resets.
+
+## 0.1.0
+
+- First release. Registers `anthropic-oauth-v2`, a provider that uses only Claude subscription OAuth and is built on Pi's own Anthropic login, Messages API, and model catalog.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# pi-anthropic-oauth-v2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This Pi extension lets you use a Claude subscription in Pi. It authenticates only with the subscription OAuth token from your claude.ai login. Pro, Max, Ultra, and Team (Standard or Premium) logins all work the same way.
+
+It registers the provider `anthropic-oauth-v2`, built from Pi's own parts. Pi supplies them to extensions through `@earendil-works/pi-ai/providers/all`:
+
+- **Login and refresh:** Pi's built-in Anthropic OAuth flow, with browser or copy-code login. Pi's credential store refreshes the token under its lock and saves it in `~/.pi/agent/auth.json` under `anthropic-oauth-v2`.
+- **Requests:** Pi's Anthropic Messages implementation. It sends an OAuth token as a Bearer credential, with the Claude Code identity that Anthropic requires for subscription tokens.
+- **Models:** Pi's built-in Anthropic catalog, listed under `anthropic-oauth-v2/`.
+
+The extension adds only the OAuth-only check below. Pi's built-in `anthropic` provider is unchanged.
+
+## OAuth only
+
+The provider has no API-key handler, so Pi never reads `ANTHROPIC_API_KEY`, `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, workload identity federation, a stored `api_key` credential, or an API-key override for it. Pi still layers `models.json` settings (`apiKey`, `headers`, `modelOverrides`) onto every provider, so the provider checks the final request just before it is sent. It refuses the request unless the credential is an `sk-ant-oat` access token, no pre-built SDK client is passed in, and every added header is `anthropic-beta` or `anthropic-version` with no `sk-ant-` key in its value. That covers headers set through Pi's `models.json` `headers` setting. Pi itself adds no headers on this path. The provider also refuses every request while `ANTHROPIC_CUSTOM_HEADERS` is set, because the Anthropic SDK reads that variable on its own and Pi does not document it. `test/oauth-only.test.ts` and `scripts/prove.sh` check this, including against a local server that records what actually arrives.
+
+## Replaces the old Claude login
+
+This extension replaces `@justjoshn/pi-anthropic-oauth` (provider `claude-subscription`) and Pi's built-in `anthropic` login. Keep only one Claude login. If two Claude providers are logged in at once, they offer the same model ids, so Pi and pi-pstack reject bare model names like `sonnet` or `claude-opus-5-5` as ambiguous. Remove the others first:
+
+```bash
+pi remove npm:@justjoshn/pi-anthropic-oauth
+pi auth logout claude-subscription
+pi auth logout anthropic
+```
+
+`scripts/prove.sh` checks that bare model names reach `anthropic-oauth-v2` when it is the only Claude login.
+
+## Install and use
+
+Install the package and start Pi:
+
+```bash
+pi install npm:@justjoshn/pi-anthropic-oauth-v2
+pi
+```
+
+To try it from this checkout, use `pi -e extensions/pi-anthropic-oauth-v2`.
+
+Run `/login`, choose **Anthropic (Claude subscription, OAuth)**, and sign in with your claude.ai account. Then pick an `anthropic-oauth-v2/...` model with `/model`.
+
+This needs Pi 1.5.2 or later.
+
+## Check your usage
+
+Run `/claude-usage` to see how much of your plan's limits you have used. Pi has no built-in usage check, so the extension adds this command. It reads your stored login through Pi, asks Anthropic's subscription usage endpoint (`GET https://api.anthropic.com/api/oauth/usage`), and shows one line per limit:
+
+```text
+Current session: 19% used, resets in 15m
+Current week (all models): 78% used, resets in 1d 15h 55m
+Current week (Fable): 0% used, resets in 1d 15h 55m
+```
+
+The rows, their order, and the model names come from Anthropic, so a new limit shows up without an extension update. The notice turns into a warning when Anthropic marks any limit above normal. With no login, or with a credential that is not a subscription OAuth token, the command sends nothing and asks you to run `/login`. In print mode (`pi -p "/claude-usage"`) the lines go to stderr.
+
+The command is `/claude-usage`, not `/usage`, because `pi-x-subscription-oauth` already registers `/usage`. Pi renames clashing commands to `/usage:1` and `/usage:2`.
+
+## Check it
+
+```bash
+bun run test            # OAuth-only rule through pi-ai's real auth and stream paths
+scripts/prove.sh        # real pi: registration, OAuth-only refusals, leanness, /claude-usage without a login
+scripts/prove.sh --live # also a real /claude-usage, a real request, a tool call, and a forced token refresh (needs /login first)
+```

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@justjoshn/pi-anthropic-oauth-v2",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Use your Claude subscription in Pi through subscription OAuth only, built on Pi's own Anthropic login and Messages API.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/just-joshn/pi-customizations.git",
+    "directory": "extensions/pi-anthropic-oauth-v2"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p .",
+    "prove": "scripts/prove.sh",
+    "prove:live": "scripts/prove.sh --live"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.5.2",
+    "@earendil-works/pi-coding-agent": "1.5.2",
+    "@types/node": "^22.19.0",
+    "@vitest/coverage-v8": "^5.0.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+import { anthropicMessagesApi, type ProviderStreams } from '@earendil-works/pi-ai/compat';
+import { createProvider, hasApi } from '@earendil-works/pi-ai/models';
+import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { createUsageCommand } from './usage.ts';
+
+const ID = 'anthropic-oauth-v2';
+
+type StreamArgs = Parameters<ProviderStreams['stream']>;
+
+const ALLOWED_HEADERS = new Set(['anthropic-beta', 'anthropic-version']);
+const isAllowedHeader = ([name, value]: [string, string | null]) => value === null || (ALLOWED_HEADERS.has(name.toLowerCase()) && !value.includes('sk-ant-'));
+
+const assertOAuthOnly = (model: StreamArgs[0], options: StreamArgs[2]) => {
+  const headers = Object.entries({ ...model.headers, ...options?.headers });
+  const usesOwnClient = options !== undefined && 'client' in options;
+  // The Anthropic SDK also reads ANTHROPIC_CUSTOM_HEADERS into every request.
+  const setsSdkHeaders = Boolean(process.env['ANTHROPIC_CUSTOM_HEADERS']?.trim());
+  if (!options?.apiKey?.startsWith('sk-ant-oat') || usesOwnClient || setsSdkHeaders || !headers.every(isAllowedHeader)) {
+    throw new Error(`${ID}: refusing non-OAuth credential; run /login and remove any apiKey and any headers other than anthropic-beta or anthropic-version for ${ID} from models.json, and unset ANTHROPIC_CUSTOM_HEADERS`);
+  }
+};
+
+export default function (pi: Pick<ExtensionAPI, 'registerProvider' | 'registerCommand'>) {
+  const anthropic = builtinProviders().find((provider) => provider.id === 'anthropic');
+  const oauth = anthropic?.auth.oauth;
+  if (!anthropic || !oauth) throw new Error(`${ID}: this Pi build has no Anthropic OAuth login`);
+  const api = anthropicMessagesApi();
+
+  pi.registerProvider(
+    createProvider({
+      id: ID,
+      name: 'Anthropic (Claude subscription)',
+      auth: { oauth: { ...oauth, name: 'Anthropic (Claude subscription, OAuth)' } },
+      models: anthropic
+        .getModels()
+        .filter((model) => hasApi(model, 'anthropic-messages'))
+        .map((model) => ({ ...model, provider: ID, compat: { supportsMessageThreads: true, ...model.compat } })),
+      api: {
+        ...api,
+        stream: (model, context, options) => {
+          assertOAuthOnly(model, options);
+          return api.stream(model, context, options);
+        },
+        streamSimple: (model, context, options) => {
+          assertOAuthOnly(model, options);
+          return api.streamSimple(model, context, options);
+        },
+      },
+    }),
+  );
+  pi.registerCommand('claude-usage', createUsageCommand(ID));
+}

package/src/usage.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+
+type UsageRow = { title: string; percent: number; resetsAt: unknown; severity: unknown };
+
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+const RELOGIN = 'Run /login and choose Anthropic (Claude subscription, OAuth).';
+const GROUP_TITLES: Record<string, string> = { session: 'Current session', weekly: 'Current week' };
+// Servers that predate limits[] send only these windows.
+const WINDOWS = [
+  ['five_hour', 'Current session'],
+  ['seven_day', 'Current week (all models)'],
+  ['seven_day_sonnet', 'Current week (Sonnet)'],
+  ['seven_day_opus', 'Current week (Opus)'],
+] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+const displayName = (value: unknown) => (isRecord(value) && typeof value['display_name'] === 'string' ? value['display_name'] : undefined);
+
+function limitRow(limit: unknown): UsageRow[] {
+  if (!isRecord(limit) || typeof limit['percent'] !== 'number') return [];
+  const group = String(limit['group']);
+  const base = GROUP_TITLES[group] ?? group;
+  const scope = isRecord(limit['scope']) ? (displayName(limit['scope']['model']) ?? displayName(limit['scope']['surface'])) : undefined;
+  const title = scope ? `${base} (${scope})` : limit['kind'] === 'weekly_all' ? `${base} (all models)` : base;
+  return [{ title, percent: limit['percent'], resetsAt: limit['resets_at'], severity: limit['severity'] }];
+}
+
+function parseUsage(body: unknown): UsageRow[] | undefined {
+  if (!isRecord(body)) return undefined;
+  const limits = body['limits'];
+  if (Array.isArray(limits)) return limits.flatMap(limitRow);
+  if (limits !== undefined && limits !== null) return undefined;
+  return WINDOWS.flatMap(([key, title]) => {
+    const window = body[key];
+    return isRecord(window) && typeof window['utilization'] === 'number' ? [{ title, percent: window['utilization'], resetsAt: window['resets_at'], severity: 'normal' }] : [];
+  });
+}
+
+function resetsIn(resetsAt: unknown): string {
+  const at = typeof resetsAt === 'string' ? Date.parse(resetsAt) : Number.NaN;
+  if (Number.isNaN(at)) return '';
+  const minutes = Math.max(0, Math.round((at - Date.now()) / 60_000));
+  const days = Math.floor(minutes / 1_440);
+  const hours = Math.floor((minutes % 1_440) / 60);
+  const left = days > 0 ? `${days}d ${hours}h ${minutes % 60}m` : hours > 0 ? `${hours}h ${minutes % 60}m` : `${minutes}m`;
+  return `, resets in ${left}`;
+}
+
+const formatRow = (row: UsageRow) => `${row.title}: ${Number(row.percent.toFixed(1))}% used${resetsIn(row.resetsAt)}`;
+
+async function fetchUsage(token: string): Promise<UsageRow[]> {
+  const response = await fetch(USAGE_URL, {
+    headers: { Authorization: `Bearer ${token}`, 'anthropic-beta': 'oauth-2025-04-20' },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (response.status === 401 || response.status === 403) throw new Error(`Claude rejected the login (HTTP ${response.status}). ${RELOGIN}`);
+  if (!response.ok) throw new Error(`Claude usage check failed (HTTP ${response.status}).`);
+  const rows = parseUsage(await response.json().catch(() => undefined));
+  if (!rows) throw new Error('Claude returned usage Pi cannot read.');
+  return rows;
+}
+
+function report(ctx: ExtensionCommandContext, text: string, level: 'info' | 'warning' | 'error') {
+  if (ctx.hasUI) ctx.ui.notify(text, level);
+  else process.stderr.write(`${text}\n`);
+}
+
+export function createUsageCommand(providerId: string): Parameters<ExtensionAPI['registerCommand']>[1] {
+  return {
+    description: 'Show Claude subscription usage limits',
+    handler: async (_args, ctx) => {
+      try {
+        const token = (await ctx.modelRegistry.getProviderAuth(providerId))?.auth.apiKey;
+        if (!token?.startsWith('sk-ant-oat')) return report(ctx, `Claude is not logged in. ${RELOGIN}`, 'error');
+        const rows = await fetchUsage(token);
+        if (rows.length === 0) return report(ctx, 'Claude reported no usage limits for this plan.', 'info');
+        const level = rows.some((row) => row.severity !== 'normal') ? 'warning' : 'info';
+        report(ctx, rows.map(formatRow).join('\n'), level);
+      } catch (error) {
+        report(ctx, error instanceof Error ? error.message : String(error), 'error');
+      }
+    },
+  };
+}