dsh-plugin-subscriptions 0.1.2 → 0.3.0

package/lib/providers/codex.js

@@ -188,6 +188,62 @@ export function isCodexPermanentRefreshError(error) {
         && error.oauthCode !== undefined
         && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
+export 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 undefined;
+    const window = value;
+    if (typeof window.used_percent !== 'number' || !Number.isFinite(window.used_percent))
+        return undefined;
+    let resetsAt;
+    if (typeof window.reset_at === 'number' && window.reset_at > 0) {
+        resetsAt = window.reset_at * 1000;
+    }
+    else if (typeof window.reset_after_seconds === 'number' && window.reset_after_seconds > 0) {
+        resetsAt = Date.now() + window.reset_after_seconds * 1000;
+    }
+    return { kind, usedPercent: window.used_percent, ...resetsAt === undefined ? {} : { 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.
+ */
+export 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 === undefined ? {} : { 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 !== undefined)
+        windows.push(primary);
+    if (secondary !== undefined)
+        windows.push(secondary);
+    return {
+        supported: true,
+        windows,
+        ...typeof payload.plan_type === 'string' && payload.plan_type.length > 0
+            ? { plan: payload.plan_type }
+            : {},
+    };
+}
 export const CODEX_MODELS_URL = 'https://chatgpt.com/backend-api/codex/models';
 /**
  * Client version sent on the /models catalog request. The backend gates the

package/lib/providers/common.d.ts

@@ -135,6 +135,26 @@ export declare class TokenManager<S extends TimedSession> {
 }
 /** Fetch signature adapters accept for discovery calls (injectable for tests). */
 export type FetchFn = typeof fetch;
+/** One rate-limit window reported by a provider's usage endpoint. */
+export interface UsageWindow {
+    /** Window kind: `session` for the short rolling window, `weekly` for the 7-day one. */
+    kind: 'session' | 'weekly' | 'other';
+    /** Model scope for model-specific windows (e.g. `Opus`), when the provider names one. */
+    scope?: string;
+    /** Percent of the window already consumed (0–100). */
+    usedPercent: number;
+    /** Epoch milliseconds at which the window resets, when the provider discloses it. */
+    resetsAt?: number;
+}
+/** Subscription usage of one provider, as served by the `usage` RPC endpoint. */
+export interface ProviderUsage {
+    /** False when the provider has no usage endpoint (grok); windows are absent then. */
+    supported: boolean;
+    /** Usage windows in display order. */
+    windows?: UsageWindow[];
+    /** Plan name the usage endpoint reported, when present. */
+    plan?: string;
+}
 /** One model discovered from a provider's live model-list endpoint. */
 export interface DiscoveredModel {
     /** Wire model id. */

package/lib/providers/grok.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { GrokSession } 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 GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
 export declare const GROK_API_URL = "https://api.x.ai/v1/responses";
@@ -31,6 +31,13 @@ export declare function grokDiscovery(): Promise<GrokDiscovery>;
  * @returns the flow spec for one attempt.
  */
 export declare function grokFlow(): Promise<FlowSpec>;
+/**
+ * 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.
+ */
+export declare function grokTierName(accessToken: string): string | undefined;
 /**
  * Exchange an authorization code for a grok session (form-encoded grant that
  * echoes the PKCE challenge as well as the verifier, per the xAI flow).
@@ -54,14 +61,53 @@ export declare function refreshGrok(session: GrokSession): Promise<GrokSession>;
  * @returns true when re-login is the only fix.
  */
 export declare function isGrokPermanentRefreshError(error: unknown): boolean;
+/**
+ * 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`.
+ */
+export declare const GROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+/**
+ * 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.
+ */
+export declare function fetchGrokUsage(session: GrokSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
 export declare const GROK_MODELS_URL = "https://api.x.ai/v1/models";
 /**
- * Fetch the live grok model list.
+ * 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).
+ */
+export declare const GROK_CLI_MODELS_URL = "https://cli-chat-proxy.grok.com/v1/models";
+/** Per-model metadata the CLI catalog contributes to a discovered model. */
+type GrokCliModelMeta = Partial<Pick<DiscoveredModel, 'name' | 'description' | 'contextWindow' | 'reasoning'>>;
+/**
+ * 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.
+ */
+export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: FetchFn): Promise<Map<string, GrokCliModelMeta>>;
+/**
+ * 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.
  */
-export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn): Promise<DiscoveredModel[]>;
+export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void): Promise<DiscoveredModel[]>;
 /** Constructor dependencies for {@link GrokAdapter}. */
 export interface GrokAdapterOptions {
     models: readonly ModelEntry[];
@@ -88,3 +134,4 @@ export declare class GrokAdapter extends LlmAdapter {
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     private request;
 }
+export {};

package/lib/providers/grok.js

@@ -3,7 +3,7 @@
  * auth.x.ai with the Grok CLI client id, and streaming against the xAI
  * Responses-style endpoint.
  */
-import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
+import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
@@ -80,6 +80,34 @@ export 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.
+ */
+export function grokTierName(accessToken) {
+    const tier = decodeJwtPayload(accessToken)?.tier;
+    if (typeof tier !== 'number' || !Number.isInteger(tier))
+        return undefined;
+    return GROK_TIER_NAMES[tier] ?? String(tier);
+}
 /** Pick a display account from an id token's claims. */
 function grokAccount(idToken) {
     const payload = idToken === undefined ? undefined : decodeJwtPayload(idToken);
@@ -172,6 +200,73 @@ export async function refreshGrok(session) {
 export 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`.
+ */
+export 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 undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * 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.
+ */
+export async function fetchGrokUsage(session, fetchFn = fetch, signal) {
+    const response = await fetchFn(GROK_BILLING_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            // The proxy only honors bearer tokens presented as the Grok CLI.
+            'x-xai-token-auth': 'xai-grok-cli',
+            'accept': 'application/json',
+            ...attributionHeaders(),
+        },
+        ...signal === undefined ? {} : { 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 === undefined ? {} : { 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 === undefined ? {} : { resetsAt },
+        });
+    }
+    // The upstream billing response rarely carries `subscriptionTier` (the CLI
+    // enriches it locally from its settings cache), so the access token's
+    // `tier` claim is the working fallback.
+    const plan = typeof payload.subscriptionTier === 'string' && payload.subscriptionTier.length > 0
+        ? payload.subscriptionTier
+        : grokTierName(session.accessToken);
+    return {
+        supported: true,
+        windows,
+        ...plan === undefined ? {} : { plan },
+    };
+}
 export const GROK_MODELS_URL = 'https://api.x.ai/v1/models';
 /**
  * Input modalities for one grok model: chat models (grok-4 family) accept
@@ -181,28 +276,110 @@ function grokModalities(id) {
     return /code|embed/i.test(id) ? ['text'] : ['text', 'image'];
 }
 /**
- * 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
- * live catalog (grok-build-0.1 and the grok-4 family pass).
+ * 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).
  */
-function isChatModel(id) {
-    return !/imagine|image-|video|embed/i.test(id);
+export 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 undefined;
+    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 undefined;
+    // The per-entry `default` flags are unreliable (the live catalog marks
+    // several levels default at once), so the top-level `reasoning_effort`
+    // field is the trusted default.
+    const defaultEffort = typeof entry.reasoning_effort === 'string'
+        && efforts.some(effort => effort.id === ReasoningEffortId(entry.reasoning_effort))
+        ? ReasoningEffortId(entry.reasoning_effort)
+        : undefined;
+    return { efforts, ...defaultEffort === undefined ? {} : { defaultEffort } };
 }
 /**
- * Fetch the live grok model list.
+ * 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 discovered chat models in endpoint order (id doubles as the name).
+ * @returns model id → contributed metadata.
  */
-export async function fetchGrokModels(session, fetchFn = fetch) {
-    const response = await fetchFn(GROK_MODELS_URL, {
+export async function fetchGrokCliCatalog(session, fetchFn = fetch) {
+    const response = await fetchFn(GROK_CLI_MODELS_URL, {
         headers: {
             'authorization': `Bearer ${session.accessToken}`,
+            // The proxy only honors bearer tokens presented as the Grok CLI.
+            '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 = 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 === undefined ? {} : { 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
+ * live catalog (grok-build-0.1 and the grok-4 family pass).
+ */
+function isChatModel(id) {
+    return !/imagine|image-|video|embed/i.test(id);
+}
+/**
+ * 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).
+ * @param onWarn - warning sink for a failed CLI catalog fetch.
+ * @returns discovered chat models in endpoint order.
+ */
+export 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)})`);
+            return undefined;
+        }),
+    ]);
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok models');
     const payload = await response.json();
@@ -216,7 +393,7 @@ export async function fetchGrokModels(session, fetchFn = fetch) {
         if (!isChatModel(entry.id))
             continue;
         seen.add(entry.id);
-        discovered.push({ id: entry.id, name: entry.id });
+        discovered.push({ id: entry.id, name: entry.id, ...cliCatalog?.get(entry.id) });
     }
     // An empty catalog from a 200 response is treated as a discovery failure so
     // the adapter falls back to the static catalog instead of vanishing from
@@ -255,11 +432,12 @@ export class GrokAdapter extends LlmAdapter {
             // The fetcher runs only on a cache miss, and resolves the session
             // through the refresh-aware path so an expired access token renews here
             // instead of failing discovery into the static fallback.
-            const discovered = await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn));
+            const discovered = await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn));
             return discovered.map(model => ({
                 provider,
                 id: model.id,
                 name: model.name,
+                ...model.description === undefined ? {} : { description: model.description },
                 inputModalities: grokModalities(model.id),
             }));
         }
@@ -284,10 +462,14 @@ export class GrokAdapter extends LlmAdapter {
             provider,
             id: model,
             name: discovered?.name ?? configured?.name ?? model,
+            ...discovered?.description === undefined ? {} : { description: discovered.description },
             inputModalities: configured?.inputModalities ?? grokModalities(model),
-            context: { contextWindow: configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
+            context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
             defaultMaxTokens: configured?.maxTokens ?? GROK_DEFAULT_MAX_TOKENS,
-            // No reasoning metadata: effort selection is not exposed for grok.
+            // Efforts come from the discovered CLI catalog; models it does not
+            // cover expose none, so the harness rejects explicit efforts before
+            // provider I/O instead of the API 400ing.
+            ...discovered?.reasoning === undefined ? {} : { reasoning: discovered.reasoning },
         });
     }
     async *stream(options) {
@@ -327,6 +509,11 @@ export class GrokAdapter extends LlmAdapter {
             tool_choice: 'auto',
             parallel_tool_calls: true,
             ...options.maxTokens !== undefined ? { max_output_tokens: options.maxTokens } : {},
+            // The harness only passes an effort the resolved model advertised (the
+            // CLI catalog's), so this never reaches a model that rejects it.
+            ...options.reasoningEffort !== undefined
+                ? { reasoning: { effort: String(options.reasoningEffort) } }
+                : {},
             store: false,
             stream: true,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subscriptions",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Use ChatGPT (Codex), Claude, and Grok (X Premium) subscriptions as DeepSeek Harness LLM providers, with OAuth login from the web Settings page",
   "license": "MIT",
   "repository": {