dsh-plugin-subscriptions 0.1.2 → 0.3.0

package/lib/index.js

@@ -454,6 +454,7 @@ async function dispatch(controller, endpoint, payload, signal) {
 		case "logout":
 			await controller.logout(readProvider(payload));
 			return ok({ ok: true });
+		case "usage": return ok(await controller.usage(readProvider(payload), signal));
 		case "image": return ok(await controller.readImage(readImageRef(payload), signal));
 		default: throw new BadRequest(`unknown /subscriptions-auth endpoint "${endpoint}"`);
 	}
@@ -1323,6 +1324,55 @@ async function refreshCodex(session) {
 function isCodexPermanentRefreshError(error) {
 	return error instanceof OAuthEndpointError && error.oauthCode !== void 0 && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+/** Map one wham/usage window into a {@link UsageWindow}; undefined when unusable. */
+function codexUsageWindow(value, kind) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const window = value;
+	if (typeof window.used_percent !== "number" || !Number.isFinite(window.used_percent)) return void 0;
+	let resetsAt;
+	if (typeof window.reset_at === "number" && window.reset_at > 0) resetsAt = window.reset_at * 1e3;
+	else if (typeof window.reset_after_seconds === "number" && window.reset_after_seconds > 0) resetsAt = Date.now() + window.reset_after_seconds * 1e3;
+	return {
+		kind,
+		usedPercent: window.used_percent,
+		...resetsAt === void 0 ? {} : { resetsAt }
+	};
+}
+/**
+* Fetch the codex subscription usage from the ChatGPT backend wham/usage
+* endpoint (the source of the codex CLI `/status` rate-limit lines). The
+* primary window is the rolling session (5-hour) lane, the secondary window
+* the weekly lane; the lookup itself consumes no rate-limit budget.
+* @param session - the stored session (used as-is; never refreshed here).
+* @param fetchFn - fetch implementation (injectable for tests).
+* @param signal - caller cancellation from the RPC transport.
+* @returns the mapped usage snapshot.
+*/
+async function fetchCodexUsage(session, fetchFn = fetch, signal) {
+	const response = await fetchFn(CODEX_USAGE_URL, {
+		headers: {
+			"authorization": `Bearer ${session.accessToken}`,
+			"chatgpt-account-id": session.accountId,
+			"originator": "codex_cli_rs",
+			"accept": "application/json",
+			...attributionHeaders()
+		},
+		...signal === void 0 ? {} : { signal }
+	});
+	if (!response.ok) throw await oauthEndpointError(response, "codex usage");
+	const payload = await response.json();
+	const windows = [];
+	const primary = codexUsageWindow(payload.rate_limit?.primary_window, "session");
+	const secondary = codexUsageWindow(payload.rate_limit?.secondary_window, "weekly");
+	if (primary !== void 0) windows.push(primary);
+	if (secondary !== void 0) windows.push(secondary);
+	return {
+		supported: true,
+		windows,
+		...typeof payload.plan_type === "string" && payload.plan_type.length > 0 ? { plan: payload.plan_type } : {}
+	};
+}
 const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models";
 /**
 * Client version sent on the /models catalog request. The backend gates the
@@ -1979,6 +2029,86 @@ async function refreshClaude(session) {
 function isClaudePermanentRefreshError(error) {
 	return error instanceof OAuthEndpointError && (error.oauthCode === "invalid_grant" || error.oauthCode === "invalid_token");
 }
+const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+/** RFC3339 `resets_at` value → epoch ms, or undefined when absent/unparsable. */
+function claudeResetsAt(value) {
+	if (typeof value !== "string" || value.length === 0) return void 0;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+/** Map one legacy `{utilization, resets_at}` bucket; undefined when null or unusable. */
+function claudeLegacyWindow(value, kind, scope) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const bucket = value;
+	if (typeof bucket.utilization !== "number" || !Number.isFinite(bucket.utilization)) return void 0;
+	const resetsAt = claudeResetsAt(bucket.resets_at);
+	return {
+		kind,
+		...scope === void 0 ? {} : { scope },
+		usedPercent: bucket.utilization,
+		...resetsAt === void 0 ? {} : { resetsAt }
+	};
+}
+/** Map the modern `limits` array; empty when absent or carrying nothing usable. */
+function claudeLimitsWindows(value) {
+	if (!Array.isArray(value)) return [];
+	const windows = [];
+	for (const raw of value) {
+		if (typeof raw !== "object" || raw === null) continue;
+		const entry = raw;
+		if (typeof entry.percent !== "number" || !Number.isFinite(entry.percent)) continue;
+		const kind = entry.kind === "session" ? "session" : entry.kind === "weekly_all" || entry.kind === "weekly_scoped" ? "weekly" : "other";
+		const scope = entry.scope?.model?.display_name;
+		const resetsAt = claudeResetsAt(entry.resets_at);
+		windows.push({
+			kind,
+			...typeof scope === "string" && scope.length > 0 ? { scope } : {},
+			usedPercent: entry.percent,
+			...resetsAt === void 0 ? {} : { resetsAt }
+		});
+	}
+	return windows;
+}
+/**
+* Fetch the claude subscription usage from the OAuth usage endpoint (the
+* source of Claude Code's `/usage` screen). Newer responses carry a
+* structured `limits` array; older ones the flat `five_hour`/`seven_day*`
+* buckets — both shapes are read, the array winning when it has entries.
+* @param session - the stored session (used as-is; never refreshed here).
+* @param fetchFn - fetch implementation (injectable for tests).
+* @param signal - caller cancellation from the RPC transport.
+* @returns the mapped usage snapshot.
+*/
+async function fetchClaudeUsage(session, fetchFn = fetch, signal) {
+	const response = await fetchFn(CLAUDE_USAGE_URL, {
+		headers: {
+			"authorization": `Bearer ${session.accessToken}`,
+			"anthropic-beta": "oauth-2025-04-20",
+			"user-agent": CLAUDE_CLI_USER_AGENT,
+			"accept": "application/json"
+		},
+		...signal === void 0 ? {} : { signal }
+	});
+	if (!response.ok) throw await oauthEndpointError(response, "claude usage");
+	const payload = await response.json();
+	const modern = claudeLimitsWindows(payload.limits);
+	if (modern.length > 0) return {
+		supported: true,
+		windows: modern
+	};
+	const windows = [];
+	const legacy = [
+		claudeLegacyWindow(payload.five_hour, "session"),
+		claudeLegacyWindow(payload.seven_day, "weekly"),
+		claudeLegacyWindow(payload.seven_day_opus, "weekly", "Opus"),
+		claudeLegacyWindow(payload.seven_day_sonnet, "weekly", "Sonnet")
+	];
+	for (const window of legacy) if (window !== void 0) windows.push(window);
+	return {
+		supported: true,
+		windows
+	};
+}
 /** The Claude 4.5 family accepts image input. */
 const CLAUDE_MODALITIES = ["text", "image"];
 /** Claude wire adapter: one instance serves the `claude` provider route. */
@@ -2131,6 +2261,33 @@ async function grokFlow() {
 		}
 	};
 }
+/**
+* Display names for the numeric `tier` claim xAI stamps on OAuth access
+* tokens (the `prod_auth.SubscriptionTier` proto enum; the mapping mirrors
+* grok-build's `jwt_tier_claim`). Unknown values fall through to the raw
+* number so a future tier still shows something.
+*/
+const GROK_TIER_NAMES = {
+	0: "Free",
+	1: "SuperGrok",
+	2: "X Basic",
+	3: "X Premium",
+	4: "X Premium+",
+	5: "SuperGrok Heavy",
+	6: "SuperGrok Lite",
+	7: "SuperGrok Plus"
+};
+/**
+* The subscription tier encoded in a grok access token's `tier` claim (no
+* verification — same trust posture as the other claim reads).
+* @param accessToken - the stored access token.
+* @returns the display tier name, or undefined when the claim is absent.
+*/
+function grokTierName(accessToken) {
+	const tier = decodeJwtPayload(accessToken)?.tier;
+	if (typeof tier !== "number" || !Number.isInteger(tier)) return void 0;
+	return GROK_TIER_NAMES[tier] ?? String(tier);
+}
 /** Pick a display account from an id token's claims. */
 function grokAccount(idToken) {
 	const payload = idToken === void 0 ? void 0 : decodeJwtPayload(idToken);
@@ -2213,6 +2370,66 @@ async function refreshGrok(session) {
 function isGrokPermanentRefreshError(error) {
 	return error instanceof OAuthEndpointError && error.oauthCode === "invalid_grant";
 }
+/**
+* The Grok Build CLI chat proxy's billing endpoint (the source of the CLI's
+* `/usage` "Usage limit" panel; see xai-org/grok-build
+* `extensions/billing.rs`). Forwards to the backend `GetGrokCreditsConfig`.
+*/
+const GROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+/** RFC3339 timestamp → epoch ms, or undefined when absent/unparsable. */
+function grokResetsAt(value) {
+	if (typeof value !== "string" || value.length === 0) return void 0;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+/**
+* Fetch the grok subscription usage from the Grok Build CLI chat proxy. The
+* newer credits config carries a ready-made percentage plus the current
+* (typically weekly) period; the legacy shape carries cent-valued
+* `monthlyLimit`/`used`, from which the percentage is derived.
+* @param session - the stored session (used as-is; never refreshed here).
+* @param fetchFn - fetch implementation (injectable for tests).
+* @param signal - caller cancellation from the RPC transport.
+* @returns the mapped usage snapshot.
+*/
+async function fetchGrokUsage(session, fetchFn = fetch, signal) {
+	const response = await fetchFn(GROK_BILLING_URL, {
+		headers: {
+			"authorization": `Bearer ${session.accessToken}`,
+			"x-xai-token-auth": "xai-grok-cli",
+			"accept": "application/json",
+			...attributionHeaders()
+		},
+		...signal === void 0 ? {} : { signal }
+	});
+	if (!response.ok) throw await oauthEndpointError(response, "grok billing");
+	const payload = await response.json();
+	const config = typeof payload.config === "object" && payload.config !== null ? payload.config : {};
+	const windows = [];
+	if (typeof config.creditUsagePercent === "number" && Number.isFinite(config.creditUsagePercent)) {
+		const kind = config.currentPeriod?.type === "USAGE_PERIOD_TYPE_WEEKLY" ? "weekly" : "other";
+		const resetsAt = grokResetsAt(config.currentPeriod?.end);
+		windows.push({
+			kind,
+			usedPercent: config.creditUsagePercent,
+			...resetsAt === void 0 ? {} : { resetsAt }
+		});
+	} else if (typeof config.monthlyLimit?.val === "number" && config.monthlyLimit.val > 0) {
+		const used = typeof config.used?.val === "number" ? config.used.val : 0;
+		const resetsAt = grokResetsAt(config.billingPeriodEnd);
+		windows.push({
+			kind: "other",
+			usedPercent: used / config.monthlyLimit.val * 100,
+			...resetsAt === void 0 ? {} : { resetsAt }
+		});
+	}
+	const plan = typeof payload.subscriptionTier === "string" && payload.subscriptionTier.length > 0 ? payload.subscriptionTier : grokTierName(session.accessToken);
+	return {
+		supported: true,
+		windows,
+		...plan === void 0 ? {} : { plan }
+	};
+}
 const GROK_MODELS_URL = "https://api.x.ai/v1/models";
 /**
 * Input modalities for one grok model: chat models (grok-4 family) accept
@@ -2222,6 +2439,58 @@ function grokModalities(id) {
 	return /code|embed/i.test(id) ? ["text"] : ["text", "image"];
 }
 /**
+* The Grok Build CLI chat proxy's model catalog — the only grok endpoint that
+* advertises reasoning capability. The `api.x.ai/v1/models` and
+* `/v1/language-models` payloads carry pricing, context, and aliases only, so
+* effort metadata must come from here (the same source the official CLI's
+* picker uses).
+*/
+const GROK_CLI_MODELS_URL = "https://cli-chat-proxy.grok.com/v1/models";
+/** Map one CLI catalog entry's reasoning fields, or undefined when unsupported. */
+function grokCliReasoning(entry) {
+	if (entry.supports_reasoning_effort !== true) return void 0;
+	const efforts = (entry.reasoning_efforts ?? []).filter((level) => typeof level.value === "string" && level.value.length > 0).map((level) => ({
+		id: ReasoningEffortId(level.value),
+		name: typeof level.label === "string" && level.label.length > 0 ? level.label : level.value,
+		...typeof level.description === "string" && level.description.length > 0 ? { description: level.description } : {}
+	}));
+	if (efforts.length === 0) return void 0;
+	const defaultEffort = typeof entry.reasoning_effort === "string" && efforts.some((effort) => effort.id === ReasoningEffortId(entry.reasoning_effort)) ? ReasoningEffortId(entry.reasoning_effort) : void 0;
+	return {
+		efforts,
+		...defaultEffort === void 0 ? {} : { defaultEffort }
+	};
+}
+/**
+* Fetch the CLI catalog and index its per-model metadata by model id.
+* @param session - the stored session (used as-is; never refreshed here).
+* @param fetchFn - fetch implementation (injectable for tests).
+* @returns model id → contributed metadata.
+*/
+async function fetchGrokCliCatalog(session, fetchFn = fetch) {
+	const response = await fetchFn(GROK_CLI_MODELS_URL, { headers: {
+		"authorization": `Bearer ${session.accessToken}`,
+		"x-xai-token-auth": "xai-grok-cli",
+		"accept": "application/json",
+		...attributionHeaders()
+	} });
+	if (!response.ok) throw await oauthEndpointError(response, "grok CLI catalog");
+	const payload = await response.json();
+	if (!Array.isArray(payload.data)) throw new Error("grok CLI catalog returned no data array");
+	const catalog = /* @__PURE__ */ new Map();
+	for (const entry of payload.data) {
+		if (typeof entry.id !== "string" || entry.id.length === 0) continue;
+		const reasoning = grokCliReasoning(entry);
+		catalog.set(entry.id, {
+			...typeof entry.name === "string" && entry.name.length > 0 ? { name: entry.name } : {},
+			...typeof entry.description === "string" && entry.description.length > 0 ? { description: entry.description } : {},
+			...typeof entry.context_window === "number" && entry.context_window > 0 ? { contextWindow: entry.context_window } : {},
+			...reasoning === void 0 ? {} : { reasoning }
+		});
+	}
+	return catalog;
+}
+/**
 * The /v1/models list also serves generation models that cannot chat
 * (grok-imagine-image*, grok-imagine-video*) and embedding models; the picker
 * must not offer them. Heuristic over the id substring, verified against the
@@ -2231,17 +2500,24 @@ function isChatModel(id) {
 	return !/imagine|image-|video|embed/i.test(id);
 }
 /**
-* Fetch the live grok model list.
+* Fetch the live grok model list, enriched with the CLI catalog's per-model
+* metadata (display name, context window, reasoning efforts). The api.x.ai
+* list stays authoritative for which models exist; the CLI catalog is
+* enrichment only, so its failure degrades to a plain list instead of taking
+* discovery down — models it does not cover simply expose no efforts.
 * @param session - the stored session (used as-is; never refreshed here).
 * @param fetchFn - fetch implementation (injectable for tests).
-* @returns discovered chat models in endpoint order (id doubles as the name).
+* @param onWarn - warning sink for a failed CLI catalog fetch.
+* @returns discovered chat models in endpoint order.
 */
-async function fetchGrokModels(session, fetchFn = fetch) {
-	const response = await fetchFn(GROK_MODELS_URL, { headers: {
+async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
+	const [response, cliCatalog] = await Promise.all([fetchFn(GROK_MODELS_URL, { headers: {
 		"authorization": `Bearer ${session.accessToken}`,
 		"accept": "application/json",
 		...attributionHeaders()
-	} });
+	} }), fetchGrokCliCatalog(session, fetchFn).catch((error) => {
+		onWarn?.(`grok CLI catalog fetch failed; reasoning efforts are unavailable (${errorChain(error)})`);
+	})]);
 	if (!response.ok) throw await oauthEndpointError(response, "grok models");
 	const payload = await response.json();
 	if (!Array.isArray(payload.data)) throw new Error("grok models endpoint returned no data array");
@@ -2253,7 +2529,8 @@ async function fetchGrokModels(session, fetchFn = fetch) {
 		seen.add(entry.id);
 		discovered.push({
 			id: entry.id,
-			name: entry.id
+			name: entry.id,
+			...cliCatalog?.get(entry.id)
 		});
 	}
 	if (discovered.length === 0) throw new Error("grok models endpoint returned an empty catalog");
@@ -2284,10 +2561,11 @@ var GrokAdapter = class extends LlmAdapter {
 		if (await this.options.tokens.peek() === void 0) return [];
 		if (!this.options.discovery) return this.staticModels(provider);
 		try {
-			return (await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn))).map((model) => ({
+			return (await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn))).map((model) => ({
 				provider,
 				id: model.id,
 				name: model.name,
+				...model.description === void 0 ? {} : { description: model.description },
 				inputModalities: grokModalities(model.id)
 			}));
 		} catch (error) {
@@ -2304,9 +2582,11 @@ var GrokAdapter = class extends LlmAdapter {
 			provider,
 			id: model,
 			name: discovered?.name ?? configured?.name ?? model,
+			...discovered?.description === void 0 ? {} : { description: discovered.description },
 			inputModalities: configured?.inputModalities ?? grokModalities(model),
-			context: { contextWindow: configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
-			defaultMaxTokens: configured?.maxTokens ?? GROK_DEFAULT_MAX_TOKENS
+			context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
+			defaultMaxTokens: configured?.maxTokens ?? GROK_DEFAULT_MAX_TOKENS,
+			...discovered?.reasoning === void 0 ? {} : { reasoning: discovered.reasoning }
 		});
 	}
 	async *stream(options) {
@@ -2339,6 +2619,7 @@ var GrokAdapter = class extends LlmAdapter {
 			tool_choice: "auto",
 			parallel_tool_calls: true,
 			...options.maxTokens !== void 0 ? { max_output_tokens: options.maxTokens } : {},
+			...options.reasoningEffort !== void 0 ? { reasoning: { effort: String(options.reasoningEffort) } } : {},
 			store: false,
 			stream: true
 		};
@@ -2893,29 +3174,24 @@ function accountOf(provider, session) {
 		case "grok": return session.account;
 	}
 }
-/** The subscription detail of a stored session (plan type), for the status endpoint. */
-function planOf(provider, session) {
-	if (session === void 0) return void 0;
-	switch (provider) {
-		case "codex": {
-			const codex = session;
-			return codex.planType ?? codexProfileClaims(codex.idToken).planType;
-		}
-		case "claude": return session.subscriptionType;
-		case "grok": return;
-	}
-}
 /**
 * Auth operations behind the `/subscriptions-auth` RPC channel: start/complete
-* OAuth attempts in the background, feed pasted codes, cancel, and log out.
+* OAuth attempts in the background, feed pasted codes, cancel, log out, and
+* answer usage lookups.
 */
 var SubscriptionsAuthController = class {
 	/** Last login failure per provider, surfaced as `detail` until the next success. */
 	lastError = /* @__PURE__ */ new Map();
-	constructor(flows, onAuthChanged, resolveAttachments) {
+	constructor(flows, onAuthChanged, resolveAttachments, usageFetchers = {}) {
 		this.flows = flows;
 		this.onAuthChanged = onAuthChanged;
 		this.resolveAttachments = resolveAttachments;
+		this.usageFetchers = usageFetchers;
+	}
+	usage(provider, signal) {
+		const fetcher = this.usageFetchers[provider];
+		if (fetcher === void 0) return Promise.resolve({ supported: false });
+		return fetcher(signal);
 	}
 	async readImage(ref, signal) {
 		const attachments = this.resolveAttachments();
@@ -2929,7 +3205,7 @@ var SubscriptionsAuthController = class {
 	async status(provider) {
 		const session = await getSession(provider);
 		const account = accountOf(provider, session);
-		const detail = this.lastError.get(provider) ?? planOf(provider, session);
+		const detail = this.lastError.get(provider);
 		return {
 			loggedIn: session !== void 0,
 			busy: this.flows.isBusy(provider),
@@ -3004,6 +3280,7 @@ function apply(ctx, config) {
 	};
 	let codexTokens;
 	let grokTokens;
+	const usageFetchers = {};
 	for (const provider of providers) switch (provider) {
 		case "codex": {
 			const tokens = new TokenManager({
@@ -3019,6 +3296,7 @@ function apply(ctx, config) {
 				}
 			});
 			codexTokens = tokens;
+			usageFetchers.codex = async (signal) => fetchCodexUsage(await tokens.session(), fetch, signal);
 			handles.set("codex", ctx.llm.registerAdapter(["codex"], new CodexAdapter({
 				models: catalog.codex,
 				streamIdleTimeoutMs,
@@ -3042,6 +3320,7 @@ function apply(ctx, config) {
 					authChanged("claude");
 				}
 			});
+			usageFetchers.claude = async (signal) => fetchClaudeUsage(await tokens.session(), fetch, signal);
 			handles.set("claude", ctx.llm.registerAdapter(["claude"], new ClaudeAdapter({
 				models: catalog.claude,
 				streamIdleTimeoutMs,
@@ -3064,6 +3343,7 @@ function apply(ctx, config) {
 				}
 			});
 			grokTokens = tokens;
+			usageFetchers.grok = async (signal) => fetchGrokUsage(await tokens.session(), fetch, signal);
 			handles.set("grok", ctx.llm.registerAdapter(["grok"], new GrokAdapter({
 				models: catalog.grok,
 				streamIdleTimeoutMs,
@@ -3075,7 +3355,7 @@ function apply(ctx, config) {
 			break;
 		}
 	}
-	registerAuthRpc(ctx, new SubscriptionsAuthController(flows, authChanged, resolveAttachments));
+	registerAuthRpc(ctx, new SubscriptionsAuthController(flows, authChanged, resolveAttachments, usageFetchers));
 	ctx.inject(["tools"], (toolsCtx) => {
 		if (grokTokens !== void 0) toolsCtx.tools.register(createXSearchTool({ tokens: grokTokens }));
 		if (codexTokens !== void 0) toolsCtx.tools.register(createImageGenerateTool({

package/lib/providers/claude.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { ClaudeSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { ModelEntry } from './common.js';
+import type { FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const CLAUDE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 export declare const CLAUDE_AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
 export declare const CLAUDE_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
@@ -40,6 +40,18 @@ export declare function refreshClaude(session: ClaudeSession): Promise<ClaudeSes
  * @returns true when re-login is the only fix.
  */
 export declare function isClaudePermanentRefreshError(error: unknown): boolean;
+export declare const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+/**
+ * Fetch the claude subscription usage from the OAuth usage endpoint (the
+ * source of Claude Code's `/usage` screen). Newer responses carry a
+ * structured `limits` array; older ones the flat `five_hour`/`seven_day*`
+ * buckets — both shapes are read, the array winning when it has entries.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export declare function fetchClaudeUsage(session: ClaudeSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
 /** Constructor dependencies for {@link ClaudeAdapter}. */
 export interface ClaudeAdapterOptions {
     models: readonly ModelEntry[];

package/lib/providers/claude.js

@@ -147,6 +147,95 @@ export function isClaudePermanentRefreshError(error) {
     return error instanceof OAuthEndpointError
         && (error.oauthCode === 'invalid_grant' || error.oauthCode === 'invalid_token');
 }
+export const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+/** RFC3339 `resets_at` value → epoch ms, or undefined when absent/unparsable. */
+function claudeResetsAt(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Map one legacy `{utilization, resets_at}` bucket; undefined when null or unusable. */
+function claudeLegacyWindow(value, kind, scope) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const bucket = value;
+    if (typeof bucket.utilization !== 'number' || !Number.isFinite(bucket.utilization))
+        return undefined;
+    const resetsAt = claudeResetsAt(bucket.resets_at);
+    return {
+        kind,
+        ...scope === undefined ? {} : { scope },
+        usedPercent: bucket.utilization,
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
+}
+/** Map the modern `limits` array; empty when absent or carrying nothing usable. */
+function claudeLimitsWindows(value) {
+    if (!Array.isArray(value))
+        return [];
+    const windows = [];
+    for (const raw of value) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const entry = raw;
+        if (typeof entry.percent !== 'number' || !Number.isFinite(entry.percent))
+            continue;
+        const kind = entry.kind === 'session'
+            ? 'session'
+            : entry.kind === 'weekly_all' || entry.kind === 'weekly_scoped' ? 'weekly' : 'other';
+        const scope = entry.scope?.model?.display_name;
+        const resetsAt = claudeResetsAt(entry.resets_at);
+        windows.push({
+            kind,
+            ...typeof scope === 'string' && scope.length > 0 ? { scope } : {},
+            usedPercent: entry.percent,
+            ...resetsAt === undefined ? {} : { resetsAt },
+        });
+    }
+    return windows;
+}
+/**
+ * Fetch the claude subscription usage from the OAuth usage endpoint (the
+ * source of Claude Code's `/usage` screen). Newer responses carry a
+ * structured `limits` array; older ones the flat `five_hour`/`seven_day*`
+ * buckets — both shapes are read, the array winning when it has entries.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export async function fetchClaudeUsage(session, fetchFn = fetch, signal) {
+    const response = await fetchFn(CLAUDE_USAGE_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            'anthropic-beta': 'oauth-2025-04-20',
+            // Unrecognized clients are aggressively rate-limited on this endpoint,
+            // so it presents as the CLI like every other subscription request.
+            'user-agent': CLAUDE_CLI_USER_AGENT,
+            'accept': 'application/json',
+        },
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'claude usage');
+    const payload = await response.json();
+    const modern = claudeLimitsWindows(payload.limits);
+    if (modern.length > 0)
+        return { supported: true, windows: modern };
+    const windows = [];
+    const legacy = [
+        claudeLegacyWindow(payload.five_hour, 'session'),
+        claudeLegacyWindow(payload.seven_day, 'weekly'),
+        claudeLegacyWindow(payload.seven_day_opus, 'weekly', 'Opus'),
+        claudeLegacyWindow(payload.seven_day_sonnet, 'weekly', 'Sonnet'),
+    ];
+    for (const window of legacy) {
+        if (window !== undefined)
+            windows.push(window);
+    }
+    return { supported: true, windows };
+}
 /** The Claude 4.5 family accepts image input. */
 const CLAUDE_MODALITIES = ['text', 'image'];
 /** Claude wire adapter: one instance serves the `claude` provider route. */

package/lib/providers/codex.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { CodexSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { DiscoveredModel, FetchFn, ModelEntry } from './common.js';
+import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 export declare const CODEX_AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
 export declare const CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
@@ -53,6 +53,18 @@ export declare function refreshCodex(session: CodexSession): Promise<CodexSessio
  * @returns true when re-login is the only fix.
  */
 export declare function isCodexPermanentRefreshError(error: unknown): boolean;
+export declare const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+/**
+ * Fetch the codex subscription usage from the ChatGPT backend wham/usage
+ * endpoint (the source of the codex CLI `/status` rate-limit lines). The
+ * primary window is the rolling session (5-hour) lane, the secondary window
+ * the weekly lane; the lookup itself consumes no rate-limit budget.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export declare function fetchCodexUsage(session: CodexSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
 export declare const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models";
 /**
  * Client version sent on the /models catalog request. The backend gates the