Архитектура

ThreadCells — локальный control plane вокруг нативных процессов агентов программирования. Он намеренно сохраняет терминал провайдера, Git-репозиторий, устойчивое состояние координации и UI браузера раздельными компонентами с явными границами.

Если перечисленные ниже термины вам незнакомы, начните с Основных понятий.

Представление системы

Browser or installed PWA
        ↓ HTTP / WebSocket on loopback
FastAPI ThreadCells server
  ├── SQLite durable state
  ├── provider/profile registries
  ├── workflow and result service
  ├── capacity and Housekeeping service
  └── tmux/provider adapter control
               ↓
        Native provider CLIs
               ↓
      Git repositories/worktrees

Сервер и Web UI

Сервер FastAPI предоставляет приложение/API и отдаёт одну production Web-сборку. React UI читает актуальное операционное состояние и подключается к потокам терминала через WebSocket.

Базовый worker PWA кэширует только статические ресурсы с fingerprint. HTML, API, авторизация, сессии, рабочие процессы, Statistics, терминалы, изменения и WebSocket остаются зависимыми от сети, поэтому UI не может выдумать офлайн-состояние control plane.

Пакет Docs создаётся во время сборки из DOCS_MANIFEST.json. В runtime попадает только публичный Markdown из allowlist.

Устойчивое состояние

SQLite хранит сессии, терминалы, проекты, ревизии профилей/провайдеров, ресурсные lease, рабочие процессы, результаты, записи использования, события аудита и квитанции планирования. Операции, которые должны выполняться ровно один раз или быть безопасными к повтору, используют устойчивые идентичности и транзакции базы данных, а не полагаются на временный вывод терминала.

Процессы провайдеров и сессии tmux — внешние факты runtime. Запуск и восстановление сверяют их с базой данных; нельзя считать, что существование одной стороны доказывает актуальность другой.

Выполнение провайдера

Адаптер переводит нормализованный запуск ThreadCells в проверенный вызов нативного CLI. Провайдер по-прежнему отображает собственный terminal UI и поддерживает собственную аутентификацию. Адаптеры сообщают о возможностях и состоянии preflight, а не имитируют неподдерживаемое поведение.

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

Рабочие контексты Git

Управляемые worktree используют общую объектную базу репозитория, но изолируют пути checkout и ветки. Полномочия writer сохраняют явное владение изменениями. Worktree — инструмент параллелизма, а не песочница операционной системы.

Рабочие процессы и результаты

Состояние рабочего процесса переживает отдельные ходы провайдера. Делегированные результаты записываются, доставляются как минимум один раз, включаются родителем и подтверждаются до возможного вывода дочернего агента из эксплуатации. Миссию верхнего уровня закрывает явное завершение, а не финальный ответ модели.

Допуск и давление

Резидентные supervisor, выполнения провайдеров, рабочие контексты и тяжёлые выполнения имеют независимые lease и лимиты. Давление на диск и защита обслуживания — дополнительные ограничения runtime. Межпроцессные барьеры не позволяют двум процессам одновременно считать, что они получили последний слот.

Граница безопасности

ThreadCells рассчитан на один доверенный хост и операторскую среду. Общий доступ к UI защищается внешним механизмом — loopback/SSH или аутентифицированным обратным прокси. Для чувствительных изменений Settings используется отдельная граница verifier/session оператора, но это не универсальная система входа.

Пакеты провайдеров и нативные CLI — доверенный исполняемый код. Импортированная конфигурация — ограниченные декларативные данные. См. Модель безопасности.