jev-layer

English · Русский · 简体中文

Install: npm install --global jev-layer · Integrate a harness · Security model

What changes

Jev never executes a selected capability. If it is disabled, unavailable, invalid, or inconclusive, control returns to the host's normal path.

Related MCP server: sagaz-mcp

Quick start

Requires Node.js 20 or newer. There are no mandatory runtime dependencies.

npm install --global jev-layer
jev install --project /path/to/workspace
jev add generic --project /path/to/workspace
jev doctor --project /path/to/workspace

The default demo provider is deterministic and works offline. To run the stdio MCP server directly:

jev mcp

How it fits into a harness

1. The host sends Jev a request and the candidate capabilities it already allows.

2. Jev returns a bounded recommendation. The host checks it against its own registry and permissions.

3. The host decides whether to execute, then can record what happened against the original correlation_id.

A provider can be deterministic demo, OpenRouter Decisions, or TypeSafe. Provider-backed tests are not required for normal CI; see the provider guide.

What else it can do

• Supervision: jev_supervise returns bounded work-state judgments. The host decides whether to continue, verify, retry, finish, or escalate.

• Model routing: jev_model_route recommends one host-declared model profile for a future call. It is advisory only; the host measures outcomes before changing provider or model settings. Correlated receipts can be reviewed with npm run model-route:report -- /path/to/cases.jsonl.

• Shadow compaction: jev_shadow_compaction produces report-only keep/drop candidates for host-supplied context. It does not summarize, mutate, or delete context, and keeps pinned evidence on provider failure.

• Context filtering: optional deterministic shadow or conservative filtering reduces stale context without LLM summarization.

• Experimental browser fast-path: jev_browser_step recommends one bounded action from a host observation. The host supplies approval, native execution, and recovery; Jev does not start a browser worker.

• Fail open: optional Jev surfaces are disabled by default. Jev never widens permissions or guesses execution.

Enable optional surfaces explicitly:

JEV_BROWSER_FAST_PATH=1 jev mcp
JEV_SUPERVISION=1 jev mcp
JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json

For provider credentials, keep keys outside the repository:

export JEV_LAYER_PROVIDER=openrouter
export OPENROUTER_API_KEY='provided-by-your-secret-store'
jev doctor --project /path/to/workspace

Pick an integration

Examples and adapters live under integrations/:

• Hermes: integrations/hermes/ (see the local-agent handoff guide)

• OMP: integrations/omp/

• Codex: integrations/codex/

• Another harness: start from integrations/template/

Adapters stay thin. The host retains native capability lookup, permissions, approvals, execution, retries, recovery, and final output. For the adapter contract, see CONTRIBUTING.md. For compatibility rules, see docs/SCHEMA-VERSIONING.md.

The release baseline records OMP 18.2.6, Hermes 0.21.3 (b675e6de), and Codex CLI 0.155.1 observed in the preparation environment. This is a version/contract baseline, not a claim of full provider/model coverage; see docs/COMPATIBILITY.md.

Boundaries

• jev-layer is not a security boundary. Host permissions and approvals remain authoritative; see SECURITY.md.

• Schema, MCP tool, receipt, replay, and adapter contracts are currently version 1. Prefer additive changes; do not break v1 silently.

• Browser fast-path reliability is validated against current real-browser fixtures. Performance optimization remains experimental; no browser speedup claim is made.

• Do not commit credentials, logs containing secrets, .env files, or machine-specific paths.

Verify locally

npm test
npm run smoke
npm run fail-open-smoke
npm run clean-install-smoke
npm pack --dry-run

GitHub Actions runs these checks on Node.js 20, 22, and 24. Provider-backed tests require a secret-managed environment and are not part of ordinary PR CI.

Project docs

Agent implementation guide · Providers · Compatibility · Contributing · Security · Release · Changelog