Messenger gateway

English · 한국어 · すべてのページ

ゲートウェイは、チャットプラットフォームをセッションまたは名前付きエージェントに接続します。そのチャットのメッセージがプロンプトになり、エージェントの答えがメッセージとして返り、承認はボタンとして届きます。v0.1 で完全にサポートされているプラットフォームは Telegram です。Discord と Slack は同じインターフェースを実装しており配信も動きますが、実戦での時間はその分少なめです。

The short way

snowpea setup --gateway telegram --token 123456:ABC-your-bot-token --user-id 987654
snowpea            # or: snowpea daemon start

セットアップはこれで全部です。ウィザードがメッセンジャーを settings.json に記録し、デーモンは起動時にそれを キャッチオール のバインディングに変えます。ボットにメッセージを送ったチャットはそれぞれ自分のセッションを得ます。作業ディレクトリは、gateway.telegram.workdir を設定しない限り $HOME です。立ち上がると snowpea daemon status が messengers telegram (listening) と表示します。トークン自体はモード 0600 の $SNOWPEA_HOME/credentials.json にコピーされ、他の場所では名前で参照されるだけなので、state.db にも、RPC の結果にも、ログの行にも決して現れません。

--user-id はそのプラットフォーム上のあなた自身の数値アカウント ID で、チャットから承認に答えられる唯一のアカウントです。Telegram では @userinfobot に /start を送れば自分の ID が分かります。省略してもメッセンジャーは会話しますが、承認ボタンの押下はすべて — あなた自身のものも含めて — 拒否されます。

ウィザード（または settings.set）でメッセンジャーをオフにすると、そのバインディングは取り除かれます。手で作ったバインディングがこれで触られることはありません。

Binding by hand

キャッチオールのセッション1つではない何か — 名前付きエージェント、特定のチャット1つ、1つのプラットフォーム上の2アカウント — がほしいときに使います。

snowpea gateway bind telegram TELEGRAM_BOT_TOKEN agent:scribe --user 987654
snowpea gateway bind telegram TELEGRAM_BOT_TOKEN new:~/src/api --channel 123456 --user 987654
snowpea gateway list --json
snowpea gateway unbind <binding-id>

3つの位置引数は、プラットフォーム、認証情報の参照（credentials.json のキー、または環境変数の名前）、そしてターゲットです。

Target	Meaning
agent:<name>	独自のメモリ名前空間を持つ、名前付きの永続エージェント
session:<id>	既存のセッション
new:<workdir>	最初のメッセージでそのディレクトリにセッションを作る

--channel はバインディングをチャット ID 1つに限定します。--user は承認に答えてよいプラットフォーム上のユーザーを指定します。両方を設定してください。--user がないと承認に答える権限を持つ人が誰もおらず、ゲートウェイは誰のボタン押下も無視します。

Getting a bot

Telegram. @BotFather に話しかけ、/newbot、トークンを控えます。チャット ID は、あなたがメッセージを送ったときにボットが見る数値で、最初の受信メッセージでデーモンのログに出ます。ロングポーリングを使うので、公開 URL も webhook も不要です。

Discord. アプリケーションを作り、ボットユーザーを追加し、message content intent を有効にし、サーバーに招待し、ボットトークンを控えます。チャンネル ID はチャンネル URL の最後のパスセグメントです。

Slack. アプリを作り、chat:write とワークスペースに必要なイベントを追加し、インストールし、ボットトークンを控えます。ターゲットにはチャンネル名または ID を使います。

Talking to it

ボットにメッセージを送れば、もうセッションの中です。コマンドのレジストリはコアにあるので、スラッシュコマンドはターミナルとまったく同じように動きます。

/mode
/ralph fix the failing integration test
/schedule "매일 09:00" "어제 커밋 요약" --channel telegram:123456

ゲートウェイが作ったセッションは、その出自つきで session.list に現れるので、同じデーモンに接続した TUI からチャットが何をしているかが見えます。

Unattended approvals

ゲートウェイやスケジューラのセッションが上げた承認は無人であり、あなたが打ち込んで起こしたものとは振る舞いが異なります。

• 接続中のすべてのクライアントに approval.pending 通知としてブロードキャストされるので、TUI の承認待ち行列に現れます。
• allow と deny のボタンつきで、バインドされたチャットに送られます。
• どちらの側であれ最初の回答が勝ちます。他の全員には、決定とそれを下した人を示す approval.resolved が届きます。
• チャットから答えられるのはバインドされた --user だけです。他の誰かの押下は無視され、ログに残ります。
• approvals.timeoutSec（デフォルト300秒）のあいだ回答がなければ拒否されます。

TUI で自分が打ち込んで起こした承認は、その面に留まり、共有の待ち行列には決して入りません。この境界こそが要点です。自分のターミナルの確認がグループチャットに漏れることはなく、チャットの承認を見知らぬ人が答えることもできません。

決定されたことはすべて、リクエスト ID、ツール、決定内容、決定者、スコープ、そして無人だったかどうかとともに $SNOWPEA_HOME/logs/approvals.jsonl に追記されます。

Named agents

名前付きエージェントは、自分のセッション、自分のメモリ名前空間、自分のチャンネル、自分のジョブを持ったまま、デーモンの再起動を越えて生き延びます。2つの名前付きエージェントが互いのメモリを読むことはできません。だからこそ、一方に仕事用のチャンネルを、もう一方に個人用のチャンネルを与えるのが理にかなうのです。

snowpea agents --json

/agent create "<description>" で作り、gateway bind ... agent:<name> でチャンネルを紐づければ、次のデーモン起動時にバインディングごと復元されます。名前付きエージェントは4つ目のキープアライブのカウンターなので、1つでもあればデーモンはアイドルで終了しません。

Security

ゲートウェイはリモート実行の経路です。そのように扱ってください。

• --user をバインドすること。必ず。
• 完全には掌握していないチャットから届くものには plan モードを選ぶこと。
• 承認リクエストは1回きりで、1つのリクエスト ID に結びついています。ボタン押下を再生しても何も起きません。
• 認証情報は 0600 のファイルに置かれ、利用できる場合は OS のキーチェーンが使われます。
• ときどき approvals.jsonl を読むこと。あなたが見ていないあいだに何が許されたかの記録です。

Next

Backends — ツールを別の場所で走らせる。