AgentRGB

AgentRGB показывает состояние Pi coding agent через подсветку клавиатуры. Core работает локально и получает только события жизненного цикла, без содержимого запросов, ответов и инструментов.

Подготовлена версия 0.1.0 для Python и Pi package; production release ещё не опубликован. Python 0.1.0rc1 ранее проверен в TestPyPI, Pi 0.1.0-rc.1 — из npm (RC evidence). Пока npm latest указывает на RC; удаление отклонено с E400. Результаты подготовки финальных артефактов — в release evidence.

Требования

• Windows — текущая подтверждённая ОС.
• Python 3.14+; локальные проверки выполнены на Python 3.14.4.
• Установленный Pi coding agent и доступная команда pi.
• Для физической индикации проверена проводная AULA F75 258A:010C, vendor HID-интерфейс MI_01/COL06. Другие ОС, клавиатуры и ревизии не подтверждены.
• Команда agentrgb должна быть в PATH процесса Pi.

Публичная установка

Версия 0.1.0 ещё не опубликована. Следующий сценарий предназначен для использования после production publish; сейчас npm без явной версии устанавливает RC через latest.

py -3.14 -m pip install agentrgb
pi install npm:agentrgb-pi
pi

Pi автоматически загружает пакет. Он подключается к существующему Core или запускает agentrgb start --output aula-f75. При /quit пакет завершает только Core, который запустил сам. Ошибка AgentRGB отключает индикацию, но не останавливает Pi.

Автозапуск Pi рассчитан на проверенную AULA F75 и может управлять её подсветкой. Для работы без клавиатуры сначала запустите в отдельном терминале agentrgb start: по умолчанию это безопасный fake. Pi подключится к такому Core и оставит его работающим при выходе.

Состояния

waiting поддерживается только при блокирующем Pi UI prompt внутри активного запуска. Обычный вопрос в ответе модели не создаёт waiting. completed означает штатное окончание выполнения, а не подтверждённый успех задачи.

F75 использует volatile Direct Mode 0x06/0x08 с heartbeat. При обычной работе AgentRGB не переписывает пользовательский lighting profile. После прекращения кадров проверенное устройство самостоятельно возвращает профиль; возврат после любого аварийного завершения не гарантируется.

Ручной запуск и диагностика

agentrgb --help
agentrgb start                 # fake, без RGB-устройства
# Только для осознанного аппаратного запуска:
agentrgb start --output aula-f75

Core работает в текущем терминале. Ctrl+C завершает его и освобождает порт. Для диагностики в другом терминале:

agentrgb doctor
agentrgb status

status обращается только к HTTP Core: running даёт код 0, not running или unavailable — 1. Это доступность Core, а не состояние агента или исправность RGB-выхода.

doctor проверяет Python, версию AgentRGB, production imports, Core, порт и identity F75. Identity read использует SetFeature с opcode 0x82 и GetFeature, без Direct-кадров и изменения RGB/profile. Отсутствующее, неоднозначное или неподходящее устройство, ошибка диагностики либо занятый другим процессом порт дают код 1. Если всё готово — 0; незапущенный Core при свободном порте этому не мешает. Ошибка аргументов даёт код 2.

CLI и Pi используют AGENTRGB_PORT (по умолчанию 8765). При изменении порта задайте одинаковое значение в обоих терминалах; допустимы целые числа от 1 до 65535.

Локальная установка для разработки

Из корня репозитория, PowerShell:

py -3.14 -m pip install -e .
pi install ./integrations/pi
pi list

После этого pi загружает пакет без -e. Не подключайте установленный extension повторно через -e ./integrations/pi/agentrgb.ts. Подробности — в README пакета.

Editable install предназначен для разработки. Release gate использует wheel в новом venv и Pi package из npm tarball, запуск вне checkout: чеклист, сборка и ручная публикация. Runtime-зависимостей у Python-пакета нет. Если Python launcher py отсутствует, используйте путь к проверенному Python 3.14+.

Проверки

После development install, без реальной клавиатуры:

py -3.14 -m unittest discover -s tests
$env:AGENTRGB_TEST_PYTHON = py -3.14 -c "import sys; print(sys.executable)"
node --test tests/*.test.mjs experiments/pi-events/recorder.test.mjs
git diff --check

Известные ограничения

• Pi transport — best-effort localhost HTTP: события при недоступности Core могут потеряться; retry и подтверждений доставки нет.
• waiting поддерживается только через Pi UI prompt. Pi interrupted и run-level error пока не классифицируются.
• Проверена конкретная проводная AULA F75. Другие устройства и режимы Bluetooth/2,4 ГГц не поддержаны; долговременная надёжность не исследована.
• Требуется Python 3.14+; подтверждённая ОС — Windows.
• При нескольких Pi выход владельца Core отключит индикацию остальных. Supervisor и полноценное управление несколькими клиентами отложены.
• QoderCLI, CodexCLI и WLED не входят в 0.1.0. OpenRGB остаётся возможным будущим адаптером.

Документы и подтверждённые проверки

• VISION, MVP, ARCHITECTURE — цель, границы и устройство проекта.
• STATES, INTEGRATIONS — модель состояний и соответствие событий Pi.
• 04C — подтверждённый путь Pi → F75 на Windows с Pi 0.86.1.
• H5–H7 — Direct Mode, штатный shutdown и контролируемый сбой output. Исторические persistent-команды 0x04/0x0A не используются production lifecycle.
• AGENTS.md — правила разработки.

Лицензия

MIT.