dsh-subscriptions 0.1.0

package/lib/providers/catalog-store.js

@@ -0,0 +1,243 @@
+/**
+ * On-disk discovered-model-catalog cache at
+ * `~/.dsh/plugins/subscriptions/models.json` — the durable half of each
+ * provider's {@link ModelCatalogCache}. One entry per provider: the last
+ * successfully discovered catalog with its fetch time, so capability metadata
+ * (reasoning efforts) survives restarts and network failures.
+ *
+ * Unlike the auth store, this file is a cache: a missing, corrupt, or
+ * malformed file silently reads as absent, because the next successful
+ * discovery rewrites it. Loads are strictly validated — a malformed entry
+ * passed through `resolveModel` would make the harness's metadata validation
+ * throw on every call, which is worse than having no fallback at all.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+/**
+ * Absolute path of the catalog store file.
+ * @returns `dshHomePath('plugins', 'subscriptions', 'models.json')`.
+ */
+export function modelsFilePath() {
+    return dshHomePath('plugins', 'subscriptions', 'models.json');
+}
+/** The per-account section of the file, or undefined when absent or malformed. */
+function accountSection(store, provider) {
+    const accounts = store.accounts;
+    if (typeof accounts !== 'object' || accounts === null || Array.isArray(accounts))
+        return undefined;
+    const section = accounts[provider];
+    if (typeof section !== 'object' || section === null || Array.isArray(section))
+        return undefined;
+    return section;
+}
+/** Validate one persisted reasoning block, or undefined when malformed. */
+function sanitizeReasoning(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    if (!Array.isArray(raw.efforts) || raw.efforts.length === 0)
+        return undefined;
+    const seen = new Set();
+    const efforts = [];
+    for (const entry of raw.efforts) {
+        if (typeof entry !== 'object' || entry === null)
+            return undefined;
+        const effort = entry;
+        if (typeof effort.id !== 'string' || effort.id.length === 0
+            || typeof effort.name !== 'string' || effort.name.length === 0
+            || (effort.description !== undefined && typeof effort.description !== 'string')
+            || seen.has(effort.id))
+            return undefined;
+        seen.add(effort.id);
+        efforts.push({
+            id: ReasoningEffortId(effort.id),
+            name: effort.name,
+            ...effort.description === undefined ? {} : { description: effort.description },
+        });
+    }
+    if (raw.defaultEffort !== undefined
+        && (typeof raw.defaultEffort !== 'string' || !seen.has(raw.defaultEffort)))
+        return undefined;
+    return {
+        efforts,
+        ...raw.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(raw.defaultEffort) },
+    };
+}
+/** Validate one persisted model, or undefined when malformed. */
+function sanitizeModel(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    if (typeof raw.id !== 'string' || raw.id.length === 0
+        || typeof raw.name !== 'string' || raw.name.length === 0
+        || (raw.description !== undefined && typeof raw.description !== 'string')
+        || (raw.contextWindow !== undefined
+            && (typeof raw.contextWindow !== 'number' || !Number.isInteger(raw.contextWindow) || raw.contextWindow <= 0))
+        || (raw.maxContextWindow !== undefined
+            && (typeof raw.maxContextWindow !== 'number' || !Number.isSafeInteger(raw.maxContextWindow) || raw.maxContextWindow <= 0))
+        || (raw.maxOutputTokens !== undefined
+            && (typeof raw.maxOutputTokens !== 'number' || !Number.isSafeInteger(raw.maxOutputTokens) || raw.maxOutputTokens <= 0))
+        || (raw.priority !== undefined
+            && (typeof raw.priority !== 'number' || !Number.isFinite(raw.priority))))
+        return undefined;
+    const reasoning = raw.reasoning === undefined ? undefined : sanitizeReasoning(raw.reasoning);
+    if (raw.reasoning !== undefined && reasoning === undefined)
+        return undefined;
+    const thinkingType = raw.thinkingType;
+    if (thinkingType !== undefined && thinkingType !== 'enabled' && thinkingType !== 'adaptive')
+        return undefined;
+    const fastTier = raw.fastTier;
+    if (fastTier !== undefined && typeof fastTier !== 'boolean')
+        return undefined;
+    const copilotWire = raw.copilotWire;
+    if (copilotWire !== undefined && copilotWire !== 'chat-completions' && copilotWire !== 'responses') {
+        return undefined;
+    }
+    const copilotResponses = raw.copilotResponses;
+    if (copilotResponses !== undefined && typeof copilotResponses !== 'boolean')
+        return undefined;
+    const inputModalities = raw.inputModalities;
+    if (inputModalities !== undefined
+        && (!Array.isArray(inputModalities) || inputModalities.length === 0
+            || inputModalities.some(modality => modality !== 'text' && modality !== 'image')))
+        return undefined;
+    return {
+        id: raw.id,
+        name: raw.name,
+        ...raw.description === undefined ? {} : { description: raw.description },
+        ...raw.contextWindow === undefined ? {} : { contextWindow: raw.contextWindow },
+        ...raw.maxContextWindow === undefined ? {} : { maxContextWindow: raw.maxContextWindow },
+        ...raw.maxOutputTokens === undefined ? {} : { maxOutputTokens: raw.maxOutputTokens },
+        ...raw.priority === undefined ? {} : { priority: raw.priority },
+        ...reasoning === undefined ? {} : { reasoning },
+        ...thinkingType === undefined ? {} : { thinkingType: thinkingType },
+        ...fastTier === undefined ? {} : { fastTier },
+        ...copilotWire === undefined ? {} : { copilotWire: copilotWire },
+        ...copilotResponses === undefined ? {} : { copilotResponses },
+        ...inputModalities === undefined ? {} : { inputModalities: [...inputModalities] },
+    };
+}
+/**
+ * Validate one persisted snapshot. Strict: any malformed field drops the
+ * whole snapshot rather than repairing it — the next successful discovery
+ * rewrites the entry anyway.
+ * @param value - the raw per-provider file entry.
+ * @returns the validated snapshot, or undefined when unusable.
+ */
+export function sanitizeSnapshot(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    if (typeof raw.at !== 'number' || !Number.isFinite(raw.at))
+        return undefined;
+    if (!Array.isArray(raw.models) || raw.models.length === 0)
+        return undefined;
+    const seen = new Set();
+    const models = [];
+    for (const entry of raw.models) {
+        const model = sanitizeModel(entry);
+        if (model === undefined || seen.has(model.id))
+            return undefined;
+        seen.add(model.id);
+        models.push(model);
+    }
+    return { at: raw.at, models };
+}
+/** Read the whole file; missing or unparsable reads as an empty cache. */
+async function readCatalogFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist the whole file atomically (tmp file + rename). */
+async function writeCatalogFile(store, path) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(tmp, JSON.stringify(store, null, 2));
+        await rename(tmp, path);
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+    }
+}
+/**
+ * Build the durable half of one provider's catalog cache over the shared
+ * models.json file (concurrent writers are last-writer-wins, acceptable for
+ * a cache).
+ * @param provider - the provider route keying the file entry.
+ * @param path - store file path; defaults to {@link modelsFilePath}.
+ * @returns the persistence hooks for {@link ModelCatalogCache}.
+ */
+export function catalogStore(provider, path = modelsFilePath()) {
+    return {
+        async load() {
+            return sanitizeSnapshot((await readCatalogFile(path))[provider]);
+        },
+        async save(snapshot) {
+            const store = await readCatalogFile(path);
+            store[provider] = snapshot;
+            await writeCatalogFile(store, path);
+        },
+        async clear() {
+            const store = await readCatalogFile(path);
+            if (store[provider] === undefined)
+                return;
+            delete store[provider];
+            await writeCatalogFile(store, path);
+        },
+    };
+}
+/**
+ * The durable half of one NON-default account's catalog cache. The provider
+ * entry belongs to the default account; every other account keeps its own
+ * snapshot under `accounts[provider][account]`, so a working secondary login
+ * survives restarts and network failures even when the default login is dead.
+ * @param provider - the provider route.
+ * @param account - the canonical account key.
+ * @param path - store file path; defaults to {@link modelsFilePath}.
+ * @returns the persistence hooks for {@link ModelCatalogCache}.
+ */
+export function accountCatalogStore(provider, account, path = modelsFilePath()) {
+    return {
+        async load() {
+            const section = accountSection(await readCatalogFile(path), provider);
+            return section !== undefined && Object.hasOwn(section, account) ? sanitizeSnapshot(section[account]) : undefined;
+        },
+        async save(snapshot) {
+            const store = await readCatalogFile(path);
+            const accounts = typeof store.accounts === 'object' && store.accounts !== null && !Array.isArray(store.accounts)
+                ? store.accounts
+                : {};
+            const section = { ...accountSection(store, provider) ?? {}, [account]: snapshot };
+            store.accounts = { ...accounts, [provider]: section };
+            await writeCatalogFile(store, path);
+        },
+        async clear() {
+            const store = await readCatalogFile(path);
+            const section = accountSection(store, provider);
+            if (section === undefined || !Object.hasOwn(section, account))
+                return;
+            const rest = { ...section };
+            delete rest[account];
+            store.accounts = { ...store.accounts, [provider]: rest };
+            await writeCatalogFile(store, path);
+        },
+    };
+}

package/lib/providers/claude-cli-version.d.ts

@@ -0,0 +1,15 @@
+import type { FetchFn } from './common.js';
+import { NpmCliVersionCache } from './npm-cli-version.js';
+/**
+ * Public metadata only: never send subscription credentials to this endpoint.
+ * `latest`, not `stable`: the endpoint gates new models on versions that
+ * reach `stable` about a week later.
+ */
+export declare const CLAUDE_CLI_VERSION_URL = "https://registry.npmjs.org/@anthropic-ai%2fclaude-code/latest";
+/**
+ * Lazy, shared-per-plugin lookup of Claude Code's newest release, never
+ * below the local CLI or the bundled fallback version.
+ */
+export declare class ClaudeCliVersionCache extends NpmCliVersionCache {
+    constructor(fetchFn?: FetchFn, now?: () => number, timeoutMs?: number, detect?: () => string);
+}

package/lib/providers/claude-cli-version.js

@@ -0,0 +1,24 @@
+import { claudeCliVersionFloor } from './claude.js';
+import { NpmCliVersionCache } from './npm-cli-version.js';
+/**
+ * Public metadata only: never send subscription credentials to this endpoint.
+ * `latest`, not `stable`: the endpoint gates new models on versions that
+ * reach `stable` about a week later.
+ */
+export const CLAUDE_CLI_VERSION_URL = 'https://registry.npmjs.org/@anthropic-ai%2fclaude-code/latest';
+/**
+ * Lazy, shared-per-plugin lookup of Claude Code's newest release, never
+ * below the local CLI or the bundled fallback version.
+ */
+export class ClaudeCliVersionCache extends NpmCliVersionCache {
+    constructor(fetchFn, now, timeoutMs, detect) {
+        super({
+            url: CLAUDE_CLI_VERSION_URL,
+            label: 'Claude Code',
+            floor: () => claudeCliVersionFloor(detect),
+            ...fetchFn === undefined ? {} : { fetchFn },
+            ...now === undefined ? {} : { now },
+            ...timeoutMs === undefined ? {} : { timeoutMs },
+        });
+    }
+}

package/lib/providers/claude.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Claude Pro/Max subscription provider: OAuth against claude.ai /
+ * platform.claude.com with the Claude Code client id, and streaming against
+ * the Anthropic Messages API with the Claude Code identity headers.
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { FlowSpec } from '../auth/oauth-flow.js';
+import type { ClaudeSession } from '../auth/store.js';
+import type { PoolAdapter } from './pool.js';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { TranslatableMessage } from '../translate/resolved.js';
+import { AccountTokenManager } from './accounts.js';
+import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
+import type { CliVersion } from './npm-cli-version.js';
+import type { RateLimitResetReader, RateLimitWait } from './rate-limit.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://claude.ai/v1/oauth/token";
+export declare const CLAUDE_API_URL = "https://api.anthropic.com/v1/messages?beta=true";
+export declare const CLAUDE_PROFILE_URL = "https://api.anthropic.com/api/oauth/profile";
+export declare const CLAUDE_MODELS_URL = "https://api.anthropic.com/v1/models?beta=true";
+export declare const CLAUDE_SCOPE = "org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload";
+export declare const CLAUDE_CALLBACK_PATH = "/callback";
+/** Refresh when the access token has less than this much life left. */
+export declare const CLAUDE_PREEMPT_MS: number;
+/**
+ * Reads the reset instant of the Anthropic window that rejected a request.
+ *
+ * `anthropic-ratelimit-unified-*` is the subscription-plan family — the one
+ * Claude Code renders as "resets 3pm" — and is the only header that names the
+ * window which actually rejected this request. The per-bucket
+ * `anthropic-ratelimit-{requests,tokens,input-tokens,output-tokens}-reset`
+ * headers are deliberately not read: they are rollover snapshots attached to
+ * every response, so on a 429 they cannot say which bucket refused, and the
+ * earliest of them is typically the bucket that still had room — a wait that
+ * lands straight back in the closed window. They reach the operator through
+ * `rateLimitDiagnostics` instead.
+ */
+export declare const claudeRateLimitReset: RateLimitResetReader;
+/**
+ * The subscription endpoint only serves requests presenting as Claude Code,
+ * so these headers impersonate the CLI; the harness attribution user-agent
+ * cannot be sent here (one user-agent slot, and the CLI's wins). The endpoint
+ * also gates new models on the CLI version, so the version normally comes
+ * from npm (`ClaudeCliVersionCache`); this is only the offline floor.
+ */
+export declare const CLAUDE_CLI_FALLBACK_VERSION = "2.1.283";
+export declare function detectClaudeVersion(): string;
+/**
+ * The lowest version to present: the local CLI or the bundled fallback,
+ * whichever is newer. An outdated local install must not pin requests to a
+ * version the endpoint already rejects for new models.
+ * @param detect - local CLI probe (injectable for tests).
+ */
+export declare function claudeCliVersionFloor(detect?: () => string): CliVersion;
+/** The User-Agent Claude Code sends at `version`. */
+export declare function claudeCliUserAgent(version: string): string;
+export declare const CLAUDE_BETA_FALLBACK: string;
+/** Static claude flow facts for the OAuth flow engine. */
+export declare const claudeFlow: FlowSpec;
+/**
+ * Exchange an authorization code for a claude session (JSON grant).
+ * @param code - the authorization code from the callback.
+ * @param verifier - the PKCE verifier minted for the attempt.
+ * @param redirectUri - the attempt's redirect URI.
+ * @param state - the attempt's state (echoed to the token endpoint).
+ * @returns the session to store.
+ */
+export declare function exchangeClaudeCode(code: string, verifier: string, redirectUri: string, state: string): Promise<ClaudeSession>;
+/**
+ * Refresh a claude session (JSON grant echoing the issued scope).
+ * @param session - the stored session.
+ * @returns the fresh session to store.
+ */
+export declare function refreshClaude(session: ClaudeSession): Promise<ClaudeSession>;
+/**
+ * Whether a claude refresh failure means the login is permanently gone.
+ * @param error - the thrown refresh error.
+ * @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.
+ * @param cliVersion - resolves the Claude Code version to present; defaults to the local floor.
+ * @returns the mapped usage snapshot.
+ */
+export declare function fetchClaudeUsage(session: ClaudeSession, fetchFn?: FetchFn, signal?: AbortSignal, cliVersion?: () => Promise<string>): Promise<ProviderUsage>;
+/**
+ * Fetch the live model catalog from the subscription endpoint. `signal`
+ * cancels the request; `cliVersion` resolves the Claude Code version to
+ * present (defaults to the local floor).
+ */
+export declare function fetchClaudeModels(session: ClaudeSession, fetchFn?: FetchFn, signal?: AbortSignal, cliVersion?: () => Promise<string>): Promise<DiscoveredModel[]>;
+/** Constructor dependencies for {@link ClaudeAdapter}. */
+export interface ClaudeAdapterOptions {
+    models: readonly ModelEntry[];
+    streamIdleTimeoutMs: number;
+    tokens: AccountTokenManager<ClaudeSession>;
+    /** Late-bound pool facade (wired after adapter construction); pools list under their first member's provider. */
+    pool?: () => PoolAdapter | undefined;
+    /** Whether to fetch the live catalog when logged in (false when config `models` overrides). */
+    discovery: boolean;
+    fetchFn?: FetchFn;
+    onWarn?: (message: string) => void;
+    /** How long this route may hold a turn open waiting for a rate-limit window; defaults to waiting on, six-hour ceiling. */
+    rateLimit?: RateLimitWait;
+    /** Resolve the attachment service per request; absent means image requests fail loudly. */
+    resolveAttachments?: () => AttachmentStore | undefined;
+    /** Durable catalog store seeding capability metadata across restarts. */
+    catalogStore?: CatalogPersistence;
+    /**
+     * Per-model default reasoning effort override (the Settings page's picker).
+     * Returns the user-configured default for one model, or undefined to follow
+     * the provider's own default.
+     */
+    defaultEffortOf?: (model: string) => string | undefined;
+    /** Resolves the Claude Code version to present (npm-backed); absent means the local floor. */
+    resolveCliVersion?: () => Promise<string>;
+}
+/**
+ * Assemble the Anthropic request body.
+ *
+ * Extracted from the adapter so the wire shape — cache breakpoints above all —
+ * is testable without a network round trip. The message array is marked before
+ * it is placed so the breakpoints land on the blocks the body ships: one on the
+ * last `system` block (covering `tools` + `system`, which render ahead of it)
+ * and up to three across the history, Anthropic's four-slot maximum.
+ * @param options - the generate request.
+ * @param messages - conversation messages with images already resolved.
+ * @param maxTokens - the resolved output cap.
+ * @param thinking - the thinking parameter, when the model takes one.
+ * @param effort - the reasoning effort, when the model advertises efforts.
+ * @returns the JSON body to POST.
+ */
+export declare function claudeRequestBody(options: GenerateOptions, messages: readonly TranslatableMessage[], maxTokens: number, thinking?: Record<string, unknown>, effort?: string): Record<string, unknown>;
+/** Claude wire adapter: one instance serves the `claude` provider route. */
+export declare class ClaudeAdapter extends LlmAdapter {
+    private readonly options;
+    private readonly catalog;
+    /** In-memory catalogs for non-default accounts (the persisted cache is the default's). */
+    private readonly accountCatalogs;
+    /** Account whose snapshot currently lives in {@link catalog}; cleared on default change. */
+    private catalogOwner;
+    constructor(options: ClaudeAdapterOptions);
+    private fetchCatalog;
+    /** Drop cached catalogs after login/logout so the next list does not reuse a stale plan. */
+    clearAccountCatalog(account?: string): void;
+    /** Persisted cache for the default account; a throwaway cache for any other. */
+    private catalogFor;
+    private discovered;
+    private staticModels;
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): import("@deepseek-ai/dsh-llm").ResolvedRetryPolicy;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /** The provider's own catalog: union of every account, or one account when named. */
+    listOwnModels(provider: string, account?: string, signal?: AbortSignal): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    /** Capability resolution of the provider's own models (the pool resolves members here). */
+    resolveOwnModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /** Pool seam: stream through one specific account instead of the default. */
+    streamAccount(options: GenerateOptions, account: string): AsyncIterable<StreamChunk>;
+    private streamCore;
+    /**
+     * `display: 'summarized'` is set explicitly on both shapes: `adaptive`-type
+     * models default to `display: 'omitted'`, which returns thinking blocks with
+     * an empty `thinking` field — without this override the "Think" panel would
+     * always render empty even though real reasoning (and billed thinking_tokens)
+     * ran.
+     */
+    private thinkingParam;
+    private request;
+}