jev-layer 0.1.0 → 0.3.0

package/README.zh-CN.md

@@ -1,117 +1,139 @@
-# 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)。
+<p align="center">
+  <img src="docs/jev-layer-banner.svg" alt="jev-layer — 面向 agent harness 的可移植 System-1 决策层" width="960">
+</p>
+
+<h1 align="center">jev-layer</h1>
+
+<p align="center">
+  <strong>面向 agent harness 的可移植 System-1 决策层。</strong><br>
+  Host 保留 routing、receipts、replay 和 fail-open 集成的所有权。
+</p>
+
+<p align="center">
+  Hermes · OMP · Codex · generic MCP
+</p>
+
+<p align="center">
+  <a href="https://github.com/typakon4/jev-layer/actions/workflows/ci.yml?query=branch%3Amain"><img alt="CI status" src="https://github.com/typakon4/jev-layer/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="https://www.npmjs.com/package/jev-layer"><img alt="npm version" src="https://img.shields.io/npm/v/jev-layer?logo=npm&amp;label=npm"></a>
+  <a href="https://github.com/typakon4/jev-layer/releases"><img alt="latest GitHub release" src="https://img.shields.io/github/v/release/typakon4/jev-layer?display_name=tag&amp;sort=semver"></a>
+  <a href="https://github.com/typakon4/jev-layer/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/typakon4/jev-layer"></a>
+</p>
+
+[English](README.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+jev-layer 只负责路由有界决策并记录证据；host 保留执行、权限、审批、重试、恢复和最终结果的所有权。
+
+> 将 jev-layer 集成到 harness 时，请先把 [Agent implementation guide](docs/AGENT-IMPLEMENTATION.md) 交给 agent，不要只发送 README 链接。
+
+## 架构
+
+<p align="center">
+  <img src="docs/architecture.svg" alt="架构：agent harness 向 jev-layer 发送有界请求；host 负责权限和执行；receipts 支持 replay。" width="960">
+</p>
+
+Jev 从不执行选中的 capability。可使用离线确定性的 `demo`、OpenRouter Decisions 或 TypeSafe；普通 CI 不需要 provider credentials。
+
+## 快速开始
+
+需要 Node.js 20 或更新版本。没有必需的 runtime 依赖。
+
+安装已发布的 CLI：
+
+```sh
+npm install --global jev-layer
+```
+
+或者使用本地 clone：
+
+```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
+```
+
+三种模式（`demo`、`openrouter` 和直连 `typesafe`）、端点及配置优先级见[提供商指南](docs/PROVIDERS.md)。
+
+## 核心能力
+
+- **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`。receipt 记录确定性的 `evidence_state`：`present`、`missing` 或 `contradictory`；矛盾证据不能导致 `finish`。Jev 不执行这些动作。
+- **Shadow compaction：** `jev_shadow_compaction` 为 host 提供的 context 生成批量、保守、只报告的 keep/drop 候选。它不会修改、总结或删除 context；path、error、command 和 requirement 在 provider review 前被保留，provider 失败时保留所有其他 items。
+- **Context filtering：** 可选的确定性 `shadow` 或 `conservative` 过滤器减少过期 context，不使用 LLM 摘要。
+- **Experimental browser fast-path：** `jev_browser_step` 根据 host observation 选择一个有界浏览器动作。observation、审批、原生执行和恢复都由 host 提供。
+- **Jev 1.14 视觉与 computer use：** TypeSafe 和 OpenRouter 都支持 PNG/JPEG 截图，适配器会转换各 API 的图片格式。可选 `jev_computer_step` 仅推荐 host 声明的桌面动作；Box 定位需验证目标可见性，执行仍需 host 审批。见[契约](docs/AGENT-IMPLEMENTATION.md#vision-and-computer-use)。
+- **Fail-open：** Jev 被禁用、不可用、出错或无法确定时，控制权返回 host 的正常路径。Jev 不扩大权限，也不猜测执行。
+
+所有可选表面默认关闭：
+
+```sh
+JEV_BROWSER_FAST_PATH=1 jev mcp
+JEV_LAYER_PROVIDER=openrouter JEV_COMPUTER_USE=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) · [Agent implementation guide](docs/AGENT-IMPLEMENTATION.md)。

package/RELEASE.md

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

package/SECURITY.md

@@ -1,56 +1,64 @@
-# 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.
+# 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.
+
+## Screenshots and computer use
+
+Screenshots can expose secrets even when text keys have been redacted. Capture/redact/crop them in the host before upload; image understanding is a remote, experimental provider feature, not local vision. Inline images are excluded from durable replay and pending receipt requests, and `data_base64` fields are redacted from context/host results.
+
+`jev_computer_step` only chooses from host-declared click, type, key, scroll, or handoff actions. Computer permissions must be explicit. Click/type/key always require host confirmation, including when their declared risk is low. A Box is used only with a positive target-visibility probability and sufficient confidence; it is not proof that an action is safe.
+
+Every returned computer action is bound to the supplied screenshot's SHA-256 and dimensions. Before acting, the host must verify that it is still current, re-observe if stale, map screenshot pixels to its desktop/window/crop/DPI coordinates, and enforce native permissions, focus, approvals and cancellation. The layer never captures the desktop or injects mouse/keyboard events.
+
+## 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.