clawmail

Clawmail

joelclaw の標準的なエージェント調整コントラクトです。

joelclaw mail は、pi エージェントでサポートされている唯一のメールアクセス手段です。 エージェントのプロンプトや役割の指示から、mcp_agent_mail の HTTP エンドポイントを直接呼び出さないでください。

トポロジー

Agent-mail はマシンごとのメールボックスではなく、中央サービスです。

• Flagg は、権威あるデーモンを 127.0.0.1:8765 でホストします。
• Blaine と Panda は com.joelclaw.agent-mail-tunnel を実行し、ローカルの 127.0.0.1:8765 から Flagg へ SSH 経由で転送します。
• Satellite/Relay クライアントは、引き続きデフォルトのローカル URL を使用します。トンネルによって、tailnet 上で認証なしのサービスを公開せずに CLI コントラクトが維持されます。
• Satellite で独立した agent-mail デーモンを起動しないでください。正常なクライアントは、Flagg と同じメールボックス数／プロジェクト数を報告する必要があります。

管理対象のコネクターアセット：

• infra/agent-mail-tunnel.sh
• infra/launchd/com.joelclaw.agent-mail-tunnel.plist

インターフェース

標準インターフェース

• joelclaw mail ...（CLI）

Pi ラッパーツール（使用可能。ただし CLI を利用）

これらのラッパーは、内部で joelclaw mail をシェル経由で実行します。

ツール	CLI 相当
mail_send	joelclaw mail send
mail_inbox	joelclaw mail inbox
mail_read	joelclaw mail read
mail_reserve	joelclaw mail reserve
mail_release	joelclaw mail release
mail_status	joelclaw mail status

必須プロトコル（共有作業のデフォルト）

1. ファイルに触れる前に受信箱を確認する
   • joelclaw mail inbox --agent <AgentName> --unread
2. 作業範囲を開始時に通知する
   • joelclaw mail send --from <AgentName> --to <AgentName|team> --subject "Starting: <work>" "intent + paths + expected output"
3. 編集前にファイルパスを予約する
   • joelclaw mail reserve --agent <AgentName> --paths "path/a.ts,path/b.ts" [--ttl-seconds 900]
4. 作業が長引く場合は予約リースを更新する
   • joelclaw mail renew --agent <AgentName> --paths "path/a.ts" [--extend-seconds 900]
5. 作業中に状況報告や引き継ぎの更新を送信する
   • joelclaw mail send --subject "Status: ..." ...
6. コミットまたは引き継ぎ後に予約を解除する
   • joelclaw mail release --agent <AgentName> --paths "..."
   • または、予約したすべてのパスの作業が終わったら --all

件名の分類（検索性と進行管理のため）

次の接頭辞を一貫して使用してください。

• Starting: — 作業開始／意図の通知
• Task: — 引き継ぎまたは割り当て
• Status: — 進捗報告
• Blocked: — 介入が必要な依存関係／インシデント
• Done: — 成果物／コミット ID を添えた完了報告

日々の進行管理では、これらのシグナルを使ってプロトコルの逸脱を検出します。

コマンド早見表

# server + inbox health
joelclaw mail status

# register / refresh identity metadata
joelclaw mail register --agent MaroonReef --program pi --model gpt-5.4 --task "interactive"

# send a coordination message
joelclaw mail send --from MaroonReef --to BlueFox --subject "Task: update prompt docs" "Please edit SYSTEM.md and roles/*.md"

# inbox / read
joelclaw mail inbox --agent MaroonReef --unread
joelclaw mail read --agent MaroonReef --id 12

# reservations
joelclaw mail reserve --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md" --ttl-seconds 900
joelclaw mail renew --agent MaroonReef --paths "SYSTEM.md" --extend-seconds 900
joelclaw mail release --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md"
joelclaw mail release --agent MaroonReef --all

# audit/search
joelclaw mail locks
joelclaw mail search --query "Starting:"

信頼性チェック

プロトコルの正常性をすばやく確認する

joelclaw mail status
joelclaw mail locks
joelclaw mail search --query "Starting:"
joelclaw mail search --query "Status:"

joelclaw mail locks は、ローカルの git-mailbox にある file_reservations/ アーティファクトから、アクティブなアドバイザリーファイル予約を反映する必要があります（そのリポジトリが利用可能な場合）。これは、raw の /mail/api/locks エンドポイントでは、メールボックス内部のアーカイブ／コミットロックが表示されていても、ファイル予約が過少報告されることがあるため重要です。

検索が不調な場合（DB／ツールのエラー）

• シグナル数を信頼できないものとして扱ってください。
• それでもプロトコル（通知／予約／解除）に従ってください。
• メールバックエンドの正常性修復にエスカレーションし、調査結果を記録してください。

CLI フラグが予期せず拒否される場合

• コンパイル済みの ~/.bun/bin/joelclaw がソースに対して古くなっている可能性があります。
• packages/cli/src/cli.ts から CLI を再ビルドして、再試行してください。

ラッパーの出力が ok: true でも、ネストされた結果にエラーが含まれている場合

• 操作は失敗したものとして扱ってください。一部の CLI パスでは、result.result または result.raw に Too many open files、Agent not found、古いプロジェクトメタデータなどのバックエンドエラーが含まれていても、成功を示すエンベロープが返されることがあります。
• 予約／登録／受信トレイの呼び出しを確認するときは、最上位の ok フラグだけでなく、ネストされた結果を読み取ってください。
• バックエンドからキャッシュ済みリポジトリを解放したと通知された場合は、一度だけ再試行してください。それでも失敗する場合は、リスクの低い編集に限って続行し、最終サマリーで連携の失敗を報告してください。
• Too many open files. Freed 0 cached repos が繰り返し発生する場合は、lsof -p $(pgrep -f 'mcp_agent_mail.*serve-http') | rg '\.(archive|commit)\.lock' を調べてください。恒久的な修正は joelhooks/mcp_agent_mail にあります。孤立したロック FD を閉じ、メタデータがないロックをすぐに古いものとして扱わないようにし、infra/agent-mail-daemon.sh と infra/launchd/com.joelclaw.agent-mail.plist を使用して com.joelclaw.agent-mail を NumberOfFiles=8192 で実行してください。

プロンプト作成チェックリスト（プロンプトの強化）

連携について言及するプロンプト／ロール／システム契約には、次の内容を含めてください。

1. 標準プロトコルスキルとして clawmail を参照する。
2. メールへのアクセスには joelclaw mail を使用する（ラッパーは許可、MCP の直接利用は禁止）と明記する。
3. 最低限、受信トレイの確認、通知、予約、解放を含める。
4. 連携メッセージにパスのコンテキストを含めるよう求める。
5. 件名のプレフィックス（Starting:、Task:、Status:、Blocked:、Done:）の使用を推奨する。
6. 共有編集や連携を伴わない場合は、メールに関する不要な説明を避ける。

ステアリングループの統合

pi/extensions/session-lifecycle は、毎日のモニターとステアリングのレビューを実行し、次のイベントを発行します。

• agent-mail/steering.reviewed

スナップショットのパス：

• ~/.joelclaw/workspace/agent-mail-steering/YYYY-MM-DD.json

ずれが検出された場合は、ステアリングのヒントを使ってプロトコルの遵守を強化してください。

関連項目

• skills/agent-mail/SKILL.md（互換性エイリアス）
• joelclaw mail --help
• ADR-0172：MCP Agent Mail 経由の Agent Mail