jev-layer 0.1.0

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security policy
+
+[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
+
+## Scope and trust model
+
+jev-layer is a routing and evidence layer, not a security boundary. It can return a bounded recommendation and persist a receipt; it does not grant permissions, execute host capabilities, approve actions, isolate a process, or validate that a provider is truthful.
+
+The host remains the source of truth for:
+
+- capability availability and permissions;
+- approval and confirmation decisions;
+- native execution, retries, recovery, and cancellation;
+- final results and side effects.
+
+Adapters must fail open to the host's normal path when Jev is disabled, unavailable, inconclusive, or returns an error. A Jev response must never be treated as authorization by itself.
+
+## API keys and credentials
+
+- Keep provider keys in process environment variables or user-owned secret storage.
+- Never commit `.env` files, API keys, bearer tokens, private keys, provider headers, or copied secret-bearing requests.
+- Do not put credentials in `context`, capabilities, prompts, replay fixtures, issue reports, or receipts.
+- Use the secret-free `demo` provider for local tests and ordinary pull requests.
+- If a credential is exposed, revoke it immediately, remove it from active systems, and report the incident privately.
+
+Supported provider environment names include `OPENROUTER_API_KEY` and `TYPESAFE_API_KEY`. The names may appear in configuration examples; their values must not.
+
+## Logs, receipts, and replay data
+
+Routing cases and execution receipts can contain capability names, prompts or bounded context, host results, errors, URLs, timing, and provider metadata. Treat `.jev/replay/cases.jsonl` and CI logs as potentially sensitive.
+
+Before sharing logs or fixtures:
+
+1. remove API keys, tokens, cookies, authorization headers, private paths, and personal data;
+2. remove sensitive prompt/context and host output;
+3. retain only the smallest correlation and status fields needed to reproduce the issue.
+
+Receipt fields are bounded, but bounded data can still be confidential. Do not use receipts as an authorization ledger.
+
+## Prompt injection and provider limitations
+
+Provider output is untrusted data. Prompt injection, malicious capability descriptions, misleading browser text, compromised providers, and incorrect confidence values can cause a bad recommendation. jev-layer does not claim to detect or defeat prompt injection.
+
+The host must validate selected ids against its current registry, enforce permissions and approval, and reject stale, unavailable, or malformed selections. The browser fast-path is experimental, opt-in, and must not be used as a security control.
+
+## Reporting a vulnerability
+
+Do not open a public issue for an unpatched vulnerability or include secrets in a report. Use a private GitHub Security Advisory for the repository when that channel is available. If it is not available, contact the project maintainers through the private contact channel listed by the repository owner and provide:
+
+- affected version or commit;
+- minimal reproduction;
+- impact and required permissions;
+- whether credentials or personal data were exposed;
+- a safe contact for coordinated follow-up.
+
+We will acknowledge a report when practicable, validate the impact, coordinate a fix or mitigation, and publish a release note after a fix is available. Please allow maintainers reasonable time for coordinated disclosure.

package/bin/jev.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { configuredProvider, loadConfig, pathExists } from "../src/config.mjs";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const [command = "help", ...argv] = process.argv.slice(2);
+
+try {
+  if (command === "mcp") {
+    await import("../src/mcp-server.mjs");
+  } else if (command === "cli") {
+    await import("../src/cli.mjs");
+  } else if (command === "install") {
+    await install(argv);
+  } else if (command === "init") {
+    await init(argv);
+  } else if (command === "add") {
+    await add(argv);
+  } else if (command === "doctor") {
+    await doctor(argv);
+  } else {
+    printHelp();
+    if (command !== "help" && command !== "--help" && command !== "-h") process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`jev: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}
+
+async function install(argv) {
+  const options = parseOptions(argv);
+  const project = projectPath(options);
+  const result = await writeInitialConfig(project, options.force);
+  console.log(`jev-layer ${result.created ? "initialized" : "already initialized"} at ${project}`);
+  console.log("Runtime dependencies: none. Node.js >= 20 is required.");
+  console.log("Next: jev add <omp|hermes|codex|generic> && jev doctor");
+}
+
+async function init(argv) {
+  const options = parseOptions(argv);
+  const project = projectPath(options);
+  const result = await writeInitialConfig(project, options.force);
+  console.log(JSON.stringify({ ok: true, project, created: result.created, config: result.configPath, env_example: result.envPath }, null, 2));
+}
+
+async function add(argv) {
+  const harness = argv[0];
+  if (!harness || ["--help", "-h"].includes(harness)) {
+    console.error("Usage: jev add <omp|hermes|codex|generic> [--project DIR] [--command CMD]");
+    process.exitCode = 1;
+    return;
+  }
+  const options = parseOptions(argv.slice(1));
+  const project = projectPath(options);
+  const { config } = await loadConfig({ cwd: project });
+  const provider = configuredProvider(config, options.provider);
+  const commandName = options.command ?? process.env.JEV_COMMAND ?? "jev";
+  const server = {
+    type: "stdio",
+    command: commandName,
+    args: ["mcp"],
+    cwd: ".",
+    env: { JEV_LAYER_PROVIDER: provider },
+  };
+
+  let destination;
+  let mode = "snippet";
+  if (harness === "omp") {
+    destination = await addOmp(project, server);
+    mode = destination.endsWith(".omp/mcp.json") ? "config" : "snippet";
+  } else if (harness === "codex") {
+    destination = await addCodex(project, server);
+    mode = destination.endsWith(".codex/config.toml") ? "config" : "snippet";
+  } else if (harness === "hermes") {
+    destination = await writeSnippet(project, "hermes", hermesSnippet(server));
+  } else if (harness === "generic" || harness === "mcp") {
+    destination = await writeSnippet(project, "generic", JSON.stringify({ mcpServers: { jev: server } }, null, 2) + "\n", ".json");
+  } else {
+    throw new Error(`unsupported harness: ${harness}`);
+  }
+
+  console.log(JSON.stringify({ ok: true, harness, provider, destination, mode, command: commandName }, null, 2));
+  if (mode === "snippet") console.log("Merge this adapter snippet into the harness configuration; existing files were not overwritten.");
+}
+
+async function doctor(argv) {
+  const options = parseOptions(argv);
+  const project = projectPath(options);
+  const { config, path: configPath, error: configError } = await loadConfig({ cwd: project });
+  const provider = configuredProvider(config, options.provider);
+  const checks = [];
+  const fail = (name, detail) => checks.push({ name, status: "error", detail });
+  const pass = (name, detail) => checks.push({ name, status: "ok", detail });
+  const warn = (name, detail) => checks.push({ name, status: "warning", detail });
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+
+  if (nodeMajor >= 20) pass("node", process.versions.node);
+  else fail("node", `Node.js >= 20 required; found ${process.versions.node}`);
+  for (const relative of ["src/route.mjs", "src/cli.mjs", "src/mcp-server.mjs", "bin/jev.mjs"]) {
+    if (await pathExists(join(PACKAGE_ROOT, relative))) pass(`package:${relative}`, "present");
+    else fail(`package:${relative}`, "missing from installation");
+  }
+  if (configError) fail("config", configError);
+  else if (await pathExists(configPath)) pass("config", configPath);
+  else warn("config", `not initialized at ${configPath}; run jev init`);
+
+  if (!["demo", "openrouter", "typesafe"].includes(provider)) fail("provider", `unsupported provider ${provider}`);
+  else pass("provider", provider);
+  if (provider === "openrouter" || provider === "typesafe") {
+    const keyEnv = config.providers?.[provider]?.api_key_env ?? (provider === "openrouter" ? "OPENROUTER_API_KEY" : "TYPESAFE_API_KEY");
+    if (process.env[keyEnv]) pass(`secret:${keyEnv}`, "configured through environment");
+    else fail(`secret:${keyEnv}`, `missing; export ${keyEnv} before using ${provider}`);
+  } else {
+    pass("provider-secret", "not required for demo provider");
+  }
+  if (process.env.JEV_LAYER_ENABLED === "0") warn("fail-open", "JEV_LAYER_ENABLED=0; routing will return fallback decisions");
+
+  const errors = checks.filter((check) => check.status === "error");
+  console.log(JSON.stringify({ ok: errors.length === 0, project, package_root: PACKAGE_ROOT, checks }, null, 2));
+  if (errors.length) process.exitCode = 1;
+}
+
+async function writeInitialConfig(project, force = false) {
+  const state = join(project, ".jev");
+  await mkdir(state, { recursive: true });
+  const configPath = join(state, "config.json");
+  const envPath = join(state, "providers.env.example");
+  const config = await readPackageFile("config/jev.example.json");
+  const envExample = await readPackageFile("config/providers.env.example");
+  const configCreated = await writeIfAllowed(configPath, config, force);
+  const envCreated = await writeIfAllowed(envPath, envExample, force);
+  return { created: configCreated || envCreated, configPath, envPath };
+}
+
+async function addOmp(project, server) {
+  const target = join(project, ".omp", "mcp.json");
+  if (!(await pathExists(target))) {
+    await writeJson(target, { "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json", mcpServers: { jev: server } });
+    return target;
+  }
+  try {
+    const parsed = JSON.parse(await readFile(target, "utf8"));
+    parsed.mcpServers = { ...(parsed.mcpServers ?? {}), jev: server };
+    await writeFile(target, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    return target;
+  } catch {
+    return writeSnippet(project, "omp", JSON.stringify({ mcpServers: { jev: server } }, null, 2) + "\n", ".json");
+  }
+}
+
+async function addCodex(project, server) {
+  const target = join(project, ".codex", "config.toml");
+  if (!(await pathExists(target))) {
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, codexSnippet(server), "utf8");
+    return target;
+  }
+  return writeSnippet(project, "codex", codexSnippet(server), ".toml");
+}
+
+async function writeSnippet(project, name, content, extension = ".yaml") {
+  const destination = join(project, ".jev", "adapters", `${name}${extension}`);
+  await mkdir(dirname(destination), { recursive: true });
+  await writeFile(destination, content, "utf8");
+  return destination;
+}
+
+function codexSnippet(server) {
+  return `[mcp_servers.jev]\ncommand = ${JSON.stringify(server.command)}\nargs = ["mcp"]\ncwd = "."\n\n[mcp_servers.jev.env]\nJEV_LAYER_PROVIDER = ${JSON.stringify(server.env.JEV_LAYER_PROVIDER)}\n`;
+}
+
+function hermesSnippet(server) {
+  return `mcp_servers:\n  jev:\n    command: ${server.command}\n    args:\n      - mcp\n    env:\n      JEV_LAYER_PROVIDER: ${server.env.JEV_LAYER_PROVIDER}\n      # Export OPENROUTER_API_KEY or TYPESAFE_API_KEY in the Hermes process environment.\n`;
+}
+
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+async function writeIfAllowed(path, content, force) {
+  if (!force && await pathExists(path)) return false;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, "utf8");
+  return true;
+}
+
+async function readPackageFile(relative) {
+  return readFile(join(PACKAGE_ROOT, relative), "utf8");
+}
+
+function projectPath(options) {
+  return resolve(options.project ?? process.cwd());
+}
+
+function parseOptions(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--project") options.project = argv[++index];
+    else if (value === "--command") options.command = argv[++index];
+    else if (value === "--provider") options.provider = argv[++index];
+    else if (value === "--force") options.force = true;
+    else if (value === "--help" || value === "-h") options.help = true;
+    else throw new Error(`unknown option ${value}`);
+  }
+  return options;
+}
+
+function printHelp() {
+  console.log(`jev-layer portable setup\n\nCommands:\n  jev install [--project DIR]       initialize local state\n  jev init [--project DIR]          write .jev/config.json and env example\n  jev add <harness> [options]       add omp, hermes, codex, or generic MCP adapter\n  jev doctor [--project DIR]        check runtime, config, provider and secrets\n  jev mcp                           run the stdio MCP server\n  jev cli                           run the JSONL CLI adapter\n\nOptions:\n  --project DIR                     target workspace; defaults to cwd\n  --command CMD                     MCP command; defaults to jev\n  --provider NAME                   override provider for generated config\n  --force                           replace generated init files\n`);
+}

package/config/codex.mcp.toml

@@ -0,0 +1,8 @@
+[mcp_servers.jev]
+command = "jev"
+args = ["mcp"]
+cwd = "."
+
+[mcp_servers.jev.env]
+JEV_LAYER_PROVIDER = "openrouter"
+# Export OPENROUTER_API_KEY in the Codex process environment.

package/config/generic-mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "jev": {
+      "type": "stdio",
+      "command": "jev",
+      "args": ["mcp"],
+      "cwd": ".",
+      "env": {
+        "JEV_LAYER_PROVIDER": "demo"
+      }
+    }
+  }
+}

package/config/hermes.mcp.yaml

@@ -0,0 +1,9 @@
+# Merge this block into the Hermes config under mcp_servers.
+mcp_servers:
+  jev:
+    command: jev
+    args:
+      - mcp
+    env:
+      JEV_LAYER_PROVIDER: openrouter
+      # Export OPENROUTER_API_KEY in the Hermes process environment.

package/config/jev.example.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": 1,
+  "provider": "demo",
+  "replay_cases": ".jev/replay/cases.jsonl",
+  "features": {
+    "browser_fast_path": false,
+    "supervision": false,
+    "context_filter": null
+  },
+  "providers": {
+    "openrouter": {
+      "api_key_env": "OPENROUTER_API_KEY",
+      "endpoint_env": "OPENROUTER_DECISIONS_ENDPOINT",
+      "model_env": "OPENROUTER_DECISIONS_MODEL"
+    },
+    "typesafe": {
+      "api_key_env": "TYPESAFE_API_KEY",
+      "endpoint_env": "TYPESAFE_ENDPOINT",
+      "model_env": "TYPESAFE_MODEL"
+    }
+  }
+}

package/config/omp.mcp.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
+  "mcpServers": {
+    "jev": {
+      "type": "stdio",
+      "command": "jev",
+      "args": ["mcp"],
+      "cwd": ".",
+      "env": {
+        "JEV_LAYER_PROVIDER": "openrouter"
+      }
+    }
+  }
+}

package/config/providers.env.example

@@ -0,0 +1,13 @@
+# Copy the variables needed by the selected provider into the harness environment.
+# Do not commit a file containing real values.
+
+JEV_LAYER_PROVIDER=demo
+# JEV_LAYER_PROVIDER=openrouter
+# OPENROUTER_API_KEY=replace-in-your-shell-only
+# OPENROUTER_DECISIONS_ENDPOINT=https://openrouter.ai/api/alpha/decisions
+# OPENROUTER_DECISIONS_MODEL=typesafe/jev-1.13
+
+# JEV_LAYER_PROVIDER=typesafe
+# TYPESAFE_API_KEY=replace-in-your-shell-only
+# TYPESAFE_ENDPOINT=https://api.typesafe.ai/v1/systemone
+# TYPESAFE_MODEL=jev-latest

package/docs/COMPATIBILITY.md

@@ -0,0 +1,15 @@
+# Harness compatibility baseline
+
+[English](../README.md) | [Русский](../README.ru.md) | [简体中文](../README.zh-CN.md)
+
+This is the first-release compatibility baseline observed on 2026-09-19. It records the installed harness versions used for the release-preparation checks; it is not a claim that every provider/model combination was exercised.
+
+| Harness | Version observed | Release-preparation coverage |
+| --- | --- | --- |
+| OMP | `18.2.6` | `omp --version`; OMP extension contract and host-owned execution path reviewed; Jev core smoke uses the same MCP/CLI contract. |
+| Hermes | `0.21.3` (`upstream b675e6de`) | `hermes --version`; Python adapter syntax/contract reviewed; Jev core smoke uses the same CLI/MCP contract. |
+| Codex CLI | `0.155.1` | `codex --version`; Codex MCP transport fixture and host-execution ownership path reviewed. The fixture does not invoke a Codex model. |
+
+The adapters are thin and target the stable v1 contract documented in [CONTRIBUTING.md](../CONTRIBUTING.md) and [SCHEMA-VERSIONING.md](SCHEMA-VERSIONING.md). Full interactive harness/model/provider coverage is environment-specific and is not required for ordinary PR CI.
+
+When a public release supports a different harness version, update this table, rerun the adapter/transport checks, and document any compatibility change in `CHANGELOG.md` before tagging.

package/docs/SCHEMA-VERSIONING.md

@@ -0,0 +1,94 @@
+# Schema and compatibility policy
+
+[English](../README.md) | [Русский](../README.ru.md) | [简体中文](../README.zh-CN.md)
+
+The current public contracts are **schema version 1**. The implementation already emits `schema_version: 1` for route requests, decision envelopes, routing cases, execution receipts, and supervision cases. A new public release must not silently change the meaning of those v1 fields.
+
+## Version rules
+
+- **Patch release:** bug fixes and documentation changes; v1 meanings remain unchanged.
+- **Minor release:** additive optional fields, new providers, new adapters, or new capability kinds that v1 consumers can ignore.
+- **Major release:** removed/renamed required fields, changed field types or meanings, changed correlation semantics, or a host-approval contract change.
+- Unknown fields must be ignored by readers. Writers must not emit a required field unless it is part of the declared schema version.
+- New runtime behavior must remain opt-in and fail open unless the existing contract explicitly requires it.
+
+A breaking schema requires a new schema version, migration notes, fixtures for both versions, and an adapter compatibility decision. Do not change v1 to avoid writing a migration.
+
+## MCP tools
+
+The MCP server currently exposes these stable tool names:
+
+- `jev_route`
+- `jev_browser_step` (experimental, opt-in)
+- `jev_supervise` (experimental, opt-in)
+- `jev_record_execution`
+
+Their input and structured output are v1. Additive optional properties are compatible. Renaming a tool, changing a required property, changing the meaning of a status, or changing who owns execution requires a new tool/schema version and adapter migration. Keep `tools/list`, `initialize`, and stdio JSON-RPC behavior backward compatible for v1 clients.
+
+## Routing decision schema
+
+A v1 decision includes at least:
+
+- `schema_version`
+- `correlation_id`
+- `status`
+- `selected`
+- `confidence`
+- `probabilities`
+- `reason`
+- `candidates`
+- `fallback`
+- `execution` with host execution initially `not_started`
+- `receipt`
+
+The selected id is advisory until the host resolves it against its own capability registry and permissions. `correlation_id` is the join key for routing and execution records.
+
+## Execution receipts
+
+A v1 `execution_receipt` is append-only JSONL data with:
+
+- `record_type: "execution_receipt"`
+- `schema_version: 1`
+- `receipt_id`
+- `correlation_id`
+- `harness`
+- the selected/candidate decision summary;
+- Jev provider, latency, cost, and status;
+- bounded host status/result/error plus optional exit and timing metadata.
+
+The host must record `completed`, `failed`, or `not_started`. Receipts must not contain unbounded prompts, secrets, or raw credentials. Receipts are evidence of what the host reported; they do not grant permission or prove that Jev executed anything.
+
+## Replay cases
+
+A v1 replay file is JSONL. Supported records include:
+
+- `record_type: "routing_case"`
+- `record_type: "execution_receipt"`
+- `record_type: "supervision_case"`
+
+Routing cases retain a sanitized request and a decision summary. Replay reads cases without calling host tools. New optional record fields are compatible; changing record type, correlation semantics, or the meaning of a recorded status requires a new replay schema and migration.
+
+## Adapter contract
+
+The adapter contract is currently **v1** and is intentionally separate from provider/model versions. A v1 adapter must:
+
+1. submit a bounded candidate set;
+2. call `jev_route` or the equivalent CLI contract;
+3. preserve `correlation_id`;
+4. keep native execution and permissions in the host;
+5. preserve approval decisions;
+6. call `jev_record_execution` after host execution or denial;
+7. fail open to the native path when Jev is unavailable or inconclusive.
+
+An adapter that cannot preserve these invariants is not v1-compatible. Record supported adapter versions in integration documentation and release checklists.
+
+## Compatibility review
+
+For every release, review:
+
+- v1 request/decision fixtures;
+- MCP `tools/list` and `tools/call` smoke cases;
+- receipt/replay round trips;
+- all supported adapter examples;
+- fail-open and approval-denial paths;
+- package contents and translated documentation.

package/examples/capabilities.json

@@ -0,0 +1,39 @@
+[
+  {
+    "id": "repo_search",
+    "kind": "mcp",
+    "name": "Repository search",
+    "description": "Search repository files and symbols without changing files",
+    "permissions": ["read"],
+    "risk": "low",
+    "execution": { "target": "host-native-repository-search" }
+  },
+  {
+    "id": "browser_inspect",
+    "kind": "mcp",
+    "name": "Browser inspection",
+    "description": "Open a webpage and inspect visible browser state",
+    "permissions": ["browser"],
+    "risk": "medium",
+    "execution": { "target": "host-native-browser" }
+  },
+  {
+    "id": "terminal_read",
+    "kind": "cli",
+    "name": "Read-only terminal",
+    "description": "Run a read-only shell command and return its output",
+    "permissions": ["terminal:read"],
+    "risk": "low",
+    "execution": { "target": "host-native-terminal" }
+  },
+  {
+    "id": "file_write",
+    "kind": "tool",
+    "name": "File writer",
+    "description": "Modify files in the repository",
+    "permissions": ["write"],
+    "risk": "high",
+    "execution": { "target": "host-native-write" },
+    "policy": { "requires_confirmation": true }
+  }
+]

package/examples/route-request.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": 1,
+  "harness": "example",
+  "intent": "Find where the routing decision is implemented in this repository",
+  "context": {
+    "workspace": "jev-layer",
+    "api_key": "must-not-reach-provider"
+  },
+  "actor_permissions": ["read"],
+  "capabilities": [
+    {
+      "id": "repo_search",
+      "kind": "mcp",
+      "name": "Repository search",
+      "description": "Search repository files and symbols without changing files",
+      "permissions": ["read"],
+      "risk": "low"
+    },
+    {
+      "id": "file_write",
+      "kind": "tool",
+      "name": "File writer",
+      "description": "Modify files in the repository",
+      "permissions": ["write"],
+      "risk": "high"
+    }
+  ]
+}

package/integrations/codex/.codex-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "jev-layer",
+  "version": "0.1.0",
+  "description": "Host-owned Jev capability routing through the standalone jev-layer core",
+  "author": { "name": "Local Jev Layer" },
+  "license": "MIT",
+  "keywords": ["jev", "routing", "decision", "mcp"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Jev Layer",
+    "shortDescription": "Bounded capability decisions without host execution",
+    "longDescription": "Routes a closed candidate set and leaves approvals and execution to Codex.",
+    "developerName": "Local Jev Layer",
+    "category": "Developer Tools",
+    "capabilities": ["Decision routing"],
+    "defaultPrompt": ["Use Jev only for bounded capability routing; keep execution and approvals in Codex."]
+  }
+}

package/integrations/codex/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "jev": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./run-mcp.mjs"],
+      "cwd": ".",
+      "env_vars": ["JEV_LAYER_ROOT", "JEV_LAYER_PROVIDER", "OPENROUTER_API_KEY"]
+    }
+  }
+}

package/integrations/codex/AGENTS.md

@@ -0,0 +1 @@
+When this adapter is enabled, use `jev_route` only for bounded closed-set capability routing. The tool returns an identifier; Codex owns all execution and approvals. On fallback, low confidence, malformed response, unavailable capability, or timeout, continue with normal Codex planning. Never send secrets or full transcripts to Jev.

package/integrations/codex/run-mcp.mjs

@@ -0,0 +1,9 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginRoot = dirname(fileURLToPath(import.meta.url));
+const projectRoot = process.env.JEV_LAYER_ROOT
+  ? resolve(process.env.JEV_LAYER_ROOT)
+  : resolve(pluginRoot, "../..");
+
+await import(resolve(projectRoot, "src/mcp-server.mjs"));

package/integrations/codex/skills/jev-route/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: jev-route
+description: Use Jev for one bounded capability choice when a closed candidate set is already available. Keep permissions, approvals, execution, and recovery in Codex.
+---
+
+# Jev route
+
+Use the `jev_route` MCP tool only when the request can be expressed as one bounded choice among supplied capabilities.
+
+1. Build a small candidate list from capabilities Codex can already execute.
+2. Include only non-secret intent, candidate metadata, and the minimum context needed.
+3. Call `jev_route` once.
+4. Treat `fallback`, `no_decision`, and `needs_confirmation` as normal outcomes.
+5. Execute `selected` only through the native Codex capability and its existing approval gate.
+6. Never interpret a Jev response as permission to bypass Codex policy.
+
+Do not use Jev for open-ended planning, coding, research, recovery, or arbitrary tool execution.

package/integrations/hermes/__init__.py

@@ -0,0 +1,51 @@
+"""Hermes adapter for the standalone Jev layer.
+
+This plugin exposes only a decision tool. The selected capability remains
+owned and executed by Hermes through its normal approval/tool path.
+"""
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from .schemas import ROUTE
+
+ROOT = Path(os.environ.get("JEV_LAYER_ROOT", Path(__file__).resolve().parents[2])).expanduser().resolve()
+CLI = ROOT / "src" / "cli.mjs"
+
+def _fallback(reason: str) -> str:
+    return json.dumps({
+        "schema_version": 1,
+        "status": "fallback",
+        "selected": None,
+        "reason": reason,
+        "fallback": {"type": "adapter_error", "reason": reason},
+        "execution": {"enabled": False, "status": "not_started"},
+    })
+
+
+def jev_route(args: dict, **kwargs) -> str:
+    """Return a bounded decision as JSON; never execute the selected target."""
+    try:
+        completed = subprocess.run(
+            [os.environ.get("JEV_NODE", "node"), str(CLI), "--provider", os.environ.get("JEV_LAYER_PROVIDER", "demo")],
+            input=json.dumps(args) + "\n",
+            capture_output=True,
+            text=True,
+            timeout=float(os.environ.get("JEV_LAYER_TIMEOUT_S", "3")),
+            check=False,
+        )
+        if completed.returncode != 0:
+            return _fallback(completed.stderr.strip() or f"core exited with status {completed.returncode}")
+        line = next((line for line in completed.stdout.splitlines() if line.strip()), "")
+        if not line:
+            return _fallback("core returned no decision")
+        json.loads(line)
+        return line
+    except Exception as error:
+        return _fallback(str(error))
+
+
+def register(ctx):
+    ctx.register_tool(name="jev_route", toolset="jev_layer", schema=ROUTE, handler=jev_route)

package/integrations/hermes/plugin.yaml

@@ -0,0 +1,5 @@
+name: jev-layer
+version: 0.1.0
+description: Host-owned Jev capability routing through the standalone jev-layer core
+provides_tools:
+  - jev_route