ollama-intern-mcp 1.0.0

package/dist/evals/retrieval.js

@@ -0,0 +1,173 @@
+/**
+ * Retrieval eval runner — measurement law for the Retrieval Truth Spine.
+ *
+ * Loads gold queries from evals/gold/retrieval.jsonl, runs every query
+ * through every search mode against a fixture corpus, and reports
+ * precision@1 and precision@3 per (mode × class) plus per-mode and
+ * overall aggregates.
+ *
+ * The runner is deliberately retrieval-native: assertions check whether
+ * the expected path appears in the top-K hits, not whether the answer
+ * is correct. Answer synthesis is slice 5; measurement is the floor
+ * under it.
+ *
+ * No product-surface changes ride on this file. It is a pure consumer
+ * of searchCorpus() and the corpus schema.
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { searchCorpus, SEARCH_MODES } from "../corpus/searcher.js";
+export const QUERY_CLASSES = [
+    "semantic",
+    "fact",
+    "procedural",
+    "confusable",
+];
+export async function loadGold(filePath) {
+    const raw = await readFile(filePath, "utf8");
+    const lines = raw.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    const queries = [];
+    for (const line of lines) {
+        const q = JSON.parse(line);
+        if (!QUERY_CLASSES.includes(q.class)) {
+            throw new Error(`retrieval.jsonl: unknown class "${q.class}" on ${q.id}`);
+        }
+        queries.push(q);
+    }
+    return queries;
+}
+function pathMatches(hitPath, expected) {
+    // Expected paths in gold are basenames; hit paths are absolute. Compare by basename.
+    return basename(hitPath) === basename(expected);
+}
+function anyExpectedInTop(hits, expected, n) {
+    for (let i = 0; i < Math.min(n, hits.length); i++) {
+        for (const ex of expected) {
+            if (pathMatches(hits[i].path, ex))
+                return true;
+        }
+    }
+    return false;
+}
+function phrasesSatisfied(hits, expected, phrases) {
+    // Find every hit whose path matches an expected doc, and check
+    // whether any one of those hits' text contains all phrases.
+    for (const hit of hits) {
+        if (!expected.some((e) => pathMatches(hit.path, e)))
+            continue;
+        // Use preview text if available; otherwise we'd need the chunk store.
+        // Runner always passes preview_chars so this is populated.
+        const text = (hit.preview ?? "").toLowerCase();
+        if (phrases.every((p) => text.includes(p.toLowerCase())))
+            return true;
+    }
+    return false;
+}
+export async function runRetrievalEval(opts) {
+    const topK = opts.topK ?? 3;
+    const previewChars = opts.previewChars ?? 400;
+    const records = [];
+    for (const q of opts.gold) {
+        for (const mode of SEARCH_MODES) {
+            const hits = await searchCorpus({
+                corpus: opts.corpus,
+                query: q.query,
+                model: opts.model,
+                mode,
+                top_k: topK,
+                preview_chars: previewChars,
+                client: opts.client,
+            });
+            const hit1 = anyExpectedInTop(hits, q.expected_paths, 1);
+            const hit3 = anyExpectedInTop(hits, q.expected_paths, 3);
+            const phrasesHit = q.expected_phrases && q.expected_phrases.length > 0
+                ? phrasesSatisfied(hits, q.expected_paths, q.expected_phrases)
+                : null;
+            records.push({
+                id: q.id,
+                class: q.class,
+                query: q.query,
+                mode,
+                top_paths: hits.map((h) => basename(h.path)),
+                hit1,
+                hit3,
+                phrasesHit,
+            });
+        }
+    }
+    return records;
+}
+function emptyCell() {
+    return { n: 0, precision1: 0, precision3: 0 };
+}
+function accumulate(cell, r) {
+    cell.n += 1;
+    cell.precision1 += r.hit1 ? 1 : 0;
+    cell.precision3 += r.hit3 ? 1 : 0;
+}
+function finalize(cell) {
+    if (cell.n === 0)
+        return cell;
+    return {
+        n: cell.n,
+        precision1: cell.precision1 / cell.n,
+        precision3: cell.precision3 / cell.n,
+    };
+}
+export function summarizeEval(records) {
+    const overall = emptyCell();
+    const byMode = {};
+    const byModeByClass = {};
+    for (const m of SEARCH_MODES) {
+        byMode[m] = emptyCell();
+        byModeByClass[m] = {};
+        for (const c of QUERY_CLASSES)
+            byModeByClass[m][c] = emptyCell();
+    }
+    for (const r of records) {
+        accumulate(overall, r);
+        accumulate(byMode[r.mode], r);
+        accumulate(byModeByClass[r.mode][r.class], r);
+    }
+    return {
+        overall: finalize(overall),
+        byMode: Object.fromEntries(Object.entries(byMode).map(([k, v]) => [k, finalize(v)])),
+        byModeByClass: Object.fromEntries(Object.entries(byModeByClass).map(([m, classes]) => [
+            m,
+            Object.fromEntries(Object.entries(classes).map(([c, v]) => [c, finalize(v)])),
+        ])),
+    };
+}
+function pct(x) {
+    return (x * 100).toFixed(0).padStart(3, " ") + "%";
+}
+/**
+ * Markdown-friendly report suitable for console.log during tests. The
+ * shape is stable so it can be diffed between runs.
+ */
+export function formatEvalReport(summary) {
+    const lines = [];
+    lines.push("");
+    lines.push("## Retrieval eval — precision@1 / precision@3");
+    lines.push("");
+    lines.push("Per mode × class (n = queries in that class):");
+    lines.push("");
+    const header = ["mode".padEnd(11), ...QUERY_CLASSES.map((c) => c.padStart(14)), "overall".padStart(14)].join(" | ");
+    lines.push(header);
+    lines.push("-".repeat(header.length));
+    for (const mode of SEARCH_MODES) {
+        const cells = [mode.padEnd(11)];
+        for (const c of QUERY_CLASSES) {
+            const m = summary.byModeByClass[mode][c];
+            cells.push(`${pct(m.precision1)}/${pct(m.precision3)}`.padStart(14));
+        }
+        const o = summary.byMode[mode];
+        cells.push(`${pct(o.precision1)}/${pct(o.precision3)}`.padStart(14));
+        lines.push(cells.join(" | "));
+    }
+    lines.push("");
+    lines.push(`Overall across all modes: P@1 ${pct(summary.overall.precision1)}, P@3 ${pct(summary.overall.precision3)} (n=${summary.overall.n})`);
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/evals/retrieval.js.map

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

package/dist/guardrails/citations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Citation guardrail — `ollama_research` must only cite paths that were
+ * provided in its source_paths input. Anything else is a fabrication and
+ * gets stripped server-side before returning to the caller.
+ */
+export interface RawCitation {
+    path: string;
+    line_range?: string;
+}
+export interface ValidatedCitation {
+    path: string;
+    line_range?: string;
+}
+export interface CitationValidationResult {
+    valid: ValidatedCitation[];
+    stripped: RawCitation[];
+}
+/**
+ * Strip any citation whose path is not in allowedPaths.
+ * Comparison is on normalized paths — forward slashes, no leading ./.
+ */
+export declare function validateCitations(citations: RawCitation[], allowedPaths: string[]): CitationValidationResult;
+/**
+ * Extract citations from a model's free-text "Sources:" block.
+ * Accepts formats like `path.md:10-25` or `path.md (lines 10-25)`.
+ */
+export declare function parseCitations(text: string): RawCitation[];
+//# sourceMappingURL=citations.d.ts.map

package/dist/guardrails/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../../src/guardrails/citations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,WAAW,EAAE,EACxB,YAAY,EAAE,MAAM,EAAE,GACrB,wBAAwB,CAY1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAe1D"}

package/dist/guardrails/citations.js

@@ -0,0 +1,45 @@
+/**
+ * Citation guardrail — `ollama_research` must only cite paths that were
+ * provided in its source_paths input. Anything else is a fabrication and
+ * gets stripped server-side before returning to the caller.
+ */
+import { normalizePath } from "../protectedPaths.js";
+/**
+ * Strip any citation whose path is not in allowedPaths.
+ * Comparison is on normalized paths — forward slashes, no leading ./.
+ */
+export function validateCitations(citations, allowedPaths) {
+    const allowed = new Set(allowedPaths.map(normalizePath));
+    const valid = [];
+    const stripped = [];
+    for (const c of citations) {
+        if (allowed.has(normalizePath(c.path))) {
+            valid.push({ path: c.path, ...(c.line_range ? { line_range: c.line_range } : {}) });
+        }
+        else {
+            stripped.push(c);
+        }
+    }
+    return { valid, stripped };
+}
+/**
+ * Extract citations from a model's free-text "Sources:" block.
+ * Accepts formats like `path.md:10-25` or `path.md (lines 10-25)`.
+ */
+export function parseCitations(text) {
+    const lines = text.split("\n");
+    const citations = [];
+    const pathLine = /^[-*\s]*([^\s:()]+(?:\.[a-z0-9]+)?)(?::(\d+(?:-\d+)?)|\s*\(lines?\s+(\d+(?:-\d+)?)\))?/i;
+    for (const line of lines) {
+        const m = line.match(pathLine);
+        if (m) {
+            const path = m[1];
+            const range = m[2] || m[3];
+            if (path && (path.includes("/") || path.includes("."))) {
+                citations.push({ path, ...(range ? { line_range: range } : {}) });
+            }
+        }
+    }
+    return citations;
+}
+//# sourceMappingURL=citations.js.map

package/dist/guardrails/citations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.js","sourceRoot":"","sources":["../../src/guardrails/citations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiBrD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAwB,EACxB,YAAsB;IAEtB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACzD,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACtF,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,SAAS,GAAkB,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,yFAAyF,CAAC;IAC3G,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACvD,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/guardrails/compileCheck.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Compile check — after ollama_draft produces code, run a cheap checker
+ * and report {compiles, checker, stderr_tail} on the envelope.
+ *
+ * The stderr tail is the real value: a boolean tells you something broke,
+ * the tail tells you *what* so review is useful instead of just binary.
+ *
+ * Never throws — compile failure is data, not an error. The tool handler
+ * still returns the draft; the reviewer decides what to do.
+ */
+export type SupportedLanguage = "typescript" | "javascript" | "python" | "rust" | "go";
+export interface CompileCheckResult {
+    compiles: boolean;
+    checker: string;
+    stderr_tail: string;
+    skipped?: boolean;
+    skip_reason?: string;
+}
+export declare function compileCheck(code: string, language: string | undefined): Promise<CompileCheckResult>;
+//# sourceMappingURL=compileCheck.d.ts.map

package/dist/guardrails/compileCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileCheck.d.ts","sourceRoot":"","sources":["../../src/guardrails/compileCheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAuB7B"}

package/dist/guardrails/compileCheck.js

@@ -0,0 +1,96 @@
+/**
+ * Compile check — after ollama_draft produces code, run a cheap checker
+ * and report {compiles, checker, stderr_tail} on the envelope.
+ *
+ * The stderr tail is the real value: a boolean tells you something broke,
+ * the tail tells you *what* so review is useful instead of just binary.
+ *
+ * Never throws — compile failure is data, not an error. The tool handler
+ * still returns the draft; the reviewer decides what to do.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Last ~800 chars of stderr — enough for the interesting part without flooding the envelope. */
+const STDERR_TAIL_CHARS = 800;
+const CHECKER_TIMEOUT_MS = 15_000;
+export async function compileCheck(code, language) {
+    if (!language) {
+        return { compiles: false, checker: "none", stderr_tail: "", skipped: true, skip_reason: "no language specified" };
+    }
+    const lang = language.toLowerCase();
+    switch (lang) {
+        case "typescript":
+            // `npx -p typescript -- tsc ...` tells npx WHICH package provides the tsc
+            // binary. The old `npx -y typescript tsc` form treats "tsc" as an arg to
+            // a nonexistent "typescript" binary and fails with "could not determine
+            // executable to run" — found in the first live dogfood run.
+            return runChecker(code, ".ts", "npx", ["-p", "typescript", "--", "tsc", "--noEmit", "--target", "ES2022", "--module", "ESNext", "--moduleResolution", "node"]);
+        case "javascript":
+            return runChecker(code, ".js", "node", ["--check"]);
+        case "python":
+            return runChecker(code, ".py", "python", ["-m", "py_compile"]);
+        case "rust":
+            return runChecker(code, ".rs", "rustc", ["--edition", "2021", "--emit=metadata", "-o", "/dev/null"]);
+        case "go":
+            return runChecker(code, ".go", "gofmt", ["-e"]);
+        default:
+            return { compiles: false, checker: "none", stderr_tail: "", skipped: true, skip_reason: `unsupported language: ${language}` };
+    }
+}
+async function runChecker(code, ext, command, baseArgs) {
+    let dir = null;
+    try {
+        dir = await mkdtemp(join(tmpdir(), "intern-check-"));
+        const file = join(dir, `snippet${ext}`);
+        await writeFile(file, code, "utf8");
+        const args = [...baseArgs, file];
+        const { code: exitCode, stdout, stderr } = await runProcess(command, args, CHECKER_TIMEOUT_MS);
+        // tsc writes diagnostics to STDOUT, most other checkers to STDERR.
+        // Merge both so the tail is useful regardless of the tool's habits.
+        const diagnostics = [stderr, stdout].filter(Boolean).join("\n");
+        return {
+            compiles: exitCode === 0,
+            checker: `${command} ${baseArgs.join(" ")}`.trim(),
+            stderr_tail: tail(diagnostics, STDERR_TAIL_CHARS),
+        };
+    }
+    catch (err) {
+        return {
+            compiles: false,
+            checker: command,
+            stderr_tail: "",
+            skipped: true,
+            skip_reason: `checker unavailable: ${err.message}`,
+        };
+    }
+    finally {
+        if (dir)
+            await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+function runProcess(cmd, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const proc = spawn(cmd, args, { shell: process.platform === "win32" });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => proc.kill("SIGKILL"), timeoutMs);
+        proc.stdout?.on("data", (d) => (stdout += d.toString()));
+        proc.stderr?.on("data", (d) => (stderr += d.toString()));
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: -1, stdout, stderr: stderr + String(err) });
+        });
+        proc.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code: code ?? -1, stdout, stderr });
+        });
+    });
+}
+function tail(s, n) {
+    if (s.length <= n)
+        return s;
+    return "…" + s.slice(-n);
+}
+//# sourceMappingURL=compileCheck.js.map

package/dist/guardrails/compileCheck.js.map

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

package/dist/guardrails/confidence.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Confidence guardrail — `ollama_classify` returns a {label, confidence} shape.
+ * Below the threshold and with allow_none=true, we return label=null rather
+ * than let a weak guess propagate.
+ */
+export declare const DEFAULT_CONFIDENCE_THRESHOLD = 0.7;
+export interface ClassifyRaw {
+    label: string | null;
+    confidence: number;
+}
+export interface ClassifyGuarded {
+    label: string | null;
+    confidence: number;
+    below_threshold: boolean;
+    threshold: number;
+}
+export declare function applyConfidenceThreshold(raw: ClassifyRaw, opts?: {
+    threshold?: number;
+    allow_none?: boolean;
+}): ClassifyGuarded;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/guardrails/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../../src/guardrails/confidence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACtD,eAAe,CAUjB"}

package/dist/guardrails/confidence.js

@@ -0,0 +1,18 @@
+/**
+ * Confidence guardrail — `ollama_classify` returns a {label, confidence} shape.
+ * Below the threshold and with allow_none=true, we return label=null rather
+ * than let a weak guess propagate.
+ */
+export const DEFAULT_CONFIDENCE_THRESHOLD = 0.7;
+export function applyConfidenceThreshold(raw, opts = {}) {
+    const threshold = opts.threshold ?? DEFAULT_CONFIDENCE_THRESHOLD;
+    const belowThreshold = raw.confidence < threshold;
+    const label = belowThreshold && opts.allow_none ? null : raw.label;
+    return {
+        label,
+        confidence: raw.confidence,
+        below_threshold: belowThreshold,
+        threshold,
+    };
+}
+//# sourceMappingURL=confidence.js.map

package/dist/guardrails/confidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.js","sourceRoot":"","sources":["../../src/guardrails/confidence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAchD,MAAM,UAAU,wBAAwB,CACtC,GAAgB,EAChB,OAAqD,EAAE;IAEvD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,4BAA4B,CAAC;IACjE,MAAM,cAAc,GAAG,GAAG,CAAC,UAAU,GAAG,SAAS,CAAC;IAClD,MAAM,KAAK,GAAG,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IACnE,OAAO;QACL,KAAK;QACL,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,eAAe,EAAE,cAAc;QAC/B,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/guardrails/timeouts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Timeout + fallback guardrail.
+ *
+ * Every tier has a hard timeout (see TIER_TIMEOUT_MS). When the timeout
+ * fires, we log the timeout event, decide whether to fall back to a
+ * cheaper tier, log the fallback decision, and re-run.
+ *
+ * Both events land in the NDJSON log. Later this is what proves the
+ * system degraded correctly under pressure, not just that a call was slow.
+ */
+import { type Tier } from "../tiers.js";
+import type { Logger } from "../observability.js";
+export interface RunWithTimeoutInput<T> {
+    tool: string;
+    tier: Tier;
+    run: (tier: Tier, signal: AbortSignal) => Promise<T>;
+    logger: Logger;
+    /** If true, cascade through TIER_FALLBACK on timeout. Default true. */
+    allowFallback?: boolean;
+    /** Override timeouts per tier. Production leaves this undefined; tests inject short values. */
+    timeoutOverrideMs?: Partial<Record<Tier, number>>;
+}
+export interface RunWithTimeoutResult<T> {
+    value: T;
+    actualTier: Tier;
+    fallbackFrom?: Tier;
+}
+/**
+ * Run `run(tier)` with the tier's timeout. On timeout:
+ *   1. log a "timeout" event
+ *   2. if TIER_FALLBACK[tier] exists and allowFallback, log a "fallback" event and retry
+ *   3. if no fallback or fallback also times out, throw TIER_TIMEOUT
+ */
+export declare function runWithTimeoutAndFallback<T>(input: RunWithTimeoutInput<T>): Promise<RunWithTimeoutResult<T>>;
+//# sourceMappingURL=timeouts.d.ts.map

package/dist/guardrails/timeouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/guardrails/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAkC,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGlD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC;IACT,UAAU,EAAE,IAAI,CAAC;IACjB,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAwClC"}

package/dist/guardrails/timeouts.js

@@ -0,0 +1,58 @@
+/**
+ * Timeout + fallback guardrail.
+ *
+ * Every tier has a hard timeout (see TIER_TIMEOUT_MS). When the timeout
+ * fires, we log the timeout event, decide whether to fall back to a
+ * cheaper tier, log the fallback decision, and re-run.
+ *
+ * Both events land in the NDJSON log. Later this is what proves the
+ * system degraded correctly under pressure, not just that a call was slow.
+ */
+import { InternError } from "../errors.js";
+import { TIER_FALLBACK, TIER_TIMEOUT_MS } from "../tiers.js";
+import { timestamp } from "../observability.js";
+/**
+ * Run `run(tier)` with the tier's timeout. On timeout:
+ *   1. log a "timeout" event
+ *   2. if TIER_FALLBACK[tier] exists and allowFallback, log a "fallback" event and retry
+ *   3. if no fallback or fallback also times out, throw TIER_TIMEOUT
+ */
+export async function runWithTimeoutAndFallback(input) {
+    const allowFallback = input.allowFallback ?? true;
+    return attempt(input.tier, undefined);
+    async function attempt(tier, fallbackFrom) {
+        const controller = new AbortController();
+        const timeoutMs = input.timeoutOverrideMs?.[tier] ?? TIER_TIMEOUT_MS[tier];
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const value = await input.run(tier, controller.signal);
+            return { value, actualTier: tier, ...(fallbackFrom ? { fallbackFrom } : {}) };
+        }
+        catch (err) {
+            if (!timedOut)
+                throw err;
+            await input.logger.log({ kind: "timeout", ts: timestamp(), tool: input.tool, tier, timeout_ms: timeoutMs });
+            const next = allowFallback ? TIER_FALLBACK[tier] : null;
+            if (!next) {
+                throw new InternError("TIER_TIMEOUT", `Tool ${input.tool} exceeded ${timeoutMs}ms on tier ${tier} with no fallback available`, "Increase the tier's timeout, reduce input size, or ensure the model is resident (check /api/ps).", true);
+            }
+            await input.logger.log({
+                kind: "fallback",
+                ts: timestamp(),
+                tool: input.tool,
+                from: tier,
+                to: next,
+                reason: `timeout after ${timeoutMs}ms`,
+            });
+            return attempt(next, fallbackFrom ?? tier);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=timeouts.js.map

package/dist/guardrails/timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../../src/guardrails/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAa,MAAM,aAAa,CAAC;AAExE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAmBhD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAA6B;IAE7B,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,IAAI,CAAC;IAClD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAEtC,KAAK,UAAU,OAAO,CAAC,IAAU,EAAE,YAA8B;QAC/D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;QAC3E,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,QAAQ,GAAG,IAAI,CAAC;YAChB,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;YACvD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAChF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ;gBAAE,MAAM,GAAG,CAAC;YACzB,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;YAC5G,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACxD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,WAAW,CACnB,cAAc,EACd,QAAQ,KAAK,CAAC,IAAI,aAAa,SAAS,cAAc,IAAI,6BAA6B,EACvF,kGAAkG,EAClG,IAAI,CACL,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;gBACrB,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,SAAS,EAAE;gBACf,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,IAAI;gBACV,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,iBAAiB,SAAS,IAAI;aACvC,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,IAAI,EAAE,YAAY,IAAI,IAAI,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/guardrails/writeConfirm.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Write-confirm guardrail — refuses drafts targeting protected paths
+ * unless the caller explicitly sets confirm_write: true.
+ *
+ * Uses the versioned list in ../protectedPaths.ts. Never accept a
+ * path-list argument here — that would let callers sidestep the policy.
+ */
+export interface WriteConfirmCheckInput {
+    target_path: string | undefined;
+    confirm_write: boolean | undefined;
+}
+export interface WriteConfirmResult {
+    /** True when a write was blocked; handler must refuse. */
+    blocked: boolean;
+    /** Reason for block, for logging. */
+    reason?: string;
+    /** Matched protected pattern, for logging. */
+    pattern?: string;
+    /** Version of the protected-path list that evaluated this call. */
+    rules_version: number;
+}
+export declare function checkWriteConfirm(input: WriteConfirmCheckInput): WriteConfirmResult;
+/** Throw the structured error to refuse. Handlers call this after logging. */
+export declare function assertWriteAllowed(input: WriteConfirmCheckInput): void;
+//# sourceMappingURL=writeConfirm.d.ts.map

package/dist/guardrails/writeConfirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeConfirm.d.ts","sourceRoot":"","sources":["../../src/guardrails/writeConfirm.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,kBAAkB,CAiBnF;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAUtE"}

package/dist/guardrails/writeConfirm.js

@@ -0,0 +1,35 @@
+/**
+ * Write-confirm guardrail — refuses drafts targeting protected paths
+ * unless the caller explicitly sets confirm_write: true.
+ *
+ * Uses the versioned list in ../protectedPaths.ts. Never accept a
+ * path-list argument here — that would let callers sidestep the policy.
+ */
+import { InternError } from "../errors.js";
+import { matchesProtectedPath, PROTECTED_PATHS_VERSION } from "../protectedPaths.js";
+export function checkWriteConfirm(input) {
+    if (!input.target_path) {
+        return { blocked: false, rules_version: PROTECTED_PATHS_VERSION };
+    }
+    const match = matchesProtectedPath(input.target_path);
+    if (!match.protected) {
+        return { blocked: false, rules_version: PROTECTED_PATHS_VERSION };
+    }
+    if (input.confirm_write === true) {
+        return { blocked: false, rules_version: PROTECTED_PATHS_VERSION };
+    }
+    return {
+        blocked: true,
+        reason: match.rule?.reason ?? "Protected path",
+        pattern: match.rule?.pattern,
+        rules_version: PROTECTED_PATHS_VERSION,
+    };
+}
+/** Throw the structured error to refuse. Handlers call this after logging. */
+export function assertWriteAllowed(input) {
+    const r = checkWriteConfirm(input);
+    if (r.blocked) {
+        throw new InternError("PROTECTED_PATH_WRITE", `Refusing draft targeting protected path "${input.target_path}" (${r.pattern}): ${r.reason}`, "If you really mean to touch this path, re-call with confirm_write: true and review the diff carefully.", false);
+    }
+}
+//# sourceMappingURL=writeConfirm.js.map

package/dist/guardrails/writeConfirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeConfirm.js","sourceRoot":"","sources":["../../src/guardrails/writeConfirm.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAkBrF,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;IACpE,CAAC;IACD,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,KAAK,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;IACpE,CAAC;IACD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,IAAI,gBAAgB;QAC9C,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO;QAC5B,aAAa,EAAE,uBAAuB;KACvC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,KAA6B;IAC9D,MAAM,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,IAAI,WAAW,CACnB,sBAAsB,EACtB,4CAA4C,KAAK,CAAC,WAAW,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,EAAE,EAC5F,wGAAwG,EACxG,KAAK,CACN,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Ollama Intern MCP — entrypoint.
+ *
+ * Registers the 8-tool labor surface. Tool descriptions encode *when* to reach
+ * for them — Claude picks the tier by picking the tool, and the tool implies
+ * the model. ollama_chat is visibly last-resort.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RunContext } from "./runContext.js";
+export declare function createServer(ctx: RunContext): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAoClD,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CA6OvD"}