作成日: 2026-03-06
ステータス: Draft
本書は ButlerLayer_アーキテクチャ定義書_v0.3.md を前提に、Brain↔Butler 間の通信方式・契約・状態遷移を定義する。
「何を頼んで何が返るか」を定義する文書であり、Brain側の実装者が主な読者。
タスク契約 (Task Contract): 頭脳から執事に渡す入力仕様結果契約 (Result Contract): 執事から頭脳に返す出力仕様協調トランザクション (Collaboration Transaction): 要求投入から結果返却までの1往復協調セッション (Collaboration Session): 複数トランザクションのまとまりエスカレーション (Escalation): 解決不能時の頭脳への差し戻し失敗分類 (Failure Class): need_input / blocked / failed の分類規約fire and forget: BrainはTask Contract投入後、結果が返るまで待つだけ。中間制御はしないButler OrchestratorはMCPサーバーとして動作する。
BrainはMCPツール経由でButlerを呼び出す。既存のMCPエコシステム（Trilium MCP等）と同一の構造。
| ツール名 | 用途 | 引数 |
|---|---|---|
butler__submit_task |
タスク契約を投入する | contract: TaskContract |
butler__get_status |
タスクの現在状態を確認する | task_id: string |
butler__approve |
承認ゲートへの応答 | task_id: string, decision: "approve" \| "deny" |
butler__teach |
need_input への手順回答 | task_id: string, steps: Step[] |
butler__cancel_task |
実行中タスクをキャンセルする | task_id: string |
butler__reload |
agent_executor 等のモジュールをホットリロードする（main.py 以外の変更を即反映） | なし |
BrainはTask Contractを1回投入したら、Orchestratorが自律実行する。
Brain: butler__submit_task(contract) → task_id
※ Orchestratorが自律的に実行（Brainを起こさない）
Brain: butler__get_status(task_id) でポーリング（MVPはポーリングのみ。ポーリング間隔はBrain側の裁量）
Brain: 結果契約を受け取って判断
OrchestratorがBrainを起こす条件:
need_input: 手順不足・情報不足blocked: ポリシー違反・承認拒否・外部依存停止need_approval: 承認ゲート待ち（Brainが butler__approve で応答）補足:
butler__submit_task で同期返却されるmain.py の intent 一覧を更新する設計は採らない{
"task_id": "uuid",
"intent": "deploy",
"target": {
"service": "mcp",
"environment": "prod",
"compose_dir": "/home/docker/docker_setup/trilium"
},
"constraints": {
"implicit_scope": ["docker", "git_read", "shell_read"],
"require_approval_for": ["git_commit", "git_push", "destructive"],
"max_minutes": 15
},
"delegation_mode": "teach_if_unknown",
"success_criteria": [
"docker compose ps で対象コンテナが Up",
"health endpoint が 200"
],
"evidence_required": [
"executed_commands",
"key_outputs",
"error_head_tail"
],
"requested_by": "claude_code",
"requested_at": "ISO8601"
}
task_id, intent, target, constraints, success_criteriaimplicit_scope（触っていいシステム・操作の列挙）
ここに入っているものはタスク契約提出時点で承認済みとみなす。スコープ外へのアクセスは自動ブロックしてBrainへescalate。
値の例:
"trilium": Triliumへのアクセス全般"docker": docker操作全般"git_read": git fetch/log/diff等の読み取り"git_write": git add/commit（pushは別途require_approval_forで制御）"shell_read": ファイル読み取り・状態確認系コマンドrequire_approval_for（スコープ内でも確認が必要な操作）
implicit_scope内であっても、不可逆・外部影響のある操作は確認する。
値の例:
"git_commit": git commit"git_push": git push"destructive": rm, docker system prune等"docker_down": docker compose down| 値 | 意味 |
|---|---|
"teach_if_unknown" |
Butlerが手順を知らなくても委任し、need_input で手順を教える |
"known_only" |
Butlerが手順を知っている場合のみ実行。知らなければescalate |
デフォルトは "teach_if_unknown"。Intentドメインのタスクには常にこれを使う。
Intentドメインには triage（障害・失敗事象の一次切り分け）を含む。
{
"task_id": "uuid",
"status": "ok",
"summary": "trilium-mcp を再起動し health 200 を確認",
"evidence": {
"commands": [
"docker compose pull",
"docker compose up -d",
"curl -s https://.../health"
],
"key_outputs": [
"container: Up",
"health: {\"status\":\"ok\"}"
],
"error_head_tail": null
},
"diff": {
"files_changed": [],
"infra_changed": ["container image updated"]
},
"next_options": [
"logs を5分監視",
"Triliumへ作業記録を反映"
],
"finished_at": "ISO8601"
}
| 値 | 意味 |
|---|---|
ok |
success criteria を全て達成 |
need_input |
手順不足・情報不足。Brainへエスカレーション |
blocked |
ポリシー違反・承認拒否・外部依存停止 |
failed |
実行済みだが success criteria 未達 |
Butler が need_input を返した時、Brain は butler__teach で手順を返す。
{
"task_id": "uuid",
"steps": [
{"kind": "cmd", "value": "git pull"},
{"kind": "cmd", "value": "docker compose pull"},
{"kind": "cmd", "value": "docker compose up -d"},
{"kind": "check", "value": "health_url returns 200"}
]
}
step kind（MVP）:
| kind | 意味 |
|---|---|
cmd |
シェルコマンド実行 |
check |
検証コマンド実行。exit code 0 = pass、非0 = fail。value は必ず実行可能なシェルコマンドで書く |
wait |
指定秒待機（value: "30s" 等） |
success_criteria はBrainとの意思疎通用メタデータ（人間向け説明）。機械判定には使用しない。実際の検証はSOPの check stepが担う。
Brainは必ずこの構造化JSONで返す。自然言語の説明は不可。
RECEIVED
-> VALIDATING_CONTRACT
-> RESOLVING_SOP
-> NEED_INPUT (手順不足 → Brainへ)
-> NEED_APPROVAL (承認待ち → Brainへ)
-> EXECUTING
-> VERIFYING
-> DONE | FAILED | BLOCKED | CANCELLED
遷移規則:
NEED_INPUT は butler__teach 受信後 RESOLVING_SOP へ戻るNEED_APPROVAL は butler__approve(approve) 後 EXECUTING、deny 時 BLOCKEDVERIFYING 未達は FAILEDBLOCKED としてBrainへRECEIVED または EXECUTING 中に butler__cancel_task を受信すると CANCELLED へ遷移agent モードでは agent_executor が key_outputs を検証し、required ツール未呼び出しの場合は FAILED にする（verify_key_outputs）| シーケンス | 主目的 | 主に発生しうる Failure Class |
|---|---|---|
| 8.1 正常系A（既知SOP） | 既知SOPで完了 | なし（正常系） |
| 8.2 正常系B（未知SOP） | 手順学習して完了 | need_input（途中） |
| 8.3 エラー系E1（契約/承認） | 入口エラー処理 | blocked |
| 8.4 エラー系E2（実行/検証） | 実行失敗処理 | failed, need_input |
| 8.5 SOP更新（昇格） | SOP昇格/据え置き | なし |
| 8.6 SOP修正（訂正） | 誤ったSOPの修正 | なし（Brain起点） |
| 8.7 承認ゲート | 承認待ち制御 | blocked |
| 8.8 協調セッション | セッション管理 | blocked（不整合時） |
ButlerLayer_アーキテクチャ定義書_v0.3.mdButlerLayer_実行SOP仕様書_v0.3.mdButlerLayer_データ運用仕様書_v0.3.md以上を Butler Layer 契約・通信仕様書 v0.3 とする。