@lihuu/dsh-ollama-cloud 0.1.0

package/lib/adapter.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `OllamaAdapter`: fetch + SSE against an Ollama (OpenAI-compatible)
+ * chat-completions endpoint, emitting harness StreamChunks. Transport-only:
+ * connection facts arrive through a thunk resolved once per operation and the
+ * bearer token through a per-request resolver.
+ *
+ * Model ids are normalized to Ollama's `:cloud` naming on every operation: a
+ * request for `deepseek-v4-flash` is sent as `deepseek-v4-flash:cloud`, and an
+ * already-suffixed id is forwarded unchanged.
+ *
+ * Dependencies are intentionally minimal: `@deepseek-ai/dsh-llm` (the harness
+ * LLM seam contract), `@deepseek-ai/cordis` (plugin framework), and
+ * `eventsource-parser` (SSE framing). Everything else is hand-rolled here.
+ *
+ * @module llm-ollama-cloud/adapter
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ModelModality, ResolvedRetryPolicy, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { RequestDefaults } from './serialize.ts';
+import type { WireError } from './types.ts';
+/** One optional model entry advertised by the direct-fetch adapter. */
+export interface OllamaCatalogModel {
+    /** Wire model id accepted by the configured endpoint; a missing `:cloud` suffix is appended. */
+    id: string;
+    /** Selector label; defaults to {@link id}. */
+    name?: string;
+    /** Optional selector detail for deployments with similar model variants. */
+    description?: string;
+    /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */
+    contextWindow?: number;
+    /** Per-request output cap for this model; omission falls back to the profile's {@link OllamaConnectionOptions.maxTokens}. */
+    maxTokens?: number;
+    /** Accepted request modalities; omission is text-only. */
+    inputModalities?: ModelModality[];
+}
+/**
+ * Validated connection facts for one operation. The plugin's
+ * `resolveAdapterOptions` is the one explicit resolve step producing this
+ * shape; the adapter trusts it and re-reads it per operation.
+ */
+export interface OllamaConnectionOptions {
+    /** Endpoint base; `/chat/completions` is appended. */
+    baseURL: string;
+    /** Environment-variable name holding the bearer token, resolved per request. */
+    apiKeyEnv: string;
+    /** Request defaults applied to every call (thinking mode, effort). */
+    defaults: RequestDefaults;
+    /** Default per-request output cap; explicit request values win. */
+    maxTokens: number;
+    /** Positive context capacity used when the selected model has no exact value. */
+    defaultContextWindow: number;
+    /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
+    models: readonly OllamaCatalogModel[];
+    /** Maximum provider idle time while one stream read is outstanding. */
+    streamIdleTimeoutMs: number;
+    /** Provider-owned model-request retry policy, already resolved. */
+    retryPolicy: ResolvedRetryPolicy;
+}
+/** Constructor options for {@link OllamaAdapter}: the operation-local resolution hooks the plugin owns. */
+export interface OllamaAdapterOptions {
+    /** Current validated connection facts; called once per operation. */
+    options: () => OllamaConnectionOptions;
+    /**
+     * Resolve the bearer token for the connection facts of one request. The
+     * snapshot is passed in — never re-read — so the key can only ever come
+     * from the same resolution as the endpoint it is sent to.
+     */
+    resolveApiKey: (connection: OllamaConnectionOptions) => Promise<string>;
+}
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Default combined request/response context capacity. */
+export declare const DEFAULT_CONTEXT_WINDOW = 1000000;
+/** Default per-request output-token cap. */
+export declare const DEFAULT_MAX_TOKENS = 65536;
+/** The Ollama cloud model-name suffix this adapter appends when missing. */
+export declare const CLOUD_SUFFIX = ":cloud";
+/** Largest value `setTimeout` accepts (2^31 - 1 ms). */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * Normalize a model id to Ollama's cloud naming. An id already carrying the
+ * `:cloud` suffix is returned unchanged; any other id gets it appended. This
+ * is the one place a bare harness model name becomes a wire model name.
+ * @param model - the requested model id.
+ * @returns the id with a `:cloud` suffix.
+ */
+export declare function normalizeCloud(model: string): string;
+/**
+ * Map an HTTP status to a stable LlmError code.
+ * @param status - status of a non-2xx provider response.
+ * @param error - parsed provider error body, when available.
+ * @returns the normalized harness error code.
+ */
+export declare function httpErrorCode(status: number, error?: WireError['error']): string;
+/**
+ * One instance serves every model name it was registered under. The harness
+ * model name is normalized to its cloud form and IS the wire model name.
+ *
+ * One stable signal reaches both initial fetch and body reads. Caller aborts
+ * map to `ABORTED`; the configured per-read idle watchdog maps to `TIMEOUT`.
+ */
+export declare class OllamaAdapter extends LlmAdapter {
+    private readonly config;
+    constructor(config: OllamaAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private request;
+}

package/lib/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Register an {@link OllamaAdapter} for the `ollama-cloud-direct` provider route
+ * on `ctx.llm`, with connection facts resolved once per operation from the
+ * plugin's `cordis.yml` mount config and the bearer token resolved per request
+ * through the credential seam (`ctx.credentials`), falling back to the
+ * process environment.
+ *
+ * Dependencies are intentionally minimal — `@deepseek-ai/dsh-llm` (the harness
+ * LLM seam contract), `@deepseek-ai/dsh-credentials` (the credential seam),
+ * `@deepseek-ai/cordis` (plugin framework), and `eventsource-parser` (SSE
+ * framing). There is no settings-section wiring and no schema library:
+ * configuration is static from the mount, and validation is hand-rolled. The
+ * route is `ollama-cloud-direct` (not `ollama-cloud`) so it can coexist with a
+ * pi-ai-configured `ollama-cloud` route.
+ *
+ * @module llm-ollama-cloud
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm';
+import type { OllamaCatalogModel, OllamaConnectionOptions } from './adapter.ts';
+export { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, MAX_TIMER_DELAY_MS, normalizeCloud, OllamaAdapter, } from './adapter.ts';
+export type { OllamaAdapterOptions, OllamaCatalogModel, OllamaConnectionOptions } from './adapter.ts';
+export type { RequestDefaults } from './serialize.ts';
+export type * from './types.ts';
+export declare const name = "llm-ollama-cloud";
+export declare const inject: string[];
+/**
+ * Plugin config from the `cordis.yml` mount entry. Every field is optional: a
+ * missing API key fails per request with `MISSING_CREDENTIAL`, omitted
+ * thinking mode uses the provider default, and omitted reasoning effort lets
+ * the server auto-enable thinking at its default.
+ */
+export interface Config {
+    /** Environment-variable name resolved per request; defaults to `OLLAMA_CLOUD_API_KEY`. */
+    apiKeyEnv?: string;
+    /** Endpoint base; defaults to the Ollama cloud API. */
+    baseURL?: string;
+    /** Deployment thinking policy; `disabled` limits every conversation request to `none` effort. */
+    thinking?: 'enabled' | 'disabled';
+    /** Default thinking effort (default unset, so the server picks); `off` maps to wire `none`. */
+    reasoningEffort?: 'off' | 'low' | 'high' | 'max';
+    /** Default per-request output cap (default 65,536); a model's own cap and explicit request values win. */
+    maxTokens?: number;
+    /** Positive context capacity used when the selected model has no exact value (default 1,000,000). */
+    defaultContextWindow?: number;
+    /** Advisory models shown by discovery consumers; a missing `:cloud` suffix is appended. */
+    models?: OllamaCatalogModel[];
+    /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
+    streamIdleTimeoutMs?: number;
+    /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
+    retryPolicy?: RetryPolicyConfig;
+}
+/** The public Ollama cloud API base. */
+export declare const PUBLIC_BASE_URL = "https://ollama.com/v1";
+/**
+ * The one explicit resolve step from raw mount config to validated connection
+ * facts, with every default and bound re-judged here (fail loud at load).
+ * @param config - raw plugin config.
+ * @returns validated connection facts plus the credential reference.
+ */
+export declare function resolveAdapterOptions(config: Config): OllamaConnectionOptions;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/serialize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Serialize harness messages into an Ollama chat completions request.
+ * Text-only (the OpenAI-compatible endpoint's image path is deferred); tool
+ * results become standalone `role: 'tool'` messages. Reasoning is replayed as
+ * the `reasoning` assistant field only for reasoning-capable models (a wire id
+ * containing `deepseek`), so non-reasoning models keep clean traces.
+ * @module dsh-llm-ollama-cloud/serialize
+ */
+import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm';
+import type { WireMessage, WireRequest } from './types.ts';
+/** Adapter-level request defaults (from plugin config). */
+export interface RequestDefaults {
+    thinking?: 'enabled' | 'disabled' | undefined;
+    reasoningEffort?: 'off' | 'low' | 'high' | 'max' | undefined;
+}
+/** The Ollama reasoning-effort values this adapter emits on the wire. */
+export type WireReasoningEffort = 'none' | 'low' | 'high' | 'max';
+/**
+ * Whether a model's reasoning should be passed back on assistant history.
+ * Only reasoning-capable models accept the `reasoning` field; a non-reasoning
+ * model ignores it, so it is written only for wire ids containing `deepseek`.
+ * @param model - the wire model id.
+ * @returns true when the model is treated as reasoning-capable.
+ */
+export declare function passReasoning(model: string): boolean;
+/**
+ * Serialize the conversation. `tool-result` blocks become standalone
+ * `{role: 'tool'}` messages; the harness puts each tool result in its own
+ * user-role message, so a mixed user message contributes its text first and
+ * its tool results as separate wire messages after.
+ * @param model - the wire model id, used to decide reasoning passback.
+ * @param messages - the harness conversation, in order.
+ * @returns the wire messages; order preserved, each tool result expanded into its own entry.
+ */
+export declare function serializeMessages(model: string, messages: Message[]): WireMessage[];
+/**
+ * Build the full wire request. Always streaming (`stream: true`, usage
+ * reporting on); optional fields are omitted rather than sent as null, so
+ * provider defaults apply.
+ * @param options - the harness request (model, history, system, tools, sampling).
+ * @param defaults - adapter-level thinking defaults; undefined fields put nothing on the wire.
+ * @returns the chat-completions request body.
+ */
+export declare function serializeRequest(options: GenerateOptions, defaults?: RequestDefaults): WireRequest;

package/lib/sse.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decode an SSE byte stream into event `data` payloads. Framing — chunk
+ * reassembly, UTF-8/CRLF/BOM handling, comment and non-data field skipping,
+ * multi-`data:` joining — is `eventsource-parser`'s. Comments are reported
+ * only through an optional transport-activity callback. This module keeps the
+ * OpenAI-compatible protocol: the literal `[DONE]` is yielded so the caller
+ * owns final flushing, and EOF before it raises {@link LlmError}. Framing is
+ * spec-strict: an event dispatches only on its blank-line terminator, so an
+ * unterminated tail at EOF is truncation, not a flushable payload.
+ *
+ * @module dsh-llm-ollama-cloud/sse
+ */
+/** The terminal payload OpenAI-compatible endpoints send after the last chunk. */
+export declare const DONE = "[DONE]";
+/**
+ * Parse an SSE byte stream into data payloads. Yields `[DONE]` as the final
+ * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
+ * without it (truncated response — the model call cannot be trusted).
+ * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onComment - optional transport-activity callback; comments never enter the yielded payload stream.
+ * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
+ */
+export declare function parseSse(stream: ReadableStream<BufferSource>, onComment?: (comment: string) => void): AsyncGenerator<string>;

package/lib/translate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Translate Ollama wire chunks into the harness `StreamChunk` protocol with
+ * one stateful harness block per content, reasoning, or tool call index. An
+ * empty initial reasoning delta does not open a block. Finish reason and the
+ * latest usage are deferred until `[DONE]`, covering both finish-attached and
+ * trailing usage-only shapes while ensuring no chunk follows `finish`.
+ * @module dsh-llm-ollama-cloud/translate
+ */
+import type { FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { WireUsage } from './types.ts';
+/**
+ * Map the wire finish_reason vocabulary to the harness FinishReason.
+ * @param reason - the wire `finish_reason` string.
+ * @returns the mapped reason; unrecognized values (content_filter, …) become `{kind: 'error'}` with the uppercased value as `code`.
+ */
+export declare function mapFinishReason(reason: string): FinishReason;
+/**
+ * Map wire usage fields to the harness convention of DISJOINT counts. Cache
+ * hits and reasoning tokens are carried only when the wire reported them.
+ * @param usage - wire usage from the finish chunk or the trailing usage-only chunk.
+ * @returns disjoint harness counts; cache/reasoning fields present only when the wire reported them.
+ */
+export declare function mapUsage(usage: WireUsage): TokenUsage;
+/**
+ * Consume SSE data payloads (ending with `[DONE]`) and yield StreamChunks.
+ * Malformed JSON payloads abort the stream with `MALFORMED_RESPONSE`.
+ * @param payloads - SSE data payloads from {@link parseSse}, `[DONE]`-terminated.
+ * @returns deltas as they arrive; `block-end`s, `usage`, and `finish` are all deferred to the `[DONE]` sentinel.
+ *   A `stop` (or absent) finish with no opened blocks is a degenerate provider completion and maps to an
+ *   `EMPTY_RESPONSE` error finish instead of a successful empty message.
+ */
+export declare function translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk>;

package/lib/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Ollama chat-completions wire format (OpenAI-compatible). Types only.
+ *
+ * Source of truth: Ollama's OpenAI-compatible `/v1/chat/completions` endpoint
+ * (https://ollama.com) plus the empirical behaviour of local Ollama serving
+ * `deepseek-v4-flash:cloud` (2026-08). Reasoning reaches the model in the
+ * `reasoning` delta field (not `reasoning_content`), and reasoning effort is a
+ * single `reasoning_effort` value (`none`/`low`/`medium`/`high`/`max`) rather
+ * than a separate `thinking` toggle: omitting the field auto-enables thinking
+ * at the server default, while `none` disables it.
+ *
+ * @module dsh-llm-ollama-cloud/types
+ */
+/** Request body for `POST {baseURL}/chat/completions`. */
+export interface WireRequest {
+    model: string;
+    messages: WireMessage[];
+    stream: true;
+    stream_options: {
+        include_usage: true;
+    };
+    /** Thinking effort; `none` disables reasoning and an omission uses the provider default. */
+    reasoning_effort?: 'none' | 'low' | 'medium' | 'high' | 'max';
+    tools?: WireTool[];
+    temperature?: number;
+    max_tokens?: number;
+    /** Stop sequences (OpenAI `stop`); generation halts as soon as the model produces one. */
+    stop?: string[];
+}
+/** System-role message: a single string of instructions. */
+export interface WireSystemMessage {
+    role: 'system';
+    content: string;
+}
+/** User-role message; Ollama accepts a plain string for text-only input. */
+export interface WireUserMessage {
+    role: 'user';
+    content: string;
+}
+/** Tool-role message: the result of one tool call, keyed by its call id. */
+export interface WireToolMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+}
+/** One entry of the request `messages` array, discriminated on `role`. */
+export type WireMessage = WireSystemMessage | WireUserMessage | WireAssistantMessage | WireToolMessage;
+/**
+ * Assistant-role history message. The harness replays `content: ""` (never
+ * null) on tool-call-only turns — some gateways reject null — and sends null
+ * only when the turn carried neither text nor tool calls.
+ */
+export interface WireAssistantMessage {
+    role: 'assistant';
+    content: string | null;
+    /**
+     * CoT passback, present only on a turn whose assistant content carried
+     * reasoning AND whose model is reasoning-capable (a wire id containing
+     * `deepseek`). Ollama accepts the `reasoning` field on assistant history
+     * messages; a non-reasoning model simply ignores it, so it is only written
+     * for reasoning-capable models to keep non-reasoning traces clean.
+     */
+    reasoning?: string;
+    tool_calls?: WireToolCall[];
+}
+/** A completed tool call replayed on an assistant history message; `arguments` is the raw JSON string. */
+export interface WireToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** One entry of the request `tools` array; `parameters` is a JSON Schema object. */
+export interface WireTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** One parsed SSE `data:` payload (a chat.completion.chunk). */
+export interface WireChunk {
+    choices?: WireChoice[];
+    /** Arrives attached to the finish chunk and/or as a trailing usage-only chunk. */
+    usage?: WireUsage | null;
+}
+/** One streamed choice (requests always ask for a single one); `finish_reason` is non-null only on its terminal chunk. */
+export interface WireChoice {
+    delta?: WireDelta;
+    finish_reason?: string | null;
+}
+/** The incremental content of one streamed choice; any subset of fields may be present per chunk. */
+export interface WireDelta {
+    role?: string;
+    /** Visible text. Null/empty on reasoning/tool-call chunks. */
+    content?: string | null;
+    /**
+     * Thinking-mode CoT. The FIRST chunk carries an empty string (must not open
+     * a reasoning block); absent entirely in non-thinking mode.
+     */
+    reasoning?: string | null;
+    tool_calls?: WireToolCallDelta[];
+}
+/** A streamed fragment of one tool call; fragments sharing an `index` concatenate into one call. */
+export interface WireToolCallDelta {
+    /** Disambiguates parallel tool calls; stable across a call's deltas. */
+    index: number;
+    /** Present on the first delta of each call only. */
+    id?: string;
+    type?: 'function';
+    function?: {
+        /** Present on the first delta of each call only. */
+        name?: string;
+        /** Argument JSON fragment (concatenate across deltas). */
+        arguments?: string;
+    };
+}
+/**
+ * Wire token accounting. Ollama's OpenAI-compatible endpoint reports standard
+ * `prompt_tokens`/`completion_tokens`; the cache and reasoning details follow
+ * the OpenAI-compat spelling when the backend supplies them.
+ */
+export interface WireUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
+/** Non-2xx error body. */
+export interface WireError {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: string;
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lihuu/dsh-ollama-cloud",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness plugin: adds the Ollama cloud chat-completions provider for LLM models.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/index.js",
+    "lib/**/*.d.ts",
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node build.mjs",
+    "build:types": "tsc -p tsconfig.json",
+    "build:bundle": "node build.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/dsh-credentials": "*"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "llm",
+    "ollama"
+  ]
+}