Версионирование конфигов и секреты

🔵 Дерево config/ можно держать git-репозиторием: любое изменение конфига, сделанное через хост (builder, переключатели модулей, провайдер, секреты), становится версией — её видно в истории, можно сравнить и откатить. Секреты хранятся в том же репозитории, но в зашифрованном виде.

Файловый доступ и git остаются на хосте за sensitive-портом agent_os.Versioning; HTTP- и UI-поверхность даёт фича-модуль versioning.

44.1 Модель: checkpoint, seal, auto-seal

Запись идёт в два уровня, чтобы история была и надёжной, и осмысленной:

Уровень	Кто делает	Что это
checkpoint	автоматически, хост	механический коммит после каждого изменения конфига. Повторные checkpoint'ы сворачиваются в один коммит (`--amend`) до следующего seal.
seal	админ/агент	один коммит с осмысленным сообщением, сворачивающий все checkpoint'ы с прошлого seal (`git reset --soft`).
auto-seal	хост	seal по простою, если задан `autoseal_idle_secs`.

Каждый коммит несёт машинные трейлеры Agent / Session / Source; тело сообщения — человекочитаемое:

Add currency tool to felix

Agent: admin
Session: 4f2a9c…
Source: tool:config_commit

checkpoint'ы нужны только для сохранности между seal; в итоговой истории после seal остаётся один коммит на смысловую правку.

44.2 Включение

# config/server.yaml
versioning:
  enabled: true          # по умолчанию выключено
  branch: config         # ветка записи (для git-источника — ветка из --config-ref)
  remote: origin         # опционально, для push
  push: false            # push после seal
  autoseal_idle_secs: 300
  secrets:
    mode: mixed          # sealed | mixed | plaintext
    key_file: ~/.agent-os/config.key

Модуль versioning должен быть включён (id versioning в config/modules.enabled или server.yaml → modules.enabled). При первом старте с enabled: true в корне конфига создаётся репозиторий (.git, .gitignore) и первый коммит Initial config version.

44.3 Git-источник (`--config-repo`)

Когда конфиг клонируется из git (см. Конфигурация сервера), версионирование работает поверх этого клона:

клон полный (не shallow) и стоит на локальной ветке (--config-ref), а не в detached HEAD — иначе нельзя коммитить и пушить;
поллер конфига делает merge --ff-only, а при расхождении — rebase, то есть локальные коммиты не затираются; конфликт просто логируется;
после внешнего обновления baseline seal перепривязывается, чтобы seal не свернул чужие коммиты;
push: true пушит ветку в remote после seal (нужен доступ к remote).

git -c user.name/email для коммитов задаётся локально (Agent OS <agent-os@localhost>), core.autocrlf=false — файлы конфига байт-в-байт.

44.4 Секреты

Секреты хранятся в config/secrets.yaml как узлы { enc: … } / { plain: … }:

scopes:
  global:
    OPENAI_API_KEY: { enc: "v1:…" }   # зашифровано (AES-256-GCM)
  admin:
    region:         { plain: "eu" }   # открытый текст (если политика разрешает)

Шифрование: симметричный AES-256-GCM, nonce на значение; расшифровка только в памяти. На диске и в git — шифртекст.
Ключ: AGENT_OS_CONFIG_KEY (base64 или hex, 32 байта) либо файл versioning.secrets.key_file (по умолчанию ~/.agent-os/config.key, создаётся при первом sealed-значении). Ключ не версионируется.
Политика mode:
- sealed — только { enc: … }, открытый текст отклоняется;
- mixed — по значению (по умолчанию);
- plaintext — без ключа (dev/CI/одиночный хост).
Значения наружу никогда не отдаются: list_secrets возвращает только scope/key/mode.

Исключения из версионирования: .env и env.overrides.yaml (машинно-локальное состояние). keys/deploy_key остаётся намеренным открытым исключением.

44.5 HTTP API (ACCESS_ADMIN)

Метод	Путь	Что делает
GET	`/v1/versioning/status`	`{ enabled, initialized, branch, head, dirty, remote, push }`
GET	`/v1/versioning/log?path=&limit=`	история коммитов (новейшие первыми)
GET	`/v1/versioning/diff?from=&to=&path=`	unified diff между ревизиями
GET	`/v1/versioning/show?rev=&path=`	файл на ревизии
POST	`/v1/versioning/commit`	`{ message }` — seal
POST	`/v1/versioning/restore`	`{ rev, path? }` — откат
POST	`/v1/versioning/push`	push в `remote`
GET	`/v1/versioning/secrets?scope=`	список ключей (без значений)
POST	`/v1/versioning/secrets`	`{ scope?, key, value, mode? }`

restore перезаписывает файлы рабочего дерева; live reload подхватывает изменения без рестарта.

44.6 UI

Страница /platform/versions (меню Platform → «Версии конфигов», владелец agent_os_versioning): список коммитов, diff выбранного, ручная фиксация (seal), restore, push.

44.7 Инструменты агента

У агента-инженера (admin, через tool_call) доступны: config_versions, config_version_show, config_version_diff, config_version_restore (подтверждать!), config_commit, secrets_list, secrets_set.

44.8 Бэкапы

Когда версионирование включено, builder не пишет полные копии в config/agents/.backups/ — их заменяет git-история. При выключенном — прежнее поведение.