Операционные гарантии

Статус: принято 1 августа 2026 года.

Контекст

GigaLoom поддерживает два способа работы с агентами разработки. Пользователь может запустить собственный CLI агента в терминале или выполнить задачу через управляемый интерфейс GigaLoom. Эти способы запуска предъявляют разные требования к совместимости, безопасности и формату результата.

Перед добавлением каталога агентов, автоматической установки и неинтерактивных запусков нужно зафиксировать несколько границ:

• /api/agents уже используется для агентов автоматизации внутри проекта;
• запись в каталоге ACP не обязательно соответствует команде, которую можно запустить в терминале;
• версия исполняемого файла помогает оценить совместимость, но не заменяет проверку протокола;
• автоматическим клиентам нужен стабильный поток событий и однозначные коды завершения;
• версия продукта должна задаваться в одном месте, а не отдельно в Python, npm, манифестах и файлах релиза.

Решение

Термины и API

В интерфейсе и API используются разные названия для разных сущностей:

Сущность	Название в продукте	API
Нативные CLI и пользовательские структурированные маршруты	Coding Agents	/api/agent-runtimes/...
Официальный каталог совместимых ACP-агентов	ACP Registry	/api/agent-runtimes/registry/...
Пакеты, загруженные в изолированное хранилище GigaLoom	Installed Agents	/api/agent-runtimes/installations/...
Переиспользуемые агенты автоматизации проекта	Automation Agents	/api/agents/...
ACP, app-server и другие машинные протоколы агента	Routes	вложенный ресурс Coding Agent

Идентификаторы registry_id, local_agent_id, native_agent_id, route_id и managed_install_id не взаимозаменяемы. Идентификатор из каталога можно использовать как локальный только после проверки коллизий. Отображаемое имя не создаёт псевдоним автоматически. Связь между установленным ACP-маршрутом и существующим нативным агентом устанавливается отдельной операцией.

Данные каталога носят справочный характер. Поиск, обновление каталога и предварительный просмотр установки не должны устанавливать пакеты, запускать код, открывать браузер, выполнять вход в сервисы, менять настройки агента или предоставлять доступ к рабочему каталогу и сети.

Передача аргументов нативному CLI

Если первый аргумент после giga распознан как нативный агент, все следующие аргументы передаются его CLI без изменений. GigaLoom не разбирает, не переписывает, не сохраняет и не хеширует эту часть команды. Формат терминала, сигналы, stdout, stderr и код завершения остаются в ведении самого агента.

Встроенные команды giga имеют приоритет перед именами и псевдонимами агентов. Поэтому giga agent add ... запускает установщик GigaLoom, а giga <agent> add ... передаёт add ... выбранному агенту. Запись каталога не может перекрыть встроенную команду или уже занятый псевдоним.

ACP-маршрут без нативного CLI не становится терминальной командой. Его можно использовать через явный структурированный запуск, например giga run --agent <id>, или через веб-интерфейс.

Проверка структурированных маршрутов

Для нативного запуска достаточно безопасно найти исполняемый файл. Для структурированного маршрута дополнительно проверяются:

• идентификатор исполняемого файла;
• версия и формат протокола;
• обязательные возможности и поведение сессии;
• формат кадров и событий;
• ограничения безопасности;
• неизменяемые результаты предыдущих проверок.

Диапазон протестированных версий влияет на предупреждение в интерфейсе, но не служит единственным списком разрешённых версий. Если новая или неизвестная версия успешно прошла обязательную проверку, маршрут получает состояние compatible_unverified и остаётся доступным с предупреждением.

Маршрут блокируется, если:

• основная версия протокола несовместима;
• отсутствует обязательная возможность;
• поток данных повреждён или небезопасен;
• нарушено обязательное ограничение безопасности;
• версия или сборка отмечена как заведомо несовместимая.

Ошибка структурированной проверки не должна блокировать безопасный нативный запуск giga <agent>. Версия, подпись, целостность пакета и успешная загрузка также не дают разрешения на установку, запуск, доступ к учётным данным, сети или файловой системе.

Неинтерактивный запуск

За публичный неинтерактивный режим отвечает команда giga run --headless. Она принимает ровно один источник запроса, требует режим --no-input, работает без TTY и отдельно проверяет рабочий каталог и каталог для результатов.

Формат jsonl-v1 соблюдает следующие правила:

• каждая строка stdout содержит один канонический JSON-объект;
• stderr используется только для коротких диагностических сообщений;
• оба потока не содержат управляющих ANSI-последовательностей;
• номера событий возрастают в пределах одного запуска;
• отмена и тайм-аут завершаются ограниченной процедурой остановки;
• итоговое событие записывается ровно один раз и содержит ссылку на результат либо капсулу, а также список отсутствующих данных;
• успех фиксируется только после успешного завершения процесса и записи обязательного итогового события.

Поддерживаются события run_started, agent_resolved, route_observed, turn_started, tool_activity, approval_required, usage, artifact, warning, run_succeeded, run_failed и run_canceled.

Коды завершения являются частью публичного контракта:

Код	Значение
0	Задача выполнена
2	Ошибка аргументов или маршрут не прошёл проверку
10	Требуется повторная аутентификация
20	Операция запрещена политикой или выданными полномочиями
30	Ошибка агента или структурированного транспорта
40	Отмена или тайм-аут
50	Ошибка состояния, результатов проверки или целостности данных
70	Нарушен внутренний инвариант GigaLoom

Единый источник версии

Файл release/version.toml — единственное место, где версия продукта меняется вручную. Команда подготовки выпуска переносит это значение в метаданные Python- и npm-пакетов, release/release.json, ожидаемое имя Git-тега, формируемые разделы списка изменений, документацию пакета и манифест артефактов.

Подготовка выпуска должна быть атомарной и идемпотентной. Проверка завершается ошибкой, если производные файлы расходятся с release/version.toml. Повторный запуск с той же версией не меняет файлы. Сборка может проверять исходные данные, но не должна исправлять их незаметно для пользователя.

Файлы результатов выпуска имеют постоянные имена: external-evidence.json, candidate-report.md и artifact-set.toml. Версия хранится внутри содержимого, связанного с контрольной суммой. Создание тега, публикация пакетов и GitHub Release остаются отдельными явными действиями.

Производительность и конфиденциальность

Основной экран настроек и локальные значения по умолчанию должны открываться без ожидания проверки учётных записей провайдеров, списка MCP-серверов, диагностики и всех конфигураций Harness. Обновление каталога и ход установки не входят в критический путь запуска CLI и команды giga --version.

Контрольные измерения фиксируют время запуска CLI и API, загрузку настроек, состав исходников и проверку смены версии. Абсолютные значения относятся к конкретной машине и не задают универсальные нормативы производительности.

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

Последствия

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

Само решение не меняет маршрутизацию, ответы API, сохранённое состояние, процессы провайдеров и внешние сервисы. Эти изменения реализуются и проверяются отдельно.