agent-mail

Agent Mail — オプションの調整アダプター

Agent Mail はメッセージ、確認応答、ID、一時的なファイル予約を扱います。タスクトラッカー、キュー、証明台帳、ライフサイクルコントローラーではありません。

予約は助言的なものです。協調するすべての書き込み側が同じ絶対プロジェクトパスに照らして予約を確認することでのみ、競合を防ぎます。別のパス解決方法で登録された書き込み側が1つでもあれば、台帳全体が助言的な見せかけにすぎなくなります。Agent Mail は、確認しない書き込み側に何も強制しません。

名称付きの失敗モード — 沈黙をステータスとみなす：未回答のスレッドを「作業が停滞している」または「作業が完了した」と読み取ること。メールの沈黙が証明するのは、メールが届かなかったことだけです。

アンチパターン：競合が発生した際、求められていないのに予約の範囲を広げたり、期限を延長したりすること。是正措置：競合をそのまま呼び出し元に報告します。範囲や TTL の変更は呼び出し元が判断します。

境界

• 書き込み側が1つだけの場合、Agent Mail は使用しません。
• 絶対プロジェクトパス、エージェントの ID、スレッド ID、参加者、パス、排他性、理由、TTL は呼び出し元が指定します。
• 予約は、協調する書き込み側どうしの偶発的な重複を防ぎます。作業の所有権を確立することも、Plan、Candidate、または判定のセマンティクスに影響することもありません。
• メールの沈黙は、作業のステータスについて何も証明しません。
• メッセージや確認応答は、通信が行われた証拠であり、変更が正しい、または完了した証拠ではありません。このアダプターは、AgentOps のセマンティクスを選択したり、拘束力のある判定を下したり、ファクトリーでの完了を納品または検証の証明に変えたりすることはできません。
• 予約の解放は、force_release を含め、呼び出し元がその特定の予約について明示的に要求した場合に限ります。強制解放に自律的なトリガーはありません。競合は報告し、強制的に解消することはありません。
• Agent Mail が作業を選択したり、トラッカーの状態を変更したり、コードをコミットしたり、検証、統合、クローズ、リリース、納品を行ったりすることはありません。

モードと権限

互いに分離された2つの領域があります。最初の領域から2つ目の領域に進んではいけません。

• 調整モード（デフォルト）。 ID の登録、呼び出し元のパスの予約と解放、呼び出し元のスレッドの送信、読み取り、確認を行います。通常の使用はこれですべてであり、そのすべてが永続的な Agent Mail レコードを書き込みます。
• 管理／災害復旧モード（呼び出し元が明示的に許可した場合のみ）。 git の pre-commit ガードのインストール、doctor repair、バックアップ／復元、取り消し不能な clear-and-reset-everything は、別のモードです。それぞれの操作について、呼び出し元から明示的な許可を得る必要があります。いずれも調整の副作用として実行されることはありません。clear-and-reset-everything はデータベースとすべてのストレージを削除し、元に戻せません。呼び出し元から明示的な破壊的リセットの許可を得ていない場合は、--force が指定されていても、決して実行しないでください。

インターフェース

ストレージルートごとに、メールボックスの所有者とアクセスモードを必ず1つだけ選択します。HTTP／MCP デーモンがルートを所有している場合は、その MCP ツールを使用してください。同じデータベースを直接 am CLI に指定してはいけません。CLI による代替手段は、実行中の Agent Mail ランタイムが所有していないルートに限り使用してください。メールボックスのアクティビティロックが使用中の場合や、制限時間付きの読み取りがタイムアウトした場合は、アダプターの機能低下を示す結果です。サービスの再起動、データベースの修復、通知なしのルート切り替えを許可するものではありません。

MCP ツールが利用できる場合は、それを使用してください。利用できない場合は、自己記述型の am CLI を使用します。意図するストレージルートを明示的に指定し、am mail --help、am file_reservations --help および関連するグループのヘルプで現行の構文を確認してください。記憶しているエイリアスからコマンドを推測してはいけません。macOS からの直接読み取りで、/var のようなシンボリックリンクされたスナップショットディレクトリが拒否された場合は、その個別の呼び出しに限り、呼び出し元のスコープ内にあるシンボリックリンクでない一時ディレクトリを使用するか、アダプターの機能低下を報告してください。トラバーサルチェックを決して緩和してはいけません。

ワンショットでの使用

1. 明示的に連携する複数のライターがリポジトリを共有していることを確認します。
2. 1 つのストレージルートと、MCP／サーバーモードまたは直接 CLI モードのいずれかを固定します。同じ稼働中のデータベースに両方を混在させてはいけません。
3. 呼び出し元から指定された ID を、同じ絶対パスのプロジェクトに登録します。
4. 指定されたパスのみを、上限のある TTL で予約します。
5. 待機したり、範囲を狭めたり、計画を変更したりせず、競合を報告します。
6. 指定されたメッセージを 1 回送信し、その ID を記録します。
7. 指定されたスレッドのみを読み取るか、確認応答します。
8. 呼び出し元が宣言済みの移行を進める前に、その移行で確認応答が必要なすべてのメッセージについて、意図された受信者から確認応答を得ていることを検証します。後続のやり取りは、暗黙の確認応答にはなりません。
9. 呼び出し元から明示的に解除を求められた予約のみを解除します。

出力

プロジェクト、ID、スレッド／メッセージ ID、予約 ID とパス（TTL を含む）、競合、タイムスタンプを返します。その後の判断はすべて呼び出し元が行います。

終了状態は明示し、決して黙って処理してはいけません。

• アダプターが利用不可 — MCP ツールも am CLI も存在しません。Agent Mail が利用不可であることを報告して停止します。手書きの連携にフォールバックしたり、不在を「競合なし」と見なしたりしてはいけません。
• 予約の競合 — 競合する予約をそのまま報告します。範囲を狭めたり広げたり、更新したり、強制解除したりしてはいけません。
• メールボックス所有権の競合 — デーモンと直接 CLI が 1 つのストレージルートを取り合っています。ロックの所有者／モードを報告して停止します。連携の副作用として、ロックを再起動、修復、回避してはいけません。
• 必須の確認応答が保留中 — 正確なメッセージと意図された受信者を報告し、依存する移行を停止します。後続の返信から確認応答を推測したり、検証後に修正したりしてはいけません。
• タイムアウト／機能低下 — タイムアウトまたは機能低下として操作を報告し、観測できた内容とできなかった内容を明示します。タイムアウトは証拠であり、「完了」ではありません。
• クリーンアップ — このセッションで解除した予約を ID ごとに列挙します。残した予約（TTL が有効なもの）も名前を挙げ、呼び出し元が残存状況を確認できるようにします。

参考資料

• CLI と MCP のインターフェースに関する注記
• 連携パターン
• トラブルシューティング