dsh-local-ai 0.1.0

package/src/index.ts

@@ -0,0 +1,279 @@
+/**
+ * `dsh-local-ai` — local-model (Ollama) integration for DeepSeek Harness.
+ * Registers the `ollama` `LlmAdapter` route, exposes discovery/management
+ * tools (`ollama_list`, `ollama_show`, `ollama_pull`, `ollama_remove`) plus a
+ * health check, routes requests to local models by task type or keyword with
+ * automatic fallback to the cloud, and provides the `/ollama` one-shot status
+ * command. Zero runtime dependencies beyond the harness peers: everything
+ * talks to Ollama over its HTTP API (or, for process liveness, the CLI).
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`, and a stray default would discard
+ * `name`/`inject`/`Config`/`apply`).
+ * @module dsh-local-ai
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { CommandResult } from '@deepseek-ai/dsh-commands'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { Config, resolveConfig } from './config.ts'
+import { OllamaAdapter, OLLAMA_PROVIDER } from './adapter.ts'
+import { decideRoute, routeLocal } from './route.ts'
+import { checkHealth } from './health.ts'
+import { contextLengthOf, listModels, listRunning, pullModel, removeModel, showModel } from './ollama.ts'
+import type { FetchLike } from './ollama.ts'
+
+export const name = 'local-ai'
+export const inject = ['llm', 'tools', 'subprocess', 'commands']
+
+export { Config, resolveConfig } from './config.ts'
+export type { Config as LocalAiConfig, ModelMapping, ResolvedConfig, ResolvedModelMapping, ResolvedRouteRule, RouteRule } from './config.ts'
+export { VERSION } from './version.ts'
+export { REDACTED, redactSecrets, sanitizeEndpoint, sanitizePath, sanitizeText, truncate } from './sanitize.ts'
+
+/** Format a byte count into a compact human-readable string. */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return '0 B'
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  let value = bytes
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  const rounded = unit === 0 ? String(Math.round(value)) : value.toFixed(1)
+  return `${rounded} ${units[unit]}`
+}
+
+/** One installed-model row reported by `ollama_list`. */
+interface ListedModel {
+  name: string
+  size: number
+  parameterSize?: string
+  quantization?: string
+  running: boolean
+}
+
+/** The `ollama_list` canonical value. */
+interface ListValue {
+  models: ListedModel[]
+  running: string[]
+  count: number
+  totalBytes: number
+}
+
+/** The `ollama_show` canonical value. */
+interface ShowValue {
+  name: string
+  parameterSize?: string
+  quantization?: string
+  contextLength?: number
+  family?: string
+  format?: string
+}
+
+/** Render the `ollama_list` canonical value as model-visible text. */
+export function renderList(value: JsonValue): string {
+  const list = value as unknown as ListValue
+  const models = list.models ?? []
+  const lines = [`${models.length} local model(s), ${formatBytes(list.totalBytes ?? 0)} on disk`]
+  for (const model of models) {
+    const detail = [model.parameterSize, model.quantization].filter(part => part !== undefined).join(' ')
+    lines.push(`- ${model.name}${detail.length > 0 ? ` (${detail})` : ''} — ${formatBytes(model.size)}${model.running ? ' [running]' : ''}`)
+  }
+  if (list.running !== undefined && list.running.length > 0) {
+    lines.push(`running: ${list.running.join(', ')}`)
+  }
+  return lines.join('\n')
+}
+
+/** Render the `ollama_show` canonical value as model-visible text. */
+export function renderShow(value: JsonValue): string {
+  const show = value as unknown as ShowValue
+  const detail = [show.parameterSize, show.quantization].filter(part => part !== undefined).join(' ')
+  const context = show.contextLength !== undefined ? `context ${show.contextLength}` : undefined
+  const parts = [detail, context, show.family, show.format].filter(part => part !== undefined && part.length > 0)
+  return `${show.name}${parts.length > 0 ? ` — ${parts.join(', ')}` : ''}`
+}
+
+/** Render a health canonical value as model-visible text. */
+export function renderHealth(value: JsonValue): string {
+  const health = value as unknown as {
+    api: { ok: boolean; version?: string }
+    process: { present: boolean; error?: string }
+  }
+  return [
+    `API: ${health.api.ok ? `ok${health.api.version !== undefined ? ` (v${health.api.version})` : ''}` : 'down'}`,
+    `process: ${health.process.present ? 'alive' : 'not detected'}`,
+  ].join('\n')
+}
+
+/** Render a pull/remove canonical value as model-visible text. */
+export function renderOperation(value: JsonValue): string {
+  const op = value as unknown as { name: string; status?: string; removed?: boolean }
+  if (op.removed === true) return `removed ${op.name}`
+  return `${op.name}: ${op.status ?? 'done'}`
+}
+
+/**
+ * Mount the plugin: resolve config (fail loud), register the Ollama adapter,
+ * the `llm/stream` routing waterfall, the five management tools, and the
+ * `/ollama` command. Every contribution goes through its registry's effect
+ * (register/on), so stop and hot-reload withdraw all of it.
+ * @param ctx - the plugin context (host).
+ * @param config - raw plugin config.
+ */
+export function apply(ctx: Context, config: Config = {}): void {
+  const resolved = resolveConfig(config)
+  const logger = ctx.logger('local-ai')
+  // Lazily-bound so tests can stub `globalThis.fetch` before a call.
+  const fetchImpl: FetchLike = (input, init) => globalThis.fetch(input, init)
+
+  const adapter = new OllamaAdapter({ config: () => resolved, fetchImpl })
+  ctx.llm.registerAdapter([OLLAMA_PROVIDER], adapter)
+
+  // Routing waterfall: passthrough by default; a matched rule re-routes to the
+  // local model and falls back to `next()` (the cloud) when local fails first.
+  ctx.on('llm/stream', (options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk> => {
+    const decision = decideRoute(options, resolved)
+    if (decision === undefined) return next()
+    return routeLocal((reRouted: GenerateOptions) => ctx.llm.stream(reRouted), options, decision, next)
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'ollama_list',
+    description: 'List local Ollama models with disk usage and which are currently loaded (running).',
+    parameters: {},
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: renderList(value) }],
+    },
+    async execute(_args, exec): Promise<JsonValue> {
+      const [models, running] = await Promise.all([
+        listModels(resolved.baseURL, fetchImpl, exec.signal),
+        listRunning(resolved.baseURL, fetchImpl, exec.signal).catch(() => []),
+      ])
+      const runningNames = new Set(running.map(model => model.name))
+      const value: ListValue = {
+        models: models.map(model => ({
+          name: model.name,
+          size: model.size,
+          ...model.details?.parameter_size === undefined ? {} : { parameterSize: model.details.parameter_size },
+          ...model.details?.quantization_level === undefined ? {} : { quantization: model.details.quantization_level },
+          running: runningNames.has(model.name),
+        })),
+        running: running.map(model => model.name),
+        count: models.length,
+        totalBytes: models.reduce((sum, model) => sum + model.size, 0),
+      }
+      return value as unknown as JsonValue
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'ollama_show',
+    description: 'Show details for one local Ollama model: parameter size, quantization, and context length.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'The Ollama model name to inspect.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: renderShow(value) }],
+    },
+    async execute(args, exec): Promise<JsonValue> {
+      const name = (args as { name: string }).name
+      const show = await showModel(resolved.baseURL, name, fetchImpl, exec.signal)
+      const value: ShowValue = {
+        name,
+        ...show.details?.parameter_size === undefined ? {} : { parameterSize: show.details.parameter_size },
+        ...show.details?.quantization_level === undefined ? {} : { quantization: show.details.quantization_level },
+        ...show.details?.family === undefined ? {} : { family: show.details.family },
+        ...show.details?.format === undefined ? {} : { format: show.details.format },
+        ...((): { contextLength?: number } => {
+          const contextLength = contextLengthOf(show)
+          return contextLength === undefined ? {} : { contextLength }
+        })(),
+      }
+      return value as unknown as JsonValue
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'ollama_pull',
+    description: 'Pull (download) a model into the local Ollama server.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'The Ollama model name to pull (e.g. llama3.2).' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: renderOperation(value) }],
+    },
+    async execute(args, exec): Promise<JsonValue> {
+      const name = (args as { name: string }).name
+      const result = await pullModel(resolved.baseURL, name, fetchImpl, exec.signal)
+      return { name, status: result.status } as unknown as JsonValue
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'ollama_remove',
+    description: 'Remove (delete) a model from the local Ollama server.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'The Ollama model name to remove.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: renderOperation(value) }],
+    },
+    async execute(args, exec): Promise<JsonValue> {
+      const name = (args as { name: string }).name
+      await removeModel(resolved.baseURL, name, fetchImpl, exec.signal)
+      return { name, removed: true } as unknown as JsonValue
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'ollama_health',
+    description: 'Check the local Ollama server: whether the process is alive and whether the API responds.',
+    parameters: {},
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: renderHealth(value) }],
+    },
+    async execute(_args, exec): Promise<JsonValue> {
+      const health = await checkHealth(resolved.baseURL, fetchImpl, ctx.subprocess, resolved.requestTimeoutMs, resolved.graceMs)
+      void exec
+      return health as unknown as JsonValue
+    },
+  }))
+
+  ctx.commands.register({
+    name: 'ollama',
+    description: 'One-shot status overview: local models, disk usage, health, and routing suggestions.',
+    async handler(): Promise<CommandResult> {
+      const health = await checkHealth(resolved.baseURL, fetchImpl, ctx.subprocess, resolved.requestTimeoutMs, resolved.graceMs)
+      const lines = ['Ollama status:']
+      lines.push(`- API: ${health.api.ok ? `ok${health.api.version !== undefined ? ` (v${health.api.version})` : ''}` : 'down'}`)
+      lines.push(`- process: ${health.process.present ? 'alive' : 'not detected'}`)
+      let models = [] as Array<{ name: string; size: number }>
+      try {
+        models = await listModels(resolved.baseURL, fetchImpl)
+      } catch {
+        // Model listing is best-effort in the overview; health already reported the failure.
+      }
+      const totalBytes = models.reduce((sum, model) => sum + model.size, 0)
+      lines.push(`- models: ${models.length} installed (${formatBytes(totalBytes)})`)
+      for (const model of models) lines.push(`  - ${model.name} (${formatBytes(model.size)})`)
+      if (!health.api.ok && !health.process.present) {
+        lines.push('suggestion: start the Ollama server (e.g. `ollama serve`)')
+      } else if (resolved.route.length === 0) {
+        lines.push('suggestion: configure `route` rules to route requests to local models')
+      }
+      return { kind: 'success', text: lines.join('\n') }
+    },
+  })
+
+  logger.info(`ollama adapter registered at ${resolved.baseURL} (${resolved.models.length} mapping(s), ${resolved.route.length} route rule(s))`)
+}

package/src/ollama.ts

@@ -0,0 +1,274 @@
+/**
+ * Ollama HTTP API client (zero runtime dependencies — plain `fetch`). The
+ * harness `LlmAdapter` streams through `/api/chat`; discovery and management
+ * tools call `/api/tags`, `/api/show`, `/api/pull`, `/api/delete`, and
+ * `/api/version`. Every request carries the harness attribution headers and
+ * honors the caller's abort signal; non-2xx responses fail with a normalized
+ * `LlmError`. The fetch implementation is injectable for tests.
+ * @module dsh-local-ai/ollama
+ */
+
+import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm'
+import { sanitizeEndpoint } from './sanitize.ts'
+
+/** A `fetch`-compatible function, injectable for tests. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
+
+/** One installed model as reported by `/api/tags`. */
+export interface OllamaModel {
+  name: string
+  model: string
+  size: number
+  digest: string
+  modified_at?: string
+  details?: OllamaModelDetails
+}
+
+/** Structured model details reported by `/api/show` and `/api/tags`. */
+export interface OllamaModelDetails {
+  family?: string
+  parameter_size?: string
+  quantization_level?: string
+  format?: string
+  parent_model?: string
+}
+
+/** The `/api/show` response body. */
+export interface OllamaShowResult {
+  license?: string
+  modelfile?: string
+  parameters?: string
+  template?: string
+  details?: OllamaModelDetails
+  model_info?: Record<string, unknown>
+}
+
+/** The `/api/version` response body. */
+export interface OllamaVersionResult {
+  version: string
+}
+
+/** The `/api/pull` final success status. */
+export interface OllamaPullResult {
+  status: string
+}
+
+/** Build an absolute API URL from a normalized base URL. */
+export function endpointUrl(baseURL: string, path: string): string {
+  return `${baseURL}${path}`
+}
+
+/** Map an HTTP status to a stable LlmError code. */
+export function httpErrorCode(status: number): string {
+  if (status === 404) return 'NOT_FOUND'
+  if (status === 400) return 'INVALID_REQUEST'
+  if (status >= 500) return 'SERVER'
+  return `HTTP_${status}`
+}
+
+/** Throw a normalized LlmError from a non-2xx response, using the body's `error`. */
+async function throwHttpError(response: Response, context: string): Promise<never> {
+  let message = `Ollama API error (HTTP ${response.status}) from ${sanitizeEndpoint(context)}`
+  try {
+    const body = await response.json() as { error?: unknown }
+    if (typeof body.error === 'string' && body.error.length > 0) message = body.error
+  } catch {
+    // Only swallow error-body parsing: the HTTP status still identifies the failure.
+  }
+  throw new LlmError(message, httpErrorCode(response.status), { status: response.status })
+}
+
+/** Send a GET request and parse the JSON response. */
+export async function requestJson<T>(
+  baseURL: string,
+  path: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<T> {
+  const response = await fetchImpl(endpointUrl(baseURL, path), {
+    method: 'GET',
+    headers: { accept: 'application/json', ...attributionHeaders() },
+    ...signal === undefined ? {} : { signal },
+  })
+  if (!response.ok) await throwHttpError(response, endpointUrl(baseURL, path))
+  return response.json() as Promise<T>
+}
+
+/** Send a POST request and parse the JSON response. */
+export async function postJson<T>(
+  baseURL: string,
+  path: string,
+  body: unknown,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<T> {
+  const response = await fetchImpl(endpointUrl(baseURL, path), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json', ...attributionHeaders() },
+    body: JSON.stringify(body),
+    ...signal === undefined ? {} : { signal },
+  })
+  if (!response.ok) await throwHttpError(response, endpointUrl(baseURL, path))
+  return response.json() as Promise<T>
+}
+
+/** Send a DELETE request and parse the JSON response. */
+export async function deleteJson<T>(
+  baseURL: string,
+  path: string,
+  body: unknown,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<T> {
+  const response = await fetchImpl(endpointUrl(baseURL, path), {
+    method: 'DELETE',
+    headers: { 'content-type': 'application/json', accept: 'application/json', ...attributionHeaders() },
+    body: JSON.stringify(body),
+    ...signal === undefined ? {} : { signal },
+  })
+  if (!response.ok) await throwHttpError(response, endpointUrl(baseURL, path))
+  return response.json() as Promise<T>
+}
+
+/**
+ * Send a POST and return the raw `Response` after validating 2xx. Used by the
+ * streaming adapter, which owns body decoding and the idle watchdog.
+ */
+export async function postStream(
+  baseURL: string,
+  path: string,
+  body: unknown,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<Response> {
+  const response = await fetchImpl(endpointUrl(baseURL, path), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/x-ndjson', ...attributionHeaders() },
+    body: JSON.stringify(body),
+    ...signal === undefined ? {} : { signal },
+  })
+  if (!response.ok) await throwHttpError(response, endpointUrl(baseURL, path))
+  return response
+}
+
+/** List installed models from `/api/tags`. */
+export async function listModels(
+  baseURL: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<OllamaModel[]> {
+  const result = await requestJson<{ models?: OllamaModel[] }>(baseURL, '/api/tags', fetchImpl, signal)
+  return result.models ?? []
+}
+
+/** List currently-loaded (running) models from `/api/ps`. */
+export async function listRunning(
+  baseURL: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<OllamaModel[]> {
+  const result = await requestJson<{ models?: OllamaModel[] }>(baseURL, '/api/ps', fetchImpl, signal)
+  return result.models ?? []
+}
+
+/** Inspect one model via `/api/show`. */
+export async function showModel(
+  baseURL: string,
+  name: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<OllamaShowResult> {
+  return postJson<OllamaShowResult>(baseURL, '/api/show', { name }, fetchImpl, signal)
+}
+
+/** Remove one model via `/api/delete`. */
+export async function removeModel(
+  baseURL: string,
+  name: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<void> {
+  await deleteJson<{ status?: string }>(baseURL, '/api/delete', { name }, fetchImpl, signal)
+}
+
+/** Query the Ollama server version via `/api/version`. */
+export async function apiVersion(
+  baseURL: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await requestJson<OllamaVersionResult>(baseURL, '/api/version', fetchImpl, signal)
+  return result.version
+}
+
+/**
+ * Pull a model via `/api/pull`, consuming the progress stream and returning the
+ * final status. An intermediate error status or a non-2xx response fails loud.
+ */
+export async function pullModel(
+  baseURL: string,
+  name: string,
+  fetchImpl: FetchLike,
+  signal?: AbortSignal,
+): Promise<OllamaPullResult> {
+  const response = await postStream(baseURL, '/api/pull', { name, stream: true }, fetchImpl, signal)
+  if (!response.body) throw new LlmError('Ollama pull returned no response body', 'EMPTY_RESPONSE')
+  let last: OllamaPullResult = { status: 'success' }
+  for await (const line of readNdjsonLines(response.body)) {
+    if (line.length === 0) continue
+    const chunk = JSON.parse(line) as { status?: string; error?: string }
+    if (typeof chunk.error === 'string' && chunk.error.length > 0) {
+      throw new LlmError(chunk.error, 'PROVIDER')
+    }
+    if (typeof chunk.status === 'string') last = { status: chunk.status }
+  }
+  return last
+}
+
+/**
+ * Decode a `ReadableStream<Uint8Array>` into newline-delimited text lines.
+ * The final line is yielded even without a trailing newline; a missing body
+ * yields nothing.
+ * @param body - the response body stream.
+ * @returns text lines in delivery order.
+ */
+export async function* readNdjsonLines(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      let newline = buffer.indexOf('\n')
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).replace(/\r$/u, '')
+        buffer = buffer.slice(newline + 1)
+        newline = buffer.indexOf('\n')
+        yield line
+      }
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  buffer += decoder.decode()
+  if (buffer.length > 0) yield buffer
+}
+
+/**
+ * Extract the context length from an `/api/show` result by scanning
+ * `model_info` for a `*.context_length` or bare `context_length` entry.
+ * @param show - the `/api/show` result.
+ * @returns the context length, or `undefined` when not reported.
+ */
+export function contextLengthOf(show: OllamaShowResult): number | undefined {
+  const info = show.model_info
+  if (info === undefined) return undefined
+  for (const [key, value] of Object.entries(info)) {
+    if (key === 'context_length' || key.endsWith('.context_length')) {
+      if (typeof value === 'number' && Number.isInteger(value) && value > 0) return value
+    }
+  }
+  return undefined
+}

package/src/route.ts

@@ -0,0 +1,127 @@
+/**
+ * Local-model routing decision and the streaming fallback. The pure decision
+ * matches configured rules (task type via `purpose`, case-insensitive
+ * keywords, or a blanket `always`) against a request, in list order — first
+ * match wins. The streaming helper routes a matched request to the local
+ * Ollama adapter and, when the local route fails BEFORE producing any visible
+ * content, falls back to the cloud (`next()`) so a down Ollama never bricks a
+ * conversation. Once local content has started, it is streamed through — a
+ * mid-stream failure cannot be retracted.
+ * @module dsh-local-ai/route
+ */
+
+import { isTokenDelta } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { OLLAMA_PROVIDER } from './adapter.ts'
+import type { ResolvedConfig, ResolvedRouteRule } from './config.ts'
+
+/** The chosen local model for one matched request. */
+export interface RouteDecision {
+  /** Harness-visible local model name. */
+  readonly model: string
+}
+
+/**
+ * Concatenate the request's model-visible text (system prompt + every text
+ * block) for keyword matching.
+ * @param options - the request.
+ * @returns the joined text.
+ */
+export function requestText(options: GenerateOptions): string {
+  const parts: string[] = []
+  if (options.system !== undefined) parts.push(options.system)
+  for (const message of options.messages) {
+    for (const block of message.content) {
+      if (block.type === 'text') parts.push(block.text)
+    }
+  }
+  return parts.join('\n')
+}
+
+/** Whether a keyword appears case-insensitively in the text. */
+export function matchesKeyword(text: string, keyword: string): boolean {
+  return text.toLowerCase().includes(keyword.toLowerCase())
+}
+
+/** Whether one resolved rule matches a request. */
+export function ruleMatches(rule: ResolvedRouteRule, options: GenerateOptions): boolean {
+  if (rule.always) return true
+  if (rule.purpose !== undefined && options.purpose === rule.purpose) return true
+  if (rule.keywords.length > 0) {
+    const text = requestText(options)
+    return rule.keywords.some(keyword => matchesKeyword(text, keyword))
+  }
+  return false
+}
+
+/**
+ * Decide whether a request should route to a local model. A request already
+ * addressed to the `ollama` provider (explicit selection or a prior re-route)
+ * never re-routes.
+ * @param options - the request.
+ * @param resolved - the resolved config.
+ * @returns the local model to use, or `undefined` to stay on the cloud route.
+ */
+export function decideRoute(options: GenerateOptions, resolved: ResolvedConfig): RouteDecision | undefined {
+  if (options.provider === OLLAMA_PROVIDER) return undefined
+  for (const rule of resolved.route) {
+    if (ruleMatches(rule, options)) return { model: rule.model }
+  }
+  return undefined
+}
+
+/**
+ * Stream a locally-routed request with automatic cloud fallback. The local
+ * stream is produced through `streamLocal` (the full harness stream, so the
+ * local route keeps retry and failure normalization). If the local route
+ * finishes with an error or aborts before any token delta, `next()` (the
+ * cloud) is streamed instead; otherwise the local stream is forwarded.
+ * @param streamLocal - produces the local stream for a re-routed request.
+ * @param options - the original request.
+ * @param decision - the local model to route to.
+ * @param next - the cloud stream (the waterfall's `next()`).
+ * @returns the effective chunk stream.
+ */
+export async function* routeLocal(
+  streamLocal: (options: GenerateOptions) => AsyncIterable<StreamChunk>,
+  options: GenerateOptions,
+  decision: RouteDecision,
+  next: () => AsyncIterable<StreamChunk>,
+): AsyncGenerator<StreamChunk> {
+  const localOptions: GenerateOptions = { ...options, provider: OLLAMA_PROVIDER, model: decision.model }
+  const upstream = streamLocal(localOptions)
+  let producedContent = false
+  const pending: StreamChunk[] = []
+  try {
+    for await (const chunk of upstream) {
+      if (producedContent) {
+        yield chunk
+        continue
+      }
+      if (chunk.type === 'finish') {
+        if (chunk.reason.kind === 'error' || chunk.reason.kind === 'aborted') {
+          // Local failed before producing content — fall back to the cloud.
+          yield* next()
+          return
+        }
+        yield chunk
+        return
+      }
+      pending.push(chunk)
+      if (isTokenDelta(chunk)) {
+        producedContent = true
+        for (const buffered of pending) yield buffered
+        pending.length = 0
+      }
+    }
+    // Stream ended without a finish chunk — flush whatever was buffered.
+    for (const buffered of pending) yield buffered
+  } catch (error) {
+    if (!producedContent) {
+      yield* next()
+      return
+    }
+    for (const buffered of pending) yield buffered
+    throw error
+  }
+}