agent-nuvira 3.3.12 → 3.3.13

package/dist/learning/knowledge-base.js

@@ -0,0 +1,337 @@
+/**
+ * KnowledgeBase — tag-scoped, vectorized retrieval over a user's own documents.
+ *
+ * WHY THIS EXISTS. The retrieval engine (`src/learning/retrieval.ts`) vectorizes
+ * a REPO for token reduction and keys everything by file path; the tagged memory
+ * store (`src/tools/memory-tools.ts`) holds FACTS, not whole documents. Neither
+ * answers "I brought my documents, gave them a tag, and I want precise answers
+ * scoped to that tag." So a user asking about their own data had exactly one
+ * path — re-read the file into context on EVERY turn, which costs the document's
+ * tokens repeatedly and is slow on large files.
+ *
+ * This module pays that cost ONCE. A document is extracted, chunked and embedded
+ * a single time under a tag; each later question embeds a short query and
+ * retrieves its top-k chunks. The tag is a real scope: each tag gets its own
+ * vector namespace (`knowledge-<tag>`), so tags never bleed into each other and
+ * a tag can be forgotten without touching anything else.
+ *
+ * The retrieved chunks are USER DATA; the model supplies the generic half of an
+ * answer (and `web-research` supplies the net-based half). `formatKnowledgeContext`
+ * labels each chunk with its source file so the model can attribute precisely
+ * which part of an answer came from the user's data.
+ *
+ * Storage: vectors in the existing pluggable VectorStore (one JSON/FAISS file
+ * per namespace), a small manifest at `<memory>/knowledge-index.json` for
+ * listing/removal. Everything lives in the Nuvira data dir (`~/.nuvira/memory`),
+ * never in a repository or package.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, extname, basename } from 'node:path';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+import { embed, RETRIEVAL_MODEL } from '../memory/embedder.js';
+import { getVectorStore } from '../memory/vector-store.js';
+import { chunkText, DEFAULT_CHUNK_TOKENS, DEFAULT_OVERLAP_TOKENS } from './retrieval.js';
+import { logger } from '../utils/logger.js';
+// ─── Constants ──────────────────────────────────────────────────────────────
+/** A tag is a sandboxed namespace segment: lowercase alphanumerics + hyphens, with at least one alphanumeric. */
+export const KNOWLEDGE_TAG_RE = /^[a-z0-9-]*[a-z0-9][a-z0-9-]*$/;
+/** Namespace prefix — keeps knowledge vectors apart from memory/history/repo. */
+export const KNOWLEDGE_NAMESPACE_PREFIX = 'knowledge-';
+/** Manifest of tags → documents (listing/removal only; vectors live elsewhere). */
+export const KNOWLEDGE_MANIFEST_FILE = 'knowledge-index.json';
+/** Default chunks returned per query. */
+export const DEFAULT_KNOWLEDGE_TOP_K = 6;
+/** Directories never walked when a tag is pointed at a folder. */
+const IGNORE_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.next', '.cache', '.venv', 'venv',
+    '__pycache__', '.turbo', '.nx', 'coverage', '.idea', '.vscode',
+]);
+/** Cap a directory walk so a stray `.` cannot index an entire disk. */
+const MAX_FILES_PER_INGEST = 500;
+/** Per-chunk text kept in metadata (matches retrieval.ts's budget). */
+const MAX_EXTRACT_CHARS = 2_000_000;
+// ─── Paths (resolved per call so tests that set NUVIRA_MEMORY_DIR are hermetic) ──
+function memoryDir() {
+    return envBuff('MEMORY_DIR') || join(resolveNuviraHome(), 'memory');
+}
+function manifestPath() {
+    return join(memoryDir(), KNOWLEDGE_MANIFEST_FILE);
+}
+// ─── Tag handling ───────────────────────────────────────────────────────────
+/**
+ * Normalize a user-supplied tag into the sandboxed form. `Dheeraj_Health_report`
+ * → `dheeraj-health-report`. This is deliberately forgiving: a human naming a
+ * tag should not have to know the namespace rules, and a tag is not a path.
+ */
+export function normalizeKnowledgeTag(tag) {
+    return tag
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-{2,}/g, '-');
+}
+/** True when a (already-normalized) tag is valid and non-empty. */
+export function isValidKnowledgeTag(tag) {
+    return KNOWLEDGE_TAG_RE.test(tag);
+}
+/** The VectorStore namespace for a tag. Assumes a normalized tag. */
+export function namespaceForTag(tag) {
+    return `${KNOWLEDGE_NAMESPACE_PREFIX}${tag}`;
+}
+// ─── Manifest ───────────────────────────────────────────────────────────────
+function emptyManifest() {
+    return { version: 1, tags: {} };
+}
+/** Read the tag manifest. Never throws — a missing/corrupt file yields empty. */
+export function readKnowledgeManifest() {
+    try {
+        if (!existsSync(manifestPath()))
+            return emptyManifest();
+        const data = JSON.parse(readFileSync(manifestPath(), 'utf-8'));
+        if (!data || typeof data !== 'object' || typeof data.tags !== 'object')
+            return emptyManifest();
+        return { version: data.version ?? 1, tags: data.tags ?? {} };
+    }
+    catch {
+        return emptyManifest();
+    }
+}
+function writeKnowledgeManifest(manifest) {
+    try {
+        if (!existsSync(memoryDir()))
+            mkdirSync(memoryDir(), { recursive: true });
+        writeFileSync(manifestPath(), JSON.stringify(manifest, null, 2), 'utf-8');
+    }
+    catch {
+        // Best-effort — the vectors are the source of truth; the manifest is an index.
+    }
+}
+/** Every tag with its recorded documents/chunk counts (sorted by recency). */
+export function listKnowledgeTags() {
+    return Object.values(readKnowledgeManifest().tags).sort((a, b) => b.updatedAt - a.updatedAt);
+}
+/** One tag's manifest entry, or null. */
+export function getKnowledgeTag(tag) {
+    const normalized = normalizeKnowledgeTag(tag);
+    return readKnowledgeManifest().tags[normalized] ?? null;
+}
+// ─── File collection ────────────────────────────────────────────────────────
+/** Recursively collect files under a path (bounded, ignores build/vendor dirs). */
+export function collectKnowledgeFiles(root, out = [], depth = 0) {
+    if (out.length >= MAX_FILES_PER_INGEST || depth > 8)
+        return out;
+    let stat;
+    try {
+        stat = statSync(root);
+    }
+    catch {
+        return out;
+    }
+    if (stat.isFile()) {
+        out.push(root);
+        return out;
+    }
+    if (!stat.isDirectory())
+        return out;
+    let entries = [];
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (out.length >= MAX_FILES_PER_INGEST)
+            break;
+        if (IGNORE_DIRS.has(entry))
+            continue;
+        collectKnowledgeFiles(join(root, entry), out, depth + 1);
+    }
+    return out;
+}
+// ─── Text extraction ────────────────────────────────────────────────────────
+/**
+ * Extract a file's text, reusing the `read_extract` manager so PDF/DOCX/XLSX/
+ * PPTX and text formats all work (and unsupported ones refuse with a reason
+ * instead of silently indexing a container's bytes).
+ */
+async function extractFileText(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    // Plain text-ish formats need no heavy reader — read directly.
+    if (['.txt', '.md', '.markdown', '.csv', '.tsv', '.json', '.yaml', '.yml', '.log'].includes(ext)) {
+        try {
+            const text = readFileSync(filePath, 'utf-8');
+            return { ok: true, text: text.length > MAX_EXTRACT_CHARS ? text.slice(0, MAX_EXTRACT_CHARS) : text };
+        }
+        catch (err) {
+            return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    try {
+        const { getReadExtractManager } = await import('../tools/read-extract.js');
+        const result = await getReadExtractManager().extract(filePath);
+        if (!result.success || !result.text) {
+            return { ok: false, reason: result.error ?? result.code ?? 'extraction failed' };
+        }
+        return { ok: true, text: result.text };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+// ─── Ingest ─────────────────────────────────────────────────────────────────
+/**
+ * Ingest raw text under a tag. Idempotent per `<tag>:<sourcePath>#<i>` chunk id,
+ * so re-ingesting a changed document overwrites its chunks rather than
+ * duplicating them.
+ */
+export async function ingestKnowledgeText(tag, sourcePath, text, opts = {}) {
+    const normalized = normalizeKnowledgeTag(tag);
+    const chunkTokens = opts.chunkTokens ?? DEFAULT_CHUNK_TOKENS;
+    const overlapTokens = opts.overlapTokens ?? DEFAULT_OVERLAP_TOKENS;
+    const embedFn = opts.embedFn ?? ((t) => embed(t, undefined, false, RETRIEVAL_MODEL));
+    const label = `${normalized}:${sourcePath}`;
+    const chunks = chunkText(text, label, chunkTokens, overlapTokens);
+    const store = getVectorStore(namespaceForTag(normalized));
+    for (const chunk of chunks) {
+        let vector;
+        try {
+            vector = await embedFn(chunk.text);
+        }
+        catch {
+            // A failed embed leaves a zero vector (never outranks a real match).
+            vector = new Array(384).fill(0);
+        }
+        await store.insert(chunk.id, vector, {
+            kind: 'knowledge-chunk',
+            tag: normalized,
+            sourcePath,
+            chunkIndex: chunk.chunkIndex,
+            text: chunk.text,
+            tokenCount: chunk.tokenCount,
+        });
+    }
+    return chunks.length;
+}
+/**
+ * Ingest one or more files/directories under a tag. Extraction, chunking and
+ * embedding happen ONCE here; later questions only embed a short query.
+ */
+export async function ingestKnowledge(tag, paths, opts = {}) {
+    const normalized = normalizeKnowledgeTag(tag);
+    if (!isValidKnowledgeTag(normalized)) {
+        throw new Error(`Invalid knowledge tag '${tag}' — it must contain at least one letter or digit.`);
+    }
+    const result = { tag: normalized, files: 0, chunks: 0, skipped: [] };
+    const manifest = readKnowledgeManifest();
+    const entry = manifest.tags[normalized] ?? {
+        tag: normalized,
+        updatedAt: Date.now(),
+        chunkCount: 0,
+        documents: [],
+    };
+    // Flatten dirs → files, bounded.
+    const files = [];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            collectKnowledgeFiles(p, files);
+        }
+        else {
+            result.skipped.push({ path: p, reason: 'not found' });
+        }
+    }
+    for (const file of files) {
+        const extracted = await extractFileText(file);
+        if (!extracted.ok) {
+            result.skipped.push({ path: file, reason: extracted.reason });
+            continue;
+        }
+        try {
+            const chunks = await ingestKnowledgeText(normalized, file, extracted.text, opts);
+            result.files += 1;
+            result.chunks += chunks;
+            // Re-ingesting a changed document replaces its chunks; keep the recorded
+            // count in step by subtracting the previous contribution first.
+            const previous = entry.documents.find((d) => d.path === file);
+            if (previous)
+                entry.chunkCount -= previous.chunks;
+            entry.documents = entry.documents.filter((d) => d.path !== file);
+            entry.documents.push({ path: file, chunks, addedAt: Date.now() });
+            entry.chunkCount += chunks;
+        }
+        catch (err) {
+            result.skipped.push({ path: file, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    entry.updatedAt = Date.now();
+    manifest.tags[normalized] = entry;
+    writeKnowledgeManifest(manifest);
+    return result;
+}
+// ─── Query ──────────────────────────────────────────────────────────────────
+/** Embed the question and return the tag's top-k chunks. Never throws. */
+export async function queryKnowledge(tag, question, opts = {}) {
+    const normalized = normalizeKnowledgeTag(tag);
+    const topK = opts.topK ?? DEFAULT_KNOWLEDGE_TOP_K;
+    const embedFn = opts.embedFn ?? ((t) => embed(t, undefined, false, RETRIEVAL_MODEL));
+    try {
+        const queryVector = await embedFn(question);
+        const store = getVectorStore(namespaceForTag(normalized));
+        const results = await store.search(queryVector, topK, (entry) => {
+            return entry.metadata?.kind === 'knowledge-chunk' && entry.metadata?.tag === normalized;
+        });
+        return results.map(({ entry, similarity }) => ({
+            tag: normalized,
+            text: String(entry.metadata?.text ?? ''),
+            sourcePath: String(entry.metadata?.sourcePath ?? entry.id),
+            chunkIndex: Number(entry.metadata?.chunkIndex ?? 0),
+            similarity,
+        }));
+    }
+    catch (err) {
+        logger.debug(`Knowledge query failed for tag '${normalized}': ${err instanceof Error ? err.message : err}`);
+        return [];
+    }
+}
+// ─── Forget ─────────────────────────────────────────────────────────────────
+/** Remove a tag's vectors and manifest entry. Returns true when something was removed. */
+export async function forgetKnowledgeTag(tag) {
+    const normalized = normalizeKnowledgeTag(tag);
+    const manifest = readKnowledgeManifest();
+    const existed = Boolean(manifest.tags[normalized]);
+    delete manifest.tags[normalized];
+    writeKnowledgeManifest(manifest);
+    try {
+        await getVectorStore(namespaceForTag(normalized)).clear();
+    }
+    catch {
+        // Best-effort — the manifest entry is already gone.
+    }
+    return existed;
+}
+// ─── Formatting for the model ───────────────────────────────────────────────
+/**
+ * Render retrieved chunks as context that ATTRIBUTES each part to the user's
+ * data. The model can then answer the data half from here and the generic half
+ * from its own knowledge / `web-research`, and say which is which.
+ */
+export function formatKnowledgeContext(tag, hits) {
+    const normalized = normalizeKnowledgeTag(tag);
+    if (hits.length === 0) {
+        return `No entries found for knowledge tag '${normalized}'. Ingest documents first with the knowledge tool (action: add).`;
+    }
+    const parts = hits.map((h) => {
+        const name = basename(h.sourcePath);
+        return `--- [from your data: ${name} · chunk ${h.chunkIndex + 1} · sim ${h.similarity.toFixed(3)}] ---\n${h.text}`;
+    });
+    return [
+        `Knowledge tag: ${normalized} (${hits.length} relevant chunk${hits.length === 1 ? '' : 's'} from the user's own data)`,
+        'Treat the following as USER DATA — quote it for facts about the user. For general advice, combine it with your own knowledge and, when current guidance is needed, the web-research tool, and say which part is which.',
+        '',
+        ...parts,
+    ].join('\n');
+}
+// Re-export for tests/callers that want the raw embedding defaults.
+export { DEFAULT_CHUNK_TOKENS, DEFAULT_OVERLAP_TOKENS };
+//# sourceMappingURL=knowledge-base.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-base.js","sourceRoot":"","sources":["../../src/learning/knowledge-base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,+EAA+E;AAE/E,iHAAiH;AACjH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gCAAgC,CAAC;AAEjE,iFAAiF;AACjF,MAAM,CAAC,MAAM,0BAA0B,GAAG,YAAY,CAAC;AAEvD,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE9D,yCAAyC;AACzC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,kEAAkE;AAClE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM;IAC3E,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS;CAC/D,CAAC,CAAC;AAEH,uEAAuE;AACvE,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,uEAAuE;AACvE,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAsDpC,oFAAoF;AAEpF,SAAS,SAAS;IAChB,OAAO,OAAO,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,iBAAiB,EAAE,EAAE,QAAQ,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,uBAAuB,CAAC,CAAC;AACpD,CAAC;AAED,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,GAAG;SACP,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,GAAG,0BAA0B,GAAG,GAAG,EAAE,CAAC;AAC/C,CAAC;AAED,+EAA+E;AAE/E,SAAS,aAAa;IACpB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAClC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC;YAAE,OAAO,aAAa,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,OAAO,CAAC,CAAsB,CAAC;QACpF,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,aAAa,EAAE,CAAC;QAC/F,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,QAA2B;IACzD,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YAAE,SAAS,CAAC,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,aAAa,CAAC,YAAY,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,+EAA+E;IACjF,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;AAC/F,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9C,OAAO,qBAAqB,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AAC1D,CAAC;AAED,+EAA+E;AAE/E,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,MAAgB,EAAE,EAAE,KAAK,GAAG,CAAC;IAC/E,IAAI,GAAG,CAAC,MAAM,IAAI,oBAAoB,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAChE,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAClB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,GAAG,CAAC;IACpC,IAAI,OAAO,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,MAAM,IAAI,oBAAoB;YAAE,MAAM;QAC9C,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QACrC,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+EAA+E;AAE/E;;;;GAIG;AACH,KAAK,UAAU,eAAe,CAAC,QAAgB;IAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,+DAA+D;IAC/D,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjG,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACvG,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACjF,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,MAAM,qBAAqB,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,IAAI,mBAAmB,EAAE,CAAC;QACnF,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACjF,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW,EACX,UAAkB,EAClB,IAAY,EACZ,OAAyB,EAAE;IAE3B,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAC7D,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACnE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;IAE7F,MAAM,KAAK,GAAG,GAAG,UAAU,IAAI,UAAU,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,cAAc,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;IAE1D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,MAAgB,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;YACrE,MAAM,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE;YACnC,IAAI,EAAE,iBAAiB;YACvB,GAAG,EAAE,UAAU;YACf,UAAU;YACV,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAW,EACX,KAAe,EACf,OAAyB,EAAE;IAE3B,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,mDAAmD,CAAC,CAAC;IACpG,CAAC;IAED,MAAM,MAAM,GAAiB,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACnF,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IACzC,MAAM,KAAK,GAAsB,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI;QAC5D,GAAG,EAAE,UAAU;QACf,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,UAAU,EAAE,CAAC;QACb,SAAS,EAAE,EAAE;KACd,CAAC;IAEF,iCAAiC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,qBAAqB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;YAC9D,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACjF,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;YAClB,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC;YACxB,yEAAyE;YACzE,gEAAgE;YAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YAC9D,IAAI,QAAQ;gBAAE,KAAK,CAAC,UAAU,IAAI,QAAQ,CAAC,MAAM,CAAC;YAClD,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YACjE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAClE,KAAK,CAAC,UAAU,IAAI,MAAM,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAED,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;IAClC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAE/E,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAW,EACX,QAAgB,EAChB,OAAyB,EAAE;IAE3B,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,uBAAuB,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;IAE7F,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,cAAc,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,KAAkB,EAAE,EAAE;YAC3E,OAAO,KAAK,CAAC,QAAQ,EAAE,IAAI,KAAK,iBAAiB,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,UAAU,CAAC;QAC1F,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;YAC7C,GAAG,EAAE,UAAU;YACf,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC;YACxC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,IAAI,KAAK,CAAC,EAAE,CAAC;YAC1D,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,IAAI,CAAC,CAAC;YACnD,UAAU;SACX,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,mCAAmC,UAAU,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5G,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,cAAc,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,IAAoB;IACtE,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,uCAAuC,UAAU,kEAAkE,CAAC;IAC7H,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACpC,OAAO,wBAAwB,IAAI,YAAY,CAAC,CAAC,UAAU,GAAG,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IACrH,CAAC,CAAC,CAAC;IACH,OAAO;QACL,kBAAkB,UAAU,KAAK,IAAI,CAAC,MAAM,kBAAkB,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,4BAA4B;QACtH,wNAAwN;QACxN,EAAE;QACF,GAAG,KAAK;KACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/learning/model-selection.d.ts

@@ -54,7 +54,8 @@ export declare function hasCredentials(configManager: ConfigManager, provider: s
 export declare const MODEL_HEALTH_CEILING = 0.6;
 /**
  * Verified working models for a provider, ranked by learned health:
- * lowest error rate first, then lowest latency, then most recently verified.
+ * strongest verification source first, then lowest error rate, then lowest
+ * latency, then most recently verified.
  * Empty when nothing has been verified yet (cold start / no keys).
  *
  * MODELS AT/ABOVE `MODEL_HEALTH_CEILING` SORT AFTER THE HEALTHY ONES but are

package/dist/learning/model-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-selection.d.ts","sourceRoot":"","sources":["../../src/learning/model-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAU1D,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,qEAAsE,CAAC;AAErG;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,CAAC;AAMnE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA6B,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOtF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAuC7D;AAcD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,EAAE,CAiErF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE,aAAa,GAC5B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA0BjD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAa5E"}
+{"version":3,"file":"model-selection.d.ts","sourceRoot":"","sources":["../../src/learning/model-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAU1D,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,qEAAsE,CAAC;AAErG;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,CAAC;AAMnE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA6B,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOtF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAqBxC;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA6C7D;AAcD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,EAAE,CAuErF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE,aAAa,GAC5B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA0BjD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAa5E"}

package/dist/learning/model-selection.js

@@ -68,9 +68,28 @@ export function hasCredentials(configManager, provider) {
  * failed outright.
  */
 export const MODEL_HEALTH_CEILING = 0.6;
+/**
+ * How much a verification SOURCE is worth when ranking models of equal health.
+ * Lower = more trustworthy, so it sorts first.
+ *
+ * A `spot-check` is a single 1-token generation: it proves the model NAME
+ * exists and accepts a request — it does NOT prove the model can hold a task.
+ * `telemetry` is real traffic (hundreds of samples), so it is the strongest
+ * evidence we have. Ranking them as equals let a model with six probe samples
+ * (observed live: `deepseek-v4-pro`, 6 samples) sit at errorRate 0 beside a
+ * model with 290 real calls (`deepseek-flash`) — and whenever the configured
+ * pin was dead, the fallback walk could then hand a caller a model that had
+ * never actually done a task. Real evidence must win.
+ */
+const SOURCE_CONFIDENCE = {
+    telemetry: 0,
+    'spot-check': 1,
+    probe: 2,
+};
 /**
  * Verified working models for a provider, ranked by learned health:
- * lowest error rate first, then lowest latency, then most recently verified.
+ * strongest verification source first, then lowest error rate, then lowest
+ * latency, then most recently verified.
  * Empty when nothing has been verified yet (cold start / no keys).
  *
  * MODELS AT/ABOVE `MODEL_HEALTH_CEILING` SORT AFTER THE HEALTHY ONES but are
@@ -96,6 +115,13 @@ export function preferredModelsFor(provider) {
         .sort((a, b) => {
         const ea = registry.getEntry(provider, a);
         const eb = registry.getEntry(provider, b);
+        // 1. Evidence strength. A model proven by real traffic must outrank one
+        //    that only ever answered a 1-token probe — they are NOT equivalent
+        //    evidence, and treating them as such is how an unproven model won.
+        const sa = SOURCE_CONFIDENCE[ea?.source ?? 'probe'] ?? 2;
+        const sb = SOURCE_CONFIDENCE[eb?.source ?? 'probe'] ?? 2;
+        if (sa !== sb)
+            return sa - sb;
         const ra = ea?.errorRate ?? 0;
         const rb = eb?.errorRate ?? 0;
         if (ra !== rb)
@@ -156,8 +182,10 @@ export function rankAvailableProviders(configManager) {
     // providers join routing the moment they appear in config. Nothing is
     // hardcoded to the 6 built-ins anymore.
     let configuredIds = [];
+    let providerConfig = {};
     try {
-        configuredIds = Object.keys(configManager.getAll?.()?.providers ?? {});
+        providerConfig = configManager.getAll?.()?.providers ?? {};
+        configuredIds = Object.keys(providerConfig);
     }
     catch {
         // Best-effort.
@@ -165,6 +193,11 @@ export function rankAvailableProviders(configManager) {
     const candidates = [...new Set([...CATALOG_PROVIDER_IDS, ...configuredIds])].filter((p) => {
         if (blocked.has(p))
             return false;
+        // The dashboard's per-provider On/Off switch. Off removes the provider from
+        // the AUTO pool only; credentials stay on disk, and an explicit `--provider`
+        // pin is a user decision the router does not second-guess.
+        if (providerConfig[p]?.enabled === false)
+            return false;
         // Keyless runners BEYOND `local` (nuvira, lmstudio, vllm) only join when the
         // registry has VERIFIED them or the user explicitly configured them — a
         // not-running localhost endpoint must never out-rank running local on a

package/dist/learning/model-selection.js.map

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

package/dist/learning/project-docs.d.ts

@@ -0,0 +1,83 @@
+/**
+ * PROJECT DOCUMENTATION (software deliverables).
+ *
+ * The gap this closes: a software build produced CODE and stopped. The
+ * documents a real project ships — a README, a changelog that grows with each
+ * change, a short architecture note with a diagram, and (for a library/service)
+ * usage + API docs — were only produced when the user named them, which is
+ * exactly backwards: a user should not have to ask a "world-class developer" to
+ * write down what it built.
+ *
+ * Two rules keep this from becoming noise:
+ *
+ *   1. **Software only.** This module is consulted ONLY for a `code` deliverable
+ *      that is not authored (`deliverable-class.ts` already separates a poem
+ *      from a program). Nobody wants a README and an ARCHITECTURE.md for
+ *      "write me a poem about rain" — the classifier decides, and this guidance
+ *      is never appended to an authored ask.
+ *   2. **Proportionate.** A README and a CHANGELOG are expected of every
+ *      software deliverable; the heavier documents (architecture, API reference,
+ *      contributing guide) are asked for only when the shape warrants them —
+ *      a multi-component or library/service build, or an explicit request for
+ *      docs. A one-file script still gets a README; it is not asked to invent an
+ *      architecture diagram.
+ *
+ * It also encodes the maintenance rule the user cares about: an EXISTING
+ * document is UPDATED in place (CHANGELOG gets a new entry at the top), never
+ * shadowed by a second file — a project with two changelogs is worse than one
+ * with none.
+ *
+ * Pure and side-effect free: every input is data, so it is unit-testable and can
+ * be appended to any prompt without touching the filesystem.
+ */
+/** The canonical documents a software project ships, in priority order. */
+export interface ProjectDocArtifact {
+    /** Project-relative path the document lives at. */
+    path: string;
+    /** What it is FOR — handed to the model so the document has a job. */
+    purpose: string;
+    /** Required of every software deliverable (README, CHANGELOG). */
+    always: boolean;
+}
+export declare const PROJECT_DOC_ARTIFACTS: readonly ProjectDocArtifact[];
+/** What we know about the deliverable, from the goal + project assessment. */
+export interface ProjectDocShape {
+    /**
+     * True when the workspace has no project yet (a scaffold). A greenfield build
+     * gets the full proportionate set rather than only the always-on pair.
+     */
+    greenfield?: boolean;
+    /**
+     * A library, package, SDK or service — a thing other code CONSUMES — rather
+     * than an end-user app. Its public surface must be documented.
+     */
+    isLibraryOrService?: boolean;
+    /** The project already exposes tests (or the agent is expected to write them). */
+    hasTests?: boolean;
+    /** Names the user explicitly asked for docs ("with documentation", "API docs"). */
+    docsRequested?: boolean;
+    /**
+     * Documents that ALREADY exist in the workspace (project-relative paths).
+     * These are UPDATED in place, never duplicated.
+     */
+    existingDocs?: readonly string[];
+}
+/** The always-on pair, plus the heavier docs a bigger build warrants. */
+export declare function requiredProjectDocs(shape?: ProjectDocShape): string[];
+/**
+ * Does the goal name something other code CONSUMES (a library, package, SDK,
+ * CLI, service, plugin) rather than an end-user app? A consumed surface has a
+ * public API worth documenting; an app does not need an API reference.
+ */
+export declare function looksLikeLibraryOrService(goal: string): boolean;
+/** The required docs that do NOT yet exist on disk (the ones to CREATE). */
+export declare function missingProjectDocs(shape?: ProjectDocShape): string[];
+/** The required docs that already exist (the ones to UPDATE, not recreate). */
+export declare function existingProjectDocs(shape?: ProjectDocShape): string[];
+/**
+ * The instruction appended to the reasoner/planner prompt for a SOFTWARE
+ * deliverable. Returns `''` for a non-software (authored) ask, so callers can
+ * append it unconditionally without a poem ever being asked for a CHANGELOG.
+ */
+export declare function softwareProjectGuidance(verdictClass: string, authored: boolean, shape?: ProjectDocShape): string;
+//# sourceMappingURL=project-docs.d.ts.map

package/dist/learning/project-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-docs.d.ts","sourceRoot":"","sources":["../../src/learning/project-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAqC9D,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAU/D;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAGxE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,OAAO,EACjB,KAAK,GAAE,eAAoB,GAC1B,MAAM,CAmCR"}