dsh-subscriptions 0.1.5 → 0.2.0

package/lib/providers/ollama-settings.js

@@ -0,0 +1,197 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+function fail(message) {
+    throw new Error(message);
+}
+function readNonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        fail(`${field} must be a non-empty string`);
+    return value;
+}
+function readPositiveInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        fail(`${field} must be a positive integer`);
+    }
+    return value;
+}
+function readBoolean(value, field) {
+    if (typeof value !== 'boolean')
+        fail(`${field} must be a boolean`);
+    return value;
+}
+/**
+ * Accept only an absolute http(s) base URL with no credentials, query, or
+ * fragment, and return its trimmed form. The route appends `/tags`, `/show`,
+ * and `/v1/chat/completions` to this value, so anything else would build a URL
+ * that cannot work — and a non-official host receives the referenced
+ * credential, which the dialog tells the user.
+ * @param value - the candidate URL.
+ * @returns the trimmed URL to store.
+ * @throws when the value is not a usable absolute http(s) URL.
+ */
+export function validateOllamaBaseURL(value) {
+    const raw = readNonEmptyString(value, 'baseURL');
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        fail('baseURL must be an absolute URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        fail('baseURL must use http or https');
+    if (url.username !== '' || url.password !== '')
+        fail('baseURL must not carry credentials');
+    if (url.search !== '' || url.hash !== '')
+        fail('baseURL must not carry a query or fragment');
+    return raw.trim();
+}
+/** Credential references are looked up by name, so whitespace is always a typo. */
+function readApiKeyRef(value) {
+    const raw = readNonEmptyString(value, 'apiKeyRef');
+    if (/\s/.test(raw))
+        fail('apiKeyRef must not contain whitespace');
+    return raw;
+}
+function readEfforts(value, field) {
+    if (!Array.isArray(value) || value.length === 0)
+        fail(`${field} must be a non-empty array`);
+    const efforts = [];
+    for (const entry of value) {
+        const effort = readNonEmptyString(entry, `${field} entries`);
+        if (!efforts.includes(effort))
+            efforts.push(effort);
+    }
+    return efforts;
+}
+function readModel(entry, index) {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        fail(`models[${index}] must be an object`);
+    }
+    const record = entry;
+    // The id is the wire id, so surrounding whitespace is always a paste
+    // artifact; trim it before the duplicate check sees it.
+    const model = { id: readNonEmptyString(record.id, `models[${index}].id`).trim() };
+    if (record.name !== undefined)
+        model.name = readNonEmptyString(record.name, `models[${index}].name`);
+    if (record.contextWindow !== undefined) {
+        model.contextWindow = readPositiveInteger(record.contextWindow, `models[${index}].contextWindow`);
+    }
+    if (record.contextOverride !== undefined) {
+        model.contextOverride = readPositiveInteger(record.contextOverride, `models[${index}].contextOverride`);
+    }
+    if (record.maxTokens !== undefined) {
+        model.maxTokens = readPositiveInteger(record.maxTokens, `models[${index}].maxTokens`);
+    }
+    if (record.vision !== undefined)
+        model.vision = readBoolean(record.vision, `models[${index}].vision`);
+    if (record.thinking !== undefined)
+        model.thinking = readBoolean(record.thinking, `models[${index}].thinking`);
+    if (record.efforts !== undefined)
+        model.efforts = readEfforts(record.efforts, `models[${index}].efforts`);
+    if (record.defaultEffort !== undefined) {
+        const effort = readNonEmptyString(record.defaultEffort, `models[${index}].defaultEffort`);
+        // The runtime rejects a default the model does not advertise, so a
+        // mismatch is a store bug rather than something to carry forward.
+        if (model.efforts !== undefined && !model.efforts.includes(effort)) {
+            fail(`models[${index}].defaultEffort must be one of its efforts`);
+        }
+        model.defaultEffort = effort;
+    }
+    return model;
+}
+/**
+ * Validate one settings document, dropping unknown keys and duplicate model
+ * ids (first wins, matching the Cursor store's visible-model handling).
+ * @param input - the parsed store document or an RPC payload.
+ * @throws when a known field has the wrong type or an unusable value.
+ */
+export function validateOllamaSettings(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        fail('Ollama settings must be an object');
+    }
+    const record = input;
+    const settings = {};
+    if (record.models !== undefined) {
+        if (!Array.isArray(record.models))
+            fail('models must be an array');
+        const seen = new Set();
+        const models = [];
+        for (const [index, entry] of record.models.entries()) {
+            const model = readModel(entry, index);
+            if (seen.has(model.id))
+                continue;
+            seen.add(model.id);
+            models.push(model);
+        }
+        settings.models = models;
+    }
+    if (record.web !== undefined)
+        settings.web = readBoolean(record.web, 'web');
+    if (record.baseURL !== undefined)
+        settings.baseURL = validateOllamaBaseURL(record.baseURL);
+    if (record.apiKeyRef !== undefined)
+        settings.apiKeyRef = readApiKeyRef(record.apiKeyRef);
+    return settings;
+}
+/**
+ * Durable Ollama Cloud configuration under the DSH home directory. Writes are
+ * serialized and atomic (temp file with mode 0600, then rename), so a crash
+ * never leaves a half-written document and a concurrent writer cannot lose an
+ * earlier save.
+ */
+export class OllamaSettingsStore {
+    path;
+    onCorrupt;
+    current = {};
+    writes = Promise.resolve();
+    /** Set when the stored file existed but was unreadable or invalid. */
+    corrupt;
+    constructor(path = dshHomePath('plugins', 'subscriptions', 'ollama-settings.json'), onCorrupt) {
+        this.path = path;
+        this.onCorrupt = onCorrupt;
+        try {
+            this.current = validateOllamaSettings(JSON.parse(readFileSync(path, 'utf8')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                // A broken file must not take the whole plugin down: degrade to
+                // defaults, keep the file untouched for manual recovery, and let
+                // the next save overwrite it.
+                this.corrupt = error instanceof Error ? error.message : String(error);
+                // The raw V8 message quotes the offending bytes; the log keeps a
+                // fixed diagnosis and corruption() carries the detail for callers
+                // that surface it outside log lines.
+                this.onCorrupt?.(`Ollama settings at ${path} are unreadable and ignored; defaults serve until the next save.`);
+            }
+        }
+    }
+    /** Why the stored file is ignored, when it is. */
+    corruption() { return this.corrupt; }
+    get() { return structuredClone(this.current); }
+    /** The stored catalog, or `undefined` when the store carries no override. */
+    models() { return this.current.models; }
+    web() { return this.current.web; }
+    baseURL() { return this.current.baseURL; }
+    apiKeyRef() { return this.current.apiKeyRef; }
+    set(input) {
+        const validated = validateOllamaSettings(input);
+        const run = this.writes.then(async () => {
+            await mkdir(dirname(this.path), { recursive: true });
+            const temporary = `${this.path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify(validated, null, 2), { mode: 0o600 });
+                await rename(temporary, this.path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+            this.current = validated;
+            this.corrupt = undefined;
+        });
+        this.writes = run.catch(() => undefined);
+        return run;
+    }
+}

package/lib/providers/ollama-web.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Ollama-native web capabilities: search and fetch ride the Cloud
+ * `/api/web_search` + `/api/web_fetch` endpoints independently of the
+ * selected chat model. Both providers share the `ollama-cloud` id because
+ * the seam addresses each capability kind separately.
+ */
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+import type { FetchFn } from './common.js';
+/** Shared provider id for both web capabilities. */
+export declare const OLLAMA_WEB_PROVIDER_ID = "ollama-cloud";
+/** Per-attempt budget; the seam owns overall cancellation. */
+export declare const OLLAMA_WEB_TIMEOUT_MS = 15000;
+/** Search result cap applied at the request layer. */
+export declare const OLLAMA_WEB_MAX_RESULTS = 10;
+/** Response body bound for web payloads. */
+export declare const OLLAMA_WEB_MAX_BYTES: number;
+export interface OllamaWebOptions {
+    /** Resolve the API key per call; `undefined` means unconfigured. */
+    apiKey: () => Promise<string | undefined>;
+    /**
+     * Native base URL; web endpoints ride it unchanged (no `/v1` mapping). A
+     * function form is read per call so a Settings save applies without a
+     * restart.
+     */
+    baseURL: string | (() => string);
+    /** Local gate; absent counts as enabled. Read on every call. */
+    enabled?: () => boolean;
+    fetchFn?: FetchFn;
+    requestTimeoutMs?: number;
+}
+/** Search provider behind DSH's stock web_search tool. */
+export declare class OllamaWebSearchProvider implements WebSearchProvider {
+    private readonly options;
+    readonly id = "ollama-cloud";
+    constructor(options: OllamaWebOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+/** Fetch provider behind DSH's stock web_fetch tool. */
+export declare class OllamaWebFetchProvider implements WebFetchProvider {
+    private readonly options;
+    readonly id = "ollama-cloud";
+    constructor(options: OllamaWebOptions);
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}

package/lib/providers/ollama-web.js

@@ -0,0 +1,213 @@
+/**
+ * Ollama-native web capabilities: search and fetch ride the Cloud
+ * `/api/web_search` + `/api/web_fetch` endpoints independently of the
+ * selected chat model. Both providers share the `ollama-cloud` id because
+ * the seam addresses each capability kind separately.
+ */
+import { attributionHeaders } from '@deepseek-ai/dsh-llm';
+import { WebError } from '@deepseek-ai/dsh-web';
+import { readBoundedJson } from './common.js';
+import { hostFetch } from '../http.js';
+/** Shared provider id for both web capabilities. */
+export const OLLAMA_WEB_PROVIDER_ID = 'ollama-cloud';
+/** Per-attempt budget; the seam owns overall cancellation. */
+export const OLLAMA_WEB_TIMEOUT_MS = 15_000;
+/** Search result cap applied at the request layer. */
+export const OLLAMA_WEB_MAX_RESULTS = 10;
+/** Response body bound for web payloads. */
+export const OLLAMA_WEB_MAX_BYTES = 2 * 1024 * 1024;
+/** The effective base URL; both forms are read fresh so saves apply live. */
+function baseURLOf(options) {
+    return typeof options.baseURL === 'function' ? options.baseURL() : options.baseURL;
+}
+function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}
+function isRedirectFailure(error) {
+    // Real fetch failures nest: undici reports `fetch failed` on top with the
+    // redirect rejection in `cause`. Walk the chain instead of reading only
+    // the outer message.
+    for (let current = error; current instanceof Error; current = current.cause) {
+        if (/redirect/i.test(current.message))
+            return true;
+    }
+    return false;
+}
+async function postJson(url, apiKey, payload, options, signal) {
+    const fetchFn = options.fetchFn ?? hostFetch;
+    const timeoutMs = options.requestTimeoutMs ?? OLLAMA_WEB_TIMEOUT_MS;
+    // Exactly two attempts; only a timeout or a pre-response transport
+    // failure retries. HTTP errors, malformed replies, missing credentials,
+    // redirects, and caller cancellation never retry.
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+        throwIfAborted(signal);
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort(new Error('ollama web request timed out'));
+        }, timeoutMs);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+        const onCallerAbort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', onCallerAbort, { once: true });
+        try {
+            const response = await fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'accept': 'application/json',
+                    'authorization': `Bearer ${apiKey}`,
+                    ...attributionHeaders(),
+                },
+                body: JSON.stringify(payload),
+                redirect: 'error',
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new WebError(`ollama web request failed (HTTP ${String(response.status)})`, 'OLLAMA_WEB_BAD_RESPONSE');
+            }
+            try {
+                return await readBoundedJson(response, 'ollama web request', OLLAMA_WEB_MAX_BYTES);
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                // A timeout can also land mid-body: same retry treatment as a
+                // connect timeout, under the same code.
+                if (timedOut) {
+                    if (attempt >= 2)
+                        throw new WebError('ollama web request timed out', 'OLLAMA_WEB_TIMEOUT');
+                    continue;
+                }
+                // The SyntaxError cause is dropped on purpose: V8 quotes the
+                // offending body bytes, which would carry provider text into
+                // logs through the chained message. An oversized body lands
+                // here too: loud and unretried.
+                throw new WebError('ollama web request returned a malformed reply', 'OLLAMA_WEB_BAD_REPLY');
+            }
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            // Classified failures carry their own code and never retry.
+            if (error instanceof WebError)
+                throw error;
+            if (isRedirectFailure(error)) {
+                throw new WebError('ollama web request redirected; redirects are not followed', 'OLLAMA_WEB_REDIRECT');
+            }
+            if (timedOut) {
+                if (attempt >= 2)
+                    throw new WebError('ollama web request timed out', 'OLLAMA_WEB_TIMEOUT', { cause: error });
+                continue;
+            }
+            if (attempt >= 2) {
+                throw new WebError('ollama web request transport failed', 'OLLAMA_WEB_TRANSPORT', { cause: error });
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    throw new WebError('ollama web request failed', 'OLLAMA_WEB_TRANSPORT');
+}
+function recordOf(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+async function resolveWebKey(options, signal) {
+    throwIfAborted(signal);
+    const apiKey = await options.apiKey();
+    if (apiKey === undefined) {
+        throw new WebError('Ollama web search requires an Ollama Cloud API key; configure OLLAMA_API_KEY', 'OLLAMA_WEB_MISSING_CREDENTIAL');
+    }
+    return apiKey;
+}
+/**
+ * Refuse a call while the Settings switch is off. The host normally selects
+ * only available providers, but a pinned `searchProvider`/`fetchProvider`
+ * would otherwise keep routing through a provider the user turned off.
+ */
+function assertEnabled(options) {
+    if (options.enabled?.() === false) {
+        throw new WebError('Ollama web search/fetch is disabled in Settings', 'OLLAMA_WEB_DISABLED');
+    }
+}
+/** Search provider behind DSH's stock web_search tool. */
+export class OllamaWebSearchProvider {
+    options;
+    id = OLLAMA_WEB_PROVIDER_ID;
+    constructor(options) {
+        this.options = options;
+    }
+    available() {
+        try {
+            new URL(baseURLOf(this.options));
+        }
+        catch {
+            return false;
+        }
+        return this.options.enabled?.() ?? true;
+    }
+    async search(request, signal) {
+        assertEnabled(this.options);
+        const apiKey = await resolveWebKey(this.options, signal);
+        const base = baseURLOf(this.options).replace(/\/+$/, '');
+        const payload = await postJson(`${base}/web_search`, apiKey, {
+            query: request.query,
+            ...(request.maxResults === undefined ? {} : { max_results: Math.min(request.maxResults, OLLAMA_WEB_MAX_RESULTS) }),
+        }, this.options, signal);
+        const results = recordOf(payload)?.['results'];
+        if (!Array.isArray(results))
+            throw new WebError('ollama web search returned no results array', 'OLLAMA_WEB_BAD_REPLY');
+        // Official shape per docs: {title, url, content}. The snippet rides
+        // `content`, not `snippet`.
+        const sources = results.flatMap(entry => {
+            const record = recordOf(entry);
+            const url = record?.['url'];
+            if (typeof url !== 'string' || url.length === 0)
+                return [];
+            return [{
+                    url,
+                    ...(typeof record?.['title'] === 'string' ? { title: record?.['title'] } : {}),
+                    ...(typeof record?.['content'] === 'string' ? { snippet: record?.['content'] } : {}),
+                }];
+        });
+        return { sources, truncated: false };
+    }
+}
+/** Fetch provider behind DSH's stock web_fetch tool. */
+export class OllamaWebFetchProvider {
+    options;
+    id = OLLAMA_WEB_PROVIDER_ID;
+    constructor(options) {
+        this.options = options;
+    }
+    available() {
+        try {
+            new URL(baseURLOf(this.options));
+        }
+        catch {
+            return false;
+        }
+        return this.options.enabled?.() ?? true;
+    }
+    async fetch(request, signal) {
+        assertEnabled(this.options);
+        const apiKey = await resolveWebKey(this.options, signal);
+        const base = baseURLOf(this.options).replace(/\/+$/, '');
+        const payload = await postJson(`${base}/web_fetch`, apiKey, { url: request.url }, this.options, signal);
+        // Official shape per docs: {title, content, links}. The endpoint
+        // answers the retrieval itself, so the request URL is the result URL
+        // and a decoded body means success.
+        const record = recordOf(payload);
+        const content = record?.['content'];
+        if (typeof content !== 'string') {
+            throw new WebError('ollama web fetch returned a malformed reply', 'OLLAMA_WEB_BAD_REPLY');
+        }
+        return { url: request.url, statusCode: 200, body: { kind: 'text', content }, truncated: false };
+    }
+}

package/lib/providers/ollama.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Ollama Cloud provider: a key-based OpenAI-completions route with no OAuth
+ * session. The credential arrives per request as a bearer key; chat posts to
+ * the configured native baseURL's `/v1` sibling. The route ships no catalog:
+ * only models the user stored on the Settings card are served, so an empty
+ * store hides the picker entry and rejects every chat model.
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { DiscoveredModel, FetchFn } from './common.js';
+import type { OllamaModelSetting } from './ollama-settings.js';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+/** Route id owned by this adapter. Not a member of the OAuth `PROVIDER_IDS`. */
+export declare const OLLAMA_CLOUD_ROUTE = "ollama-cloud";
+/** Default credential reference naming the Ollama Cloud API key. */
+export declare const DEFAULT_OLLAMA_API_KEY_REF = "OLLAMA_API_KEY";
+/** Default native base URL; chat maps it to its `/v1` sibling. */
+export declare const DEFAULT_OLLAMA_BASE_URL = "https://ollama.com/api";
+/** Fallback per-request output cap; Ollama publishes no per-model limit. */
+export declare const OLLAMA_DEFAULT_MAX_TOKENS = 32768;
+/** Fallback context window for a row the endpoint never described. */
+export declare const OLLAMA_DEFAULT_CONTEXT_WINDOW = 262144;
+/**
+ * Budget for the Settings card's explicit cloud listing. Longer than the
+ * picker's discovery bound because a user waits on this one and `/api/show`
+ * runs once per model.
+ */
+export declare const OLLAMA_PULL_TIMEOUT_MS = 20000;
+/**
+ * The window the session plans against: the user's override, capped at what
+ * the endpoint advertises (or, without discovery, the stored snapshot). The
+ * cap keeps a stale or mistyped override from planning past the model.
+ */
+export declare function effectiveContextWindow(row: {
+    contextWindow: number;
+    contextOverride: number | undefined;
+}, discovered: number | undefined): number;
+export interface OllamaAdapterOptions {
+    /** Resolve the API key per request; `undefined` means unconfigured. */
+    apiKey: () => Promise<string | undefined>;
+    /**
+     * Live native base URL (`https://ollama.com/api`); chat maps it to `/v1`.
+     * Read per request so a Settings save takes effect without a restart.
+     */
+    baseURL: () => string;
+    /**
+     * Live catalog snapshot, in picker order. The Settings store (or a
+     * non-empty config override) is the only source; an empty list means the
+     * route serves no model.
+     */
+    catalog: () => readonly OllamaModelSetting[];
+    /** Per-model default-effort override, winning over the stored row. */
+    defaultEffortOf?: (model: string) => string | undefined;
+    /** Live discovery via `/api/tags` + `/api/show` (default true). */
+    discovery?: boolean;
+    fetchFn?: FetchFn;
+    resolveAttachments?: () => AttachmentStore | undefined;
+    streamIdleTimeoutMs?: number;
+    onWarn?: (message: string) => void;
+}
+/** Map a native base URL to its OpenAI-compatible chat sibling. */
+export declare function ollamaChatBaseURL(baseURL: string): string;
+/**
+ * Normalize one listing id to the wire id the chat endpoint accepts. The
+ * Cloud listing advertises bare names (`glm-5.3`) while its chat wire wants
+ * the `:cloud` tag; a local daemon reached through a custom base URL takes
+ * the bare name, so only the official host gets the tag. An id that already
+ * carries a tag is returned unchanged.
+ * @param id - the id as listed by `/api/tags`.
+ * @param baseURL - the native base URL the listing came from.
+ * @returns the id to store and send on the chat wire.
+ */
+export declare function normalizeOllamaModelId(id: string, baseURL: string): string;
+export interface OllamaDiscoveryOptions {
+    baseURL: string;
+    apiKey: string | undefined;
+    fetchFn?: FetchFn | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** One discovered Cloud model, with the capability flags the card badges. */
+export interface OllamaDiscoveredModel extends DiscoveredModel {
+    /** The id exactly as `/api/tags` published it, before wire normalization. */
+    rawId: string;
+    /** The endpoint advertised the `thinking` capability. */
+    thinking: boolean;
+}
+/**
+ * List Cloud models via `/api/tags`, enriching through `/api/show`. A failed
+ * enrichment degrades to an id-only row; a failed listing fails. Listing ids
+ * are normalized to their wire form ({@link normalizeOllamaModelId}) while
+ * `/api/show` still receives the id the endpoint published.
+ */
+export declare function fetchOllamaModels(options: OllamaDiscoveryOptions): Promise<OllamaDiscoveredModel[]>;
+export declare function ollamaChatRequestBody(options: GenerateOptions, messages: Record<string, unknown>[], maxTokens: number | undefined): Record<string, unknown>;
+export declare class OllamaAdapter extends LlmAdapter {
+    private readonly options;
+    private readonly catalogCache;
+    constructor(options: OllamaAdapterOptions);
+    /** Drop the discovery snapshot so the next picker pass re-reads the endpoint. */
+    invalidateModels(): void;
+    private rows;
+    providerInfo(provider: string): LlmProviderInfo;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    private staticList;
+    resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}