proposal(storage): local-first replication for cross-machine agent teams

[orangewk]

背景

agmsg のチームを複数マシンにまたがって使いたいケースがあります。

例えば、Windows 上の Codex Desktop と Mac 上の Claude Code が、それぞれのマシンにしかないリポジトリや開発環境を担当している構成です。現在のローカル storage は単一マシンでは非常に扱いやすい一方、別マシンのエージェントへ仕事を引き継ぐには、利用者が SSH、共有 DB、ファイルコピーなどを別途設計する必要があります。

PR #389 は複数マシンの履歴をアプリで統合表示する提案ですが、remote source は read-only であり、エージェント間の送受信経路そのものは対象外です。Issue #208 は Redis に messages と team/run state を置く中央 network storage の提案です。本 Issue はそれとは異なり、各マシンのローカル操作経路を維持したまま eventual に複製する方式を検討するものです。

得たい UX

orange は Windows で Codex Desktop、Mac で Claude Code を動かしている。それぞれのエージェントは、そのマシンにある開発環境を担当している。

Mac の Claude が調査を終え、Windows の Codex へ続きを依頼する。

agmsg send codex "API 調査が終わりました。Windows 版の実装をお願いします"

Claude は、Codex が同じマシンにいるか、別のマシンにいるかを意識しない。SSH 接続先や remote DB を指定せず、従来と同じ agent name とコマンドを使う。

Windows が sleep 中でも、送信内容はまず Mac のローカル storage に確定する。相手マシンやネットワークの応答を待って Claude の turn が停止することはない。接続可能になった時点で同期され、Windows 側では通常の agmsg inbox として現れる。

Codex が返信すると、それも同じ仕組みで Mac へ届く。双方が一時的に offline でも、再接続後には同じメッセージ・既読状態へ収束し、重複取得によって同じ依頼を二度処理しない。

利用者から見ると、次の状態になります。

ひとつの agmsg team に参加する agent が、たまたま別の machine で動いている。

提案する capability

既存の per-team storage driver 境界を使い、opt-in の local-first replicated storage driver を追加できないでしょうか。

• send は最初にローカルへ durable に記録する
• remote の停止や network timeout を agent の hot path に持ち込まない
• 同期は retry 可能で、offline 後も eventual に収束する
• message ID と operation ID により import を冪等にする
• message と read state を同期する
• default の sqlite/local-only 動作と依存関係は変更しない
• transport は利用者が選んだ private な保存先を使い、public repository を前提にしない
• transport と delivery/wake は分離する。wake 非対応環境では次の turn や通常の inbox check で受信する

具体的な transport が Git、S3、その他の append-only store のどれであるべきかは、この Issue では確定しません。まず upstream の storage driver設計の中で、この local-first replication semantics を持つことが適切かを相談したいです。

既存設計との関係

• feat(storage): phase 2 — per-team storage backends (sqlite/jsonl, migrate, per-team watcher) #271 で導入された per-team storage driver / facade を拡張点として使う
• default zero-extra-dependency と opt-in driver の方針を維持する
• storage driver の現行 content/read-state invariants、UUID、export/import 契約に従う
• storage: redis network backend — multi-machine (messages + team/run state) #208 の中央 Redis storage とは、障害時 semantics と local state の扱いが異なる代替案になり得る
• feat(app): merge local and remote message sources #389 の remote history aggregation とは目的が異なり、併存も一方による置換もあり得る
• Codex Desktop: opt-in inbox monitor with thread wake and watchdog #374 / Codex Desktop: add native Scheduled inbox monitor #375 の Codex Desktop wake は delivery 側の課題として、この提案には含めない

fork での実証について

orangewk/agmsg では、Git を transport に使う proof of concept を実装し、複数環境間の message sync、offline 後の再同期、read receipt、重複排除まで動作確認しています。

• feat(remote): git-backed bus transport for multi-environment messaging (ADR 0005 MVP) orangewk/agmsg#14
• fix(remote): address PR #14 review — monitor-path pull, honest push failures, per-team bus namespace orangewk/agmsg#18
• feat(remote): ephemeral-environment ops — history cutoff (#19), pinned env ids (#15), one-line bootstrap (#17) orangewk/agmsg#20
• fix(remote): replicate read receipts across environments orangewk/agmsg#21

ただし、この実装は upstream の現在の per-team storage driver 設計より前に、独立した replication/transport 軸として作ったものです。event/schema、ID、storage と transport の責務分割などが現行 upstream 設計と完全には整合していません。そのまま merge を求めるものではなく、UX の実現可能性を示す PoC と設計材料として共有します。

相談したい点

1. local-first replicated storage は、agmsg の storage 軸に置く capability として適切でしょうか。
2. 複製対象は message + read state までとし、team registry や run/process state は machine-local に残す整理でよいでしょうか。
3. 設計方向が合う場合、既存 fork の PoC を upstream の driver contract に合わせて作り直す価値はあるでしょうか。

この Issue は設計提案のみで、現時点では実装 PR を前提にしていません。

[fujibee]

Thanks for this proposal — the problem framing, the relationship mapping to #208 / #271 / #389, and the working PoC in your fork make this very easy to follow.

Cross-machine team support is something we want to prioritize in upstream now. Our current plan is implementation-first: we will build a server-backed remote storage driver in upstream, and let that implementation settle the storage/driver design rather than fixing a contract on paper beforehand. The local-first direction you describe and your PoC are valuable reference material, and we will consult them as the design takes shape.

For the specific design questions (replication scope, contract details, how alternative transports could fit in), we would rather not commit to answers at this stage — they will be much clearer once the implementation has progressed, and we will follow up on this issue then.

---

日本語版(同内容):

提案ありがとうございます。問題設定、#208 / #271 / #389 との関係整理、fork での動作する PoC まで含めて、大変分かりやすくまとまっていました。

cross-machine 対応は upstream として今から優先度を上げる予定です。進め方は実装先行で、まず server-backed の remote storage driver を upstream で実装し、contract を紙上で先に確定するのではなく、その実装を通じて storage/driver 設計を固めていく方針です。ご提案の local-first の方向性と PoC は貴重な参考材料として、設計を進める中で参照させていただきます。

個別の設計論点(複製対象の範囲、contract の詳細、代替 transport の位置づけ)については、現段階で確定的な回答はせず、実装が進んで見通しが立った時点でこの issue でフォローアップさせてください。