dsh-local-ai 0.1.0

package/src/adapter.ts

@@ -0,0 +1,158 @@
+/**
+ * `OllamaAdapter`: the harness `LlmAdapter` over Ollama's native `/api/chat`
+ * streaming endpoint. Transport-only: the registering plugin owns config
+ * resolution (one `() => ResolvedConfig` thunk re-read per operation), so a
+ * changed base URL, model mapping, or timeout reaches the next request without
+ * re-registration, while an in-flight stream keeps the facts it started with.
+ * The adapter is text-only (`inputModalities: ['text']`); tool calls and tool
+ * results are translated by {@link serializeRequest}.
+ * @module dsh-local-ai/adapter
+ */
+
+import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { sanitizeEndpoint } from './sanitize.ts'
+import { listModels as listOllamaModels, postStream, readNdjsonLines } from './ollama.ts'
+import type { FetchLike } from './ollama.ts'
+import { serializeRequest } from './serialize.ts'
+import { translate } from './translate.ts'
+import type { ResolvedConfig } from './config.ts'
+
+/** Idle-timeout abort code stamped onto a stalled stream's timeout reason. */
+const STREAM_IDLE_TIMEOUT_CODE = 'LLM_STREAM_IDLE_TIMEOUT'
+
+/** Constructor options for {@link OllamaAdapter}. */
+export interface OllamaAdapterOptions {
+  /** Current validated config; called once per operation. */
+  config: () => ResolvedConfig
+  /** Fetch implementation, injectable for tests; defaults to `globalThis.fetch`. */
+  fetchImpl?: FetchLike
+}
+
+/** The single provider route this adapter owns. */
+export const OLLAMA_PROVIDER = 'ollama'
+
+/** Reverse a model mapping: Ollama model id → harness-visible name. */
+function harnessNameOf(resolved: ResolvedConfig, ollamaName: string): string {
+  const mapping = resolved.models.find(entry => entry.model === ollamaName)
+  return mapping?.name ?? ollamaName
+}
+
+/** Advertise one configured or discovered local model as text-only. */
+function modelInfo(provider: string, id: string, name: string): LlmModelInfo {
+  return { provider, id, name, inputModalities: ['text'] }
+}
+
+/**
+ * The Ollama provider adapter. One instance serves every harness-visible local
+ * model name; the harness model name maps to the wire model id through the
+ * configured model mapping (identity when unmapped).
+ */
+export class OllamaAdapter extends LlmAdapter {
+  constructor(private readonly options: OllamaAdapterOptions) {
+    super()
+  }
+
+  private fetchImpl(): FetchLike {
+    return this.options.fetchImpl ?? ((input: string, init?: RequestInit) => globalThis.fetch(input, init))
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: 'Ollama (local)' }
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    const resolved = this.options.config()
+    return listOllamaModels(resolved.baseURL, this.fetchImpl())
+      .then(models => models.map(model => modelInfo(provider, harnessNameOf(resolved, model.name), harnessNameOf(resolved, model.name))))
+      .catch(() => resolved.models.map(entry => modelInfo(provider, entry.name, entry.name)))
+  }
+
+  override resolveModel(
+    provider: string,
+    model: string,
+    _signal?: AbortSignal,
+  ): Promise<LlmResolvedModelInfo> {
+    const resolved = this.options.config()
+    const mapping = resolved.models.find(entry => entry.name === model)
+    return Promise.resolve({
+      provider,
+      id: model,
+      name: model,
+      inputModalities: ['text'],
+      context: { contextWindow: mapping?.contextWindow ?? resolved.defaultContextWindow },
+      defaultMaxTokens: mapping?.maxTokens ?? resolved.maxTokens,
+    })
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // One resolution per stream call: connection facts freeze here and hold for
+    // this whole request, so an in-flight stream never observes a config change
+    // and the next call re-resolves.
+    const resolved = this.options.config()
+    const consumer = new AbortController()
+    const upstream = options.signal === undefined
+      ? consumer.signal
+      : AbortSignal.any([options.signal, consumer.signal])
+    using watchdog = idleWatchdog(upstream, resolved.requestTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
+    const iterator = this.request(options, resolved, watchdog.signal)[Symbol.asyncIterator]()
+    let exhausted = false
+    try {
+      while (true) {
+        const result = await watchdog.next(iterator)
+        if (result.done) {
+          exhausted = true
+          return
+        }
+        yield result.value
+      }
+    } catch (error: unknown) {
+      if (timeoutOf(watchdog.signal, STREAM_IDLE_TIMEOUT_CODE) !== undefined) {
+        throw new LlmError(
+          `Ollama stream idle timeout after ${resolved.requestTimeoutMs}ms`,
+          'TIMEOUT',
+          { cause: error },
+        )
+      }
+      if (options.signal?.aborted) {
+        throw new LlmError('Ollama request aborted by caller', 'ABORTED', { cause: error })
+      }
+      if (error instanceof LlmError) throw error
+      throw new LlmError(`Ollama API stream from ${sanitizeEndpoint(resolved.baseURL)} failed`, 'TRANSPORT', { cause: error })
+    } finally {
+      consumer.abort('Ollama stream consumer stopped')
+      if (!exhausted && iterator.return !== undefined) {
+        try {
+          await iterator.return()
+        } catch (_abortedTransportTeardown) {
+          // The consumer controller already owns termination; a return-time abort cannot add a second outcome.
+        }
+      }
+    }
+  }
+
+  private async * request(
+    options: GenerateOptions,
+    resolved: ResolvedConfig,
+    signal: AbortSignal,
+  ): AsyncIterable<StreamChunk> {
+    const body = serializeRequest(options, resolved)
+    let response: Response
+    try {
+      response = await postStream(resolved.baseURL, '/api/chat', body, this.fetchImpl(), signal)
+    } catch (error: unknown) {
+      // The outer stream distinguishes caller cancellation and watchdog expiry.
+      if (signal.aborted) throw error
+      throw new LlmError(
+        `Ollama API request to ${sanitizeEndpoint(resolved.baseURL)} failed`,
+        'TRANSPORT',
+        { cause: error },
+      )
+    }
+    if (!response.body) {
+      throw new LlmError('Ollama API returned no response body', 'EMPTY_RESPONSE')
+    }
+    yield* translate(readNdjsonLines(response.body))
+  }
+}

package/src/config.ts

@@ -0,0 +1,243 @@
+/**
+ * Config schema and resolution for `dsh-local-ai`. Every tunable is a
+ * validated {@link Config} field changeable from cordis.yml; the resolution
+ * step validates URLs, numeric bounds, and route/model entries so
+ * misconfiguration fails loud at mount — never silently skips a rule or
+ * half-configures the adapter. The plugin is inert until at least one route
+ * rule exists or a caller selects the `ollama` provider explicitly: routing
+ * every request to a local model requires an explicit opt-in (privacy and
+ * cost default: no automatic re-routing).
+ * @module dsh-local-ai/config
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+/** One harness-visible model mapping onto an Ollama model id. */
+export interface ModelMapping {
+  /** Harness-visible model name (what `GenerateOptions.model` uses). */
+  name: string
+  /** Ollama model id; defaults to {@link name}. */
+  model?: string
+  /** Combined request/response context capacity in tokens. */
+  contextWindow?: number
+  /** Per-request output cap in tokens. */
+  maxTokens?: number
+  /** Default sampling temperature for this model (0..2). */
+  temperature?: number
+}
+
+/** One local-model routing rule, matched in list order (first match wins). */
+export interface RouteRule {
+  /** Target harness-visible model name, resolved through the model mapping. */
+  model: string
+  /** Route when the request purpose matches this task type. */
+  purpose?: 'compaction' | 'session-title'
+  /** Route when any keyword appears (case-insensitive) in the request text. */
+  keywords?: string[]
+  /** Route every eligible request to this local model (offline-first). */
+  always?: boolean
+}
+
+/** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
+export interface Config {
+  /** Ollama HTTP API base URL; `/api/*` paths are appended. */
+  baseURL?: string
+  /** Per-request HTTP timeout in milliseconds. */
+  requestTimeoutMs?: number
+  /** Subprocess terminate grace in milliseconds (health-check CLI). */
+  graceMs?: number
+  /** Context capacity used when a model has no exact value. */
+  defaultContextWindow?: number
+  /** Per-request output cap used when a model has no exact value. */
+  maxTokens?: number
+  /** Default sampling temperature; omitted leaves the provider default. */
+  temperature?: number
+  /** Harness-visible → Ollama model mappings. */
+  models?: ModelMapping[]
+  /** Local-model routing rules (offline-first / long-text / privacy tasks). */
+  route?: RouteRule[]
+}
+
+/** Fully resolved model mapping. */
+export interface ResolvedModelMapping {
+  readonly name: string
+  readonly model: string
+  readonly contextWindow?: number
+  readonly maxTokens?: number
+  readonly temperature?: number
+}
+
+/** Fully resolved routing rule. */
+export interface ResolvedRouteRule {
+  readonly model: string
+  readonly purpose?: 'compaction' | 'session-title'
+  readonly keywords: readonly string[]
+  readonly always: boolean
+}
+
+/** The complete resolved config handed to the runtime. */
+export interface ResolvedConfig {
+  readonly baseURL: string
+  readonly requestTimeoutMs: number
+  readonly graceMs: number
+  readonly defaultContextWindow: number
+  readonly maxTokens: number
+  readonly temperature?: number
+  readonly models: readonly ResolvedModelMapping[]
+  readonly route: readonly ResolvedRouteRule[]
+}
+
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export const Config: z<Config> = z.object({
+  baseURL: z.string().default('http://127.0.0.1:11434'),
+  requestTimeoutMs: z.number().default(30_000),
+  graceMs: z.number().default(15_000),
+  defaultContextWindow: z.number().default(8192),
+  maxTokens: z.number().default(4096),
+  temperature: z.number(),
+  models: z.array(z.object({
+    name: z.string().required(),
+    model: z.string(),
+    contextWindow: z.number(),
+    maxTokens: z.number(),
+    temperature: z.number(),
+  })).default([]),
+  route: z.array(z.object({
+    model: z.string().required(),
+    purpose: z.union(['compaction', 'session-title'] as const),
+    keywords: z.array(z.string()).default([]),
+    always: z.boolean().default(false),
+  })).default([]),
+})
+
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name: string, value: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`)
+  }
+}
+
+/** Throw unless `value` is a finite number in `[min, max]`. */
+function assertFiniteRange(name: string, value: number, min: number, max: number): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`)
+  }
+}
+
+/**
+ * Validate an http(s) URL string and normalize it to a clean base (no query,
+ * no fragment, no trailing slash).
+ * @param name - config key, for the error message.
+ * @param value - raw URL value.
+ * @returns the normalized base URL.
+ */
+export function normalizeBaseUrl(name: string, value: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(value)
+  } catch (error) {
+    throw new TypeError(`${name} must be a valid URL, got ${JSON.stringify(value)} (${error instanceof Error ? error.message : 'invalid URL'})`)
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new TypeError(`${name} must use http(s), got ${JSON.stringify(parsed.protocol)}`)
+  }
+  parsed.search = ''
+  parsed.hash = ''
+  return parsed.href.replace(/\/+$/u, '')
+}
+
+/**
+ * Validate raw values and fill explicit defaults. Invalid URLs, numeric
+ * bounds, duplicate model names, or empty route/model names throw here —
+ * misconfiguration fails loud at mount even when the plugin is mounted
+ * without the Schemastery loader.
+ * @param config - raw (possibly partial) plugin config.
+ * @returns the fully resolved config.
+ */
+export function resolveConfig(config: Config = {}): ResolvedConfig {
+  const baseURL = normalizeBaseUrl('baseURL', config.baseURL ?? 'http://127.0.0.1:11434')
+
+  const requestTimeoutMs = config.requestTimeoutMs ?? 30_000
+  assertPositiveInt('requestTimeoutMs', requestTimeoutMs)
+
+  const graceMs = config.graceMs ?? 15_000
+  assertPositiveInt('graceMs', graceMs)
+
+  const defaultContextWindow = config.defaultContextWindow ?? 8192
+  assertPositiveInt('defaultContextWindow', defaultContextWindow)
+
+  const maxTokens = config.maxTokens ?? 4096
+  assertPositiveInt('maxTokens', maxTokens)
+
+  const temperature = config.temperature
+  if (temperature !== undefined) assertFiniteRange('temperature', temperature, 0, 2)
+
+  const seenNames = new Set<string>()
+  const models = (config.models ?? []).map((mapping, index) => {
+    if (typeof mapping.name !== 'string' || mapping.name.trim().length === 0) {
+      throw new TypeError(`models[${index}].name must be a non-empty string`)
+    }
+    const name = mapping.name.trim()
+    if (seenNames.has(name)) throw new TypeError(`models[${index}]: duplicate model name ${JSON.stringify(name)}`)
+    seenNames.add(name)
+    const model = (mapping.model ?? name).trim()
+    if (model.length === 0) throw new TypeError(`models[${index}].model must be a non-empty string`)
+    const contextWindow = mapping.contextWindow
+    if (contextWindow !== undefined) assertPositiveInt(`models[${index}].contextWindow`, contextWindow)
+    const modelMaxTokens = mapping.maxTokens
+    if (modelMaxTokens !== undefined) assertPositiveInt(`models[${index}].maxTokens`, modelMaxTokens)
+    const modelTemperature = mapping.temperature
+    if (modelTemperature !== undefined) assertFiniteRange(`models[${index}].temperature`, modelTemperature, 0, 2)
+    return {
+      name,
+      model,
+      ...contextWindow === undefined ? {} : { contextWindow },
+      ...modelMaxTokens === undefined ? {} : { maxTokens: modelMaxTokens },
+      ...modelTemperature === undefined ? {} : { temperature: modelTemperature },
+    }
+  })
+
+  const route = (config.route ?? []).map((rule, index) => {
+    if (typeof rule.model !== 'string' || rule.model.trim().length === 0) {
+      throw new TypeError(`route[${index}].model must be a non-empty string`)
+    }
+    const keywords = (rule.keywords ?? []).map((keyword, keywordIndex) => {
+      if (typeof keyword !== 'string' || keyword.trim().length === 0) {
+        throw new TypeError(`route[${index}].keywords[${keywordIndex}] must be a non-empty string`)
+      }
+      return keyword
+    })
+    if (rule.always !== true && rule.purpose === undefined && keywords.length === 0) {
+      throw new TypeError(`route[${index}] must declare a purpose, at least one keyword, or always: true`)
+    }
+    return {
+      model: rule.model.trim(),
+      ...rule.purpose === undefined ? {} : { purpose: rule.purpose },
+      keywords,
+      always: rule.always ?? false,
+    }
+  })
+
+  return {
+    baseURL,
+    requestTimeoutMs,
+    graceMs,
+    defaultContextWindow,
+    maxTokens,
+    ...temperature === undefined ? {} : { temperature },
+    models,
+    route,
+  }
+}
+
+/**
+ * Resolve one harness-visible model name to its Ollama model id, or return
+ * `undefined` when no mapping matches (the identity mapping applies).
+ * @param resolved - resolved config.
+ * @param name - harness-visible model name.
+ * @returns the mapped Ollama model id, or `undefined` when unmapped.
+ */
+export function ollamaModelOf(resolved: ResolvedConfig, name: string): string | undefined {
+  const mapping = resolved.models.find(entry => entry.name === name)
+  return mapping?.model
+}

package/src/health.ts

@@ -0,0 +1,133 @@
+/**
+ * Health checks for the local Ollama server: API responsiveness over HTTP and
+ * process liveness through the real subprocess seam (the `ollama` CLI's own
+ * channel). Both signals are independent — a server that answers HTTP but has
+ * no reachable CLI, or vice versa, is reported as two facts, never conflated.
+ * @module dsh-local-ai/health
+ */
+
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess'
+import { apiVersion } from './ollama.ts'
+import type { FetchLike } from './ollama.ts'
+import { sanitizeText } from './sanitize.ts'
+import { tmpdir } from 'node:os'
+
+/** The HTTP responsiveness result. */
+export interface ApiHealth {
+  readonly ok: boolean
+  readonly version?: string
+  readonly error?: string
+}
+
+/** The process liveness result. */
+export interface ProcessHealth {
+  readonly present: boolean
+  readonly error?: string
+}
+
+/** The combined health result. */
+export interface HealthResult {
+  readonly api: ApiHealth
+  readonly process: ProcessHealth
+}
+
+/** The subprocess probe used to test process liveness. */
+export interface ProcessProbe {
+  readonly command: string
+  readonly args: readonly string[]
+}
+
+/** The default probe: `ollama list` reaches the server through the CLI's own channel. */
+export const OLLAMA_PROCESS_PROBE: ProcessProbe = { command: 'ollama', args: ['list'] }
+
+/**
+ * Check whether the Ollama HTTP API responds to `/api/version` within a
+ * deadline. A timeout, transport failure, or non-2xx response is `ok: false`
+ * with a sanitized error.
+ * @param baseURL - the Ollama base URL.
+ * @param fetchImpl - the fetch implementation.
+ * @param timeoutMs - deadline in milliseconds.
+ * @returns the API health result.
+ */
+export async function checkApiHealth(
+  baseURL: string,
+  fetchImpl: FetchLike,
+  timeoutMs: number,
+): Promise<ApiHealth> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs)
+  try {
+    const version = await apiVersion(baseURL, fetchImpl, controller.signal)
+    return { ok: true, version: sanitizeText(version, 64) }
+  } catch (error: unknown) {
+    return { ok: false, error: sanitizeText(error instanceof Error ? error.message : String(error), 500) }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Check process liveness through the subprocess seam by spawning the probe
+ * command in collect mode. Exit code 0 means the CLI (and, for the default
+ * `ollama list` probe, the server it talks to) is alive; a missing executable
+ * or non-zero exit is `present: false` with a sanitized error.
+ * @param subprocess - the real subprocess runtime.
+ * @param graceMs - terminate grace for the spawned probe.
+ * @param probe - the command to probe with (defaults to `ollama list`).
+ * @returns the process health result.
+ */
+export async function checkProcessHealth(
+  subprocess: SubprocessRuntime,
+  graceMs: number,
+  probe: ProcessProbe = OLLAMA_PROCESS_PROBE,
+): Promise<ProcessHealth> {
+  let executable: string
+  try {
+    executable = await subprocess.resolveExecutable(probe.command)
+  } catch (error: unknown) {
+    return {
+      present: false,
+      error: sanitizeText(`"${probe.command}" not found: ${error instanceof Error ? error.message : String(error)}`, 500),
+    }
+  }
+  const handle = subprocess.spawn({
+    argv: [executable, ...probe.args],
+    cwd: tmpdir(),
+    stdio: {
+      stdin: 'ignore',
+      stdout: { maxBytes: 4096 },
+      stderr: { maxBytes: 4096 },
+    },
+    graceMs,
+  })
+  const outcome = await handle.done
+  if (outcome.exitCode === 0) return { present: true }
+  const stderr = handle.collected.stderr?.readFrom(0).text ?? ''
+  return {
+    present: false,
+    error: sanitizeText(stderr.trim().length > 0 ? stderr : `exit code ${String(outcome.exitCode)}`, 500),
+  }
+}
+
+/**
+ * Check both health signals.
+ * @param baseURL - the Ollama base URL.
+ * @param fetchImpl - the fetch implementation.
+ * @param subprocess - the real subprocess runtime.
+ * @param requestTimeoutMs - HTTP deadline in milliseconds.
+ * @param graceMs - subprocess terminate grace in milliseconds.
+ * @returns the combined health result.
+ */
+export async function checkHealth(
+  baseURL: string,
+  fetchImpl: FetchLike,
+  subprocess: SubprocessRuntime,
+  requestTimeoutMs: number,
+  graceMs: number,
+): Promise<HealthResult> {
+  const [api, process] = await Promise.all([
+    checkApiHealth(baseURL, fetchImpl, requestTimeoutMs),
+    checkProcessHealth(subprocess, graceMs),
+  ])
+  return { api, process }
+}