jev-layer 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to jev-layer are recorded here. Entries describe public behavior and compatibility impact; provider-specific experiments are listed only when they affect a public contract.
+
+## [0.1.0]
+
+First public-release candidate. This version is prepared but has not been pushed, released on GitHub, or published to npm.
+
+### Added
+
+- Portable CLI and stdio MCP routing layer for Hermes, OMP, Codex, and generic MCP-compatible agents.
+- Closed-set capability routing through `jev_route` with deterministic host-side policy checks.
+- `jev_record_execution` and append-only JSONL routing/execution receipts joined by `correlation_id`.
+- Offline replay/evaluation without host execution calls.
+- Opt-in supervision judgments with deterministic host policy.
+- Opt-in deterministic context filtering (`shadow` and `conservative`).
+- Explicit capability discovery for skills, MCP, CLI, DSH, tools, subagents, and models.
+- Experimental, opt-in browser fast-path over host-supplied observations.
+- MIT license, security policy, schema/version policy, contribution guide, adapter template, CI, and multilingual README documentation.
+
+### Compatibility
+
+- Node.js `>=20`.
+- Public request, decision, MCP tool, receipt, replay, and adapter contracts remain schema version 1.
+- Release-preparation baseline: OMP `18.2.6`, Hermes `0.21.3` (`b675e6de`), and Codex CLI `0.155.1` observed in the preparation environment. See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+- Browser reliability is validated against the current real-browser fixtures; browser performance optimization remains experimental.
+
+### Release constraints
+
+- Host harnesses retain ownership of permissions, approvals, native execution, retries, recovery, and final results.
+- Provider-backed tests require explicit secret-managed environments and are not required for ordinary PR CI.
+- No npm publication, GitHub release, or remote push is part of this preparation.
+
+Proposed repository: https://github.com/typakon4/jev-layer. GitHub release and comparison links become active after repository creation.

package/CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing to jev-layer
+
+[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
+
+jev-layer is a portable System-1 decision layer. Contributions must preserve the rule that the host owns execution, permissions, approvals, retries, recovery, and final results. Jev returns bounded decisions; it does not become a security boundary or a second executor.
+
+## Before opening a pull request
+
+1. Read `SECURITY.md` and `docs/SCHEMA-VERSIONING.md`.
+2. Keep the change narrow. Do not add runtime features while changing an adapter or documentation.
+3. Add deterministic tests and an offline fixture. Provider-backed tests are optional and must not require secrets in ordinary CI.
+4. Do not commit API keys, tokens, private keys, `.env` files, machine-specific paths, home directories, or local installation state.
+5. Preserve existing schema v1 fields and fail-open behavior unless a versioned migration is part of the change.
+
+## Adapter contract (version 1)
+
+A harness adapter is a thin integration. It may use the CLI or stdio MCP, but it must preserve the following sequence:
+
+| Stage | Required behavior |
+| --- | --- |
+| Capability discovery/input | Build a closed `capabilities[]` set from the host's known capabilities. Include stable `id`, `kind`, `name`, `description`, `permissions`, `risk`, and availability metadata where known. Do not ask Jev to discover or execute hidden host tools. |
+| `jev_route` call | Send `schema_version: 1`, `harness`, `intent`, bounded `context`, `actor_permissions`, `capabilities`, and `policy` to `jev_route`. Preserve the returned `correlation_id` and selected capability id. |
+| Host execution | Resolve the selected id through the harness's native registry. The adapter must not shell out to arbitrary ids, grant permissions, or replace native tool execution. |
+| `jev_record_execution` receipt | After the host decides what happened, call `jev_record_execution` with the same `correlation_id`, `status` (`completed`, `failed`, or `not_started`), `capability_id`, bounded result/error, and optional exit/timing metadata. |
+| Fail-open | If Jev is disabled, unavailable, times out, returns an error, or returns no usable selection, continue through the harness's normal native path. Never guess a capability or treat a Jev failure as permission to execute. |
+| Approval semantics | The host remains the approval authority. Consequential actions require the host's normal approval before execution. A denial records `not_started`; Jev cannot approve, elevate, retry, or override the host. |
+
+`jev_browser_step` follows the same ownership rule: the host supplies a structured observation, the host approves consequential browser actions, and the host executes or hands control back. It is experimental and opt-in.
+
+### Minimal adapter pseudocode
+
+```text
+request = {
+  schema_version: 1,
+  harness: "my-harness",
+  intent: host_goal,
+  context: bounded_host_context,
+  actor_permissions: host_permissions,
+  capabilities: host_capabilities,
+  policy: host_policy
+}
+
+decision = call_jev_route(request)
+
+if decision.status != "selected" or decision.selected is null:
+    return native_host_path(request)
+
+if consequential(decision.selected) and not host_approval(decision.selected):
+    call_jev_record_execution({
+      correlation_id: decision.correlation_id,
+      capability_id: decision.selected,
+      status: "not_started",
+      error: "host approval denied"
+    })
+    return native_host_path(request)
+
+try:
+    host_result = execute_native(decision.selected)
+    status = "completed"
+except error:
+    host_result = null
+    status = "failed"
+
+receipt = call_jev_record_execution({
+  correlation_id: decision.correlation_id,
+  capability_id: decision.selected,
+  status,
+  result: bounded(host_result),
+  error: bounded(error),
+  duration_ms: measured_duration
+})
+return { decision, host_result, receipt }
+```
+
+Copy `integrations/template/adapter.mjs` for a small JavaScript starting point with the same injected boundaries.
+
+## Adding a new harness
+
+The shortest supported PR path is:
+
+1. Add `integrations/<harness>/` with a thin adapter that calls the existing CLI or MCP contract.
+2. Add a secret-free config/example snippet under `config/` or the integration directory.
+3. Add an offline smoke fixture proving route, fail-open, approval denial, host execution, and execution receipt behavior.
+4. Register compatibility in `README.md`, the translated READMEs, `docs/SCHEMA-VERSIONING.md`, and `RELEASE.md` when the harness is supported.
+5. Run the required CI commands and submit the PR.
+
+Do not add a harness-specific routing implementation. Keep configuration user-owned; never overwrite global harness settings.
+
+## Adding a provider
+
+Providers implement the existing provider surface in `src/providers/`: a `name` and an async `decide({ state, candidates })` method. Supervision-capable providers may also implement `evaluate({ state, questions })`. Return the normalized provider response expected by `src/route.mjs`; do not execute capabilities in the provider.
+
+- Add the provider to explicit configuration/selection only when it is usable offline or clearly fails open.
+- Add deterministic unit tests using injected responses or the `demo` provider.
+- Keep API keys and endpoints in environment variables or user-owned configuration.
+- Provider-backed tests belong in secret-managed CI, not ordinary pull-request CI.
+
+## Adding a discovery source
+
+Use `discoverCapabilities()` and the normalized capability shape in `src/discovery.mjs`. A new source must:
+
+- produce stable, namespaced ids;
+- preserve `kind`, `name`, `description`, `source`, `verified`, and availability metadata;
+- deduplicate by id deterministically;
+- read only explicit input or an explicitly supplied manifest path;
+- never scan undocumented global locations or execute discovered entries.
+
+Add a fixture covering empty input, malformed entries, duplicate ids, unavailable entries, and the new source's normalized output.
+
+## Adding a browser executor
+
+Browser executors are host-owned and optional. Implement `observe()` plus `execute(action)`, and implement `select(action)` when the host has a native select mechanism. The observation must be bounded and structured; the executor must validate target ids, preserve host approval, return the next observation, and report failures without retrying implicitly. Do not add screenshots, text entry, browser workers, or permission logic to jev-layer as part of an executor contribution.
+
+## Adding an eval or replay fixture
+
+Add a small JSONL or JSON fixture under `examples/` or a test fixture directory. Include a stable `schema_version`, `harness`, bounded capabilities, and deterministic expected selection/fallback behavior. For receipts, use one `correlation_id` for the routing case and execution receipt. Exercise it with:
+
+```sh
+npm run replay:evaluate -- --provider demo --limit 20
+npm test
+```
+
+A fixture must not call a real provider, host command, network service, or browser. If a real-provider scenario is useful, document it separately and gate it on an explicitly supplied secret.
+
+## Required checks
+
+From a clean checkout:
+
+```sh
+npm install
+npm test
+npm run smoke
+npm run fail-open-smoke
+npm run clean-install-smoke
+npm pack --dry-run
+```
+
+Changes touching browser, supervision, context filtering, discovery, or MCP should also run the matching existing E2E/smoke script. CI does not require provider credentials.
+
+## Backward compatibility
+
+- Keep schema v1 request, decision, receipt, and replay fields readable.
+- Prefer additive optional fields. Do not rename or remove existing fields in a patch release.
+- Preserve `correlation_id` across route and execution records.
+- Preserve fail-open behavior and host approval ownership.
+- If a breaking contract is unavoidable, document a new schema/adapter version and migration before changing the implementation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jev-layer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# jev-layer
+
+[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
+
+Portable **System-1 decision layer for agent harnesses**. jev-layer routes bounded choices and records evidence; the host keeps execution, permissions, approvals, retries, recovery, and final results.
+
+Supported integration examples: **Hermes, OMP, Codex, and generic MCP-compatible agents**.
+
+## Architecture
+
+```text
++----------------------+      bounded request       +----------------------+
+| Agent harness        | --------------------------> | jev-layer            |
+| Hermes / OMP /       |                            | route / supervise /  |
+| Codex / generic MCP  | <-------------------------- | context filter        |
++----------+-----------+      decision + id          +----------+-----------+
+           |                                                  |
+           | host validates permissions/approval              |
+           v                                                  v
++----------+-----------+      execution result       +----------+-----------+
+| Native host executor | --------------------------> | receipts + replay   |
+| owns all side effects|   jev_record_execution     | JSONL, correlation_id|
++----------------------+                            +----------------------+
+```
+
+Jev never executes a selected capability. A provider can be deterministic `demo`, OpenRouter Decisions, or TypeSafe; provider-backed tests are not required for normal CI.
+
+## Quick Start
+
+Requirements: Node.js 20 or newer. There are no mandatory runtime dependencies.
+
+```sh
+npm install
+npm link
+jev install --project /path/to/workspace
+jev add generic --project /path/to/workspace
+jev doctor --project /path/to/workspace
+```
+
+`npm link` is local only. It does not publish the package. Use `node /path/to/jev-layer/bin/jev.mjs ...` instead if a global link is not wanted. The default `demo` provider is offline and deterministic.
+
+To call the stdio MCP server directly:
+
+```sh
+jev mcp
+```
+
+To use a provider with credentials, keep keys outside the repository:
+
+```sh
+export JEV_LAYER_PROVIDER=openrouter
+export OPENROUTER_API_KEY='provided-by-your-secret-store'
+jev doctor --project /path/to/workspace
+```
+
+## Core surfaces
+
+- **Routing:** `jev_route` selects one capability from the host-supplied candidate set. Selection is advisory; the host validates the id and permissions.
+- **Receipts/replay:** `jev_record_execution` joins the host result to the original `correlation_id`. JSONL cases live in `.jev/replay/cases.jsonl` and can be evaluated offline with `npm run replay:evaluate`.
+- **Supervision:** `jev_supervise` returns bounded work-state judgments; deterministic host policy maps them to `continue`, `verify`, `retry`, `finish`, or `escalate`. Jev does not perform those actions.
+- **Context filtering:** optional deterministic `shadow` or `conservative` filtering reduces stale context without LLM summarization.
+- **Experimental browser fast-path:** `jev_browser_step` chooses one bounded action from a host observation. The host supplies observations, approval, native execution, and recovery. It is opt-in and does not start a browser worker.
+- **Fail-open:** disabled, unavailable, invalid, or inconclusive Jev calls return control to the host's normal path. Jev never widens permissions or guesses execution.
+
+All optional surfaces are disabled by default:
+
+```sh
+JEV_BROWSER_FAST_PATH=1 jev mcp
+JEV_SUPERVISION=1 jev mcp
+JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
+```
+
+## Harness adapters
+
+Current examples live under `integrations/`:
+
+- `integrations/hermes/`
+- `integrations/omp/`
+- `integrations/codex/`
+- `integrations/template/`
+
+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](docs/COMPATIBILITY.md).
+
+Adapters are intentionally thin. They may call the CLI or stdio MCP, but the host must retain native capability lookup, permissions, approvals, execution, retries, recovery, and final output.
+
+### Adding a new harness
+
+The shortest PR path is:
+
+1. copy `integrations/template/adapter.mjs`;
+2. add `integrations/<harness>/` and a secret-free config/example;
+3. call `jev_route`, preserve `correlation_id`, execute only through the host registry, then call `jev_record_execution`;
+4. add an offline smoke fixture for success, fail-open, approval denial, and execution receipt;
+5. document supported versions and run CI.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the adapter contract and [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md) for compatibility rules.
+
+## Browser status
+
+Browser fast-path **reliability is validated against the current real-browser fixtures**, including action sequencing, visible-link navigation, native select execution, approval denial, and recovery. **Performance optimization remains experimental**. No browser speedup claim is made.
+
+## Security and compatibility
+
+- MIT licensed; see [LICENSE](LICENSE).
+- jev-layer is not a security boundary. Host permissions and approvals are authoritative; see [SECURITY.md](SECURITY.md).
+- Schema, MCP tool, receipt, replay, and adapter contracts are currently version 1. Prefer additive changes; do not break v1 silently.
+- Do not commit credentials, logs containing secrets, `.env` files, or machine-specific paths.
+
+## Verification
+
+```sh
+npm test
+npm run smoke
+npm run fail-open-smoke
+npm run clean-install-smoke
+npm pack --dry-run
+```
+
+The GitHub Actions matrix runs these checks on Node.js 20, 22, and 24. Provider-backed tests require an explicitly configured secret-managed environment and are not part of ordinary PR CI.
+
+## Release documents
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [RELEASE.md](RELEASE.md)
+- [CHANGELOG.md](CHANGELOG.md)

package/README.ru.md

@@ -0,0 +1,117 @@
+# jev-layer
+
+[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
+
+Портируемый **System-1 слой принятия решений для agent harnesses**. jev-layer маршрутизирует ограниченные решения и сохраняет доказательства; harness сохраняет владение исполнением, разрешениями, подтверждениями, retry, восстановлением и итоговым результатом.
+
+Поддерживаются примеры интеграций **Hermes, OMP, Codex и generic MCP-compatible agents**.
+
+## Архитектура
+
+```text
++----------------------+       ограниченный запрос  +----------------------+
+| Agent harness        | --------------------------> | jev-layer            |
+| Hermes / OMP /       |                            | route / supervise /  |
+| Codex / generic MCP  | <-------------------------- | context filter        |
++----------+-----------+       решение + id          +----------+-----------+
+           |                                                  |
+           | host проверяет permissions/approval              |
+           v                                                  v
++----------+-----------+       результат исполнения +----------+-----------+
+| Native host executor | --------------------------> | receipts + replay   |
+| владеет side effects |   jev_record_execution     | JSONL, correlation_id|
++----------------------+                            +----------------------+
+```
+
+Jev не исполняет выбранную capability. Доступны детерминированный `demo`, OpenRouter Decisions и TypeSafe; тесты с provider credentials не требуются для обычного CI.
+
+## Быстрый старт
+
+Требуется Node.js 20 или новее. Обязательных runtime-зависимостей нет.
+
+```sh
+npm install
+npm link
+jev install --project /path/to/workspace
+jev add generic --project /path/to/workspace
+jev doctor --project /path/to/workspace
+```
+
+`npm link` используется только локально и ничего не публикует. Вместо него можно запускать `node /path/to/jev-layer/bin/jev.mjs ...`. Provider по умолчанию — офлайн-детерминированный `demo`.
+
+Для stdio MCP:
+
+```sh
+jev mcp
+```
+
+Секреты должны находиться вне репозитория:
+
+```sh
+export JEV_LAYER_PROVIDER=openrouter
+export OPENROUTER_API_KEY='provided-by-your-secret-store'
+jev doctor --project /path/to/workspace
+```
+
+## Основные поверхности
+
+- **Routing:** `jev_route` выбирает одну capability из набора, предоставленного host. Host повторно проверяет id и permissions.
+- **Receipts/replay:** `jev_record_execution` связывает результат host с исходным `correlation_id`. JSONL-файлы находятся в `.jev/replay/cases.jsonl` и проверяются офлайн через `npm run replay:evaluate`.
+- **Supervision:** `jev_supervise` возвращает ограниченные judgments о состоянии работы; детерминированная host policy преобразует их в `continue`, `verify`, `retry`, `finish` или `escalate`. Jev эти действия не выполняет.
+- **Context filtering:** опциональная детерминированная фильтрация `shadow` или `conservative` убирает устаревший context без LLM-суммаризации.
+- **Experimental browser fast-path:** `jev_browser_step` выбирает одно ограниченное действие из observation host. Host предоставляет observation, approval, native execution и recovery.
+- **Fail-open:** при отключённом, недоступном, ошибочном или неубедительном Jev вызове управление возвращается в обычный host path. Jev не расширяет permissions и не угадывает execution.
+
+Опциональные поверхности по умолчанию отключены:
+
+```sh
+JEV_BROWSER_FAST_PATH=1 jev mcp
+JEV_SUPERVISION=1 jev mcp
+JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
+```
+
+## Harness adapters
+
+Примеры находятся в `integrations/`:
+
+- `integrations/hermes/`
+- `integrations/omp/`
+- `integrations/codex/`
+- `integrations/template/`
+
+Для release baseline зафиксированы версии OMP `18.2.6`, Hermes `0.21.3` (`b675e6de`) и Codex CLI `0.155.1`, наблюдавшиеся в среде подготовки. Это базовая проверка версий и контрактов, а не полный набор provider/model tests; подробности — в [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+
+### Добавление нового harness
+
+1. Скопируйте `integrations/template/adapter.mjs`.
+2. Добавьте `integrations/<harness>/` и secret-free config/example.
+3. Вызовите `jev_route`, сохраните `correlation_id`, исполняйте только через native registry host, затем вызовите `jev_record_execution`.
+4. Добавьте offline smoke fixture для успеха, fail-open, отказа в approval и execution receipt.
+5. Зафиксируйте поддерживаемые версии и пройдите CI.
+
+Подробности: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md).
+
+## Статус browser
+
+Надёжность browser fast-path **проверена на текущих real-browser fixtures**: sequencing, visible-link navigation, native select, approval denial и recovery. **Оптимизация производительности остаётся экспериментальной**. Заявлений об ускорении браузера нет.
+
+## Безопасность и совместимость
+
+- Лицензия MIT: [LICENSE](LICENSE).
+- jev-layer не является security boundary. Источник истины для permissions и approvals — host: [SECURITY.md](SECURITY.md).
+- MCP tools, routing decisions, receipts, replay cases и adapter contract сейчас имеют version 1. Изменения должны быть additive и не ломать v1 молча.
+- Не коммитьте credentials, секретные logs, `.env` или machine-specific paths.
+
+## Проверка
+
+```sh
+npm test
+npm run smoke
+npm run fail-open-smoke
+npm run clean-install-smoke
+npm pack --dry-run
+```
+
+GitHub Actions запускает эти проверки на Node.js 20, 22 и 24. Provider-backed тесты требуют отдельного secret-managed окружения и не входят в обычный PR CI.
+
+Документы: [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [RELEASE.md](RELEASE.md) · [CHANGELOG.md](CHANGELOG.md).

package/README.zh-CN.md

@@ -0,0 +1,117 @@
+# jev-layer
+
+[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
+
+面向 agent harness 的可移植 **System-1 决策层**。jev-layer 只负责路由有界决策并记录证据；host 保留执行、权限、审批、重试、恢复和最终结果的所有权。
+
+提供 **Hermes、OMP、Codex 和 generic MCP-compatible agents** 的集成示例。
+
+## 架构
+
+```text
++----------------------+       有界请求            +----------------------+
+| Agent harness        | --------------------------> | jev-layer            |
+| Hermes / OMP /       |                            | route / supervise /  |
+| Codex / generic MCP  | <-------------------------- | context filter        |
++----------+-----------+       决策 + id             +----------+-----------+
+           |                                                  |
+           | host 检查权限和审批                              |
+           v                                                  v
++----------+-----------+       执行结果             +----------+-----------+
+| Native host executor | --------------------------> | receipts + replay   |
+| 负责所有副作用       |   jev_record_execution     | JSONL, correlation_id|
++----------------------+                            +----------------------+
+```
+
+Jev 从不执行选中的 capability。可使用离线确定性的 `demo`、OpenRouter Decisions 或 TypeSafe；普通 CI 不需要 provider credentials。
+
+## 快速开始
+
+需要 Node.js 20 或更新版本。没有必需的 runtime 依赖。
+
+```sh
+npm install
+npm link
+jev install --project /path/to/workspace
+jev add generic --project /path/to/workspace
+jev doctor --project /path/to/workspace
+```
+
+`npm link` 仅用于本地安装，不会发布包。如果不想全局 link，可使用 `node /path/to/jev-layer/bin/jev.mjs ...`。默认 provider 是离线确定性的 `demo`。
+
+直接运行 stdio MCP：
+
+```sh
+jev mcp
+```
+
+凭据必须保存在仓库之外：
+
+```sh
+export JEV_LAYER_PROVIDER=openrouter
+export OPENROUTER_API_KEY='provided-by-your-secret-store'
+jev doctor --project /path/to/workspace
+```
+
+## 核心能力
+
+- **Routing：** `jev_route` 从 host 提供的候选集合中选择一个 capability。host 会再次验证 id 和权限。
+- **Receipts/replay：** `jev_record_execution` 使用原始 `correlation_id` 关联 host 结果。JSONL 位于 `.jev/replay/cases.jsonl`，可用 `npm run replay:evaluate` 离线评估。
+- **Supervision：** `jev_supervise` 返回有界的工作状态判断；确定性的 host policy 将其映射为 `continue`、`verify`、`retry`、`finish` 或 `escalate`。Jev 不执行这些动作。
+- **Context filtering：** 可选的确定性 `shadow` 或 `conservative` 过滤器减少过期 context，不使用 LLM 摘要。
+- **Experimental browser fast-path：** `jev_browser_step` 根据 host observation 选择一个有界浏览器动作。observation、审批、原生执行和恢复都由 host 提供。
+- **Fail-open：** Jev 被禁用、不可用、出错或无法确定时，控制权返回 host 的正常路径。Jev 不扩大权限，也不猜测执行。
+
+所有可选表面默认关闭：
+
+```sh
+JEV_BROWSER_FAST_PATH=1 jev mcp
+JEV_SUPERVISION=1 jev mcp
+JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
+```
+
+## Harness adapters
+
+示例位于 `integrations/`：
+
+- `integrations/hermes/`
+- `integrations/omp/`
+- `integrations/codex/`
+- `integrations/template/`
+
+发布基线记录了准备环境中观察到的 OMP `18.2.6`、Hermes `0.21.3`（`b675e6de`）和 Codex CLI `0.155.1`。这是版本与契约基线，不代表覆盖所有 provider/model 组合；详见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。
+
+### 添加新的 harness
+
+1. 复制 `integrations/template/adapter.mjs`。
+2. 添加 `integrations/<harness>/` 和不含 secret 的 config/example。
+3. 调用 `jev_route`，保留 `correlation_id`，仅通过 host registry 执行，然后调用 `jev_record_execution`。
+4. 添加覆盖成功、fail-open、审批拒绝和 execution receipt 的离线 smoke fixture。
+5. 记录支持的版本并通过 CI。
+
+详见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md)。
+
+## Browser 状态
+
+Browser fast-path 的**可靠性已通过当前 real-browser fixtures 验证**，包括动作顺序、可见链接导航、原生 select、审批拒绝和恢复。**性能优化仍是实验性的**。不宣称任何浏览器加速倍数。
+
+## 安全与兼容性
+
+- MIT 许可证：[LICENSE](LICENSE)。
+- jev-layer 不是 security boundary。权限和审批的权威来源是 host：[SECURITY.md](SECURITY.md)。
+- MCP tools、routing decisions、receipts、replay cases 和 adapter contract 当前都是 version 1。应优先添加可选字段，不要静默破坏 v1。
+- 不要提交 credentials、含 secret 的 logs、`.env` 或 machine-specific paths。
+
+## 验证
+
+```sh
+npm test
+npm run smoke
+npm run fail-open-smoke
+npm run clean-install-smoke
+npm pack --dry-run
+```
+
+GitHub Actions 在 Node.js 20、22 和 24 上运行这些检查。Provider-backed 测试需要单独的 secret-managed 环境，不属于普通 PR CI。
+
+文档：[CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [RELEASE.md](RELEASE.md) · [CHANGELOG.md](CHANGELOG.md)。

package/RELEASE.md

@@ -0,0 +1,53 @@
+# Release checklist
+
+[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
+
+This checklist prepares a public open-source release without publishing or pushing it. Do not run `git push`, create a GitHub release, or run `npm publish` without explicit release approval.
+
+## Before the release commit
+
+- [ ] Confirm package name, ownership, repository metadata, and supported Node versions.
+- [ ] Set the intended semantic version in `package.json` and `package-lock.json`.
+- [ ] Keep `private: true` until the publish decision is explicit; set it false only in the release commit that is authorized to publish.
+- [ ] Confirm [LICENSE](LICENSE) is MIT and the copyright notice is correct.
+- [ ] Review `CONTRIBUTING.md` and [SECURITY.md](SECURITY.md).
+- [ ] Review schema v1 compatibility in [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md).
+- [ ] Verify every supported adapter and its documented compatibility range.
+
+## Verification
+
+- [ ] `npm install`
+- [ ] `npm test`
+- [ ] `npm run smoke`
+- [ ] `npm run fail-open-smoke`
+- [ ] `npm run clean-install-smoke`
+- [ ] Run relevant E2E checks for MCP, receipts, supervision, context filtering, discovery, and browser when changed.
+- [ ] Confirm provider-backed tests are either absent from ordinary CI or run only with secret-managed credentials.
+- [ ] Confirm fail-open and approval-denial paths still preserve host ownership.
+
+## Package and documentation
+
+- [ ] Run `npm pack --dry-run` and inspect the file list.
+- [ ] Ensure no `.env`, credentials, private keys, machine-specific paths, or local state is packaged.
+- [ ] Confirm `README.md`, `README.ru.md`, and `README.zh-CN.md` all start with the language links and describe the same public behavior.
+- [ ] Confirm the README includes the architecture diagram, Quick Start, supported harnesses, routing, receipts/replay, supervision, context filtering, browser status, and fail-open behavior.
+- [ ] Update [CHANGELOG.md](CHANGELOG.md) with user-visible changes and compatibility notes.
+- [ ] Add release notes for schema, adapter, or provider changes.
+
+## Tag and release
+
+- [ ] Review the final diff and `npm pack --dry-run` output.
+- [ ] Create the version commit.
+- [ ] Create an annotated tag matching the package version, for example `v0.1.0`.
+- [ ] Push the commit and tag only after explicit approval.
+- [ ] Create the GitHub release from the tag only after explicit approval.
+- [ ] Verify the release source archive and documentation links.
+
+## npm publish
+
+- [ ] Confirm the package is no longer private and the intended npm account/organization is selected.
+- [ ] Confirm npm 2FA/trusted publishing policy and provenance requirements.
+- [ ] Run `npm publish --dry-run` and inspect the result.
+- [ ] Run `npm publish` only after explicit approval.
+- [ ] Install the published version in a clean temporary directory and run the smoke/clean-install checks.
+- [ ] Record the published version, tag, release URL, and rollback/contact plan in the changelog or release notes.