@orquentra/codebuddy 2.14.0 → 2.15.0

package/ARCHITECTURE.md

@@ -113,6 +113,104 @@ Rationale:
 
 - better to return slightly stale ranking than block on Hugging Face cold starts or rate limits
 
+## Local LLM and Intent Cards (2.15)
+
+**Runtime: node-llama-cpp.** The local small model (Qwen3-0.6B Q4_K_M by
+default; Qwen3-1.7B as `better`; Qwen only) runs through
+node-llama-cpp 3.22 (llama.cpp bindings). It was compared with Cactus on the
+four criteria in the 2.15 brief:
+
+| | node-llama-cpp 3.22.3 | Cactus |
+|---|---|---|
+| Install size | 41 MB package + one prebuilt binary (19 MB mac-arm64-metal, 33–34 MB x64) | npm ships `cactus-react-native` (152 MB, mobile) and `cactus-needle` (tool-calling model only) |
+| Cold start (M-series, Qwen3-0.6B) | 441 ms load, measured | no Node server binding to measure |
+| Tokens/s (M-series, Metal) | 100–200 tok/s measured; ~2 s per card incl. JSON grammar | n/a |
+| Prebuilt targets | macOS arm64/x64, Linux x64/arm64, Windows x64 (+CUDA/Vulkan) | iOS/Android focus |
+
+Cactus has no maintained Node.js binding for a desktop/server process, and its
+Node package hosts only the Needle tool-calling model, which the brief excludes
+(the job is plain English → code vocabulary, not tool selection). So
+node-llama-cpp. It is not a package dependency: `codebuddy use` (or
+`codebuddy models add local-llm`) installs it with `npm -g` and downloads the pinned GGUF into
+`~/.cache/codebuddy/models/gguf/`, checking size and sha256 before moving it
+into place. Forcing `gpu: false` on macOS makes node-llama-cpp compile llama.cpp
+from source (34 s first load), so the backend uses `gpu: "auto"` (Metal on Apple
+Silicon, CPU elsewhere) with `threads` capped at cores − 1
+(`CODEBUDDY_LLM_THREADS` overrides).
+
+**Where it runs.** Generation happens on llama.cpp's native threads inside
+`codebuddy serve` (background project sync) or `codebuddy index --cards`, never
+on a request path except the bounded query expansion below. A single context
+sequence serialises calls. Hooks and MCP tool calls touch
+`.codebuddy/cache/foreground`; the card and fact passes wait (up to 15 s) while
+it is fresher than 2 s. Output is constrained by a JSON-schema grammar with
+`maxItems`/`maxLength` bounds (without them the 0.6B model writes paragraphs
+until the token cap cuts the JSON), then validated with zod; invalid output is
+retried once, then the file is skipped.
+
+**Lifetime.** The model is loaded on demand and unloaded `IDLE_UNLOAD_MS`
+(60 s) after its last generation; measured on Qwen3-0.6B, resident memory went
+from 1,274 MB to 452 MB (the rest is the llama.cpp/Metal runtime, freed when
+the process exits). `serve` frees it on shutdown, and the detached
+`index --cards` that setup starts exits when its pass ends. Setup skips the
+local model on machines under 4 GB RAM or with one core (`machineCanCard`) and
+uses cloud Qwen there when a key is set.
+
+**Model size.** The same four-file card test with the grammar bounds:
+SmolLM2-135M Q4_K_M (105 MB) wrote `...` summaries and raw code lines as
+symptoms; Gemma 3 270M Q4_K_M (253 MB) wrote one-word summaries and term lists
+as symptoms; Qwen3-0.6B Q4_K_M (397 MB) wrote usable summaries and symptoms.
+So CodeBuddy ships Qwen only. A machine below `machineCanCard` gets Qwen from
+the cloud instead (BYOK: `qwen/qwen3.8-27b` on Groq or OpenRouter, sent with
+`reasoning_effort: "none"`; `<think>` blocks are stripped), configured by
+setup only when a provider key is already in the environment.
+
+**Cards** extend the existing `llm-summaries.json` store (prompt version 2), so
+the BYOK and local backends fill the same cache. Each card is used three ways:
+a card vector per file in `file-vectors.json` (granite, next to the chunk
+vectors), one Markdown file per source file in `.codebuddy/cache/cards/`, which
+is its own zvec-grep workspace (English model `local/bge-small-en-v1.5`,
+`--no-ignore`, so the project's ignore rules never hide it), and card terms and
+symptoms in the content index at half weight.
+
+**Agreement rule** (`context/discovery.ts`). 2.14 dropped every vector hit
+outside the keyword set unless it shared task terms with the source and cleared
+`zvec.minScore`. That deleted exactly the hits a reworded task needs. In 2.15 a
+candidate is admitted when at least two signals put it in their top k (default
+5): zvec-grep (code and card workspaces fused), the source-chunk vector, the
+card vector, and the old term-overlap rule as one more vote. Every ranking has
+a top k even for an unrelated task, so a vector vote also needs its cosine at
+or above a floor (`chunkFloor` 0.80, `cardFloor` 0.75). zg prints no
+similarity, so its vote is rank-only, and two rank-only votes never agree.
+Abstention returns nothing only when no candidate passes the rule and keyword
+evidence is below the floor. Card text alone never admits a file; card
+evidence counts when another signal agrees. The floors are uncalibrated
+defaults. Tune them in `.codebuddy/config.json` under `discovery.agreement`
+against the unrelated-task files (the 6 in the Litestar harness plus
+`evals/unrelated-2.15.json`).
+
+**Confidence.** Discovery returns `high` (anchor, exact identifier, CLI
+command, or ≥ 3 votes counting a strong keyword match as two), `medium` (two),
+or `low` (dense signals present but no returned file has two). `low` returns no
+paths: the hook emits nothing, and `context_pack` adds a note telling the agent
+to search normally. Without any dense signal the result is 2.14's keyword path
+and is never suppressed.
+
+**Expansion.** When a task found nothing confident and names no identifier,
+discovery asks the warm local model for 5–8 code terms (≤ 800 ms in
+`context_pack`, ≤ 300 ms in the hook) and ranks once more. Answers are cached
+per normalised task in `.codebuddy/cache/expansions.json` (LRU, 200). The hook
+process never has a warm model, so it only benefits from cached expansions.
+
+**Index facts** (`llm/index-facts.ts`) are Markdown facts with
+`createdByAgent: codebuddy-index`, `paths: [source]`,
+`verification: ["source:Lline"]` and an `index:` idempotency key.
+Manifest and CI facts are read deterministically. Prose facts come from the
+model and must share words with the cited line and read as a statement.
+Sensitive candidates are dropped. Re-extraction replaces only index facts
+whose source hash changed. The cap is 40 per repository, and near-duplicates
+(Jaccard ≥ 0.8) of any existing fact are skipped.
+
 ## Sharing Model
 
 Shares are references by default.

package/README.md

@@ -1,11 +1,18 @@
-# CodeBuddy
+# CodeBuddy by Orquentra
 
 Local-first project context and memory for AI coding agents.
 
+Published by Orquentra as
+[`@orquentra/codebuddy` on npm](https://www.npmjs.com/package/@orquentra/codebuddy).
+
 CodeBuddy helps agents find relevant code, understand project constraints, and
 remember decisions across sessions. It works through MCP with Claude Code,
 Codex, OpenCode, Hermes, and other compatible clients.
 
+[npm package](https://www.npmjs.com/package/@orquentra/codebuddy) ·
+[Documentation](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/guide.md) ·
+[Source and issues](https://github.com/Orquentra-Inc/CodeBuddy)
+
 ## Install
 
 Requires Node.js 20 or later.
@@ -16,9 +23,12 @@ cd your-project
 codebuddy
 ```
 
-The setup wizard configures the project and agent integration. Project context
-works without a database; semantic memory recall optionally uses PostgreSQL
-with pgvector and a local Hugging Face embedding model (no token needed).
+That one command sets everything up: PostgreSQL (the bundled Docker database
+if none is running), the local embedding model (~90 MB), zvec-grep (installed
+and indexed), the local Qwen model (~400 MB; cloud Qwen with a key you enter on
+machines under 4 GB RAM), agent wiring for Claude and Codex, and a background
+pass that builds file vectors, intent cards and project facts. Skip pieces with
+`--no-local-llm`, `--no-graphify` or `--no-docker`.
 
 Run setup inside the project you want CodeBuddy to read. Claude Desktop
 registration saves that folder's absolute path, so restarting the desktop app
@@ -28,13 +38,27 @@ Older desktop registrations without a project path can be repaired by running
 `codebuddy claude install` from the initialized project folder, then restarting
 Claude Desktop.
 
+### Verify the package
+
+The npm package name is **`@orquentra/codebuddy`**; the installed command is
+**`codebuddy`**. Open the [npm package page](https://www.npmjs.com/package/@orquentra/codebuddy)
+directly to find its published versions, or query the public registry:
+
+```bash
+npm view @orquentra/codebuddy version --registry=https://registry.npmjs.org/
+```
+
+Search engine results and AI summaries may lag behind npm releases. If an
+installation fails, include the exact npm error and requested version in a
+[GitHub issue](https://github.com/Orquentra-Inc/CodeBuddy/issues).
+
 ## What it does
 
 - **Task context:** relevant files, symbols, code excerpts, nearby dependencies,
   and covering tests within a token budget.
 - **Project memory:** decisions, rules, and handoffs stored as readable Markdown,
   recalled for relevant tasks by hybrid lexical + vector search
-  ([how it works](docs/semantic-memory.md)).
+  ([how it works](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/semantic-memory.md)).
 - **Continuity:** a local journal of each session's goal, edits, checks and
   findings, re-injected after compaction and offered to the next session when
   a task was left unfinished. Native bridges cover Claude Code, Codex, OpenCode
@@ -50,6 +74,63 @@ Claude Desktop.
 - **Optional retrieval:** zvec semantic search, Graphify architecture maps, and
   a bring-your-own LLM layer.
 
+## Optional local LLM (2.15)
+
+A small local model can write a plain-English **intent card** for every source
+file, so a task worded nothing like the code (for example "the browser forgets
+how long to wait before reconnecting") still finds the right file. `codebuddy`
+/ `codebuddy use` installs it as part of setup (Qwen3-0.6B Q4_K_M, ~400 MB,
+checksum-verified; skip with `--no-local-llm` or `CODEBUDDY_LOCAL_LLM=0`), and it
+runs offline after that. To manage it by hand:
+
+```bash
+codebuddy models add local-llm            # Qwen3-0.6B Q4_K_M, ~400 MB, checksum-verified
+codebuddy models add local-llm --size better   # Qwen3-1.7B, ~1.1 GB
+codebuddy models remove local-llm         # back to keyword + vector discovery
+```
+
+Setup also installs the runtime (`node-llama-cpp`, prebuilt for macOS, Linux
+and Windows; `models add` asks first). CodeBuddy uses Qwen only. On a machine
+under 4 GB of RAM or with one CPU core, setup uses Qwen in the cloud instead
+(`qwen/qwen3.8-27b` on Groq, free-tier key; or OpenRouter). It uses
+`GROQ_API_KEY` / `OPENROUTER_API_KEY` from the environment, or asks for a Groq
+key (free at console.groq.com/keys) and saves it in `~/.codebuddy/global.json`
+(mode 0600, never in the project). Bounded, redacted file heads and
+signatures are then sent to that provider ([details](docs/llm-byok.md)). Skip
+the prompt and keyword + vector discovery keep working.
+The model runs inside `codebuddy serve` (not in Docker; Docker only hosts
+PostgreSQL). It is unloaded 60 s after its last card and freed when the agent
+closes `serve`, so it never keeps running in the background.
+
+Qwen3-0.6B is the smallest model that wrote usable cards in our checks:
+SmolLM2-135M (105 MB) returned placeholders and raw code lines, and Gemma 3
+270M returned keyword lists instead of descriptions, so neither ships.
+Nothing leaves your machine, and without the model every feature falls back to
+the 2.14 behaviour.
+
+- **Intent cards:** a summary, 3–6 "symptoms" in bug-report wording, the code
+  terms to search for, and a line per main symbol. Written in the background by
+  `codebuddy serve` (or `codebuddy index --cards`) for new and changed source
+  files only; tests, docs, generated, vendored and secret-bearing files are
+  skipped. Cards feed a second vector per file, a zvec-grep card workspace, and
+  (down-weighted) the keyword index. Progress: `codebuddy models`, `codebuddy
+  storage`.
+- **Agreement rule:** a file the keywords missed is admitted when two
+  independent signals agree (zvec-grep, source-chunk vectors, card vectors,
+  term overlap). When no returned file has two, CodeBuddy says so instead of
+  guessing: `context_pack` returns `confidence: "low"` with a note to search
+  normally, and the prompt hook stays silent.
+- **Index facts:** up to 40 project facts drawn from `package.json`,
+  `pyproject.toml`, CI workflows, README / CONTRIBUTING / AGENTS.md /
+  CLAUDE.md and deprecation or release policies, each with its source line.
+  They are ordinary Markdown facts; `codebuddy memory list --origin index`
+  shows them and `codebuddy memory prune --origin index` removes them. Facts a
+  person or agent wrote are never replaced.
+
+`codebuddy use` also builds the zvec-grep index and enables it when `zg` 0.2.x
+is installed, and `codebuddy serve` keeps a `zg server` running so the prompt
+hook gets vector candidates within its deadline.
+
 ## What it costs
 
 Context is not free: tool schemas, the rules block and the injected context are
@@ -98,7 +179,7 @@ needs more detail. Inspect missing or truncated evidence before editing.
 
 ## Documentation
 
-- [Full guide and examples](https://github.com/Orquentra-Inc/CodeBuddy/blob/348bb7c/README.md)
+- [Full guide and examples](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/guide.md)
 - [Telemetry and the admin panel](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/telemetry.md)
 - [Token budgets](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/token-budgets.md)
 - [Optional LLM setup](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/llm-byok.md)

package/dist/{chunk-LW75SKZR.js → chunk-4BSO3HST.js}

@@ -1,9 +1,9 @@
 import {
   asksForChangelog
-} from "./chunk-YNSTIMCF.js";
+} from "./chunk-UR3DF74I.js";
 import {
   readConfigFile
-} from "./chunk-KNR2P2UY.js";
+} from "./chunk-M75SN4D4.js";
 import {
   writeAtomic
 } from "./chunk-CG5B3LYG.js";
@@ -52,10 +52,10 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
   const config = await zvecConfig(root);
   if (!config.enabled) return none("disabled", "zvec-grep not enabled");
   const { deadlineAt } = options;
-  const run = (args) => {
+  const run = (args, cwd = root) => {
     const ms = deadlineAt === void 0 ? config.timeoutMs : Math.min(config.timeoutMs, deadlineAt - Date.now());
-    if (ms <= 0) return Promise.resolve({ stdout: "", error: deadlineError() });
-    return runZg(config.binary, args, root, ms);
+    if (ms <= 0) return Promise.resolve({ stdout: "", stderr: "", error: deadlineError() });
+    return runZg(config.binary, args, cwd, ms);
   };
   const missedDeadline = (status) => deadlineAt !== void 0 && status === "timeout" && Date.now() >= deadlineAt - 5;
   const cached = await readCachedReadiness(root, config.binary);
@@ -73,7 +73,7 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
   const limit = Math.min(20, Math.max(1, Math.floor(options.limit ?? 10)));
   const chunkLimit = limit * 8;
   const globs = zvecExcludeGlobs(task);
-  const result = await run([
+  const query = [
     "query",
     "--vector",
     task,
@@ -84,13 +84,20 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
     "--limit",
     String(chunkLimit),
     ...globs.flatMap((glob) => ["-g", glob])
-  ]);
+  ];
+  const cardQuery = queryCards(root, task, limit, (args, cwd) => run(args, cwd));
+  let result = await run(query);
+  if (result.error && isBusy(result) && (deadlineAt === void 0 || deadlineAt - Date.now() > 400)) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, BUSY_RETRY_MS));
+    result = await run(query);
+  }
   if (result.error) {
-    const failure = fromError(result.error, "zvec-grep query");
-    if (!missedDeadline(failure.status)) await resetZvecCache(root);
+    const failure = fromError(result.error, "zvec-grep query", result.stderr);
+    if (!missedDeadline(failure.status) && failure.status !== "busy") await resetZvecCache(root);
     return failure;
   }
   const hits = parseHits(result.stdout).slice(0, chunkLimit);
+  const cardPaths = await cardQuery;
   if (hits.length === 0 && /\bzg index\b/.test(result.stdout)) {
     const notReady = none("index-not-ready", NOT_READY);
     await markReadiness(root, config.binary, notReady);
@@ -133,7 +140,8 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
     stale,
     changed,
     minScore: config.minScore,
-    reason: `zvec-grep vector search: ${paths.length} file(s)` + (globs.length > 0 ? "; non-source paths excluded" : "") + (stale > 0 ? `, ${stale} stale hit(s) dropped` : "") + (changed > 0 ? `, ${changed} hit(s) changed since the zg index dropped` : "") + (indexedAt === null ? "; index age unknown, hits unverified (run `codebuddy zvec index`)" : "")
+    ...cardPaths.length > 0 ? { cardPaths } : {},
+    reason: `zvec-grep vector search: ${paths.length} file(s)` + (globs.length > 0 ? "; non-source paths excluded" : "") + (stale > 0 ? `, ${stale} stale hit(s) dropped` : "") + (changed > 0 ? `, ${changed} hit(s) changed since the zg index dropped` : "") + (cardPaths.length > 0 ? `; ${cardPaths.length} intent card match(es)` : "") + (indexedAt === null ? "; index age unknown, hits unverified (run `codebuddy zvec index`)" : "")
   };
 }
 async function refreshZvecIndex(repositoryRoot, options = {}) {
@@ -229,6 +237,90 @@ async function buildZvecIndex(repositoryRoot, options = {}) {
   return code;
 }
 var NOT_READY = "zvec-grep index missing or not ready; run `codebuddy zvec index`";
+var CARDS_DIR = join(".codebuddy", "cache", "cards");
+var DEFAULT_CARD_MODEL = "local/bge-small-en-v1.5";
+async function queryCards(root, task, limit, run) {
+  const cards = join(root, CARDS_DIR);
+  if (!await stat(join(cards, ".zvec-grep")).catch(() => null)) return [];
+  const result = await run(
+    ["query", "--vector", task, "--mode", "auto", "--refresh", "off", "--limit", String(limit)],
+    cards
+  );
+  if (result.error) return [];
+  const paths = [];
+  for (const hit of parseHits(result.stdout)) {
+    const card = toRepoRelative(cards, hit.path);
+    if (!card?.endsWith(".md")) continue;
+    const path = card.slice(0, -3);
+    if (paths.includes(path)) continue;
+    if (!(await stat(resolve(root, path)).catch(() => null))?.isFile()) continue;
+    paths.push(path);
+  }
+  return paths.slice(0, limit);
+}
+async function refreshZvecCardIndex(repositoryRoot, options = {}) {
+  const root = resolve(repositoryRoot);
+  const config = await zvecConfig(root);
+  if (!config.enabled) return { status: "disabled", reason: "zvec-grep not enabled" };
+  const cards = join(root, CARDS_DIR);
+  if (!await stat(cards).catch(() => null))
+    return { status: "ok", reason: "no intent cards yet" };
+  const exists = await stat(join(cards, ".zvec-grep")).catch(() => null);
+  const result = await runZg(
+    config.binary,
+    [
+      "index",
+      cards,
+      ...exists ? [] : ["--embedding", config.cardModel],
+      "--no-ignore",
+      "--mode",
+      "auto"
+    ],
+    cards,
+    REFRESH_TIMEOUT_MS,
+    options.signal
+  );
+  if (result.error) {
+    const failure = fromError(result.error, "zvec-grep card index", result.stderr);
+    return { status: failure.status, reason: failure.reason };
+  }
+  await writeFile(join(cards, ".zvec-grep", ".gitignore"), "*\n", { flag: "wx" }).catch(() => {
+  });
+  return { status: "ok", reason: "zvec-grep card index refreshed" };
+}
+async function ensureZvecServer(repositoryRoot) {
+  const root = resolve(repositoryRoot);
+  const config = await zvecConfig(root);
+  const noop = async () => {
+  };
+  if (!config.enabled) return { started: false, reason: "zvec-grep not enabled", stop: noop };
+  const run = (args) => runZg(config.binary, args, root, Math.max(config.timeoutMs, 5e3));
+  const readiness = await checkReadiness(run);
+  if (readiness) return { started: false, reason: readiness.reason, stop: noop };
+  const status = await run(["server", "status"]);
+  if (!status.error && /^Server: ready\b/m.test(status.stdout)) {
+    return { started: false, reason: "zg server already running (reused)", stop: noop };
+  }
+  const on = await run(["server", "on"]);
+  await rm(serverPath(root), { force: true });
+  if (on.error) {
+    return {
+      started: false,
+      reason: fromError(on.error, "zg server on", on.stderr).reason,
+      stop: noop
+    };
+  }
+  return {
+    started: true,
+    reason: "zg server started",
+    // ponytail: the daemon is shared; a second `codebuddy serve` that reused it
+    // loses vectors when this one exits. Refcount via ZVEC_GREP_HOME if that matters.
+    stop: async () => {
+      await runZg(config.binary, ["server", "off"], root, 5e3);
+      await rm(serverPath(root), { force: true });
+    }
+  };
+}
 async function checkReadiness(run) {
   const version = await run(["version"]);
   if (version.error) return fromError(version.error, "zvec-grep version check");
@@ -306,7 +398,8 @@ async function zvecConfig(root) {
     enabled: env !== void 0 ? env === "1" || env === "true" : file.zvec?.enabled ?? false,
     binary: file.zvec?.binary ?? "zg",
     timeoutMs: file.zvec?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    minScore: file.zvec?.minScore ?? DEFAULT_ZVEC_MIN_SCORE
+    minScore: file.zvec?.minScore ?? DEFAULT_ZVEC_MIN_SCORE,
+    cardModel: file.zvec?.cardModel ?? DEFAULT_CARD_MODEL
   };
 }
 function runZg(binary, args, cwd, timeoutMs, signal) {
@@ -321,12 +414,16 @@ function runZg(binary, args, cwd, timeoutMs, signal) {
         killSignal: "SIGKILL",
         ...signal ? { signal } : {}
       },
-      (error, stdout) => {
+      (error, stdout, stderr) => {
         if (error && error.killed) {
-          resolveRun({ stdout: "", error: Object.assign(error, { code: "ETIMEDOUT" }) });
+          resolveRun({
+            stdout: "",
+            stderr: String(stderr),
+            error: Object.assign(error, { code: "ETIMEDOUT" })
+          });
           return;
         }
-        resolveRun({ stdout: String(stdout), error });
+        resolveRun({ stdout: String(stdout), stderr: String(stderr), error });
       }
     );
   });
@@ -360,10 +457,17 @@ async function serverRunning(root, binary, run) {
   }
   return running;
 }
-function fromError(error, what) {
+function fromError(error, what, stderr = "") {
   if (error.code === "ENOENT") return none("not-installed", "zvec-grep (`zg`) not found on PATH");
   if (error.code === "ETIMEDOUT") return none("timeout", `${what} timed out`);
-  return none("failed", `${what} failed`);
+  if (BUSY.test(stderr)) return none("busy", `${what}: index busy (a zg index refresh is running)`);
+  const code = stderr.match(/\bCode:\s*(\S+)/)?.[1];
+  return none("failed", `${what} failed${code ? ` (${code})` : ""}`);
+}
+var BUSY = /ZVEC_GREP\.ENGINE\.LOCK\.BUSY/;
+var BUSY_RETRY_MS = 150;
+function isBusy(result) {
+  return BUSY.test(result.stderr);
 }
 function none(status, reason) {
   return { status, paths: [], hits: [], reason, stale: 0, changed: 0 };
@@ -384,6 +488,10 @@ export {
   parseHits,
   resetZvecCache,
   zvecStatus,
-  buildZvecIndex
+  buildZvecIndex,
+  CARDS_DIR,
+  DEFAULT_CARD_MODEL,
+  refreshZvecCardIndex,
+  ensureZvecServer
 };
-//# sourceMappingURL=chunk-LW75SKZR.js.map
+//# sourceMappingURL=chunk-4BSO3HST.js.map

package/dist/chunk-4BSO3HST.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retrieval/zvec.ts"],"sourcesContent":["import { execFile, spawn } from \"node:child_process\";\nimport { mkdir, readFile, rm, stat, writeFile } from \"node:fs/promises\";\nimport { dirname, isAbsolute, join, relative, resolve, sep } from \"node:path\";\nimport { asksForChangelog } from \"../context/discovery.js\";\nimport { readConfigFile } from \"../core/config-file.js\";\nimport { writeAtomic } from \"../core/markdown-store-fs.js\";\n\n/**\n * Optional semantic candidate source backed by zvec-grep (`zg`), a local\n * code-search CLI. It only *suggests* files: hits are normalized to\n * repository-relative paths, checked against the working tree, and fused with\n * the keyword ranking by the caller. Risk, policy and incident evidence are\n * never derived from it.\n *\n * Off unless `.codebuddy/config.json` sets `zvec.enabled` (or\n * `CODEBUDDY_ZVEC=1`). It never builds an index implicitly: an unready index,\n * a missing or unsupported binary, a timeout, or unparseable output all return\n * no candidates plus a reason, and callers fall back to keyword ranking.\n *\n * Queries exclude non-source paths (docs, Markdown, evals, scripts, tests,\n * CodeBuddy's own state) unless the task asks about them: otherwise prose that\n * quotes a task, such as audits or eval prompts, outranks the code it describes.\n *\n * Benchmarked: vector-only queries beat zg's default hybrid route on code\n * tasks, so only `--vector` is used. Results are parsed from zg's agent\n * markdown (`#N matchedBy=… path:start-end`), as 0.2.x has no JSON output.\n *\n * Queries use `--mode auto`: a running `zg server` answers in ~200ms, otherwise\n * zg searches directly (~400ms). Auto mode never starts the daemon. The\n * version/readiness check (~400ms) is cached on disk for a few minutes so the\n * per-prompt hook process doesn't repeat it. A failed check (not installed,\n * index not ready, timeout) is cached too, but only for 30 s and only until the\n * workspace's `.zvec-grep/` changes, so an unready index costs one probe per\n * window instead of one per call while a fresh `zg index` is still picked up.\n *\n * Freshness: queries keep `--refresh off` so the prompt path never waits on\n * embedding. Instead `refreshZvecIndex` (run by project sync after index\n * passes, off the request path) and `codebuddy zvec index` record when the zg\n * index was last brought up to date, and hits whose file changed after that are\n * dropped rather than presented with their old meaning.\n */\n\n/** zvec-grep versions whose CLI and output format this adapter was tested against. */\nconst SUPPORTED = /^0\\.2\\.\\d+$/;\nconst DEFAULT_TIMEOUT_MS = 1_500;\nconst READY_CACHE_MS = 10 * 60_000;\n/** A failed readiness check is reused this long, so a fresh `zg index` is noticed quickly. */\nconst NOT_READY_CACHE_MS = 30_000;\n/** An incremental `zg index` runs in the background; only a runaway is killed. */\nconst REFRESH_TIMEOUT_MS = 10 * 60_000;\n/** Small, fast local model; indexes this repo in seconds. */\nexport const DEFAULT_ZVEC_MODEL = \"local/potion-code-16m-v2\";\n/**\n * Default `zvec.minScore`: a vector-only file must cover this share of the\n * task's IDF mass in its current source. zg 0.2.x prints no similarity (its\n * `--trace` score is 1/(60+rank)), so the floor is CodeBuddy's own measure. 0.3\n * is the content gate's value (`MIN_IDF_COVERAGE`), not calibrated on vector\n * hits: see docs/zvec-floor.md to calibrate it.\n */\nexport const DEFAULT_ZVEC_MIN_SCORE = 0.3;\nconst DOC_GLOBS = [\"!**/*.md\", \"!**/*.mdx\", \"!**/*.rst\", \"!**/*.adoc\", \"!docs/**\"];\n/** zg globs are case-sensitive: the usual spellings of changelogs and release notes. */\nconst CHANGELOG_GLOBS = [\n  \"!**/CHANGES*\",\n  \"!**/CHANGELOG*\",\n  \"!**/HISTORY*\",\n  \"!**/NEWS*\",\n  \"!**/RELEASE*\",\n  \"!**/changelog*\",\n  \"!**/Changelog*\",\n  \"!**/ChangeLog*\",\n];\nconst TEST_GLOBS = [\n  \"!**/*.test.*\",\n  \"!**/*.spec.*\",\n  \"!**/__tests__/**\",\n  \"!**/test/**\",\n  \"!**/tests/**\",\n];\nconst ALWAYS_EXCLUDED_GLOBS = [\"!evals/**\", \"!scripts/**\", \"!.codebuddy/**\", \"!**/fixtures/**\"];\n\n/** zg `-g` exclusions for a task: docs and tests stay searchable when the task names them. */\nexport function zvecExcludeGlobs(task: string): string[] {\n  return [\n    ...(/\\b(docs?|readme|documentation|markdown)\\b/i.test(task) ? [] : DOC_GLOBS),\n    ...(/\\b(tests?|spec)\\b/i.test(task) ? [] : TEST_GLOBS),\n    ...(asksForChangelog(task) ? [] : CHANGELOG_GLOBS),\n    ...ALWAYS_EXCLUDED_GLOBS,\n  ];\n}\n\nconst EXCLUDED_PREFIXES = [\".codebuddy/cache/\", \".zvec-grep/\", \".git/\", \"node_modules/\"];\n\nexport type ZvecStatus =\n  | \"ok\"\n  | \"disabled\"\n  | \"not-installed\"\n  | \"unsupported-version\"\n  | \"index-not-ready\"\n  | \"timeout\"\n  | \"failed\"\n  | \"no-server\"\n  /** Another zg process (a background `zg index`) holds the index lock. */\n  | \"busy\";\n\n/** zg provides no content hash: a valid range alone cannot prove index freshness. */\nexport type RetrievalHit = {\n  path: string;\n  startLine: number;\n  endLine: number;\n  rank: number;\n  /** `anchor`: a line the task itself names (path:line, stack frame, error string). */\n  source: \"zvec\" | \"anchor\";\n  freshness: \"unverified\";\n};\n\nexport type ZvecCandidates = {\n  status: ZvecStatus;\n  /** Repo-relative paths of existing files, best first. */\n  paths: string[];\n  /** Every chunk hit inside `paths`, in rank order (several per file). */\n  hits: RetrievalHit[];\n  reason: string;\n  /** Hits dropped because the file no longer exists (stale index). */\n  stale: number;\n  /** Hits dropped because the file changed after the zg index was refreshed. */\n  changed: number;\n  /** `zvec.minScore` for vector-only files; set on every `ok` result. */\n  minScore?: number;\n  /**\n   * Source paths whose intent card (`.codebuddy/cache/cards/<path>.md`, written\n   * by the card pass) matched the task in the card workspace, best first.\n   * Paths only: a card's line ranges say nothing about its source file.\n   */\n  cardPaths?: string[];\n};\n\nexport async function zvecCandidates(\n  repositoryRoot: string,\n  task: string,\n  options: {\n    limit?: number;\n    /**\n     * Hard stop (epoch ms) for every zg call: each one is killed at the\n     * deadline and the caller falls back to keyword ranking. A miss is not\n     * cached, so a slow prompt does not turn zvec off for the next one.\n     */\n    deadlineAt?: number;\n    /** Query only while a `zg server` is running (checked at most every 30 s). */\n    requireServer?: boolean;\n  } = {},\n): Promise<ZvecCandidates> {\n  const root = resolve(repositoryRoot);\n  const config = await zvecConfig(root);\n  if (!config.enabled) return none(\"disabled\", \"zvec-grep not enabled\");\n  const { deadlineAt } = options;\n  const run = (args: string[], cwd = root): Promise<RunResult> => {\n    const ms =\n      deadlineAt === undefined\n        ? config.timeoutMs\n        : Math.min(config.timeoutMs, deadlineAt - Date.now());\n    if (ms <= 0) return Promise.resolve({ stdout: \"\", stderr: \"\", error: deadlineError() });\n    return runZg(config.binary, args, cwd, ms);\n  };\n  const missedDeadline = (status: ZvecStatus) =>\n    deadlineAt !== undefined && status === \"timeout\" && Date.now() >= deadlineAt - 5;\n\n  const cached = await readCachedReadiness(root, config.binary);\n  if (cached !== \"ready\") {\n    if (cached) return cached;\n    const readiness = await checkReadiness(run);\n    if (!(readiness && missedDeadline(readiness.status))) {\n      await markReadiness(root, config.binary, readiness);\n    }\n    if (readiness) return readiness;\n  }\n  if (options.requireServer && !(await serverRunning(root, config.binary, run))) {\n    return none(\"no-server\", \"no running `zg server` (this path never starts one)\");\n  }\n\n  // zg ranks chunks, and one file can own many of them: oversample chunks so\n  // `limit` distinct files survive de-duplication.\n  const limit = Math.min(20, Math.max(1, Math.floor(options.limit ?? 10)));\n  const chunkLimit = limit * 8;\n  const globs = zvecExcludeGlobs(task);\n  const query = [\n    \"query\",\n    \"--vector\",\n    task,\n    \"--mode\",\n    \"auto\",\n    \"--refresh\",\n    \"off\",\n    \"--limit\",\n    String(chunkLimit),\n    ...globs.flatMap((glob) => [\"-g\", glob]),\n  ];\n  // The card workspace is queried in parallel; it never delays or fails the code query.\n  const cardQuery = queryCards(root, task, limit, (args, cwd) => run(args, cwd));\n  let result = await run(query);\n  // A background `zg index` (project sync) holds the lock for a moment: one retry.\n  if (\n    result.error &&\n    isBusy(result) &&\n    (deadlineAt === undefined || deadlineAt - Date.now() > 400)\n  ) {\n    await new Promise((resolveWait) => setTimeout(resolveWait, BUSY_RETRY_MS));\n    result = await run(query);\n  }\n  if (result.error) {\n    const failure = fromError(result.error, \"zvec-grep query\", result.stderr);\n    if (!missedDeadline(failure.status) && failure.status !== \"busy\") await resetZvecCache(root);\n    return failure;\n  }\n\n  const hits = parseHits(result.stdout).slice(0, chunkLimit);\n  const cardPaths = await cardQuery;\n  // With no index, zg answers with a \"run zg index\" hint instead of hits.\n  if (hits.length === 0 && /\\bzg index\\b/.test(result.stdout)) {\n    const notReady = none(\"index-not-ready\", NOT_READY);\n    await markReadiness(root, config.binary, notReady);\n    return notReady;\n  }\n  const indexedAt = await readIndexedAt(root);\n  const paths: string[] = [];\n  const candidates: RetrievalHit[] = [];\n  const seen = new Set<string>();\n  let stale = 0;\n  let changed = 0;\n  for (const hit of hits) {\n    const path = toRepoRelative(root, hit.path);\n    if (!path) continue;\n    // Later chunks of an accepted file keep their spans; a rejected file stays rejected.\n    if (seen.has(path)) {\n      if (paths.includes(path)) candidates.push({ ...hit, path });\n      continue;\n    }\n    if (paths.length >= limit) continue;\n    seen.add(path);\n    if (EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))) continue;\n    try {\n      const info = await stat(resolve(root, path));\n      if (!info.isFile()) continue;\n      // ctime too: a rename over the path keeps the old mtime.\n      if (indexedAt !== null && Math.max(info.mtimeMs, info.ctimeMs) > indexedAt) {\n        changed++;\n        continue;\n      }\n    } catch {\n      stale++;\n      continue;\n    }\n    paths.push(path);\n    candidates.push({ ...hit, path });\n  }\n  return {\n    status: \"ok\",\n    paths,\n    hits: candidates,\n    stale,\n    changed,\n    minScore: config.minScore,\n    ...(cardPaths.length > 0 ? { cardPaths } : {}),\n    reason:\n      `zvec-grep vector search: ${paths.length} file(s)` +\n      (globs.length > 0 ? \"; non-source paths excluded\" : \"\") +\n      (stale > 0 ? `, ${stale} stale hit(s) dropped` : \"\") +\n      (changed > 0 ? `, ${changed} hit(s) changed since the zg index dropped` : \"\") +\n      (cardPaths.length > 0 ? `; ${cardPaths.length} intent card match(es)` : \"\") +\n      (indexedAt === null\n        ? \"; index age unknown, hits unverified (run `codebuddy zvec index`)\"\n        : \"\"),\n  };\n}\n\nexport type ZvecRefresh = { status: ZvecStatus; reason: string };\n\n/**\n * Incrementally refresh an existing zg index (no `--rebuild`, no embedding\n * flag) and record when it started, which is the freshness bound applied to\n * later hits. Never builds a missing index and never starts a zg server; every\n * failure is returned as a status for the caller to log.\n */\nexport async function refreshZvecIndex(\n  repositoryRoot: string,\n  options: { signal?: AbortSignal } = {},\n): Promise<ZvecRefresh> {\n  const root = resolve(repositoryRoot);\n  const config = await zvecConfig(root);\n  if (!config.enabled) return { status: \"disabled\", reason: \"zvec-grep not enabled\" };\n  const readiness = await checkReadiness((args) =>\n    runZg(config.binary, args, root, config.timeoutMs),\n  );\n  if (readiness) return { status: readiness.status, reason: readiness.reason };\n  const startedAt = Date.now();\n  const result = await runZg(\n    config.binary,\n    [\"index\", root, \"--mode\", \"auto\"],\n    root,\n    REFRESH_TIMEOUT_MS,\n    options.signal,\n  );\n  if (result.error) {\n    const failure = fromError(result.error, \"zvec-grep refresh\");\n    return { status: failure.status, reason: failure.reason };\n  }\n  await markIndexed(root, startedAt);\n  return { status: \"ok\", reason: \"zvec-grep index refreshed\" };\n}\n\n/** Extract bounded, validated line ranges in retrieval rank order. */\nexport function parseHits(output: string): RetrievalHit[] {\n  return [...output.matchAll(/^#(\\d+) matchedBy=\\S+ (.+?):(\\d+)(?:-(\\d+))?\\s*$/gm)]\n    .flatMap((match) => {\n      const rank = Number(match[1]);\n      const startLine = Number(match[3]);\n      const endLine = Number(match[4] ?? match[3]);\n      if (startLine < 1 || endLine < startLine) return [];\n      return [\n        {\n          path: match[2] as string,\n          rank,\n          startLine,\n          endLine,\n          source: \"zvec\" as const,\n          freshness: \"unverified\" as const,\n        },\n      ];\n    })\n    .sort((left, right) => left.rank - right.rank);\n}\n\n/** Forget the cached readiness check, e.g. after `zg index` or a failed query. */\nexport async function resetZvecCache(repositoryRoot: string): Promise<void> {\n  await rm(readyPath(resolve(repositoryRoot)), { force: true });\n}\n\nexport type ZvecReport = {\n  enabled: boolean;\n  binary: string;\n  version: string | null;\n  supported: boolean;\n  indexReady: boolean;\n  server: \"running\" | \"stopped\" | \"unknown\";\n  reason: string;\n};\n\n/** Everything `codebuddy zvec status` shows. Read-only; never builds an index. */\nexport async function zvecStatus(repositoryRoot: string): Promise<ZvecReport> {\n  const root = resolve(repositoryRoot);\n  const config = await zvecConfig(root);\n  const run = (args: string[]) =>\n    runZg(config.binary, args, root, Math.max(config.timeoutMs, 5_000));\n  const version = await run([\"version\"]);\n  const found = version.error ? null : (version.stdout.trim().split(/\\s+/).pop() ?? null);\n  const supported = found !== null && SUPPORTED.test(found);\n  const readiness = supported ? await checkReadiness(run) : null;\n  const server = supported ? await run([\"server\", \"status\"]) : null;\n  return {\n    enabled: config.enabled,\n    binary: config.binary,\n    version: found,\n    supported,\n    indexReady: supported && readiness === null,\n    server:\n      server === null || server.error\n        ? \"unknown\"\n        : /running|ready/i.test(server.stdout)\n          ? \"running\"\n          : \"stopped\",\n    reason: version.error\n      ? fromError(version.error, \"zvec-grep version check\").reason\n      : !supported\n        ? `zvec-grep ${found ?? \"unknown\"} is not 0.2.x`\n        : (readiness?.reason ?? \"ready\"),\n  };\n}\n\n/**\n * Build or incrementally refresh the zg index for this repository, streaming\n * zg's progress. Explicit by design: CodeBuddy never indexes implicitly.\n */\nexport async function buildZvecIndex(\n  repositoryRoot: string,\n  options: {\n    model?: string;\n    rebuild?: boolean /** Discard zg's progress output. */;\n    quiet?: boolean;\n  } = {},\n): Promise<number> {\n  const root = resolve(repositoryRoot);\n  const config = await zvecConfig(root);\n  const args = [\n    \"index\",\n    root,\n    \"--embedding\",\n    options.model ?? DEFAULT_ZVEC_MODEL,\n    \"--mode\",\n    \"auto\",\n  ];\n  if (options.rebuild) args.push(\"--rebuild\");\n  const startedAt = Date.now();\n  const code = await new Promise<number>((resolveRun, reject) => {\n    const child = spawn(config.binary, args, {\n      cwd: root,\n      stdio: options.quiet ? \"ignore\" : \"inherit\",\n    });\n    child.on(\"error\", reject);\n    child.on(\"close\", (exit) => resolveRun(exit ?? 1));\n  });\n  await resetZvecCache(root);\n  if (code === 0) {\n    // zg's index is binary and rebuildable: keep it out of git (and so out of\n    // the uncommitted-file targets) without touching the project's .gitignore.\n    await writeFile(join(root, \".zvec-grep\", \".gitignore\"), \"*\\n\", { flag: \"wx\" }).catch(() => {});\n    await markIndexed(root, startedAt);\n  }\n  return code;\n}\n\nconst NOT_READY = \"zvec-grep index missing or not ready; run `codebuddy zvec index`\";\n\n/**\n * Intent cards live in their own zg workspace (`.codebuddy/cache/cards/`, one\n * Markdown file per source file at `<path>.md`), so the project's ignore rules\n * never hide them and the code index never sees them. Cards are plain English,\n * so they get an English sentence model instead of the code model.\n */\nexport const CARDS_DIR = join(\".codebuddy\", \"cache\", \"cards\");\nexport const DEFAULT_CARD_MODEL = \"local/bge-small-en-v1.5\";\n\n/** Source paths whose card matched the task; empty when there is no card index or it fails. */\nasync function queryCards(\n  root: string,\n  task: string,\n  limit: number,\n  run: (args: string[], cwd: string) => Promise<RunResult>,\n): Promise<string[]> {\n  const cards = join(root, CARDS_DIR);\n  if (!(await stat(join(cards, \".zvec-grep\")).catch(() => null))) return [];\n  const result = await run(\n    [\"query\", \"--vector\", task, \"--mode\", \"auto\", \"--refresh\", \"off\", \"--limit\", String(limit)],\n    cards,\n  );\n  if (result.error) return [];\n  const paths: string[] = [];\n  for (const hit of parseHits(result.stdout)) {\n    const card = toRepoRelative(cards, hit.path);\n    if (!card?.endsWith(\".md\")) continue;\n    const path = card.slice(0, -3);\n    if (paths.includes(path)) continue;\n    if (!(await stat(resolve(root, path)).catch(() => null))?.isFile()) continue;\n    paths.push(path);\n  }\n  return paths.slice(0, limit);\n}\n\n/**\n * Build or refresh the card workspace's zg index (background only: after a\n * card pass). No-op without cards or with zvec off; never throws.\n */\nexport async function refreshZvecCardIndex(\n  repositoryRoot: string,\n  options: { signal?: AbortSignal } = {},\n): Promise<ZvecRefresh> {\n  const root = resolve(repositoryRoot);\n  const config = await zvecConfig(root);\n  if (!config.enabled) return { status: \"disabled\", reason: \"zvec-grep not enabled\" };\n  const cards = join(root, CARDS_DIR);\n  if (!(await stat(cards).catch(() => null)))\n    return { status: \"ok\", reason: \"no intent cards yet\" };\n  const exists = await stat(join(cards, \".zvec-grep\")).catch(() => null);\n  const result = await runZg(\n    config.binary,\n    [\n      \"index\",\n      cards,\n      ...(exists ? [] : [\"--embedding\", config.cardModel]),\n      \"--no-ignore\",\n      \"--mode\",\n      \"auto\",\n    ],\n    cards,\n    REFRESH_TIMEOUT_MS,\n    options.signal,\n  );\n  if (result.error) {\n    const failure = fromError(result.error, \"zvec-grep card index\", result.stderr);\n    return { status: failure.status, reason: failure.reason };\n  }\n  await writeFile(join(cards, \".zvec-grep\", \".gitignore\"), \"*\\n\", { flag: \"wx\" }).catch(() => {});\n  return { status: \"ok\", reason: \"zvec-grep card index refreshed\" };\n}\n\n/**\n * Start the shared `zg server` for this project when it is enabled and ready,\n * so the prompt hook (which only queries a running server) gets vector\n * candidates within its deadline. Returns a stop function that stops the\n * server only if this call started it.\n */\nexport async function ensureZvecServer(repositoryRoot: string): Promise<{\n  started: boolean;\n  reason: string;\n  stop: () => Promise<void>;\n}> {\n  const root = resolve(repositoryRoot);\n  const config = await zvecConfig(root);\n  const noop = async () => {};\n  if (!config.enabled) return { started: false, reason: \"zvec-grep not enabled\", stop: noop };\n  const run = (args: string[]) =>\n    runZg(config.binary, args, root, Math.max(config.timeoutMs, 5_000));\n  const readiness = await checkReadiness(run);\n  if (readiness) return { started: false, reason: readiness.reason, stop: noop };\n  const status = await run([\"server\", \"status\"]);\n  if (!status.error && /^Server: ready\\b/m.test(status.stdout)) {\n    return { started: false, reason: \"zg server already running (reused)\", stop: noop };\n  }\n  const on = await run([\"server\", \"on\"]);\n  // The hook's 30 s server-status cache would otherwise keep saying \"stopped\".\n  await rm(serverPath(root), { force: true });\n  if (on.error) {\n    return {\n      started: false,\n      reason: fromError(on.error, \"zg server on\", on.stderr).reason,\n      stop: noop,\n    };\n  }\n  return {\n    started: true,\n    reason: \"zg server started\",\n    // ponytail: the daemon is shared; a second `codebuddy serve` that reused it\n    // loses vectors when this one exits. Refcount via ZVEC_GREP_HOME if that matters.\n    stop: async () => {\n      await runZg(config.binary, [\"server\", \"off\"], root, 5_000);\n      await rm(serverPath(root), { force: true });\n    },\n  };\n}\n\n/** Version + index readiness. Returns null when ready, else the failure. */\nasync function checkReadiness(\n  run: (args: string[]) => Promise<RunResult>,\n): Promise<ZvecCandidates | null> {\n  const version = await run([\"version\"]);\n  if (version.error) return fromError(version.error, \"zvec-grep version check\");\n  const found = version.stdout.trim().split(/\\s+/).pop() ?? \"\";\n  if (!SUPPORTED.test(found)) {\n    return none(\"unsupported-version\", `zvec-grep ${found || \"unknown\"} is not 0.2.x`);\n  }\n  const ready = await run([\"status\", \"--check-ready\", \"--mode\", \"auto\"]);\n  if (!ready.error) return null;\n  return ready.error.code === \"ETIMEDOUT\"\n    ? none(\"timeout\", \"zvec-grep status timed out\")\n    : none(\"index-not-ready\", NOT_READY);\n}\n\nfunction readyPath(root: string): string {\n  return join(root, \".codebuddy\", \"cache\", \"zvec-ready.json\");\n}\n\ntype CachedReadiness = {\n  binary?: string;\n  checkedAt?: string;\n  /** Absent in caches written before failures were cached: those were always ready. */\n  failure?: { status: ZvecStatus; reason: string };\n};\n\n/**\n * \"ready\", a cached failure (reason marked as cached), or null when the check\n * must run. A failure is dropped once `.zvec-grep/` changed after it was\n * recorded, i.e. someone (re)built the index outside CodeBuddy.\n */\nasync function readCachedReadiness(\n  root: string,\n  binary: string,\n): Promise<\"ready\" | ZvecCandidates | null> {\n  let cached: CachedReadiness;\n  try {\n    cached = JSON.parse(await readFile(readyPath(root), \"utf8\")) as CachedReadiness;\n  } catch {\n    return null;\n  }\n  const checkedAt = Date.parse(cached.checkedAt ?? \"\");\n  const age = Date.now() - checkedAt;\n  if (cached.binary !== binary || !(age >= 0)) return null;\n  if (!cached.failure) return age <= READY_CACHE_MS ? \"ready\" : null;\n  if (age > NOT_READY_CACHE_MS) return null;\n  const workspace = await stat(join(root, \".zvec-grep\")).catch(() => null);\n  if (workspace && workspace.mtimeMs > checkedAt) return null;\n  const { status, reason } = cached.failure;\n  return none(status, `${reason}; cached check from ${Math.round(age / 1000)}s ago`);\n}\n\n/** Cache a readiness result: null = ready. */\nasync function markReadiness(\n  root: string,\n  binary: string,\n  failure: ZvecCandidates | null,\n): Promise<void> {\n  try {\n    const path = readyPath(root);\n    await mkdir(dirname(path), { recursive: true, mode: 0o700 });\n    const record: CachedReadiness = {\n      binary,\n      checkedAt: new Date().toISOString(),\n      ...(failure ? { failure: { status: failure.status, reason: failure.reason } } : {}),\n    };\n    await writeAtomic(path, `${JSON.stringify(record)}\\n`);\n  } catch {\n    // A read-only cache only costs a repeated readiness check.\n  }\n}\n\nfunction indexedPath(root: string): string {\n  return join(root, \".codebuddy\", \"cache\", \"zvec-index.json\");\n}\n\n/** When the zg index was last refreshed by CodeBuddy, or null if unknown. */\nasync function readIndexedAt(root: string): Promise<number | null> {\n  try {\n    const parsed = JSON.parse(await readFile(indexedPath(root), \"utf8\")) as { indexedAt?: string };\n    const at = Date.parse(parsed.indexedAt ?? \"\");\n    return Number.isFinite(at) ? at : null;\n  } catch {\n    return null;\n  }\n}\n\nasync function markIndexed(root: string, at: number): Promise<void> {\n  try {\n    const path = indexedPath(root);\n    await mkdir(dirname(path), { recursive: true, mode: 0o700 });\n    await writeAtomic(path, `${JSON.stringify({ indexedAt: new Date(at).toISOString() })}\\n`);\n  } catch {\n    // Without the record, later hits are reported as unverified, not trusted.\n  }\n}\n\nasync function zvecConfig(root: string): Promise<{\n  enabled: boolean;\n  binary: string;\n  timeoutMs: number;\n  minScore: number;\n  cardModel: string;\n}> {\n  let file: Awaited<ReturnType<typeof readConfigFile>> = {};\n  try {\n    file = await readConfigFile(root);\n  } catch {\n    // A broken config must not break context assembly; treat zvec as disabled.\n  }\n  const env = process.env.CODEBUDDY_ZVEC;\n  return {\n    enabled: env !== undefined ? env === \"1\" || env === \"true\" : (file.zvec?.enabled ?? false),\n    binary: file.zvec?.binary ?? \"zg\",\n    timeoutMs: file.zvec?.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    minScore: file.zvec?.minScore ?? DEFAULT_ZVEC_MIN_SCORE,\n    cardModel: file.zvec?.cardModel ?? DEFAULT_CARD_MODEL,\n  };\n}\n\ntype RunResult = {\n  stdout: string;\n  stderr: string;\n  error: (Error & { code?: string | number | null | undefined }) | null;\n};\n\nfunction runZg(\n  binary: string,\n  args: string[],\n  cwd: string,\n  timeoutMs: number,\n  signal?: AbortSignal,\n): Promise<RunResult> {\n  return new Promise((resolveRun) => {\n    execFile(\n      binary,\n      args,\n      {\n        cwd,\n        timeout: timeoutMs,\n        maxBuffer: 1024 * 1024,\n        killSignal: \"SIGKILL\",\n        ...(signal ? { signal } : {}),\n      },\n      (error, stdout, stderr) => {\n        if (error && (error as { killed?: boolean }).killed) {\n          resolveRun({\n            stdout: \"\",\n            stderr: String(stderr),\n            error: Object.assign(error, { code: \"ETIMEDOUT\" }),\n          });\n          return;\n        }\n        resolveRun({ stdout: String(stdout), stderr: String(stderr), error });\n      },\n    );\n  });\n}\n\nfunction deadlineError(): NonNullable<RunResult[\"error\"]> {\n  return Object.assign(new Error(\"hook deadline reached\"), { code: \"ETIMEDOUT\" });\n}\n\nfunction serverPath(root: string): string {\n  return join(root, \".codebuddy\", \"cache\", \"zvec-server.json\");\n}\n\n/** `zg server status` says ready; the answer (either way) is reused for 30 s. */\nasync function serverRunning(\n  root: string,\n  binary: string,\n  run: (args: string[]) => Promise<RunResult>,\n): Promise<boolean> {\n  try {\n    const cached = JSON.parse(await readFile(serverPath(root), \"utf8\")) as {\n      binary?: string;\n      checkedAt?: number;\n      running?: boolean;\n    };\n    const age = Date.now() - (cached.checkedAt ?? 0);\n    if (cached.binary === binary && age >= 0 && age <= NOT_READY_CACHE_MS) {\n      return cached.running === true;\n    }\n  } catch {\n    // No record yet: ask zg.\n  }\n  const status = await run([\"server\", \"status\"]);\n  // A deadline miss says nothing about the server: not cached.\n  if (status.error?.code === \"ETIMEDOUT\") return false;\n  const running = !status.error && /^Server: ready\\b/m.test(status.stdout);\n  try {\n    await mkdir(dirname(serverPath(root)), { recursive: true, mode: 0o700 });\n    await writeAtomic(\n      serverPath(root),\n      `${JSON.stringify({ binary, checkedAt: Date.now(), running })}\\n`,\n    );\n  } catch {\n    // An unwritable cache only repeats the check.\n  }\n  return running;\n}\n\nfunction fromError(\n  error: NonNullable<RunResult[\"error\"]>,\n  what: string,\n  stderr = \"\",\n): ZvecCandidates {\n  if (error.code === \"ENOENT\") return none(\"not-installed\", \"zvec-grep (`zg`) not found on PATH\");\n  if (error.code === \"ETIMEDOUT\") return none(\"timeout\", `${what} timed out`);\n  if (BUSY.test(stderr)) return none(\"busy\", `${what}: index busy (a zg index refresh is running)`);\n  // zg prints `Code: ZVEC_GREP.…` on failure; keep it so the explain line is diagnosable.\n  const code = stderr.match(/\\bCode:\\s*(\\S+)/)?.[1];\n  return none(\"failed\", `${what} failed${code ? ` (${code})` : \"\"}`);\n}\n\n/** zg's lock error while another process (a background `zg index`) writes the index. */\nconst BUSY = /ZVEC_GREP\\.ENGINE\\.LOCK\\.BUSY/;\nconst BUSY_RETRY_MS = 150;\n\nfunction isBusy(result: RunResult): boolean {\n  return BUSY.test(result.stderr);\n}\n\nfunction none(status: ZvecStatus, reason: string): ZvecCandidates {\n  return { status, paths: [], hits: [], reason, stale: 0, changed: 0 };\n}\n\nfunction toRepoRelative(root: string, path: string): string | null {\n  const absolute = isAbsolute(path) ? path : resolve(root, path);\n  const rel = relative(root, absolute);\n  if (rel === \"\" || rel === \"..\" || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;\n  return rel.split(sep).join(\"/\");\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-CAEPHLHC.js → chunk-57642NGU.js}

@@ -58,50 +58,8 @@ function clampBudgetForCallerModel(requestedBudget, callerModel) {
   return { budget: requestedBudget, clamped: false };
 }
 
-// src/core/ids.ts
-import { createHash, randomBytes } from "crypto";
-var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-function generateUlid(now = Date.now()) {
-  let timePart = "";
-  let ts = now;
-  for (let i = 0; i < 10; i++) {
-    timePart = (CROCKFORD[ts % 32] ?? "0") + timePart;
-    ts = Math.floor(ts / 32);
-  }
-  const bytes = randomBytes(10);
-  let randPart = "";
-  for (let i = 0; i < 16; i++) {
-    const bitOffset = i * 5;
-    const byteIndex = Math.floor(bitOffset / 8);
-    const bitInByte = bitOffset % 8;
-    const hi = bytes[byteIndex] ?? 0;
-    const lo = bytes[byteIndex + 1] ?? 0;
-    const combined = (hi << 8 | lo) >>> 0;
-    const shift = 16 - bitInByte - 5;
-    const value = combined >>> shift & 31;
-    randPart += CROCKFORD[value] ?? "0";
-  }
-  return timePart + randPart;
-}
-function generateSessionId(now) {
-  return `sess_${generateUlid(now).toLowerCase()}`;
-}
-function generateEntityId(prefix, now) {
-  return `${prefix}_${generateUlid(now).toLowerCase()}`;
-}
-function computeContentHash(namespace, sessionId, content) {
-  return createHash("sha256").update(`${namespace}${sessionId}${content}`).digest("hex");
-}
-function computeFactHash(namespace, content) {
-  return createHash("sha256").update(`${namespace}fact${content}`).digest("hex");
-}
-
 export {
   countTokens,
-  clampBudgetForCallerModel,
-  generateSessionId,
-  generateEntityId,
-  computeContentHash,
-  computeFactHash
+  clampBudgetForCallerModel
 };
-//# sourceMappingURL=chunk-CAEPHLHC.js.map
+//# sourceMappingURL=chunk-57642NGU.js.map

package/dist/chunk-57642NGU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/planner/budget.ts"],"sourcesContent":["import { Tiktoken } from \"js-tiktoken/lite\";\nimport cl100kBase from \"js-tiktoken/ranks/cl100k_base\";\nimport { getModelContextWindow } from \"../providers/models.js\";\n\nlet encoder: Tiktoken | null = null;\n\nfunction getEncoder(): Tiktoken {\n  if (!encoder) {\n    encoder = new Tiktoken(cl100kBase);\n  }\n  return encoder;\n}\n\n/** cl100k pre-tokenizer: BPE merges never cross these pieces, so counts add up. */\nconst PIECE = new RegExp(cl100kBase.pat_str, \"gu\");\nconst SPECIAL_TOKENS = Object.keys(cl100kBase.special_tokens);\n// ponytail: cleared when full rather than LRU; source and JSON pieces repeat\n// heavily, so a simple bound keeps the hit rate high.\nconst MAX_CACHED_PIECES = 200_000;\nconst pieceTokens = new Map<string, number>();\nconst MAX_PIECE_CHARS = 256;\n\n/**\n * Exact cl100k token count. A context request tokenizes nearly the same JSON\n * several times (stats, stages, budget fixed point, delivery), so BPE results\n * are memoized per pre-tokenized piece; the sum equals `encode(text).length`.\n */\nexport function countTokens(text: string): number {\n  if (!text) return 0;\n  try {\n    // `encode` rejects special-token text; keep the same fallback for it.\n    if (SPECIAL_TOKENS.some((token) => text.includes(token))) throw new Error(\"special token\");\n    let total = 0;\n    for (const [whole] of text.matchAll(PIECE)) {\n      // BPE is quadratic in piece length: one 32 KB run of \"x\" took over a\n      // minute and blocked the MCP server. Long pieces are counted in chunks.\n      // ponytail: may over-count by ≤ 1 token per chunk on pieces > 256 chars\n      // (real text almost never has them); exact again if js-tiktoken gets linear.\n      for (let start = 0; start < whole.length; start += MAX_PIECE_CHARS) {\n        const piece = whole.slice(start, start + MAX_PIECE_CHARS);\n        let count = pieceTokens.get(piece);\n        if (count === undefined) {\n          count = getEncoder().encode(piece).length;\n          if (pieceTokens.size >= MAX_CACHED_PIECES) pieceTokens.clear();\n          pieceTokens.set(piece, count);\n        }\n        total += count;\n      }\n    }\n    return total;\n  } catch {\n    return Math.max(1, Math.ceil(text.length / 4));\n  }\n}\n\nexport type BudgetClampResult = {\n  budget: number;\n  clamped: boolean;\n  reason?: string;\n};\n\nexport function clampBudgetForCallerModel(\n  requestedBudget: number,\n  callerModel: string | undefined,\n): BudgetClampResult {\n  if (!callerModel) {\n    return { budget: requestedBudget, clamped: false };\n  }\n  const ctx = getModelContextWindow(callerModel);\n  if (!ctx) {\n    return { budget: requestedBudget, clamped: false };\n  }\n  const headroom = Math.floor(ctx * 0.75);\n  if (requestedBudget > headroom) {\n    return {\n      budget: headroom,\n      clamped: true,\n      reason: `budget ${requestedBudget} exceeds 75% of ${callerModel} context window (${ctx}); clamped to ${headroom}.`,\n    };\n  }\n  return { budget: requestedBudget, clamped: false };\n}\n"],"mappings":";;;;;AAAA,SAAS,gBAAgB;AACzB,OAAO,gBAAgB;AAGvB,IAAI,UAA2B;AAE/B,SAAS,aAAuB;AAC9B,MAAI,CAAC,SAAS;AACZ,cAAU,IAAI,SAAS,UAAU;AAAA,EACnC;AACA,SAAO;AACT;AAGA,IAAM,QAAQ,IAAI,OAAO,WAAW,SAAS,IAAI;AACjD,IAAM,iBAAiB,OAAO,KAAK,WAAW,cAAc;AAG5D,IAAM,oBAAoB;AAC1B,IAAM,cAAc,oBAAI,IAAoB;AAC5C,IAAM,kBAAkB;AAOjB,SAAS,YAAY,MAAsB;AAChD,MAAI,CAAC,KAAM,QAAO;AAClB,MAAI;AAEF,QAAI,eAAe,KAAK,CAAC,UAAU,KAAK,SAAS,KAAK,CAAC,EAAG,OAAM,IAAI,MAAM,eAAe;AACzF,QAAI,QAAQ;AACZ,eAAW,CAAC,KAAK,KAAK,KAAK,SAAS,KAAK,GAAG;AAK1C,eAAS,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS,iBAAiB;AAClE,cAAM,QAAQ,MAAM,MAAM,OAAO,QAAQ,eAAe;AACxD,YAAI,QAAQ,YAAY,IAAI,KAAK;AACjC,YAAI,UAAU,QAAW;AACvB,kBAAQ,WAAW,EAAE,OAAO,KAAK,EAAE;AACnC,cAAI,YAAY,QAAQ,kBAAmB,aAAY,MAAM;AAC7D,sBAAY,IAAI,OAAO,KAAK;AAAA,QAC9B;AACA,iBAAS;AAAA,MACX;AAAA,IACF;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO,KAAK,IAAI,GAAG,KAAK,KAAK,KAAK,SAAS,CAAC,CAAC;AAAA,EAC/C;AACF;AAQO,SAAS,0BACd,iBACA,aACmB;AACnB,MAAI,CAAC,aAAa;AAChB,WAAO,EAAE,QAAQ,iBAAiB,SAAS,MAAM;AAAA,EACnD;AACA,QAAM,MAAM,sBAAsB,WAAW;AAC7C,MAAI,CAAC,KAAK;AACR,WAAO,EAAE,QAAQ,iBAAiB,SAAS,MAAM;AAAA,EACnD;AACA,QAAM,WAAW,KAAK,MAAM,MAAM,IAAI;AACtC,MAAI,kBAAkB,UAAU;AAC9B,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,SAAS;AAAA,MACT,QAAQ,UAAU,eAAe,mBAAmB,WAAW,oBAAoB,GAAG,iBAAiB,QAAQ;AAAA,IACjH;AAAA,EACF;AACA,SAAO,EAAE,QAAQ,iBAAiB,SAAS,MAAM;AACnD;","names":[]}