jev-layer 0.1.0 → 0.2.0

package/integrations/hermes/__init__.py

@@ -1,51 +1,150 @@
-"""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)
+"""Full Hermes adapter for the standalone Jev decision layer.
+
+Jev receives only host-supplied bounded choices. Hermes retains tool lookup,
+permissions, approvals, native execution, retries, recovery, and final output.
+The adapter is fail-open: transport or core errors become a Jev fallback and
+never block Hermes's normal path.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import threading
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any
+
+from .schemas import BROWSER_STEP, MODEL_ROUTE, RECORD_EXECUTION, ROUTE, SHADOW_COMPACTION, SUPERVISE
+
+ROOT = Path(os.environ.get("JEV_LAYER_ROOT", Path(__file__).resolve().parents[2])).expanduser().resolve()
+CORE = ROOT / "src" / "hermes-adapter.mjs"
+_MAX_PENDING_DECISIONS = 64
+_pending_decisions: OrderedDict[str, dict[str, Any]] = OrderedDict()
+_pending_lock = threading.Lock()
+
+
+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 _runtime_env() -> dict[str, str]:
+    env = os.environ.copy()
+    # Resolve only through Hermes's profile-scoped store, then pass it only to
+    # this short-lived local Node adapter. It is never returned or logged.
+    try:
+        from agent.secret_scope import get_secret
+        openrouter_key = get_secret("OPENROUTER_API_KEY")
+        if openrouter_key:
+            env["OPENROUTER_API_KEY"] = openrouter_key
+    except Exception:
+        # The core remains fail-open when the optional provider credential is unavailable.
+        pass
+    # Keep replay evidence in the active Hermes profile, never in the source checkout.
+    env.setdefault("JEV_REPLAY_CASES", str(Path(env.get("HERMES_HOME", "~/.hermes")).expanduser() / "jev-layer" / "replay" / "cases.jsonl"))
+    return env
+
+
+def _call_core(operation: str, args: dict, *, decision: dict | None = None) -> dict:
+    envelope: dict[str, Any] = {"operation": operation, "args": args}
+    if decision is not None:
+        envelope["decision"] = decision
+    try:
+        completed = subprocess.run(
+            [os.environ.get("JEV_NODE", "node"), str(CORE)],
+            input=json.dumps(envelope) + "\n", capture_output=True, text=True,
+            timeout=float(os.environ.get("JEV_LAYER_TIMEOUT_S", "5")), cwd=ROOT,
+            env=_runtime_env(), check=False,
+        )
+        if completed.returncode != 0:
+            return json.loads(_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 json.loads(_fallback("core returned no response"))
+        result = json.loads(line)
+        return result if isinstance(result, dict) else json.loads(_fallback("core returned non-object response"))
+    except Exception as error:
+        return json.loads(_fallback(str(error)))
+
+
+def _remember(decision: dict) -> None:
+    correlation_id = decision.get("correlation_id")
+    if not isinstance(correlation_id, str) or not correlation_id:
+        return
+    with _pending_lock:
+        _pending_decisions[correlation_id] = decision
+        _pending_decisions.move_to_end(correlation_id)
+        while len(_pending_decisions) > _MAX_PENDING_DECISIONS:
+            _pending_decisions.popitem(last=False)
+
+
+def _take(correlation_id: str) -> dict | None:
+    with _pending_lock:
+        return _pending_decisions.pop(correlation_id, None)
+
+
+def _route(args: dict, operation: str = "route") -> str:
+    request = dict(args)
+    request.setdefault("schema_version", 1)
+    request.setdefault("harness", "hermes")
+    result = _call_core(operation, request)
+    if result.get("status") in {"selected", "fallback", "no_decision", "needs_confirmation"} and result.get("correlation_id"):
+        _remember(result)
+    result.pop("_jev_request", None)
+    return json.dumps(result)
+
+
+def jev_route(args: dict, **kwargs) -> str:
+    """Choose from a closed Hermes-owned candidate set; never execute it."""
+    return _route(args)
+
+
+def jev_browser_step(args: dict, **kwargs) -> str:
+    """Choose one bounded browser action; Hermes owns observation, approval and execution."""
+    return _route(args, operation="browser_step")
+
+
+def jev_model_route(args: dict, **kwargs) -> str:
+    """Recommend a declared model profile; this never changes Hermes's model route."""
+    return _route(args, operation="model_route")
+
+
+def jev_shadow_compaction(args: dict, **kwargs) -> str:
+    """Report Jev's conservative keep/drop candidates without mutating host context."""
+    return json.dumps(_call_core("shadow_compaction", dict(args)))
+
+
+def jev_supervise(args: dict, **kwargs) -> str:
+    """Return a bounded work-state judgment; Hermes maps it to its own next action."""
+    request = dict(args)
+    request.setdefault("harness", "hermes")
+    return json.dumps(_call_core("supervise", request))
+
+
+def jev_record_execution(args: dict, **kwargs) -> str:
+    """Append an execution receipt for a decision made in this Hermes process."""
+    correlation_id = args.get("correlation_id")
+    if not isinstance(correlation_id, str) or not correlation_id:
+        return _fallback("correlation_id is required")
+    decision = _take(correlation_id)
+    if decision is None:
+        return _fallback("unknown or expired Jev correlation_id; host execution remains authoritative")
+    receipt = _call_core("record_execution", dict(args), decision=decision)
+    return json.dumps(receipt)
+
+
+def register(ctx):
+    ctx.register_tool(name="jev_route", toolset="jev_layer", schema=ROUTE, handler=jev_route)
+    ctx.register_tool(name="jev_model_route", toolset="jev_layer", schema=MODEL_ROUTE, handler=jev_model_route)
+    ctx.register_tool(name="jev_shadow_compaction", toolset="jev_layer", schema=SHADOW_COMPACTION, handler=jev_shadow_compaction)
+    ctx.register_tool(name="jev_record_execution", toolset="jev_layer", schema=RECORD_EXECUTION, handler=jev_record_execution)
+    ctx.register_tool(name="jev_supervise", toolset="jev_layer", schema=SUPERVISE, handler=jev_supervise)
+    ctx.register_tool(name="jev_browser_step", toolset="jev_layer", schema=BROWSER_STEP, handler=jev_browser_step)

package/integrations/hermes/plugin.yaml

@@ -1,5 +1,10 @@
-name: jev-layer
-version: 0.1.0
-description: Host-owned Jev capability routing through the standalone jev-layer core
-provides_tools:
-  - jev_route
+name: jev-layer
+version: 0.1.0
+description: Full host-owned Jev routing, receipts, supervision, shadow compaction, model routing, and browser decisions
+provides_tools:
+  - jev_route
+  - jev_model_route
+  - jev_shadow_compaction
+  - jev_record_execution
+  - jev_supervise
+  - jev_browser_step

package/integrations/hermes/schemas.py

@@ -1,12 +1,89 @@
-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"},
-    },
-}
+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"},
+        "provider": {"type": "string", "enum": ["demo", "typesafe", "openrouter"]},
+        "engine": {"type": "string", "enum": ["native", "jevrouter"]},
+    },
+}
+
+RECORD_EXECUTION = {
+    "type": "object",
+    "required": ["correlation_id", "status"],
+    "properties": {
+        "correlation_id": {"type": "string"},
+        "harness": {"type": "string"},
+        "capability_id": {"type": "string"},
+        "status": {"type": "string", "enum": ["completed", "failed", "not_started"]},
+        "result": {},
+        "error": {},
+        "browser": {"type": "object"},
+        "exit_status": {"type": ["integer", "null"]},
+        "duration_ms": {"type": ["number", "null"]},
+        "started_at": {"type": ["string", "null"]},
+        "completed_at": {"type": ["string", "null"]},
+    },
+}
+
+MODEL_ROUTE = {
+    "type": "object",
+    "required": ["intent", "models"],
+    "properties": {
+        "intent": {"type": "string"},
+        "context": {"type": "object"},
+        "models": {"type": "array", "minItems": 1, "items": {"type": "object"}},
+        "harness": {"type": "string"},
+        "policy": {"type": "object"},
+        "provider": {"type": "string", "enum": ["demo", "typesafe", "openrouter"]},
+    },
+}
+
+SHADOW_COMPACTION = {
+    "type": "object",
+    "required": ["intent", "context"],
+    "properties": {
+        "intent": {"type": "string"},
+        "context": {"type": "object"},
+        "provider": {"type": "string", "enum": ["demo", "typesafe", "openrouter"]},
+        "batch_size": {"type": "integer", "minimum": 1, "maximum": 8},
+        "keep_threshold": {"type": "number", "minimum": 0, "maximum": 1},
+        "min_confidence": {"type": "number", "minimum": 0, "maximum": 1},
+    },
+}
+
+SUPERVISE = {
+    "type": "object",
+    "required": ["job", "observation"],
+    "properties": {
+        "job": {"type": "object"},
+        "observation": {"type": "object"},
+        "evidence": {"type": "object"},
+        "harness": {"type": "string"},
+        "actor_permissions": {"type": "array", "items": {"type": "string"}},
+        "policy": {"type": "object"},
+        "attempts": {"type": "integer", "minimum": 0},
+        "provider": {"type": "string", "enum": ["demo", "typesafe", "openrouter"]},
+        "enabled": {"type": "boolean"},
+    },
+}
+
+BROWSER_STEP = {
+    "type": "object",
+    "required": ["goal", "observation"],
+    "properties": {
+        "goal": {"type": "string"},
+        "harness": {"type": "string"},
+        "start_url": {"type": ["string", "null"]},
+        "observation": {"type": "object"},
+        "progress": {"type": "object"},
+        "policy": {"type": "object"},
+        "provider": {"type": "string", "enum": ["demo", "typesafe", "openrouter"]},
+        "enabled": {"type": "boolean"},
+    },
+}

package/integrations/omp/extension.js

@@ -1,105 +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" },
-  };
-}
+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], {
+    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], {
+      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

@@ -1,10 +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.
+# 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.