@polderlabs/bizar 6.3.0 → 7.0.0

package/packages/sdk/tests/memory-distillation.test.mjs

@@ -0,0 +1,186 @@
+/**
+ * Tests for the RETRIEVE → JUDGE → DISTILL → CONSOLIDATE pipeline (F-033 / ADR-174).
+ *
+ * Roundtrip: write 3 memory entries of kind `coding_convention`,
+ * run the distiller, assert ≥1 promoted pattern with
+ * `provenance_tier` set.
+ */
+
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  runDistillation,
+  retrieve,
+  judge,
+  PROVENANCE_TIERS,
+} from "../src/router/memory-distillation.js";
+import { writeNote } from "../dist/memory/index.js";
+
+function makeEntry(body, opts = {}) {
+  return {
+    memory_id: opts.id ?? `note-${Math.random().toString(36).slice(2, 8)}`,
+    frontmatter: {
+      kind: opts.kind ?? "coding_convention",
+      createdAt: opts.createdAt ?? new Date().toISOString(),
+      ...opts.frontmatter,
+    },
+    body,
+  };
+}
+
+describe("memory-distillation — RETRIEVE", () => {
+  test("short body without code block is 'simple'", () => {
+    const r = retrieve(makeEntry("Use const for module exports.", { kind: "coding_convention" }));
+    expect(r.complexity).toBe("simple");
+    expect(r.hasCodeBlock).toBe(false);
+  });
+
+  test("body with a fenced code block is 'complex'", () => {
+    const r = retrieve(makeEntry("Pattern:\n```ts\nconst a = 1;\n```"));
+    expect(r.complexity).toBe("complex");
+    expect(r.hasCodeBlock).toBe(true);
+  });
+
+  test("frontmatter tag `test-exec` flips testExec=true", () => {
+    const r = retrieve(makeEntry("x", { frontmatter: { tags: ["test-exec"] } }));
+    expect(r.testExec).toBe(true);
+  });
+
+  test("frontmatter `kind: feedback` flips testExec=true", () => {
+    const r = retrieve(makeEntry("x", { frontmatter: { kind: "feedback" } }));
+    expect(r.testExec).toBe(true);
+  });
+});
+
+describe("memory-distillation — JUDGE / provenance_tier", () => {
+  test("testExec=true → oracle:test-exec", () => {
+    const r = retrieve(makeEntry("x", { frontmatter: { tags: ["test-exec"] } }));
+    expect(judge(makeEntry("x"), r)).toBe("oracle:test-exec");
+  });
+
+  test("testExec=false → proxy:structural", () => {
+    const r = retrieve(makeEntry("x", { kind: "coding_convention" }));
+    expect(judge(makeEntry("x"), r)).toBe("proxy:structural");
+  });
+});
+
+describe("memory-distillation — RUN (4-step pipeline)", () => {
+  test("3 coding_convention entries → ≥1 promoted pattern with provenance_tier", () => {
+    const entries = [
+      makeEntry("Always use const for module-level exports.", { kind: "coding_convention" }),
+      makeEntry("Prefer async/await over raw promise chains.", { kind: "coding_convention" }),
+      makeEntry(
+        "Document every exported function with a JSDoc block.",
+        { kind: "coding_convention", frontmatter: { kind: "coding_convention", tags: ["test-exec"] } },
+      ),
+    ];
+
+    const result = runDistillation(entries);
+    expect(result.patterns.length).toBeGreaterThan(0);
+    // The third entry carries the `test-exec` tag → oracle tier →
+    // eligible for promotion.
+    const promoted = result.promoted;
+    expect(promoted.length).toBeGreaterThanOrEqual(1);
+    expect(promoted[0].provenance_tier).toBe("oracle:test-exec");
+    expect(promoted[0].promoted).toBe(true);
+    expect(result.byTier["oracle:test-exec"]).toBeGreaterThanOrEqual(1);
+  });
+
+  test("all-proxy input still produces patterns, but none promoted", () => {
+    const entries = [
+      makeEntry("Pattern: keep imports sorted.", { kind: "task_summary" }),
+      makeEntry("Use: lint before commit.", { kind: "task_summary" }),
+    ];
+    const result = runDistillation(entries);
+    expect(result.patterns.length).toBeGreaterThan(0);
+    expect(result.promoted.length).toBe(0);
+    expect(result.byTier["proxy:structural"]).toBeGreaterThan(0);
+  });
+
+  test("empty input → empty result with zero counts", () => {
+    const result = runDistillation([]);
+    expect(result.patterns).toEqual([]);
+    expect(result.promoted).toEqual([]);
+    for (const tier of PROVENANCE_TIERS) {
+      expect(result.byTier[tier]).toBe(0);
+    }
+  });
+
+  test("non-pattern kinds (e.g. user_preference) are not distilled", () => {
+    const entries = [
+      makeEntry("I prefer dark mode.", { kind: "user_preference" }),
+      makeEntry("I prefer tabs.", { kind: "user_preference" }),
+    ];
+    const result = runDistillation(entries);
+    expect(result.patterns.length).toBe(0);
+  });
+
+  test("run is idempotent (same input → same patterns)", () => {
+    const entries = [
+      makeEntry("Use const for top-level exports.", { kind: "coding_convention", id: "a" }),
+      makeEntry(
+        "Use const for top-level exports in TypeScript modules.",
+        { kind: "coding_convention", frontmatter: { tags: ["test-exec"] }, id: "b" },
+      ),
+    ];
+    const r1 = runDistillation(entries);
+    const r2 = runDistillation(entries);
+    expect(r2.patterns.length).toBe(r1.patterns.length);
+    expect(r2.promoted.map((p) => p.id).sort()).toEqual(r1.promoted.map((p) => p.id).sort());
+  });
+});
+
+describe("memory-distillation — roundtrip via in-process vault", () => {
+  test("write 3 coding_convention notes → run distiller → promoted pattern exists", async () => {
+    const vault = mkdtempSync(join(tmpdir(), "bizar-f033-"));
+    try {
+      // 1. Seed: write 3 coding_convention notes — one of them is
+      //    marked `test-exec` to drive the oracle tier.
+      writeNote(vault, "conv-1.md", {
+        title: "Always use const for module-level exports",
+        kind: "coding_convention",
+        createdAt: new Date().toISOString(),
+      }, "Always use `const` for module-level exports.");
+      writeNote(vault, "conv-2.md", {
+        title: "Prefer async/await over raw promise chains",
+        kind: "coding_convention",
+        createdAt: new Date().toISOString(),
+      }, "Prefer `async`/`await` over raw `.then()` chains.");
+      writeNote(vault, "conv-3.md", {
+        title: "Document exported functions",
+        kind: "coding_convention",
+        createdAt: new Date().toISOString(),
+        tags: ["test-exec"],
+      }, "Document every exported function with a JSDoc block.");
+
+      // 2. Read them back via the SDK in-process vault helpers.
+      const vaultModule = await import("../dist/memory/index.js");
+      const notes = vaultModule.listNotes(vault, "", 100);
+      expect(notes.length).toBe(3);
+
+      // 3. Translate to the distiller's input shape.
+      const entries = notes.map((n) => ({
+        memory_id: n.relPath,
+        relPath: n.relPath,
+        frontmatter: n.frontmatter ?? {},
+        body: n.body ?? "",
+        kind: n.frontmatter?.kind ?? n.frontmatter?.type,
+        createdAt: n.frontmatter?.createdAt,
+      }));
+
+      // 4. Run the distiller and assert the promoted pattern.
+      const result = runDistillation(entries);
+      expect(result.patterns.length).toBeGreaterThanOrEqual(1);
+      const promoted = result.promoted;
+      expect(promoted.length).toBeGreaterThanOrEqual(1);
+      expect(promoted[0].provenance_tier).toBe("oracle:test-exec");
+      expect(promoted[0].promoted).toBe(true);
+      // Provenance tier is one of the allowed ADR-174 values.
+      expect(PROVENANCE_TIERS).toContain(promoted[0].provenance_tier);
+    } finally {
+      rmSync(vault, { recursive: true, force: true });
+    }
+  });
+});

package/packages/sdk/tests/model-router.test.mjs

@@ -0,0 +1,108 @@
+/**
+ * Tests for the Thompson-sampling bandit model router (F-033).
+ *
+ * - Codemod short-circuit returns `{tier: 'flash', codemodIntent}`.
+ * - Default priors make `flash` the most-likely pick.
+ * - recordOutcome() shifts the Beta(α, β) priors.
+ * - recordOutcome with seed gives deterministic picks.
+ */
+
+import { describe, test, expect } from "vitest";
+import { ModelRouter } from "../src/router/model-router.js";
+
+describe("ModelRouter — codemod short-circuit", () => {
+  test("var-to-const short-circuits to flash with codemodIntent", () => {
+    const r = new ModelRouter({ seed: 42 });
+    const d = r.route("convert var to const");
+    expect(d.tier).toBe("flash");
+    expect(d.codemodIntent).toBe("var-to-const");
+    expect(d.confidence).toBe(1.0);
+  });
+
+  test("remove-console short-circuits to flash with codemodIntent", () => {
+    const r = new ModelRouter({ seed: 42 });
+    const d = r.route("strip console.log statements");
+    expect(d.tier).toBe("flash");
+    expect(d.codemodIntent).toBe("remove-console");
+  });
+
+  test("add-logging short-circuits to flash with codemodIntent", () => {
+    const r = new ModelRouter({ seed: 42 });
+    const d = r.route("add logging to the handler");
+    expect(d.tier).toBe("flash");
+    expect(d.codemodIntent).toBe("add-logging");
+  });
+});
+
+describe("ModelRouter — Thompson sampling", () => {
+  test("non-codemod prompt returns a valid tier", () => {
+    const r = new ModelRouter({ seed: 42 });
+    const d = r.route("design a database schema for inventory");
+    expect(["flash", "mid", "expensive"]).toContain(d.tier);
+    expect(d.confidence).toBeGreaterThanOrEqual(0);
+    expect(d.confidence).toBeLessThanOrEqual(1);
+    expect(d.codemodIntent).toBeUndefined();
+  });
+
+  test("default priors favor flash (alpha=2, beta=1)", () => {
+    const r = new ModelRouter({ seed: 1 });
+    const priors = r.getPriors();
+    // The default-prior math (matches ADR-026 §BANDIT_REWARDS note).
+    expect(priors.flash.alpha).toBe(2);
+    expect(priors.flash.beta).toBe(1);
+    expect(priors.mid.alpha).toBe(1);
+    expect(priors.mid.beta).toBe(1);
+    expect(priors.expensive.alpha).toBe(1);
+    expect(priors.expensive.beta).toBe(2);
+  });
+
+  test("many flash successes shift priors toward flash", () => {
+    const r = new ModelRouter({ seed: 42 });
+    for (let i = 0; i < 30; i++) r.recordOutcome("flash", true);
+    const priors = r.getPriors();
+    expect(priors.flash.alpha).toBeGreaterThan(2);
+    expect(priors.flash.beta).toBe(1);
+  });
+
+  test("flash failures increment β", () => {
+    const r = new ModelRouter({ seed: 42 });
+    for (let i = 0; i < 5; i++) r.recordOutcome("flash", false);
+    const priors = r.getPriors();
+    expect(priors.flash.alpha).toBe(2);
+    expect(priors.flash.beta).toBe(1 + 5);
+  });
+
+  test("seeded RNG produces deterministic pick", () => {
+    const a = new ModelRouter({ seed: 7 });
+    const b = new ModelRouter({ seed: 7 });
+    const prompt = "explain what this function does";
+    // Run several samples; at least one must agree (probabilistically
+    // very near 1.0).
+    let matches = 0;
+    for (let i = 0; i < 20; i++) {
+      const da = a.route(prompt);
+      const db = b.route(prompt);
+      if (da.tier === db.tier) matches += 1;
+    }
+    expect(matches).toBeGreaterThanOrEqual(18);
+  });
+
+  test("expensive success is devalued (alpha += 0.4)", () => {
+    const r = new ModelRouter({ seed: 42 });
+    r.recordOutcome("expensive", true);
+    const priors = r.getPriors();
+    expect(priors.expensive.alpha).toBeCloseTo(1.4);
+  });
+});
+
+describe("ModelRouter — overrides", () => {
+  test("priors override applies per-tier", () => {
+    const r = new ModelRouter({
+      priors: { expensive: { alpha: 100, beta: 1 } },
+      seed: 1,
+    });
+    const priors = r.getPriors();
+    expect(priors.expensive.alpha).toBe(100);
+    expect(priors.flash.alpha).toBe(2); // default still in place
+  });
+});

package/packages/sdk/tests/q-learning-router.test.mjs

@@ -0,0 +1,100 @@
+/**
+ * Tests for the Q-learning agent router (F-033).
+ *
+ * - selectAgent() returns one of the 8 hard-coded Bizar agent names.
+ * - Codemod prompts route to heimdall (the routine-implementation agent).
+ * - recordOutcome() updates the Q-table (snapshot mean shifts).
+ * - LRU caching: repeated tasks return the same pick without burning
+ *   exploration budget.
+ */
+
+import { describe, test, expect } from "vitest";
+import { QLearningRouter, AGENT_ACTIONS } from "../src/router/q-learning-router.js";
+
+describe("QLearningRouter — action set", () => {
+  test("AGENT_ACTIONS lists 8 Bizar agents", () => {
+    expect(AGENT_ACTIONS.length).toBe(8);
+    expect(AGENT_ACTIONS).toContain("odin");
+    expect(AGENT_ACTIONS).toContain("heimdall");
+    expect(AGENT_ACTIONS).toContain("forseti");
+  });
+});
+
+describe("QLearningRouter — codemod short-circuit", () => {
+  test("var-to-const picks heimdall", () => {
+    const r = new QLearningRouter({ seed: 42, epsilon: 0 });
+    expect(r.selectAgent("convert var to const").agent).toBe("heimdall");
+  });
+
+  test("remove-console picks heimdall", () => {
+    const r = new QLearningRouter({ seed: 42, epsilon: 0 });
+    expect(r.selectAgent("remove console.log calls").agent).toBe("heimdall");
+  });
+
+  test("add-logging picks heimdall", () => {
+    const r = new QLearningRouter({ seed: 42, epsilon: 0 });
+    expect(r.selectAgent("add logging to the handler").agent).toBe("heimdall");
+  });
+});
+
+describe("QLearningRouter — bandit behavior", () => {
+  test("non-codemod task returns a valid agent", () => {
+    const r = new QLearningRouter({ seed: 42, epsilon: 0.5 });
+    const d = r.selectAgent("explain the architecture of this codebase");
+    expect(AGENT_ACTIONS).toContain(d.agent);
+    expect(d.confidence).toBeGreaterThanOrEqual(0);
+    expect(d.confidence).toBeLessThanOrEqual(1);
+  });
+
+  test("epsilon=0 deterministic given seeded RNG", () => {
+    const a = new QLearningRouter({ seed: 99, epsilon: 0 });
+    const b = new QLearningRouter({ seed: 99, epsilon: 0 });
+    const task = "implement a new cache layer for the storage engine";
+    // Different RNG state path; the LRU cache for the first call
+    // should fire identically. Subsequent calls fall back to bandit.
+    expect(a.selectAgent(task).agent).toBe(b.selectAgent(task).agent);
+  });
+
+  test("recordOutcome shifts the Q snapshot toward the rewarded agent", () => {
+    const r = new QLearningRouter({ seed: 7, epsilon: 0 });
+    const before = r.snapshot().find((s) => s.agent === "thor")?.qMean ?? 0.5;
+    for (let i = 0; i < 50; i++) r.recordOutcome("thor", true);
+    const after = r.snapshot().find((s) => s.agent === "thor")?.qMean ?? 0.5;
+    expect(after).toBeGreaterThan(before);
+  });
+
+  test("failures shift the Q mean downward", () => {
+    const r = new QLearningRouter({ seed: 7, epsilon: 0 });
+    for (let i = 0; i < 50; i++) r.recordOutcome("frigg", false);
+    const after = r.snapshot().find((s) => s.agent === "frigg")?.qMean ?? 0.5;
+    expect(after).toBeLessThan(0.5);
+  });
+
+  test("recordOutcome is a no-op for unknown agents", () => {
+    const r = new QLearningRouter({ seed: 7, epsilon: 0 });
+    const before = r.snapshot();
+    r.recordOutcome("not-a-real-agent", true);
+    const after = r.snapshot();
+    expect(after).toEqual(before);
+  });
+});
+
+describe("QLearningRouter — LRU cache", () => {
+  test("repeated task returns the cached decision", () => {
+    const r = new QLearningRouter({ seed: 11, epsilon: 0 });
+    const task = "review this PR for security concerns";
+    const first = r.selectAgent(task);
+    const second = r.selectAgent(task);
+    // The LRU returns the exact stored object — same agent, same confidence.
+    expect(second.agent).toBe(first.agent);
+    expect(second.confidence).toBe(first.confidence);
+  });
+});
+
+describe("QLearningRouter — empty input safety", () => {
+  test("null task returns the safe odin fallback", () => {
+    const r = new QLearningRouter({ seed: 7 });
+    const d = r.selectAgent("");
+    expect(d.agent).toBe("odin");
+  });
+});

package/packages/sdk/tests/router-orchestrator.test.mjs

@@ -0,0 +1,172 @@
+/**
+ * Tests for the router orchestrator (F-033).
+ *
+ * Verifies the precedence chain:
+ *   explicit > codemod > q-learning > bandit > default
+ *
+ * Plus the surfaced-tags contract:
+ *   [CODEMOD_AVAILABLE] <intent>
+ *   [TASK_MODEL_RECOMMENDATION] <tier>
+ *
+ * Plus persistence: saveTo() writes state files; loadFrom() rehydrates
+ * the same priors.
+ */
+
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  decideAgentWith,
+  getRouter,
+  ModelRouter,
+  QLearningRouter,
+  codemodTag,
+  tierTag,
+  DEFAULT_MODEL_STATE_PATH,
+  DEFAULT_Q_STATE_PATH,
+} from "../src/router/index.js";
+
+describe("decideAgentWith — precedence chain", () => {
+  test("explicit agent wins (when known)", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, {
+      task: "convert var to const",
+      explicitAgent: "odin",
+    });
+    expect(d.agent).toBe("odin");
+    expect(d.agentConfidence).toBe(1.0);
+    expect(d.codemodIntent).toBeNull();
+    // Explicit path still emits a [TASK_MODEL_RECOMMENDATION] tag.
+    expect(d.surfacedTags.some((t) => t.startsWith("[TASK_MODEL_RECOMMENDATION]"))).toBe(true);
+    expect(d.surfacedTags.some((t) => t.startsWith("[CODEMOD_AVAILABLE]"))).toBe(false);
+  });
+
+  test("codemod intent short-circuits before q-learning", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: "convert var to const" });
+    expect(d.agent).toBe("heimdall");
+    expect(d.agentConfidence).toBe(1.0);
+    expect(d.codemodIntent).toBe("var-to-const");
+    expect(d.modelTier).toBe("flash");
+    // Both tags should be surfaced for a codemod hit.
+    expect(d.surfacedTags.some((t) => t.includes("CODEMOD_AVAILABLE"))).toBe(true);
+    expect(d.surfacedTags.some((t) => t.includes("TASK_MODEL_RECOMMENDATION"))).toBe(true);
+  });
+
+  test("non-codemod task routes via q-learning + bandit", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: "design a database schema" });
+    expect(["odin", "frigg", "vor", "mimir", "heimdall", "thor", "tyr", "forseti"])
+      .toContain(d.agent);
+    expect(d.codemodIntent).toBeNull();
+    expect(["flash", "mid", "expensive"]).toContain(d.modelTier);
+    expect(d.surfacedTags.length).toBe(1);
+    expect(d.surfacedTags[0]).toMatch(/^\[TASK_MODEL_RECOMMENDATION\]/);
+  });
+
+  test("unknown explicit agent falls through to q-learning", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: "hello world", explicitAgent: "totally-unknown" });
+    expect(d.agent).not.toBe("totally-unknown");
+    expect(AGENT_SET.has(d.agent)).toBe(true);
+  });
+});
+
+const AGENT_SET = new Set(["odin", "frigg", "vor", "mimir", "heimdall", "thor", "tyr", "forseti"]);
+
+describe("tag formatters", () => {
+  test("codemodTag includes intent and confidence", () => {
+    const tag = codemodTag("var-to-const", 0.71);
+    expect(tag).toContain("[CODEMOD_AVAILABLE]");
+    expect(tag).toContain("var-to-const");
+    expect(tag).toMatch(/conf=0\.71/);
+  });
+
+  test("tierTag includes tier and confidence", () => {
+    const tag = tierTag({ tier: "flash", confidence: 0.42 });
+    expect(tag).toContain("[TASK_MODEL_RECOMMENDATION]");
+    expect(tag).toContain("flash");
+    expect(tag).toMatch(/conf=0\.42/);
+  });
+});
+
+describe("getRouter() — factory + persistence", () => {
+  test("with custom routers is in-memory only", () => {
+    const mr = new ModelRouter({ seed: 1 });
+    const qr = new QLearningRouter({ seed: 1 });
+    const bundle = getRouter({ modelRouter: mr, qRouter: qr });
+    expect(bundle.modelRouter).toBe(mr);
+    expect(bundle.qRouter).toBe(qr);
+    const d = bundle.decideAgent({ task: "convert var to const" });
+    expect(d.codemodIntent).toBe("var-to-const");
+  });
+
+  test("default state paths are .harness/router-state.{model,q}", () => {
+    expect(DEFAULT_MODEL_STATE_PATH).toBe(".harness/router-state.json");
+    expect(DEFAULT_Q_STATE_PATH).toBe(".harness/q-router-state.json");
+  });
+
+  test("saveTo writes the bundle pointer + per-router state files", () => {
+    const dir = mkdtempSync(join(tmpdir(), "bizar-router-"));
+    try {
+      const mr = new ModelRouter({ seed: 5 });
+      const qr = new QLearningRouter({ seed: 5 });
+      // Force the persistence files into a temp dir by manipulating
+      // the bundle basePath through saveTo's sibling files.
+      const bundle = getRouter({ modelRouter: mr, qRouter: qr });
+      // Override the cwd-derived basePath so the save lands in `dir`.
+      const basePath = join(dir, "router-state");
+      const modelPath = `${basePath}.model`;
+      const qPath = `${basePath}.q`;
+      mr.saveTo(modelPath);
+      qr.saveTo(qPath);
+      expect(existsSync(modelPath)).toBe(true);
+      expect(existsSync(qPath)).toBe(true);
+      const state = JSON.parse(readFileSync(modelPath, "utf-8"));
+      expect(state.version).toBe(1);
+      expect(state.priors.flash.alpha).toBe(2);
+    } finally {
+      // mkdtempSync + recursive rm
+      const { rmSync } = require("node:fs");
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("ModelRouter.loadFrom rehydrates priors", () => {
+    const dir = mkdtempSync(join(tmpdir(), "bizar-router-"));
+    try {
+      const fp = join(dir, "router.json");
+      const original = new ModelRouter({ seed: 42 });
+      original.recordOutcome("flash", true);
+      original.recordOutcome("flash", true);
+      original.saveTo(fp);
+
+      const loaded = ModelRouter.loadFrom(fp);
+      const priors = loaded.getPriors();
+      expect(priors.flash.alpha).toBeGreaterThan(2);
+    } finally {
+      const { rmSync } = require("node:fs");
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("decideAgent — codemod short-circuit covers all three intents", () => {
+  test.each([
+    ["convert var to const", "var-to-const"],
+    ["remove console.log calls", "remove-console"],
+    ["add logging to the handler", "add-logging"],
+  ])("codemod surface for: %s", (prompt, expected) => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: prompt });
+    expect(d.codemodIntent).toBe(expected);
+    expect(d.agent).toBe("heimdall");
+  });
+});

package/packages/sdk/tests/router.test.mjs

@@ -0,0 +1,91 @@
+/**
+ * Tests for codemod intent detection (F-033).
+ *
+ * 5+ positive prompts per deterministic intent (var-to-const,
+ * remove-console, add-logging) plus 5+ negatives that should NOT
+ * be codemod-eligible (the caller falls through to the bandit).
+ */
+
+import { describe, test, expect } from "vitest";
+import { detectCodemodIntent } from "../src/router/codemod-intent.js";
+
+describe("detectCodemodIntent — var-to-const", () => {
+  test("matches canonical phrasing", () => {
+    const hit = detectCodemodIntent("convert var to const");
+    expect(hit).not.toBeNull();
+    expect(hit?.intent).toBe("var-to-const");
+    expect(hit?.confidence).toBeGreaterThan(0);
+  });
+
+  test.each([
+    "change var to const in this file",
+    "replace var with const",
+    "use const instead of var",
+    "var to const for all declarations",
+    "convert var declarations to const",
+    "change var declarations to const everywhere",
+  ])("matches var-to-const phrasing: %s", (prompt) => {
+    const hit = detectCodemodIntent(prompt);
+    expect(hit?.intent).toBe("var-to-const");
+  });
+});
+
+describe("detectCodemodIntent — remove-console", () => {
+  test.each([
+    "remove console.log calls",
+    "delete console statements",
+    "strip console logs",
+    "clean up console",
+    "remove all debug logs",
+    "remove console.log statements everywhere",
+  ])("matches remove-console phrasing: %s", (prompt) => {
+    const hit = detectCodemodIntent(prompt);
+    expect(hit?.intent).toBe("remove-console");
+  });
+});
+
+describe("detectCodemodIntent — add-logging", () => {
+  test.each([
+    "add logging to the handler",
+    "add console.log statements",
+    "add debug logs to the module",
+    "log this function for diagnostics",
+    "add trace logging",
+    "instrument with logs",
+  ])("matches add-logging phrasing: %s", (prompt) => {
+    const hit = detectCodemodIntent(prompt);
+    expect(hit?.intent).toBe("add-logging");
+  });
+});
+
+describe("detectCodemodIntent — negatives", () => {
+  test.each([
+    "design a database schema for inventory",
+    "implement OAuth2 PKCE flow with refresh-token rotation",
+    "debug a memory leak in the cache",
+    "explain what this function does",
+    "refactor the http client to use async await",
+    "add type annotations to the API",
+    "wrap the parser in try/catch",
+  ])("rejects non-codemod prompt: %s", (prompt) => {
+    expect(detectCodemodIntent(prompt)).toBeNull();
+  });
+
+  test("returns null for empty input", () => {
+    expect(detectCodemodIntent("")).toBeNull();
+  });
+
+  test("returns null for non-string input", () => {
+    expect(detectCodemodIntent(null)).toBeNull();
+    expect(detectCodemodIntent(undefined)).toBeNull();
+    expect(detectCodemodIntent(42)).toBeNull();
+  });
+});
+
+describe("detectCodemodIntent — confidence ordering", () => {
+  test("multi-match returns the highest-confidence intent", () => {
+    const hit = detectCodemodIntent("convert var to const, replace var with const, change var declarations to const");
+    expect(hit?.intent).toBe("var-to-const");
+    expect(hit?.confidence).toBeGreaterThan(0.4);
+  });
+});