hierarchical-codex

hierarchical-codex — это детерминированная управляющая плоскость MCP для нативных субагентов Codex. Codex по-прежнему создаёт видимые в UI потоки Sol → Terra → Luna через spawn_agent; этот проект предоставляет долговременное состояние, политические ограничения, бюджеты, артефакты, рабочий процесс доказательств и протокол восстановления вокруг этих потоков.

Статус: инженерный MVP. Управляющая плоскость, интеграция с проектом Codex, хуки, тесты и эксплуатационная документация реализованы. Проверяйте доступность моделей и точную версию ядра Codex в каждом целевом развёртывании App/IDE.

Выбор дизайна

Проект следует одному явному маршруту:

Управление порождением через модель; ограничения, применяемые кодом.

Codex native execution plane
  spawn_agent / wait_agent / send_message / Subagents UI
                  |
                  | task_id in TaskEnvelope
                  v
TypeScript MCP control plane
  SQLite task ledger / leases / budgets / artifacts / evidence / audit
                  ^
                  |
Codex Skills + Profiles + Hooks
  orchestration policy / model-effort routing / spawn veto / stop checks

MCP и хуки не создают нативные потоки. Модель Sol или Terra вызывает нативный spawn_agent; код проверяет и фиксирует окружающий рабочий процесс.

Related MCP server: dingdawg-governance

Реализованные возможности

• Реестры миссий и задач с оптимистичными версиями.

• Политика ролей прямого родителя: директор Sol → координатор Terra → лист Luna.

• Матрица модель/усилие:

  • Sol: high, xhigh, max

  • Terra: xhigh, max

  • Luna: high, xhigh, max

• Готовность с учётом зависимостей и ограниченное выделение дочерних элементов.

• Истекающие аренды рабочих, пульс, освобождение и безопасное восстановление.

• Иерархические бюджеты токенов, затрат, времени стены, вызовов инструментов и количества дочерних элементов.

• Хранилище артефактов с адресацией по содержимому и ограниченным чтением.

• Ворота доказательств: кандидат → проверено → подтверждено → зафиксировано.

• Разделение производителя/проверяющего.

• Идемпотентные мутации с хешированием запросов и события аудита только на добавление.

• Снимки восстановления после перезапуска или сжатия контекста.

• Скилл Codex, профили агентов, конфигурация MCP и хуки в рамках проекта.

Требования

• Node.js 22.5 или новее. В разработке используется Node 26.

• Python 3.10 или новее для хуков жизненного цикла Codex.

• Codex 0.148.0 или новее — рекомендуемая производственная базовая линия, с нативными инструментами мультиагентности, пользовательскими агентами, MCP и хуками.

• Доверенный проект Codex, чтобы загружались .codex/config.toml и хуки проекта.

Быстрый старт

cd "/mnt/tools/others/codes/web project/hierarchical-codex"
npm install
npm run check
npm run doctor

Затем:

1. Откройте корень этого репозитория в Codex App, Codex CLI или расширении Codex для VS Code. npm run doctor не устанавливает скилл в ChatGPT; App должен использовать эту папку как рабочую область.

2. Доверьтесь проекту при запросе. Непроверенные проекты скрывают скиллы .codex.

3. Начните новый корневой разговор с gpt-5.6-sol (скиллы загружаются при запуске).

4. Введите $ и выберите prism, или вызовите $prism <mission>. Если выбор пуст, AGENTS.md всё равно инструктирует корневой Sol.

5. Проверяйте нативную активность дочерних элементов в UI Subagents и долговременное состояние через инструменты MCP.

Чтобы использовать полный стек из других папок в расширении VS Code Codex или CLI, выполните npm run install:user после npm run build. См. docs/USER_INSTALL.md. Не копируйте .codex/config.toml этого репозитория в ~/.codex; это закрепит Sol как модель по умолчанию и заблокирует обычные субагенты.

Конфигурация MCP проекта запускает node dist/cli.js с корнем репозитория в качестве рабочего каталога. Выполняйте npm run build после изменений исходного кода.

Команды разработки

npm run dev          # Run the stdio MCP server from TypeScript
npm run doctor       # Validate runtime and Codex integration files
npm run test         # Unit and integration tests
npm run typecheck    # Strict TypeScript checks
npm run lint         # ESLint
npm run format       # Prettier
npm run build        # Compile dist/
npm run check          # Full local quality gate
npm run install:user   # Install skill, agents, hooks, and MCP into ~/.codex
npm run doctor:user    # Verify the user-global install
npm run uninstall:user # Remove the managed user-global files

Сервер MCP записывает сообщения протокола в stdout. Логирование приложения должно использовать stderr; логирование в stdout повреждает транспорт MCP stdio.

Состояние выполнения

По умолчанию состояние локально для проекта и игнорируется Git:

.hierarchical-codex/
├── control-plane.sqlite
└── artifacts/
    └── <sha-prefix>/<sha256>

Пользовательская глобальная установка (npm run install:user) хранит реестр в ~/.local/share/hierarchical-codex/, чтобы песочницы MCP Codex могли записывать его. Если этот каталог недоступен для записи, сервер переключается на временный путь и записывает выбранный дом в stderr.

Переменные окружения конфигурации:

• HIERARCHICAL_CODEX_HOME

• HIERARCHICAL_CODEX_DB

• HIERARCHICAL_CODEX_ARTIFACTS

• HIERARCHICAL_CODEX_MAX_ARTIFACT_BYTES

• HIERARCHICAL_CODEX_DEFAULT_LEASE_SECONDS

• HIERARCHICAL_CODEX_MAX_LEASE_SECONDS

• HIERARCHICAL_CODEX_EVENT_PAGE_SIZE

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

Миссия:

• mission_create

• mission_get

• mission_close

Задача и аренда:

• task_allocate

• task_get

• task_claim

• task_start

• task_heartbeat

• task_release

• task_block

• task_fail

• task_cancel

• task_supersede

• task_set_effort

• task_commit

Артефакты и доказательства:

• artifact_put

• artifact_get

• result_submit_candidate

• result_check

• result_verify

Учёт и восстановление:

• budget_report

• recovery_snapshot

См. docs/API.md для контрактов и docs/PROTOCOL.md для последовательности оркестрации.

Структура репозитория

.agents/skills/             Codex orchestration Skill
.codex/agents/              Sol/Terra/Luna custom profiles
.codex/hooks/               Python policy gates
.codex/config.toml          MCP and native agent configuration
src/domain/                 State and policy definitions
src/infra/                  SQLite repository and artifact storage
src/mcp/                    MCP tool registration
tests/                      Control-plane, policy, and hook tests
docs/                       Architecture, protocol, operations, ADRs, records

Важные границы

• Внешний код MCP не может вызывать внутренний нативный реестр spawn_agent.

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

• Нативное состояние UI является наблюдательным; SQLite — источник долговременного рабочего процесса.

• Этот MVP однопользовательский. SQLite сериализует мутации, но не является распределённой системой консенсуса.

• Использование токенов сообщается агентами/хостами; сервер MCP не может независимо измерять токены модели.

• Репозиторий в настоящее время UNLICENSED; добавьте явную лицензию перед внешним распространением.

Документация

• Архитектура

• Протокол

• MCP API

• Интеграция Codex

• Пользовательская глобальная установка VS Code / CLI

• Эксплуатация

• Модель безопасности

• Руководство разработчика

• Стратегия тестирования

• Дорожная карта

• Журнал изменений

• Запись реализации

• Архитектурные решения