pi-subagent

Превращает Pi CLI (@earendil-works/pi-coding-agent) в программируемого суб-агента для написания кода, которому любой MCP-хост (ZCode, Claude Code, Cursor, …) может делегировать задачи, отслеживать сессии и завершать процессы.

pi-subagent — это тонкий MCP-сервер, который оборачивает pi -p --mode json в 7 структурированных инструментов: делегирование задач, сбор результатов, принятие решений о планировании, управление именованными сессиями и прерывание запусков. Изоляция на уровне процессов, полностью сессионная модель, синхронный/асинхронный режимы.

Зачем

Pi — это минималистичный терминальный агент для написания кода. Вместо того чтобы обучать Pi методологии, этот проект относится к Pi как к делегируемому работнику: агент-хост (ZCode / Claude Code) решает, когда делегировать задачу, запускает самодостаточную задачу и собирает результат. Один процесс Pi = один изолированный запуск суб-агента.

• Изоляция процессов — каждое делегирование порождает один дочерний процесс pi -p. Сбой Pi затрагивает только этот запуск.

• Полностью сессионная модель — каждая задача привязывается к именованной сессии (например, feat-auth); последующие вызовы автоматически продолжают её.

• Синхронный / асинхронный — по умолчанию async (позволяет избежать тайм-аутов вызовов инструментов со стороны хоста); сбор результата через long-poll pi_status.

• Планируемый — pi_plan — это чистая функция принятия решений из 5 этапов (reject / capacity / reuse / modify / mode), полностью покрытая модульными тестами.

• Универсальный MCP — любой стандартный MCP-клиент может его загрузить.

Related MCP server: cursor-agent-bridge

Архитектура

┌─────────────────────────────────────────────────────────────┐
│  MCP Host (ZCode / Claude Code / Pi / Cursor …)              │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP (JSON-RPC over stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  pi-subagent-server  (Node/TS)                                │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ Tool layer │  │ Session      │  │ Pi runner          │   │
│  │ (7 tools)  │─▶│ registry     │─▶│ (spawn pi -p)      │   │
│  │ + plan()   │  │ + persist    │  │ parse agent_end    │   │
│  └─────┬──────┘  │ + _snapshot  │  │ + tool_execution   │   │
│        │         └──────────────┘  └─────────┬──────────┘   │
│        │                           ┌────────▼─────────┐     │
│        └───────────────────────────│ Run registry     │     │
│           (kill)                   │ + process-table  │     │
│                                   └──────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │ child_process.spawn({ cwd })
                            ▼
                   ┌─────────────────────┐
                   │  pi CLI (0.77+)     │
                   └─────────────────────┘

Три уровня с чёткими границами: уровень инструментов (MCP-схема + чистая функция plan()) / реестр сессий (состояние + персистентность + очистка) / исполнитель (spawn pi, разбор NDJSON, таблица процессов).

Инструменты

Цикл рецензирования: после pi_task_plan соберите результат через pi_status(runId). Когда запуск завершается, сервер определяет, что это рецензионный запуск, разбирает _plan-reviewed.md и сохраняет planVerdict / planReviewedPath в задаче. Промпты этапов автоматически включают отрецензированный план и выходные файлы успешно пройденных этапов-зависимостей.

Асинхронные этапы: передайте mode: "async" в pi_task_stage_run, чтобы не блокировать вызов инструмента на весь запуск (рекомендуется, если MCP-хост ограничивает время вызова инструмента). Сбор результата — через pi_task_stage_collect(taskId, stageId). Неудачные попытки повторно отправляются под новым именем сессии, чтобы избежать загрязнения истории; после 3 неудач этап переходит в manual с панелью решений (retry_with_new_hint поддерживается через promptHintOverride).

Восстановление после перезапуска: повторный запуск pi_task_create с тем же taskId выполняет слияние, а не конфликт. Этапы, чей выходной файл уже существует и проходит валидацию, автоматически помечаются как passed, поэтому прерванные задачи возобновляются без ручного редактирования tasks.json.

Модель сессий

• Каждая сессия имеет человекочитаемое имя + UUID Pi + cwd + goal.

• Первый pi_delegate создаёт сессию (обязателен goal); последующие вызовы автоматически продолжают её.

• Реестр сохраняется в ~/.pi-subagent/registry.json (атомарная запись; при перезапуске прерванные записи со статусом running исправляются на error).

• Ограничение параллелизма: 4 одновременных запуска; одна сессия никогда не выполняется параллельно.

• Задачи сохраняются в ~/.pi-subagent/tasks.json (атомарная запись; запущенные этапы при перезапуске исправляются на failed(interrupted_by_restart)).

Установка

git clone <this-repo> && cd pi-subagent
npm install

Предварительное требование: установлен CLI pi (npm i -g @earendil-works/pi-coding-agent) и он доступен в PATH.

Настройка MCP-хоста

Добавьте в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "pi-subagent": {
      "command": "npx",
      "args": ["tsx", "/abs/path/to/pi-subagent/src/server.ts"]
    }
  }
}

Дополнительные переменные окружения:

• PI_SUBAGENT_REGISTRY — путь к реестру (по умолчанию ~/.pi-subagent/registry.json)

• PI_BIN — переопределение исполняемого файла pi (используется в тестах)

Тестирование

npm test           # full suite (140 tests)
npm run test:fast  # dot reporter

В тестах используется фейковый pi (test/fixtures/fake-pi.sh); покрытие: async/sync, тайм-аут, kill, сбой создания сессии, несколько ожидающих, лимит прогресса, правила планирования (табличные + property-тесты на 100 итераций), персистентность реестра, очистка и т.д.

Структура проекта

src/
├── types.ts                 # all shared types + error codes
├── errors.ts                # ToolError helpers
├── runner/                  # parse.ts, argv.ts, spawn.ts, process-table.ts
├── registry/                # session.ts, run.ts, persist.ts, redact.ts
├── scheduler/               # keywords.ts, plan.ts (5-stage pure function)
├── tools/                   # delegate, status, plan-tool, session, kill
└── server.ts                # MCP entry (stdio)
skills/pi-subagent/          # SKILL.md + delegation-patterns (strategy layer)
test/                        # fixtures/ + *.test.ts
docs/                        # design.md (spec) + implementation-plan.md

Дизайн и процесс

Проект прошёл совместное проектирование + 4 раунда внешнего рецензирования до реализации. Спецификация и план сохранены в docs/:

• docs/design.md — полная спецификация дизайна (архитектура, контракты инструментов, обработка ошибок, правила планировщика, стратегия тестирования). Каждый контракт прослеживается до заметки рецензента (R1–R4).

• docs/implementation-plan.md — 19 TDD-задач (написать падающий тест → реализовать → пройти → закоммитить).

Ключевые проектные решения, все подкреплённые реальным исследованием вывода pi -p и внешним рецензированием:

• cwd ≠ хранилище сессий — spawn({ cwd }) управляет рабочей директорией; файлы сессий Pi используют своё расположение по умолчанию (не засоряет проект).

• async по умолчанию + рукопожатие — новые сессии ждут события session от Pi перед возвратом (с sessionStartTimeoutMs), поэтому хост всегда получает настоящий piSessionId.

• Многоэтапный планировщик — plan() работает как reject → capacity → reuse → modify → mode, где модификаторы накапливаются, а не выбираются по первому совпадению (урок из раунда рецензирования 1).

• Очистка вывода — результаты инструментов усекаются и очищаются от токенов/ключей перед сохранением.

Статус

Рабочая реализация, 140 проходящих тестов. Ещё не опубликовано в npm — запуск из исходников через tsx.

Лицензия

MIT