dsh-local-ai 0.1.0

package/src/sanitize.ts

@@ -0,0 +1,114 @@
+/**
+ * Display/log sanitization for `dsh-local-ai`. Every value shown to the model
+ * or to the user (tool results, the `/ollama` command, error messages) passes
+ * through one of these pure functions first, so an endpoint address or a local
+ * path can never leak credentials, secret query parameters, or unbounded text.
+ *
+ * All functions are pure: they depend only on their arguments, never on
+ * process state (the caller supplies a home directory for path redaction).
+ * @module dsh-local-ai/sanitize
+ */
+
+/** Placeholder substituted for a redacted secret or credential. */
+export const REDACTED = '[REDACTED]'
+
+/** Control characters (C0 + DEL) stripped from every sanitized value. */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/gu
+
+/** Secret-shaped query-parameter keys removed from endpoint URLs. */
+const SECRET_KEY_PATTERN = /key|token|secret|password|credential|auth/iu
+
+/** Built-in secret literal patterns redacted from arbitrary text. */
+const BUILTIN_SECRET_PATTERNS = [
+  /\bsk-[A-Za-z0-9]{16,}\b/u,
+  /\bghp_[A-Za-z0-9]{20,}\b/u,
+  /\bgho_[A-Za-z0-9]{20,}\b/u,
+  /\bAKIA[0-9A-Z]{16}\b/u,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/u,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[A-Za-z0-9+/=\s]*-----END [A-Z ]*PRIVATE KEY-----/u,
+] as const
+
+/** Remove C0/DEL control characters from a string. */
+export function stripControl(value: string): string {
+  return value.replace(CONTROL_CHARS, '')
+}
+
+/**
+ * Truncate a string to `maxChars`, appending an ellipsis when it was cut.
+ * A non-positive `maxChars` yields the empty string.
+ * @param value - the string to bound.
+ * @param maxChars - maximum returned length, including the ellipsis.
+ * @returns the bounded string.
+ */
+export function truncate(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value
+  if (maxChars <= 1) return maxChars <= 0 ? '' : '…'
+  return `${value.slice(0, maxChars - 1)}…`
+}
+
+/**
+ * Sanitize an endpoint address for display: strip the URL userinfo
+ * (`user:pass@`), drop query parameters whose key looks like a secret, strip
+ * control characters, and bound the length. Values that are not parseable as
+ * a URL are still stripped and truncated.
+ * @param value - the raw endpoint (URL string or anything stringifiable).
+ * @param maxChars - maximum returned length.
+ * @returns the sanitized endpoint text.
+ */
+export function sanitizeEndpoint(value: unknown, maxChars = 2048): string {
+  const text = stripControl(typeof value === 'string' ? value : String(value))
+  let out: string
+  try {
+    const url = new URL(text)
+    url.username = ''
+    url.password = ''
+    for (const key of [...url.searchParams.keys()]) {
+      if (SECRET_KEY_PATTERN.test(key)) url.searchParams.delete(key)
+    }
+    out = url.href
+  } catch {
+    out = text
+  }
+  return truncate(out, maxChars)
+}
+
+/**
+ * Sanitize a local path for display: strip control characters, redact a
+ * leading home directory to `~`, and bound the length.
+ * @param value - the raw path (string or anything stringifiable).
+ * @param home - the user's home directory to redact; omit to skip redaction.
+ * @param maxChars - maximum returned length.
+ * @returns the sanitized path text.
+ */
+export function sanitizePath(value: unknown, home = '', maxChars = 1024): string {
+  const text = stripControl(typeof value === 'string' ? value : String(value))
+  const redacted = home.length > 0 && text.startsWith(home)
+    ? `~${text.slice(home.length)}`
+    : text
+  return truncate(redacted, maxChars)
+}
+
+/**
+ * Redact built-in secret literals (API keys, GitHub tokens, AWS keys, bearer
+ * credentials, PEM private keys) from arbitrary text. Control characters are
+ * stripped first.
+ * @param value - the raw text (string or anything stringifiable).
+ * @returns the text with secret literals replaced by {@link REDACTED}.
+ */
+export function redactSecrets(value: unknown): string {
+  const text = stripControl(typeof value === 'string' ? value : String(value))
+  let out = text
+  for (const pattern of BUILTIN_SECRET_PATTERNS) out = out.replace(pattern, REDACTED)
+  return out
+}
+
+/**
+ * Sanitize arbitrary display text: redact secrets, strip control characters,
+ * and bound the length.
+ * @param value - the raw text (string or anything stringifiable).
+ * @param maxChars - maximum returned length.
+ * @returns the sanitized text.
+ */
+export function sanitizeText(value: unknown, maxChars = 4000): string {
+  return truncate(redactSecrets(value), maxChars)
+}

package/src/serialize.ts

@@ -0,0 +1,178 @@
+/**
+ * Serialize harness messages and requests into the Ollama `/api/chat` wire
+ * vocabulary. User text is joined; assistant text becomes `content` and tool
+ * calls become `tool_calls` (with arguments parsed from the raw JSON string to
+ * the object Ollama expects); tool results become separate `tool` messages.
+ * Core image blocks are rejected explicitly because this route is text-only;
+ * unknown declaration-merged block types retain the documented extension
+ * fallback (ignored for content, retained as text where text is expected).
+ * @module dsh-local-ai/serialize
+ */
+
+import { contentHasImage, LlmError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, Message, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { ResolvedConfig } from './config.ts'
+
+/** One Ollama chat message on the wire. */
+export interface OllamaWireMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string
+  tool_calls?: Array<{ function: { name: string; arguments: Record<string, unknown> } }>
+  tool_name?: string
+}
+
+/** The Ollama `/api/chat` request body. */
+export interface OllamaWireRequest {
+  model: string
+  messages: OllamaWireMessage[]
+  stream: boolean
+  options?: Record<string, unknown>
+  tools?: Array<{ type: 'function'; function: ToolSchema }>
+}
+
+/** Join the text blocks of a message (used for user/tool-result content). */
+function flattenText(blocks: readonly 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 adapter does not support image content.', 'UNSUPPORTED_CONTENT')
+  }
+}
+
+/**
+ * Parse a tool-call argument string into the object Ollama expects. The raw
+ * string is guaranteed by the harness contract to be JSON; a malformed value
+ * from a hand-built call degrades to a single `value` field rather than
+ * bricking the whole session.
+ * @param raw - the raw JSON string produced by the model.
+ * @returns the parsed object, or a `{ value }` fallback.
+ */
+export function parseToolArguments(raw: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+    return { value: raw }
+  } catch {
+    return { value: raw }
+  }
+}
+
+/** Serialize one assistant message (text + tool calls). */
+function serializeAssistant(message: Message): OllamaWireMessage {
+  const text = flattenText(message.content)
+  const toolCalls = message.content
+    .filter(block => block.type === 'tool-call')
+    .map(block => ({
+      function: { name: block.name, arguments: parseToolArguments(block.arguments) },
+    }))
+
+  return {
+    role: 'assistant',
+    content: text,
+    ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {},
+  }
+}
+
+/** Resolve a tool-result block's name from the assistant tool calls that precede it. */
+function toolNameOf(callId: string, namesByCallId: ReadonlyMap<string, string>): string | undefined {
+  return namesByCallId.get(callId)
+}
+
+/**
+ * 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. Assistant tool calls are
+ * indexed first so their results can carry the tool name Ollama needs.
+ * @param messages - the harness conversation, in order.
+ * @returns the wire messages; order preserved, each tool result expanded into its own entry.
+ */
+export function serializeMessages(messages: Message[]): OllamaWireMessage[] {
+  const namesByCallId = new Map<string, string>()
+  for (const message of messages) {
+    if (message.role !== 'assistant') continue
+    for (const block of message.content) {
+      if (block.type === 'tool-call') namesByCallId.set(String(block.id), block.name)
+    }
+  }
+
+  const wire: OllamaWireMessage[] = []
+  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))
+      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) {
+      const name = toolNameOf(String(result.toolCallId), namesByCallId)
+      wire.push({
+        role: 'tool',
+        // Empty tool output still needs SOME content on the wire.
+        content: flattenText(result.content) || '(no output)',
+        ...name === undefined ? {} : { tool_name: name },
+      })
+    }
+  }
+  return wire
+}
+
+/**
+ * Build the full wire request. Always streaming (`stream: true`); optional
+ * fields are omitted rather than sent as null, so Ollama defaults apply.
+ * `temperature` resolves request → model mapping → plugin default; `num_predict`
+ * is the harness-materialized `maxTokens`.
+ * @param options - the harness request (model, history, system, tools, sampling).
+ * @param resolved - the resolved plugin config.
+ * @returns the `/api/chat` request body.
+ */
+export function serializeRequest(
+  options: GenerateOptions,
+  resolved: ResolvedConfig,
+): OllamaWireRequest {
+  const mapping = resolved.models.find(entry => entry.name === options.model)
+  const model = mapping?.model ?? options.model
+
+  const messages: OllamaWireMessage[] = []
+  if (options.system !== undefined) {
+    messages.push({ role: 'system', content: options.system })
+  }
+  messages.push(...serializeMessages(options.messages))
+
+  const temperature = options.temperature ?? mapping?.temperature ?? resolved.temperature
+  const ollamaOptions: Record<string, unknown> = {}
+  if (temperature !== undefined) ollamaOptions.temperature = temperature
+  if (options.maxTokens !== undefined) ollamaOptions.num_predict = options.maxTokens
+  if (options.stop !== undefined && options.stop.length > 0) ollamaOptions.stop = options.stop
+
+  const tools = options.tools?.map(tool => ({
+    type: 'function' as const,
+    function: tool,
+  }))
+
+  return {
+    model,
+    messages,
+    stream: true,
+    ...Object.keys(ollamaOptions).length > 0 ? { options: ollamaOptions } : {},
+    ...tools !== undefined && tools.length > 0 ? { tools } : {},
+  }
+}

package/src/translate.ts

@@ -0,0 +1,205 @@
+/**
+ * Translate Ollama NDJSON chat chunks into the harness `StreamChunk` protocol.
+ * Ollama streams one JSON object per line: `message.content` and
+ * `message.thinking` are incremental deltas, while `message.tool_calls`
+ * carries the CUMULATIVE arguments object, so tool-call deltas are computed by
+ * longest-common-prefix diffing. Usage and the finish reason are deferred to
+ * the `done: true` chunk, guaranteeing no chunk follows `finish`.
+ * @module dsh-local-ai/translate
+ */
+
+import { CallId, EMPTY_RESPONSE_CODE, LlmError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
+
+/** One Ollama streaming chat chunk on the wire. */
+export interface OllamaWireChunk {
+  model?: string
+  message?: {
+    role?: string
+    content?: string
+    thinking?: string
+    tool_calls?: Array<{ function?: { name?: string; arguments?: Record<string, unknown> } }>
+  }
+  done?: boolean
+  done_reason?: string
+  prompt_eval_count?: number
+  eval_count?: number
+  error?: string
+}
+
+/** 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 Ollama `done_reason` vocabulary to the harness FinishReason.
+ * @param reason - the wire `done_reason` string.
+ * @returns the mapped reason; unrecognized values become `{kind: 'error'}`.
+ */
+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:
+      return {
+        kind: 'error',
+        failure: { message: `model stopped: ${reason}`, code: reason.toUpperCase() },
+      }
+  }
+}
+
+/** 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: CallId(block.callId ?? ''),
+      name: block.name ?? '',
+      arguments: block.text,
+    }
+  }
+}
+
+/**
+ * Compute the append delta from a cumulative JSON string, so the harness's
+ * delta-concatenating assembler reconstructs the full arguments. Ollama grows
+ * the arguments object monotonically, so the delta is everything past the
+ * longest common prefix with the previously seen string.
+ * @param previous - the previously seen cumulative JSON (or `''`).
+ * @param next - the new cumulative JSON.
+ * @returns the fragment to append.
+ */
+export function argumentsDelta(previous: string, next: string): string {
+  if (next.startsWith(previous)) return next.slice(previous.length)
+  let index = 0
+  while (index < previous.length && index < next.length && previous[index] === next[index]) index += 1
+  return next.slice(index)
+}
+
+/**
+ * Consume Ollama NDJSON lines and yield StreamChunks. Text and reasoning deltas
+ * stream as they arrive; tool-call deltas are diffed from the cumulative wire
+ * arguments; `block-end`, `usage`, and `finish` are deferred to the `done`
+ * chunk. A `stop` finish with no opened blocks maps to an `EMPTY_RESPONSE`
+ * error finish.
+ * @param lines - newline-delimited Ollama chat payloads.
+ * @returns deltas as they arrive; `block-end`s, `usage`, and `finish` deferred to `done`.
+ */
+export async function* translate(lines: AsyncIterable<string>): AsyncGenerator<StreamChunk> {
+  let nextIndex = 0
+  let textBlock: OpenBlock | undefined
+  let reasoningBlock: OpenBlock | undefined
+  const toolBlocks = new Map<number, OpenBlock>()
+  const toolArguments = new Map<number, string>()
+  const order: OpenBlock[] = []
+
+  function open(kind: OpenBlock['kind']): OpenBlock {
+    const block: OpenBlock = { index: nextIndex++, kind, text: '' }
+    order.push(block)
+    return block
+  }
+
+  for await (const line of lines) {
+    if (line.length === 0) continue
+
+    let chunk: OllamaWireChunk
+    try {
+      chunk = JSON.parse(line) as OllamaWireChunk
+    } catch {
+      throw new LlmError(`malformed Ollama NDJSON payload: ${line.slice(0, 120)}`, 'MALFORMED_RESPONSE')
+    }
+
+    if (typeof chunk.error === 'string' && chunk.error.length > 0) {
+      throw new LlmError(chunk.error, 'PROVIDER')
+    }
+
+    const message = chunk.message
+    if (message !== undefined) {
+      const reasoning = message.thinking
+      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 = message.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 }
+      }
+
+      const toolCalls = message.tool_calls ?? []
+      for (let callIndex = 0; callIndex < toolCalls.length; callIndex++) {
+        const call = toolCalls[callIndex]
+        let block = toolBlocks.get(callIndex)
+        if (!block) {
+          block = open('tool-call')
+          toolBlocks.set(callIndex, block)
+          toolArguments.set(callIndex, '')
+          yield { type: 'block-start', index: block.index, blockType: 'tool-call' }
+        }
+        if (call?.function?.name !== undefined && block.name === undefined) {
+          block.name = call.function.name
+        }
+        const cumulative = JSON.stringify(call?.function?.arguments ?? {})
+        const previous = toolArguments.get(callIndex) ?? ''
+        if (cumulative !== previous) {
+          const fragment = argumentsDelta(previous, cumulative)
+          toolArguments.set(callIndex, cumulative)
+          block.text += fragment
+          yield {
+            type: 'tool-call-delta',
+            index: block.index,
+            id: CallId(block.callId ?? ''),
+            ...block.name !== undefined ? { name: block.name } : {},
+            argumentsDelta: fragment,
+          }
+        }
+      }
+    }
+
+    if (chunk.done === true) {
+      for (const block of order) {
+        yield { type: 'block-end', index: block.index, block: closeBlock(block) }
+      }
+      const promptCount = chunk.prompt_eval_count
+      const evalCount = chunk.eval_count
+      if (promptCount !== undefined || evalCount !== undefined) {
+        const usage: TokenUsage = {
+          inputTokens: promptCount ?? 0,
+          outputTokens: evalCount ?? 0,
+        }
+        yield { type: 'usage', usage }
+      }
+      const reason = mapFinishReason(chunk.done_reason ?? 'stop')
+      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
+    }
+  }
+
+  throw new LlmError('Ollama NDJSON stream ended without a done chunk', 'STREAM_CLOSED')
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+/**
+ * The `dsh-local-ai` plugin version. The release script bumps this string
+ * alongside `package.json`; `test/version.spec.ts` trips when the two drift.
+ */
+export const VERSION = '0.1.0'