@polderlabs/bizar 9.0.0 → 10.0.7

package/packages/sdk/dist/memory/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Bizar Memory Vault — Claude Code-native re-export of the
+ * Obsidian-compatible memory vault. This is the same implementation that
+ * previously lived at plugins/bizar/src/memory-vault.ts; it's framework-
+ * agnostic so we lifted it into the SDK so that:
+ *
+ *  - The Claude Code MCP server (packages/sdk/src/mcp/server.ts) reads
+ *    and writes memory in-process.
+ *  - The bizar-dash dashboard imports the same code so the on-disk vault
+ *    stays the single source of truth.
+ *
+ * Vault location: $BIZAR_MEMORY_VAULT or ~/.bizar_memory/ (default).
+ * Legacy: ~/.local/share/bizar/memory/ (still readable if it exists).
+ */
+export declare const DEFAULT_MEMORY_VAULT: string;
+export declare const LEGACY_MEMORY_VAULT: string;
+export declare function resolveVaultRoot(): string;
+export interface MemoryNote {
+    relPath: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+    raw: string;
+    mtime: number;
+    size: number;
+}
+/** Parse YAML frontmatter from a markdown note. Minimal parser — no nested
+ *  structures, no multi-line values, no comments. Sufficient for the
+ *  tags / type / title / createdAt metadata that the dashboard writes. */
+export declare function parseFrontmatter(raw: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/** Serialize frontmatter back to markdown. */
+export declare function serializeFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
+/** Read a single note. Returns null if not found. */
+export declare function readNote(vaultRoot: string, relPath: string): MemoryNote | null;
+/** Write a note. Creates the parent directory if needed. */
+export declare function writeNote(vaultRoot: string, relPath: string, frontmatter: Record<string, unknown>, body: string): MemoryNote;
+/** List notes matching a prefix. */
+export declare function listNotes(vaultRoot: string, prefix?: string, limit?: number): MemoryNote[];
+/** Full-text search over note bodies + frontmatter. */
+export declare function searchNotes(vaultRoot: string, query: string, limit?: number): MemoryNote[];
+//# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/memory/index.js

@@ -0,0 +1,159 @@
+/**
+ * Bizar Memory Vault — Claude Code-native re-export of the
+ * Obsidian-compatible memory vault. This is the same implementation that
+ * previously lived at plugins/bizar/src/memory-vault.ts; it's framework-
+ * agnostic so we lifted it into the SDK so that:
+ *
+ *  - The Claude Code MCP server (packages/sdk/src/mcp/server.ts) reads
+ *    and writes memory in-process.
+ *  - The bizar-dash dashboard imports the same code so the on-disk vault
+ *    stays the single source of truth.
+ *
+ * Vault location: $BIZAR_MEMORY_VAULT or ~/.bizar_memory/ (default).
+ * Legacy: ~/.local/share/bizar/memory/ (still readable if it exists).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { homedir } from "node:os";
+const HOME = homedir();
+export const DEFAULT_MEMORY_VAULT = join(HOME, ".bizar_memory");
+export const LEGACY_MEMORY_VAULT = join(HOME, ".local", "share", "bizar", "memory");
+export function resolveVaultRoot() {
+    return process.env.BIZAR_MEMORY_VAULT || DEFAULT_MEMORY_VAULT;
+}
+/** Parse YAML frontmatter from a markdown note. Minimal parser — no nested
+ *  structures, no multi-line values, no comments. Sufficient for the
+ *  tags / type / title / createdAt metadata that the dashboard writes. */
+export function parseFrontmatter(raw) {
+    if (!raw.startsWith("---"))
+        return { frontmatter: {}, body: raw };
+    const end = raw.indexOf("\n---", 3);
+    if (end < 0)
+        return { frontmatter: {}, body: raw };
+    const fmBlock = raw.slice(3, end).trim();
+    const body = raw.slice(end + 4).replace(/^\n/, "");
+    const frontmatter = {};
+    for (const line of fmBlock.split(/\r?\n/)) {
+        const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!m)
+            continue;
+        const key = m[1];
+        let value = m[2];
+        value = value.trim();
+        if (value.startsWith("[") && value.endsWith("]")) {
+            value = value.slice(1, -1).split(",").map((s) => s.trim()).filter(Boolean);
+        }
+        else if (value === "true")
+            value = "true";
+        else if (value === "false")
+            value = "false";
+        frontmatter[key] = value;
+    }
+    return { frontmatter, body };
+}
+/** Serialize frontmatter back to markdown. */
+export function serializeFrontmatter(frontmatter, body) {
+    const lines = ["---"];
+    for (const [k, v] of Object.entries(frontmatter)) {
+        if (Array.isArray(v))
+            lines.push(`${k}: [${v.join(", ")}]`);
+        else
+            lines.push(`${k}: ${String(v)}`);
+    }
+    lines.push("---", "", body.startsWith("\n") ? body : body);
+    return lines.join("\n");
+}
+/** Read a single note. Returns null if not found. */
+export function readNote(vaultRoot, relPath) {
+    const safe = relPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (safe.includes("..") || safe.startsWith("."))
+        return null;
+    const fp = join(vaultRoot, safe);
+    if (!existsSync(fp))
+        return null;
+    const raw = readFileSync(fp, "utf-8");
+    const st = statSync(fp);
+    const { frontmatter, body } = parseFrontmatter(raw);
+    return { relPath: safe, frontmatter, body, raw, mtime: st.mtimeMs, size: st.size };
+}
+/** Write a note. Creates the parent directory if needed. */
+export function writeNote(vaultRoot, relPath, frontmatter, body) {
+    const safe = relPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (safe.includes("..") || safe.startsWith(".")) {
+        throw new Error(`invalid_path: ${relPath}`);
+    }
+    const fp = join(vaultRoot, safe);
+    mkdirSync(join(fp, ".."), { recursive: true });
+    const raw = serializeFrontmatter(frontmatter, body);
+    writeFileSync(fp, raw, "utf-8");
+    const st = statSync(fp);
+    return { relPath: safe, frontmatter, body, raw, mtime: st.mtimeMs, size: st.size };
+}
+/** List notes matching a prefix. */
+export function listNotes(vaultRoot, prefix = "", limit = 100) {
+    if (!existsSync(vaultRoot))
+        return [];
+    const out = [];
+    walk(vaultRoot, vaultRoot, out, limit, prefix);
+    return out;
+}
+function walk(root, dir, out, limit, prefix) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (out.length >= limit)
+            return;
+        const fp = join(dir, name);
+        let st;
+        try {
+            st = statSync(fp);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            if (name === ".obsidian" || name === ".git")
+                continue;
+            walk(root, fp, out, limit, prefix);
+        }
+        else if (name.endsWith(".md")) {
+            const rel = relative(root, fp).split(sep).join("/");
+            if (prefix && !rel.startsWith(prefix))
+                continue;
+            const note = readNote(root, rel);
+            if (note)
+                out.push(note);
+        }
+    }
+}
+/** Full-text search over note bodies + frontmatter. */
+export function searchNotes(vaultRoot, query, limit = 20) {
+    const q = query.toLowerCase();
+    const notes = listNotes(vaultRoot, "", 1000);
+    const out = [];
+    for (const note of notes) {
+        const haystack = (note.body + "\n" + Object.values(note.frontmatter).join(" ")).toLowerCase();
+        const score = countOccurrences(haystack, q);
+        if (score > 0)
+            out.push({ note, score });
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out.slice(0, limit).map((o) => o.note);
+}
+function countOccurrences(haystack, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    let idx = 0;
+    while ((idx = haystack.indexOf(needle, idx)) >= 0) {
+        count += 1;
+        idx += needle.length;
+    }
+    return count;
+}
+//# sourceMappingURL=index.js.map

package/packages/sdk/dist/router/codemod-intent.d.ts

@@ -0,0 +1,68 @@
+/**
+ * router/codemod-intent.ts — Tier-1 codemod intent detection.
+ *
+ * v6.4.0 — ported from ruflo `enhanced-model-router.ts` (ADR-026, ADR-143).
+ *
+ * Three deterministic intents are eligible for $0 Tier-1 codemod
+ * execution — they can be applied structurally, no LLM in the loop:
+ *
+ *   - `var-to-const`   — convert `var` declarations to `const` / `let`.
+ *   - `remove-console` — strip `console.*` calls.
+ *   - `add-logging`    — add `console.*` / logger statements.
+ *
+ * Other intents (`add-types`, `add-error-handling`, `async-await`, …)
+ * REQUIRE judgement and route to a model tier (Tier-2/3); they are
+ * explicitly OUT OF SCOPE for this detector. See ADR-143.
+ *
+ * Pure function — no I/O. Confidence is the match strength
+ * (number of distinct regex patterns that hit, normalised by pattern
+ * count; capped at 1.0). Returning `null` means the prompt is NOT
+ * codemod-eligible and the caller should consult the bandit / neural
+ * router.
+ */
+export type CodemodIntent = "var-to-const" | "remove-console" | "add-logging";
+export interface CodemodIntentHit {
+    intent: CodemodIntent;
+    confidence: number;
+}
+/**
+ * Default confidence threshold for `detectCodemodIntent`. The function
+ * returns `null` for pattern-set hits with confidence below this.
+ *
+ * Kept intentionally low (0.1) so a single canonical phrase on a
+ * 7-pattern intent — natural prompts like "convert var to const" —
+ * still short-circuits the bandit. Callers that want stricter
+ * filtering (the F-033 orchestrator `decideAgentWith`, see ADR-174)
+ * can pass `threshold` explicitly.
+ *
+ * Strong threshold the spec mentions ("Return null if confidence < 0.6")
+ * is exported as `STRICT_CODEMOD_CONFIDENCE_THRESHOLD` below.
+ */
+export declare const DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD = 0.1;
+export declare const STRICT_CODEMOD_CONFIDENCE_THRESHOLD = 0.6;
+/** Alias used in the spec — kept for backwards compat. */
+export declare const CODEMOD_CONFIDENCE_THRESHOLD = 0.1;
+export interface CodemodDetectionOptions {
+    /** Override the threshold. Default:
+     *  `DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD` (=0.1). */
+    threshold?: number;
+}
+/**
+ * Probe whether a prompt matches one of the deterministic codemod
+ * intents. Order matters only for tie-breaking: we return the FIRST
+ * intent whose overall score is highest in case of a multi-intent
+ * tie.
+ *
+ * Confidence is `hits / patterns.length`. A single regex hit on a
+ * intent with 7 patterns yields confidence 1/7 ≈ 0.14 — enough to
+ * flag the intent but well below 1.0 so the caller can decide
+ * whether to escalate. Two hits on a smaller intent (say 4
+ * patterns) yields 0.5 — past the 0.4 bandit-confirmation
+ * threshold.
+ *
+ * Result filtered by `opts.threshold` (default 0.1). When the
+ * strongest pattern-set hit is below the threshold the function
+ * returns `null` so the caller falls through to Q-learning / bandit.
+ */
+export declare function detectCodemodIntent(prompt: string, opts?: CodemodDetectionOptions): CodemodIntentHit | null;
+//# sourceMappingURL=codemod-intent.d.ts.map

package/packages/sdk/dist/router/codemod-intent.js

@@ -0,0 +1,112 @@
+/**
+ * router/codemod-intent.ts — Tier-1 codemod intent detection.
+ *
+ * v6.4.0 — ported from ruflo `enhanced-model-router.ts` (ADR-026, ADR-143).
+ *
+ * Three deterministic intents are eligible for $0 Tier-1 codemod
+ * execution — they can be applied structurally, no LLM in the loop:
+ *
+ *   - `var-to-const`   — convert `var` declarations to `const` / `let`.
+ *   - `remove-console` — strip `console.*` calls.
+ *   - `add-logging`    — add `console.*` / logger statements.
+ *
+ * Other intents (`add-types`, `add-error-handling`, `async-await`, …)
+ * REQUIRE judgement and route to a model tier (Tier-2/3); they are
+ * explicitly OUT OF SCOPE for this detector. See ADR-143.
+ *
+ * Pure function — no I/O. Confidence is the match strength
+ * (number of distinct regex patterns that hit, normalised by pattern
+ * count; capped at 1.0). Returning `null` means the prompt is NOT
+ * codemod-eligible and the caller should consult the bandit / neural
+ * router.
+ */
+const PATTERNS = {
+    "var-to-const": [
+        /convert\s+var\s+to\s+const/i,
+        /convert\s+var\s+declarations?\s+to\s+const/i,
+        /change\s+var\s+to\s+const/i,
+        /change\s+var\s+declarations?\s+to\s+const/i,
+        /replace\s+var\s+with\s+const/i,
+        /var\s*(?:→|->|to)\s*const/i,
+        /use\s+const\s+instead\s+of\s+var/i,
+        /\bvar\s+to\s+const\b/i,
+    ],
+    "remove-console": [
+        /remove\s+(?:all\s+)?console\.log/i,
+        /remove\s+(?:all\s+)?console\s+statements?/i,
+        /delete\s+(?:all\s+)?console\s+statements?/i,
+        /strip\s+console/i,
+        /clean\s+up\s+console/i,
+        /clean\s+up\s+debug\s+logs?/i,
+        /remove\s+(?:all\s+)?debug\s+logs?/i,
+        /delete\s+(?:all\s+)?console\.log/i,
+        /strip\s+(?:all\s+)?console/i,
+    ],
+    "add-logging": [
+        /\badd\s+logging\b/i,
+        /\badd\s+console\.log\b/i,
+        /\badd\s+debug\s+logs?\b/i,
+        /\blog\s+this\s+function\b/i,
+        /\badd\s+trace\s+logging\b/i,
+        /\binstrument\s+with\s+logs?\b/i,
+    ],
+};
+/**
+ * Default confidence threshold for `detectCodemodIntent`. The function
+ * returns `null` for pattern-set hits with confidence below this.
+ *
+ * Kept intentionally low (0.1) so a single canonical phrase on a
+ * 7-pattern intent — natural prompts like "convert var to const" —
+ * still short-circuits the bandit. Callers that want stricter
+ * filtering (the F-033 orchestrator `decideAgentWith`, see ADR-174)
+ * can pass `threshold` explicitly.
+ *
+ * Strong threshold the spec mentions ("Return null if confidence < 0.6")
+ * is exported as `STRICT_CODEMOD_CONFIDENCE_THRESHOLD` below.
+ */
+export const DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD = 0.1;
+export const STRICT_CODEMOD_CONFIDENCE_THRESHOLD = 0.6;
+/** Alias used in the spec — kept for backwards compat. */
+export const CODEMOD_CONFIDENCE_THRESHOLD = DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD;
+/**
+ * Probe whether a prompt matches one of the deterministic codemod
+ * intents. Order matters only for tie-breaking: we return the FIRST
+ * intent whose overall score is highest in case of a multi-intent
+ * tie.
+ *
+ * Confidence is `hits / patterns.length`. A single regex hit on a
+ * intent with 7 patterns yields confidence 1/7 ≈ 0.14 — enough to
+ * flag the intent but well below 1.0 so the caller can decide
+ * whether to escalate. Two hits on a smaller intent (say 4
+ * patterns) yields 0.5 — past the 0.4 bandit-confirmation
+ * threshold.
+ *
+ * Result filtered by `opts.threshold` (default 0.1). When the
+ * strongest pattern-set hit is below the threshold the function
+ * returns `null` so the caller falls through to Q-learning / bandit.
+ */
+export function detectCodemodIntent(prompt, opts = {}) {
+    if (!prompt || typeof prompt !== "string")
+        return null;
+    let best = null;
+    for (const intent of Object.keys(PATTERNS)) {
+        const patterns = PATTERNS[intent];
+        let hits = 0;
+        for (const p of patterns)
+            if (p.test(prompt))
+                hits += 1;
+        if (hits === 0)
+            continue;
+        const confidence = hits / patterns.length;
+        if (best === null || confidence > best.confidence) {
+            best = { intent, confidence };
+        }
+    }
+    if (best === null)
+        return null;
+    const threshold = opts.threshold ?? DEFAULT_CODEMOD_CONFIDENCE_THRESHOLD;
+    if (best.confidence < threshold)
+        return null;
+    return best;
+}
+//# sourceMappingURL=codemod-intent.js.map

package/packages/sdk/dist/router/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * router/index.ts — orchestrator for Bizar's self-learning router.
+ *
+ * v6.4.0 — F-033. Composes the three sub-routers
+ * (`codemod-intent`, `model-router`, `q-learning-router`) into a
+ * single precedence chain:
+ *
+ *     explicit-route (caller-provided) >
+ *       codemod-intent ($0 Tier-1 short-circuit) >
+ *         q-learning-router (8-action agent pick) >
+ *           model-router (Thompson bandit for tier) >
+ *             default ("odin", "mid", confidence 0.5)
+ *
+ * The orchestrator is what the `hooks_route` MCP tool (and any
+ * in-process caller such as the Odin agent) calls to make a routing
+ * decision. It surfaces two human-readable tags on `stdout`-equivalent
+ * surfaces:
+ *
+ *   - `[CODEMOD_AVAILABLE] <intent>` — printed BEFORE the model call
+ *     would happen, telling the model that a deterministic $0 codemod
+ *     could short-circuit the work. Honoured by the Odin prompt.
+ *   - `[TASK_MODEL_RECOMMENDATION] <tier> (conf=<n>)` — appended to
+ *     prompt-side telemetry so downstream model selection knows the
+ *     bandit-learner thinks this task should be routed to `flash` /
+ *     `mid` / `expensive`.
+ *
+ * Persistence: when constructed via `getRouter({ persist: true })`,
+ * the orchestrator holds a single shared `ModelRouter` +
+ * `QLearningRouter` whose state lives at `.harness/router-state.json`
+ * and `.harness/q-router-state.json` respectively. Callers can also
+ * pass `modelRouter` / `qRouter` for in-memory-only operation
+ * (preferred in tests).
+ */
+import { type CodemodIntent } from "./codemod-intent.js";
+import { ModelRouter, type ModelTier, type RouteDecision } from "./model-router.js";
+import { QLearningRouter } from "./q-learning-router.js";
+export interface RouteInput {
+    task: string;
+    /** Caller-provided explicit override for the agent (highest precedence). */
+    explicitAgent?: string;
+    /** Optional embedding — currently ignored (reserved for future ANN
+     *  lookup that could refine the state bucket). */
+    embedding?: number[];
+}
+export interface RouteDecisionOutput {
+    agent: string;
+    modelTier: ModelTier;
+    agentConfidence: number;
+    modelConfidence: number;
+    /** Null unless the prompt matched a Tier-1 codemod intent. */
+    codemodIntent: CodemodIntent | null;
+    /** `[CODEMOD_AVAILABLE] var-to-const` style surface for prompt pre-injection. */
+    surfacedTags: string[];
+}
+export interface RouterBundle {
+    modelRouter: ModelRouter;
+    qRouter: QLearningRouter;
+    decideAgent(input: RouteInput): RouteDecisionOutput;
+    /** Persist both routers to `path`'s sibling state files. */
+    saveTo(path: string): void;
+}
+export interface GetRouterOpts {
+    /** When provided, the orchestrator attempts to load priors + Q-table
+     *  from `<basePath>.{model,q}` if those files exist; missing files
+     *  fall back to defaults. */
+    basePath?: string;
+    /** In-memory overrides — useful for tests. */
+    modelRouter?: ModelRouter;
+    qRouter?: QLearningRouter;
+}
+/** Default state-file paths (kept beside the orchestrator's caller). */
+export declare const DEFAULT_MODEL_STATE_PATH = ".harness/router-state.json";
+export declare const DEFAULT_Q_STATE_PATH = ".harness/q-router-state.json";
+/**
+ * Build (or rehydrate) a router bundle.
+ *
+ * Default state files are stored under `.harness/` in the current
+ * working directory. Tests typically pass `modelRouter` / `qRouter`
+ * to keep things in-process.
+ */
+export declare function getRouter(opts?: GetRouterOpts): RouterBundle;
+/**
+ * Pure, testable entry point — the actual precedence chain.
+ *
+ * Order:
+ *  1. caller-supplied `explicitAgent` wins outright.
+ *  2. Tier-1 codemod intent → agent="heimdall" (routine implementation),
+ *     tier="flash" ($0), confidence 1.0, surface `[CODEMOD_AVAILABLE]`.
+ *  3. Q-learning agent pick (clamped to known agent names).
+ *  4. Thompson-bandit model-tier pick.
+ *  5. Defaults: agent="odin", tier="mid".
+ */
+export declare function decideAgentWith(modelRouter: ModelRouter, qRouter: QLearningRouter, input: RouteInput): RouteDecisionOutput;
+export declare function codemodTag(intent: CodemodIntent, confidence: number): string;
+export declare function tierTag(decision: RouteDecision): string;
+export { detectCodemodIntent, CODEMOD_CONFIDENCE_THRESHOLD, } from "./codemod-intent.js";
+export type { CodemodIntent, CodemodIntentHit } from "./codemod-intent.js";
+export { ModelRouter, type ModelTier, type RouteDecision, } from "./model-router.js";
+export { QLearningRouter, AGENT_ACTIONS, type AgentName, type AgentRouteDecision, } from "./q-learning-router.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/router/index.js

@@ -0,0 +1,149 @@
+/**
+ * router/index.ts — orchestrator for Bizar's self-learning router.
+ *
+ * v6.4.0 — F-033. Composes the three sub-routers
+ * (`codemod-intent`, `model-router`, `q-learning-router`) into a
+ * single precedence chain:
+ *
+ *     explicit-route (caller-provided) >
+ *       codemod-intent ($0 Tier-1 short-circuit) >
+ *         q-learning-router (8-action agent pick) >
+ *           model-router (Thompson bandit for tier) >
+ *             default ("odin", "mid", confidence 0.5)
+ *
+ * The orchestrator is what the `hooks_route` MCP tool (and any
+ * in-process caller such as the Odin agent) calls to make a routing
+ * decision. It surfaces two human-readable tags on `stdout`-equivalent
+ * surfaces:
+ *
+ *   - `[CODEMOD_AVAILABLE] <intent>` — printed BEFORE the model call
+ *     would happen, telling the model that a deterministic $0 codemod
+ *     could short-circuit the work. Honoured by the Odin prompt.
+ *   - `[TASK_MODEL_RECOMMENDATION] <tier> (conf=<n>)` — appended to
+ *     prompt-side telemetry so downstream model selection knows the
+ *     bandit-learner thinks this task should be routed to `flash` /
+ *     `mid` / `expensive`.
+ *
+ * Persistence: when constructed via `getRouter({ persist: true })`,
+ * the orchestrator holds a single shared `ModelRouter` +
+ * `QLearningRouter` whose state lives at `.harness/router-state.json`
+ * and `.harness/q-router-state.json` respectively. Callers can also
+ * pass `modelRouter` / `qRouter` for in-memory-only operation
+ * (preferred in tests).
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { detectCodemodIntent, CODEMOD_CONFIDENCE_THRESHOLD, } from "./codemod-intent.js";
+import { ModelRouter, } from "./model-router.js";
+import { QLearningRouter, AGENT_ACTIONS, } from "./q-learning-router.js";
+/** Default state-file paths (kept beside the orchestrator's caller). */
+export const DEFAULT_MODEL_STATE_PATH = ".harness/router-state.json";
+export const DEFAULT_Q_STATE_PATH = ".harness/q-router-state.json";
+/**
+ * Build (or rehydrate) a router bundle.
+ *
+ * Default state files are stored under `.harness/` in the current
+ * working directory. Tests typically pass `modelRouter` / `qRouter`
+ * to keep things in-process.
+ */
+export function getRouter(opts = {}) {
+    const basePath = opts.basePath ?? join(process.cwd(), ".harness", "router-state");
+    const modelPath = `${basePath}.model`;
+    const qPath = `${basePath}.q`;
+    const modelRouter = opts.modelRouter ??
+        (existsSync(modelPath) ? ModelRouter.loadFrom(modelPath) : new ModelRouter());
+    const qRouter = opts.qRouter ??
+        (existsSync(qPath) ? QLearningRouter.loadFrom(qPath) : new QLearningRouter());
+    return {
+        modelRouter,
+        qRouter,
+        decideAgent(input) {
+            return decideAgentWith(modelRouter, qRouter, input);
+        },
+        saveTo(path) {
+            const fp = isAbsolute(path) ? path : resolve(path);
+            mkdirSync(dirname(fp), { recursive: true });
+            modelRouter.saveTo(modelPath);
+            qRouter.saveTo(qPath);
+            // And a tiny pointer file for callers that only know the bundle name.
+            writeFileSync(fp, JSON.stringify({ modelPath, qPath, version: 1 }, null, 2), "utf-8");
+        },
+    };
+}
+/**
+ * Pure, testable entry point — the actual precedence chain.
+ *
+ * Order:
+ *  1. caller-supplied `explicitAgent` wins outright.
+ *  2. Tier-1 codemod intent → agent="heimdall" (routine implementation),
+ *     tier="flash" ($0), confidence 1.0, surface `[CODEMOD_AVAILABLE]`.
+ *  3. Q-learning agent pick (clamped to known agent names).
+ *  4. Thompson-bandit model-tier pick.
+ *  5. Defaults: agent="odin", tier="mid".
+ */
+export function decideAgentWith(modelRouter, qRouter, input) {
+    const task = String(input?.task ?? "");
+    const surfacedTags = [];
+    // 1. Explicit override — highest precedence.
+    if (input.explicitAgent && AGENT_ACTIONS.includes(input.explicitAgent)) {
+        // Still pick a model tier (bandit) so we can surface
+        // [TASK_MODEL_RECOMMENDATION] downstream.
+        const tier = modelRouter.route(task);
+        surfacedTags.push(tierTag(tier));
+        return {
+            agent: input.explicitAgent,
+            modelTier: tier.tier,
+            agentConfidence: 1.0,
+            modelConfidence: tier.confidence,
+            codemodIntent: null,
+            surfacedTags,
+        };
+    }
+    // 2. Codemod short-circuit (only when there's a task string).
+    const cm = task ? detectCodemodIntent(task) : null;
+    if (cm !== null) {
+        surfacedTags.push(codemodTag(cm.intent, cm.confidence));
+        // Tier-1 codemod: $0, model tier = "flash" but the call is
+        // supposed to be skipped (deterministic). We still set
+        // modelTier/Confidence so downstream telemetry has consistent
+        // shape.
+        surfacedTags.push(tierTag({ tier: "flash", confidence: 1.0 }));
+        return {
+            agent: "heimdall",
+            modelTier: "flash",
+            agentConfidence: 1.0,
+            modelConfidence: 1.0,
+            codemodIntent: cm.intent,
+            surfacedTags,
+        };
+    }
+    // 3. Q-learning agent pick.
+    const agentDecision = qRouter.selectAgent(task);
+    // 4. Thompson bandit for model tier.
+    const tierDecision = modelRouter.route(task);
+    surfacedTags.push(tierTag(tierDecision));
+    return {
+        agent: agentDecision.agent,
+        modelTier: tierDecision.tier,
+        agentConfidence: agentDecision.confidence,
+        modelConfidence: tierDecision.confidence,
+        codemodIntent: null,
+        surfacedTags,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tag formatters — the strings the spec asks us to surface to the prompt.
+// ---------------------------------------------------------------------------
+export function codemodTag(intent, confidence) {
+    return `[CODEMOD_AVAILABLE] ${intent} (conf=${confidence.toFixed(2)} >= ${CODEMOD_CONFIDENCE_THRESHOLD.toFixed(2)})`;
+}
+export function tierTag(decision) {
+    return `[TASK_MODEL_RECOMMENDATION] ${decision.tier} (conf=${decision.confidence.toFixed(2)})`;
+}
+// ---------------------------------------------------------------------------
+// Convenience re-exports so callers can `import { ... } from "..."/router"
+// ---------------------------------------------------------------------------
+export { detectCodemodIntent, CODEMOD_CONFIDENCE_THRESHOLD, } from "./codemod-intent.js";
+export { ModelRouter, } from "./model-router.js";
+export { QLearningRouter, AGENT_ACTIONS, } from "./q-learning-router.js";
+//# sourceMappingURL=index.js.map