# Jev Answer Check

Локальная проверка ответов Codex и Claude Code по общей русскоязычной рубрике.
Агент готовит черновик, MCP отправляет его TypeSafe Jev, агент исправляет явные
замечания один раз и повторно проверяет результат. Видео и публикация материалов
в этот пакет не входят.

## Из чего состоит

- `skills/clear-report/` — ясный русский по принципам plain language
  (ISO 24495-1), выбор текста, схемы, таблицы, графика или HTML.
- `src/mcp.mjs` — один инструмент `jev_check_answer` на официальном MCP SDK.
- `src/hook.mjs` — адаптеры `UserPromptSubmit` и `Stop` для обоих агентов.
- `src/runtime.mjs` — общая рубрика, TypeSafe API, приватный контекст,
  журнал оценок, редактирование секретов и лимиты.
- `scripts/install.py` — установка с резервными копиями и сохранением других
  MCP, hooks и настроек.

MCP-сервер — собственная реализация этого проекта, а не официальный сервер
TypeSafe. Используются официальный MCP SDK и официальный API TypeSafe.
Нет автоматической установки сторонних MCP через `npx ...@latest`.

## Установка

Требуются Node.js 22+, npm и Python 3.11+. Установленные Codex / Claude Code
и ключ TypeSafe нужны для настоящих проверок.

```sh
npm ci --ignore-scripts
npm test
python3 scripts/install.py --hosts codex claude --enable --key-source /path/to/private/key-file
```

`--key-source` принимает путь к уже существующему файлу ключа, не само значение.
Ключ копируется в `~/.config/jev-answer-check/api-key` с правами `0600`.
Его нельзя добавлять в Git, аргументы shell-команд, промпт или MCP-конфигурацию.
Можно вместо файла предоставить `TYPESAFE_API_KEY` через существующее хранилище
секретов и окружение процесса. Не сохраняйте реальное значение в README или `.env`.

После установки откройте новую сессию. Codex CLI и Desktop используют MCP
одного host. В Claude Code потребуется рабочая авторизация модели.

**Доверие hooks Codex:** новые hooks нужно проверить и разрешить через `/hooks`.
До этого Codex может пропускать их. MCP доступен независимо от hook: при отсутствии
контекста агент передает `last_user_message`, сервер создает ограниченный контекст.
Этот запасной режим не доказывает наличие Stop-страховки.
Без hook одинаковый повторный запрос использует прежний лимит; сервер не может
надежно отличить отдельные ходы по одному тексту сообщения.

## Как идет проверка

1. Hook сохраняет очищенный последний запрос и передает агенту `session_id`.
2. Агент передает MCP `task_summary`, `draft`, текстовые `artifacts` и `evidence`.
3. Сервер читает одну общую рубрику из пакета и вызывает закрепленную
   `jev-1.13.0` через `https://api.typesafe.ai/v1/systemone`.
4. Ответ по каждому применимому критерию — вероятность «да».
   Явный провал дает `rewrite`, неопределенность — `uncertain`, остальные — `keep`.
5. Агент исправляет текст и материалы; Jev сам их не генерирует.
6. Повторная оценка разрешена один раз. Неудачная оценка и превышение лимита
   никогда не называются успешной проверкой.

Проверяются восемь критериев: закрытие запроса, ясный русский, отсутствие воды,
видимый итог и ограничения, практическая польза, точные статусы, подходящая
форма и верность данных/связей. Короткое приветствие не требует проверки.

Stop-hook — дополнительная страховка: он может попросить продолжение, когда
финальная версия не имеет оценки. Первая версия уже могла появиться в UI.
Это не жесткий скрытый шлюз перед отображением. Основной вызов MCP должен
происходить до финального сообщения. Guard возобновляет ход максимум один раз.
При сравнении текста игнорируется служебный блок `<oai-mem-citation>`:
Codex удаляет его перед передачей ответа Stop-hook. Содержательная правка
ответа по-прежнему требует новой оценки.

## Данные и пределы

- Передаются актуальное задание, последний запрос, черновик, рубрика и только
  добавленные текстовые материалы/свидетельства; полный транскрипт не отправляется.
- Jev принимает текст. Ссылка или скриншот сами по себе не дают ему содержание
  HTML и не подтверждают качество отображения.
- Реально выполненные команды не доказываются одним текстом ответа.
- Из данных удаляются известный ключ и распространенные форматы токенов,
  паролей и приватных ключей. Универсальное удаление всех секретов не гарантируется.
- Контекст хранится локально в приватном state. В receipts сохраняются хеши,
  оценки и стоимость, без текста запросов, черновиков и ключей.
- Сервер — локальный процесс с правами пользователя; MCP не является sandbox.
  Он не предоставляет инструментов исполнения команд или чтения произвольных
  путей. Адрес API закреплен, перенаправления запрещены.

Настройки находятся в `~/.config/jev-answer-check/config.json`, состояние — в
`~/.local/state/jev-answer-check/`. Установка выключена без явного `--enable`.
Начальные лимиты: $0.05 в день UTC, максимум две оценки одного turn,
200 вызовов в день, резерв $0.004 на запрос. При ошибке лимиты не расходуются
повторными автоматическими retry; непригодный результат остается `unverified`.
Резерв при ошибке не возвращается; автоматических API-повторов нет.
Расчет цены закреплен за Jev 1.13 ($0.042 / миллион входных токенов); при смене
модели/тарифа нужно обновить его. Это лимиты данного пакета, не всех сервисов аккаунта.
Допуск следующего запроса учитывает большую из зарезервированной и фактической
сумм. Резерв оценивается до вызова, а точная стоимость доступна после него;
это локальный предохранитель, не гарантированный лимит списаний провайдера.

## Проверки и публикация

```sh
npm test
npm audit --omit=dev --audit-level=high
npm run scan
```

Сканер проверяет дерево проекта и распакованные Git blobs, включая удаленные
файлы в истории. При наличии локального ключа проверяет и его точное значение.
Для независимой проверки можно передать `JEV_SCAN_KEY_FILE`; содержимое ключа
никогда не печатается. Скрипт сообщает только имена подозрительных файлов.

Первый пилот: пять заданных синтетических черновиков в настоящем Codex CLI,
пять вызовов Jev, решения совпали с заранее записанными ожиданиями; стоимость
TypeSafe $0.00134799. Исправления написал Codex, повторная оценка в том пилоте
не выполнялась. Это иллюстрация поведения, не оценка общей точности.

## Источники

- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [TypeSafe API](https://docs.typesafe.ai/api)
- [Codex MCP](https://developers.openai.com/codex/mcp)
- [Codex hooks](https://developers.openai.com/codex/hooks/)
- [Claude Code MCP](https://code.claude.com/docs/en/mcp)
- [Claude Code hooks](https://code.claude.com/docs/en/hooks)

SDK, API и hooks сверены через Context7 и официальные источники. При расхождении
примеров приоритет имеют актуальный официальный API и проверенный wire format.
Текст рубрики — собственная адаптация, не полный текст ISO и не сертификация.