# Codex Oracle Kit

MCP-комплект для Codex: локальный preview → делегирование в ChatGPT через Chrome → proposed → локальная проверка → явный accept. Ответ модели — данные, не исполняемый код. API fallback отсутствует. CodexPro и другие навыки не нужны.

## Быстрый старт через Codex

Откройте в Codex проект, с которым хотите работать, и отправьте:

```text
Установи https://github.com/born2be4/codex-oracle-kit по README для текущего проекта.
Проверь Node.js 24+, настрой MCP и навык oracle-delegate, сохрани остальные настройки.
Проведи локальную проверку без отправки файлов в ChatGPT.
Затем помоги мне войти в мой аккаунт ChatGPT для работы через Oracle.
```

После настройки задачи ставятся в Codex. При первом подключении потребуется личный вход в ChatGPT; Chrome может открывать видимое окно. Проверка полноценного браузерного запроса выполняется на вашем аккаунте отдельно от локальных тестов.

## Установка из Git, без публикации npm

Требуются Node.js >=24, npm, Git, установленный Codex CLI и Google Chrome. Native Windows/macOS/Linux desktop; WSL Windows bridge не поддерживается в Kit v1. Проверки и ограничения: [docs/verification.md](docs/verification.md).

```sh
git clone https://github.com/born2be4/codex-oracle-kit.git
cd codex-oracle-kit
npm ci
npm test
npm link
codex-oracle-kit init --project "/absolute/path/to/your-project"
codex-oracle-kit doctor --project "/absolute/path/to/your-project"
codex-oracle-kit setup --project "/absolute/path/to/your-project"
```

В Windows используйте, например, `C:/work/my-project`. `setup` вызывает `codex mcp list --json`, затем `codex mcp add oracle-kit -- <node> <absolute-cok.js> serve --project <path>`. Чужие записи не редактируются, существующая oracle-kit не заменяется. Windows автоматически разрешает native `codex.exe` либо соседний с PATH shim `codex.cmd` известный `node_modules/@openai/codex/bin/codex.js`, запускаемый через Node без shell. Содержимое .cmd не читается и не исполняется. Неизвестная установка вызывает отказ. PATH должен содержать доверенные каталоги программ; одновременный setup нескольких процессов не поддерживается.

`setup` устанавливает навык в `.agents/skills/oracle-delegate/SKILL.md` выбранного проекта. Совпадающий файл оставляется, отличающийся не перезаписывается; конфликт обнаруживается до изменения MCP. Отдельная установка без изменения конфигурации Codex:

```sh
codex-oracle-kit skill-install --project "/absolute/path/to/your-project"
```

Если `codex mcp add` завершился ошибкой, установленный навык остаётся; исправьте причину и повторите setup. Перезапустите Codex после регистрации/установки навыка. Подключение имеет одно имя oracle-kit; для нескольких проектов регистрируйте вручную разные имена. Папку установки после npm link не перемещайте. Без глобального link: `node /absolute/path/to/kit/src/bin/cok.js`.

## Конфигурация проекта и личный вход

`init` сохраняет `.oracle-kit/config.json`, добавляет `.oracle-kit/` и `.supersily/` в `.gitignore`, не меняя существующие правила. Пример локальной конфигурации:

```json
{
  "model": "gpt-5.5",
  "chatgptUrl": "https://chatgpt.com/",
  "memory": ["docs/project-memory.md"],
  "ttlMs": 86400000
}
```

`memory` — ссылки на уже существующую каноническую память проекта, без дубликатов. По умолчанию список пуст. Не перечисляйте секретные разделы. `browserModelLabel` необязателен и задаёт UI label; `chatgptUrl` допускает ваш ChatGPT Project URL на https://chatgpt.com без query/hash. Выберите доступную аккаунту gpt-модель: Pro не требуется, но gpt-5.5-pro/gpt-5.6-sol допустимы в конфигурации. Фактическая доступность определяется ChatGPT.

Config перечитывается перед preview/delegate/accept, перезапуск serve не требуется. Job использует свой снимок config, а не настройки, изменённые во время ожидания. Перед следующей job при изменении config upstream MCP client пересоздаётся. Невалидный config вызывает отказ; старый config молча не используется. Изменение контекста блокирует accept прежней job.

Каждому пользователю нужен личный login в отдельном Chrome-профиле `.oracle-kit/oracle/browser-profile`. Kit не читает cookies обычного профиля и не синхронизирует их. Первоначальный вход делайте сами. Следующая команда реально отправляет `HI`, поэтому НЕ является offline-проверкой. Из папки установки, Linux/macOS:

```sh
ORACLE_HOME_DIR="/absolute/project/.oracle-kit/oracle" node node_modules/@steipete/oracle/dist/bin/oracle-cli.js --engine browser --model gpt-5.5 --browser-manual-login --browser-manual-login-profile-dir "/absolute/project/.oracle-kit/oracle/browser-profile" --browser-keep-browser -p "HI"
```

PowerShell:

```powershell
$env:ORACLE_HOME_DIR = "C:/work/project/.oracle-kit/oracle"
node node_modules/@steipete/oracle/dist/bin/oracle-cli.js --engine browser --model gpt-5.5 --browser-manual-login --browser-manual-login-profile-dir "C:/work/project/.oracle-kit/oracle/browser-profile" --browser-keep-browser -p "HI"
Remove-Item Env:ORACLE_HOME_DIR
```

Закройте использованный профиль перед делегированием, чтобы избежать конфликта Chrome. Окно Chrome может быть видимым. Не обходите тарифные ограничения и правила сервиса. Kit не гарантирует доступность модели/страницы и не выполняет вход автоматически.

## Инструменты MCP

- `preview({prompt, files})`: локальные пути, размеры, memory, модель, URL и SHA256. Нет внешнего запроса или запуска Oracle. Проверяйте содержимое файлов самостоятельно.
- `delegate({prompt, files, force?})`: повторная проверка контекста, немедленный id. Только явные UTF-8 файлы: до 30, по 256 KiB, суммарно с prompt/memory 512 KiB. Ни glob, ни весь cwd не отправляются. Проверенный снимок передаётся inline в prompt; upstream `files` всегда пуст.
- `result({id, waitMs?})`: running/proposed/accepted/error/incomplete, первые 1500 символов полного журнала и абсолютный fullPath. `waitMs` — целое 0..45000, по умолчанию 0. Ожидание возвращается при завершении job либо по лимиту, не отменяет и не повторяет запрос. Для `waitMs:45000` задайте MCP timeout не менее 60 секунд.
- `accept({id, confirm:true})`: только после проверки полного ответа и локальных тестов. Возможен после рестарта, если контекст и hash результата прежние. Повторный accept не продлевает TTL.

Пример: `preview({"prompt":"Проверь дизайн; не меняй файлы", "files":["docs/design.md"]})`, затем такой же delegate. Ждите через `result({id, waitMs:45000})`, не создавайте повторную job. Upstream wait идёт в фоне 20-секундными отрезками. Лимит наблюдения — 2 часа; timeout не отменяет detached Oracle.

Полный upstream session log сохраняется без обрезания в `.oracle-kit/jobs/<id>.txt`; он включает служебные строки Oracle. Summary — фрагмент, не LLM-резюме. Бинарные вложения не являются результатом v1. Журналы свыше 128 MiB сохраняются, но result/accept их отклоняют.

Кэш только accepted. SHA256 включает prompt, exact bytes/пути файлов и памяти, нормализованный config, engine и Oracle version. TTL от accept, force обходит кэш. Ошибки/partial/incomplete не принимаются. Изменения удалённых ChatGPT Project sources не обнаруживаются локальным hash: используйте force.

После crash: `codex-oracle-kit recover --project <path>`. Удаление lock разрешено только при подтверждённо отсутствующем PID того же host/ОС/владельца. Живой PID и неопределённость означают отказ. Следующий serve помечает running как incomplete без повторной отправки. Detached Oracle может продолжать работу — сначала проверьте его вручную. Legacy lock и аварийный guard: см. [troubleshooting](docs/troubleshooting.md).

## Зависимости и безопасность

Fork: https://github.com/born2be4/oracle . Runtime устанавливает НЕ fork, а оригинальный npm `@steipete/oracle@0.21.1` от https://github.com/steipete/oracle . Контракт проверен по опубликованному dist; GitHub main может отличаться. Обновление требует пересмотра тестов. MIT; см. THIRD_PARTY_NOTICES.md.

`npm test` включает настоящий SDK handshake/listTools и consult dryRun без браузера. `doctor` не проверяет login/Chrome UI/тариф. `npm pack --dry-run` показывает публичный состав. [SECURITY](SECURITY.md), [verification](docs/verification.md), [WSL ограничения](docs/wsl-bridge.md). Живой ChatGPT не проверялся.

## EN quickstart

Install Node >=24, Git, Codex CLI and Google Chrome. Clone this repository, run `npm ci && npm test && npm link`, then `codex-oracle-kit init --project <absolute-project>`, `doctor --project <absolute-project>` and `setup --project <absolute-project>`. Setup installs the project skill under `.agents/skills/oracle-delegate/SKILL.md` without overwriting existing content. Windows supports native codex.exe and the known npm codex.cmd JS entry without a shell. Restart Codex.

Sign into ChatGPT yourself using the dedicated project Chrome profile above. A visible browser window is expected; Pro is not mandatory. Configure an available model, optional ChatGPT Project URL and canonical memory paths in `.oracle-kit/config.json`. Configuration reloads per operation; jobs retain their own snapshots. Preview, delegate once, wait with `result({id,waitMs:45000})` (MCP timeout >=60s), inspect the full transcript, verify locally, then explicitly accept. Only accepted results enter the TTL cache. No API fallback or automatic execution. Use `recover --project` after a crash; a live writer lock is never removed. Live ChatGPT is untested. WSL Windows bridge is unsupported in v1.