dsh-subscriptions 0.1.5 → 0.2.2

package/lib/providers/ollama-web.js

@@ -0,0 +1,231 @@
+/**
+ * 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>;
+}