headlesscode 1.0.2

package/src/codesearch/search.ts

@@ -0,0 +1,141 @@
+/**
+ * Query-time search over the persisted codebase index.
+ *
+ * Embed the query (one call), brute-force cosine against every stored chunk,
+ * return the top-K as file:startLine-endLine citations + a snippet — matching
+ * the vendored codebase_search tool's expected result shape (see
+ * src/vendor/zoo-code/src/core/tools/CodebaseSearchTool.ts and the native
+ * tool's description).
+ *
+ * The index stores only { file, startLine, endLine, embedding, hash } — the
+ * chunk TEXT is deliberately NOT duplicated into the index (it would roughly
+ * double the file). The snippet is re-read from the file at query time from
+ * the cited line range; if the file is gone or unreadable the citation is
+ * still returned with an empty snippet.
+ *
+ * SCALING LIMIT (documented, accepted): brute-force cosine is O(N) per query
+ * over all chunks in the index. Fine for this project's scale; a vector DB or
+ * ANN index is the known future path for very large repos (see
+ * src/codesearch/index.ts).
+ *
+ * LOAD CACHING: parsing the index JSONL is the dominant per-query cost — a
+ * 37k-chunk index is ~860MB of JSONL that takes ~5s to stream-parse into
+ * ~1.4GB of JS objects. A codebase_search query therefore pays that once per
+ * SESSION (not per call): the parsed entries are cached keyed by
+ * (path, mtimeMs, size), so a rebuild elsewhere invalidates the cache
+ * automatically and repeated queries are ~instant.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { cosineSimilarity } from "./embedder.js"
+import { indexFilePath, loadIndex } from "./index.js"
+import { DEFAULT_TOP_K, type IndexEntry } from "./types.js"
+
+/** One search result, matching the vendored CodebaseSearchTool's payload shape. */
+export interface SearchResult {
+	filePath: string
+	score: number
+	startLine: number
+	endLine: number
+	codeChunk: string
+}
+
+/** Best-effort read of the cited line range from the file on disk. */
+function readSnippet(workspaceRoot: string, rel: string, startLine: number, endLine: number): string {
+	try {
+		const abs = path.join(path.resolve(workspaceRoot), rel)
+		const content = fs.readFileSync(abs, "utf-8")
+		const lines = content.split(/\r?\n/)
+		const slice = lines.slice(startLine - 1, endLine)
+		return slice.join("\n").trim()
+	} catch {
+		return ""
+	}
+}
+
+// Module-level parsed-index cache (one entry per process — a session runs one
+// workspace; keying by path+mtime+size also makes it correct for several).
+let cachedIndexPath: string | undefined
+let cachedIndexMtimeMs = -1
+let cachedIndexSize = -1
+let cachedEntries: IndexEntry[] = []
+
+/** loadIndex with a session-scoped parse cache; invalidated by file change. */
+function loadIndexCached(workspaceRoot: string): IndexEntry[] {
+	const file = indexFilePath(workspaceRoot)
+	let st: fs.Stats
+	try {
+		st = fs.statSync(file)
+	} catch {
+		// Index disappeared (or never existed) — drop the cache entry so a
+		// later build of the same path is picked up fresh.
+		cachedIndexPath = undefined
+		return loadIndex(workspaceRoot)
+	}
+	if (cachedIndexPath === file && cachedIndexMtimeMs === st.mtimeMs && cachedIndexSize === st.size) {
+		return cachedEntries
+	}
+	const entries = loadIndex(workspaceRoot)
+	cachedIndexPath = file
+	cachedIndexMtimeMs = st.mtimeMs
+	cachedIndexSize = st.size
+	cachedEntries = entries
+	return entries
+}
+
+/** Search the persisted index for the chunks most similar to `query`. */
+export function searchIndex(
+	workspaceRoot: string,
+	queryEmbedding: number[],
+	pathPrefix?: string,
+	topK: number = DEFAULT_TOP_K,
+): SearchResult[] {
+	const entries = loadIndexCached(workspaceRoot)
+	const scored: Array<{ entry: IndexEntry; score: number }> = []
+
+	for (const entry of entries) {
+		if (pathPrefix) {
+			const normalized = pathPrefix.replace(/\\/g, "/").replace(/\/+$/, "")
+			if (!entry.file.startsWith(normalized + "/") && entry.file !== normalized) {
+				continue
+			}
+		}
+		const score = cosineSimilarity(queryEmbedding, entry.embedding)
+		if (score > 0) {
+			scored.push({ entry, score })
+		}
+	}
+
+	scored.sort((a, b) => b.score - a.score)
+	return scored.slice(0, Math.max(1, topK)).map(({ entry, score }) => ({
+		filePath: entry.file,
+		score,
+		startLine: entry.startLine,
+		endLine: entry.endLine,
+		codeChunk: readSnippet(workspaceRoot, entry.file, entry.startLine, entry.endLine),
+	}))
+}
+
+/**
+ * Format search results for the tool result string, matching the vendored
+ * CodebaseSearchTool's output layout (Query / Results / File path / Score /
+ * Lines / Code Chunk).
+ */
+export function formatSearchResults(query: string, results: SearchResult[]): string {
+	if (results.length === 0) {
+		return `No relevant code snippets found for the query: "${query}"`
+	}
+	const blocks = results.map(
+		(r) => `File path: ${r.filePath}
+Score: ${r.score.toFixed(4)}
+Lines: ${r.startLine}-${r.endLine}
+Code Chunk: ${r.codeChunk}
+`,
+	)
+	return `Query: ${query}
+Results:
+
+${blocks.join("\n")}`
+}

package/src/codesearch/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared types for the codebase semantic-search subsystem
+ * (src/codesearch/ — chunker, cloud embedder, persisted index, and the
+ * `codebase_search` tool handler that consumes it).
+ *
+ * This is a deliberately separate subsystem from the Phase 3 memory embedder
+ * (src/memory/embed.ts): that one is a cheap deterministic hash stand-in for
+ * handful-of-records session/fact recall, while this one embeds an entire
+ * repo's source via a real cloud model and persists the vectors to disk.
+ */
+
+/** One indexed code chunk, persisted as one JSON line in the index file. */
+export interface IndexEntry {
+	/** Workspace-relative POSIX path (e.g. "src/engine/loop.ts"). */
+	file: string
+	/** 1-based inclusive line range of this chunk within the file. */
+	startLine: number
+	endLine: number
+	/** Embedding vector (dimension depends on the model). */
+	embedding: number[]
+	/**
+	 * Content hash of the chunk text (sha256 hex of the raw chunk lines). The
+	 * index build compares this against the previous build's entries to skip
+	 * re-embedding unchanged chunks — the cost-control mechanism that stops a
+	 * re-index of an untouched repo from spending money.
+	 */
+	hash: string
+	/**
+	 * Backend that produced this entry's embedding
+	 * (`openrouter` | `ollama` | `airunner`). Added by the build for every
+	 * entry; absent on pre-existing entries from before the Ollama backend
+	 * existed, which the build treats as `openrouter` (the only backend that
+	 * existed then). The query handler refuses to search with a mismatched
+	 * backend — local and cloud embedding models produce different vector
+	 * dimensions, so mixing them would silently yield garbage similarity
+	 * scores.
+	 */
+	backend?: "openrouter" | "ollama" | "airunner"
+}
+
+/**
+ * The on-disk index, relative to the CENTRAL project data dir
+ * (`<dataRoot>/projects/<project-key>/codesearch/index.jsonl` — see
+ * src/project-store.ts). No longer workspace-relative: the index lives in the
+ * central store so every worktree of a repo shares it.
+ */
+export const INDEX_RELATIVE_PATH = "codesearch/index.jsonl"
+
+/** Default top-K results returned by codebase_search. */
+export const DEFAULT_TOP_K = 10
+
+/** Supported source-file extensions (this repo's language mix + docs/config). */
+export const CODE_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".py",
+	".rs",
+	".go",
+	".c",
+	".h",
+	".cpp",
+	".hpp",
+	".cs",
+	".rb",
+	".java",
+	".php",
+	".swift",
+	".kt",
+	".kts",
+	".ex",
+	".exs",
+	".el",
+	".html",
+	".htm",
+	".md",
+	".markdown",
+	".txt",
+	".json",
+	".css",
+	".ml",
+	".mli",
+	".lua",
+	".scala",
+	".toml",
+	".zig",
+	".elm",
+	".ejs",
+	".erb",
+	".vb",
+	".dart",
+	".sh",
+	".bash",
+	".zsh",
+	".yml",
+	".yaml",
+])

package/src/config/mode-models.ts

@@ -0,0 +1,218 @@
+/**
+ * Per-mode model assignment — the CENTRAL project store's `mode-models.json`
+ * (`~/.local/share/headlesscode/projects/<key>/mode-models.json`, see
+ * src/project-store.ts). Keyed by the repo's git-common-dir, so every worktree
+ * of a repo resolves the same per-mode models with zero per-directory setup.
+ *
+ * Maps a mode slug to an OpenRouter model id, with an optional `_default`
+ * fallback key. Kept deliberately simple (a plain local config file — no
+ * complexity-based routing, which is an explicit future idea, not this):
+ *
+ *   { "code": "deepseek/deepseek-v4-flash", "deepseek-reviewer": "deepseek/deepseek-reasoner", "_default": "deepseek/deepseek-v4-flash" }
+ *
+ * Resolution precedence for `resolveModelForMode`:
+ *   1. `explicitModel` (an actual `--model` flag value) — always wins, a
+ *      deliberate manual override.
+ *   2. `mode-models.json[mode]`.
+ *   3. `mode-models.json["_default"]`.
+ *   4. `env.OPENROUTER_MODEL`.
+ *   5. `undefined` — the caller's OpenRouter client then falls back to its
+ *      own built-in default (`DEFAULT_MODEL` in src/llm/openrouter.ts),
+ *      which stays the single source of truth for the ultimate default.
+ *
+ * Non-model `_`-prefixed keys extend the same file: `_condensation` assigns
+ * a cheaper model for the context-condensation call (consulted via extraKeys
+ * before the mode entry), and `_reasoning_effort` sets the graded reasoning
+ * effort for deepseek/* models (see resolveReasoningEffortForMode).
+ *
+ * Fail-loudly on a malformed file (invalid JSON, non-object, or a non-string
+ * value) — the same idiom as the central permissions.json (see
+ * src/permissions/config.ts): a broken config file throws with a clear
+ * message, it never silently falls back. A missing file is NOT an error —
+ * zero config means zero behavior change.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { resolveProjectDataDir } from "../project-store.js"
+
+/** Config file basename inside the central project data dir. */
+export const MODE_MODELS_CONFIG_FILE = "mode-models.json"
+
+/** Absolute path of the central mode-models.json for a workspace root. */
+export function modeModelsFilePath(workspaceRoot: string): string {
+	return path.join(resolveProjectDataDir(workspaceRoot), MODE_MODELS_CONFIG_FILE)
+}
+
+/** The fallback key inside the config file (not a mode slug itself). */
+export const DEFAULT_KEY = "_default"
+
+/** The parsed config file: mode slug (or `_default`) -> model id. */
+export type ModeModelsFile = Record<string, string>
+
+export interface ResolveModelOptions {
+	workspaceRoot: string
+	/** Mode slug to resolve a model for (e.g. "code", "deepseek-reviewer", "qa-agent"). */
+	mode: string
+	/** An explicit `--model` flag value, if the caller passed one. Always wins. */
+	explicitModel?: string
+	/** Env to read OPENROUTER_MODEL from (default: process.env). */
+	env?: NodeJS.ProcessEnv
+	/**
+	 * Optional EXTRA config keys consulted BEFORE the mode entry (e.g.
+	 * `_condensation` — a cheaper model id used for the context-condensation
+	 * LLM call; see src/engine/condense.ts). Each key is read directly from
+	 * the config file, so an entry like `"_condensation": "qwen/qwen3-8b"`
+	 * works without being a real mode slug. Consulted first because the
+	 * whole point of such a key is to override whatever the session model
+	 * resolves to — if the mode entry shadowed it, a file that sets both
+	 * `"code"` and `"_condensation"` (the canonical example) would silently
+	 * keep running condensation on the full-price session model. When none
+	 * of the keys resolve, precedence falls through to `mode` → `_default`
+	 * → `OPENROUTER_MODEL` → undefined exactly as before.
+	 */
+	extraKeys?: string[]
+}
+
+/**
+ * Load the central `mode-models.json` for a workspace when present.
+ * Returns `null` when the file does not exist (the common case). A
+ * present-but-malformed file throws — a broken mapping must fail loudly,
+ * never silently fall back to a different model than the one configured.
+ * Falls back to the legacy `<workspaceRoot>/.headlesscode/mode-models.json`
+ * only when the central file is absent AND the legacy one still exists
+ * (pre-migration grace — the migration in resolveProjectDataDir normally
+ * moves it before this is reached).
+ */
+export function loadModeModelsFile(workspaceRoot: string): ModeModelsFile | null {
+	const filePath = modeModelsFilePath(workspaceRoot)
+	let raw: string
+	try {
+		raw = fs.readFileSync(filePath, "utf-8")
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			const legacy = path.resolve(workspaceRoot, ".headlesscode", MODE_MODELS_CONFIG_FILE)
+			try {
+				raw = fs.readFileSync(legacy, "utf-8")
+			} catch {
+				return null
+			}
+		} else {
+			throw new Error(
+				`mode-models: cannot read mode-models file '${filePath}': ${err instanceof Error ? err.message : String(err)}`,
+			)
+		}
+	}
+
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch (err) {
+		throw new Error(
+			`mode-models: invalid JSON in '${filePath}': ${err instanceof Error ? err.message : String(err)}`,
+		)
+	}
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`mode-models: '${filePath}' must be a JSON object of mode slug -> model id strings`)
+	}
+
+	const out: ModeModelsFile = {}
+	const obj = parsed as Record<string, unknown>
+	for (const [key, value] of Object.entries(obj)) {
+		if (typeof value !== "string") {
+			throw new Error(
+				`mode-models: '${filePath}' entry '${key}' must be a string model id, got ${JSON.stringify(value)}`,
+			)
+		}
+		out[key] = value
+	}
+	return out
+}
+
+/**
+ * Resolve the model id to use for one session, per the precedence rules in
+ * the file header. Returns `undefined` when nothing more specific is
+ * configured — the caller's OpenRouter client then applies its own built-in
+ * default, keeping `DEFAULT_MODEL` in src/llm/openrouter.ts the single
+ * source of truth for the ultimate fallback.
+ */
+export function resolveModelForMode(options: ResolveModelOptions): string | undefined {
+	const { workspaceRoot, mode, explicitModel, extraKeys, env = process.env } = options
+
+	if (explicitModel !== undefined && explicitModel !== "") {
+		return explicitModel
+	}
+
+	const file = loadModeModelsFile(workspaceRoot)
+	if (file !== null) {
+		for (const key of extraKeys ?? []) {
+			if (typeof file[key] === "string") {
+				return file[key]
+			}
+		}
+		if (typeof file[mode] === "string") {
+			return file[mode]
+		}
+		if (typeof file[DEFAULT_KEY] === "string") {
+			return file[DEFAULT_KEY]
+		}
+	}
+
+	const envModel = env.OPENROUTER_MODEL
+	return envModel === undefined || envModel === "" ? undefined : envModel
+}
+
+/** The optional `_reasoning_effort` key inside mode-models.json (not a mode slug). */
+export const REASONING_EFFORT_KEY = "_reasoning_effort"
+
+export interface ResolveReasoningEffortOptions {
+	workspaceRoot: string
+	/** Env to read HEADLESSCODE_REASONING_EFFORT from (default: process.env). */
+	env?: NodeJS.ProcessEnv
+}
+
+/**
+ * Resolve the session's graded reasoning effort (issue #30 experiment) from
+ * the central `mode-models.json` `_reasoning_effort` key (beats env), then
+ * `$HEADLESSCODE_REASONING_EFFORT`, then `undefined` — no effort sent, the
+ * endpoint's undeclared default applies (pre-existing behavior). The value is
+ * a plain string in the same `Record<string, string>` format as model ids, so
+ * no format change is needed. The caller validates/normalizes the value
+ * (parseReasoningEffort in src/llm/openrouter.ts); a missing file/key/env is
+ * NOT an error — zero config means zero behavior change.
+ */
+export function resolveReasoningEffortForMode(options: ResolveReasoningEffortOptions): string | undefined {
+	const { workspaceRoot, env = process.env } = options
+	const file = loadModeModelsFile(workspaceRoot)
+	if (file !== null && typeof file[REASONING_EFFORT_KEY] === "string") {
+		return file[REASONING_EFFORT_KEY]
+	}
+	const envValue = env.HEADLESSCODE_REASONING_EFFORT
+	return envValue === undefined || envValue === "" ? undefined : envValue
+}
+
+/**
+ * Validate a prospective config-file body (used by the dashboard settings
+ * endpoint so a malformed save is rejected server-side instead of writing
+ * garbage that later throws when a worker reads it). Throws on invalid input;
+ * a `{...}` object of string values always passes.
+ */
+export function validateModeModelsBody(body: unknown): asserts body is ModeModelsFile {
+	if (body === null || typeof body !== "object" || Array.isArray(body)) {
+		throw new Error("mode-models: body must be a JSON object of mode slug -> model id strings")
+	}
+	for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+		if (typeof value !== "string") {
+			throw new Error(
+				`mode-models: entry '${key}' must be a string model id, got ${JSON.stringify(value)}`,
+			)
+		}
+	}
+}
+
+/** Pretty-printed canonical serialization for the settings file. */
+export function stringifyModeModelsFile(file: ModeModelsFile): string {
+	return JSON.stringify(file, null, 2) + "\n"
+}