dsh-plugin-subscription-oauth 0.2.1 → 0.3.0

package/lib/providers/ark.js

@@ -0,0 +1,412 @@
+/**
+ * The `ark` route: Volcengine Ark's Coding Plan over the OpenAI Responses wire.
+ *
+ * Everything in this module is pinned to what the endpoints themselves said:
+ *
+ * - `POST /api/coding/v3/responses` exists and wants a credential (401).
+ * - It accepts a **bearer Ark API key** and nothing else. An SSO identity token in
+ *   the same header is refused with `403 Unsupported zti authentication method`,
+ *   and an AK/SK signature with `403 Unsupported aksk authentication method`, while
+ *   a UUID-shaped key is looked up (`401 The API key doesn't exist`) and a
+ *   malformed one is told so (`401 The API key format is incorrect`). So the
+ *   credential is a UUID key, sent as a plain bearer — no request signing.
+ * - `/api/coding/v3` is documented by the official CLI as "OpenTOP + CodingPlan
+ *   API", and the catalogue below is the plan's roster.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/ark
+ */
+import { LlmAdapter, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+import { finiteInstant, nonEmpty } from '../auth/store.js';
+import { callArkControl, parseArkFreeUsage, parseArkPlanUsage } from '../auth/ark-control.js';
+import { proxiedFetch } from '../http.js';
+import { findEntry, resolveCatalog } from './catalog.js';
+import { streamProviderResponses } from './responses-stream.js';
+import { toResponsesInput, toResponsesTools } from '../translate/responses.js';
+/** Provider route this module serves. */
+export const ARK_PROVIDER_ID = 'ark';
+/** Display name for the picker group and the Settings card. */
+export const ARK_PROVIDER_NAME = 'Volcengine Ark';
+/** Page a user opens to manage the plan. */
+export const ARK_CODE_URL = 'https://console.volcengine.com/ark/region:ark+cn-beijing/overview';
+/** Coding-plan base; the Responses endpoint is `<base>/responses`. */
+export const ARK_API_BASE = 'https://ark.cn-beijing.volces.com/api/coding/v3';
+/** Origin the account-level endpoints hang off. */
+export const ARK_ORIGIN = 'https://ark.cn-beijing.volces.com';
+/** Path appended to the API base for a streaming request. */
+export const ARK_RESPONSES_PATH = '/responses';
+/** Model the picker preselects: the plan's own alias for its coding model. */
+export const ARK_DEFAULT_MODEL = 'ark-code-latest';
+/**
+ * Context capacity advertised for the plan's models.
+ *
+ * The Coding Plan is a curated, text-first roster and states no window per model;
+ * discovery refines this where the endpoint reports one.
+ */
+export const ARK_CONTEXT_WINDOW = 262_144;
+/** Output budget used when the caller sets no cap. */
+export const ARK_DEFAULT_MAX_TOKENS = 32_000;
+/** The plan's model roster, as the reference registry records it. */
+export const ARK_MODELS = [
+    { id: 'ark-code-latest', name: 'Ark Code (latest)', description: 'Plan alias for the current coding model', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
+    { id: 'doubao-seed-2.0-code', name: 'Doubao Seed 2.0 Code', description: 'Coding-tuned Doubao', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
+    { id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash', description: 'Fast DeepSeek', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
+    { id: 'glm-5.3', name: 'GLM-5.3', description: 'Zhipu flagship', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
+    { id: 'glm-5.3-flash', name: 'GLM-5.3 Flash', description: 'Fast GLM, reads images', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text', 'image'] },
+    { id: 'glm-5.2', name: 'GLM-5.2', description: 'Previous Zhipu flagship', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
+    { id: 'kimi-k2.6', name: 'Kimi K2.6', description: 'Moonshot model on Ark', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text'] },
+    { id: 'minimax-m3', name: 'MiniMax M3', description: 'MiniMax model on Ark', contextWindow: ARK_CONTEXT_WINDOW, inputModalities: ['text', 'image'] },
+];
+/**
+ * Coerce one decoded credential entry into an Ark session.
+ *
+ * @param value - decoded JSON value for one account.
+ * @returns the session, or undefined when required fields are missing.
+ */
+export function parseArkSession(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const apiKey = nonEmpty(record.apiKey);
+    const expiresAt = finiteInstant(record.expiresAt);
+    if (apiKey === undefined || expiresAt === undefined)
+        return undefined;
+    const idToken = nonEmpty(record.idToken);
+    const refreshToken = nonEmpty(record.refreshToken);
+    const apiBase = nonEmpty(record.apiBase);
+    const accountId = nonEmpty(record.accountId);
+    const email = nonEmpty(record.email);
+    const sts = stsFromSession(record.sts);
+    return {
+        // The data plane carries the API key; `accessToken` is the same value so the
+        // shared token machinery has one bearer to resolve.
+        accessToken: apiKey,
+        apiKey,
+        expiresAt,
+        ...sts === undefined ? {} : { sts },
+        ...idToken === undefined ? {} : { idToken },
+        ...refreshToken === undefined ? {} : { refreshToken },
+        ...apiBase === undefined ? {} : { apiBase },
+        ...accountId === undefined ? {} : { accountId },
+        ...email === undefined ? {} : { email },
+    };
+}
+/** Read a stored STS credential set, tolerating a partial one. */
+function stsFromSession(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const accessKeyId = nonEmpty(record.accessKeyId);
+    const secretAccessKey = nonEmpty(record.secretAccessKey);
+    const sessionToken = nonEmpty(record.sessionToken);
+    const expiresAt = finiteInstant(record.expiresAt);
+    if (accessKeyId === undefined || secretAccessKey === undefined || sessionToken === undefined || expiresAt === undefined) {
+        return undefined;
+    }
+    return { accessKeyId, secretAccessKey, sessionToken, expiresAt };
+}
+/** An entry for an id this build ships no metadata for. */
+function extraEntry(id) {
+    return { id, name: id, contextWindow: ARK_CONTEXT_WINDOW };
+}
+/** The adapter behind the `ark` route. */
+export class ArkAdapter extends LlmAdapter {
+    options;
+    live;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: ARK_PROVIDER_NAME };
+    }
+    providerRetryPolicy() {
+        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 [];
+        const hidden = await this.hidden();
+        return resolveCatalog(this.catalog(), [], hidden).entries.map((entry) => ({
+            provider: ARK_PROVIDER_ID,
+            id: entry.id,
+            name: entry.name,
+            ...entry.description === undefined ? {} : { description: entry.description },
+            ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+        }));
+    }
+    async resolveModel(_provider, model) {
+        const entry = findEntry(this.catalog(), model);
+        if (entry === undefined) {
+            const template = findEntry(this.catalog(), ARK_DEFAULT_MODEL) ?? this.catalog()[0];
+            return {
+                provider: ARK_PROVIDER_ID,
+                id: model,
+                name: model,
+                context: { contextWindow: template?.contextWindow ?? ARK_CONTEXT_WINDOW },
+                defaultMaxTokens: ARK_DEFAULT_MAX_TOKENS,
+            };
+        }
+        const reasoning = reasoningInfo(entry);
+        return {
+            provider: ARK_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: ARK_DEFAULT_MAX_TOKENS,
+            ...reasoning === undefined ? {} : { reasoning },
+        };
+    }
+    stream(options) {
+        return streamProviderResponses(options, {
+            label: 'Ark 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?.(`ark: 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(`Ark sign-in expired; connect the account again from Settings → Subscriptions (${ARK_CODE_URL})`, 'INVALID_CREDENTIAL', { status: 401 });
+        }
+        return error;
+    }
+    catalog() {
+        return [...this.shippedCatalog(), ...this.addedEntries()];
+    }
+    shippedCatalog() {
+        const shipped = this.options.extraModels === undefined
+            ? [...ARK_MODELS]
+            : [...ARK_MODELS, ...this.options.extraModels.map(extraEntry)];
+        const live = this.live;
+        if (live === undefined)
+            return shipped;
+        const merged = [...shipped];
+        for (const id of live) {
+            if (findEntry(merged, id) === undefined)
+                merged.push(extraEntry(id));
+        }
+        return merged;
+    }
+    addedEntries() {
+        const own = this.shippedCatalog();
+        const added = this.options.userModels?.();
+        if (added === undefined)
+            return [];
+        return (Array.isArray(added) ? added : [])
+            .filter((id) => findEntry(own, id) === undefined)
+            .map(extraEntry);
+    }
+    async hidden() {
+        if (this.options.hiddenModels === undefined)
+            return new Set();
+        try {
+            return await this.options.hiddenModels();
+        }
+        catch {
+            return new Set();
+        }
+    }
+    /** Adopt the endpoint's live catalog. */
+    discover(ids) {
+        this.live = [...ids];
+    }
+    /**
+     * Read the plan's live model list.
+     *
+     * The Coding Plan answers the OpenAI models shape on its own base; an endpoint
+     * that does not serve it leaves the shipped roster in place.
+     */
+    async fetchCatalog(apiKey, signal) {
+        if (!this.options.discovery)
+            return undefined;
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        try {
+            const response = await fetchFn(`${this.options.apiBase}/models`, {
+                headers: { authorization: `Bearer ${apiKey}`, accept: 'application/json' },
+                ...signal === undefined ? {} : { signal },
+            });
+            if (!response.ok) {
+                this.options.onWarn?.(`Ark model list unavailable (HTTP ${response.status})`);
+                return undefined;
+            }
+            const body = await response.json();
+            const ids = (body.data ?? [])
+                .map((entry) => (typeof entry?.id === 'string' ? entry.id.trim() : ''))
+                .filter((id) => id !== '');
+            return ids.length === 0 ? undefined : ids;
+        }
+        catch (error) {
+            this.options.onWarn?.(`Ark model list unavailable (${error instanceof Error ? error.message : String(error)})`);
+            return undefined;
+        }
+    }
+    /** Send one streaming request over the Responses wire. */
+    async request(options, model, apiKey, 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: String(options.reasoningEffort) } },
+            ...options.sessionId === undefined ? {} : { prompt_cache_key: String(options.sessionId) },
+            stream: true,
+        };
+        const fetchFn = this.options.fetchFn ?? proxiedFetch;
+        return fetchFn(`${this.options.apiBase}${ARK_RESPONSES_PATH}`, {
+            method: 'POST',
+            headers: {
+                'authorization': `Bearer ${apiKey}`,
+                'accept': 'text/event-stream',
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    /** 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 (${error instanceof Error ? error.message : String(error)})`);
+                return undefined;
+            }
+        };
+    }
+    /** The catalog the controller publishes without hand-added ids. */
+    ownCatalogEntries() {
+        return this.shippedCatalog();
+    }
+    /** The catalog the controller publishes. */
+    catalogEntries() {
+        return this.catalog();
+    }
+}
+/** 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;
+    return {
+        efforts: efforts.map((effort) => ({ id: ReasoningEffortId(effort), name: String(effort), description: '' })),
+        ...entry.defaultEffort === undefined ? {} : { defaultEffort: ReasoningEffortId(entry.defaultEffort) },
+    };
+}
+/**
+ * Read the plan's allowance.
+ *
+ * Two allowances exist, and both live on the **control plane** — a different host
+ * from the data plane, reached with the STS AK/SK the SSO identity was exchanged
+ * for (see `auth/ark-control.ts`) rather than with the plan API key:
+ *
+ * - the **subscription** periods (`GetCodingPlanUsage` → `coding_usage.periods[]`,
+ *   each `{ label, used, total, percent, reset_at }`), which an account without a
+ *   plan answers as `Status: Reclaimed`;
+ * - the **free inference allowance** per model (`ListModelChargeItems` →
+ *   `InferenceFreeUsage { Consumed, Total }`), which exists with no subscription.
+ *
+ * The free allowance is what a plan-less account actually has, so it is reported
+ * even when the subscription is absent — otherwise the card would say "no quota"
+ * while the account still had tokens to spend.
+ *
+ * @param input - the signed control-plane client.
+ * @returns the windows the service stated, subscription first.
+ */
+export async function readArkUsage(input) {
+    const windows = [];
+    let plan;
+    let planError;
+    try {
+        const payload = await callArkControl({
+            action: 'GetCodingPlanUsage',
+            credentials: input.credentials,
+            fetchFn: input.fetchFn,
+            ...input.signal === undefined ? {} : { signal: input.signal },
+        });
+        plan = parseArkPlanUsage(payload);
+        for (const period of plan.periods) {
+            const usedPercent = period.percent
+                ?? (period.used !== undefined && period.total !== undefined && period.total > 0
+                    ? (period.used / period.total) * 100
+                    : undefined);
+            windows.push({
+                // The plan's own period names become the window labels the page already
+                // knows: `5h`, `weekly`, `monthly`.
+                label: period.label,
+                ...usedPercent === undefined ? {} : { usedPercent: Math.max(0, Math.min(100, usedPercent)) },
+                ...period.used === undefined ? {} : { used: period.used },
+                ...period.total === undefined ? {} : { limit: period.total },
+                ...period.resetsAt === undefined ? {} : { resetsAt: period.resetsAt },
+            });
+        }
+    }
+    catch (error) {
+        planError = error instanceof Error ? error.message : String(error);
+    }
+    try {
+        const payload = await callArkControl({
+            action: 'ListModelChargeItems',
+            credentials: input.credentials,
+            fetchFn: input.fetchFn,
+            body: 'Modality=LLM&PageSize=50',
+            ...input.signal === undefined ? {} : { signal: input.signal },
+        });
+        const free = parseArkFreeUsage(payload);
+        if (free.length > 0) {
+            // One row per model would bury the plan figures; the page shows the free
+            // allowance as the pool it is, spent across the models that grant it.
+            const consumed = free.reduce((sum, entry) => sum + entry.consumed, 0);
+            const total = free.reduce((sum, entry) => sum + entry.total, 0);
+            windows.push({
+                label: 'free',
+                usedPercent: total > 0 ? Math.max(0, Math.min(100, (consumed / total) * 100)) : 0,
+                used: consumed,
+                limit: total,
+            });
+        }
+    }
+    catch (error) {
+        // The free pool is a bonus, not the subscription: failing to read it must not
+        // hide the plan figures that did come back.
+        if (plan === undefined || plan.periods.length === 0) {
+            return {
+                windows,
+                usageError: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    return {
+        windows,
+        ...plan === undefined || plan.subscribed
+            ? {}
+            : {
+                // A plan-less account is a state, not a failure: say so, and let the free
+                // pool above speak for itself.
+                usageError: planError ?? 'no Ark Coding Plan on this account; showing the free inference allowance',
+            },
+    };
+}

package/lib/providers/auto.js

@@ -198,6 +198,22 @@ export class AutoAdapter extends LlmAdapter {
             // Auto cannot chain to itself; that would be a loop, not a fallback.
             if (entry.id === AUTO_PROVIDER_ID)
                 continue;
+            // A route this plugin owns but has not signed in offers nothing, even though
+            // the harness still answers with its catalog: the harness has no notion of an
+            // account, so Auto is the layer that has to ask. Host providers are left
+            // alone — Auto has no way to judge somebody else's readiness, and dropping
+            // them would silently empty the chain.
+            const owned = this.options.registry.get(entry.id);
+            if (owned !== undefined) {
+                try {
+                    if (!(await owned.status()).loggedIn)
+                        continue;
+                }
+                catch (error) {
+                    this.options.onWarn?.(`auto could not read ${entry.id}'s account state (${errorChain(error)})`);
+                    continue;
+                }
+            }
             try {
                 for (const model of await host.models(entry.id)) {
                     const resolved = await host.resolve(entry.id, model.id);

package/lib/providers/usage.js

@@ -49,9 +49,42 @@ function toInstant(value) {
         return undefined;
     return numeric < 1e12 ? numeric * 1000 : numeric;
 }
-/** The first present reset instant among a row's usual field names. */
+/**
+ * Read one `usages.<key>` row.
+ *
+ * Kimi states these as a spent fraction (`used_ratio`, 0–1) plus `reset_time`,
+ * rather than the `limit`/`used` pair the other rows use, so the percentage is the
+ * ratio itself.
+ *
+ * @param usages - the payload's `usages` object.
+ * @param key - `limit_5h` or `limit_7d`.
+ * @returns the row, or undefined when it states no figure.
+ */
+function readUsagesRow(usages, key) {
+    if (!isRecord(usages))
+        return undefined;
+    const row = usages[key];
+    if (!isRecord(row))
+        return undefined;
+    const ratio = toNumber(row.used_ratio);
+    if (ratio === undefined)
+        return undefined;
+    const resetsAt = resetInstant(row);
+    return {
+        usedPercent: Math.max(0, Math.min(100, ratio * 100)),
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
+}
+/**
+ * The first present reset instant among a row's usual field names.
+ *
+ * `reset_time` is in the list because that is what Kimi's own `/usages` body uses —
+ * `usages.limit_5h.reset_time` — and omitting it was why the Kimi card showed its
+ * windows without any reset at all. The other spellings cover the shapes the other
+ * routes and the earlier payloads use.
+ */
 function resetInstant(row) {
-    for (const key of ['resetsAt', 'resets_at', 'resetAt', 'reset_at', 'end', 'endsAt', 'expiresAt']) {
+    for (const key of ['resetsAt', 'resets_at', 'resetAt', 'reset_at', 'resetTime', 'reset_time', 'end', 'endsAt', 'expiresAt']) {
         const instant = toInstant(row[key]);
         if (instant !== undefined)
             return instant;
@@ -131,8 +164,8 @@ function unwrapKimiUsage(value) {
     if (!isRecord(nested))
         return value;
     const usable = (field) => field !== undefined && field !== null;
-    const outer = usable(value.usage) || usable(value.limits) || usable(value.totalQuota);
-    const inner = usable(nested.usage) || usable(nested.limits) || usable(nested.totalQuota);
+    const outer = usable(value.usage) || usable(value.limits) || usable(value.totalQuota) || usable(value.usages);
+    const inner = usable(nested.usage) || usable(nested.limits) || usable(nested.totalQuota) || usable(nested.usages);
     return !outer && inner ? nested : value;
 }
 /** The label a Kimi limit row carries, lowercased. */
@@ -217,6 +250,18 @@ export async function readKimiUsage(input) {
         windows.push(toWindow('5h', fiveHour));
     if (weekly !== undefined)
         windows.push(toWindow('weekly', weekly));
+    // Kimi's own `/usages` body states the two metered windows as
+    // `usages.limit_5h` / `usages.limit_7d` with `used_ratio` and `reset_time`. Those
+    // are read last so a `limits[]` row, when present, keeps its more specific
+    // figures; this is the fallback that stops a payload from rendering as two
+    // windows with no reset at all.
+    if (windows.length === 0) {
+        for (const [key, label] of [['limit_5h', '5h'], ['limit_7d', 'weekly']]) {
+            const row = readUsagesRow(body.usages, key);
+            if (row !== undefined)
+                windows.push(toWindow(label, row));
+        }
+    }
     if (windows.length === 0)
         return undefined;
     const plan = typeof body.plan === 'string' && body.plan.length > 0 ? body.plan : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subscription-oauth",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Use subscription accounts as DeepSeek Harness LLM providers — Kimi Code (OAuth device flow), Grok / X Premium (OIDC + PKCE), Google Antigravity (Google OAuth + Cloud Code Assist) and GLM / BigModel (ZCode's browser sign-in) — with per-model visibility, drag-to-reorder Auto fallback and plan quotas from the web Settings page",
   "license": "MIT",
   "author": "EricFL1998",