jev-layer 0.1.0 → 0.3.0

package/test/computer.test.mjs

@@ -0,0 +1,195 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { test } from "node:test";
+import { decideComputerStep } from "../src/computer.mjs";
+import { PNG } from "./image-fixture.mjs";
+
+const SCREENSHOT = { format: "png", data_base64: PNG, width: 400, height: 300 };
+const SCROLL = { id: "scroll-down", operation: "scroll", args: { direction: "down", amount: 120 } };
+const CLICK = { id: "save", operation: "click", target: "the Save button", args: { button: "left" }, risk: "low" };
+const BOX = { left: 0.2, right: 0.6, top: 0.1, bottom: 0.5 };
+
+function input(overrides = {}) {
+  return { goal: "Inspect the application", observation: { screenshot: SCREENSHOT, visible_text: "Save", application: "Editor" }, actions: [SCROLL], actor_permissions: ["computer"], ...overrides };
+}
+
+function grounding(visibility = 0.99, confidence = 0.95, box = BOX) {
+  return { answers: { target_visible: { type: "noul", noul: visibility }, target_box: { type: "box", box, confidence } } };
+}
+
+function provider({ choice, confidence = 1, result = grounding(), error = false } = {}) {
+  return {
+    name: "computer-test", supportsImages: true, choices: [], groundings: [],
+    async decide(request) {
+      this.choices.push(request);
+      const selected = choice ?? request.candidates[0].id;
+      return { answers: { tool: { type: "choice", choice: selected, confidence, probabilities: { [selected]: confidence } } } };
+    },
+    async evaluate(request) {
+      this.groundings.push(request);
+      if (error) throw new Error("offline");
+      return result;
+    },
+  };
+}
+
+function assertFallback(result, type) {
+  assert.equal(result.action, null);
+  assert.equal(result.decision.status, "fallback");
+  if (type) assert.equal(result.decision.fallback.type, type);
+  assert.equal(result.decision.execution.enabled, false);
+  assert.equal(result.decision.correlation_id, result.decision.receipt.correlation_id);
+}
+
+test("computer advice is opt-in and an explicit disable overrides the environment", async () => {
+  const previous = process.env.JEV_COMPUTER_USE;
+  const engine = provider();
+  try {
+    delete process.env.JEV_COMPUTER_USE;
+    assertFallback(await decideComputerStep(input(), { provider: engine }), "computer_use_disabled");
+    process.env.JEV_COMPUTER_USE = "1";
+    assertFallback(await decideComputerStep(input(), { enabled: false, provider: engine }), "computer_use_disabled");
+    assert.equal(engine.choices.length, 0);
+    const enabled = await decideComputerStep(input(), { provider: engine });
+    assert.equal(enabled.decision.status, "selected");
+    assert.deepEqual(enabled.action.args, SCROLL.args);
+    assert.deepEqual(enabled.decision.execution, { enabled: false, status: "not_started" });
+  } finally {
+    if (previous === undefined) delete process.env.JEV_COMPUTER_USE;
+    else process.env.JEV_COMPUTER_USE = previous;
+  }
+});
+
+test("malformed screenshots and non-closed action arguments fail open before provider calls", async () => {
+  const engine = provider();
+  for (const candidate of [
+    input({ observation: {} }),
+    input({ observation: { screenshot: { ...SCREENSHOT, data_base64: "file:///screen.png" } } }),
+    input({ observation: { screenshot: { ...SCREENSHOT, data_base64: Buffer.from("not an image").toString("base64") } } }),
+    input({ observation: { screenshot: { ...SCREENSHOT, width: 800 } } }),
+    input({ actions: [{ ...SCROLL, operation: "shell", args: { command: "anything" } }] }),
+    input({ actions: [{ ...SCROLL, args: { direction: "down", command: "anything" } }] }),
+    input({ actions: [{ ...CLICK, target: undefined }] }),
+    input({ actions: [{ ...CLICK, args: { x: 400, y: 20 } }] }),
+    input({ actions: [{ ...CLICK, args: { x: 20 } }] }),
+    input({ actions: [SCROLL, SCROLL] }),
+    input({ actions: Array.from({ length: 33 }, (_, index) => ({ ...SCROLL, id: `scroll-${index}` })) }),
+    input({ policy: { min_target_visibility: Number.NaN } }),
+    input({ policy: { min_box_confidence: 0 } }),
+  ]) assertFallback(await decideComputerStep(candidate, { enabled: true, provider: engine }), "invalid_input");
+  assert.equal(engine.choices.length, 0);
+  assert.equal(engine.groundings.length, 0);
+});
+
+test("registry filters enforce explicit computer permission, availability, extra permissions, and risk", async () => {
+  const engine = provider();
+  for (const candidate of [
+    input({ actor_permissions: undefined }),
+    input({ actor_permissions: [] }),
+    input({ actions: [{ ...SCROLL, permissions: ["administrator"] }] }),
+    input({ actions: [{ ...SCROLL, available: false }] }),
+    input({ actions: [{ ...SCROLL, availability: { available: false, reason: "offline" } }] }),
+    input({ actions: [{ ...SCROLL, risk: "high" }], policy: { max_risk: "low" } }),
+  ]) {
+    const result = await decideComputerStep(candidate, { enabled: true, provider: engine });
+    assert.equal(result.decision.status, "no_decision");
+    assert.equal(result.action, null);
+    assert.equal(result.decision.execution.enabled, false);
+    assert.ok(result.decision.candidates.every((item) => item.filtered));
+  }
+  assert.equal(engine.choices.length, 0);
+});
+
+test("consequential actions require confirmation even at low risk", async () => {
+  for (const action of [
+    { id: "click", operation: "click", args: { x: 17, y: 29, button: "right" }, risk: "low" },
+    { id: "type", operation: "type", args: { text: "host supplied text" }, risk: "low" },
+    { id: "key", operation: "key", args: { keys: ["Control", "S"] }, risk: "low" },
+    { ...SCROLL, consequential: true },
+    { ...SCROLL, requires_confirmation: true },
+    { ...SCROLL, policy: { requires_confirmation: true } },
+  ]) {
+    const engine = provider();
+    const result = await decideComputerStep(input({ actions: [action], policy: { confirmation_risk_levels: [] } }), { enabled: true, provider: engine });
+    assert.equal(result.decision.status, "needs_confirmation");
+    assert.equal(result.decision.candidates[0].requires_confirmation, true);
+    assert.equal(result.decision.execution.enabled, false);
+    assert.equal(engine.groundings.length, 0);
+  }
+});
+
+test("only the chosen described click is grounded, once, and mapped to bound screenshot pixels", async () => {
+  const engine = provider({ choice: "save" });
+  const result = await decideComputerStep(input({ actions: [SCROLL, CLICK, { ...CLICK, id: "other", target: "Cancel button" }] }), { enabled: true, provider: engine });
+  assert.equal(result.decision.status, "needs_confirmation");
+  assert.deepEqual(result.action.args, { button: "left", x: 160, y: 90 });
+  assert.equal(result.action.target, CLICK.target);
+  assert.deepEqual(result.action.grounding, { box: BOX, visibility: 0.99, confidence: 0.95, coordinate_space: "screenshot_pixels" });
+  assert.equal(result.action.screenshot.sha256, `sha256:${createHash("sha256").update(Buffer.from(PNG, "base64")).digest("hex")}`);
+  assert.equal(result.action.screenshot.requires_current, true);
+  assert.equal(result.action.screenshot.width, 400);
+  assert.equal(result.action.screenshot.height, 300);
+  assert.equal(engine.groundings.length, 1);
+  assert.equal(JSON.stringify(result.request.context).includes(PNG), false);
+  assert.equal(JSON.stringify(result.decision).includes(PNG), false);
+  assert.deepEqual(CLICK.args, { button: "left" });
+});
+
+test("absent, malformed, and uncertain grounding yields no action while retaining routing correlation", async () => {
+  const badResults = [
+    [grounding(0), "target_not_visible"],
+    [grounding(0.899), "target_not_visible"],
+    [grounding(0.99, 0.799), "low_grounding_confidence"],
+    [grounding(Number.NaN), "malformed_grounding"],
+    [grounding(Infinity), "malformed_grounding"],
+    [grounding("0.99"), "malformed_grounding"],
+    [grounding(0.99, Infinity), "malformed_grounding"],
+    [{ answers: { target_box: grounding().answers.target_box } }, "malformed_grounding"],
+    [grounding(0.99, 0.95, { ...BOX, left: -0.1 }), "malformed_grounding"],
+    [grounding(0.99, 0.95, { ...BOX, right: 1.1 }), "malformed_grounding"],
+    [grounding(0.99, 0.95, { ...BOX, left: BOX.right }), "malformed_grounding"],
+    [grounding(0.99, 0.95, { ...BOX, top: BOX.bottom + 0.1 }), "malformed_grounding"],
+    [grounding(0.99, 0.95, { ...BOX, bottom: Number.NaN }), "malformed_grounding"],
+  ];
+  for (const [raw, type] of badResults) {
+    const result = await decideComputerStep(input({ actions: [CLICK] }), { enabled: true, provider: provider({ result: raw }) });
+    assertFallback(result, type);
+    assert.equal(result.decision.selected, CLICK.id);
+    assert.equal(result.decision.receipt.provider, "computer-test");
+    assert.equal(result.decision.receipt.candidate_count, 1);
+  }
+});
+
+test("host grounding thresholds are inclusive and edge pixels remain inside the screenshot", async () => {
+  const engine = provider({ result: grounding(0.95, 0.9, { left: 0.999, right: 1, top: 0.999, bottom: 1 }) });
+  const result = await decideComputerStep(input({ actions: [CLICK], policy: { min_target_visibility: 0.95, min_box_confidence: 0.9 } }), { enabled: true, provider: engine });
+  assert.deepEqual(result.action.args, { button: "left", x: 399, y: 299 });
+  const stricter = await decideComputerStep(input({ actions: [CLICK] }), { enabled: true, provider: engine, policy: { min_target_visibility: 0.96 } });
+  assertFallback(stricter, "target_not_visible");
+});
+
+test("route fallback, provider failures, unsupported images, and unknown selections never leak actions", async () => {
+  assertFallback(await decideComputerStep(input(), { enabled: true, provider: provider({ confidence: 0.2 }) }), "low_confidence");
+  assertFallback(await decideComputerStep(input(), { enabled: true, provider: provider({ choice: "not-host-supplied" }) }), "invalid_selection");
+  assertFallback(await decideComputerStep(input({ actions: [CLICK] }), { enabled: true, provider: provider({ error: true }) }), "provider_error");
+  const unavailable = provider();
+  unavailable.supportsImages = false;
+  assertFallback(await decideComputerStep(input(), { enabled: true, provider: unavailable }), "unsupported_images");
+  assert.equal(unavailable.choices.length, 0);
+  const noGrounding = provider();
+  delete noGrounding.evaluate;
+  assertFallback(await decideComputerStep(input({ actions: [CLICK] }), { enabled: true, provider: noGrounding }), "grounding_unavailable");
+  const broken = provider();
+  broken.decide = async () => { throw new Error("offline"); };
+  assertFallback(await decideComputerStep(input(), { enabled: true, provider: broken }), "provider_error");
+});
+
+test("handoff is advisory and nonselected described targets are never grounded", async () => {
+  const engine = provider({ choice: "handoff" });
+  const action = { id: "handoff", operation: "handoff", args: { reason: "Host planning needed" }, available: true, risk: "low" };
+  const result = await decideComputerStep(input({ actions: [CLICK, action] }), { enabled: true, provider: engine });
+  assert.equal(result.decision.status, "selected");
+  assert.equal(result.action.operation, "handoff");
+  assert.equal(engine.groundings.length, 0);
+  assert.equal(result.decision.execution.enabled, false);
+});

package/test/context-filter.test.mjs

@@ -1,65 +1,65 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { filterContext } from "../src/relevance-filter.mjs";
-import { projectState } from "../src/context-filter.mjs";
-import { routeRequest } from "../src/route.mjs";
-
-const capabilities = [{ id: "inspect", kind: "tool", name: "Inspect", description: "Inspect the supplied context", risk: "low" }];
-
-function messages() {
-  return [
-    ...Array.from({ length: 10 }, (_, index) => `old unrelated note ${index}`),
-    "Requirement: preserve /workspace/project/config.json exactly",
-    "command: `npm test` failed with exit status 1; Error: fixture failed",
-    "recent worker update",
-  ];
-}
-
-test("shadow mode never mutates context and reports evidence", () => {
-  const context = { messages: messages() };
-  const before = JSON.stringify(context);
-  const result = filterContext(context, { mode: "shadow", recent: 2 });
-  assert.strictEqual(result.context, context);
-  assert.equal(JSON.stringify(context), before);
-  assert.equal(result.report.mode, "shadow");
-  assert.equal(result.report.changed, false);
-  assert.ok(result.report.pinned >= 2);
-});
-
-test("conservative mode drops stale noise but preserves exact evidence", () => {
-  const result = filterContext({ messages: messages() }, { mode: "conservative", recent: 2 });
-  assert.equal(result.report.mode, "conservative");
-  assert.equal(result.report.changed, true);
-  assert.ok(result.report.dropped > 0);
-  assert.ok(result.context.messages.includes("Requirement: preserve /workspace/project/config.json exactly"));
-  assert.ok(result.context.messages.includes("command: `npm test` failed with exit status 1; Error: fixture failed"));
-  assert.ok(!result.context.messages.includes("old unrelated note 0"));
-});
-
-test("route projection applies explicit filtering without losing pinned evidence", async () => {
-  let captured;
-  const decision = await routeRequest({
-    intent: "inspect project state",
-    policy: { context_filter_mode: "conservative" },
-    context: { messages: messages() },
-    capabilities,
-  }, {
-    provider: {
-      name: "context-filter-test-provider",
-      async decide({ state }) {
-        captured = state;
-        return { answers: { tool: { type: "choice", choice: "inspect", probabilities: { inspect: 1 }, confidence: 1 } } };
-      },
-    },
-  });
-  assert.equal(decision.status, "selected");
-  assert.equal(captured.context_filter.mode, "conservative");
-  assert.ok(captured.context.messages.includes("Requirement: preserve /workspace/project/config.json exactly"));
-  assert.ok(captured.context.messages.includes("command: `npm test` failed with exit status 1; Error: fixture failed"));
-});
-
-test("no mode keeps the existing projection contract", () => {
-  const result = projectState({ intent: "inspect", context: { messages: ["plain"] } }, capabilities, 6_000);
-  assert.equal(result.state.context_filter, undefined);
-  assert.deepEqual(result.state.context, { messages: ["plain"] });
-});
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { filterContext } from "../src/relevance-filter.mjs";
+import { projectState } from "../src/context-filter.mjs";
+import { routeRequest } from "../src/route.mjs";
+
+const capabilities = [{ id: "inspect", kind: "tool", name: "Inspect", description: "Inspect the supplied context", risk: "low" }];
+
+function messages() {
+  return [
+    ...Array.from({ length: 10 }, (_, index) => `old unrelated note ${index}`),
+    "Requirement: preserve /workspace/project/config.json exactly",
+    "command: `npm test` failed with exit status 1; Error: fixture failed",
+    "recent worker update",
+  ];
+}
+
+test("shadow mode never mutates context and reports evidence", () => {
+  const context = { messages: messages() };
+  const before = JSON.stringify(context);
+  const result = filterContext(context, { mode: "shadow", recent: 2 });
+  assert.strictEqual(result.context, context);
+  assert.equal(JSON.stringify(context), before);
+  assert.equal(result.report.mode, "shadow");
+  assert.equal(result.report.changed, false);
+  assert.ok(result.report.pinned >= 2);
+});
+
+test("conservative mode drops stale noise but preserves exact evidence", () => {
+  const result = filterContext({ messages: messages() }, { mode: "conservative", recent: 2 });
+  assert.equal(result.report.mode, "conservative");
+  assert.equal(result.report.changed, true);
+  assert.ok(result.report.dropped > 0);
+  assert.ok(result.context.messages.includes("Requirement: preserve /workspace/project/config.json exactly"));
+  assert.ok(result.context.messages.includes("command: `npm test` failed with exit status 1; Error: fixture failed"));
+  assert.ok(!result.context.messages.includes("old unrelated note 0"));
+});
+
+test("route projection applies explicit filtering without losing pinned evidence", async () => {
+  let captured;
+  const decision = await routeRequest({
+    intent: "inspect project state",
+    policy: { context_filter_mode: "conservative" },
+    context: { messages: messages() },
+    capabilities,
+  }, {
+    provider: {
+      name: "context-filter-test-provider",
+      async decide({ state }) {
+        captured = state;
+        return { answers: { tool: { type: "choice", choice: "inspect", probabilities: { inspect: 1 }, confidence: 1 } } };
+      },
+    },
+  });
+  assert.equal(decision.status, "selected");
+  assert.equal(captured.context_filter.mode, "conservative");
+  assert.ok(captured.context.messages.includes("Requirement: preserve /workspace/project/config.json exactly"));
+  assert.ok(captured.context.messages.includes("command: `npm test` failed with exit status 1; Error: fixture failed"));
+});
+
+test("no mode keeps the existing projection contract", () => {
+  const result = projectState({ intent: "inspect", context: { messages: ["plain"] } }, capabilities, 6_000);
+  assert.equal(result.state.context_filter, undefined);
+  assert.deepEqual(result.state.context, { messages: ["plain"] });
+});

package/test/hermes-adapter.test.mjs

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const adapter = fileURLToPath(new URL("../src/hermes-adapter.mjs", import.meta.url));
+
+function run(lines, replayPath) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [adapter], { env: { ...process.env, JEV_REPLAY_CASES: replayPath } });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => { out += chunk; });
+    child.stderr.on("data", (chunk) => { err += chunk; });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) return reject(new Error(err || `adapter exited ${code}`));
+      resolve(out.trim().split(/\r?\n/).filter(Boolean).map(JSON.parse));
+    });
+    child.stdin.end(lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
+  });
+}
+
+test("Hermes adapter routes a closed candidate set and records a correlated receipt", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jev-hermes-adapter-"));
+  const replayPath = join(dir, "cases.jsonl");
+  const routeRequest = { operation: "route", args: { harness: "hermes-test", intent: "Read a source file", provider: "demo", actor_permissions: ["read"], capabilities: [
+    { id: "read", kind: "tool", name: "Read file", description: "Read a local text file", permissions: ["read"], risk: "low", available: true },
+    { id: "write", kind: "tool", name: "Write file", description: "Mutate a local file", permissions: ["write"], risk: "high", available: true },
+  ] } };
+  const [decision] = await run([routeRequest], replayPath);
+  assert.equal(decision.status, "selected");
+  assert.equal(decision.selected, "read");
+  assert.ok(decision.correlation_id);
+  assert.ok(decision._jev_request);
+  const [receipt] = await run([{ operation: "record_execution", decision, args: { correlation_id: decision.correlation_id, harness: "hermes-test", capability_id: "read", status: "completed", result: { lines: 3 }, duration_ms: 4 } }], replayPath);
+  assert.equal(receipt.record_type, "execution_receipt");
+  assert.equal(receipt.correlation_id, decision.correlation_id);
+  assert.equal(receipt.host.status, "completed");
+  const records = (await readFile(replayPath, "utf8")).trim().split(/\r?\n/).map(JSON.parse);
+  assert.equal(records.filter((record) => record.record_type === "routing_case").length, 1);
+  assert.equal(records.filter((record) => record.record_type === "execution_receipt").length, 1);
+});
+
+test("Hermes adapter exposes supervision, shadow-compaction, and browser surfaces without execution", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "jev-hermes-adapter-"));
+  const replayPath = join(dir, "cases.jsonl");
+  const [supervision, shadow, browser] = await run([
+    { operation: "supervise", args: { provider: "demo", enabled: true, harness: "hermes-test", job: { goal: "verify" }, observation: { state: "done" }, evidence: { tests_passed: true } } },
+    { operation: "shadow_compaction", args: { provider: "demo", intent: "review context", context: { messages: ["old note", "Requirement: preserve /workspace/project/config.json"] } } },
+    { operation: "browser_step", args: { provider: "demo", enabled: true, harness: "hermes-test", goal: "Open the visible docs link", observation: { url: "https://example.test", targets: [{ id: "docs", name: "Docs", href: "/docs", visible: true, clickable: true }], tabs: [], scroll: { down: false, up: false } } } },
+  ], replayPath);
+  assert.equal(supervision.status, "judged");
+  assert.ok(["continue", "verify", "retry", "finish", "escalate"].includes(supervision.action));
+  assert.equal(shadow.mode, "jev_shadow");
+  assert.equal(shadow.changed, false);
+  assert.equal(shadow.protected_count, 1);
+  assert.ok(["selected", "fallback", "no_decision", "needs_confirmation"].includes(browser.status));
+  assert.equal(browser.execution.enabled, false);
+});

package/test/image-fixture.mjs

@@ -0,0 +1,2 @@
+// Complete 400x300 still RGB PNG, generated with zlib and valid chunk CRCs.
+export const PNG = "iVBORw0KGgoAAAANSUhEUgAAAZAAAAEsCAIAAABi1XKVAAABdElEQVR4nO3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD+Bn+3AAEkkD9cAAAAAElFTkSuQmCC";

package/test/images.test.mjs

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { normalizeImageAssets } from "../src/images.mjs";
+import { OpenRouterDecisionsProvider, TypeSafeProvider } from "../src/providers/typesafe.mjs";
+import { routeRequest } from "../src/route.mjs";
+import { PNG as png } from "./image-fixture.mjs";
+
+const reference = "frame-6e1d0b7c";
+const image = { type: "image", format: "png", data_base64: png };
+const assets = { [reference]: image };
+const candidates = [{ id: "search", name: "Search", kind: "mcp", description: "Search files", permissions: ["read"], risk: "low" }];
+const request = { intent: "Inspect the image and choose a capability", actor_permissions: ["read"], capabilities: candidates, assets };
+const questions = { visible: { type: "noul", instructions: "Is the target visible?" }, target: { type: "box", instructions: "the target in `screenshot`" } };
+
+// Keep provider resolution deterministic without using developer credentials.
+for (const key of Object.keys(process.env)) {
+  if (/^(JEV_|TYPESAFE_|OPENROUTER_)/.test(key)) delete process.env[key];
+}
+
+test("image reference names cannot change the output object's prototype", () => {
+  const special = normalizeImageAssets(JSON.parse(`{"__proto__":${JSON.stringify(image)}}`));
+  assert.equal(Object.hasOwn(special, "__proto__"), true);
+  assert.equal(Object.getPrototypeOf(special), Object.prototype);
+});
+
+test("image trust boundary rejects malformed maps, references, formats and noncanonical base64", () => {
+  for (const input of [null, [], "file.png", { "": image }, { " ": image }, { ["é".repeat(513)]: image }]) {
+    assert.throws(() => normalizeImageAssets(input));
+  }
+  for (const invalid of [
+    { ...image, format: "webp" }, { ...image, format: "jpg" }, { ...image, type: "video" },
+    { ...image, part: "file" }, { ...image, url: "https://example.test/image.png" },
+    { ...image, data_base64: `data:image/png;base64,${png}` },
+    { ...image, data_base64: `${png}\n` }, { ...image, data_base64: "AB==" },
+    { ...image, data_base64: "!!!!" }, { ...image, data_base64: png.slice(0, -4) },
+  ]) assert.throws(() => normalizeImageAssets({ [reference]: invalid }));
+  const manyReferences = Object.fromEntries(Array.from({ length: 65 }, (_, i) => [`${i}-${"x".repeat(1018)}`, image]));
+  assert.throws(() => normalizeImageAssets(manyReferences), /references/);
+});
+
+test("image dimensions, animation and decoded byte limits are checked locally", () => {
+  for (const [width, height] of [[256, 256], [255, 400], [400, 1569]]) {
+    const bytes = Buffer.from(png, "base64");
+    bytes.writeUInt32BE(width, 16);
+    bytes.writeUInt32BE(height, 20);
+    assert.throws(() => normalizeImageAssets({ [reference]: { ...image, data_base64: bytes.toString("base64") } }), /dimensions/);
+  }
+  const bytes = Buffer.from(png, "base64");
+  const animation = Buffer.alloc(20);
+  animation.writeUInt32BE(8);
+  animation.write("acTL", 4);
+  const animated = Buffer.concat([bytes.subarray(0, 33), animation, bytes.subarray(33)]).toString("base64");
+  assert.throws(() => normalizeImageAssets({ [reference]: { ...image, data_base64: animated } }), /animated/);
+  const tooLarge = "A".repeat(4 * Math.ceil((16 * 1024 * 1024 + 1) / 3));
+  assert.throws(() => normalizeImageAssets({ [reference]: { ...image, data_base64: tooLarge } }), /16 MiB/);
+});
+
+for (const Provider of [TypeSafeProvider, OpenRouterDecisionsProvider]) {
+  test(`${Provider.name} rejects unreferenced images and oversized requests before HTTP`, async () => {
+    let calls = 0;
+    const provider = new Provider({ apiKey: "fixture-key", fetchImpl: async () => { calls += 1; return Response.json({ answers: {} }); } });
+    await assert.rejects(provider.evaluate({ state: { [reference]: "not an image reference" }, questions, assets }), /must be referenced/);
+    await assert.rejects(provider.evaluate({ state: "x".repeat(32 * 1024 * 1024), questions: {} }), /32 MiB/);
+    assert.equal(calls, 0);
+  });
+}
+
+for (const Provider of [TypeSafeProvider, OpenRouterDecisionsProvider]) {
+  test(`${Provider.name} image errors remain fail-open without leaking bytes`, async () => {
+    for (const settings of [
+      { apiKey: "", fetchImpl: () => { throw new Error("must not call HTTP"); } },
+      { apiKey: "fixture-key", fetchImpl: async () => new Response(png, { status: 400 }) },
+      { apiKey: "fixture-key", fetchImpl: async () => new Response(png) },
+      { apiKey: "fixture-key", fetchImpl: async () => { throw new Error(png); } },
+      { apiKey: "fixture-key", fetchImpl: async () => { throw new DOMException("fixture timeout", "TimeoutError"); } },
+    ]) {
+      const result = await routeRequest(request, { provider: new Provider(settings) });
+      assert.equal(result.status, "fallback");
+      assert.equal(result.fallback.type, "provider_error");
+      assert.equal(result.execution.enabled, false);
+      assert.equal(JSON.stringify(result).includes(png), false);
+    }
+  });
+}
+

package/test/model-route-metrics.test.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { buildModelRouteReport } from "../src/model-route-metrics.mjs";
+
+const rows = [
+  {
+    record_type: "routing_case",
+    correlation_id: "one",
+    request: { context: { model_route: { mode: "shadow", profiles: [{ id: "fast" }, { id: "frontier" }] } } },
+    decision: { status: "selected", selected: "fast", receipt: { latency_ms: 4, cost_usd: 0.001 } },
+  },
+  {
+    record_type: "execution_receipt",
+    correlation_id: "one",
+    host: {
+      status: "completed",
+      duration_ms: 20,
+      result: { model_route: { actual_model_id: "fast", retry_count: 1, outcome: "verified" } },
+    },
+  },
+  {
+    record_type: "routing_case",
+    correlation_id: "two",
+    request: { context: { model_route: { mode: "shadow", profiles: [{ id: "fast" }, { id: "frontier" }] } } },
+    decision: { status: "selected", selected: "frontier", receipt: { latency_ms: 6, cost_usd: 0.002 } },
+  },
+  {
+    record_type: "execution_receipt",
+    correlation_id: "two",
+    host: {
+      status: "failed",
+      duration_ms: 30,
+      result: { model_route: { actual_model_id: "fast", retry_count: 2, outcome: "failed" } },
+    },
+  },
+];
+
+test("model route report joins shadow recommendation to host outcome without treating it as a route change", () => {
+  const report = buildModelRouteReport(rows);
+  assert.equal(report.schema_version, 1);
+  assert.equal(report.summary.decisions, 2);
+  assert.equal(report.summary.with_host_outcome, 2);
+  assert.equal(report.summary.recommendation_match_rate, 0.5);
+  assert.equal(report.summary.verified_outcomes, 1);
+  assert.equal(report.summary.failed_outcomes, 1);
+  assert.equal(report.summary.total_retry_count, 3);
+  assert.deepEqual(report.models.map((row) => row.recommended_model_id), ["fast", "frontier"]);
+  assert.equal(report.models[0].host_actual_model_ids.fast, 1);
+  assert.equal(report.models[1].host_actual_model_ids.fast, 1);
+  assert.equal(report.models[1].recommendation_matches, 0);
+});
+
+test("model route report fails open on incomplete or unrelated receipts", () => {
+  const report = buildModelRouteReport([
+    { record_type: "routing_case", correlation_id: "unrelated", request: { context: {} }, decision: { selected: "tool" } },
+    { record_type: "routing_case", correlation_id: "pending", request: { context: { model_route: { mode: "shadow" } } }, decision: { selected: null } },
+  ]);
+  assert.equal(report.summary.decisions, 1);
+  assert.equal(report.summary.with_host_outcome, 0);
+  assert.equal(report.models[0].recommended_model_id, "unrecommended");
+});

package/test/model-routing.test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { recommendModelRoute } from "../src/model-routing.mjs";
+
+const models = [
+  {
+    id: "fast",
+    provider: "openrouter",
+    model: "small-model",
+    reasoning_effort: "low",
+    description: "fast and cheap for simple classification or file inspection",
+  },
+  {
+    id: "frontier",
+    provider: "openai-codex",
+    model: "frontier-model",
+    reasoning_effort: "high",
+    description: "strong model for difficult implementation and ambiguous reasoning",
+  },
+];
+
+test("model routing returns an advisory profile and never changes the host route", async () => {
+  let captured;
+  const result = await recommendModelRoute({
+    intent: "classify a small batch of already structured feedback",
+    context: { task_size: "small", external_side_effects: false },
+    models,
+    provider: {
+      name: "model-route-test-provider",
+      async decide(input) {
+        captured = input;
+        return {
+          answers: { tool: { type: "choice", choice: "fast", probabilities: { fast: 0.92, frontier: 0.08 }, confidence: 0.92 } },
+          usage: { cost: 0.0001 },
+        };
+      },
+    },
+  });
+
+  assert.equal(result.route_mode, "shadow");
+  assert.equal(result.status, "selected");
+  assert.equal(result.selected, "fast");
+  assert.equal(result.recommended_model.model, "small-model");
+  assert.equal(result.execution.enabled, false);
+  assert.equal(captured.candidates.every((candidate) => candidate.kind === "model"), true);
+});
+
+test("model routing excludes unavailable profiles and fails open with no selected profile", async () => {
+  const result = await recommendModelRoute({
+    intent: "inspect a file",
+    models: [{ ...models[0], available: false }],
+    provider: "demo",
+  });
+
+  assert.equal(result.status, "no_decision");
+  assert.equal(result.selected, null);
+  assert.equal(result.recommended_model, null);
+  assert.equal(result.execution.enabled, false);
+});