jev-layer 0.1.0 → 0.2.0

package/docs/AGENT-IMPLEMENTATION.md

@@ -0,0 +1,250 @@
+# 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.
+
+## 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,15 @@
-# 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.

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

@@ -0,0 +1,177 @@
+# Hermes integration: handoff для локального агента
+
+Этот документ описывает **текущую рабочую интеграцию** `jev-layer` в Hermes. Он нужен локальному агенту, чтобы сначала понять границы и точки входа, а не повторно «интегрировать Jev» через глобальный конфиг, произвольные shell-команды или второй executor.
+
+## Что уже установлено
+
+- Исходный репозиторий: `/home/hermes/jev-layer`.
+- Активная plugin-копия Hermes: `~/.hermes/plugins/jev-layer`.
+- Plugin регистрирует ровно шесть tools:
+  - `jev_route`;
+  - `jev_record_execution`;
+  - `jev_supervise`;
+  - `jev_browser_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. Возвращает один 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_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,67 @@
+# 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.13` | `OPENROUTER_API_KEY` |
+| `typesafe` | `https://api.typesafe.ai/v1/systemone` | `jev-latest` | `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.
+
+## 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
+```
+
+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.