mcpField
I
imsg-rpc

imsg-rpc

github.com/joelhooksクラウド・DevOps6535 回インストール1 日前に更新
リポジトリ

imsg-rpc について

imsg-rpcは、JoelClaw GatewayデーモンをiMessageに接続するlaunchdサービスを管理するスキルです。サービスの状態確認、アプリのビルドと署名、フルディスクアクセスの設定、ソケットのトラブルシューティングを扱います。

主な機能

  1. 01launchdサービスの管理
  2. 02ソケットとGatewayの状態確認
  3. 03imsgアプリのビルドと署名
  4. 04フルディスクアクセスの設定
  5. 05JSON-RPCソケット問題の調査

活用シーン

  1. 01iMessage Gatewayの接続確認
  2. 02新しいマシンでのサービス設定
  3. 03ソケットの欠落や無応答からの復旧
  4. 04フルディスクアクセス障害の診断

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/joelhooks/joelclaw --skill imsg-rpc

インストール後、Claude Code で/imsg-rpcを入力して読み込まれたか確認します。

同梱ファイルagents/openai.yaml

詳細

imsg-rpc スキル

ゲートウェイデーモンと iMessage を Unix ソケット経由で接続する com.joel.imsg-rpc launchd サービスを管理します。

アーキテクチャ（ADR-0121）

gateway daemon (bun, no FDA)
    ↕ JSON-RPC over /tmp/imsg.sock
imsg-rpc (com.joel.imsg-rpc launchd agent, has FDA)
    ↕ SQLite reads
~/Library/Messages/chat.db
  • ソース：~/Code/steipete/imsg（所有しているため、自由に変更できます）
  • ビルドバイナリ：~/Code/steipete/imsg/bin/imsg
  • 起動バイナリ：/Applications/imsg-rpc.app/Contents/MacOS/imsg
  • ソケット：/tmp/imsg.sock
  • launchd plist：~/Library/LaunchAgents/com.joel.imsg-rpc.plist
  • ログ：/tmp/joelclaw/imsg-rpc.{log,err}
  • ゲートウェイチャネル：packages/gateway/src/channels/imessage.ts

ステータスの確認

launchctl print gui/$(id -u)/com.joel.imsg-rpc | rg "state =|pid =|runs =|last exit code"
lsof -p "$(launchctl print gui/$(id -u)/com.joel.imsg-rpc | awk '/pid =/{print $3; exit}')" | rg "imsg.sock|chat.db"
lsof -nP -U | rg "imsg.sock|com.joel.gateway|/tmp/imsg.sock"  # gateway socket peer
tail -10 /tmp/joelclaw/gateway.log | rg imessage

正常な状態：PID があり、終了コードが 0 で、ゲートウェイに watch.subscribe OK と表示されます。

再起動

launchctl unload ~/Library/LaunchAgents/com.joel.imsg-rpc.plist
launchctl load ~/Library/LaunchAgents/com.joel.imsg-rpc.plist

imsg の再ビルド

署名を安定させ、/Applications/imsg-rpc.app をソースからのビルドと同期した状態に保つため、必ず build-local.sh を使用してください。make build は使用しないでください。

cd ~/Code/steipete/imsg && ./build-local.sh

build-local.sh は現在、次の処理を行います。

  • bin/imsg をビルドします
  • imsg Local Signing で署名します
  • scripts/install-rpc-app.sh を使って /Applications/imsg-rpc.app を更新し、署名します

FDA の設定（新しいマシン）

imsg バイナリにはフルディスクアクセスが必要です。macOS でこれを許可するには、検証可能なコード署名が必要です。

1. 既存の署名 ID を使用する

キーをエクスポートせずに、利用可能なコード署名 ID を確認します。有効な場合は、サービスで確立済みの ID を再利用してください。新しい ID が必要な場合は、承認済みのキーチェーン手順を使用してください。秘密鍵はキーチェーン内、またはタスク専用のアクセス制限付き一時ディレクトリに保管し、使用後に削除してください。共有の固定一時ファイル名や、ハードコードされたエクスポートパスワードは使用しないでください。署名前に ID と信頼性を確認してください。

2. ビルドと署名
cd ~/Code/steipete/imsg && ./build-local.sh
3. システム設定で FDA を許可する
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
  • + をクリックします
  • ⌘⇧G を押し、/Applications/imsg-rpc.app を貼り付けて、Enter キーを押します
  • ON に切り替えます
4. サービスを読み込む
launchctl load ~/Library/LaunchAgents/com.joel.imsg-rpc.plist

確認方法：tail -f /tmp/joelclaw/gateway.log | grep imessage を実行します。watch.subscribe OK と表示されるはずです。

トラブルシューティング

imsg-rpc.log に permissionDenied と表示される

FDA が設定されていないか、csreq が一致していません。次を確認してください。

sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db \
  "SELECT client, auth_value FROM access WHERE client LIKE '%imsg%';"
# auth_value 2 = allowed, 0 = denied

/usr/bin/log show --last 10m --style compact \
  --predicate 'process == "tccd" && (eventMessage CONTAINS "com.steipete.imsg" || eventMessage CONTAINS "kTCCServiceSystemPolicyAllFiles")' \
  | tail -80

拒否されている（0）場合：システム設定 → フルディスクアクセスに移動し、imsg をオンにします。 設定が見つからない場合：FDA 設定の手順 3 をやり直します。 /Applications/imsg-rpc.app/Contents/MacOS/imsg に対して tccd に AUTHREQ_RESULT ... authValue=2 と表示される場合、FDA は許可されています。

ソケットは存在するが、ゲートウェイがサブスクライブできない

imsg-rpc が接続を受け付けた後にクラッシュしました。/tmp/joelclaw/imsg-rpc.err を確認してください。サービスを再起動します。

launchd では実行中なのに connect ENOENT /tmp/imsg.sock と表示される

Unix ソケットのパスが削除されても、デーモンプロセスが実行状態を保つことがあります。ソケットのパスが再作成されるまで、ゲートウェイは接続できません。

launchctl kickstart -k gui/$(id -u)/com.joel.imsg-rpc
ls -l /tmp/imsg.sock

ゲートウェイは ENOENT が繰り返し発生すると自動で修復を試みるようになりましたが、インシデント発生時は手動で kickstart するのが最も迅速な復旧方法です。

再ビルド後も FDA の切り替えで解決しない

アプリバンドルを更新せずに再ビルドした可能性があります。次を再実行してください。

cd ~/Code/steipete/imsg && ./build-local.sh
imsg-rpc が再起動を繰り返す（終了コード 1）

FDA による拒否が考えられます。テストするには、ターミナルから実行してください。

/Applications/imsg-rpc.app/Contents/MacOS/imsg chats --limit 1

これで動作するのに launchd では失敗する場合、FDA の項目が誤ったパスまたは誤った署名を対象にしています。

JSON-RPC プロトコルリファレンス

ゲートウェイは /tmp/imsg.sock 経由で次のメソッドを使用します。

// Subscribe to incoming messages
{"jsonrpc":"2.0","method":"watch.subscribe","params":{"participants":["handle"]},"id":1}

// Send a message
{"jsonrpc":"2.0","method":"send","params":{"to":"handle","text":"..."},"id":2}

// Inbound notification format
{"jsonrpc":"2.0","method":"message","params":{"subscription":1,"message":{...}}}

ファイル

パス用途
~/Code/steipete/imsg/imsg のソース（所有しています）
~/Code/steipete/imsg/bin/imsgビルド済みバイナリ
/Applications/imsg-rpc.applaunchd プロセスの FDA 対象アプリバンドル
~/Code/steipete/imsg/build-local.shビルド＋署名＋アプリ同期
~/Code/steipete/imsg/scripts/install-rpc-app.sh/Applications/imsg-rpc.app を作成して署名
~/Library/LaunchAgents/com.joel.imsg-rpc.plistlaunchd サービス（git 管理外）
packages/gateway/src/channels/imessage.tsゲートウェイのソケットクライアント
apps/web/content/adrs/0121-imsg-rpc-socket-daemon.mdADR

コメント

Markdown 対応