Grok Plugin Codex

grok-plugin-codex предоставляет локально установленный Grok CLI в Codex через встроенный Node/TypeScript MCP-сервер. Codex по-прежнему отвечает за область видимости, состояние рабочего пространства, верификацию, git и окончательное решение; Grok — это ограниченная вторая поверхность.

Версия 0.3.0 — текущий релиз. Она нормализует словарь причин остановки Grok (end_turn и EndTurn — одно и то же), корректно классифицирует тайм-ауты и исчерпание квот, по умолчанию запускает инструменты диспетчеризации в фоне с бюджетами времени для каждого вида, возвращает дескриптор восстановления для каждого неполного результата, отказывается сообщать о вынесенном решении без единого вызова инструмента как о завершенном обзоре, и добавляет grok_finalize — одношаговый способ без инструментов для восстановления уже существующего ответа. Полные изменения контракта см. в CHANGELOG.md. Версия 0.2 представила архитектуру приватного центрального рабочего процесса и типизированные MCP-конверты.

Репозиторий: https://github.com/handong66/grok-plugin-codex Статья: https://han-dong.link/en/work/grok-plugin-codex

Требования

• Node.js >=22

• npm

• macOS или Linux

• Поддержка локального плагина Codex marketplace

• Установленный и аутентифицированный Grok CLI

Проверьте три уровня среды выполнения отдельно:

grok --version   # CLI can be discovered
grok --help      # installed flags/capabilities
grok models      # authentication and model listing

Указанная модель не обязательно завершала реальный вызов. grok_check сохраняет это различие.

Related MCP server: chatgpt-codex-local-mcp

Установка

npm install
npm run check
codex plugin marketplace add .
codex plugin add grok-plugin-codex --marketplace grok-plugin-codex

Начните новую задачу Codex после установки или обновления. Существующие задачи сохраняют MCP-сервер и снимок навыка, с которыми они были запущены. Если новая задача Codex Desktop видит обновленный навык, но не обновленные MCP-инструменты, перезапустите Codex Desktop и создайте другую задачу; процесс Desktop может сохранять свой MCP-реестр после переустановки.

Установленный пакет содержит оба компонента:

plugins/grok-plugin-codex/dist/server.js
plugins/grok-plugin-codex/dist/job-worker.js

Поверхность возможностей

• grok_check, grok_models: диагностика CLI/возможностей, аутентификации, прав доступа и моделей. authenticated и entitled могут быть true, false или "unknown" — никогда null.

• grok_run, grok_continue: явное выполнение запросов и продолжение известных сессий.

• grok_finalize: один шаг, без инструментов, полный ответ — восстановление для прерванного по тайм-ауту, лимиту шагов, отменённого или заблокированного разрешениями выполнения.

• grok_rescue, grok_review, grok_adversarial_review: принудительно только для чтения, без подчинённых агентов второй проход. Каждому требуется target (или problem), для которого также принимается имя prompt родственного плагина. grok_adversarial_review принимает необязательный threatModel; выводы вне его рамок носят рекомендательный характер и могут не блокировать.

• grok_sessions, grok_export: просмотр сессий явного рабочего пространства и экспорт в Markdown.

• grok_status, grok_result, grok_cancel: жизненный цикл приватных центральных фоновых задач только по jobId. grok_status возвращает дешёвый прогресс (textChars, eventCounts, lastEventAt, toolCallCount, deniedToolCalls) и принимает необязательный waitMs (≤ 30 с) для ожидания на стороне сервера; grok_result разбивает finalText на страницы с помощью finalTextOffset / finalTextMaxChars.

Текущая схема MCP listTools является авторитетной для точных аргументов. Дымовой тест репозитория фиксирует опубликованную поверхность и отвергает отклонения.

Контракт результатов

Успешные операции возвращают:

{ "ok": true, "data": {}, "error": null, "warnings": [] }

Сбои бизнес-логики устанавливают MCP isError: true и возвращают:

{
  "ok": false,
  "data": null,
  "error": { "code": "typed_code", "message": "actionable message", "retryable": false },
  "warnings": []
}

Нарушения схемы входных данных — это ошибки инструмента, сгенерированные SDK (isError: true) без конверта бизнес-логики плагина; клиенты должны проверять разрешённый результат инструмента, а не полагаться только на отклонение обещания. Каждый инструмент публикует схему вывода, а JSON-текст, обработанный плагином, отражает structuredContent.

Границы рабочего пространства и запросов

Операции с рабочим пространством требуют cwd. Сервер канонизирует символические ссылки и требует, чтобы разрешённый каталог оставался внутри активного корня MCP-рабочего пространства. Приватные пути Codex, такие как ~/.codex, блокируются, если пользователь явно не разрешит этот риск.

Запросы временно размещаются в приватных файлах 0600, чтобы отсоединённый рабочий процесс мог пережить выход MCP-сервера. Рабочий процесс читает и удаляет файл размещения перед запуском Grok, затем передаёт запрос через FIFO 0600 внутри случайного каталога 0700. Grok получает только этот приватный путь через нативный --prompt-file; программа-загрузчик удаляет его, как только Grok открывает его, до записи любых байтов запроса. Текст запроса не помещается в список аргументов дочернего процесса или запись задания. GROK_BIN — единственная поддерживаемая конфигурация пользовательского исполняемого файла и должна поступать из доверенной среды MCP.

Фоновые задания

Фоновые задания выполняются в отсоединённом рабочем процессе и переживают перезапуски MCP-сервера. Состояние хранится в:

1. $GROK_PLUGIN_STATE_DIR, если явно настроено;

2. $XDG_STATE_HOME/grok-plugin-codex;

3. ~/.local/state/grok-plugin-codex.

Явный каталог состояния не должен пересекаться ни с одним активным корнем рабочего пространства: ни внутри корня, ни быть его предком. Он должен быть пустым, содержать маркер владения плагина или соответствовать строгой приватной предварительно помеченной структуре заданий; плагин не будет претендовать на существующий общий каталог или выполнять chmod. Эти проверки завершаются с ошибкой до создания или изменения состояния в репозитории.

Каталоги используют 0700; записи, журналы, файлы размещения запросов, маркеры отмены, пульс и межпроцессные блокировки маркера владельца используют 0600. Записи являются атомарными, а конечный статус — монотонным. Отмена линеаризуется маркером, потребляемым рабочим процессом-владельцем. Каждая группа процессов возглавляется приватным загрузчиком, чья команда идентификации включает ID задания и случайный токен задания; согласование зависшего рабочего процесса завершает сохранённую группу только при совпадении всех трёх, и загрузчик удаляет остаточные потомки перед выходом.

Инструменты диспетчеризации (grok_run, grok_review, grok_adversarial_review, grok_rescue) по умолчанию имеют background: true; grok_continue по умолчанию работает в переднем плане. Сохраните data.job.id, затем вызывайте инструменты задания с jobId. Вызов переднего плана (background: false) блокируется не более чем на timeoutMs плюс 10 с запас и затем возвращает foreground_wait_timeout с этим id задания. Пропущенный timeoutMs по умолчанию зависит от типа — для run/continue 180000, для review/rescue 240000, для adversarial_review 300000 — и явное значение никогда не зажимается ни в одну сторону; оба эффективных значения возвращаются как effectiveTimeoutMs / effectiveMaxTurns. Рекомендуемый ритм для фонового задания: один grok_status с waitMs, затем один grok_result, а не цикл опроса. Только эта комбинация является окончательной:

data.resultComplete === true

Внутренне полнота также требует непустого конечного текста и нормального события окончания, а для grok_review и grok_adversarial_review — хотя бы одного вызова инструмента, поскольку решение проверяющего, который ничего не открыл, — это мнение (no_evidence_review). Типы только для чтения работают в режиме плана, где выполнение оболочки автоматически отклоняется: встроите diff или вывод команды, необходимые для проверки, в цель, и запуск, который был отменён, потому что команда оболочки требовала одобрения, сообщается как permission_denied_headless, а не как цель, которая была слишком широкой. Причины остановки нормализуются без учёта регистра и разделителей (end_turn и EndTurn — одно и то же), необработанное значение сохраняется в outputSummary.stopReason, и вызывающие стороны не должны сопоставлять строки самостоятельно. Отменённый конец возвращается как cancelled_output. Неопознанная причина остановки после реального текста принимается с stopReasonRecognised: false и предупреждением вместо отбрасывания.

Каждый неполный результат содержит дескриптор восстановления — error.details.recovery для неудачного вызова переднего плана, data.recovery для grok_result — в виде { jobId, grokSessionId, partialTextChars, suggested: { tool: "grok_finalize", args }, fallback: { tool: "grok_continue", args } }. Дескриптор исполняем как есть: suggested — это одношаговое восстановление, а fallback — то же самое, выраженное для вызывающей стороны, которая работает только с grok_continue (maxTurns: 1 плюс запрос grok_finalize). Ни то, ни другое не требует сокращённого ответа. Средство для max_turns_reached и для отменённого или истекшего по тайм-ауту запуска — это grok_finalize с этим id задания, или тот же вызов вручную: продолжить ту же сессию с maxTurns: 1 и запросом, сообщающим Grok прекратить использовать инструменты и выдать окончательный ответ сейчас. Не сужайте цель, не увеличивайте maxTurns и не перезапускайте задачу — частичный ответ никогда не уничтожается, error.details.finalTextRef — это id задания, и grok_result возвращает полный захваченный текст независимо от resultComplete.

resultComplete сам учитывает усечение: outputTruncated означает только переполнение общего окна захвата, что обычно является эхом вызова инструмента, тогда как textTruncated означает, что текст ответа был отброшен, и это флаг, который блокирует полноту. Чрезмерно большие полезные нагрузки инструментов усекаются во время захвата, а полезные нагрузки available_commands отбрасываются; установите GROK_PLUGIN_RAW_CAPTURE=1, чтобы сохранить поток поставщика дословно для разработки плагина.

Используйте data.finalText. Частичные состояния предназначены только для диагностики, а необработанные хвосты журнала для каждого токена возвращаются только при вызове grok_result с includeRawTail: true. Рабочий процесс хранит ответ в реестре добавления <id>.final.txt и факты потока в <id>.summary.json, поэтому grok_result отвечает из этого реестра вместо повторного анализа необработанного потока, а grok_status читает прогресс из того же файла. Артефакты завершённых заданий хранятся в течение семи дней и очищаются по возможности.

Обновление с версии 0.1

• Завершите или отмените фоновые задания 0.1 перед обновлением.

• 0.2 не сканирует и не доверяет старым записям <workspace>/.grok-plugin-codex/jobs.

• Старые каталоги рабочего пространства не удаляются автоматически, поскольку они принадлежат рабочему пространству пользователя.

• Удалены: выбор исполняемого файла для каждого вызова, файлы экспорта, выбранные вызывающей стороной, неявные цели проверки и cwd управления заданиями.

Граница конфиденциальности

Плагин не копирует скрытый контекст Codex, системные/разработческие сообщения, рассуждения, произвольный вывод инструментов, секреты или учётные данные в запросы. Он не может редактировать конфиденциальный текст, который вызывающая сторона явно предоставила. См. docs/privacy.md.

Разработка

npm install
npm run check
git diff --check

Необязательный аутентифицированный вызов:

npm run smoke:live-grok

Схемы времени выполнения и тесты являются авторитетными. Встроенные файлы README/навыка — это контракт пользователя; test/contract-drift.test.ts и дымовой MCP-тест предотвращают повторное появление удалённых аргументов или несоответствующих версий.

См. docs/development.md и docs/verification.md.

Политики проекта

• Политика конфиденциальности

• Условия использования

• Политика безопасности

• Участие