agmsg × antigravity(agy) 統合解説書v1.0(2026-08-03)

公開 2026年8月3日

1. これは何か
2. インストールと使い方
3. 仕組み(アーキテクチャ)
4. 同梱ファイル(sources/・全15件・md5で正本一致確認済み)
5. 障害時の手がかり
6. 配置先の対応(実処理の正本=`~/.agents`側。本パッケージは配布物)
7. 更新履歴・歴史資料・上流関連(参考)

(配布ファイル「antigravity.zip」は現在提供していません)

パッケージ版数: v1.0(2026-08-03)/ 種別: 解説・配布用パッケージ
対象: antigravity CLI(agy)の席を agmsg チームで使えるようにする仕組み一式。
実際に処理へ使われている正本は `~/.agents/` 側(対応表は§6)。本パッケージはその
解説書+配布用完全セット(sources/ 15件+install.sh)で、これだけで別環境へ導入できる。
導入方法は§2.1、実装を修正した時は本パッケージへ反映して版数を上げ§7へ履歴を書く。

1. これは何か

1.1 agmsg と「席」

agmsg はbash製のエージェント間メッセージング基盤(`~/.agents/skills/agmsg/`)。
チームに 席(seat)= (team, agent, project) の三つ組 としてエージェントを登録し、
sqlite DB 経由でメッセージを送受信する。主要コマンド: `join.sh`(登録)/`send.sh`(送信)/
`inbox.sh`(未読取得)/`history.sh`(履歴)。

1.2 antigravity(agy)

Google の Antigravity CLI(Gemini系エージェントTUI)。単体実行ファイル `agy` として
インストールされ(既定では `%LOCALAPPDATA%\agy\bin\agy`)、PATHが通っていれば
どこからでも起動できる。サブスク(Google AI Pro等)経路で動作する。

1.3 この統合が解決すること

agyには起動フックもグローバル設定も無く、席として登録しても
①どの会話に配送するか(束縛)②未読をどう知らせるか(監視)③誰がそれを起動・停止するか(運用)
がすべて課題になる。本統合はこの3つを1コマンドで全自動にする。

2. インストールと使い方

2.1 インストール(新しい環境への導入)

前提条件:

| 必要物 | 確認方法 | 備考 |
|---|---|---|
| Windows + Git for Windows(Git Bash) | `bash --version` | MSYS環境。スクリプト実行基盤 |
| PowerShell 7(pwsh) | `pwsh -v` | 5.1不可(`??`演算子・`-SkipCertificateCheck`使用) |
| python3(Git Bash内) | `python3 -V` | ランチャの席逆引きに使用 |
| sqlite3.exe | `sqlite3 -version` | pollerの未読検知に使用(WinGet導入でも可・自動探索あり) |
| agmsg本体 | `~/.agents/skills/agmsg/` が存在 | 本パッケージはagmsg本体を含まない |
| antigravity CLI(agy) | `agy --version` | PATHが通っていること |

手順:

# 1. 本パッケージのディレクトリで(差分確認→配置→md5検証まで自動)
bash install.sh            # 確認だけなら: bash install.sh --check

# 2. 席を登録(初回のみ。チーム・エージェント名・プロジェクトパスは環境に合わせる)
~/.agents/skills/agmsg/scripts/join.sh <team> <agent> antigravity "<プロジェクトのWindowsパス>"

# 3. 起動して動作確認(§2.2)

install.sh がやること: sources/ の15ファイルを§6の配備先3箇所へコピーし、md5で検証する。
既存ファイルは上書きされる(差分は実行時に表示。`--check`で事前確認可能)。

2.2 使い方(日常)

cd <プロジェクト>
& "$env:USERPROFILE\.agents\bin\agy-team.cmd"     # 開く=繋がる

席が自動で逆引き表示される(例 `seat: admin/antigravity`)。複数候補なら列挙されるので
`agy-team <team> [agent]` で指定
agyが普通に開く。最初の一言(内容自由)を入力すると会話が生まれる
以後は全自動: 会話の特定→席の記録→監視(poller)起動。席宛のagmsgメッセージが
自動で画面に届き、返信もagent自身が`send.sh`で行う
agyを閉じると監視も自動停止(片付け不要)

事前条件: 席が未登録なら先に `join.sh <team> <agent> antigravity "<プロジェクトパス>"`。

3. 仕組み(アーキテクチャ)

3.1 データフロー

agy-team.cmd → agy-team.sh ──(前景)── agy 本体(TUI)
                   │                     │ 終了
                   │(detach)             └→ lease削除 → poller自主停止
                   ▼
        agy-seat-bootstrap.ps1(自動束縛)
          ①祖先チェーンでagy pid帰属 → ②そのpidのLISTENポート
          → ③会話特定(ちょうど1件になるまで待つ) → ④席の記録
          → ⑤lease書込 → ⑥poller起動
                   ▼
        monitor-api.ps1(poller・常駐)
          agmsg DB未読検知 → agyのローカルAPIで会話へwakeメッセージ注入
          → 未読が消費されたことを確認(成功判定)

3.2 技術的な土台(agyのローカルAPI)

agyは窓(インスタンス)ごとにローカルLanguage ServerをHTTPS(自己署名・認証なし)でLISTENする:

POST https://127.0.0.1:<port>/exa.language_server_pb.LanguageServerService/<RPC>

| RPC | 用途 | 重要な性質 |
|---|---|---|
| `GetAllCascadeTrajectories` `{}` | 会話一覧 | port-local: その窓が開いている会話しか返さない(負試験で実証)。束縛設計の土台 |
| `SendUserCascadeMessage` | 会話へメッセージ投入 | `requestedModel`はメッセージ型`{"model":"<enum名>"}`。文字列で渡すとリクエスト拒否(steps増えず)で配送されない |
| `GetCascadeTrajectorySteps` | 会話のステップ取得 | こちらはどのポートからでも引ける(GetAllと混同しない) |
| `GetAvailableModels` `{}` | モデルenum名一覧 | `MODEL_GOOGLE_GEMINI_2_5_FLASH`等。`MODEL_PLACEHOLDER_*`は不可 |
| `Heartbeat` `{}` | 疎通確認 | — |

注意: 未知のJSONフィールドは黙って捨てられる(成否は必ずtrajectoryで確認)。
PowerShell 7では`-SkipCertificateCheck`必須。ポートは起動ごとに変わる。
課金はサブスク枠(`daily-cloudcode-pa.googleapis.com`)。公式Python SDKは別物・従量課金のため不使用。

3.3 束縛(どの会話に配送するか)

wakeを間違った会話に注入すると「他プロジェクトの中断」+「本来の席が起こされない」の
二重事故になるため、束縛は厳格に:

正本 = 席→会話の記録 `run/role-session.<team>__<agent>`(`session=<会話UUID>`)
記録のガード(`antigravity-record-session.sh`): UUID形式のみ/他席と同一会話の重複禁止/
壊れたproject値は記録しない
配送側は毎周期、記録の会話が「起動規約(`--add-dir <プロジェクト>`)一致のagy窓の
port-local一覧に実在し workspace一致」することを再検証。検証に落ちたら配送拒否
(推測に降格しない)
自動束縛(bootstrap)は「所有権チェーン」= 起動したagyのpid(祖先チェーン≤4段で帰属)→
そのpidのポート→その窓の会話一覧、が繋がりちょうど1件の時だけ記録する。
0件/複数/エラー/タイムアウトは常に「未束縛・poller起動なし」(誤動作でなく不作為に倒す)

3.4 監視(poller)の寿命管理

lease方式: bootstrapが`run/agy-lease.<team>__<agent>`(nonce入り)をatomicに書き、
pollerは毎周期チェック。ファイル消滅 or nonce不一致で自主停止
agy終了時: ランチャが自分のnonceのleaseを消し、自nonceのpollerだけ止める
世代交代: 新しい起動が新nonceのleaseを書く→旧pollerは≤1周期で自主停止→
新pollerが起動(mutexが空くまでbootstrapがretry)。常に1本に収束
mutex(席+プロジェクトのハッシュ)で同一席の多重pollerを構造的に防止

3.5 wake(起こし方)と成功判定

wake文には実行すべきコマンドを一字一句埋め込む
(`Run EXACTLY: bash ~/.agents/skills/agmsg/scripts/inbox.sh <team> <agent> ...`)。
曖昧な指示はagentがチーム名を推測して誤る(実例あり→§7)
成功判定は「送信時点の未読が減った」= 席がinbox.shを実行した運用上のE2E指標
(因果証明ではない点に留意)。RPC受理・画面表示は根拠にしない
頻度制御: 最小間隔60秒(1 wake=agyの1ターン=クォータ消費)。失敗時は指数バックオフ+
managerへ1回だけ`[UNDELIVERABLE]` bounce

3.6 安全設計の性質(まとめ)

| 性質 | 実現方法 |
|---|---|
| 誤配送しない | 束縛は証明時のみ/記録の毎周期再検証/曖昧なら拒否+bounce |
| 誤束縛しない | 祖先チェーン帰属・port-local列挙・ちょうど1件ルール |
| 監視が漏れ残らない | lease所有権(nonce)で自主停止。stopは自nonce限定 |
| 二重化しない | mutex+世代交代の収束 |
| injectionされない | パス等の任意文字列はPSコマンド文字列に載せずenv継承 |
| 壊れても安全側 | 全経路が「自動化が効かない」に倒れる |

4. 同梱ファイル(sources/・全15件・md5で正本一致確認済み)

4.1 `sources/bin/` — ランチャ(正本: `~/.agents/bin/`)

| ファイル | 役割 |
|---|---|
| agy-team.sh | 本体: 席逆引き→自winpid取得→bootstrap起動→agy前景実行→終了時の後片付け |
| agy-team.cmd | PowerShell/cmd用の入口(ASCIIのみ。cmd.exeはOEMコードページのため) |

4.2 `sources/integration/` — 実体(正本: `~/.agents/agmsg-local/integration/antigravity/`)

| ファイル | 役割 |
|---|---|
| agy-seat-bootstrap.ps1 | 自動束縛の核(§3.3の所有権チェーン+§3.4のlease+世代交代retry) |
| antigravity-record-session.sh | 席→会話の記録(§3.3のガード群) |
| monitor.sh | poller の start/stop/status。席自己記録ルールの自動配置も担う |
| monitor-api.ps1 | poller本体(§3.4-3.5) |
| agmsg-seat-recording.md | 席自己記録ルール(agyのプロジェクトルールとして配置。自動束縛が未束縛で終わった時のフォールバック) |
| monitor-win.ps1 | 廃止済み旧方式(§7参照。歴史資料) |

4.3 `sources/agmsg-tree/` — agmsgツリー側(正本: `~/.agents/skills/agmsg/scripts/drivers/types/antigravity/`)

| ファイル | 素性 | 役割 |
|---|---|---|
| _delivery.sh | 実体 | 配送定義(actasベースの送信経路) |
| type.conf | 実体 | 席種宣言(monitor=no — monitor相当は外部pollerで実現) |
| template.md | 実体 | join時に席へ渡されるテンプレート |
| monitor.sh / antigravity-record-session.sh / monitor-api.ps1 | forwarder | integrationの実体へexecする橋(agmsg更新で消えたら`reapply.sh`が再設置) |
| monitor-win.ps1 | 実体・廃止済み | 歴史資料 |

4.4 手動での配置(install.sh を使わない場合の参考)

通常は §2.1 の `install.sh` を使えばよい。手動なら §6 の対応表どおりに3ディレクトリへ
コピーするだけ(_delivery.sh/type.conf/template.md/monitor-win.ps1 はagmsg本体にも
元から含まれるが、上書きしても同一内容)。その後 `join.sh` で席登録 → `agy-team.cmd`。

5. 障害時の手がかり

自動束縛の経過: `run/agy-bootstrap.<team>__<agent>.log`
pollerの動作: `run/agy-apimon.<team>__<agent>.log`(CONSUMED=成功/NOT consumed/bounce/FATAL)
席の記録: `run/role-session.<team><agent>` / lease: `run/agy-lease.<team><agent>`
pollerの状態確認: `monitor.sh status <team> <agent>`
手動復旧(ランチャを使わない従来運用): agy窓内で
`antigravity-record-session.sh <team> <agent>` → `monitor.sh start <team> <agent> <project>`
(lease無し起動=無期限常駐)

6. 配置先の対応(実処理の正本=`~/.agents`側。本パッケージは配布物)

| パッケージ(sources/) | 配置先(=実際に処理へ使われる正本) |
|---|---|
| sources/bin/* | `~/.agents/bin/` |
| sources/integration/* | `~/.agents/agmsg-local/integration/antigravity/` |
| sources/agmsg-tree/* | `~/.agents/skills/agmsg/scripts/drivers/types/antigravity/` |

`install.sh` はこの表のとおりに配置する。agmsg本体の更新でツリー側forwarderが消えた
場合も `install.sh` の再実行で復元できる(既存の `reapply.sh` とは独立に本パッケージ
だけで完結)。実装を修正した時は、正本(`~/.agents`側)での動作確認後に本パッケージの
sources/ へコピーし直し、版数を上げて§7に履歴を書く。

関連文書: 姉妹パッケージ「高速化レイヤー(accel)解説書」=`../accel/`。
agmsgへのローカル改変全体の台帳は配備先の `~/.agents/agmsg-local/BOUNDARY.md`(導入環境ごとに育てる)。
Agent APIのRPC仕様の要点は§3.2に記載。

7. 更新履歴・歴史資料・上流関連(参考)

7.1 方式の変遷

| 世代 | 時期 | 方式 | 廃止理由 |
|---|---|---|---|
| 第1世代 | 〜2026-07 | VS Code拡張・個別の未読通知スクリプト | 単一チーム時代の遺産。手動・不確実 |
| 第2世代 | 2026-07-31 | `monitor-win.ps1` — WriteConsoleInputでキー入力を偽装しTUIへ打鍵 | フォーカス・タイミング依存で壊れやすい。会話特定も曖昧 |
| 第3世代 | 2026-08-01 | `monitor-api.ps1` — ローカルConnectRPC(Agent API)発見により公式経路で会話へ直接投入 | (現行) |
| +ランチャ | 2026-08-03 | `agy-team` — 記録・監視の起動/停止も全自動化(「LLMに定型作業をさせない」) | (現行) |

背景: Agent API発見(2026-08-01)以前は、idle状態のagyを外部から起こす確立手段が無かった
(当時idle wakeが確立していた席種はclaude-codeのみ)。APIの発見はOSS実装(dwgx/WindsurfAPI)の
解析が最短路だった。

7.2 主要な修正の履歴(2026-08-03・agy-team導入時)

codexレビュー3周(プラン→実装→再レビュー)でadopt。主な指摘と対処:

束縛前提の検証: GetAllのport-local性を、別プロジェクトの2窓を同時に開いた負試験で証明(各窓のポートは自窓の会話のみを返し、相互に見えない)
帰属レース: snapshot差分→祖先チェーン(≤4段・全リンク生存)へ
lease世代交代の穴: 旧pollerのmutex保持中はstartが無効→自nonce可視までretryへ
quote breakout: パスをPSコマンド文字列から全排除(env継承)で構造的に解決
フィールド試験での発見2件: ①MSYSが外部exe起動に中間スタブbashを挟み「直接の子」判定が
不成立(→祖先チェーンの直接の動機) ②wake文が曖昧だとagentがチーム名をフォルダ名から推測し
廃止チームのinboxを見て「未読なし」と誤答(→コマンド一字一句指定の直接の動機)
(観察)agentはinbox内容や差出人を画面表示用に脚色することがある。配送成否の正はDB側

7.3 実証状況(2026-08-03時点)

実証済み: 新規窓の束縛・配送往復(未読消費+席からの返信受信)・lease自主停止(約5秒)・
世代交代(3世代)。保留: agy-team 1発の完全自走E2E(束縛は手動bootstrap再実行で実証済み・
次回起動が初回)/dual-launcher同時起動/apostrophe入りパスの実地試験。

7.4 上流(agmsg作者)との関係

本統合による上流agmsg・agy本体の改変はなし。ツリー内のantigravity系3ファイルは
実体をローカル層へ移した数行のforwarder(agmsg更新後は`reapply.sh`で再適用)
agmsg側には別系統の`instance-id.sh`1関数パッチが存在(pid-domainバグ・上流へ#567として
報告済み。修正入り上流版を検出したら自動退役)。詳細はaccel解説書
Windows環境の性能問題は#449として上流へ報告済み(高速化はすべて外部レイヤーで実施)

【宣伝】SwitchBot 購入はこちらから

SwitchBot公式ページ
クーポン「AF-4903」で5％引き（アフィリエイトクーポンになりますのでご協力お願いします）
割引の詳しい仕組みに関してはこちらのページを参照ください。
製品ごとの特徴・紹介動画は SwitchBot 製品ガイドにまとめています。

How to Get the Lowest Price on the SwitchBot Official Store (US, UK & EU): The Complete Checkout Strategy — August 2026

当ページの商品リンクは基本アフィリエイト（SwitchBot、Amazon、楽天、アリエクスプレス他）となっております。ご協力いただければ幸いです。

agmsg × antigravity(agy) 統合 解説書v1.0(2026-08-03)