dsh-plugin-subscription-oauth 0.0.0-stage → 0.2.0

package/lib/providers/kimi.js

@@ -0,0 +1,400 @@
+/**
+ * The `kimi` provider route: Kimi Code model catalog, request assembly over
+ * the OpenAI Responses wire, and streaming.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/kimi
+ */
+import { EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
+import { KIMI_CODE_URL, KIMI_CONTEXT_WINDOW, KIMI_DEFAULT_MAX_TOKENS, KIMI_DEFAULT_MODEL, KIMI_LONG_CONTEXT_WINDOW, KIMI_MODELS_PATH, KIMI_PROVIDER_ID, KIMI_PROVIDER_NAME, KIMI_RESPONSES_PATH, } from '../constants.js';
+import { proxiedFetch } from '../http.js';
+import { kimiRequestHeaders } from '../auth/headers.js';
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+import { finiteInstant, nonEmpty } from '../auth/store.js';
+import { idleWatchdog, httpLlmError, isMissingOrInvalidCredential, mapFetchFailure } from './common.js';
+import { streamProviderResponses } from './responses-stream.js';
+import { fallbackEntry, findEntry, resolveCatalog } from './catalog.js';
+import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
+/**
+ * Coerce one decoded credential entry into a Kimi session.
+ * @param value - decoded JSON value for one account.
+ * @returns the session, or undefined when required fields are missing.
+ */
+export function parseKimiSession(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const accessToken = nonEmpty(record.accessToken);
+    const oauthHost = nonEmpty(record.oauthHost);
+    const expiresAt = finiteInstant(record.expiresAt);
+    if (accessToken === undefined || oauthHost === undefined || expiresAt === undefined)
+        return undefined;
+    const refreshToken = nonEmpty(record.refreshToken);
+    const apiBase = nonEmpty(record.apiBase);
+    const accountId = nonEmpty(record.accountId);
+    const email = nonEmpty(record.email);
+    return {
+        accessToken,
+        expiresAt,
+        oauthHost,
+        ...refreshToken === undefined ? {} : { refreshToken },
+        ...apiBase === undefined ? {} : { apiBase },
+        ...accountId === undefined ? {} : { accountId },
+        ...email === undefined ? {} : { email },
+    };
+}
+/** Harness effort ids normalised onto the ladder Kimi's endpoint accepts. */
+const EFFORT_WIRE_MAP = {
+    none: 'none',
+    low: 'low',
+    medium: 'high',
+    high: 'high',
+    xhigh: 'max',
+    max: 'max',
+};
+/** Display metadata for the reasoning ladder shared by every live coding model. */
+const EFFORT_LABELS = {
+    none: { name: 'Off', description: 'Answer without spending thinking tokens' },
+    low: { name: 'Low', description: 'Short chain of thought' },
+    medium: { name: 'Medium', description: 'Balanced thinking budget' },
+    high: { name: 'High', description: 'Deep chain of thought' },
+    xhigh: { name: 'Max', description: 'Highest thinking budget Kimi accepts' },
+    max: { name: 'Max', description: 'Highest thinking budget Kimi accepts' },
+};
+/**
+ * Kimi Code's live coding catalog.
+ *
+ * `kimi-for-coding` is the stable subscription alias Moonshot re-points at each
+ * coding release; `k3` is the current flagship, with the `[1m]` suffix selecting
+ * its 1M-token window.
+ */
+export const KIMI_MODELS = [
+    {
+        id: 'kimi-for-coding',
+        name: 'Kimi for Coding',
+        description: 'Stable subscription alias — 1M-token window',
+        aliases: ['kimi-for-coding-highspeed', 'kimi-k2.7-code', 'kimi-k2.7-code-highspeed', 'kimi-k2.6', 'kimi-k2.5'],
+        contextWindow: KIMI_LONG_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+        reasoningEfforts: ['low', 'medium', 'high', 'max'],
+        defaultEffort: 'max',
+    },
+    {
+        id: 'k3',
+        name: 'Kimi K3',
+        description: 'Flagship reasoning model',
+        aliases: ['kimi-k3'],
+        contextWindow: KIMI_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+        reasoningEfforts: ['low', 'medium', 'high', 'max'],
+        defaultEffort: 'max',
+    },
+    {
+        id: 'k3[1m]',
+        name: 'Kimi K3 (1M)',
+        description: 'Flagship reasoning model with the 1M-token window',
+        contextWindow: KIMI_LONG_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+        reasoningEfforts: ['low', 'medium', 'high', 'max'],
+        defaultEffort: 'max',
+    },
+    {
+        id: 'k3-256k',
+        name: 'Kimi K3 (256K)',
+        description: 'Flagship reasoning model pinned to the standard window',
+        contextWindow: KIMI_CONTEXT_WINDOW,
+        inputModalities: ['text', 'image'],
+        reasoningEfforts: ['low', 'medium', 'high', 'max'],
+        defaultEffort: 'max',
+    },
+];
+/** One `reasoning.efforts` entry for a resolved model. */
+function effortInfo(effort) {
+    const label = EFFORT_LABELS[effort] ?? { name: effort, description: '' };
+    return { id: ReasoningEffortId(effort), name: label.name, description: label.description };
+}
+/** The reasoning block for a catalog entry, or undefined when it supports none. */
+function reasoningInfo(entry) {
+    const efforts = entry.reasoningEfforts;
+    if (efforts === undefined || efforts.length === 0)
+        return undefined;
+    const defaultEffort = entry.defaultEffort ?? efforts[efforts.length - 1];
+    return {
+        efforts: efforts.map(effortInfo),
+        ...defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(defaultEffort) },
+    };
+}
+/** Kimi Code adapter serving the `kimi` provider route. */
+export class KimiAdapter extends LlmAdapter {
+    options;
+    /** Live catalog ids seen this session, used to accept renamed models. */
+    discovered;
+    /** Ids the user added by hand, cached so the sync catalog can name them. */
+    userAddedIds = [];
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: KIMI_PROVIDER_NAME };
+    }
+    providerRetryPolicy() {
+        // Kimi reports its own pacing through 429 `retry-after`; a local retry
+        // ladder would fight the account-level rate limiter.
+        return undefined;
+    }
+    async listModels(_provider) {
+        // Nothing to offer without a signed-in account: a model that cannot be called
+        // must not appear in the picker, and Auto must not try it.
+        if (await this.options.tokens.session() === undefined)
+            return [];
+        await this.syncUserModels();
+        const hidden = await this.hidden();
+        return resolveCatalog(this.catalog(), [], hidden).entries.map((entry) => ({
+            provider: KIMI_PROVIDER_ID,
+            id: entry.id,
+            name: entry.name,
+            ...entry.description === undefined ? {} : { description: entry.description },
+            ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+        }));
+    }
+    /** The ids the picker must currently omit. */
+    async hidden() {
+        if (this.options.hiddenModels === undefined)
+            return new Set();
+        try {
+            return await this.options.hiddenModels();
+        }
+        catch (error) {
+            // A preferences read failure must not empty the picker.
+            this.options.onWarn?.(`model preferences unavailable (${errorChain(error)})`);
+            return new Set();
+        }
+    }
+    async resolveModel(_provider, model) {
+        await this.syncUserModels();
+        const entry = this.entryFor(model);
+        if (entry === undefined) {
+            // An unknown id is still dispatchable: the endpoint accepts the id it
+            // reports, and a model added after this build should not be refused. It
+            // inherits the standard window and the shared reasoning ladder.
+            const template = this.entryFor(KIMI_DEFAULT_MODEL) ?? this.catalog()[0];
+            const reasoning = template === undefined ? undefined : reasoningInfo(template);
+            return {
+                provider: KIMI_PROVIDER_ID,
+                id: model,
+                name: model,
+                context: { contextWindow: KIMI_CONTEXT_WINDOW },
+                defaultMaxTokens: KIMI_DEFAULT_MAX_TOKENS,
+                ...reasoning === undefined ? {} : { reasoning },
+            };
+        }
+        const reasoning = reasoningInfo(entry);
+        return {
+            provider: KIMI_PROVIDER_ID,
+            id: entry.id,
+            name: entry.name,
+            ...entry.description === undefined ? {} : { description: entry.description },
+            ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+            context: { contextWindow: entry.contextWindow },
+            defaultMaxTokens: KIMI_DEFAULT_MAX_TOKENS,
+            ...reasoning === undefined ? {} : { reasoning },
+        };
+    }
+    stream(options) {
+        return streamProviderResponses(options, {
+            label: 'Kimi API',
+            tokens: this.options.tokens,
+            request: (call, model, accessToken, signal) => this.request(call, model, accessToken, signal),
+            streamIdleTimeoutMs: this.options.streamIdleTimeoutMs,
+            ...this.options.onCredentialRejected === undefined
+                ? {}
+                : { onCredentialRejected: this.options.onCredentialRejected },
+            onFallback: (from, to, reason) => {
+                this.options.onWarn?.(`kimi: model ${from} unavailable (${reason}); falling back to ${to}`);
+            },
+            describeFailure: (error) => this.refreshHint(error),
+        });
+    }
+    /** Translate an auth failure into the message a user can act on. */
+    refreshHint(error) {
+        if (error instanceof ProviderError && error.code === REAUTH_REQUIRED) {
+            return new LlmError(`Kimi Code login expired; sign in again from Settings → Subscriptions (${KIMI_CODE_URL})`, 'INVALID_CREDENTIAL', { status: 401 });
+        }
+        return error;
+    }
+    /**
+     * The catalog the route serves: its own entries, then the ids the user added
+     * by hand. The two are built separately so the hand-added check can look at
+     * the shipped list without recursing.
+     */
+    catalog() {
+        return [...this.shippedCatalog(), ...this.addedEntries()];
+    }
+    /**
+     * The catalog to present: the shipped entries in their curated order and with
+     * their curated metadata, then any configured extra id, then any live id this
+     * build does not know.
+     *
+     * The live list never removes a shipped entry: the endpoint serves variants
+     * such as `k3[1m]` that its own `/models` listing omits, so absence there is
+     * not evidence of retirement.
+     */
+    shippedCatalog() {
+        const extra = [];
+        const seen = new Set();
+        const append = (id, description) => {
+            if (seen.has(id) || this.entryFor(id) !== undefined)
+                return;
+            seen.add(id);
+            extra.push(fallbackEntry(id, description, KIMI_CONTEXT_WINDOW));
+        };
+        for (const id of this.options.extraModels ?? [])
+            append(id, 'Extra model from the plugin configuration');
+        for (const id of this.discovered ?? [])
+            append(id, 'Reported by the Kimi Code model list');
+        return extra.length === 0 ? KIMI_MODELS : [...KIMI_MODELS, ...extra];
+    }
+    /** Whether one shipped entry covers a live model id. */
+    entryMatches(entry, id) {
+        return entry.id === id || entry.aliases?.includes(id) === true;
+    }
+    /** Resolve a requested model id onto its catalog entry. */
+    entryFor(model) {
+        return findEntry(KIMI_MODELS, model);
+    }
+    /** Re-read the ids the user added by hand. */
+    async syncUserModels() {
+        if (this.options.userModels === undefined)
+            return;
+        try {
+            this.userAddedIds = await this.options.userModels();
+        }
+        catch (error) {
+            this.options.onWarn?.(`user-added models unavailable (${errorChain(error)})`);
+            this.userAddedIds = [];
+        }
+    }
+    /**
+     * The entries for ids the user added by hand, in the order they added them.
+     *
+     * Published without shipped metadata: this build has never seen the model, so
+     * the endpoint's own defaults are the honest description.
+     */
+    addedEntries() {
+        if (this.userAddedIds.length === 0)
+            return [];
+        const known = new Set(this.shippedCatalog().map((entry) => entry.id));
+        return this.userAddedIds
+            .filter((id) => !known.has(id))
+            .map((id) => fallbackEntry(id, 'Added by hand in Settings', KIMI_CONTEXT_WINDOW));
+    }
+    /** Record the live catalog for the picker; failures keep the shipped list. */
+    discover(ids) {
+        this.discovered = ids;
+    }
+    /** The curated catalog, for the Settings page's model list. */
+    catalogEntries() {
+        return this.catalog();
+    }
+    /** What this route itself serves, without the ids added by hand. */
+    ownCatalogEntries() {
+        return this.shippedCatalog();
+    }
+    /** Build and send one request. */
+    async request(options, model, accessToken, signal) {
+        const resolveImage = this.imageResolver(signal);
+        const resolved = await toResponsesInput(options.messages, options.system, resolveImage);
+        const body = {
+            model,
+            ...resolved.instructions === undefined ? {} : { instructions: resolved.instructions },
+            input: resolved.input,
+            ...options.tools === undefined || options.tools.length === 0
+                ? {}
+                : { tools: toResponsesTools(options.tools), tool_choice: 'auto', parallel_tool_calls: true },
+            ...options.maxTokens === undefined ? {} : { max_output_tokens: options.maxTokens },
+            ...options.reasoningEffort === undefined
+                ? {}
+                : { reasoning: { effort: EFFORT_WIRE_MAP[String(options.reasoningEffort)] ?? String(options.reasoningEffort) } },
+            ...options.sessionId === undefined ? {} : { prompt_cache_key: String(options.sessionId) },
+            // Ask for the encrypted reasoning payload so a later turn can replay the
+            // provider's own item rather than reconstructed text.
+            include: ['reasoning.encrypted_content'],
+            store: false,
+            stream: true,
+        };
+        // Kimi locks temperature and penalties on every subscription coding model,
+        // so a caller-supplied value is dropped rather than rejected upstream.
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        return fetchFn(`${this.options.apiBase}${KIMI_RESPONSES_PATH}`, {
+            method: 'POST',
+            headers: kimiRequestHeaders(await this.identity(), {
+                'authorization': `Bearer ${accessToken}`,
+                'accept': 'text/event-stream',
+                'content-type': 'application/json',
+            }),
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    /** Client-identity headers for this machine, when configured. */
+    async identity() {
+        if (this.options.identityHeaders === undefined)
+            return {};
+        try {
+            return await this.options.identityHeaders();
+        }
+        catch (error) {
+            this.options.onWarn?.(`device identity unavailable (${errorChain(error)})`);
+            return {};
+        }
+    }
+    /** Resolve image blocks through the attachment service, when it is present. */
+    imageResolver(signal) {
+        const store = this.options.resolveAttachments?.();
+        if (store === undefined || store === null)
+            return undefined;
+        return async (ref) => {
+            try {
+                const stored = await store.readImage(ref, signal);
+                return { mediaType: ref.mediaType, base64: Buffer.from(stored.data).toString('base64') };
+            }
+            catch (error) {
+                this.options.onWarn?.(`image attachment unavailable (${errorChain(error)})`);
+                return undefined;
+            }
+        };
+    }
+    /** Read the live `/models` catalog, or undefined when unavailable. */
+    async fetchCatalog(accessToken, signal) {
+        if (!this.options.discovery)
+            return undefined;
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        try {
+            const response = await fetchFn(`${this.options.apiBase}${KIMI_MODELS_PATH}`, {
+                headers: kimiRequestHeaders(await this.identity(), { 'authorization': `Bearer ${accessToken}` }),
+                ...signal === undefined ? {} : { signal },
+            });
+            if (!response.ok) {
+                if (!isMissingOrInvalidCredential(await httpLlmError(response, 'Kimi models'))) {
+                    this.options.onWarn?.(`Kimi model discovery failed (HTTP ${response.status}); using the built-in catalog`);
+                }
+                return undefined;
+            }
+            const payload = await response.json();
+            const ids = (payload.data ?? [])
+                .map((entry) => entry.id)
+                .filter((id) => typeof id === 'string' && id.length > 0);
+            if (ids.length === 0) {
+                this.options.onWarn?.('Kimi model discovery returned an empty catalog; using the built-in catalog');
+                return undefined;
+            }
+            return ids;
+        }
+        catch (error) {
+            if (signal?.aborted === true)
+                return undefined;
+            this.options.onWarn?.(`Kimi model discovery failed; using the built-in catalog (${errorChain(error)})`);
+            return undefined;
+        }
+    }
+}

package/lib/providers/responses-stream.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The shared request/stream dance for providers that speak the OpenAI Responses
+ * wire (Kimi Code, xAI/Grok).
+ *
+ * Everything route-specific stays with the route: building the URL, assembling
+ * the body, and its headers. What is shared is the part that is easy to get
+ * subtly wrong twice — resolving a usable token, retrying exactly once after a
+ * rejected credential, walking a model chain when one model is unavailable,
+ * mapping transport and HTTP failures, guarding an idle stream, and translating
+ * the SSE body into harness chunks.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/responses-stream
+ */
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionBase } from '../auth/store.js';
+import type { TokenManager } from '../auth/tokens.js';
+/** Constructor inputs for {@link streamProviderResponses}. */
+export interface ResponsesStreamInput<S extends SessionBase> {
+    /** Endpoint name used in failure messages, e.g. `Kimi API`. */
+    label: string;
+    /** Token manager owning refresh. */
+    tokens: TokenManager<S>;
+    /** Send one request for one model with the given access token. */
+    request(options: GenerateOptions, model: string, accessToken: string, signal: AbortSignal): Promise<Response>;
+    /** Inactivity budget before the stream is abandoned. */
+    streamIdleTimeoutMs: number;
+    /**
+     * The models to try, most preferred first, resolved lazily.
+     *
+     * Omitted means "only the requested model". `auto` supplies the user's whole
+     * ranked chain here; a concrete id supplies just itself.
+     */
+    models?: () => Promise<readonly string[]>;
+    /** Called when a call proved the stored credential unusable. */
+    onCredentialRejected?: (account: string) => void;
+    /** Rewrite a thrown failure before it is mapped, e.g. to name the fix. */
+    describeFailure?(error: unknown): unknown;
+    /** Called when a model in the chain was skipped, with the reason. */
+    onFallback?: (from: string, to: string, reason: string) => void;
+}
+/**
+ * Run one model call over the Responses wire, walking a model chain.
+ *
+ * The chain is what `auto` means to a user: request the most preferred model,
+ * and — only while nothing has been streamed yet — fall through to the next one
+ * when the provider says that model cannot serve this request. Once any chunk has
+ * been produced the turn belongs to that model, so a later failure is reported
+ * rather than papered over by a second model's text.
+ *
+ * A 401/403 triggers exactly one forced token refresh and retry of the same
+ * model before the chain advances; if the retry is refused too, the credential is
+ * reported as dead so the caller can ask the user to sign in again.
+ *
+ * @param options - the fully assembled request for this call.
+ * @param input - the route's transport hooks and budgets.
+ * @yields harness stream chunks in contract order.
+ */
+export declare function streamProviderResponses<S extends SessionBase>(options: GenerateOptions, input: ResponsesStreamInput<S>): AsyncIterable<StreamChunk>;

package/lib/providers/responses-stream.js

@@ -0,0 +1,115 @@
+/**
+ * The shared request/stream dance for providers that speak the OpenAI Responses
+ * wire (Kimi Code, xAI/Grok).
+ *
+ * Everything route-specific stays with the route: building the URL, assembling
+ * the body, and its headers. What is shared is the part that is easy to get
+ * subtly wrong twice — resolving a usable token, retrying exactly once after a
+ * rejected credential, walking a model chain when one model is unavailable,
+ * mapping transport and HTTP failures, guarding an idle stream, and translating
+ * the SSE body into harness chunks.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/responses-stream
+ */
+import { EMPTY_RESPONSE_CODE, LlmError } from '@deepseek-ai/dsh-llm';
+import { streamResponses } from '../translate/responses.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure } from './common.js';
+/**
+ * Whether a refusal says "this model cannot serve you now", as opposed to "this
+ * request is wrong".
+ *
+ * Only the first kind may be answered by another model. A 400 or an unparseable
+ * body is a bug in what this plugin sent: silently re-sending it elsewhere would
+ * hide the defect and produce an answer from a model the caller did not ask for.
+ */
+function isModelFallbackWorthy(status) {
+    // Gone or renamed model, exhausted allowance, rate limit, provider trouble.
+    return status === 402 || status === 404 || status === 408 || status === 429 || status >= 500;
+}
+/** One short reason for a log line. */
+function reasonOf(error) {
+    if (error instanceof LlmError)
+        return `${error.failure.code}: ${error.message}`;
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Run one model call over the Responses wire, walking a model chain.
+ *
+ * The chain is what `auto` means to a user: request the most preferred model,
+ * and — only while nothing has been streamed yet — fall through to the next one
+ * when the provider says that model cannot serve this request. Once any chunk has
+ * been produced the turn belongs to that model, so a later failure is reported
+ * rather than papered over by a second model's text.
+ *
+ * A 401/403 triggers exactly one forced token refresh and retry of the same
+ * model before the chain advances; if the retry is refused too, the credential is
+ * reported as dead so the caller can ask the user to sign in again.
+ *
+ * @param options - the fully assembled request for this call.
+ * @param input - the route's transport hooks and budgets.
+ * @yields harness stream chunks in contract order.
+ */
+export async function* streamProviderResponses(options, input) {
+    const { label, tokens, request } = input;
+    const watchdog = idleWatchdog(options.signal, input.streamIdleTimeoutMs);
+    let lastError;
+    try {
+        // A chain is resolved once per call, so a settings change can never make the
+        // fallbacks disagree with the model the caller asked for.
+        const models = input.models === undefined ? [options.model] : await input.models();
+        if (models.length === 0) {
+            throw new LlmError(`${label} has no enabled model to dispatch to`, EMPTY_RESPONSE_CODE);
+        }
+        let token = await tokens.resolve();
+        for (const [index, model] of models.entries()) {
+            try {
+                let response = await request(options, model, token.accessToken, watchdog.signal);
+                if (response.status === 401 || response.status === 403) {
+                    token = await tokens.resolve(token.account, true);
+                    response = await request(options, model, token.accessToken, watchdog.signal);
+                    if (response.status === 401 || response.status === 403) {
+                        input.onCredentialRejected?.(token.account);
+                    }
+                }
+                if (!response.ok) {
+                    const error = await httpLlmError(response, label);
+                    if (models.length > 1 && isModelFallbackWorthy(response.status) && index < models.length - 1) {
+                        const next = models[index + 1];
+                        if (next !== undefined) {
+                            lastError = error;
+                            input.onFallback?.(model, next, reasonOf(error));
+                            continue;
+                        }
+                    }
+                    throw error;
+                }
+                if (response.body === null) {
+                    throw new LlmError(`${label} returned no response body`, EMPTY_RESPONSE_CODE);
+                }
+                yield* streamResponses(response.body, () => { watchdog.pulse(); });
+                return;
+            }
+            catch (error) {
+                // A transport failure on a chain is also worth another model.
+                const transport = error instanceof TypeError || error.name === 'AbortError';
+                if (transport && options.signal?.aborted !== true && index < models.length - 1) {
+                    const next = models[index + 1];
+                    if (next !== undefined) {
+                        lastError = error;
+                        input.onFallback?.(model, next, reasonOf(error));
+                        continue;
+                    }
+                }
+                throw input.describeFailure === undefined ? error : input.describeFailure(error);
+            }
+        }
+        throw lastError ?? new LlmError(`${label} served none of the requested models`, EMPTY_RESPONSE_CODE);
+    }
+    catch (error) {
+        const described = input.describeFailure === undefined ? error : input.describeFailure(error);
+        throw mapFetchFailure(label, described, watchdog, options.signal);
+    }
+    finally {
+        watchdog.stop();
+    }
+}

package/lib/providers/usage.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Plan and allowance reads.
+ *
+ * Both providers state what a subscription still has left on their own
+ * endpoints, in their own shapes. This module normalises those shapes into the
+ * one {@link UsageRead} the Settings page renders, and nothing here ever throws
+ * for a merely unsupported or unavailable endpoint: a provider that states no
+ * usage simply yields `undefined`.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/usage
+ */
+import type { UsageWindow } from '../protocol.js';
+import type { FetchFn } from '../http.js';
+/** Provider-neutral usage read, before the controller stamps it. */
+export interface UsageRead {
+    plan?: string;
+    renewsAt?: number;
+    windows: readonly UsageWindow[];
+    /**
+     * Why the figures are not the provider's primary accounting.
+     *
+     * Set when a route had to publish a substitute — Antigravity's per-model quota
+     * when its account summary was unreachable — so the page can say so instead of
+     * presenting the substitute as the plan's own numbers.
+     */
+    usageError?: string;
+}
+/** The `/usages` endpoint on the Kimi Code base. */
+export declare const KIMI_USAGE_PATH = "/usages";
+/** The Grok Build CLI chat proxy's billing endpoint. */
+export declare const GROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+/**
+ * Read the Kimi Code plan's rolling windows.
+ *
+ * `GET <base>/usages` states a five-hour window and a weekly window, either of
+ * which may be absent depending on the plan. The payload also carries a
+ * whole-subscription `totalQuota`, which is deliberately not published as a third
+ * meter: what a Kimi Code plan is metered against is the rolling and weekly
+ * windows, and a bare credit total next to them reads as a second, contradictory
+ * allowance.
+ *
+ * @param input - endpoint base, bearer, and an injectable fetch.
+ * @returns the windows, or undefined when the endpoint states none.
+ */
+export declare function readKimiUsage(input: {
+    apiBase: string;
+    accessToken: string;
+    fetchFn?: FetchFn;
+}): Promise<UsageRead | undefined>;
+/** Read the subscription tier a Grok access token carries. */
+export declare function grokTierName(accessToken: string): string | undefined;
+/**
+ * Read the Grok (X Premium) plan's metered allowance.
+ *
+ * The CLI's own chat proxy states included-credit usage as a ready-made
+ * percentage plus the current period; an older shape states cent-valued totals
+ * from which the percentage is derived.
+ *
+ * @param input - bearer, and an injectable fetch.
+ * @returns the window, or undefined when the endpoint states none.
+ */
+export declare function readGrokUsage(input: {
+    accessToken: string;
+    fetchFn?: FetchFn;
+}): Promise<UsageRead | undefined>;