agent-nuvira 3.3.13 → 3.3.15

package/dist/learning/knowledge-turn.js

@@ -0,0 +1,190 @@
+/**
+ * Knowledge TURN wiring (`src/learning/knowledge-turn.ts`) — the deterministic,
+ * tag-scoped pre-step for a chat turn.
+ *
+ * WHY THIS EXISTS. `knowledge-base.ts` is the STORE, and the `knowledge` tool
+ * lets the model drive it mid-task. Neither answers "answer from THIS document",
+ * because that shape makes the model the trigger: it has to know the tag exists
+ * and decide to use it, and a wrong guess is a silent answer from the wrong
+ * corpus. Here a message that OPENS with a resolvable tag has that tag's
+ * relevant passages retrieved and placed in front of the model BEFORE it sees
+ * the question. The trigger is syntax, not judgement — which is what makes it
+ * deterministic, explainable, and testable.
+ *
+ * THE CAPABILITY GUARANTEE (the whole point of this module). It is INERT unless
+ * the message opens with a marker that resolves to a tag the user actually has:
+ *
+ *   - no marker, or no tags at all → `block: ''`, NO embedder call, and the turn
+ *     is byte-identical to one from a build without this feature;
+ *   - marker names an unknown tag → a short "no such tag" note, and the question
+ *     is answered normally — the wrong corpus is never substituted;
+ *   - tag exists but nothing clears the relevance floor → a note saying the
+ *     tagged documents did not cover it, which is the honest answer;
+ *   - any failure at all → `block: ''` (best-effort, mirroring the ambient
+ *     project-context contract in `src/tools/loop-project-context.ts`).
+ *
+ * So it cannot add cost, latency, noise, or a wrong corpus to a turn that did
+ * not ask for it. And because the block is a USER-TURN message (never the system
+ * prompt), the prompt stays byte-stable and therefore cacheable — the same rule
+ * the channel-policy block follows in `src/cli/chat.ts`.
+ *
+ * WHERE IT RUNS. One seam — `runChatAnswer` in `src/cli/chat.ts` — is shared by
+ * the CLI, the dashboard console (`debugSurface: 'dashboard-chat'`) and the
+ * gateway (`gateway-chat`), so all three surfaces get the same behaviour and
+ * cannot drift.
+ *
+ * THE MARKER. `#tag` as the FIRST token, followed by whitespace or end of input.
+ * A leading `/` is already the interactive chat's command prefix, so it is not
+ * used here. The whole-word requirement plus requiring the tag to start with a
+ * LETTER is what keeps `#1 priority`, a Markdown heading (`# Title`), a shebang
+ * (`#!/bin/bash`), and mid-sentence `C#` from resolving. A pasted `#include`
+ * DOES parse as the tag name `include` — which is exactly why an unknown marker
+ * only ever produces a note, and why the whole feature is inert until the user
+ * has at least one tag of their own.
+ */
+import { formatKnowledgeContext, listKnowledgeTags, normalizeKnowledgeTag, queryKnowledge, } from './knowledge-base.js';
+import { logger } from '../utils/logger.js';
+/**
+ * The marker: `#tag` as the first token. The tag must begin with a LETTER (so
+ * `#1`, `#!`, and `#/` cannot match) and must end at whitespace or end-of-input
+ * (so `#fff,` does not run on into the sentence).
+ */
+export const KNOWLEDGE_MARKER_RE = /^\s*#([A-Za-z][A-Za-z0-9_-]*)(?=\s|$)/;
+/**
+ * Hard cap on the injected block. `topK` already bounds the chunk COUNT, but a
+ * pathological document set could still produce a large block, and a context
+ * block must never crowd out the ask it was meant to help answer. Truncation is
+ * explicit, never silent.
+ */
+export const MAX_KNOWLEDGE_BLOCK_CHARS = 12_000;
+/** How many candidates a "did you mean" note may name. */
+export const MAX_TAG_SUGGESTIONS = 3;
+/** The tag a message opens with, normalized, or null when it opens with none. */
+export function parseKnowledgeMarker(message) {
+    const match = KNOWLEDGE_MARKER_RE.exec(message);
+    if (!match)
+        return null;
+    const tag = normalizeKnowledgeTag(match[1]);
+    return tag.length > 0 ? tag : null;
+}
+/**
+ * The message with its leading marker removed — the marker is retrieval syntax,
+ * not part of the question, and leaving `#tag` in the text it is embedded from
+ * would nudge the query vector toward the tag token instead of the ask.
+ */
+export function stripKnowledgeMarker(message) {
+    const match = KNOWLEDGE_MARKER_RE.exec(message);
+    if (!match)
+        return message;
+    return message.slice(match[0].length).trimStart();
+}
+/** Bounded Levenshtein distance — tags are short, so this is cheap and exact. */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j += 1)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        const swap = prev;
+        prev = curr;
+        curr = swap;
+    }
+    return prev[b.length];
+}
+/**
+ * "Did you mean" candidates for an unknown tag, best first.
+ *
+ * A prefix relationship is the common typo ("spec" for "spec-v2") and is worth
+ * naming even when the edit distance is larger than the cap. Suggestion only —
+ * nothing here ever substitutes one tag for another.
+ */
+export function suggestKnowledgeTags(unknown, tags) {
+    const target = normalizeKnowledgeTag(unknown);
+    if (!target)
+        return [];
+    const maxDistance = target.length <= 4 ? 1 : 2;
+    return tags
+        .map((entry) => {
+        const candidate = entry.tag;
+        return {
+            tag: candidate,
+            distance: editDistance(target, candidate),
+            prefix: candidate.startsWith(target) || target.startsWith(candidate),
+        };
+    })
+        .filter((c) => c.prefix || c.distance <= maxDistance)
+        .sort((a, b) => (a.prefix === b.prefix ? a.distance - b.distance : a.prefix ? -1 : 1))
+        .slice(0, MAX_TAG_SUGGESTIONS)
+        .map((c) => c.tag);
+}
+/** Honest, explicit truncation of an over-long block. */
+function capBlock(block) {
+    if (block.length <= MAX_KNOWLEDGE_BLOCK_CHARS)
+        return block;
+    return `${block.slice(0, MAX_KNOWLEDGE_BLOCK_CHARS)}\n[... knowledge context truncated at ${MAX_KNOWLEDGE_BLOCK_CHARS} characters ...]`;
+}
+/**
+ * Build the knowledge block for a turn. Never throws, never blocks a turn on a
+ * failure, and returns an empty block unless the message genuinely asked for a
+ * tag the user has.
+ */
+export async function buildKnowledgeTurnContext(message, opts = {}) {
+    try {
+        const marker = parseKnowledgeMarker(message);
+        if (!marker)
+            return { block: '', outcome: 'none' };
+        const tags = listKnowledgeTags();
+        // No tags at all: the feature is inert. Without this, a stray leading
+        // `#word` (a pasted `#include`, a `#fff` colour) would produce a note about
+        // a corpus that does not exist.
+        if (tags.length === 0)
+            return { block: '', outcome: 'none' };
+        const match = tags.find((entry) => entry.tag === marker);
+        if (!match) {
+            const suggestions = suggestKnowledgeTags(marker, tags);
+            const hint = suggestions.length > 0
+                ? ` Did you mean ${suggestions.map((s) => `#${s}`).join(' or ')}?`
+                : ` Known tags: ${tags
+                    .slice(0, MAX_TAG_SUGGESTIONS * 2)
+                    .map((t) => `#${t.tag}`)
+                    .join(', ')}.`;
+            return {
+                block: `[Knowledge] No knowledge tag '#${marker}'.${hint} ` +
+                    'Answer the question from your own knowledge — do not guess at documents the user has not tagged.',
+                outcome: 'unknown-tag',
+            };
+        }
+        const question = stripKnowledgeMarker(message) || message;
+        const hits = await queryKnowledge(match.tag, question, opts);
+        if (hits.length === 0) {
+            // The relevance floor dropped everything. This is the honest case the
+            // store could not previously express, and it must NOT be softened into a
+            // general answer read off the tagged documents.
+            return {
+                block: `[Knowledge] Tag '#${match.tag}' has ${match.chunkCount} indexed chunk(s), but none matched this ` +
+                    'question closely enough to be used. Answer from your own knowledge and say the tagged documents did not cover it.',
+                outcome: 'empty',
+                tag: match.tag,
+            };
+        }
+        return {
+            block: capBlock(`[Knowledge] ${formatKnowledgeContext(match.tag, hits)}`),
+            outcome: 'matched',
+            tag: match.tag,
+        };
+    }
+    catch (err) {
+        // Best-effort, exactly like the ambient project context: a retrieval failure
+        // must never break or delay the turn's actual answer.
+        logger.debug(`Knowledge turn context failed: ${err instanceof Error ? err.message : err}`);
+        return { block: '', outcome: 'none' };
+    }
+}
+//# sourceMappingURL=knowledge-turn.js.map

package/dist/learning/knowledge-turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-turn.js","sourceRoot":"","sources":["../../src/learning/knowledge-turn.ts"],"names":[],"mappings":"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"}

package/dist/learning/learned-commands.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Learned commands — a per-OS command the MODEL worked out, kept so it is known
+ * next time.
+ *
+ * WHY THIS EXISTS. The per-OS command map (Bundle 47) declares the command for
+ * the two verbs where the OS determines it; machine facts (Bundle 50) say what is
+ * installed. Neither can enumerate the long tail — every tool, every OS, every
+ * version — and trying to would be a table that is wrong the day it ships. So the
+ * table GROWS BY USE instead: when the model works out how to do a verb on this
+ * OS (and, in the verify loop, it works), the command is recorded here, keyed by
+ * `(verb, os)`, and surfaced to the next search and the next resolve.
+ *
+ * This is the "model-derived, harness-remembered" half of the loop. The MODEL
+ * decides the command (it is the general intelligence); the harness persists it
+ * and hands it back, so the same discovery is not paid for twice.
+ *
+ * ISOLATION. The store resolves through `resolveNuviraDataPath`, so
+ * `$NUVIRA_CONFIG_DIR` isolates it — an isolated (test/CI/sandbox) process never
+ * reads or writes the developer's real store (the bug `resolveNuviraHome` invites).
+ *
+ * BEST-EFFORT AND BOUNDED. Every read/write is wrapped; a corrupt or missing file
+ * is simply an empty store, and the file is capped so a runaway cannot grow
+ * forever (newest wins). A command never TRUSTS a learned entry blindly — the
+ * caller still checks it against the machine — so a stale entry is a hint, not a
+ * fact.
+ */
+import { type NormalizedOs } from './machine-facts.js';
+/** One learned command: how to do `verb` on `os`, as the model derived it. */
+export interface LearnedCommand {
+    /** The verb it accomplishes, normalized (lowercased) — e.g. "install java". */
+    verb: string;
+    /** The OS it was derived for. */
+    os: NormalizedOs;
+    /** The command, exactly as it should run. */
+    command: string;
+    /** The executable the command starts with, when it has one. */
+    binary?: string;
+    /** Optional note (why, a caveat). */
+    note?: string;
+    /** Where it came from: the model's resolution, or an observed successful run. */
+    source: 'model' | 'observed';
+    /** When it was recorded (ms epoch). */
+    learnedAt: number;
+}
+/** Read the store. A missing/corrupt file is an empty store, never a throw. */
+export declare function listLearnedCommands(): LearnedCommand[];
+/** The learned command for `verb` on `os` (default: this machine's OS), or null. */
+export declare function learnedCommandFor(verb: string, os?: NormalizedOs): LearnedCommand | null;
+/**
+ * Record (or replace) the command for `(verb, os)`. Returns the stored entry, or
+ * null when the input is unusable (no verb or no command). Best-effort: a failed
+ * write returns the entry without persisting, never a throw.
+ */
+export declare function recordLearnedCommand(input: {
+    verb: string;
+    command: string;
+    binary?: string;
+    note?: string;
+    source?: 'model' | 'observed';
+    os?: NormalizedOs;
+}): LearnedCommand | null;
+/** Forget the command for `verb` on `os` (default: this machine). True if removed. */
+export declare function forgetLearnedCommand(verb: string, os?: NormalizedOs): boolean;
+//# sourceMappingURL=learned-commands.d.ts.map

package/dist/learning/learned-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learned-commands.d.ts","sourceRoot":"","sources":["../../src/learning/learned-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,EAAE,EAAE,YAAY,CAAC;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,MAAM,EAAE,OAAO,GAAG,UAAU,CAAC;IAC7B,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAmBD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAQtD;AAgBD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,GAAE,YAAsC,GACzC,cAAc,GAAG,IAAI,CAIvB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC9B,EAAE,CAAC,EAAE,YAAY,CAAC;CACnB,GAAG,cAAc,GAAG,IAAI,CAiBxB;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAQ7E"}

package/dist/learning/learned-commands.js

@@ -0,0 +1,108 @@
+/**
+ * Learned commands — a per-OS command the MODEL worked out, kept so it is known
+ * next time.
+ *
+ * WHY THIS EXISTS. The per-OS command map (Bundle 47) declares the command for
+ * the two verbs where the OS determines it; machine facts (Bundle 50) say what is
+ * installed. Neither can enumerate the long tail — every tool, every OS, every
+ * version — and trying to would be a table that is wrong the day it ships. So the
+ * table GROWS BY USE instead: when the model works out how to do a verb on this
+ * OS (and, in the verify loop, it works), the command is recorded here, keyed by
+ * `(verb, os)`, and surfaced to the next search and the next resolve.
+ *
+ * This is the "model-derived, harness-remembered" half of the loop. The MODEL
+ * decides the command (it is the general intelligence); the harness persists it
+ * and hands it back, so the same discovery is not paid for twice.
+ *
+ * ISOLATION. The store resolves through `resolveNuviraDataPath`, so
+ * `$NUVIRA_CONFIG_DIR` isolates it — an isolated (test/CI/sandbox) process never
+ * reads or writes the developer's real store (the bug `resolveNuviraHome` invites).
+ *
+ * BEST-EFFORT AND BOUNDED. Every read/write is wrapped; a corrupt or missing file
+ * is simply an empty store, and the file is capped so a runaway cannot grow
+ * forever (newest wins). A command never TRUSTS a learned entry blindly — the
+ * caller still checks it against the machine — so a stale entry is a hint, not a
+ * fact.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { resolveNuviraDataPath } from '../config/paths.js';
+import { detectMachineFacts } from './machine-facts.js';
+const FILE_NAME = 'learned-commands.json';
+/** Cap the store: newest wins, so a runaway cannot grow without bound. */
+const MAX_COMMANDS = 500;
+function storePath() {
+    return resolveNuviraDataPath(FILE_NAME);
+}
+function isValid(c) {
+    const e = c;
+    return !!e && typeof e.verb === 'string' && typeof e.os === 'string' && typeof e.command === 'string';
+}
+/** Read the store. A missing/corrupt file is an empty store, never a throw. */
+export function listLearnedCommands() {
+    try {
+        if (!existsSync(storePath()))
+            return [];
+        const parsed = JSON.parse(readFileSync(storePath(), 'utf-8'));
+        return Array.isArray(parsed.commands) ? parsed.commands.filter(isValid) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeStore(commands) {
+    try {
+        const path = storePath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify({ commands }, null, 2), 'utf-8');
+    }
+    catch {
+        // Best-effort — a failed write must never break the turn.
+    }
+}
+function normalizeVerb(verb) {
+    return String(verb ?? '').trim().toLowerCase();
+}
+/** The learned command for `verb` on `os` (default: this machine's OS), or null. */
+export function learnedCommandFor(verb, os = detectMachineFacts().os) {
+    const v = normalizeVerb(verb);
+    if (!v)
+        return null;
+    return listLearnedCommands().find((c) => c.verb === v && c.os === os) ?? null;
+}
+/**
+ * Record (or replace) the command for `(verb, os)`. Returns the stored entry, or
+ * null when the input is unusable (no verb or no command). Best-effort: a failed
+ * write returns the entry without persisting, never a throw.
+ */
+export function recordLearnedCommand(input) {
+    const verb = normalizeVerb(input.verb);
+    const command = String(input.command ?? '').trim();
+    if (!verb || !command)
+        return null;
+    const os = input.os ?? detectMachineFacts().os;
+    const entry = {
+        verb,
+        os,
+        command,
+        ...(input.binary ? { binary: input.binary } : {}),
+        ...(input.note ? { note: input.note } : {}),
+        source: input.source ?? 'model',
+        learnedAt: Date.now(),
+    };
+    const rest = listLearnedCommands().filter((c) => !(c.verb === verb && c.os === os));
+    writeStore([entry, ...rest].slice(0, MAX_COMMANDS));
+    return entry;
+}
+/** Forget the command for `verb` on `os` (default: this machine). True if removed. */
+export function forgetLearnedCommand(verb, os) {
+    const v = normalizeVerb(verb);
+    const target = os ?? detectMachineFacts().os;
+    const before = listLearnedCommands();
+    const after = before.filter((c) => !(c.verb === v && c.os === target));
+    if (after.length === before.length)
+        return false;
+    writeStore(after);
+    return true;
+}
+//# sourceMappingURL=learned-commands.js.map

package/dist/learning/learned-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learned-commands.js","sourceRoot":"","sources":["../../src/learning/learned-commands.ts"],"names":[],"mappings":"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"}

package/dist/learning/lexical-search.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lexical search (`src/learning/lexical-search.ts`) — BM25 over a candidate set.
+ *
+ * WHY. Embeddings answer "what is this about"; they are unreliable at "which
+ * passage contains `ERR_TOKEN_FAMILY_REVOKED`". A user's own documents are full
+ * of exactly that — identifiers, clause numbers, dates, error codes, product
+ * names — and a question built from those words fails a dense retriever and is
+ * trivial for a lexical one. That is why retrieval runs both and fuses them
+ * rather than choosing: the two fail on different questions.
+ *
+ * WHY THERE IS NO PERSISTED INVERTED INDEX. The index is built from the
+ * namespace's stored chunks at query time. That sounds wasteful, and it is the
+ * deliberate trade: the chunks are ALREADY being scanned to compute cosine
+ * against every vector (the JSON backend is an exact linear scan, and the
+ * candidate set here is a user's document folder, not a web crawl), so a second
+ * on-disk structure would buy asymptotics nobody needs while adding a NEW
+ * consistency problem — an index that can drift out of step with the vectors
+ * every time a document is re-ingested, deleted or forgotten. A rebuild every
+ * query cannot drift. If a corpus ever grows past the point where this is the
+ * bottleneck, the cache is the place to add one, and the test suite will say so.
+ *
+ * Also here: the tokenizer, shared with the eval so that "what counts as a term"
+ * is one definition rather than two that can disagree.
+ */
+/** Function words carry no topic signal and inflate every score. */
+export declare const STOPWORDS: Set<string>;
+/** Lowercased content tokens (length ≥ 3, not a stopword), in order. */
+export declare function contentTokens(text: string): string[];
+/** FNV-1a — small, fast, deterministic, and dependency-free. */
+export declare function fnv1a(input: string): number;
+export interface LexicalDocument {
+    id: string;
+    text: string;
+}
+export interface LexicalHit {
+    id: string;
+    score: number;
+}
+/**
+ * Rank documents against a query with Okapi BM25.
+ *
+ * A document scores only on terms it actually contains, so a query sharing no
+ * vocabulary with any candidate returns nothing at all — which is what keeps an
+ * unrelated question out even when the dense half is floored.
+ *
+ * The ordering is fully deterministic: equal scores fall back to the document id,
+ * so a fixture corpus scores identically on every run.
+ */
+export declare function bm25Search(documents: LexicalDocument[], query: string, k: number): LexicalHit[];
+//# sourceMappingURL=lexical-search.d.ts.map

package/dist/learning/lexical-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-search.d.ts","sourceRoot":"","sources":["../../src/learning/lexical-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,oEAAoE;AACpE,eAAO,MAAM,SAAS,aAOpB,CAAC;AAEH,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKpD;AAED,gEAAgE;AAChE,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3C;AAMD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAiD/F"}

package/dist/learning/lexical-search.js

@@ -0,0 +1,111 @@
+/**
+ * Lexical search (`src/learning/lexical-search.ts`) — BM25 over a candidate set.
+ *
+ * WHY. Embeddings answer "what is this about"; they are unreliable at "which
+ * passage contains `ERR_TOKEN_FAMILY_REVOKED`". A user's own documents are full
+ * of exactly that — identifiers, clause numbers, dates, error codes, product
+ * names — and a question built from those words fails a dense retriever and is
+ * trivial for a lexical one. That is why retrieval runs both and fuses them
+ * rather than choosing: the two fail on different questions.
+ *
+ * WHY THERE IS NO PERSISTED INVERTED INDEX. The index is built from the
+ * namespace's stored chunks at query time. That sounds wasteful, and it is the
+ * deliberate trade: the chunks are ALREADY being scanned to compute cosine
+ * against every vector (the JSON backend is an exact linear scan, and the
+ * candidate set here is a user's document folder, not a web crawl), so a second
+ * on-disk structure would buy asymptotics nobody needs while adding a NEW
+ * consistency problem — an index that can drift out of step with the vectors
+ * every time a document is re-ingested, deleted or forgotten. A rebuild every
+ * query cannot drift. If a corpus ever grows past the point where this is the
+ * bottleneck, the cache is the place to add one, and the test suite will say so.
+ *
+ * Also here: the tokenizer, shared with the eval so that "what counts as a term"
+ * is one definition rather than two that can disagree.
+ */
+/** Function words carry no topic signal and inflate every score. */
+export const STOPWORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'can', 'do', 'does',
+    'for', 'from', 'has', 'have', 'how', 'i', 'if', 'in', 'is', 'it', 'its', 'me',
+    'my', 'no', 'not', 'of', 'on', 'or', 'our', 'should', 'so', 'than', 'that',
+    'the', 'their', 'them', 'then', 'there', 'these', 'they', 'this', 'to', 'up',
+    'us', 'was', 'we', 'what', 'when', 'where', 'which', 'who', 'why', 'will',
+    'with', 'you', 'your',
+]);
+/** Lowercased content tokens (length ≥ 3, not a stopword), in order. */
+export function contentTokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length >= 3 && !STOPWORDS.has(token));
+}
+/** FNV-1a — small, fast, deterministic, and dependency-free. */
+export function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+/** BM25 term-frequency saturation and length-normalisation. */
+const K1 = 1.2;
+const B = 0.75;
+/**
+ * Rank documents against a query with Okapi BM25.
+ *
+ * A document scores only on terms it actually contains, so a query sharing no
+ * vocabulary with any candidate returns nothing at all — which is what keeps an
+ * unrelated question out even when the dense half is floored.
+ *
+ * The ordering is fully deterministic: equal scores fall back to the document id,
+ * so a fixture corpus scores identically on every run.
+ */
+export function bm25Search(documents, query, k) {
+    const queryTerms = [...new Set(contentTokens(query))];
+    if (queryTerms.length === 0 || documents.length === 0 || k <= 0)
+        return [];
+    const documentLengths = new Map();
+    /** term → docId → term frequency. */
+    const postings = new Map();
+    let totalLength = 0;
+    for (const doc of documents) {
+        const tokens = contentTokens(doc.text);
+        documentLengths.set(doc.id, tokens.length);
+        totalLength += tokens.length;
+        const frequencies = new Map();
+        for (const token of tokens)
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+        for (const [term, frequency] of frequencies) {
+            let posting = postings.get(term);
+            if (!posting) {
+                posting = new Map();
+                postings.set(term, posting);
+            }
+            posting.set(doc.id, frequency);
+        }
+    }
+    const total = documents.length;
+    const averageLength = totalLength / total || 1;
+    const scores = new Map();
+    for (const term of queryTerms) {
+        const posting = postings.get(term);
+        if (!posting)
+            continue;
+        const documentFrequency = posting.size;
+        // The standard BM25 idf: a term every document carries is worth ~nothing, a
+        // term only one document carries is worth a lot.
+        const idf = Math.log(1 + (total - documentFrequency + 0.5) / (documentFrequency + 0.5));
+        for (const [docId, frequency] of posting) {
+            const length = documentLengths.get(docId) ?? 0;
+            const denominator = frequency + K1 * (1 - B + (B * length) / averageLength);
+            const contribution = idf * ((frequency * (K1 + 1)) / denominator);
+            scores.set(docId, (scores.get(docId) ?? 0) + contribution);
+        }
+    }
+    return [...scores.entries()]
+        .filter(([, score]) => score > 0)
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, k);
+}
+//# sourceMappingURL=lexical-search.js.map

package/dist/learning/lexical-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-search.js","sourceRoot":"","sources":["../../src/learning/lexical-search.ts"],"names":[],"mappings":"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"}

package/dist/learning/machine-facts.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Machine facts — what THIS machine is, detected once per run.
+ *
+ * WHY. The agent reasons about "how do I do X here" constantly, and the honest
+ * inputs to that reasoning are facts about the host: which OS and release, which
+ * architecture, which shell, and — the one that actually decides the command —
+ * WHICH PACKAGE MANAGERS ARE INSTALLED. A model that assumes `apt` on a machine
+ * that only has `dnf`, or `brew` on Windows, produces a command that cannot run.
+ * The harness should hand it the facts once rather than let it guess per turn.
+ *
+ * THE ASYMMETRY WITH THE PER-OS COMMAND MAP (Bundle 47). That map declares the
+ * command for the two verbs where the OS DETERMINES it and a wrong guess is
+ * expensive. This module is the opposite side: it detects what is PRESENT on the
+ * host, from the same `which`/`where` resolver the shell uses (`binary-probe`).
+ * Presence is a fact, not a declaration, so it cannot drift — and it is the input
+ * that lets the model derive a command for anything the map does not cover,
+ * instead of the map having to enumerate the world.
+ *
+ * DETECTED ONCE. The whole result is memoized for the process (OS and installed
+ * tools cannot change mid-run), and `binary-probe` is memoized a second time per
+ * name, so the ~25 lookups are paid once. `resetMachineFactsCache()` exists for
+ * test isolation.
+ *
+ * INPUTS ARE INJECTABLE. A test can pass a platform and a fake `binary` probe;
+ * the real call uses `process.platform`, `process.env` and `binaryOnPath`.
+ */
+import type { Capability } from './capability-types.js';
+/** The OS vocabulary shared with the per-OS command map. */
+export type NormalizedOs = 'windows' | 'macos' | 'linux' | 'other';
+export interface MachineFacts {
+    /** When the facts were detected (ms epoch). */
+    detectedAt: number;
+    /** Raw `process.platform` (win32 | darwin | linux | …). */
+    platform: NodeJS.Platform;
+    /** Normalized OS name. */
+    os: NormalizedOs;
+    /** Human label: "Windows 10.0.22631", "macOS (Darwin 23.5.0)", "Ubuntu 22.04". */
+    osName: string;
+    /** Linux distro id from /etc/os-release (e.g. "ubuntu"), else null. */
+    distro: string | null;
+    /** `process.arch` (x64 | arm64 | …). */
+    arch: string;
+    /** Full shell path, when the environment declares one. */
+    shell: string | null;
+    /** Shell's short name (zsh | bash | powershell | cmd). */
+    shellName: string | null;
+    /** Package managers/toolchain binaries actually present, in preference order. */
+    packageManagers: string[];
+}
+/** Options for a deterministic test (the real call passes none). */
+export interface MachineFactsProbe {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    binary?: (name: string) => boolean;
+}
+/** Clear the memo (test isolation). */
+export declare function resetMachineFactsCache(): void;
+/**
+ * Detect this machine's facts. Memoized for the process when called with no
+ * overrides (the real path); an override call (a test) always computes fresh.
+ */
+export declare function detectMachineFacts(probe?: MachineFactsProbe): MachineFacts;
+/** One bounded line the model reads — the machine, stated, not assumed. */
+export declare function buildMachineFactsBlock(facts?: MachineFacts): string;
+/**
+ * The machine facts as a discoverable capability, so the SAME facts the prompt
+ * carries are reachable through a capability search (and so readiness can reason
+ * about what is present). Read-only, no requirements, no grant.
+ */
+export declare function machineFactsCapability(facts?: MachineFacts): Capability;
+//# sourceMappingURL=machine-facts.d.ts.map

package/dist/learning/machine-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-facts.d.ts","sourceRoot":"","sources":["../../src/learning/machine-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnE,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,0BAA0B;IAC1B,EAAE,EAAE,YAAY,CAAC;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iFAAiF;IACjF,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAuBD,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC;AAID,uCAAuC;AACvC,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAqCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,iBAAsB,GAAG,YAAY,CAmC9E;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,YAAmC,GAAG,MAAM,CASzF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,YAAmC,GAAG,UAAU,CAa7F"}