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

package/lib/providers/kimi-provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The `kimi` provider route's wiring: credential store, device-flow login,
+ * token refresh, model catalog, and its Settings card facts.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/kimi-provider
+ */
+import type { ProviderRoute } from '../auth/registry.js';
+import type { ModelPreferences } from '../settings.js';
+import type { FetchFn } from '../http.js';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+/** Everything the Kimi route needs from the plugin configuration. */
+export interface KimiProviderOptions {
+    /** Directory holding the device id. */
+    dataDir: string;
+    /** Absolute path of `auth.json`. */
+    credentialFile: string;
+    /** OAuth host serving the device flow. */
+    oauthHost: string;
+    /** Request base; `<base>/responses` is the endpoint. */
+    apiBase: string;
+    /** Consult the endpoint's live model list. */
+    discovery: boolean;
+    /** Abandon a stream after this much silence. */
+    streamIdleTimeoutMs: number;
+    /** Model the picker preselects. */
+    defaultModel?: string;
+    /** Extra model ids published without shipped metadata. */
+    extraModels?: readonly string[];
+    /** Shared model-visibility preferences. */
+    preferences: ModelPreferences;
+    /** Resolve the attachment service per request. */
+    resolveAttachments?: () => AttachmentStore | undefined;
+    /** Invoked when the catalog or its visibility changed. */
+    onCatalogChanged?: () => void;
+    onWarn?: (message: string) => void;
+    /** Fetch implementation; defaults to the proxy-aware fetch. */
+    fetchFn?: FetchFn;
+}
+/**
+ * Build the `kimi` route: its adapter and its login/lifecycle controller.
+ *
+ * @param options - resolved endpoints, paths, and shared services.
+ * @returns the route, ready to register and to serve over RPC.
+ */
+export declare function createKimiProvider(options: KimiProviderOptions): ProviderRoute;

package/lib/providers/kimi-provider.js

@@ -0,0 +1,148 @@
+/**
+ * The `kimi` provider route's wiring: credential store, device-flow login,
+ * token refresh, model catalog, and its Settings card facts.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/kimi-provider
+ */
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+import { KIMI_CODE_URL, KIMI_CONTEXT_WINDOW, KIMI_DEFAULT_MODEL, KIMI_PROVIDER_ID, KIMI_PROVIDER_NAME } from '../constants.js';
+import { TokenStore } from '../auth/store.js';
+import { TokenManager } from '../auth/tokens.js';
+import { DeviceFlowManager, identityFromTokens, refreshKimiToken } from '../auth/device-flow.js';
+import { loadOrCreateDeviceId } from '../auth/device-id.js';
+import { kimiIdentityHeaders } from '../auth/headers.js';
+import { KimiAdapter, parseKimiSession } from './kimi.js';
+import { readKimiUsage } from './usage.js';
+import { ProviderController } from '../auth/provider-controller.js';
+import { proxiedFetch } from '../http.js';
+/**
+ * Build the `kimi` route: its adapter and its login/lifecycle controller.
+ *
+ * @param options - resolved endpoints, paths, and shared services.
+ * @returns the route, ready to register and to serve over RPC.
+ */
+export function createKimiProvider(options) {
+    const fetchFn = options.fetchFn ?? proxiedFetch;
+    const store = new TokenStore(options.credentialFile, KIMI_PROVIDER_ID, parseKimiSession);
+    const deviceFlow = new DeviceFlowManager();
+    /** The wrapped in-flight attempt, so `pending()` is stable across calls. */
+    let current;
+    const toSession = (tokens) => ({
+        accessToken: tokens.accessToken,
+        ...tokens.refreshToken === undefined ? {} : { refreshToken: tokens.refreshToken },
+        expiresAt: tokens.expiresAt,
+        oauthHost: options.oauthHost,
+        apiBase: options.apiBase,
+        ...identityFromTokens(tokens.accessToken, tokens.refreshToken),
+    });
+    /** Adapt one device attempt onto the shared login contract. */
+    const wrap = (attempt) => ({
+        prompt: {
+            url: attempt.verificationUrl,
+            userCode: attempt.userCode,
+            expiresAt: attempt.expiresAt,
+            mode: 'device-code',
+        },
+        session: attempt.waitToken().then(toSession),
+        cancel: () => { attempt.cancel(); },
+    });
+    const flow = {
+        async start() {
+            const attempt = await deviceFlow.start(KIMI_PROVIDER_ID, {
+                host: options.oauthHost,
+                deviceId: await loadOrCreateDeviceId(options.dataDir),
+                fetchFn,
+            });
+            const wrapped = wrap(attempt);
+            current = wrapped;
+            // The manager drops its own record once the attempt settles; mirror that
+            // so `pending()` cannot report a finished login.
+            void attempt.waitToken().catch(() => undefined).finally(() => {
+                if (current === wrapped)
+                    current = undefined;
+            });
+            return wrapped;
+        },
+        pending() {
+            return deviceFlow.pending(KIMI_PROVIDER_ID) === undefined ? undefined : current;
+        },
+    };
+    const tokens = new TokenManager({
+        store,
+        displayName: KIMI_PROVIDER_NAME,
+        refresh: async (session) => {
+            const refreshToken = session.refreshToken;
+            if (refreshToken === undefined) {
+                throw new ProviderError(`${KIMI_PROVIDER_NAME} account has no refresh token; sign in again`, REAUTH_REQUIRED);
+            }
+            return refreshKimiToken({
+                host: session.oauthHost,
+                deviceId: await loadOrCreateDeviceId(options.dataDir),
+                fetchFn,
+            }, refreshToken);
+        },
+    });
+    const adapter = new KimiAdapter({
+        apiBase: options.apiBase,
+        discovery: options.discovery,
+        streamIdleTimeoutMs: options.streamIdleTimeoutMs,
+        tokens,
+        ...options.onWarn === undefined ? {} : { onWarn: options.onWarn },
+        ...options.resolveAttachments === undefined ? {} : { resolveAttachments: options.resolveAttachments },
+        identityHeaders: async () => kimiIdentityHeaders(await loadOrCreateDeviceId(options.dataDir)),
+        hiddenModels: () => options.preferences.hiddenIds(KIMI_PROVIDER_ID),
+        userModels: () => options.preferences.extraIds(KIMI_PROVIDER_ID),
+        modelOrder: () => options.preferences.orderOf(KIMI_PROVIDER_ID),
+        ...options.extraModels === undefined ? {} : { extraModels: options.extraModels },
+        fetchFn,
+    });
+    const spec = {
+        id: KIMI_PROVIDER_ID,
+        displayName: KIMI_PROVIDER_NAME,
+        codeUrl: KIMI_CODE_URL,
+        credentialFile: options.credentialFile,
+        discovery: options.discovery,
+        defaultModel: KIMI_DEFAULT_MODEL,
+        catalog: () => adapter.catalogEntries(),
+        catalogOwn: () => adapter.ownCatalogEntries(),
+        fallbackContextWindow: KIMI_CONTEXT_WINDOW,
+        discover: (accessToken) => adapter.fetchCatalog(accessToken),
+        usage: (accessToken) => readKimiUsage({ apiBase: options.apiBase, accessToken, fetchFn }),
+        details: () => [
+            { key: 'oauthHost', value: options.oauthHost },
+            { key: 'apiBase', value: options.apiBase },
+            { key: 'credentialFile', value: options.credentialFile },
+        ],
+        applyDiscovery: (ids) => { adapter.discover(ids); },
+    };
+    const controller = new ProviderController({
+        spec,
+        store,
+        tokens,
+        flow,
+        preferences: options.preferences,
+        ...options.onCatalogChanged === undefined ? {} : { onCatalogChanged: options.onCatalogChanged },
+        ...options.onWarn === undefined ? {} : { onWarn: options.onWarn },
+    });
+    // An explicit façade, not a spread: a spread would copy own properties and
+    // drop the class prototype, leaving every method undefined.
+    return {
+        id: controller.id,
+        displayName: controller.displayName,
+        credentialFile: controller.credentialFile,
+        adapter,
+        status: () => controller.status(),
+        login: (account) => controller.login(account),
+        cancel: () => controller.cancel(),
+        logout: (account) => controller.logout(account),
+        setDefault: (account) => controller.setDefault(account),
+        refresh: (account) => controller.refresh(account),
+        discover: (force) => controller.discover(force),
+        setModelVisible: (id, visible) => controller.setModelVisible(id, visible),
+        setModelOrder: (ids) => controller.setModelOrder(ids),
+        addModel: (id) => controller.addModel(id),
+        removeModel: (id) => controller.removeModel(id),
+        usage: (force) => controller.usage(force),
+        reload: () => controller.reload(),
+    };
+}

package/lib/providers/kimi.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { FetchFn } from '../http.js';
+import type { TokenManager } from '../auth/tokens.js';
+import type { SessionBase } from '../auth/store.js';
+import type { CatalogEntry } from './catalog.js';
+/** One catalog entry exposed as a selectable model. */
+export type KimiModelEntry = CatalogEntry;
+/**
+ * A stored Kimi Code login.
+ *
+ * The OAuth host and API base are recorded per account so a later refresh uses
+ * the same endpoints the login did, even if the plugin configuration changes.
+ */
+export interface KimiSession extends SessionBase {
+    /** OAuth host the tokens were issued by. */
+    oauthHost: string;
+    /** API base recorded at login time (diagnostics only). */
+    apiBase?: string;
+}
+/**
+ * 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 declare function parseKimiSession(value: unknown): KimiSession | undefined;
+/**
+ * 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 declare const KIMI_MODELS: readonly KimiModelEntry[];
+/** Constructor dependencies for {@link KimiAdapter}. */
+export interface KimiAdapterOptions {
+    /** Resolved Kimi Code API base (`<base>/responses`). */
+    apiBase: string;
+    /** Whether the live `/models` catalog is consulted when logged in. */
+    discovery: boolean;
+    /** Inactivity budget before a stalled stream is abandoned. */
+    streamIdleTimeoutMs: number;
+    /** OAuth token manager owning refresh and invalidation. */
+    tokens: TokenManager<KimiSession>;
+    /** Warning sink for discovery failures that fall back to the static catalog. */
+    onWarn?: (message: string) => void;
+    /** Resolve the attachment service per request, so a late service start still works. */
+    resolveAttachments?: () => AttachmentStore | undefined;
+    /**
+     * Client-identity headers (`X-Msh-*` + `User-Agent`) for this machine.
+     * Resolved per request because the device id file is read lazily.
+     */
+    identityHeaders?: () => Promise<Record<string, string>>;
+    /** Fetch implementation; defaults to the proxy-aware fetch. */
+    fetchFn?: FetchFn;
+    /** Called when a call proved the stored credential unusable. */
+    onCredentialRejected?: (account: string) => void;
+    /** Extra model ids from the plugin configuration, appended to the catalog. */
+    extraModels?: readonly string[];
+    /**
+     * The user's model rank for this route, most preferred first.
+     *
+     * Read per catalog query, so a drag-and-drop re-order takes effect at the
+     * picker's next refresh without rebuilding the adapter.
+     */
+    modelOrder?: () => Promise<readonly string[]>;
+    /**
+     * Model ids the session model picker must not offer.
+     *
+     * Read per catalog query, so a settings change takes effect at the picker's
+     * next refresh without rebuilding the adapter. A hidden model stays
+     * resolvable: an existing session that already selected it keeps working.
+     */
+    hiddenModels?: () => Promise<ReadonlySet<string>>;
+    /**
+     * Model ids the user added by hand.
+     *
+     * Read per catalog query, so the add button takes effect at the picker's next
+     * refresh. A hand-added id is published with conservative metadata: the
+     * endpoint is the authority on what it serves, not this build.
+     */
+    userModels?: () => Promise<readonly string[]>;
+}
+/** Kimi Code adapter serving the `kimi` provider route. */
+export declare class KimiAdapter extends LlmAdapter {
+    private readonly options;
+    /** Live catalog ids seen this session, used to accept renamed models. */
+    private discovered;
+    /** Ids the user added by hand, cached so the sync catalog can name them. */
+    private userAddedIds;
+    constructor(options: KimiAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): undefined;
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    /** The ids the picker must currently omit. */
+    private hidden;
+    resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /** Translate an auth failure into the message a user can act on. */
+    private refreshHint;
+    /**
+     * 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.
+     */
+    private catalog;
+    /**
+     * 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.
+     */
+    private shippedCatalog;
+    /** Whether one shipped entry covers a live model id. */
+    private entryMatches;
+    /** Resolve a requested model id onto its catalog entry. */
+    private entryFor;
+    /** Re-read the ids the user added by hand. */
+    private syncUserModels;
+    /**
+     * 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.
+     */
+    private addedEntries;
+    /** Record the live catalog for the picker; failures keep the shipped list. */
+    discover(ids: readonly string[]): void;
+    /** The curated catalog, for the Settings page's model list. */
+    catalogEntries(): readonly KimiModelEntry[];
+    /** What this route itself serves, without the ids added by hand. */
+    ownCatalogEntries(): readonly KimiModelEntry[];
+    /** Build and send one request. */
+    private request;
+    /** Client-identity headers for this machine, when configured. */
+    private identity;
+    /** Resolve image blocks through the attachment service, when it is present. */
+    private imageResolver;
+    /** Read the live `/models` catalog, or undefined when unavailable. */
+    fetchCatalog(accessToken: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
+}