@lihuu/dsh-ollama-cloud 0.1.0

package/src/serialize.ts

@@ -0,0 +1,215 @@
+/**
+ * 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 { contentHasImage, LlmError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
+import type {
+  WireMessage,
+  WireRequest,
+  WireTool,
+} 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'
+
+interface ResolvedThinking {
+  reasoningEffort?: WireReasoningEffort
+}
+
+/**
+ * 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 function passReasoning(model: string): boolean {
+  return model.includes('deepseek')
+}
+
+/** Validate the adapter-owned effort before resolving its Ollama wire value. */
+function reasoningEffort(effort: NonNullable<GenerateOptions['reasoningEffort']>): 'off' | 'low' | 'high' | 'max' {
+  if (effort === 'off' || effort === 'low' || effort === 'high' || effort === 'max') {
+    return effort as 'off' | 'low' | 'high' | 'max'
+  }
+  throw new LlmError(
+    `Ollama does not support reasoning effort "${effort}"`,
+    'UNSUPPORTED_REASONING_EFFORT',
+  )
+}
+
+/**
+ * Resolve one legal thinking/effort pair into an Ollama wire effort. An `off`
+ * (or a `disabled` deployment default) maps to `none`; an explicit effort maps
+ * to its Ollama spelling; an omitted effort with thinking enabled sends
+ * nothing so the server auto-enables thinking at its default.
+ * @param options - the harness request.
+ * @param defaults - adapter-level thinking defaults.
+ * @returns the wire `reasoning_effort`, or nothing when the server default should apply.
+ */
+function resolveThinking(options: GenerateOptions, defaults: RequestDefaults): ResolvedThinking {
+  if (options.purpose === 'session-title') return { reasoningEffort: 'none' }
+  const effort = options.reasoningEffort === undefined
+    ? defaults.reasoningEffort
+    : reasoningEffort(options.reasoningEffort)
+  if (defaults.thinking === 'disabled' && effort !== undefined && effort !== 'off') {
+    throw new LlmError(
+      `Ollama deployment does not support reasoning effort "${effort}"`,
+      'UNSUPPORTED_REASONING_EFFORT',
+    )
+  }
+  if (effort === 'off') return { reasoningEffort: 'none' }
+  if (effort === 'low' || effort === 'high' || effort === 'max') {
+    return { reasoningEffort: effort }
+  }
+  // effort undefined: disabled defaults suppress reasoning, enabled or unset
+  // ones send nothing and let the server pick its default.
+  return defaults.thinking === 'disabled' ? { reasoningEffort: 'none' } : {}
+}
+
+/** Join the text blocks of a message (used for user/tool-result content). */
+function flattenText(blocks: ContentBlock[]): string {
+  return blocks
+    .filter(block => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+/** Reject core image content before any text-flattening path can silently erase it. */
+function assertTextOnly(blocks: readonly ContentBlock[]): void {
+  if (contentHasImage(blocks)) {
+    throw new LlmError('The Ollama chat-completions adapter does not support image content yet.', 'UNSUPPORTED_CONTENT')
+  }
+}
+
+/** Serialize one assistant message (text + optional reasoning + tool calls). */
+function serializeAssistant(message: Message, model: string): WireMessage {
+  const text = flattenText(message.content)
+  const reasoning = message.content
+    .filter(block => block.type === 'reasoning')
+    .map(block => block.text)
+    .join('')
+  const toolCalls = message.content
+    .filter(block => block.type === 'tool-call')
+    .map(block => ({
+      id: block.id,
+      type: 'function' as const,
+      function: { name: block.name, arguments: block.arguments },
+    }))
+
+  return {
+    role: 'assistant',
+    // Text-less turns send "" — NEVER null. Reasoning-only turns (the model
+    // can answer entirely in the reasoning channel) risk a gateway 400, and
+    // since the message sits durably in the session log, a null here bricks
+    // every later turn of that session.
+    content: text,
+    // CoT passback only for reasoning-capable models, via the `reasoning`
+    // field Ollama accepts on assistant history.
+    ...passReasoning(model) && reasoning.length > 0 ? { reasoning } : {},
+    ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {},
+  }
+}
+
+/**
+ * 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 function serializeMessages(model: string, messages: Message[]): WireMessage[] {
+  const wire: WireMessage[] = []
+  for (const message of messages) {
+    assertTextOnly(message.content)
+    if (message.role === 'system') {
+      wire.push({ role: 'system', content: flattenText(message.content) })
+      continue
+    }
+    if (message.role === 'assistant') {
+      wire.push(serializeAssistant(message, model))
+      continue
+    }
+    // user role: tool results ride in user messages in the harness
+    // vocabulary, but Ollama wants them as role:'tool' messages.
+    const toolResults = message.content.filter(block => block.type === 'tool-result')
+    const text = flattenText(message.content)
+    if (text.length > 0 || toolResults.length === 0) {
+      wire.push({ role: 'user', content: text })
+    }
+    for (const result of toolResults) {
+      wire.push({
+        role: 'tool',
+        tool_call_id: result.toolCallId,
+        // Empty tool output still needs SOME content on the wire.
+        content: flattenText(result.content) || '(no output)',
+      })
+    }
+  }
+  return wire
+}
+
+/** Assemble request fields shared by every conversion. */
+function requestWithMessages(
+  options: GenerateOptions,
+  messages: WireMessage[],
+  defaults: RequestDefaults,
+): WireRequest {
+  const tools: WireTool[] | undefined = options.tools?.map(tool => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    },
+  }))
+  const resolvedThinking = resolveThinking(options, defaults)
+  return {
+    model: options.model,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+    ...resolvedThinking.reasoningEffort !== undefined
+      ? { reasoning_effort: resolvedThinking.reasoningEffort }
+      : {},
+    ...tools !== undefined && tools.length > 0 ? { tools } : {},
+    ...options.temperature !== undefined ? { temperature: options.temperature } : {},
+    ...options.maxTokens === undefined ? {} : { max_tokens: options.maxTokens },
+    ...options.stop !== undefined ? { stop: options.stop } : {},
+  }
+}
+
+/**
+ * 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 function serializeRequest(
+  options: GenerateOptions,
+  defaults: RequestDefaults = {},
+): WireRequest {
+  const messages: WireMessage[] = []
+  if (options.system !== undefined) {
+    messages.push({ role: 'system', content: options.system })
+  }
+  messages.push(...serializeMessages(options.model, options.messages))
+
+  return requestWithMessages(options, messages, defaults)
+}

package/src/sse.ts

@@ -0,0 +1,40 @@
+/**
+ * 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
+ */
+
+import { EventSourceParserStream } from 'eventsource-parser/stream'
+import { LlmError } from '@deepseek-ai/dsh-llm'
+
+/** The terminal payload OpenAI-compatible endpoints send after the last chunk. */
+export 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 async function* parseSse(
+  stream: ReadableStream<BufferSource>,
+  onComment?: (comment: string) => void,
+): AsyncGenerator<string> {
+  const events = stream
+    .pipeThrough(new TextDecoderStream())
+    .pipeThrough(new EventSourceParserStream({ onComment }))
+  for await (const { data } of events) {
+    yield data
+    if (data === DONE) return
+  }
+  throw new LlmError('SSE stream ended without [DONE]', 'STREAM_CLOSED')
+}

package/src/translate.ts

@@ -0,0 +1,182 @@
+/**
+ * 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 { ToolCallId, EMPTY_RESPONSE_CODE, LlmError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
+import { DONE } from './sse.ts'
+import type { WireChunk, WireUsage } from './types.ts'
+
+/** One open block under assembly. */
+interface OpenBlock {
+  index: number
+  kind: 'text' | 'reasoning' | 'tool-call'
+  text: string
+  /** tool-call only */
+  callId?: string
+  name?: string
+}
+
+/**
+ * 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 function mapFinishReason(reason: string): FinishReason {
+  switch (reason) {
+    case 'stop': return { kind: 'stop' }
+    case 'tool_calls': return { kind: 'tool-calls' }
+    case 'length': return { kind: 'max-tokens' }
+    default:
+      // content_filter, insufficient_system_resource, future additions.
+      return {
+        kind: 'error',
+        failure: { message: `model stopped: ${reason}`, code: reason.toUpperCase() },
+      }
+  }
+}
+
+/**
+ * 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 function mapUsage(usage: WireUsage): TokenUsage {
+  const cacheRead = usage.prompt_tokens_details?.cached_tokens
+  const reasoning = usage.completion_tokens_details?.reasoning_tokens
+  return {
+    inputTokens: usage.prompt_tokens - (cacheRead ?? 0),
+    outputTokens: usage.completion_tokens,
+    ...cacheRead !== undefined ? { cacheReadTokens: cacheRead } : {},
+    ...reasoning !== undefined ? { reasoningTokens: reasoning } : {},
+  }
+}
+
+/** Assemble the final ContentBlock for one open block. */
+function closeBlock(block: OpenBlock): ContentBlock {
+  switch (block.kind) {
+    case 'text': return { type: 'text', text: block.text }
+    case 'reasoning': return { type: 'reasoning', text: block.text }
+    case 'tool-call': return {
+      type: 'tool-call',
+      id: ToolCallId(block.callId ?? ''),
+      name: block.name ?? '',
+      arguments: block.text,
+    }
+  }
+}
+
+/**
+ * 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 async function* translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk> {
+  let nextIndex = 0
+  let textBlock: OpenBlock | undefined
+  let reasoningBlock: OpenBlock | undefined
+  const toolBlocks = new Map<number, OpenBlock>()
+  const order: OpenBlock[] = []
+  let pendingFinish: FinishReason | undefined
+  let pendingUsage: TokenUsage | undefined
+
+  function open(kind: OpenBlock['kind']): OpenBlock {
+    const block: OpenBlock = { index: nextIndex++, kind, text: '' }
+    order.push(block)
+    return block
+  }
+
+  for await (const payload of payloads) {
+    if (payload === DONE) {
+      for (const block of order) {
+        yield { type: 'block-end', index: block.index, block: closeBlock(block) }
+      }
+      if (pendingUsage) yield { type: 'usage', usage: pendingUsage }
+      const reason = pendingFinish ?? { kind: 'stop' as const }
+      yield {
+        type: 'finish',
+        reason: reason.kind === 'stop' && order.length === 0
+          ? {
+            kind: 'error',
+            failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE },
+          }
+          : reason,
+      }
+      return
+    }
+
+    let chunk: WireChunk
+    try {
+      chunk = JSON.parse(payload) as WireChunk
+    } catch {
+      throw new LlmError(`malformed SSE payload: ${payload.slice(0, 120)}`, 'MALFORMED_RESPONSE')
+    }
+
+    for (const choice of chunk.choices ?? []) {
+      const delta = choice.delta
+
+      // Reasoning first: thinking mode interleaves it before text. The
+      // empty-string first chunk must not open a block.
+      const reasoning = delta?.reasoning
+      if (typeof reasoning === 'string' && reasoning.length > 0) {
+        if (!reasoningBlock) {
+          reasoningBlock = open('reasoning')
+          yield { type: 'block-start', index: reasoningBlock.index, blockType: 'reasoning' }
+        }
+        reasoningBlock.text += reasoning
+        yield { type: 'reasoning-delta', index: reasoningBlock.index, text: reasoning }
+      }
+
+      const content = delta?.content
+      if (typeof content === 'string' && content.length > 0) {
+        if (!textBlock) {
+          textBlock = open('text')
+          yield { type: 'block-start', index: textBlock.index, blockType: 'text' }
+        }
+        textBlock.text += content
+        yield { type: 'text-delta', index: textBlock.index, text: content }
+      }
+
+      for (const call of delta?.tool_calls ?? []) {
+        let block = toolBlocks.get(call.index)
+        if (!block) {
+          block = open('tool-call')
+          toolBlocks.set(call.index, block)
+          yield { type: 'block-start', index: block.index, blockType: 'tool-call' }
+        }
+        if (call.id !== undefined) block.callId = call.id
+        if (call.function?.name !== undefined) block.name = call.function.name
+        const fragment = call.function?.arguments ?? ''
+        block.text += fragment
+        yield {
+          type: 'tool-call-delta',
+          index: block.index,
+          id: ToolCallId(block.callId ?? ''),
+          ...block.name !== undefined ? { name: block.name } : {},
+          argumentsDelta: fragment,
+        }
+      }
+
+      if (typeof choice.finish_reason === 'string') {
+        pendingFinish = mapFinishReason(choice.finish_reason)
+      }
+    }
+
+    // Usage may arrive attached to the finish chunk or as a trailing
+    // usage-only chunk — keep the latest.
+    if (chunk.usage) pendingUsage = mapUsage(chunk.usage)
+  }
+
+  // parseSse guarantees the [DONE] sentinel (or throws); reaching here means
+  // the payload source violated that contract.
+  throw new LlmError('SSE payload stream ended without [DONE]', 'STREAM_CLOSED')
+}

package/src/types.ts

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