Консультант

Консультант — независимая экспертная модель, которая анализирует задачу воркера и возвращает рекомендации. Консультацией владеет OpenCodex от начала до конца: прокси внедряет синтетический инструмент advisor в ход воркера, сам выполняет консультацию через штатный маршрутизирующий механизм и возвращает рекомендацию, чтобы исходный воркер продолжил работу. Воркеру не нужно делегировать, spawn-ить что-либо или держать провайдерские учётные данные.

Это отличается от поверхности сабагентов (см. Конфигурацию агентов): сабагенты — это инициированная воркером делегация через инструменты совместной работы Codex. Консультант — прокси-sidecar, невидимый для клиента: даже воркер, который никогда ничего не spawn-ит, может получить совет.

Конфигурация

На странице Advisor выберите модель из каталога. Селектор сохраняет точные идентификаторы нативных моделей, провайдеров, аккаунтов, пользовательских моделей и combo. Отключённые модели и модели, ожидающие начального выбора, не предлагаются. Сохранённый идентификатор вне доступного списка остаётся видимым с предупреждением до замены или очистки. Ошибка загрузки сохраняет выбор и позволяет повторить попытку. Выберите модель для текстовых советов: каталог не гарантирует совместимость консультаций. CLI и API по-прежнему принимают строки моделей, поддерживаемые маршрутизатором.

{
  "advisor": {
    "enabled": true,
    "model": "gpt-6-astra",
    "effort": "max",
    "policy": "preflight",
    "contextSharingConsent": "v1"
  }
}

Поле	Тип	По умолчанию	Значение
enabled?	boolean	false	Главный выключатель. Выключено — ноль поведения консультанта на пути запроса.
model?	string	—	Экспертная модель. Любая строка модели, которую принимает роутер: «голая» нативная модель (gpt-6-astra), явный provider/model (anthropic/claude-sonnet-4-6, xai/grok-...) или модель с квалификацией аккаунта. Полная поддержка межпровайдерных сценариев.
effort?	string	"max"	Интенсивность рассуждений вызова консультанта (low–ultra).
policy?	"manual" | "preflight" | "adaptive"	"manual"	Когда консультировать.
maxConsultationsPerTask?	integer	3	Бюджет адаптивной задачи: 1–3 попытки, включая ручные вызовы.
timeoutMs?	number	120000	Тайм-аут loopback-консультации.
contextSharingConsent?	"v1"	нет	Согласие оператора отправлять контекст задачи настроенному провайдеру консультанта. Текущая версия только "v1". Отсутствие, устаревшее или иное значение означает, что содержимое задачи не отправляется. enabled: true само по себе не согласие.

Управляйте через страницу Advisor на дашборде или ocx advisor status|on|off|set --model <model> --effort <effort> --policy <manual|preflight|adaptive>.

Без текущего согласия ocx advisor on не включает межпровайдерную отправку: команда печатает раскрытие и останавливается. ocx advisor on --ack-context-sharing и ocx advisor consent записывают v1. ocx advisor consent --revoke снимает согласие и сразу прекращает отправку. ocx advisor set согласие не выдаёт. Флажок на дашборде изначально снят.

Политики

• manual — консультация только при явном вызове воркером синтетического инструмента advisor. Вызов перехватывается прокси, никогда не показывается клиенту и не исполняется как локальный инструмент.
• preflight — OpenCodex дополнительно автоматически пытается провести одну консультацию на задачу. Неудавшаяся консультация не считается советом: попытка повторяется после истечения записи о неудаче в реестре. После того как воркер получил первые свидетельства ориентации (вызов инструмента ассистентом ИЛИ результат инструмента после последнего сообщения пользователя), прокси консультируется с экспертом и вводит рекомендацию до следующего хода воркера — даже если воркер никогда не вызывает инструмент. Триггер — детерминированное, документированное приближение, а не семантический детектор «модель застряла».

Согласие

Содержимое задачи не отправляется, пока оператор не записал согласие на передачу контекста v1. Согласие версионировано: если раскрытие расширится, потребуется v2, а не повторное использование этого разрешения. Это проверяет runtime. Отсутствующее или устаревшее значение делает консультанта неисполняемым (advisor_context_sharing_consent_required) и не роняет запрос на написание кода. Ни воркер, ни модель консультанта, ни строка в тексте задачи не могут выдать согласие.

Что видит консультант

Консультация может отправить:

• последнюю просьбу пользователя
• текст пользователя, ассистента и разработчика, видимый в разобранной беседе
• вызовы инструментов и их аргументы
• результаты инструментов
• каталог инструментов воркера и описания
• идентификатор воркера и настроенную модель консультанта
• необязательный уточняющий вопрос, когда воркер вызывает advisor()

Настроенный провайдер консультанта может отличаться от провайдера воркера.

OpenCodex не вставляет в этот запрос ключи API провайдера, заголовки Authorization, токены OAuth, секреты конфигурации только для бэкенда, окружение процесса или скрытую цепочку рассуждений. Он не расшифровывает и не пересылает зашифрованное закрытое рассуждение провайдера. Содержимое задачи от секретов не очищается. Вставленный в задачу ключ, секрет в файле, который прочитали инструменты, или токен, напечатанный инструментом или журналом, может быть отправлен. OpenCodex не выполняет общий DLP.

Полномочия

Ручной совет — это результат инструмента для вызова advisor, который сделал сам воркер. Результат — объект JSON. Поле advice — текст модели консультанта. Поле status записывает runtime.

Автоматический совет передаётся как экранированный JSON в отдельном консультативном сообщении роли user. В developer остаётся только фиксированная инструкция runtime; сгенерированный консультантом текст никогда не попадает в developer/system. OpenAI Chat и Anthropic поддерживают это без выдуманного вызова инструмента. Экранирование предотвращает структурный выход и подделку полей, но не гарантирует защиту от инструкций на естественном языке. Отдельный протокол мог бы лучше отличать совет от запроса пользователя. На запрос разрешено не более трёх консультаций и четырёх продолжений воркера. При исчерпании консультаций инструмент advisor удаляется; повторный вызов получает одно последнее продолжение с результатом о лимите. Ещё один вызов завершает запрос с 502 advisor_continuation_limit без новой отправки. Повторы пустого завершения используют тот же лимит.

Подавление не читает строки консультанта. Автоматическая дедупликация принадлежит серверному журналу. Сообщение developer, даже скопировавшее текст транспорта, не подавляет preflight.

Стоимость и учёт

Каждая консультация — реальный дополнительный вызов модели. Она учитывается в использовании под моделью консультанта — никогда не сливается с токенами воркера — и пишет строку лога [advisor] с триггером, длительностью, статусом и использованием, так что вызов консультанта всегда можно доказать по логам.

Поведение при сбоях

Консультант отказывает открыто: при сбое уже отправленной консультации (модель недоступна, ошибка настройки, тайм-аут) воркер получает короткое, не вводящее в заблуждение уведомление «консультант недоступен» (сообщение <opencodex_advisor_unavailable> для preflight, ошибочный результат инструмента для manual) и продолжает задачу. Ничего не внедряется только при отмене консультации; при конфигурации без запуска (отключено, нет модели или нет текущего согласия на передачу контекста) preflight-уведомление тоже не отправляется. Ручной вызов advisor() без текущего согласия возвращает результат инструмента consent-required и ничего не отправляет. Сбой консультанта никогда не проваливает кодинг-запрос, а консультация никогда не переключает основную модель сессии.

Ограничения PR1

• Нативные passthrough-ходы OpenAI (воркеры пула ChatGPT) не получают синтетический инструмент; поддержка консультанта покрывает маршрутизируемых (переведённых) провайдеров. Preflight-консультация применяется к run-turn-адаптерам; инструмент — нет.
• Нет семантической детекции застревания, итоговой проверки, уровней эскалации, нескольких консультантов или голосования.
• Учётная книга дедупликации preflight живёт в процессе; после перезапуска прокси задача в работе может получить ещё одну preflight-консультацию.

Адаптивные консультации и журнал

adaptive добавляет к начальной консультации обращение после неудачного исправления: та же проверка в том же каталоге не проходит, последующее редактирование файла успешно завершается, а новая проверка снова не проходит. Успех снимает состояние сбоя; проверка, начатая до редактирования, не считается повтором после исправления. Начальный этап и этап исправления дедуплицируются отдельно. Для автоматики нужен стабильный идентификатор беседы. Нужны парные вызовы/результаты инструментов и явный код выхода. Сложные скрипты, пакеты вызовов, правки через shell и неоднозначный вывод не запускают консультацию.

Настройка: ocx advisor set --policy adaptive --max-consultations 2. Ручные и автоматические попытки делят бюджет 1–3 на задачу. До отправки сервер резервирует попытку в OPENCODEX_HOME/advisor-budget.sqlite; перезапуск и смена worker не сбрасывают счётчик. Хранятся только дайджесты задач, счётчики и сроки: 24 часа от первой попытки, максимум 512 задач. Если бюджет недоступен или исчерпан, worker продолжает. Уже отправленные ошибочные или отменённые вызовы не возвращают резерв, поскольку могли стоить денег. Без стабильного идентификатора остаются ручные вызовы с лимитом на запрос.

Страница Advisor и ocx advisor activity --json (GET /api/advisor/activity) показывают до 100 записей метаданных процесса за 24 часа. Видимая страница обновляется каждые пять секунд. Записи включают причину, статус, модели, время, сообщённые токены ввода/вывода, запрошенный и переданный адаптером уровни рассуждения. Текст задачи, команды, советы и идентификаторы беседы не хранятся; перезапуск очищает журнал. Значение адаптера описывает отправленный параметр, а не внутренние рассуждения провайдера. Отсутствующие данные остаются неизвестными; принятие советов и точная стоимость не выводятся.