headlesscode 1.0.2

package/src/init/cli.ts

@@ -0,0 +1,248 @@
+/**
+ * `headlesscode init` subcommand — one-command project registration.
+ *
+ *   npx tsx src/cli.ts init --workspace <path> [--skip-index] [--skip-codemap]
+ *                           [--embedding-backend <openrouter|ollama|airunner>]
+ *
+ * A thin orchestration layer over EXISTING functionality: project registration
+ * (resolveProjectDataDir), stack detection (detectStacks), .gitignore hygiene
+ * (ensureWorkspaceGitignore), the codesearch index (indexMain) and the codemap
+ * (codemapMain). It must not reimplement any of those — each step shells into
+ * the same code path its standalone subcommand uses (see
+ * plans/project-init-registration.md).
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { resolveProjectDataDir } from "../project-store.js"
+import { detectStacks, getCentralStackRulesFile } from "../engine/stacks.js"
+import { indexMain } from "../codesearch/cli.js"
+import { loadIndex } from "../codesearch/index.js"
+import { codemapMain } from "../codemap/cli.js"
+import { ensureWorkspaceGitignore } from "./gitignore.js"
+
+const INIT_USAGE = `headlesscode init — one-command project registration
+
+Usage:
+  headlesscode init --workspace <path> [--skip-index] [--skip-codemap]
+                    [--embedding-backend <openrouter|ollama|airunner>]
+
+Options:
+  --workspace <path>      Workspace root to register (required; must be a
+                          directory)
+  --skip-index            Do not build/refresh the codebase-search index
+                          (saves embedding API cost)
+  --skip-codemap          Do not build/refresh the codemap
+  --embedding-backend <b> Embedding backend for the index step: openrouter
+                          (default), ollama (local), or airunner (local
+                          AIRunner server). Passed straight through to
+                          \`headlesscode index\`
+  --help                  Show this help and exit
+
+Registers a new project with headlesscode in one step: resolves the central
+per-project data dir (~/.local/share/headlesscode/projects/<key>), detects
+the project's stack(s) (stack-aware instructions are spliced into every
+session automatically — see docs/stack-rules.md), makes sure the workspace's
+.gitignore excludes .headlesscode/ session artifacts, then builds the
+codebase-search index and the codemap. Each step is independent: a failure in
+one is reported inline and the remaining steps still run, but the command
+exits non-zero.
+
+The index step costs real money (embedding API calls) unless a local backend
+(--embedding-backend ollama or airunner) is used or the step is skipped with
+--skip-index.
+`
+
+interface InitCliOptions {
+	workspace?: string
+	skipIndex: boolean
+	skipCodemap: boolean
+	embeddingBackend?: string
+	help: boolean
+}
+
+export function parseInitArgs(argv: string[]): { options: InitCliOptions; error?: string } {
+	const options: InitCliOptions = { skipIndex: false, skipCodemap: false, help: false }
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		const eq = arg.indexOf("=")
+		const flag = eq === -1 ? arg : arg.slice(0, eq)
+		const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1)
+		const next = (): string | undefined => {
+			if (inlineValue !== undefined) {
+				return inlineValue
+			}
+			const v = argv[i + 1]
+			if (v === undefined || v.startsWith("--")) {
+				return undefined
+			}
+			i++
+			return v
+		}
+		switch (flag) {
+			case "--workspace":
+			case "--embedding-backend": {
+				const value = next()
+				if (value === undefined) {
+					return { options, error: `Missing value for ${flag}` }
+				}
+				if (flag === "--workspace") {
+					options.workspace = value
+				} else {
+					options.embeddingBackend = value
+				}
+				break
+			}
+			case "--skip-index":
+				options.skipIndex = true
+				break
+			case "--skip-codemap":
+				options.skipCodemap = true
+				break
+			case "--help":
+			case "-h":
+				options.help = true
+				break
+			default:
+				return { options, error: `Unknown argument: ${arg}` }
+		}
+	}
+	return { options }
+}
+
+export async function initMain(argv: string[]): Promise<number> {
+	const { options, error } = parseInitArgs(argv)
+	if (error) {
+		process.stderr.write(`headlesscode init: ${error}\n\n${INIT_USAGE}`)
+		return 2
+	}
+	if (options.help) {
+		process.stdout.write(INIT_USAGE)
+		return 0
+	}
+	if (!options.workspace) {
+		process.stderr.write(`headlesscode init: --workspace <path> is required\n\n${INIT_USAGE}`)
+		return 2
+	}
+
+	const workspaceRoot = path.resolve(options.workspace)
+	let isDir = false
+	try {
+		isDir = fs.statSync(workspaceRoot).isDirectory()
+	} catch {
+		isDir = false
+	}
+	if (!isDir) {
+		process.stderr.write(`headlesscode init: --workspace is not a directory: ${workspaceRoot}\n\n${INIT_USAGE}`)
+		return 2
+	}
+
+	process.stdout.write("headlesscode init — one-command project registration\n\n")
+
+	// Step 1: resolve + register (the existing, sole registration mechanism —
+	// writes <central>/project.json on first contact). `registered: true` is
+	// ONLY ever set here — no other call site in the codebase passes it, so a
+	// human-deliberate registration is the single thing that flips the flag.
+	const centralDir = resolveProjectDataDir(workspaceRoot, { registered: true })
+	process.stdout.write(
+		"Step 1/5 — project registration\n" +
+			`  workspace:        ${workspaceRoot}\n` +
+			`  central data dir: ${centralDir}\n\n`,
+	)
+
+	// Step 2: detect stacks (per-session detection is what actually drives
+	// instruction selection — this is the one place it's surfaced to a human).
+	const stacks = await detectStacks(workspaceRoot)
+	process.stdout.write("Step 2/5 — stack detection\n")
+	if (stacks.size === 0) {
+		process.stdout.write("  no recognized stack — generic instructions only\n")
+	} else {
+		process.stdout.write(`  detected: ${[...stacks].join(", ")}\n`)
+		for (const stack of stacks) {
+			const rulesFile = getCentralStackRulesFile(stack)
+			if (fs.existsSync(rulesFile)) {
+				process.stdout.write(`    ${stack}: rules at ${rulesFile}\n`)
+			} else {
+				process.stdout.write(
+					`    ${stack}: no central rules content yet — consider adding ${rulesFile}\n`,
+				)
+			}
+		}
+	}
+	process.stdout.write("\n")
+
+	// Step 3: ensure the target repo's .gitignore excludes .headlesscode/.
+	process.stdout.write("Step 3/5 — .gitignore\n")
+	const gitignoreResult = ensureWorkspaceGitignore(workspaceRoot)
+	const gitignoreActionText =
+		gitignoreResult.action === "created"
+			? "created with /.headlesscode/ entry"
+			: gitignoreResult.action === "appended"
+				? "appended /.headlesscode/ entry (existing content untouched)"
+				: "already covers .headlesscode — no change"
+	process.stdout.write(`  ${gitignoreResult.path}: ${gitignoreActionText}\n\n`)
+
+	// Steps 4-5: index + codemap. Each is independent: a failure is reported
+	// inline and the later step still runs, but the command exits non-zero.
+	let exitCode = 0
+	let indexSummary = "skipped by flag"
+	let codemapSummary = "skipped by flag"
+
+	process.stdout.write("Step 4/5 — codebase index\n")
+	if (!options.skipIndex) {
+		const indexArgs = ["--workspace", workspaceRoot]
+		if (options.embeddingBackend) {
+			indexArgs.push("--embedding-backend", options.embeddingBackend)
+		}
+		try {
+			// Same code path as `headlesscode index` — including its
+			// cost/token summary (real embedding API spend).
+			const code = await indexMain(indexArgs)
+			if (code !== 0) {
+				exitCode = 1
+				indexSummary = `FAILED (exit ${code})`
+			} else {
+				indexSummary = `ok — ${loadIndex(workspaceRoot).length} chunks in index`
+			}
+		} catch (err) {
+			exitCode = 1
+			indexSummary = `FAILED (${err instanceof Error ? err.message : String(err)})`
+		}
+	} else {
+		process.stdout.write("  skipped by flag\n")
+	}
+	process.stdout.write("\n")
+
+	process.stdout.write("Step 5/5 — codemap\n")
+	if (!options.skipCodemap) {
+		try {
+			const code = await codemapMain(["--workspace", workspaceRoot])
+			if (code !== 0) {
+				exitCode = 1
+				codemapSummary = `FAILED (exit ${code})`
+			} else {
+				codemapSummary = "ok (see step 5 output above)"
+			}
+		} catch (err) {
+			exitCode = 1
+			codemapSummary = `FAILED (${err instanceof Error ? err.message : String(err)})`
+		}
+	} else {
+		process.stdout.write("  skipped by flag\n")
+	}
+	process.stdout.write("\n")
+
+	// Step 6: final summary.
+	process.stdout.write(
+		"Summary\n" +
+			`  workspace:         ${workspaceRoot}\n` +
+			`  central data dir:  ${centralDir}\n` +
+			`  stacks:            ${stacks.size === 0 ? "none (generic instructions only)" : [...stacks].join(", ")}\n` +
+			`  gitignore:         ${gitignoreResult.action}\n` +
+			`  index:             ${indexSummary}\n` +
+			`  codemap:           ${codemapSummary}\n`,
+	)
+
+	return exitCode
+}

package/src/init/gitignore.ts

@@ -0,0 +1,74 @@
+/**
+ * `headlesscode init`'s .gitignore hygiene: ensure a target repo's
+ * `.gitignore` excludes `.headlesscode/` so workspace-relative session
+ * artifacts (events, reports, usage, scratch, memory) can never be
+ * accidentally committed by a human `git add -A` after a first run.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+export type GitignoreActionResult =
+	| { action: "created"; path: string }
+	| { action: "appended"; path: string }
+	| { action: "unchanged"; path: string }
+
+/**
+ * True when a `.gitignore` already covers `.headlesscode`. Accepts any of the
+ * four common spellings (`.headlesscode/`, `/.headlesscode/`, `.headlesscode`,
+ * `/.headlesscode`) plus a bare `*` — the same slash-normalizing,
+ * segment-matching idiom src/codesearch/files.ts's fallback matcher uses.
+ */
+function gitignoreCoversHeadlesscode(content: string): boolean {
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim()
+		if (trimmed === "" || trimmed.startsWith("#")) {
+			continue
+		}
+		const p = trimmed.replace(/^\/+/, "").replace(/\/+$/, "")
+		if (p === ".headlesscode" || p === "*") {
+			return true
+		}
+	}
+	return false
+}
+
+/**
+ * Ensure `<workspace>/.gitignore` ignores `.headlesscode/`:
+ *   - file absent → created with the entry;
+ *   - file present but not covering it → entry appended (existing content
+ *     preserved byte-for-byte, no reformatting or reordering);
+ *   - already covered → untouched.
+ *
+ * Never touches the filesystem when the workspace is not a real directory
+ * (a missing workspace is `init`'s job to fail on, not this helper's to
+ * silently create a `.gitignore` for).
+ */
+export function ensureWorkspaceGitignore(workspaceRoot: string): GitignoreActionResult {
+	const gitignorePath = path.join(workspaceRoot, ".gitignore")
+	try {
+		if (!fs.statSync(workspaceRoot).isDirectory()) {
+			return { action: "unchanged", path: gitignorePath }
+		}
+	} catch {
+		return { action: "unchanged", path: gitignorePath }
+	}
+
+	let existing = ""
+	let existed = false
+	try {
+		existing = fs.readFileSync(gitignorePath, "utf-8")
+		existed = true
+	} catch {
+		// Missing .gitignore — start from empty.
+	}
+
+	if (gitignoreCoversHeadlesscode(existing)) {
+		return { action: "unchanged", path: gitignorePath }
+	}
+
+	const entry = "# headlesscode session artifacts (events, reports, usage, scratch, memory)\n/.headlesscode/\n"
+	const content = existing === "" || existing.endsWith("\n") ? existing + entry : existing + "\n" + entry
+	fs.writeFileSync(gitignorePath, content, "utf-8")
+	return { action: existed ? "appended" : "created", path: gitignorePath }
+}

package/src/llm/ollama.ts

@@ -0,0 +1,308 @@
+/**
+ * Ollama-compatible local LLM client — implements the full `LlmClient`
+ * interface (not the narrow read-only `LocalChatClient` in
+ * src/engine/local-explore.ts) so a session's `code` mode can run entirely
+ * against a local model instead of OpenRouter. See
+ * plans/local-dual-model-code-agent.md (Phase 2 step 4) and
+ * plans/local-code-mode-trial.md for the design this implements.
+ *
+ * Reuses the wire-format findings already verified live against Ollama
+ * 0.24.0 / the local daemon's ollama-compat route in
+ * src/engine/local-explore.ts's OllamaLocalChatClient:
+ *   - `function.arguments` must be a parsed OBJECT on the wire in both
+ *     directions (Ollama rejects the OpenAI/OpenRouter JSON-string form).
+ *   - `think` previously had to be hardcoded `false`: a prior local model
+ *     was observed leaving `message.content` empty and putting the reply in
+ *     `message.thinking` when thinking was on. Re-verified live 2026-08-20
+ *     against Qwen3-14B (the first thinking-capable local model this harness
+ *     has run) on both a plain reply and a tool call — `content`/`tool_calls`
+ *     came back correctly populated with `think: true`, so that failure mode
+ *     doesn't reproduce for this model. Rather than flip the default (and
+ *     risk the original model that motivated `false`), `think` is now
+ *     configurable per client instance — see `OLLAMA_THINK_ENV`.
+ * Cost is always $0 (no OpenRouter billing involved) but real token counts
+ * are still reported via `usage` so budget/report accounting stays accurate.
+ *
+ * `node_id` continuity (found 2026-08-27 debugging a live daemon): the
+ * airunnerdesktop daemon's `/api/chat` route is NOT actually stateless
+ * despite implementing the Ollama wire protocol — `_get_or_create_conversation`
+ * (conversation_management_mixin.py) opens a BRAND NEW, empty DB-backed
+ * conversation on every call unless the request body carries a stable
+ * `node_id` string, which this client never sent. Verified live: without
+ * `node_id`, every call got a fresh `conversation_id` (confirmed via the
+ * daemon's own logs incrementing 5912 -> 5913 one call apart) with zero
+ * prior messages, so on any turn after the first — once the daemon's own
+ * chat-template tries to render a multi-turn tool-calling exchange whose
+ * "history" is actually empty — the underlying jinja2 chat template raises
+ * `TemplateError: No user query found in messages` (the DB truly has no
+ * user-role message, since only the single newest turn — a tool result,
+ * not the original user turn — ever got attached to that fresh
+ * conversation). One real request in isolation "works" (a fresh
+ * conversation containing exactly the current user message renders fine),
+ * which is why this was easy to misdiagnose as a context-window or
+ * capability issue rather than a continuity bug. Sending a stable `node_id`
+ * (generated once per `OllamaClient` instance, i.e. once per headlesscode
+ * session) makes the daemon reuse the SAME conversation record across every
+ * call in a session, matching how a real chat UI like uwuchat's own
+ * LangChain-based client drives this same daemon successfully.
+ */
+
+import { randomUUID } from "node:crypto"
+import { Agent, fetch as undiciFetch } from "undici"
+import type { ChatMessage, ChatToolCall, LlmClient, LlmRequest, LlmResponse } from "../engine/types.js"
+import { captureTranscript, isTranscriptCaptureEnabled } from "./transcript-capture.js"
+
+export const OLLAMA_URL_ENV = "HEADLESSCODE_OLLAMA_URL"
+export const DEFAULT_OLLAMA_URL = "http://localhost:11434"
+export const DEFAULT_OLLAMA_TIMEOUT_MS = 300_000
+/** Opt a thinking-capable local model into `think: true` (default false — see the module doc comment). */
+export const OLLAMA_THINK_ENV = "HEADLESSCODE_OLLAMA_THINK"
+
+export interface OllamaClientOptions {
+	baseUrl?: string
+	defaultModel?: string
+	timeoutMs?: number
+	fetchImpl?: typeof fetch
+	/** Send `think: true` to the daemon (default false). See `OLLAMA_THINK_ENV`. */
+	think?: boolean
+	/** Override the `node_id` sent with every request (default: a fresh UUID per client instance). See the module doc comment. */
+	nodeId?: string
+}
+
+/** Typed error for a non-2xx response or a malformed payload from the daemon. */
+export class OllamaError extends Error {
+	readonly status?: number
+	readonly body?: string
+
+	constructor(message: string, status?: number, body?: string) {
+		super(message)
+		this.name = "OllamaError"
+		this.status = status
+		this.body = body
+	}
+}
+
+function envThinkEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	const v = env[OLLAMA_THINK_ENV]
+	return v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false"
+}
+
+export class OllamaClient implements LlmClient {
+	private readonly baseUrl: string
+	private readonly defaultModel: string
+	private readonly timeoutMs: number
+	private readonly fetchImpl: typeof fetch
+	private readonly think: boolean
+	/** Stable per-client identifier sent as `node_id` so a stateful daemon (e.g. airunnerdesktop) reuses one conversation for this session instead of a fresh, history-less one per call. See the module doc comment. */
+	private readonly nodeId: string
+	/**
+	 * Node's global `fetch` runs on an undici HTTP client with its OWN
+	 * independent default timeouts (`headersTimeout`/`bodyTimeout`, 300s
+	 * each) that fire regardless of the `AbortSignal` passed to fetch() —
+	 * verified live 2026-08-28 (joeos issue #26, round 7): with `timeoutMs`
+	 * already raised past 300s via the constructor option AND the request's
+	 * own AbortController set to fire at that later value, a session still
+	 * died at ~300-330s with a generic "fetch failed" (not the "timed out
+	 * after Xms" message this class produces itself on a real AbortError —
+	 * proof it wasn't `this.timeoutMs`'s own timer that fired first). A
+	 * real prefill+generation call against a 9B local model at deep prompt
+	 * lengths can legitimately take longer than undici's default assumes.
+	 *
+	 * Overriding this requires a per-instance `Agent` with both timeouts
+	 * derived from `this.timeoutMs` (comfortable margin above it) — but
+	 * passing an `Agent` built from the standalone `undici` npm package as
+	 * Node's GLOBAL `fetch`'s `dispatcher` does not reliably work: verified
+	 * live, this threw `InvalidArgumentError: invalid onRequestStart
+	 * method` (code UND_ERR_INVALID_ARG) — Node's global fetch runs on its
+	 * OWN internal, bundled copy of undici (`node:internal/deps/undici`),
+	 * whose Dispatcher/Handler interface isn't guaranteed to match whatever
+	 * version the standalone package resolves to. The fix is to use
+	 * undici's own `fetch` (imported below as `undiciFetch`) together with
+	 * its own `Agent`, so both come from the SAME package/version and the
+	 * interface always matches — never Node's global `fetch` plus an
+	 * externally-built dispatcher.
+	 */
+	private readonly dispatcher: Agent
+
+	constructor(options: OllamaClientOptions = {}) {
+		this.baseUrl = (options.baseUrl ?? process.env[OLLAMA_URL_ENV] ?? DEFAULT_OLLAMA_URL).replace(/\/+$/, "")
+		this.defaultModel = options.defaultModel ?? ""
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_OLLAMA_TIMEOUT_MS
+		// Default to undici's OWN fetch, not Node's global one — see
+		// `dispatcher`'s doc comment for why: only undici's own fetch is
+		// guaranteed interface-compatible with an Agent built from the same
+		// package. `fetchImpl`'s public option type stays `typeof fetch`
+		// (structurally close enough for test fakes to satisfy); the cast
+		// here just reconciles undici's own Response/RequestInit types
+		// against the DOM-lib ones the public field declares.
+		const defaultFetchImpl: unknown = (url: unknown, init: unknown) =>
+			undiciFetch(url as Parameters<typeof undiciFetch>[0], init as Parameters<typeof undiciFetch>[1])
+		this.fetchImpl = options.fetchImpl ?? (defaultFetchImpl as typeof fetch)
+		this.think = options.think ?? envThinkEnabled()
+		this.nodeId = options.nodeId ?? randomUUID()
+		const undiciTimeoutMs = this.timeoutMs + 60_000
+		this.dispatcher = new Agent({ headersTimeout: undiciTimeoutMs, bodyTimeout: undiciTimeoutMs })
+	}
+
+	resolveModel(requestModel?: string): string {
+		return requestModel?.trim() || this.defaultModel
+	}
+
+	async createChatCompletion(request: LlmRequest): Promise<LlmResponse> {
+		const model = this.resolveModel(request.model)
+		if (!model) {
+			throw new OllamaError("OllamaClient: no model resolved (pass request.model or defaultModel)")
+		}
+		const startedAt = Date.now()
+
+		const controller = new AbortController()
+		const onAbort = () => controller.abort()
+		request.signal?.addEventListener("abort", onAbort)
+		const timer = setTimeout(() => controller.abort(), this.timeoutMs)
+
+		try {
+			const res = await this.fetchImpl(`${this.baseUrl}/api/chat`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				signal: controller.signal,
+				// See `dispatcher`'s doc comment: `this.fetchImpl` defaults to
+				// undici's own fetch (bridged through a `typeof fetch`-typed
+				// wrapper for public-API/test compatibility), which DOES
+				// understand a per-call `dispatcher` the same way undici's
+				// Agent-based clients do — this cast just reconciles that
+				// against the DOM-lib `RequestInit` type this call site is
+				// statically typed against. A fake fetchImpl injected in
+				// tests simply ignores this extra field.
+				dispatcher: this.dispatcher as unknown as RequestInit["dispatcher"],
+				body: JSON.stringify({
+					model,
+					node_id: this.nodeId,
+					messages: toOllamaMessages(request.messages),
+					stream: false,
+					think: this.think,
+					tools: request.tools,
+					...(request.toolChoice !== undefined ? { tool_choice: request.toolChoice } : {}),
+					options: {
+						temperature: request.temperature ?? 0,
+						...(request.maxTokens !== undefined ? { num_predict: request.maxTokens } : {}),
+						...(request.repeatPenalty !== undefined ? { repeat_penalty: request.repeatPenalty } : {}),
+					},
+				}),
+			})
+			if (!res.ok) {
+				const body = await res.text().catch(() => "")
+				throw new OllamaError(`Ollama /api/chat returned HTTP ${res.status}: ${body.slice(0, 500)}`, res.status, body)
+			}
+			const data = (await res.json()) as {
+				message?: {
+					role?: string
+					content?: string | null
+					thinking?: string | null
+					tool_calls?: Array<{ id?: string; function?: { name?: string; arguments?: unknown } }>
+				}
+				prompt_eval_count?: number
+				eval_count?: number
+			}
+			if (!data.message) {
+				throw new OllamaError("Ollama /api/chat response had no message field")
+			}
+			const toolCalls: ChatToolCall[] = (data.message.tool_calls ?? []).map((c, i) => ({
+				id: c.id ?? `call_${i}`,
+				type: "function" as const,
+				function: {
+					name: c.function?.name ?? "",
+					arguments: normalizeToolCallArguments(c.function?.arguments),
+				},
+			}))
+			const message: ChatMessage = {
+				role: "assistant",
+				content: data.message.content ?? null,
+				...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+				...(data.message.thinking ? { reasoning: data.message.thinking } : {}),
+			}
+			const response: LlmResponse = {
+				message,
+				usage: {
+					promptTokens: data.prompt_eval_count ?? 0,
+					completionTokens: data.eval_count ?? 0,
+					totalTokens: (data.prompt_eval_count ?? 0) + (data.eval_count ?? 0),
+				},
+			}
+			if (isTranscriptCaptureEnabled()) {
+				captureTranscript(
+					{ provider: "ollama", model },
+					{ messages: request.messages, tools: request.tools, temperature: request.temperature, response, durationMs: Date.now() - startedAt },
+				)
+			}
+			return response
+		} catch (err) {
+			if (isTranscriptCaptureEnabled()) {
+				captureTranscript(
+					{ provider: "ollama", model },
+					{
+						messages: request.messages,
+						tools: request.tools,
+						temperature: request.temperature,
+						error: err instanceof Error ? err.message : String(err),
+						durationMs: Date.now() - startedAt,
+					},
+				)
+			}
+			if (err instanceof OllamaError) {
+				throw err
+			}
+			if (err instanceof Error && err.name === "AbortError") {
+				throw new OllamaError(`Ollama /api/chat timed out after ${this.timeoutMs}ms`)
+			}
+			throw new OllamaError(
+				`Ollama /api/chat request failed: ${err instanceof Error ? err.message : String(err)} (is the daemon running at ${this.baseUrl}? is ${model} loaded?)`,
+			)
+		} finally {
+			clearTimeout(timer)
+			request.signal?.removeEventListener("abort", onAbort)
+		}
+	}
+}
+
+/** Engine ChatMessage[] → Ollama wire format (tool_call arguments as OBJECTS, tool schemas untouched). */
+function toOllamaMessages(messages: ChatMessage[]): unknown[] {
+	return messages.map((m) => {
+		if (m.role === "assistant" && m.tool_calls && m.tool_calls.length > 0) {
+			return {
+				role: "assistant",
+				content: m.content ?? "",
+				tool_calls: m.tool_calls.map((c) => ({
+					id: c.id,
+					type: "function",
+					function: { name: c.function.name, arguments: toOllamaArgs(c.function.arguments) },
+				})),
+			}
+		}
+		if (m.role === "tool") {
+			return { role: "tool", content: m.content ?? "", tool_call_id: m.tool_call_id, name: m.name }
+		}
+		return { role: m.role, content: m.content ?? "" }
+	})
+}
+
+/** Engine arguments JSON string → Ollama object. Parse failure → {} (Ollama rejects strings here). */
+function toOllamaArgs(args: string): unknown {
+	try {
+		return JSON.parse(args)
+	} catch {
+		return {}
+	}
+}
+
+/** Ollama arguments (object, or occasionally string) → engine JSON-string form. */
+function normalizeToolCallArguments(args: unknown): string {
+	if (typeof args === "string") {
+		try {
+			JSON.parse(args)
+			return args
+		} catch {
+			return JSON.stringify({ raw: args })
+		}
+	}
+	return JSON.stringify(args ?? {})
+}