Lattice

Lattice は、Sprites と呼ばれる AI コーディングエージェントのフリートを管理するための Elixir/Phoenix コントロールプレーンです。リアルタイムフリート可視化のための LiveView ダッシュボード、プログラマティック制御のための REST API、安全性分類とヒューマンインザループ承認によるインテント ベースのガバナンスシステム、および Telemetry と PubSub を介したイベント駆動の可観測性を提供します。

コアコンセプト

Sprites

Sprite は管理下にある AI コーディングエージェントです。各 Sprite は OTP GenServer プロセスとして実行され、Fleet Manager によって監視されます。Sprites には 3 つのステータスがあります：

• cold — 実行していない、リソースが割り当てられていない
• warm — プロビジョニング済みだがアイドル状態
• running — アクティブに作業を実行中

Sprites API エンドポイントを使用して、Sprites の作成、起動、休止、タグ付け、調整、および削除を実行できます。

Intents

Intent は Lattice における管理対象の作業単位です。Sprite（またはオペレータ）が操作を実行したい場合、Intent を提案します。Intent はステートマシンを通じて移行します：

proposed → classified → awaiting_approval → approved → running → completed
                                                                → failed
                                          → rejected
                        → canceled (from most states)

各 Intent には kind があります：action（何かを変更）、inquiry（読み取り専用）、または maintenance（システムメンテナンス）。

Fleet Manager

Fleet Manager は、すべての Sprite プロセスを所有する DynamicSupervisor です。Sprites のスポーン、追跡、および監視を処理します。フリート概要については GET /api/fleet を使用し、フリート全体の調整をトリガーするには POST /api/fleet/audit を使用します。

Capabilities

Capabilities は、外部システム（GitHub、Fly.io、Sprites API）に対して境界のあるインターフェースを提供する behavior モジュールです。これらはクリーンなモッキングとテストを実現します。

Safety pipeline

すべての操作は safety pipeline を通じて流れます：classify → gate → audit。

• Classify: 操作が safe、controlled、または dangerous であるかを判定
• Gate: 分類に基づいて承認要件を適用
• Audit: トレーサビリティのためにすべての操作と決定をログ

API 概要

認証

すべての /api エンドポイントはベアラートークンが必要です：

Authorization: Bearer <token>

GET /health は認証なしでアクセスできます。

レスポンスフォーマット

成功レスポンス：

{
  "data": { ... },
  "timestamp": "2026-01-15T12:00:00Z"
}

エラーレスポンス：

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

ステータスコード

コード	意味
200	成功
401	ベアラートークンが不足または無効
404	リソースが見つからない
422	バリデーションエラー

エンドポイント リファレンス

Health

メソッド	パス	説明
GET	/health	ヘルスチェック（認証不要）

Fleet

メソッド	パス	説明
GET	/api/fleet	フリート概要とステータス別 sprite カウント
POST	/api/fleet/audit	フリート全体調整のトリガー

Sprites

メソッド	パス	説明
GET	/api/sprites	すべての sprites をリスト表示
GET	/api/sprites/:id	Sprite 詳細
POST	/api/sprites	Sprite を作成（ボディ：{"name": "..."})
POST	/api/sprites/:id/wake	休止中の sprite を起動
POST	/api/sprites/:id/sleep	実行中の sprite を休止
PUT	/api/sprites/:id/tags	Sprite タグ/メタデータを更新
DELETE	/api/sprites/:id	Sprite を削除（危険 — 承認が必要）
POST	/api/sprites/:id/reconcile	Sprite 調整をトリガー
POST	/api/sprites/:id/exec	exec セッションを開始（WebSocket ベース）
GET	/api/sprites/:id/sessions	アクティブな exec セッションをリスト表示
GET	/api/sprites/:id/sessions/:sid	出力を含む exec セッション詳細
DELETE	/api/sprites/:id/sessions/:sid	exec セッションを終了
POST	/api/sprites/:name/tasks	Sprite 上にタスクを作成
GET	/api/sprites/:name/skills	Sprite で利用可能なスキルをリスト表示
GET	/api/sprites/:name/skills/:skill_name	マニフェスト付きスキル詳細

Intents

メソッド	パス	説明
GET	/api/intents	Intents をリスト表示
GET	/api/intents/:id	遷移ログ付き Intent 詳細
POST	/api/intents	Intent を作成（提案）
POST	/api/intents/:id/approve	Intent を承認
POST	/api/intents/:id/reject	Intent を却下
POST	/api/intents/:id/cancel	Intent をキャンセル

Runs

メソッド	パス	説明
GET	/api/runs	Runs をリスト表示（フィルタ：intent_id、sprite_name、status）
GET	/api/runs/:id	Run 詳細
POST	/api/runs/:id/answer	ブロック中の run の質問に回答

一般的なワークフロー

フリートヘルスを確認

curl -H "Authorization: Bearer $TOKEN" https://your-lattice.fly.dev/api/fleet

Sprite を起動してタスクを割り当て

# Sprite を起動
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://your-lattice.fly.dev/api/sprites/my-sprite/wake

# タスクを割り当て
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "org/repo", "task_kind": "open_pr_trivial_change", "instructions": "Fix the typo in README.md"}' \
  https://your-lattice.fly.dev/api/sprites/my-sprite/tasks

Intent を作成して承認

# Intent を提案
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "action", "source": {"type": "operator", "id": "jane"}, "summary": "Deploy v1.2.3"}' \
  https://your-lattice.fly.dev/api/intents

# 承認（レスポンスから intent ID を使用）
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actor": "operator:jane"}' \
  https://your-lattice.fly.dev/api/intents/INTENT_ID/approve

安全性分類

レベル	ゲーティング	例
safe	自動承認、ヒューマンレビュー不要	読み取り専用クエリ、ステータスチェック、sprites のリスト表示
controlled	実行前にヒューマン承認が必要	Sprites の作成、起動/休止、コードのデプロイ
dangerous	明示的なヒューマン承認が必須、昇格されたオーディット	Sprites の削除、破壊的な操作、インフラストラクチャの変更

エラーコード

コード	意味
SPRITE_NOT_FOUND	指定された ID の sprite が存在しない
INTENT_NOT_FOUND	指定された ID の intent が存在しない
MISSING_FIELD	リクエストボディに必須フィールドが不足している
INVALID_STATE	リソースが操作に対して有効なステートにない
INVALID_KIND	Intent kind が action、inquiry、maintenance のいずれでもない
INVALID_SOURCE_TYPE	ソースタイプが sprite、agent、cron、operator のいずれでもない
INVALID_STATE_TRANSITION	リクエストされたステート遷移が許可されていない
INVALID_TRANSITION	ステートマシンがこの遷移を許可していない
SPRITE_ALREADY_EXISTS	この名前の sprite が既に存在する
UPSTREAM_API_ERROR	外部 API（Sprites API、GitHub、Fly）がエラーを返した
DELETE_FAILED	Sprite 削除が上流 API で失敗した

注意点

• Intent ステートマシンは厳密です。 ステートをスキップすることはできません。Intent は承認前に分類される必要があり、実行前に承認される必要があります。無効な遷移を試みると INVALID_STATE_TRANSITION が返されます。
• エンドポイントでの名前と ID。 ほとんどの sprite エンドポイントは :id を使用しますが、/tasks および /skills エンドポイントは :name を使用します。上記のエンドポイント リファレンスを確認してください。
• 危険な操作は承認が必要です。 dangerous に分類された操作（DELETE /api/sprites/:id など）は Intent 承認ワークフローを通す必要があります。直接削除を試みると、承認が必要な Intent が作成されます。
• Sprite ステータスは上流のステートを反映します。 cold/warm/running ステータスは Lattice ではなく Sprites API から来ます。調整はこのステートを同期します。
• Intent kind は必須フィールドに影響します。 action kind は affected_resources、expected_side_effects、および rollback_strategy を期待します。inquiry および maintenance kind はそうではありません。
• ソースタイプは列挙されています。 Intent ソースの type は sprite、agent、cron、または operator である必要があります。