jev-layer 0.1.0 → 0.3.0

package/docs/AGENT-IMPLEMENTATION.md

@@ -0,0 +1,306 @@
+# Agent implementation guide
+
+This is the implementation brief to hand to a coding agent before integrating jev-layer into a harness. It is intentionally operational: inspect the target harness first, preserve host ownership, and prove the fallback path. Do not treat a link to this repository as permission to invent an adapter or change the host's execution model.
+
+## Contract in one paragraph
+
+jev-layer is a **System-1 decision layer**, not an executor, permission system, security boundary, retry loop, or browser worker. The host owns capability discovery, the closed candidate set, permissions, approvals, native execution, retries, recovery, and final output. Jev receives bounded input, returns one bounded decision with a `correlation_id`, and records the host's result. If Jev is disabled, unavailable, invalid, inconclusive, or refused by policy, the host continues through its normal native path.
+
+## Before editing
+
+1. Identify the harness's native capability registry and native execution function.
+2. Identify the existing permission and approval checks, especially for consequential actions.
+3. Identify the host's normal fallback path and its error/retry boundaries.
+4. Read [CONTRIBUTING.md](../CONTRIBUTING.md), [SECURITY.md](../SECURITY.md), and [SCHEMA-VERSIONING.md](SCHEMA-VERSIONING.md).
+5. Confirm the harness version and transport: CLI, stdio MCP, or an existing adapter boundary.
+6. Write a short integration plan naming the exact adapter entry point and the unchanged host-owned functions.
+7. Only then edit the smallest possible adapter/configuration surface.
+
+Do not begin by pasting the repository URL to an agent and asking it to "integrate Jev" without supplying the target harness, its native execution path, and its approval semantics.
+
+## Required data flow
+
+### 1. Build a closed capability set in the host
+
+The host must provide only capabilities it already knows how to execute. Each candidate needs a stable id and enough metadata for bounded selection:
+
+```json
+{
+  "id": "repo:search",
+  "kind": "tool",
+  "name": "Search repository",
+  "description": "Find text in tracked repository files",
+  "permissions": ["read"],
+  "risk": "low",
+  "available": true
+}
+```
+
+Do not ask Jev to discover hidden host tools. Do not pass arbitrary shell commands as capability ids. Do not expose a capability that the host cannot validate and execute through its native registry.
+
+### 2. Call `jev_route` with bounded input
+
+Preserve schema version 1 and include the host-owned facts needed for the decision:
+
+```json
+{
+  "schema_version": 1,
+  "harness": "my-harness",
+  "intent": "Find the implementation of the routing contract",
+  "context": {
+    "task": "repository inspection"
+  },
+  "actor_permissions": ["read"],
+  "capabilities": [
+    {
+      "id": "repo:search",
+      "kind": "tool",
+      "name": "Search repository",
+      "description": "Find text in tracked repository files",
+      "permissions": ["read"],
+      "risk": "low",
+      "available": true
+    }
+  ],
+  "policy": {
+    "deterministic": true
+  }
+}
+```
+
+Keep `intent`, `context`, and the candidate set bounded. Do not send credentials, unbounded conversation history, hidden tool descriptions, or machine-specific paths.
+
+### 3. Treat the response as advice, never authorization
+
+A normal decision has this shape:
+
+```json
+{
+  "schema_version": 1,
+  "correlation_id": "decision-id",
+  "status": "selected",
+  "selected": "repo:search",
+  "execution": {
+    "enabled": false,
+    "status": "not_started"
+  }
+}
+```
+
+The adapter must validate all of the following before execution:
+
+- `status` permits a host action (`selected` is different from `fallback`, `no_decision`, and `needs_confirmation`);
+- `selected` is non-null and exactly matches an id in the request's candidate set;
+- the candidate is still available and its permissions/risk are acceptable;
+- the host's current approval policy allows the action.
+
+Never execute an id returned by Jev as a shell command, import path, URL, or arbitrary function name. Resolve it through the harness's native registry.
+
+### 4. Let the host approve consequential work
+
+Jev cannot approve, elevate, or override the host. For a consequential candidate:
+
+1. pause after the decision;
+2. run the host's existing approval flow;
+3. if denied, do not execute and record `status: "not_started"`;
+4. if approved, execute through the native host path.
+
+The Jev decision does not replace the harness confirmation dialog, policy engine, or permission check.
+
+### 5. Execute only through the native host path
+
+The adapter must not become a second executor. Preserve the host's existing:
+
+- capability lookup;
+- permission checks;
+- approval prompts;
+- process/browser/tool execution;
+- retry and recovery behavior;
+- result shaping and user-visible output.
+
+Jev returns a decision. The host performs the work.
+
+### 6. Record one receipt with the same correlation id
+
+After the host knows what happened, call `jev_record_execution`:
+
+```json
+{
+  "correlation_id": "decision-id",
+  "harness": "my-harness",
+  "capability_id": "repo:search",
+  "status": "completed",
+  "result": {
+    "matches": 3
+  },
+  "exit_status": 0,
+  "duration_ms": 12
+}
+```
+
+Use the same `correlation_id` from `jev_route`. Use:
+
+- `completed` when native execution finished successfully;
+- `failed` when native execution ran and failed;
+- `not_started` when approval, policy, or fail-open handling prevented execution.
+
+Bound results and errors before recording them. Never write secrets or full untrusted logs into receipts.
+
+### 7. Preserve fail-open behavior
+
+The following conditions must return control to the host's ordinary path without guessing a capability:
+
+- Jev is disabled by configuration;
+- the MCP/CLI process is unavailable or times out;
+- the provider returns an error or malformed response;
+- the decision is `fallback`, `no_decision`, or otherwise unusable;
+- the selected id is not in the closed candidate set;
+- permissions or approval reject the action.
+
+A Jev failure is not permission to execute. Do not add an adapter retry loop that changes the host's existing retry semantics.
+
+## Installing and wiring the package
+
+For a published local CLI:
+
+```sh
+npm install --global jev-layer
+jev init --project /path/to/workspace
+jev add generic --project /path/to/workspace
+jev doctor --project /path/to/workspace
+```
+
+For a stdio MCP server:
+
+```sh
+jev mcp
+```
+
+The generated generic adapter uses the `jev mcp` command. Keep the adapter configuration in the project/workspace where the harness owns it; do not overwrite global harness configuration. Use `JEV_LAYER_PROVIDER=demo` for offline deterministic development. Keep OpenRouter or TypeSafe credentials in the process environment or another user-owned secret store.
+
+For an existing harness, copy the smallest relevant example from `integrations/` and adapt its transport. Do not copy an integration wholesale without checking the harness's actual registry, approval, and execution APIs.
+
+## Copy-paste handoff for a coding agent
+
+Use this prompt with the guide and the target harness details:
+
+```text
+Implement jev-layer as a thin System-1 decision layer in this harness.
+
+Read docs/AGENT-IMPLEMENTATION.md first. Then inspect the harness's native
+capability registry, permission checks, approval flow, execution function,
+retry/recovery boundaries, and existing MCP/CLI integration point.
+
+Target harness: <name and version>
+Target integration point: <file/function/config>
+Native execution function: <file/function>
+Approval authority: <file/function>
+Normal fallback path: <file/function>
+
+Requirements:
+- Build a closed capabilities[] set from the host registry.
+- Call jev_route with schema_version: 1, bounded intent/context,
+  actor_permissions, capabilities, and policy.
+- Validate status, selected id, availability, permissions, and approval in
+  the host before execution.
+- Resolve selected ids through the native registry; never shell out to ids
+  returned by Jev and never let Jev execute host work.
+- Preserve the existing host fallback path when Jev is disabled, unavailable,
+  invalid, inconclusive, or rejected.
+- Call jev_record_execution with the same correlation_id after the host knows
+  the result.
+- Add offline tests for selected execution, fail-open, unknown-id rejection,
+  approval denial, and receipt correlation.
+- Do not add provider credentials, global config writes, hidden capability
+  discovery, arbitrary command execution, or unrelated runtime features.
+
+Before changing code, show the files/symbols you will touch. After changing
+code, report the exact native execution path preserved and the verification
+commands/results.
+```
+
+Replace every `<...>` placeholder with facts from the target harness. Do not leave the agent to infer them from a generic repository link.
+
+## Vision and computer use
+
+Jev 1.14 image input and Box are experimental. Direct `typesafe` is pinned to `jev-1.14.0` and sends the required Images opt-in header. `openrouter` uses `typesafe/jev-1.14` and converts layer assets into inline `image_url` parts. Both support screenshots; live OpenRouter checks verified color perception and screenshot-only Box grounding. See [provider formats, limits and enablement](PROVIDERS.md#images-and-box-questions).
+
+### Browser screenshots
+
+`jev_browser_step` accepts optional `observation.screenshot = { format, data_base64, width, height }` alongside the existing visible text, DOM/accessibility targets, tabs, scroll and progress. Existing structured actions remain authoritative; an image does not invent additional browser capabilities. The host-owned `runBrowserFastPath` also forwards screenshots from `executor.observe()` and subsequent observations.
+
+### Desktop decision
+
+Enable with `features.computer_use: true`, `JEV_COMPUTER_USE=1`, or per-call `enabled: true`. Explicit per-call `enabled: false` wins. Send `jev_computer_step` (MCP) or `computer_step` (Hermes core) this shape:
+
+```json
+{
+  "provider": "openrouter",
+  "enabled": true,
+  "goal": "Click the visible Save button",
+  "actor_permissions": ["computer"],
+  "observation": {
+    "application": "Editor",
+    "screenshot": {
+      "format": "png",
+      "data_base64": "<base64 of the host-captured image>",
+      "width": 400,
+      "height": 300
+    }
+  },
+  "actions": [
+    { "id": "save", "operation": "click", "target": "the Save button", "args": {} },
+    { "id": "handoff", "operation": "handoff", "args": {} }
+  ]
+}
+```
+
+The screenshot must be a prepared PNG/JPEG within upstream limits; its declared dimensions must match its bytes. No file paths, URLs, implicit screenshot capture or image resizing. Supply at most 32 unique host-owned action ids. The supported argument shapes are:
+
+| Operation | Host-supplied `args` |
+| --- | --- |
+| `click` | `{ x, y, button? }`, or `{ button? }` plus a unique top-level `target` description |
+| `type` | `{ text }`; exact host text, never generated by Jev |
+| `key` | `{ keys: ["Control", "S"] }`; exact host key names |
+| `scroll` | `{ direction: "up|down|left|right", amount?, x?, y? }` |
+| `handoff` | `{ reason? }` |
+
+Availability, additional permissions, risk and confirmation metadata use the existing capability policy. Missing `computer` permission cannot select a desktop action. Click/type/key always return `needs_confirmation`; the layer does not approve or execute them.
+
+For a selected described click, a second request asks Noul whether the target is clearly visible and unique, and Box where it is. Both must pass `policy.min_target_visibility` (default `0.9`) and `policy.min_box_confidence` (default `0.8`). These are configurable prototype thresholds, not validated safety guarantees. Absent, ambiguous, low-confidence, malformed or failed grounding yields `fallback` with `computer_action: null`.
+
+`computer_action.args.x/y` are the box center in **screenshot pixels**, rounded down and bounded to the image. `grounding` contains normalized edges and visibility/confidence. `computer_action.screenshot` contains the SHA-256 of decoded image bytes, dimensions and `requires_current: true`. The host must re-check freshness, focus, coordinate mapping (including crop/window origin and DPI), availability and native approval immediately before dispatch. Re-observe after execution; stop or fall back on stale state or lack of progress. Record the result using the original `correlation_id`.
+
+### Image privacy and replay
+
+Images travel in route `assets`, outside the bounded text projection; generic `jev_route` attaches their references once as `state.visual_assets`. Do not duplicate those references in context unless another image expansion is intended. Do not place base64 in capability descriptions or free-text prompts.
+
+Routing cases and retained receipt requests omit images and set `assets_omitted: true`; bounded host results redact `data_base64`. Visual replay fails open until the host explicitly restores the original assets and removes that marker. Screenshots may still contain secrets: redact them before sending to a remote provider. The layer does not provide local vision or an OS executor.
+
+## Minimum verification matrix
+
+An implementation is not complete until it proves these observable behaviors:
+
+| Scenario | Required result |
+| --- | --- |
+| Valid low-risk selection | Host executes the matching native capability once. |
+| Unknown or stale selected id | Host does not execute; normal fallback remains available. |
+| `needs_confirmation` | Host approval is requested before execution. |
+| Approval denied | No host execution; receipt is `not_started`. |
+| Jev disabled/unavailable/error | Normal host path continues without guessed selection. |
+| Native execution failure | Receipt is `failed` with the same `correlation_id`. |
+| Successful native execution | Receipt is `completed` with bounded result/timing metadata. |
+| Replay evaluation | Routing/receipt cases replay without host execution. |
+
+Run the existing project checks plus the matching adapter smoke fixture. At minimum, a jev-layer integration should preserve the checks in `CONTRIBUTING.md` and add a harness-specific offline fixture; provider credentials are not required for ordinary CI.
+
+## Common incorrect implementations
+
+- **Calling Jev after executing the tool.** Routing must happen before the host action.
+- **Passing every hidden tool to Jev.** Send only a closed, host-owned candidate set.
+- **Treating `selected` as authorization.** The host still validates permissions and approval.
+- **Executing the returned id directly.** Map it through the native registry; never use it as a command.
+- **Replacing fail-open with a retry loop.** Return to the existing host path.
+- **Letting Jev discover or mutate global config.** Discovery and configuration remain explicit and user-owned.
+- **Adding provider calls to ordinary CI.** Use the deterministic `demo` provider and injected fixtures.
+- **Reporting only that an adapter was added.** Show the preserved execution path, receipt correlation, and fallback evidence.

package/docs/COMPATIBILITY.md

@@ -1,15 +1,24 @@
-# 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.
+# 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.
+
+## Jev 1.14 verification — 2026-10-15
+
+- Existing v1 text contracts remain unchanged. Direct TypeSafe defaults to `jev-1.14.0`; OpenRouter defaults to `typesafe/jev-1.14`.
+- Live OpenRouter alpha Decisions routing resolved `typesafe/jev-1.14-20261014` and selected an eligible capability without execution.
+- Vision/browser/computer-use transport was exercised through an actual stdio MCP process and a loopback HTTP fixture: image bytes/header/model, confirmation, absent-target fallback, screenshot coordinate mapping, correlated denial receipt, browser-loop execution by the fixture host, and image-free replay.
+- Live OpenRouter vision with the corrected `image_url` Decisions format classified red and blue PNGs correctly (confidence 1 each). The actual MCP computer tool selected a screenshot-only red rectangle and grounded its click at `(200, 148)` within the known rectangle, with visibility 0.97 and Box confidence 0.98. Host confirmation was required and no desktop input was dispatched; the correlated denial receipt omitted screenshot bytes.
+- No direct TypeSafe API key was available for live accuracy testing. Earlier OpenRouter probes with TypeSafe's `assets` format were invalid transport probes, not evidence against OpenRouter vision support. Physical input dispatch, full interactive harnesses, DPI/crop mapping and general visual accuracy remain host/environment-specific and are not established by these controlled checks.
+- Windows release checks: `npm test` passed 117 tests with two optional Python-transport skips; core smoke, fail-open, browser MCP e2e, MCP receipts, feature flags, supervision, context filtering and capability e2e passed. A separate Python → Node → loopback HTTP smoke exercised computer grounding and a correlated denial receipt. Cross-platform clean-install smoke now passes on Windows using native Node entrypoints, with installed CLI/MCP, correlated receipts and execution-free replay.

package/docs/HERMES-LOCAL-AGENT-HANDOFF.ru.md

@@ -0,0 +1,187 @@
+# Hermes integration: handoff для локального агента
+
+Этот документ описывает **текущую рабочую интеграцию** `jev-layer` в Hermes. Он нужен локальному агенту, чтобы сначала понять границы и точки входа, а не повторно «интегрировать Jev» через глобальный конфиг, произвольные shell-команды или второй executor.
+
+## Что уже установлено
+
+- Исходный репозиторий: `/home/hermes/jev-layer`.
+- Активная plugin-копия Hermes: `~/.hermes/plugins/jev-layer`.
+- Набор tools текущего исходника (новый `jev_computer_step` появится в gateway только после синхронизации plugin-копии и restart):
+  - `jev_route`;
+  - `jev_record_execution`;
+  - `jev_supervise`;
+  - `jev_browser_step`;
+  - `jev_computer_step`;
+  - `jev_shadow_compaction`;
+  - `jev_model_route`.
+- Replay evidence активного профиля: `~/.hermes/jev-layer/replay/cases.jsonl`.
+- Gateway загружает Python plugin при старте. После изменения `integrations/hermes/*`, `plugin.yaml` или списка tools нужен пользовательский `/restart` gateway.
+
+Не путай surfaces:
+
+```text
+/home/hermes/jev-layer                 source checkout, тесты и документация
+~/.hermes/plugins/jev-layer            установленная plugin-копия текущего профиля
+~/.hermes/jev-layer/replay/cases.jsonl profile-scoped evidence, не source artifact
+~/.hermes/config.yaml                  глобальный Hermes config; не менять для этой plugin без явного задания
+```
+
+## Главный принцип
+
+```text
+Hermes registry/permissions/approval/executor/recovery
+                 │ closed, bounded input
+                 ▼
+            jev-layer decision
+                 │ correlation_id, advice only
+                 ▼
+Hermes validates → native execution → jev_record_execution → JSONL evidence
+```
+
+Jev **никогда** не получает право исполнять tool, shell, URL или browser action. Любое решение — advisory. Hermes остаётся владельцем discovery, policy, approval, native execution, retry, recovery и финального ответа.
+
+Если Jev выключен, недоступен, даёт невалидный ответ или низкую уверенность, текущий normal Hermes path продолжается. Не добавляй обходной executor и не меняй retry semantics.
+
+## Файловая карта
+
+| Зачем | Файл |
+| --- | --- |
+| Hermes tool registration + profile-scoped secret bridge | `integrations/hermes/__init__.py` |
+| JSON schemas шести tool surfaces | `integrations/hermes/schemas.py` |
+| Plugin manifest | `integrations/hermes/plugin.yaml`, `plugin.yaml` |
+| Один JSONL request/response adapter process | `src/hermes-adapter.mjs` |
+| Общая bounded routing contract | `src/route.mjs`, `src/contract.mjs` |
+| Receipt/replay JSONL format | `src/receipts.mjs` |
+| Browser action space, progress и recovery | `src/browser.mjs` |
+| Model recommendation | `src/model-routing.mjs` |
+| Model-route evidence report | `src/model-route-metrics.mjs`, `scripts/model-route-report.mjs` |
+| Context keep/drop report | `src/shadow-compaction.mjs` |
+| Work-state judgement | `src/supervision.mjs` |
+| Harness-neutral integration contract | `docs/AGENT-IMPLEMENTATION.md` |
+
+## Как работают tools
+
+### `jev_route`
+
+Hermes сначала собирает **закрытый** `capabilities[]` из своего registry. Jev выбирает один известный id. До исполнения Hermes снова проверяет: `status`, точное совпадение id, availability, permission, risk и approval. После результата используется `jev_record_execution` с тем же `correlation_id`.
+
+Нельзя передавать в candidates hidden tools, raw shell command, credential, неограниченную историю или capability, для которой у Hermes нет native executor.
+
+### `jev_record_execution`
+
+Принимает результат уже выполненного/отклонённого host action. `correlation_id` должен принадлежать decision того же gateway process. Статусы: `completed`, `failed`, `not_started`.
+
+Receipt — evidence, не источник авторизации. В `result` нельзя писать токены, пароли, номера карт и полный неочищенный лог.
+
+### `jev_model_route`
+
+Возвращает рекомендацию одного из **host-declared** `models[]`. Всегда `route_mode: "shadow"`; он не меняет Hermes provider, model или reasoning effort.
+
+Когда host закончил реальный model call, он записывает outcome через `jev_record_execution`:
+
+```json
+{
+  "correlation_id": "из jev_model_route",
+  "capability_id": "recommended model id",
+  "status": "completed",
+  "result": {
+    "model_route": {
+      "actual_model_id": "фактически использованный id",
+      "retry_count": 0,
+      "outcome": "verified"
+    }
+  }
+}
+```
+
+Отчёт только читает receipts:
+
+```bash
+npm run model-route:report -- ~/.hermes/jev-layer/replay/cases.jsonl
+```
+
+Пока не накоплены репрезентативные outcomes/retries/latency/cost, **не включать** auto-switching моделей.
+
+### `jev_browser_step`
+
+Принимает только snapshot, который сделал host: `url`, visible text, targets, tabs, scroll, progress и опциональный `screenshot: {format, data_base64, width, height}`. Возвращает один bounded action: scroll, switch tab, visible link navigation, click, native select или handoff.
+
+- `scroll` и `switch_tab` могут быть исполнены только через native Hermes browser executor.
+- `click`, `select`, `navigate` требуют host approval.
+- `submit`, login, payment, delete, секретный ввод и `TYPE_TEXT` не являются быстрым Jev execution path.
+- Progress не даёт повторять уже выполненный target и блокирует повторный scroll без измеримого состояния страницы.
+- После каждого host шага можно записать routing case и execution receipt; это позволяет replay без повторного browser execution.
+
+`browser-use/jev-ultrafast` был использован как архитектурный reference (динамическая индексированная action space), но его cloud/browser worker **не установлен и не запущен**. Не подменяй Hermes browser security model его executor'ом.
+
+### `jev_computer_step`
+
+Новая opt-in поверхность для desktop: host передаёт скриншот и закрытый `actions` из click/type/key/scroll/handoff. Нужны явные `actor_permissions: ["computer"]` и Jev 1.14 через `openrouter` или `typesafe`. Включение: `JEV_COMPUTER_USE=1`, `features.computer_use: true` или `enabled: true`; явное `enabled: false` отключает вызов.
+
+Клик по описанной цели проходит отдельные Noul + Box проверки. Координаты привязаны к SHA-256 и пикселям исходного скриншота; freshness, focus, DPI/crop mapping и исполнение проверяет host. Click/type/key требуют host confirmation даже при low risk. OpenRouter принимает изображения как inline `image_url` parts, а не TypeSafe `assets`; адаптер делает преобразование автоматически. Live проверки подтвердили различение красного/синего и grounding прямоугольника по скриншоту.
+
+Полный [контракт и пример](AGENT-IMPLEMENTATION.md#vision-and-computer-use). Скриншоты не сохраняются в replay; visual replay без исходных assets возвращает fallback. Никакой desktop executor, OCR service или browser worker этой поверхностью не устанавливается.
+
+
+### `jev_shadow_compaction`
+
+Возвращает консервативный report keep/drop для переданного context. Не меняет prompt, не удаляет сообщения и не заменяет host compaction. Pinned requirements, paths, errors и commands сохраняются без provider review; provider error удерживает всё.
+
+### `jev_supervise`
+
+Делает bounded judgement о work state. Hermes, не Jev, преобразует его в `continue`, `verify`, `retry`, `finish` или `escalate`. Contradictory evidence не может закончиться `finish`.
+
+## Secrets и providers
+
+`integrations/hermes/__init__.py` получает `OPENROUTER_API_KEY` только через Hermes profile-scoped secret store (`agent.secret_scope.get_secret`). Ключ передаётся лишь в короткоживущий локальный Node adapter; не возвращается в tool output и не логируется.
+
+Для локальных/offline tests используй `provider: "demo"`. Provider-backed проверки — отдельные, opt-in; ключи никогда не клади в repo, plugin manifest, test fixture или обычный shell history.
+
+## Безопасный change workflow
+
+1. Прочитай этот документ и `docs/AGENT-IMPLEMENTATION.md`.
+2. Проверь target surface: source checkout, installed plugin copy, active profile или global config.
+3. Измени source в `/home/hermes/jev-layer` и сначала добавь/измени offline test.
+4. Запусти узкий test, затем полный suite.
+5. Синхронизируй **только нужные** source files в `~/.hermes/plugins/jev-layer`.
+6. Запусти `hermes plugins doctor jev-layer`.
+7. Если менялась регистрация/handler/schema/manifest, попроси пользователя о `/restart`.
+8. После restart проверь живой gateway tool path и read back exact receipt/report.
+9. Не делай `git push`, npm publish, GitHub release или изменение глобального Hermes config без отдельной команды пользователя.
+
+## Проверки
+
+Из source checkout:
+
+```bash
+npm test
+npm run receipt:mcp-smoke
+npm run browser:e2e
+npm run model-route:report -- /tmp/nonexistent-cases.jsonl
+python3 -m py_compile integrations/hermes/__init__.py integrations/hermes/schemas.py
+git diff --check
+hermes plugins doctor jev-layer
+```
+
+Текущее доказанное состояние: `npm test` — 35/35; MCP receipt smoke и browser fixture E2E проходят; gateway-live model route был записан и успешно связан с execution receipt/report. Это не доказательство автоматического роутинга моделей и не утверждение о real-browser speedup.
+
+## Готовый prompt локальному агенту
+
+```text
+Работай только с jev-layer в указанном target surface. Сначала прочитай:
+- docs/HERMES-LOCAL-AGENT-HANDOFF.ru.md
+- docs/AGENT-IMPLEMENTATION.md
+
+Сохрани host ownership: Jev даёт bounded advisory decision; Hermes владеет registry,
+permissions, approval, execution, retry/recovery и финальным результатом. Не добавляй
+автоматическое переключение моделей, browser executor, глобальный config write, provider
+credential или network publication без отдельного явного требования.
+
+Перед изменением назови source files, installed plugin files и gateway impact. Используй TDD:
+сначала узкий offline test, затем implementation, потом npm test + релевантные smoke tests.
+Если touch'нуты registration/handler/schema/manifest, синхронизируй plugin copy, прогоняй
+hermes plugins doctor jev-layer и попроси /restart. После рестарта сделай live tool call,
+запиши/прочитай exact receipt и только затем заявляй, что integration активна.
+
+Не делай git push, npm publish, release или удаление replay/artifact без отдельной команды.
+```

package/docs/PROVIDERS.md

@@ -0,0 +1,109 @@
+# Routing providers
+
+CLI, stdio MCP, and the Hermes/OMP adapters use the same three providers. Routing, supervision, and browser decisions share provider resolution. The host still owns execution and approval.
+
+| Provider | Default endpoint | Default model | Credentials |
+| --- | --- | --- | --- |
+| `demo` | None; deterministic word matching, no HTTP | `jev-demo` | None |
+| `openrouter` | `https://openrouter.ai/api/alpha/decisions` | `typesafe/jev-1.14` | `OPENROUTER_API_KEY` |
+| `typesafe` | `https://api.typesafe.ai/v1/systemone` | `jev-1.14.0` | `TYPESAFE_API_KEY` |
+
+Both remote providers send `{ model, state, questions }` with a Choice question and Bearer authentication. They use the [OpenRouter Decisions API](https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-questions-and-answers-request) and the [official TypeSafe API](https://docs.typesafe.ai/api), respectively.
+
+TypeSafe is pinned to the [official Jev 1.14 release](https://docs.typesafe.ai/models); `TYPESAFE_MODEL` still overrides it. The upstream `jev-latest` alias currently points to 1.13, so it does not select 1.14. OpenRouter defaults to its verified [Jev 1.14 model ID](https://openrouter.ai/typesafe/jev-1.14); `OPENROUTER_DECISIONS_MODEL` still overrides it. Both providers support PNG/JPEG images and Box with Jev 1.14, using different HTTP image formats.
+
+## Images and Box questions
+
+Both providers advertise `supportsImages = true`. Their `decide({ state, candidates, assets })` and `evaluate({ state, questions, assets })` accept the same optional layer-level `assets` map:
+
+```json
+{
+  "state": { "screenshot": "frame-6e1d0b7c" },
+  "assets": {
+    "frame-6e1d0b7c": { "type": "image", "format": "png", "data_base64": "<base64 image bytes>" }
+  },
+  "questions": {
+    "visible": { "type": "noul", "instructions": "Is the target visible in `screenshot`?" },
+    "target": { "type": "box", "instructions": "the target in `screenshot`" }
+  }
+}
+```
+
+Use real standard base64, with padding and no whitespace or `data:` prefix. Only inline PNG/JPG/JPEG still images are supported; the adapter never fetches files or URLs. Each asset reference must occur in a string value in `state`, question `instructions`, or `criteria`. Prefer unique references: upstream replaces plain-text matches, including mid-sentence matches, but never object keys. Put a shared image in state once; repeated references expand the image repeatedly upstream.
+
+`normalizeImageAssets(assets)` returns a canonical map (or `{}` when omitted) and rejects invalid map entries, references, base64, format signatures, truncated headers, animated PNGs, and local bounds. Local limits follow the [official image contract](https://docs.typesafe.ai/images): 16 MiB decoded per image, 32 MiB serialized request body, references at most 1,024 UTF-8 bytes each and 65,536 bytes total, width/height 256–1568 pixels each, and at least 78,400 pixels. No artificial image-count or 4 MB proxy limit is imposed. Header inspection is not a complete image decoder: upstream still validates image integrity and its processed/expanded 32 MiB limits. Images are never silently resized.
+
+Direct TypeSafe adds `TypeSafe-Danger-Zone-Images: true` for assets or [Box questions](https://docs.typesafe.ai/primitives/box), without an extra environment switch. These upstream surfaces are experimental. Box requires Jev 1.14 and returns normalized edges plus confidence, even when the target is absent; pair it with Noul (`answer.noul`, not a confidence field) before grounding an action. Hosts retain approval, execution, and screenshot-to-desktop/DPI/crop mapping.
+
+OpenRouter uses the [Multimodal Decisions format](https://openrouter.ai/docs/guides/community/multimodal-decisions): `{ "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }` parts in `state`, question instructions or criteria. The adapter expands layer asset references into these parts, including references inside longer strings, without replacing object keys or changing question types. PNG remains `image/png`; JPG/JPEG use `image/jpeg`. It does **not** send TypeSafe's top-level `assets` field to OpenRouter. No extra vision flag or direct TypeSafe key is needed.
+
+Live checks on October 15, 2026 against `/api/alpha/decisions` resolved `typesafe/jev-1.14-20261014`: solid-red and solid-blue images were each classified correctly with confidence 1. A screenshot-only red rectangle was grounded through the actual MCP computer tool at `(200, 148)` inside the known rectangle, with visibility 0.97 and Box confidence 0.98; the response required host confirmation and no desktop action was executed. Earlier probes using TypeSafe assets/references with OpenRouter returned `unknown` because they used the wrong image input format; they do not establish lack of OpenRouter vision support.
+
+For Windows PowerShell, with `OPENROUTER_API_KEY` already supplied by your secret store:
+
+```powershell
+$env:JEV_LAYER_PROVIDER = "openrouter"
+$env:OPENROUTER_DECISIONS_MODEL = "typesafe/jev-1.14"
+$env:JEV_COMPUTER_USE = "1"
+npm run mcp
+```
+
+Restart an already-running MCP server after updating the source/environment. Vision is used when the host supplies `observation.screenshot` to `jev_computer_step`/`jev_browser_step`, or `assets` to `jev_route`; the layer does not capture the screen itself. `JEV_COMPUTER_USE` opts into desktop advice, not image input generally. Browser advice still requires its own enabled setting.
+
+Missing credentials, unsupported image providers, timeouts, HTTP errors, and rejected images fail open through the host's existing caller error path; no retries or autonomous computer executor are added. Image-path transport, HTTP-body, and invalid-JSON error details are redacted so an upstream echo of base64 cannot enter durable error receipts.
+
+## Select a provider
+
+For a stdio MCP process, export the selected provider's API key through your secret store into the harness environment, then choose one command:
+
+```sh
+JEV_LAYER_PROVIDER=demo jev mcp
+JEV_LAYER_PROVIDER=openrouter jev mcp
+JEV_LAYER_PROVIDER=typesafe jev mcp
+```
+
+For a single CLI request from the repository root:
+
+```sh
+jev cli --provider demo --input examples/route-request.json
+jev cli --provider openrouter --input examples/route-request.json
+jev cli --provider typesafe --input examples/route-request.json
+```
+
+Selection precedence is: request `provider` → CLI `--provider` (CLI only) → `JEV_LAYER_PROVIDER` → `.jev/config.json` `provider` → `demo`. MCP launcher `env` entries count as process environment; update them when switching providers. Hermes and OMP delegate this choice to the CLI instead of forcing `demo`. The Hermes adapter's default process timeout is 10 seconds, allowing either provider's HTTP timeout to complete; `JEV_LAYER_TIMEOUT_S` overrides it.
+
+`jev add <harness> --provider typesafe` generates configuration for TypeSafe in the target workspace. Use `--provider openrouter` or `--provider demo` for the other modes. Keep keys outside generated configuration.
+
+## Endpoints, models, and custom environment names
+
+- TypeSafe: `TYPESAFE_ENDPOINT`, `TYPESAFE_MODEL`.
+- OpenRouter: `OPENROUTER_DECISIONS_ENDPOINT`, `OPENROUTER_DECISIONS_MODEL`; optional attribution headers use `OPENROUTER_HTTP_REFERER` and `OPENROUTER_APP_TITLE`.
+- Endpoints are complete request URLs, including `/v1/systemone` or `/api/alpha/decisions`.
+- Default HTTP timeouts are 2 seconds for TypeSafe and 5 seconds for OpenRouter. There are no provider retries; failures return control to the host.
+
+The CLI and MCP read `.jev/config.json` from their working directory. `JEV_CONFIG` selects another file. To use secret-store-specific environment names, set only their names in the config:
+
+```json
+{
+  "provider": "typesafe",
+  "providers": {
+    "typesafe": {
+      "api_key_env": "MY_TYPESAFE_KEY",
+      "endpoint_env": "MY_TYPESAFE_ENDPOINT",
+      "model_env": "MY_TYPESAFE_MODEL"
+    }
+  }
+}
+```
+
+Omitted fields retain the default environment names. A missing configured key returns `fallback` without an HTTP call, even if `TYPESAFE_API_KEY` is set. The same mapping is supported under `providers.openrouter`.
+
+## Verification
+
+`jev doctor` checks configuration and key presence; it does not run inference or validate a key with the provider.
+
+```sh
+node --test test/providers.test.mjs test/provider-transports.test.mjs test/images.test.mjs
+```
+
+These offline checks cover all three provider selections, CLI/MCP precedence, custom environment names, Hermes/OMP transport, and fail-open behavior. Remote-provider requests use injected responses or a loopback HTTP server with fixture credentials. No paid inference, agent model, or real browser is invoked. Live provider/account availability requires a separately configured environment.