agent-postbox

agent-postbox

MCP エージェント間の検証可能な引き継ぎ。agent-postbox は、単なるステータスメッセージではなく、読み返しと証拠によって、GitHub 上でのエージェント間の引き継ぎを検証可能にします。

AI の同僚たちは、GitHub Issues とプルリクエストを通じて、範囲を限定した書き込み、受領証、複数人によるレビューを行いながら協力します。

すでに、永続的で監査可能な、人間が読みやすい調整システムである GitHub リポジトリをお使いです。agent-postbox はこれを AI エージェント用のメールボックスに変え、エージェント同士が作業を引き継ぎ、結果を報告し、互いのプルリクエストをレビューできるようにします。その間、すべての書き込みは小さく、検証済みで、実行者を特定でき、すべての判断は人間に委ねられます。

これは、小規模な Model Context Protocol サーバー（stdio または Streamable HTTP）と CLI です。ランタイム依存関係はありません。

human ──opens issue──▶  #12  [to:builder]
builder ── inbox ─────▶ claims (claimed:builder), works, opens PR #13 [to:reviewer]
reviewer ─ review ────▶ REQUEST_CHANGES on #13 @ head commit (cannot review its own PR)
builder ── comment ───▶ evidence: tests, output, links
human ───────────────▶ merges. Agents cannot merge, close, or set authority labels.

共有受信箱はメッセージを届けます。agent-postbox は引き継ぎが実際に行われたことを証明します ― すべての書き込みを読み返し、エージェントが読んだ正確なテキストに結び付けた確認応答を行い、自己レビューを禁止し、検証可能な署名付き証拠ログを記録します。

リリース：v0.2.1 · 対象：1 つの GitHub リポジトリで複数のコーディングエージェント（Claude Code、Codex、Cursor など）を実行する開発者 · ランタイム依存関係なし。

30 秒で試す

GitHub アカウント、トークン、ネットワーク接続は不要です。デモでは、合成データを使ってインメモリの GitHub 上で 2 つのエージェントを実行します。

git clone https://github.com/Aethelgard-Systems/agent-postbox.git
cd agent-postbox
npm run demo

Windows PowerShell で「このシステムではスクリプトの実行が無効になっているため、npm がブロックされる」場合は、代わりに npm.cmd run demo または node examples/offline-demo/demo.mjs を使用してください。同じデモを実行でき、ポリシーを変更する必要はありません。

ビルダーとレビュアーが互いに作業を引き継ぐ様子、ネットワーク応答の消失時に二重投稿せずに状態を照合する様子、そして安全でない 3 つのアクション（自己レビュー、人間専用ラベル、コメント内のトークン）が拒否される様子を確認できます。詳細と制限については、examples/offline-demo を参照してください。

npm run demo:handoff では、v0.2 のフローを確認できます。プランナーがビルダーにタスクを引き継ぎ、ビルダーの確認応答が読んだテキストに結び付けられます（引き継ぎ内容が編集されている場合、再読するまで拒否されます）。さらに、署名付き証拠ログが検証され、その後、改ざんされて検出される様子も確認できます。

理由

マルチエージェント構成は、たいてい退屈な問題で失敗します。投稿していないのに投稿したと主張する、タイムアウト後に同じ内容を二重投稿する、自分の作業を自分で承認する、イシュー内のテキストを命令として扱う、コメントにトークンを漏らす、といった問題です。agent-postbox は、まさにこれらの失敗を防ぐことだけを目的としています。

問題	agent-postbox の機能
「投稿しました」— しかし何もない	読み返し：書き込みはすべて再取得して照合され、完了として扱われます
タイムアウト → 再試行 → 重複	書き込みレシート：送信前に ATTEMPTED が、読み返し後に CONFIRMED が記録されます。結果が不明な場合、GitHub 上でエージェント自身のアイデンティティによる完全一致の書き込みが確認できたときに限り照合されます。それ以外は、人間が解決するまでブロックされたままになります
エージェントが自分の PR を承認する	複数人確認：PR の作成者がトークン自身のアイデンティティである場合、レビュー（コメントを含む）はすべて拒否されます。このアイデンティティは GitHub に照会して検証され、レビューはヘッドコミットに紐付けられます
エージェントが、提案だけにとどめるべきことを決定する	権限の分離：保護対象のラベル（例：approved、decision:*）を付与できるのは人間のみです。提案には、権限を持たないことを明示するフッターが付きます
トークンでできることは何でもエージェントができる	書き込みの制限：エンドポイントの許可リストは固定されており、マージ、クローズ、削除、本文の編集、設定、コードへのアクセスはできません
トークンやパスワードがコメントに入り込む	タイトルと本文すべてに対するシークレットフィルター（ベストエフォート。セキュリティを参照）
イシューのテキストがエージェントに指示しようとする	読み取ったコンテンツはすべて信頼できないデータとしてマークされます
暴走するエージェント	書き込みと提案に対する日次上限
「完了」— しかし、どのタスクのどのバージョンが完了したのか？	ハンドオフ（v0.2）：受け入れ条件を含むタスクイシューです。確認応答は、エージェントが読み取ったテキストのハッシュに紐付けられ、証拠が必要です
ログが後から編集される可能性がある	証拠ログ（v0.2）：レシートの状態変更はすべてハッシュチェーンに記録され、Ed25519 署名されます。evidence verify で編集、欠落、切り詰めを検出できます

対象外

エージェントフレームワークではなく、ランタイムでもなく、データベース、ダッシュボード、ワークツリーのオーケストレーション、ロールモデルもありません。エージェントはご自身で用意してください。agent-postbox はメールボックスに徹します。

ツール

ツール	効果
inbox	to:<this-agent> ラベルが付いたイシュー／PR
read	コメントを含む単一のイシューまたは PR（信頼できないコンテンツ）
comment	レシート付きで読み返しを行う単一のコメント
label	ラベルの追加／削除：to:<any-agent>（引き継ぎ）、claimed:<self>、allowedLabels のラベル
propose	proposal ラベル付きの新規イシュー。重複チェックと日次上限あり
review	ヘッドコミットに紐付けられた PR レビュー（APPROVE、REQUEST_CHANGES、COMMENT）。自身の PR では拒否
handoff_create	受け入れ条件を付けて、to:<agent> と handoff のラベル付きイシューを作成し、別のエージェントにタスクを引き継ぎます（v0.2）
handoff_read	ハンドオフとその確認応答を読み取り、body_sha256 を返します（v0.2）
handoff_ack	自分宛てのハンドオフを確認します（DONE には証拠が必要です）。読み取り後にテキストが変更されていた場合は拒否され、完了として扱う前に読み返しを行います（v0.2）

完全なツール一覧がモデルのコンテキストに占める文字数は 4,500 未満です（テスト済み）。

クイックスタート

1. エージェントごとに固有のアイデンティティを用意します。 作成者の明確化と二者レビューを実際に機能させるため、各エージェントにはそれぞれ独自の GitHub アイデンティティが必要です。1 つのリポジトリに限定したきめ細かい個人用アクセストークン（Issues：読み取り／書き込み、Pull requests：読み取り／書き込み、Metadata：読み取り）を持つ専用のマシンアカウント、または GitHub App のインストールトークンを使用してください。従来型のトークンは、デフォルトで拒否されます。
2. インストールします（Node.js ≥ 20）：

   npm install -g github:Aethelgard-Systems/agent-postbox
   

3. 設定します – agent-postbox.config.json：

   {
     "repository": "example-org/example-repo",
     "agent": "builder",
     "tokenEnv": "AGENT_POSTBOX_TOKEN",
     "allowedLabels": ["needs-review", "blocked", "question"],
     "protectedLabels": ["approved", "decision:*"],
     "limits": { "writesPerDay": 50, "proposalsPerDay": 5 }
   }
   

4. 何も書き込まずに確認します：

   AGENT_POSTBOX_TOKEN=... agent-postbox doctor
   

5. MCP クライアントを接続します（一般的な mcpServers 形式を使用するクライアントの例です）。Streamable HTTP に対応するクライアントの場合は、代わりに agent-postbox serve --transport http --port 8471 を実行し、http://127.0.0.1:8471/mcp を指定してください（ほかのホストでは AGENT_POSTBOX_HTTP_TOKEN が必要です）：

   {
     "mcpServers": {
       "agent-postbox": {
         "command": "agent-postbox",
         "args": ["serve", "--config", "/path/to/agent-postbox.config.json"],
         "env": { "AGENT_POSTBOX_TOKEN": "<this agent's token>" }
       }
     }
   }
   

6. templates/AGENTS.md と templates/pull_request_template.md をリポジトリにコピーし、エージェントと人間が同じプロトコルを共有できるようにします。

手順を追ったセットアップ方法は、docs/getting-started.md を参照してください。2 つのエージェントが互いをレビューするウォークスルーは、examples/two-agent-review にあります。

設定

キー	デフォルト	意味
repository	–	owner/repo。このインスタンスが操作できる唯一のリポジトリです
agent	–	このエージェントの名前（[a-z0-9-]）
login	GET /user の結果	トークンの GitHub ログイン名。GitHub App トークンの場合は必須です（例：my-app[bot]）
tokenEnv	AGENT_POSTBOX_TOKEN	トークンを格納する環境変数
addressPrefix	to:	エージェント宛てのラベル接頭辞
claimPrefix	claimed:	作業を割り当てるためのラベル接頭辞（自分のみ）
proposalLabel	proposal	エージェントの提案に付けるラベル
allowedLabels	needs-review、blocked、question	エージェントが設定できる追加ラベル（末尾の * は接頭辞による一致）
protectedLabels	approved、decision:*	人間専用のラベル。エージェントは追加も削除もできません
limits	1 日あたり書き込み 50 件、提案 5 件、本文 6000 文字、タイトル 120 文字	エージェントごとの上限
receiptsFile	$XDG_STATE_HOME/agent-postbox/<owner>-<repo>-<agent>.json	ローカルのレシート保存先
allowClassicToken	false	従来型の PAT を受け入れます（非推奨）
evidence	true	署名付き証跡ログを書き込みます（v0.2）。false にすると無効になります
evidenceFile、evidenceKeyFile	receiptsFile と同じ場所	証跡ログと Ed25519 キー（初回使用時に作成、0600）
handoffLabel	handoff	引き継ぎを示す Issue のラベル

CLI

agent-postbox doctor | inbox | read <n> | comment <n> --body ... | label <n> --add a --remove b
agent-postbox propose --title ... --body-file ... | review <n> --event approve|request-changes|comment --body ...
agent-postbox handoff create --to <agent> --title ... --body ... [--acceptance "a|b"] | handoff read <n>
agent-postbox handoff ack <n> --read-sha256 <hex> --result done|partial|blocked|declined [--evidence "a|b"]
agent-postbox receipts list | receipts resolve <key> --as confirmed|failed
agent-postbox evidence verify | evidence key
agent-postbox serve [--transport stdio|http] [--host 127.0.0.1] [--port 8471]

すべての出力は JSON です。拒否された場合は終了コード 2 と、安定したエラーコード（POLICY、SECRET、LIMIT、SELF_REVIEW、UNKNOWN_OUTCOME、READBACK_MISMATCH、…）が返されます。

証跡ログ（v0.2）

レシートファイルと同じ場所に、agent-postbox は <receipts>.evidence.jsonl を保持します。レシートの状態変更ごとに 1 行記録し、ハッシュチェーンで連結したうえで、エージェントの Ed25519 キーで署名します。記録されるのはキー、種類、状態、読み戻しの判定、ハッシュであり、本文、タイトル、トークンは含まれません。 agent-postbox evidence verify はチェーンを再計算し、変更、削除、並べ替え、偽造、または切り詰められた行があれば報告します。 形式は docs/evidence-format.md に記載されており、関連ツール間で共有されるため、すべてのツールで同じ検証ツールを使用できます。

既知の制限事項（v0.2）

• 同じイシューに同一のコメント本文を投稿できるのは一度だけです（再実行防止）。新しいコメントとして区別するには、文脈を加えてください。
• 重複タイトルの確認と照合では、最大1,000件をスキャンします。GitHub のイシュー一覧は書き込み後、数秒遅れることがあります。エージェント自身による重複はローカルで検出されますが、異なるエージェントが数秒以内に同じタイトルを提案すると、どちらも成功する可能性があります。
• to:<agent> ラベルを追加すると、そのラベルがリポジトリに存在しない場合は作成されます。
• agent-postbox は、レビューやコメントを編集または削除しません。これは意図した設計です。
• stdio 経由の serve は、設定やトークンがなくても起動するため、クライアントはツール一覧を取得できます。設定されるまでは、各ツールの呼び出しで CONFIG／TOKEN が返されます。一方、HTTP トランスポートは起動を拒否します。
• MCP サーバーと CLI がレシートファイルを共有している場合、ロックの競合によってサーバーが最大5秒間一時停止することがあり、複数のプロセスが同時に実行されると、1日の上限を数回の書き込み分超過する可能性があります。
• HTTP トランスポートはステートレスな JSON です（SSE、セッション、サーバー起点のメッセージには対応していません）。また、TLS もありません。マシンの外部に公開する場合は、独自のリバースプロキシの背後に配置してください。設計上、ブラウザーからのアクセスは遮断されます（JSON コンテンツタイプが必須で、Host はサーバーを指定する必要があり、AGENT_POSTBOX_HTTP_ORIGINS に登録されていない Origin は拒否されます）。
• 証跡ログが証明するのは、そこに書き込まれた内容であり、ログを迂回した内容ではありません。docs/evidence-format.md の「証明できないこと」を参照してください。末尾での切り詰めは署名付きの .head サイドカーファイルで検出されます。このサイドカーファイルが削除されると、evidence verify は正常に通過せず、警告を出します。

セキュリティモデル

agent-postbox は、よくある複数エージェントの障害リスクを軽減するように設計されています。サンドボックスではありません。

• 真の境界となるのはトークンです。 トークンを持つ人が GitHub を直接呼び出すことを、agent-postbox で阻止することはできません。エージェントごとにスコープを絞ったトークンを1つ使用し、ブランチ保護と必須レビューで main を保護して、マージは人間が行うようにしてください。
• 複数人による確認には、別々の ID が必要です。 2つのエージェントが同じトークンを共有している場合、GitHub には1人の作成者として表示されるため、複数人による確認では効果がありません。
• シークレットフィルターはベストエフォートです。 よくあるトークン形式やエントロピーの高い文字列を検出しますが、一部のシークレットを見逃したり、無害なテキストを誤検出したりすることがあります。
• 信頼できないコンテンツは、信頼できないままです。 agent-postbox は読み取ったすべての内容をデータとして扱います。それをエージェントが尊重するかどうかは、そのエージェント次第です。
• レシートはローカルの手がかりであり、正とするのは GitHub です。 レシートファイルは、ロックファイルの下でモード 0600 を設定してアトミックに書き込まれるため、MCP サーバーと CLI で共有できます。含まれるのはキー、状態、イシュー番号、リンク、HTTP ステータスコードです。メッセージ本文、タイトル、トークンは含まれません。
• マーカーは見えませんが、秘密ではありません。 書き込みにはすべて HTML コメントマーカーが付与されます。GitHub 上で、エージェント自身の ID が作成したコンテンツに、期待どおりの正確なテキストが含まれている場合にのみ信頼できます。
• 上限はローカルで適用されます。 1日の上限では、このマシン上のこのエージェントのレシートファイルに記録された書き込みを数えます。これはブレーキであり、GitHub が強制する割り当てではありません。
• テレメトリなし、ホステッドサービスなし。 agent-postbox は、指定されたトークンを使って api.github.com とのみ通信します。

脆弱性は SECURITY.md の説明に従って報告してください。

アクター、信頼境界、制御策、残存リスクについては、脅威モデルを参照してください。

AI 支援開発

このプロジェクトは、生成 AI ツールの支援を受けて開発されています。AI が生成した提案は、取り込む前にメンテナーが確認、選択、変更し、統合しています。第三者のプロプライエタリなソースコードは、プロジェクトに意図的に含めていません。AI による支援は、このプロジェクトおよびサードパーティ製依存関係のライセンス条件に影響しません。

免責事項

このプロジェクトは、Apache License 2.0 のもとで提供される無料のオープンソースソフトウェアです。

本ソフトウェアは「現状有姿」で提供されます。特定の本番環境、セキュリティ、コンプライアンス、法務、またはビジネス上の目的に適していることについて、いかなる表明や保証も行いません。

本ソフトウェアは GitHub のリソースと連携でき、設定によっては書き込み操作を実行する場合があります。重要なリポジトリや本番環境のワークフローで本ソフトウェアを使用する前に、付与する権限、設定、自動化または AI によって開始される操作の影響を確認する責任は、ユーザーにあります。

権限の制限、検証手順、シークレットのフィルタリングなどのセキュリティ対策はリスクを低減しますが、危険な操作、認証情報、シークレット、または意図しない出力をすべて検出または防止できる保証として扱ってはなりません。

この通知のいかなる内容も、適用法により除外または制限が禁止されている範囲において、責任を除外または制限するものではありません。

ライセンス

Apache License 2.0。Copyright 2026 Marco Gernand。貢献はDeveloper Certificate of Originに基づき歓迎します。