アーキテクチャ
ThreadCells は、ネイティブのコーディングエージェントプロセスを取り巻くローカルコントロールプレーンです。プロバイダー端末、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 を公開し、本番用 Web ビルドを一つ配信します。React UI はライブの運用状態を読み取り、WebSocket を通じて端末ストリームへ接続します。
基本 PWA ワーカーがキャッシュするのはフィンガープリント付き静的アセットだけです。HTML、API、認可、セッション、ワークフロー、Statistics、端末、変更操作、WebSocket はネットワーク依存のままなので、UI がオフラインのコントロールプレーン状態を作り出すことはできません。
Docs バンドルは、ビルド時に DOCS_MANIFEST.json から生成されます。ランタイムに入るのは許可リスト済みの公開 Markdown だけです。
永続状態
SQLite には、セッション、端末、プロジェクト、プロファイル／プロバイダーのリビジョン、リソースリース、ワークフロー、結果、使用量レコード、監査イベント、スケジューリング受領記録が保存されます。厳密に一度だけ実行する必要がある操作やリプレイ安全である必要がある操作は、一時的な端末出力に頼らず、安定した ID とデータベーストランザクションを使用します。
プロバイダープロセスと tmux セッションは外部ランタイムの事実です。起動／復旧時にはデータベースと照合します。一方の存在だけで、もう一方が現在のものだと仮定してはいけません。
プロバイダー実行
アダプターは、正規化された ThreadCells の起動要求を、レビュー済みのネイティブ CLI 呼び出しへ変換します。プロバイダーは引き続き独自の端末 UI を描画し、独自の認証を維持します。アダプターは、サポートされない動作を模倣するのではなく、機能と事前検査の事実を報告します。
構造化されたプロバイダーテレメトリーは、永続的な使用量レコードに正規化されます。累積カウンターは安定したチェックポイントを使うため、ポーリングや再起動で合計が重複しません。
Git 作業コンテキスト
管理対象 worktree はリポジトリのオブジェクトデータベースを共有しますが、チェックアウトパスとブランチを分離します。書き込み権限により変更所有権を明示的に保ちます。worktree は並行実行のための道具であり、オペレーティングシステムのサンドボックスではありません。
ワークフローと結果
ワークフロー状態は個々のプロバイダーターンをまたいで存続します。委任された結果は記録され、少なくとも一度配信され、親に取り込まれ、対象の子を退役可能にする前に確認応答されます。トップレベルのミッションを閉じるのは、モデルの最終応答ではなく明示的な完了です。
受け入れと負荷
常駐スーパーバイザー、プロバイダー実行、作業コンテキスト、重い実行には、独立したリースと制限があります。ディスク圧迫と Housekeeping の保護も追加のランタイム制約です。プロセス間フェンスにより、二つのプロセスが最後のスロットを取得したと同時に信じることを防ぎます。
セキュリティ境界
ThreadCells は、信頼できる一台のホストとオペレーター環境を前提としています。一般的な UI アクセスは、ループバック／SSH または認証済みリバースプロキシによって外部で保護されます。機密性の高い Settings の変更では、別個のオペレーター検証機構／セッション境界を使いますが、これは一般的なログインシステムではありません。
プロバイダーパッケージとネイティブ CLI は、信頼された実行可能コードです。インポートされる設定は制約付きの宣言的データです。セキュリティモデルを参照してください。