jev-layer 0.1.0

package/integrations/hermes/schemas.py

@@ -0,0 +1,12 @@
+ROUTE = {
+    "type": "object",
+    "required": ["intent", "capabilities"],
+    "properties": {
+        "intent": {"type": "string"},
+        "harness": {"type": "string"},
+        "context": {"type": "object"},
+        "actor_permissions": {"type": "array", "items": {"type": "string"}},
+        "capabilities": {"type": "array", "items": {"type": "object"}},
+        "policy": {"type": "object"},
+    },
+}

package/integrations/omp/extension.js

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = process.env.JEV_LAYER_ROOT
+  ? resolve(process.env.JEV_LAYER_ROOT)
+  : fileURLToPath(new URL("../..", import.meta.url));
+const CORE = resolve(PACKAGE_ROOT, "src/cli.mjs");
+export default function jevLayerExtension(pi) {
+  const z = pi.zod;
+  pi.registerTool({
+    name: "jev_route",
+    label: "Jev route",
+    description: "Return one bounded Jev capability decision. The host executes the selected capability; this tool never executes it.",
+    parameters: z.object({
+      intent: z.string(),
+      harness: z.string().optional(),
+      context: z.unknown().optional(),
+      actor_permissions: z.array(z.string()).optional(),
+      capabilities: z.array(z.unknown()),
+      policy: z.unknown().optional(),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const decision = await runCore({ ...params, harness: params.harness ?? "omp" }, signal);
+      return {
+        content: [{ type: "text", text: JSON.stringify(decision) }],
+        details: decision,
+      };
+    },
+  });
+}
+
+async function runCore(payload, signal) {
+  if (globalThis.Bun?.spawn) return runCoreWithBun(payload, signal);
+  return runCoreWithNode(payload, signal);
+}
+
+async function runCoreWithBun(payload, signal) {
+  const child = Bun.spawn([process.env.JEV_NODE ?? "node", CORE, "--provider", process.env.JEV_LAYER_PROVIDER ?? "demo"], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const abort = () => child.kill("SIGTERM");
+  signal?.addEventListener("abort", abort, { once: true });
+  child.stdin.write(`${JSON.stringify(payload)}\n`);
+  child.stdin.end();
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  signal?.removeEventListener("abort", abort);
+  return parseCoreOutput(stdout, stderr, code);
+}
+
+function runCoreWithNode(payload, signal) {
+  return new Promise((resolve) => {
+    const child = spawn(process.env.JEV_NODE ?? "node", [CORE, "--provider", process.env.JEV_LAYER_PROVIDER ?? "demo"], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    const abort = () => child.kill("SIGTERM");
+    signal?.addEventListener("abort", abort, { once: true });
+    child.on("error", (error) => resolve(fallback(error.message)));
+    child.on("close", (code) => {
+      signal?.removeEventListener("abort", abort);
+      resolve(parseCoreOutput(stdout, stderr, code));
+    });
+    child.stdin.end(`${JSON.stringify(payload)}\n`);
+  });
+}
+
+function parseCoreOutput(stdout, stderr, code) {
+  if (code !== 0) return fallback(stderr.trim() || `core exited with status ${code}`);
+  const lines = stdout.split(/\r?\n/);
+  for (const line of lines) {
+    const jsonStart = line.indexOf("{");
+    if (jsonStart < 0) continue;
+    try {
+      return JSON.parse(line.slice(jsonStart));
+    } catch {
+      // Ignore non-decision lines emitted by a host runtime wrapper.
+    }
+  }
+  return fallback("core returned no valid JSON decision");
+}
+
+function fallback(reason) {
+  return {
+    schema_version: 1,
+    status: "fallback",
+    selected: null,
+    reason,
+    fallback: { type: "adapter_error", reason },
+    execution: { enabled: false, status: "not_started" },
+  };
+}

package/integrations/template/README.md

@@ -0,0 +1,10 @@
+# Template harness adapter
+
+Copy `adapter.mjs` to `integrations/<harness>/` and replace the injected callbacks with the harness's native implementations:
+
+- `jevRoute(request)`: call `jev_route` through the existing stdio MCP or CLI boundary;
+- `jevRecordExecution(args)`: call `jev_record_execution` with the original `correlation_id`;
+- `approve(capabilityId, decision, request)`: delegate to the host's normal approval UI/policy;
+- `executeNative(capabilityId, request, decision)`: resolve and execute the id through the host registry.
+
+The template intentionally does not discover arbitrary tools, grant permissions, retry actions, or spawn workers. Jev failures return `native_fallback`; the host should continue its normal path. Copy the template only after adding a harness-specific smoke fixture and compatibility entry.

package/integrations/template/adapter.mjs

@@ -0,0 +1,87 @@
+/*
+ * Copy this file to integrations/<your-harness>/adapter.mjs.
+ * The three injected functions are the only Jev/host boundaries:
+ *   jevRoute(request) -> decision from jev_route
+ *   jevRecordExecution(args) -> execution_receipt from jev_record_execution
+ *   executeNative(capabilityId, request) -> host-owned result
+ */
+
+export function createTemplateAdapter({ jevRoute, jevRecordExecution, executeNative, approve = async () => true }) {
+  for (const [name, value] of Object.entries({ jevRoute, jevRecordExecution, executeNative, approve })) {
+    if (typeof value !== "function") throw new TypeError(`${name} callback is required`);
+  }
+
+  return {
+    async run(request) {
+      let decision;
+      try {
+        decision = await jevRoute(request);
+      } catch (error) {
+        return nativeFallback("jev_unavailable", error);
+      }
+
+      if (decision?.status !== "selected" || typeof decision.selected !== "string" || decision.selected === "") {
+        return { status: "native_fallback", reason: decision?.reason ?? "no_selection", decision };
+      }
+
+      const approval = await approve(decision.selected, decision, request);
+      if (!approval) {
+        const receipt = await record(jevRecordExecution, {
+          correlation_id: decision.correlation_id,
+          harness: request.harness,
+          capability_id: decision.selected,
+          status: "not_started",
+          error: "host approval denied",
+        });
+        return { status: "native_fallback", reason: "host_confirmation_required", decision, receipt };
+      }
+
+      const started = Date.now();
+      let host;
+      try {
+        host = await executeNative(decision.selected, request, decision);
+      } catch (error) {
+        const receipt = await record(jevRecordExecution, {
+          correlation_id: decision.correlation_id,
+          harness: request.harness,
+          capability_id: decision.selected,
+          status: "failed",
+          error: boundedError(error),
+          duration_ms: Date.now() - started,
+        });
+        return { status: "native_fallback", reason: "host_execution_failed", decision, error: boundedError(error), receipt };
+      }
+
+      const receipt = await record(jevRecordExecution, {
+        correlation_id: decision.correlation_id,
+        harness: request.harness,
+        capability_id: decision.selected,
+        status: "completed",
+        result: host,
+        duration_ms: Date.now() - started,
+      });
+      return { status: "completed", decision, host, receipt };
+    },
+  };
+}
+
+async function record(jevRecordExecution, args) {
+  try {
+    return await jevRecordExecution(args);
+  } catch (error) {
+    // Execution ownership stays with the host even if receipt persistence fails.
+    return { persisted: false, error: boundedError(error) };
+  }
+}
+
+function nativeFallback(reason, error) {
+  return {
+    status: "native_fallback",
+    reason,
+    error: error ? boundedError(error) : null,
+  };
+}
+
+function boundedError(error) {
+  return String(error instanceof Error ? error.message : error).slice(0, 2_000);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "jev-layer",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typakon4/jev-layer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/typakon4/jev-layer/issues"
+  },
+  "homepage": "https://github.com/typakon4/jev-layer#readme",
+  "type": "module",
+  "bin": {
+    "jev": "bin/jev.mjs"
+  },
+  "files": [
+    "bin/",
+    "config/",
+    "docs/",
+    "examples/",
+    "integrations/",
+    "scripts/",
+    "src/",
+    "test/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "README.ru.md",
+    "README.zh-CN.md",
+    "RELEASE.md",
+    "SECURITY.md",
+    "package.json",
+    "package-lock.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "jev": "node bin/jev.mjs",
+    "test": "node --test test/*.test.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "benchmark": "node scripts/benchmark.mjs",
+    "openrouter:choice": "node scripts/openrouter-choice.mjs",
+    "mcp": "node src/mcp-server.mjs",
+    "fail-open-smoke": "node scripts/fail-open-smoke.mjs",
+    "codex:mcp-smoke": "node scripts/codex-mcp-smoke.mjs",
+    "replay:evaluate": "node scripts/replay-eval.mjs",
+    "receipt:mcp-smoke": "node scripts/mcp-receipt-smoke.mjs",
+    "browser:e2e": "node scripts/browser-e2e.mjs",
+    "browser:benchmark": "node scripts/browser-benchmark.mjs",
+    "supervision:e2e": "node scripts/supervision-e2e.mjs",
+    "context-filter:e2e": "node scripts/context-filter-e2e.mjs",
+    "capability:e2e": "node scripts/capability-e2e.mjs",
+    "feature-flags:smoke": "node scripts/feature-flags-smoke.mjs",
+    "clean-install-smoke": "node scripts/clean-install-smoke.mjs"
+  }
+}

package/scripts/benchmark.mjs

@@ -0,0 +1,35 @@
+import { routeRequest } from "../src/route.mjs";
+
+const capabilities = [
+  { id: "repo_search", kind: "mcp", name: "Repository search", description: "Search repository files and symbols", permissions: ["read"], risk: "low" },
+  { id: "browser_inspect", kind: "mcp", name: "Browser inspection", description: "Open and inspect webpages", permissions: ["browser"], risk: "medium" },
+  { id: "terminal_read", kind: "cli", name: "Read-only terminal", description: "Run read-only terminal commands", permissions: ["terminal:read"], risk: "low" },
+  { id: "file_write", kind: "tool", name: "File writer", description: "Modify repository files", permissions: ["write"], risk: "high" },
+];
+const request = {
+  harness: "benchmark",
+  intent: "Search repository files for the routing implementation",
+  context: { workspace: "jev-layer" },
+  actor_permissions: ["read"],
+  capabilities,
+};
+const samples = [];
+const started = performance.now();
+for (let index = 0; index < 1_000; index += 1) {
+  const before = performance.now();
+  await routeRequest(request, { provider: "demo" });
+  samples.push(performance.now() - before);
+}
+samples.sort((left, right) => left - right);
+const percentile = (p) => Number(samples[Math.min(samples.length - 1, Math.floor(samples.length * p))].toFixed(3));
+console.log(JSON.stringify({
+  provider: "jev-demo",
+  iterations: samples.length,
+  total_ms: Number((performance.now() - started).toFixed(3)),
+  p50_ms: percentile(0.5),
+  p95_ms: percentile(0.95),
+  p99_ms: percentile(0.99),
+  provider_calls_per_route: 1,
+  host_execution_calls: 0,
+  paid_provider_calls: 0,
+}));

package/scripts/browser-benchmark.mjs

@@ -0,0 +1,92 @@
+import { runBrowserFastPath } from "../src/browser.mjs";
+
+const iterations = Number(process.env.JEV_BROWSER_BENCHMARK_ITERATIONS ?? 25);
+const baseline = [];
+const jev = [];
+
+for (let iteration = 0; iteration < iterations; iteration += 1) {
+  baseline.push(await runBaseline());
+  jev.push(await runJev());
+}
+
+const report = {
+  ok: true,
+  iterations,
+  provider: "injected-jev-demo-choice",
+  baseline: summarize(baseline),
+  jev: summarize(jev),
+  delta: {
+    wall_time_reduction_percent: percent(mean(baseline, "wall_time_ms"), mean(jev, "wall_time_ms")),
+    main_model_turn_reduction: mean(baseline, "main_model_turns") - mean(jev, "main_model_turns"),
+    extra_jev_calls: mean(jev, "jev_calls") - mean(baseline, "jev_calls"),
+    browser_action_delta: mean(jev, "browser_actions") - mean(baseline, "browser_actions"),
+    failure_delta: mean(jev, "failures") - mean(baseline, "failures"),
+  },
+};
+console.log(JSON.stringify(report, null, 2));
+
+async function runBaseline() {
+  const started = performance.now();
+  const actions = ["scroll", "switch_tab"];
+  for (const operation of actions) await Promise.resolve(operation);
+  return {
+    wall_time_ms: elapsed(started),
+    main_model_turns: 2,
+    jev_calls: 0,
+    browser_actions: actions.length,
+    failures: 0,
+    cost_usd: 0,
+  };
+}
+
+async function runJev() {
+  let index = 0;
+  const choices = ["browser:scroll:down", "browser:switch_tab:tab-2"];
+  const result = await runBrowserFastPath({
+    goal: "scroll down and switch to the other tab",
+    enabled: true,
+    provider: {
+      name: "browser-benchmark-provider",
+      async decide({ candidates }) {
+        const requested = choices[index++] ?? "browser:handoff";
+        const choice = candidates.some((candidate) => candidate.id === requested)
+          ? requested
+          : candidates.find((candidate) => candidate.id === "browser:handoff")?.id ?? candidates[0]?.id;
+        return {
+          answers: { tool: { type: "choice", choice, probabilities: Object.fromEntries(candidates.map((candidate) => [candidate.id, candidate.id === choice ? 1 : 0])), confidence: 1 } },
+          usage: { cost: 0.0001 },
+        };
+      },
+    },
+    executor: {
+      state: 0,
+      async observe() {
+        return this.state === 0
+          ? { scroll: { up: false, down: true }, tabs: [{ id: "tab-1", active: true }, { id: "tab-2", title: "Other", active: false }] }
+          : { scroll: { up: false, down: false }, tabs: [{ id: "tab-1", active: true }, { id: "tab-2", title: "Other", active: false }] };
+      },
+      async execute() {
+        this.state += 1;
+        return { observation: await this.observe(), handoff: this.state >= 2 };
+      },
+    },
+    mainModelTurns: 1,
+  });
+  return result.metrics;
+}
+
+function summarize(rows) {
+  return Object.fromEntries(["wall_time_ms", "main_model_turns", "jev_calls", "browser_actions", "failures", "cost_usd"].map((key) => [key, mean(rows, key)]));
+}
+
+function mean(rows, key) {
+  return Number((rows.reduce((sum, row) => sum + row[key], 0) / rows.length).toFixed(3));
+}
+
+function percent(before, after) {
+  return before ? Number((((before - after) / before) * 100).toFixed(2)) : 0;
+}
+
+function elapsed(started) {
+  return Number((performance.now() - started).toFixed(3));
+}

package/scripts/browser-e2e.mjs

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const casesPath = join(await mkdtemp(join(tmpdir(), "jev-browser-e2e-")), "cases.jsonl");
+const child = spawn(process.env.JEV_NODE ?? "node", [resolve(root, "src/mcp-server.mjs")], {
+  cwd: root,
+  env: { ...process.env, JEV_BROWSER_FAST_PATH: "1", JEV_REPLAY_CASES: casesPath },
+  stdio: ["pipe", "pipe", "pipe"],
+});
+const lines = createInterface({ input: child.stdout });
+const pending = new Map();
+lines.on("line", (line) => {
+  if (!line.trim()) return;
+  const message = JSON.parse(line);
+  const waiter = pending.get(message.id);
+  if (waiter) {
+    pending.delete(message.id);
+    waiter(message);
+  }
+});
+
+try {
+  const initialized = await request(1, "initialize", {});
+  assert.equal(initialized.result.serverInfo.name, "jev-layer");
+  await notification("notifications/initialized", {});
+  const listed = await request(2, "tools/list", {});
+  assert.ok(listed.result.tools.some((tool) => tool.name === "jev_browser_step"));
+
+  const routed = await request(3, "tools/call", {
+    name: "jev_browser_step",
+    arguments: {
+      provider: process.env.JEV_BROWSER_PROVIDER ?? "demo",
+      enabled: true,
+      harness: "browser-e2e",
+      goal: "scroll the page downward",
+      observation: {
+        url: "https://example.test",
+        title: "Fixture",
+        visible_text: "Additional content is below the fold",
+        scroll: { up: false, down: true },
+        targets: [],
+        tabs: [],
+      },
+      policy: { min_confidence: 0 },
+    },
+  });
+  const decision = routed.result.structuredContent;
+  assert.equal(decision.status, "selected");
+  assert.equal(decision.browser_action.operation, "scroll");
+  assert.equal(decision.browser_action.target_id, null);
+
+  const started = performance.now();
+  const hostResult = { operation: decision.browser_action.operation, direction: "down", fixture: true };
+  const recorded = await request(4, "tools/call", {
+    name: "jev_record_execution",
+    arguments: {
+      correlation_id: decision.correlation_id,
+      harness: "browser-e2e",
+      capability_id: decision.selected,
+      status: "completed",
+      result: hostResult,
+      browser: { operation: "scroll", direction: "down", executed: true },
+      exit_status: 0,
+      duration_ms: Number((performance.now() - started).toFixed(3)),
+    },
+  });
+  const receipt = recorded.result.structuredContent;
+  assert.equal(receipt.correlation_id, decision.correlation_id);
+  assert.equal(receipt.host.browser.operation, "scroll");
+  assert.equal(receipt.host.exit_status, 0);
+
+  const records = (await readFile(casesPath, "utf8")).trim().split(/\r?\n/).map(JSON.parse);
+  assert.deepEqual(records.map((record) => record.record_type), ["routing_case", "execution_receipt"]);
+  assert.equal(records[0].request.context.browser.goal, "scroll the page downward");
+  console.log(JSON.stringify({
+    ok: true,
+    cases_path: casesPath,
+    decision: {
+      correlation_id: decision.correlation_id,
+      selected: decision.selected,
+      operation: decision.browser_action.operation,
+      confidence: decision.confidence,
+      latency_ms: decision.receipt.latency_ms,
+      cost_usd: decision.receipt.cost_usd ?? null,
+    },
+    host_execution: { operation: hostResult.operation, exit_status: receipt.host.exit_status },
+    receipts: records.length,
+  }, null, 2));
+} finally {
+  child.kill();
+  await new Promise((resolveExit) => child.once("close", resolveExit));
+}
+
+function request(id, method, params) {
+  return new Promise((resolveResponse, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`MCP request timed out: ${method}`));
+    }, 15_000);
+    pending.set(id, (message) => {
+      clearTimeout(timer);
+      resolveResponse(message);
+    });
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+  });
+}
+
+function notification(method, params) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+  return new Promise((resolveNotification) => setImmediate(resolveNotification));
+}

package/scripts/capability-e2e.mjs

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { routeRequest } from "../src/route.mjs";
+
+let providerCalls = 0;
+const decision = await routeRequest({
+  harness: "capability-e2e",
+  intent: "use the verified model for a bounded decision",
+  context: { task: "model" },
+  policy: { deterministic: true, prefer_kind: "model", prefer_verified: true },
+}, {
+  discovery: {
+    skills: [{ id: "skill:inspect", name: "Inspect skill", description: "Inspect context" }],
+    models: [{ id: "model:verified", name: "Verified model", description: "Make bounded decisions", verified: true, risk: "low", source: "e2e-manifest" }],
+    tools: [{ id: "tool:offline", name: "Offline tool", description: "Unavailable", available: false }],
+  },
+  provider: { name: "capability-e2e-provider", async decide() { providerCalls += 1; throw new Error("deterministic selection should not call Jev"); } },
+});
+assert.equal(providerCalls, 0);
+assert.equal(decision.status, "selected");
+assert.equal(decision.selected, "model:verified");
+assert.equal(decision.candidates.find((candidate) => candidate.id === "model:verified").source, "e2e-manifest");
+assert.equal(decision.candidates.find((candidate) => candidate.id === "model:verified").verified, true);
+console.log(JSON.stringify({
+  ok: true,
+  status: decision.status,
+  selected: decision.selected,
+  provider: decision.receipt.provider,
+  deterministic: true,
+  jev_calls: providerCalls,
+  candidate_metadata: decision.candidates.find((candidate) => candidate.id === decision.selected),
+}, null, 2));