jev-layer 0.1.0 → 0.2.0

package/test/hermes-adapter.test.mjs

@@ -0,0 +1,62 @@
+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 test from "node:test";
+
+const adapter = new URL("../src/hermes-adapter.mjs", import.meta.url).pathname;
+
+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/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);
+});

package/test/openrouter-provider.test.mjs

@@ -1,55 +1,55 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { OpenRouterDecisionsProvider } from "../src/providers/typesafe.mjs";
-
-const candidates = [{
-  id: "search",
-  kind: "mcp",
-  name: "Repository search",
-  description: "Search repository files",
-  risk: "low",
-}];
-
-test("OpenRouter provider sends Decisions Choice payload, not chat completion payload", async () => {
-  let requestUrl;
-  let requestInit;
-  const provider = new OpenRouterDecisionsProvider({
-    apiKey: "test-key",
-    endpoint: "https://openrouter.ai/api/alpha/decisions",
-    model: "typesafe/jev-1.13",
-    fetchImpl: async (url, init) => {
-      requestUrl = url;
-      requestInit = init;
-      return new Response(JSON.stringify({
-        id: "decision-test",
-        model: "typesafe/jev-1.13",
-        provider: "TypeSafe",
-        answers: {
-          tool: {
-            type: "choice",
-            choice: "search",
-            probabilities: { search: 1 },
-            confidence: 1,
-          },
-        },
-        usage: { input_tokens: 10, output_tokens: 2, cost: 0.000001 },
-      }), { status: 200, headers: { "content-type": "application/json" } });
-    },
-  });
-
-  const raw = await provider.decide({
-    state: { intent: "Search repository files" },
-    candidates,
-  });
-  const body = JSON.parse(requestInit.body);
-  assert.equal(requestUrl, "https://openrouter.ai/api/alpha/decisions");
-  assert.equal(requestInit.method, "POST");
-  assert.equal(requestInit.headers.Authorization, "Bearer test-key");
-  assert.equal(body.model, "typesafe/jev-1.13");
-  assert.equal(body.questions.tool.type, "choice");
-  assert.equal(body.questions.tool.criteria.search.description, "Search repository files");
-  assert.deepEqual(body.state, { intent: "Search repository files" });
-  assert.equal("messages" in body, false);
-  assert.equal(raw.answers.tool.choice, "search");
-  assert.equal(raw.usage.cost, 0.000001);
-});
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { OpenRouterDecisionsProvider } from "../src/providers/typesafe.mjs";
+
+const candidates = [{
+  id: "search",
+  kind: "mcp",
+  name: "Repository search",
+  description: "Search repository files",
+  risk: "low",
+}];
+
+test("OpenRouter provider sends Decisions Choice payload, not chat completion payload", async () => {
+  let requestUrl;
+  let requestInit;
+  const provider = new OpenRouterDecisionsProvider({
+    apiKey: "test-key",
+    endpoint: "https://openrouter.ai/api/alpha/decisions",
+    model: "typesafe/jev-1.13",
+    fetchImpl: async (url, init) => {
+      requestUrl = url;
+      requestInit = init;
+      return new Response(JSON.stringify({
+        id: "decision-test",
+        model: "typesafe/jev-1.13",
+        provider: "TypeSafe",
+        answers: {
+          tool: {
+            type: "choice",
+            choice: "search",
+            probabilities: { search: 1 },
+            confidence: 1,
+          },
+        },
+        usage: { input_tokens: 10, output_tokens: 2, cost: 0.000001 },
+      }), { status: 200, headers: { "content-type": "application/json" } });
+    },
+  });
+
+  const raw = await provider.decide({
+    state: { intent: "Search repository files" },
+    candidates,
+  });
+  const body = JSON.parse(requestInit.body);
+  assert.equal(requestUrl, "https://openrouter.ai/api/alpha/decisions");
+  assert.equal(requestInit.method, "POST");
+  assert.equal(requestInit.headers.Authorization, "Bearer test-key");
+  assert.equal(body.model, "typesafe/jev-1.13");
+  assert.equal(body.questions.tool.type, "choice");
+  assert.equal(body.questions.tool.criteria.search.description, "Search repository files");
+  assert.deepEqual(body.state, { intent: "Search repository files" });
+  assert.equal("messages" in body, false);
+  assert.equal(raw.answers.tool.choice, "search");
+  assert.equal(raw.usage.cost, 0.000001);
+});

package/test/provider-transports.test.mjs

@@ -0,0 +1,205 @@
+import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { routeRequest } from "../src/route.mjs";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const request = {
+  intent: "Search repository files",
+  actor_permissions: ["read"],
+  capabilities: [
+    { id: "search", name: "Repository search", description: "Search repository files", risk: "low", permissions: ["read"] },
+    { id: "clock", name: "Clock", description: "Report the current time", risk: "low", permissions: ["read"] },
+  ],
+};
+const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(JEV_|TYPESAFE_|OPENROUTER_)/.test(key)));
+const hasPython = spawnSync("python3", ["--version"]).status === 0;
+
+test("provider configuration reaches CLI, MCP and adapters over local HTTP", { timeout: 30_000 }, async (t) => {
+  const workspace = await mkdtemp(join(tmpdir(), "jev-providers-"));
+  t.after(() => rm(workspace, { recursive: true, force: true }));
+  const calls = [];
+  const server = createServer(async (incoming, outgoing) => {
+    let text = "";
+    for await (const chunk of incoming) text += chunk;
+    const body = JSON.parse(text);
+    calls.push({ url: incoming.url, headers: incoming.headers, body });
+    if (incoming.url === "/timeout") return;
+    const answers = Object.fromEntries(Object.entries(body.questions).map(([id, question]) => {
+      if (question.type === "noul") return [id, { type: "noul", noul: 0.1 }];
+      const ids = Object.keys(question.criteria);
+      const choice = ids.includes("search") ? "search" : ids[0];
+      return [id, { type: "choice", choice, confidence: 1, probabilities: Object.fromEntries(ids.map((key) => [key, key === choice ? 1 : 0])) }];
+    }));
+    outgoing.setHeader("Content-Type", "application/json");
+    outgoing.end(JSON.stringify({ model: body.model, answers, usage: { input_tokens: 10, output_tokens: 2 } }));
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  t.after(() => { server.closeAllConnections(); server.close(); });
+  const endpoint = `http://127.0.0.1:${server.address().port}`;
+  const configPath = join(workspace, "config.json");
+  const casesPath = join(workspace, "cases.jsonl");
+  const env = {
+    ...cleanEnv,
+    JEV_CONFIG: configPath,
+    JEV_REPLAY_CASES: casesPath,
+    TYPESAFE_API_KEY: "fixture-typesafe",
+    TYPESAFE_ENDPOINT: `${endpoint}/typesafe`,
+    TYPESAFE_MODEL: "fixture-typesafe-model",
+    OPENROUTER_API_KEY: "fixture-openrouter",
+    OPENROUTER_DECISIONS_ENDPOINT: `${endpoint}/openrouter`,
+    OPENROUTER_DECISIONS_MODEL: "fixture-openrouter-model",
+    JEV_NODE: process.execPath,
+    PYTHONDONTWRITEBYTECODE: "1",
+  };
+
+  async function run(args, input, overrides = {}, command = process.execPath) {
+    const child = spawn(command, args, { cwd: workspace, env: { ...env, ...overrides }, stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.stdin.end(input);
+    const [code] = await once(child, "close");
+    assert.equal(code, 0, stderr);
+    assert.equal(stderr, "");
+    return stdout.trim().split(/\r?\n/).map((line) => JSON.parse(line));
+  }
+
+  async function cli(payload = request, args = [], overrides = {}) {
+    return (await run([join(root, "bin/jev.mjs"), "cli", ...args], JSON.stringify(payload), overrides))[0];
+  }
+
+  async function mcp(payload = request, overrides = {}, name = "jev_route") {
+    const messages = [
+      { jsonrpc: "2.0", id: 1, method: "initialize", params: {} },
+      { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name, arguments: payload } },
+    ];
+    const responses = await run([join(root, "bin/jev.mjs"), "mcp"], messages.map((message) => JSON.stringify(message)).join("\n") + "\n", overrides);
+    assert.equal(responses[0].result.serverInfo.name, "jev-layer");
+    assert.equal(responses[1].error, undefined);
+    return responses[1].result.structuredContent;
+  }
+
+  function selected(decision, provider, before) {
+    assert.equal(decision.status, "selected");
+    assert.equal(decision.selected, "search");
+    assert.ok(decision.correlation_id);
+    assert.deepEqual(decision.execution, { enabled: false, status: "not_started" });
+    assert.equal(calls.length, before + (provider === "demo" ? 0 : 1));
+    if (provider === "demo") return;
+    assert.equal(calls.at(-1).url, `/${provider}`);
+    assert.equal(calls.at(-1).headers.authorization, `Bearer fixture-${provider}`);
+    assert.equal(calls.at(-1).body.model, `fixture-${provider}-model`);
+    if (provider === "openrouter") assert.equal(decision.receipt.provider, "openrouter:fixture-openrouter-model");
+  }
+
+  for (const provider of ["demo", "openrouter", "typesafe"]) {
+    for (const transport of ["cli", "mcp"]) {
+      await t.test(`${provider} via ${transport}: explicit selection overrides environment and config`, async () => {
+        await writeFile(configPath, JSON.stringify({ provider: "unknown" }));
+        const before = calls.length;
+        const decision = transport === "cli"
+          ? await cli({ ...request, provider }, ["--provider", "unknown"], { JEV_LAYER_PROVIDER: "unknown" })
+          : await mcp({ ...request, provider }, { JEV_LAYER_PROVIDER: "unknown" });
+        selected(decision, provider, before);
+      });
+      await t.test(`${provider} via ${transport}: environment overrides config`, async () => {
+        await writeFile(configPath, JSON.stringify({ provider: "unknown" }));
+        const before = calls.length;
+        const decision = transport === "cli"
+          ? await cli(request, [], { JEV_LAYER_PROVIDER: provider })
+          : await mcp(request, { JEV_LAYER_PROVIDER: provider });
+        selected(decision, provider, before);
+      });
+      await t.test(`${provider} via ${transport}: project configuration`, async () => {
+        await writeFile(configPath, JSON.stringify({ provider }));
+        const before = calls.length;
+        selected(await (transport === "cli" ? cli() : mcp()), provider, before);
+      });
+    }
+    await t.test(`${provider} via CLI flag overrides environment and config`, async () => {
+      await writeFile(configPath, JSON.stringify({ provider: "unknown" }));
+      const before = calls.length;
+      selected(await cli(request, ["--provider", provider], { JEV_LAYER_PROVIDER: "unknown" }), provider, before);
+    });
+    await t.test(`${provider} remains disabled without HTTP`, async () => {
+      const before = calls.length;
+      for (const decision of [await cli({ ...request, provider }, [], { JEV_LAYER_ENABLED: "0" }), await mcp({ ...request, provider }, { JEV_LAYER_ENABLED: "0" })]) {
+        assert.equal(decision.fallback.type, "disabled");
+        assert.equal(decision.execution.enabled, false);
+      }
+      assert.equal(calls.length, before);
+    });
+  }
+
+  for (const provider of ["openrouter", "typesafe"]) {
+    await writeFile(configPath, JSON.stringify({ provider, providers: { [provider]: {
+      api_key_env: "FIXTURE_KEY", endpoint_env: "FIXTURE_ENDPOINT", model_env: "FIXTURE_MODEL",
+    } } }));
+    const aliases = { FIXTURE_KEY: `fixture-${provider}`, FIXTURE_ENDPOINT: `${endpoint}/${provider}`, FIXTURE_MODEL: `fixture-${provider}-model` };
+    const guardedEnv = { ...aliases, TYPESAFE_API_KEY: "", OPENROUTER_API_KEY: "", TYPESAFE_ENDPOINT: `${endpoint}/wrong`, OPENROUTER_DECISIONS_ENDPOINT: `${endpoint}/wrong` };
+    for (const transport of ["cli", "mcp"]) {
+      await t.test(`${provider} via ${transport}: configured environment variable names`, async () => {
+        const before = calls.length;
+        selected(await (transport === "cli" ? cli(request, [], guardedEnv) : mcp(request, guardedEnv)), provider, before);
+      });
+      await t.test(`${provider} via ${transport}: missing configured key fails open`, async () => {
+        const before = calls.length;
+        const decision = await (transport === "cli" ? cli(request) : mcp());
+        assert.equal(decision.fallback.type, "provider_error");
+        assert.equal(calls.length, before);
+      });
+    }
+    await t.test(`${provider} configuration reaches MCP supervision and browser decisions`, async () => {
+      const before = calls.length;
+      const supervised = await mcp({ enabled: true, job: {}, observation: {} }, guardedEnv, "jev_supervise");
+      assert.equal(supervised.status, "judged");
+      const browser = await mcp({ enabled: true, goal: "Scroll down", observation: { scroll: { down: true } } }, guardedEnv, "jev_browser_step");
+      assert.equal(browser.status, "selected");
+      assert.equal(browser.selected, "browser:scroll:down");
+      assert.equal(browser.execution.enabled, false);
+      assert.equal(calls.length, before + 2);
+      assert.equal(calls.at(-1).url, `/${provider}`);
+    });
+    await t.test(`${provider} times out an actual stalled HTTP request`, async () => {
+      const decision = await routeRequest(request, { provider, [provider]: { apiKey: "fixture-key", endpoint: `${endpoint}/timeout`, timeoutMs: 50 } });
+      assert.equal(decision.fallback.type, "provider_error");
+      assert.match(decision.reason, /timed out/);
+      assert.equal(decision.execution.enabled, false);
+    });
+
+    await t.test(`${provider} project configuration reaches the OMP Node adapter`, async () => {
+      const before = calls.length;
+      const code = `
+        import extension from ${JSON.stringify(new URL("../integrations/omp/extension.js", import.meta.url).href)};
+        const field = { optional() { return this; } };
+        const zod = { string: () => field, unknown: () => field, array: () => field, object: () => field };
+        let tool;
+        extension({ zod, registerTool(value) { tool = value; } });
+        console.log(JSON.stringify((await tool.execute("fixture", ${JSON.stringify(request)})).details));
+      `;
+      selected((await run(["--input-type=module", "-e", code], "", guardedEnv))[0], provider, before);
+    });
+    await t.test(`${provider} project configuration reaches the Hermes adapter`, { skip: !hasPython }, async () => {
+      const before = calls.length;
+      const code = "import importlib.util, json, pathlib, sys\np = pathlib.Path(sys.argv[1])\nspec = importlib.util.spec_from_file_location('fixture_hermes', p, submodule_search_locations=[str(p.parent)])\nmodule = importlib.util.module_from_spec(spec)\nsys.modules[spec.name] = module\nspec.loader.exec_module(module)\nprint(module.jev_route(json.load(sys.stdin)))";
+      selected((await run(["-c", code, join(root, "integrations/hermes/__init__.py")], JSON.stringify(request), guardedEnv, "python3"))[0], provider, before);
+    });
+  }
+
+  await t.test("MCP persists routing cases with their correlation ids", async () => {
+    const records = (await readFile(casesPath, "utf8")).trim().split(/\r?\n/).map(JSON.parse);
+    assert.ok(records.some((record) => record.decision?.receipt?.provider === "typesafe"));
+    for (const record of records.filter((record) => record.record_type === "routing_case")) {
+      assert.equal(record.case_id, record.correlation_id);
+    }
+  });
+});

package/test/providers.test.mjs

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { routeRequest } from "../src/route.mjs";
+
+// Keep these offline checks independent of a developer's provider environment.
+for (const key of Object.keys(process.env)) {
+  if (/^(JEV_|TYPESAFE_|OPENROUTER_)/.test(key)) delete process.env[key];
+}
+
+const request = {
+  intent: "Search repository files",
+  actor_permissions: ["read"],
+  capabilities: [
+    { id: "search", name: "Repository search", description: "Search repository files", permissions: ["read"], risk: "low" },
+    { id: "clock", name: "Clock", description: "Report the current time", permissions: ["read"], risk: "low" },
+  ],
+};
+const answer = { type: "choice", choice: "search", probabilities: { search: 0.9, clock: 0.1 }, confidence: 0.8 };
+
+test("demo routes deterministically without a network call or credentials", async (t) => {
+  t.mock.method(globalThis, "fetch", () => { throw new Error("demo must remain offline"); });
+  const first = await routeRequest(request, { provider: "demo" });
+  const second = await routeRequest(request, { provider: "demo" });
+  assert.equal(first.status, "selected");
+  assert.equal(first.selected, "search");
+  assert.deepEqual(first.probabilities, second.probabilities);
+  assert.equal(first.receipt.provider, "jev-demo");
+  assert.equal(first.execution.enabled, false);
+  assert.equal(globalThis.fetch.mock.callCount(), 0);
+});
+
+for (const [provider, endpoint, model] of [
+  ["typesafe", "https://api.typesafe.ai/v1/systemone", "jev-latest"],
+  ["openrouter", "https://openrouter.ai/api/alpha/decisions", "typesafe/jev-1.13"],
+]) {
+  test(`${provider} routes with the documented endpoint, model, auth and Choice contract`, async () => {
+    let calls = 0;
+    const decision = await routeRequest(request, {
+      provider,
+      [provider]: {
+        apiKey: "fixture-key",
+        httpReferer: "https://example.test",
+        appTitle: "Jev fixture",
+        async fetchImpl(url, init) {
+          calls += 1;
+          assert.equal(url, endpoint);
+          assert.equal(init.method, "POST");
+          assert.equal(init.headers.Authorization, "Bearer fixture-key");
+          assert.equal(init.headers["Content-Type"], "application/json");
+          assert.ok(init.signal instanceof AbortSignal);
+          if (provider === "openrouter") {
+            assert.equal(init.headers["HTTP-Referer"], "https://example.test");
+            assert.equal(init.headers["X-Title"], "Jev fixture");
+          }
+          const body = JSON.parse(init.body);
+          assert.equal(body.model, model);
+          assert.equal(body.state.intent, request.intent);
+          assert.equal(body.questions.tool.type, "choice");
+          assert.deepEqual(Object.keys(body.questions.tool.criteria), ["search", "clock"]);
+          assert.equal(body.questions.tool.criteria.search.description, request.capabilities[0].description);
+          assert.equal("messages" in body, false);
+          return Response.json({ model, answers: { tool: answer }, usage: { input_tokens: 10, output_tokens: 2 } });
+        },
+      },
+    });
+    assert.equal(calls, 1);
+    assert.equal(decision.status, "selected");
+    assert.equal(decision.selected, "search");
+    assert.deepEqual(decision.probabilities, answer.probabilities);
+    assert.equal(decision.confidence, answer.confidence);
+    assert.deepEqual(decision.execution, { enabled: false, status: "not_started" });
+  });
+
+  test(`${provider} never calls HTTP when credentials are missing or routing is deterministic`, async () => {
+    let calls = 0;
+    const options = { provider, [provider]: { apiKey: "", fetchImpl: async () => { calls += 1; throw new Error("must not call HTTP"); } } };
+    const missing = await routeRequest(request, options);
+    assert.equal(missing.status, "fallback");
+    assert.equal(missing.fallback.type, "provider_error");
+    assert.match(missing.reason, /API_KEY is not configured/);
+    const deterministic = await routeRequest({ ...request, policy: { deterministic: true, deterministic_capability_id: "search" } }, options);
+    assert.equal(deterministic.status, "selected");
+    assert.equal(calls, 0);
+  });
+
+  for (const status of [401, 422, 429, 529]) {
+    test(`${provider} fails open on HTTP ${status} without retries`, async () => {
+      let calls = 0;
+      const decision = await routeRequest(request, { provider, [provider]: {
+        apiKey: "fixture-key",
+        async fetchImpl() { calls += 1; return new Response("fixture error", { status }); },
+      } });
+      assert.equal(calls, 1);
+      assert.equal(decision.status, "fallback");
+      assert.equal(decision.fallback.type, "provider_error");
+      assert.match(decision.reason, new RegExp(`HTTP ${status}`));
+      assert.equal(decision.execution.enabled, false);
+    });
+  }
+
+  for (const [name, response, fallback] of [
+    ["invalid JSON", "{", "provider_error"],
+    ["missing answers", {}, "provider_error"],
+    ["wrong answer type", { answers: { tool: { type: "score" } } }, "malformed_response"],
+    ["unknown capability", { answers: { tool: { ...answer, choice: "unknown" } } }, "invalid_selection"],
+    ["low confidence", { answers: { tool: { ...answer, confidence: 0.1 } } }, "low_confidence"],
+  ]) {
+    test(`${provider} fails open on ${name}`, async () => {
+      const decision = await routeRequest(request, { provider, [provider]: {
+        apiKey: "fixture-key",
+        fetchImpl: async () => new Response(typeof response === "string" ? response : JSON.stringify(response)),
+      } });
+      assert.equal(decision.status, "fallback");
+      assert.equal(decision.fallback.type, fallback);
+      assert.equal(decision.execution.enabled, false);
+    });
+  }
+}
+
+test("unsupported providers preserve the routing fallback envelope", async () => {
+  const decision = await routeRequest(request, { provider: "unknown" });
+  assert.equal(decision.status, "fallback");
+  assert.equal(decision.fallback.type, "provider_error");
+  assert.ok(decision.correlation_id);
+  assert.equal(decision.execution.enabled, false);
+});