@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/tests/mcp-tools.test.ts

@@ -0,0 +1,204 @@
+/**
+ * mcp-tools.test.ts — exercises the 4 new MCP tools (F-032) by calling
+ * each tool's `handler` directly and asserting the return shape.
+ *
+ * The tools live in `packages/sdk/src/mcp/server.ts`; we import the
+ * compiled `BIZAR_TOOLS` array and walk it to find each tool by name.
+ */
+
+import { describe, test, expect, beforeEach } from "vitest";
+import { BIZAR_TOOLS, type SdkMcpToolDef } from "../src/mcp/server.js";
+import { bizarAgentRegistry } from "../src/agent-registry.js";
+import { swarmTopologyRegistry } from "../src/swarm-topology.js";
+
+function findTool(name: string): SdkMcpToolDef {
+  const t = BIZAR_TOOLS.find((x) => x.name === name);
+  if (!t) throw new Error(`tool not found: ${name}`);
+  return t;
+}
+
+async function call(toolName: string, args: unknown): Promise<unknown> {
+  const tool = findTool(toolName);
+  const res = await tool.handler(args, {});
+  // Standard MCP shape: { content: [{ type: 'text', text: '...' }] }
+  if (!Array.isArray(res.content) || res.content.length !== 1) {
+    throw new Error(`unexpected response shape from ${toolName}`);
+  }
+  const block = res.content[0];
+  if (block.type !== "text") throw new Error(`unexpected block type: ${block.type}`);
+  try { return JSON.parse(block.text); }
+  catch { return block.text; }
+}
+
+describe("MCP tools — F-032 swarm/agent lifecycle", () => {
+  beforeEach(() => {
+    // Each test starts from a clean slate so list assertions are deterministic.
+    bizarAgentRegistry.reset();
+    swarmTopologyRegistry.reset();
+  });
+
+  test("BIZAR_TOOLS includes the 4 new tools (total ≥ 17)", () => {
+    const names = new Set(BIZAR_TOOLS.map((t) => t.name));
+    expect(names.has("agent_spawn")).toBe(true);
+    expect(names.has("agent_list")).toBe(true);
+    expect(names.has("agent_terminate")).toBe(true);
+    expect(names.has("swarm_init")).toBe(true);
+    expect(BIZAR_TOOLS.length).toBeGreaterThanOrEqual(17);
+  });
+
+  test("each new tool has the expected inputSchema", () => {
+    const spawn = findTool("agent_spawn");
+    expect(spawn.inputSchema).toMatchObject({
+      type: "string", name: "string", priority: "string", metadata: "string",
+    });
+
+    const list = findTool("agent_list");
+    expect(list.inputSchema).toMatchObject({
+      status: "string", type: "string", limit: "number", offset: "number",
+    });
+
+    const term = findTool("agent_terminate");
+    expect(term.inputSchema).toMatchObject({
+      agentId: "string", graceful: "boolean", reason: "string",
+    });
+
+    const swarm = findTool("swarm_init");
+    expect(swarm.inputSchema).toMatchObject({
+      topology: "string", maxAgents: "number", metadata: "string",
+    });
+  });
+
+  test("agent_spawn returns { agentId, status }", async () => {
+    const r = await call("agent_spawn", { type: "coder", name: "ada" });
+    expect(r).toMatchObject({ status: "active" });
+    expect((r as { agentId: string }).agentId).toMatch(/^agent-/);
+  });
+
+  test("agent_spawn parses metadata JSON when supplied", async () => {
+    const r = await call("agent_spawn", {
+      type: "coder",
+      metadata: JSON.stringify({ region: "us", priority: "high" }),
+    });
+    const id = (r as { agentId: string }).agentId;
+    const got = bizarAgentRegistry.getAgent(id);
+    expect(got?.metadata).toEqual({ region: "us", priority: "high" });
+  });
+
+  test("agent_spawn returns a structured error when metadata is not valid JSON", async () => {
+    const tool = findTool("agent_spawn");
+    const res = await tool.handler({ type: "coder", metadata: "not-json" }, {});
+    const text = (res.content[0] as { text: string }).text;
+    expect(text).toMatch(/^error:/);
+    expect(text).toMatch(/JSON/);
+  });
+
+  test("agent_spawn rejects types outside the AGENT_TYPES allowlist", async () => {
+    const tool = findTool("agent_spawn");
+    const res = await tool.handler({ type: "lawyer" }, {});
+    const text = (res.content[0] as { text: string }).text;
+    expect(text).toMatch(/^error:/);
+    expect(text).toMatch(/must be one of/);
+  });
+
+  test("agent_list returns active agents by default", async () => {
+    await call("agent_spawn", { type: "coder" });
+    await call("agent_spawn", { type: "reviewer" });
+    const r = await call("agent_list", {});
+    expect(r).toMatchObject({ total: 2 });
+    expect((r as { agents: unknown[] }).agents).toHaveLength(2);
+  });
+
+  test("agent_list filters by status", async () => {
+    const a = await call("agent_spawn", { type: "coder" }) as { agentId: string };
+    await call("agent_spawn", { type: "coder" });
+    await call("agent_terminate", { agentId: a.agentId, reason: "test" });
+    const terminated = await call("agent_list", { status: "terminated" });
+    expect(terminated).toMatchObject({ total: 1 });
+    const active = await call("agent_list", { status: "active" });
+    expect(active).toMatchObject({ total: 1 });
+  });
+
+  test("agent_list defaults status to 'all' for unrecognized values", async () => {
+    await call("agent_spawn", { type: "coder" });
+    const r = await call("agent_list", { status: "bogus" });
+    expect(r).toMatchObject({ total: 1 });
+  });
+
+  test("agent_terminate returns { agentId, status, terminatedAt }", async () => {
+    const spawned = await call("agent_spawn", { type: "coder" }) as { agentId: string };
+    const r = await call("agent_terminate", { agentId: spawned.agentId, reason: "done" });
+    expect(r).toMatchObject({
+      agentId: spawned.agentId,
+      status: "terminated",
+    });
+    expect(typeof (r as { terminatedAt: string }).terminatedAt).toBe("string");
+  });
+
+  test("agent_terminate surfaces a structured error for unknown agent", async () => {
+    const tool = findTool("agent_terminate");
+    const res = await tool.handler({ agentId: "agent-nope" }, {});
+    const text = (res.content[0] as { text: string }).text;
+    expect(text).toMatch(/^error:/);
+    expect(text).toMatch(/not found/);
+  });
+
+  test("swarm_init creates a swarm with defaults", async () => {
+    const r = await call("swarm_init", {}) as {
+      swarmId: string; topology: string; maxAgents: number; createdAt: string;
+    };
+    expect(r.swarmId).toMatch(/^swarm-\d+$/);
+    expect(r.topology).toBe("hierarchical-mesh");
+    expect(r.maxAgents).toBe(15);
+    expect(typeof r.createdAt).toBe("string");
+  });
+
+  test("swarm_init respects topology and maxAgents", async () => {
+    const r = await call("swarm_init", {
+      topology: "mesh",
+      maxAgents: 42,
+      metadata: JSON.stringify({ owner: "F-032" }),
+    }) as { topology: string; maxAgents: number; metadata?: Record<string, unknown> };
+    expect(r.topology).toBe("mesh");
+    expect(r.maxAgents).toBe(42);
+    expect(r.metadata).toEqual({ owner: "F-032" });
+  });
+
+  test("swarm_init clamps maxAgents to [1, 1000]", async () => {
+    const lo = await call("swarm_init", { maxAgents: 0 }) as { maxAgents: number };
+    const hi = await call("swarm_init", { maxAgents: 99999 }) as { maxAgents: number };
+    expect(lo.maxAgents).toBe(1);
+    expect(hi.maxAgents).toBe(1000);
+  });
+
+  test("swarm_init returns an error for invalid JSON metadata", async () => {
+    const tool = findTool("swarm_init");
+    const res = await tool.handler({ metadata: "{not-json" }, {});
+    const text = (res.content[0] as { text: string }).text;
+    expect(text).toMatch(/^error:/);
+    expect(text).toMatch(/JSON/);
+  });
+
+  test("end-to-end: spawn → list → terminate → list shows 1 active + 1 terminated", async () => {
+    const spawned = await call("agent_spawn", { type: "coder", name: "ada" }) as {
+      agentId: string;
+    };
+
+    const allAfterSpawn = await call("agent_list", { status: "all" }) as {
+      total: number; agents: { agentId: string; status: string }[];
+    };
+    expect(allAfterSpawn.total).toBe(1);
+    expect(allAfterSpawn.agents[0]?.status).toBe("active");
+    expect(allAfterSpawn.agents[0]?.agentId).toBe(spawned.agentId);
+
+    await call("agent_terminate", { agentId: spawned.agentId, reason: "smoke" });
+
+    const allAfterTerm = await call("agent_list", { status: "all" }) as {
+      total: number; agents: { status: string }[];
+    };
+    expect(allAfterTerm.total).toBe(1);
+    expect(allAfterTerm.agents[0]?.status).toBe("terminated");
+
+    // Sanity: the registry returns the same record (proves state lives in BizarAgentRegistry).
+    expect(bizarAgentRegistry.getAgent(spawned.agentId)?.status).toBe("terminated");
+  });
+});

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");
+  });
+});