gateways/

1 つのフォルダに、2 つの無関係な仕事: エージェントを公開することと、チャットプラットフォームをそれに接続すること。

gateways/

この 1 つのフォルダの下にある gateways/*.bx/.json ファイルは、2 つの別個の、無関係なことをカバーしています - あるエントリがどちらの種類かは、その configure() 構造体が exposes キーを持つかどうかだけで決まります。

flowchart TD
    F["a file under gateways/"] --> Q{"does configure() return<br/>an 'exposes' key?"}
    Q -->|"yes"| E["EXPOSURE<br/>a route into your agent"]
    Q -->|"no - it has a 'type' key instead"| C["CHANNEL ADAPTER<br/>a connection to a chat platform"]
    E --> E1["exposes: agent<br/>route().toAi()"]
    E --> E2["exposes: mcp<br/>route().toMCP()"]
    E --> E3["exposes: webui<br/>generated index.html + /api"]
    C --> C1["mock / cli / http<br/>pull-driven: something calls US"]
    C --> C2["telegram, slack, discord, email, whatsapp-cloud,<br/>teams, twilio, github, signal<br/>push-style: holds its own connection"]
    C2 --> S["one GatewaySession<br/>bound to the root agent"]

    style E fill:#d4edda,stroke:#155724
    style C fill:#cce5ff,stroke:#004085

1. HTTP/MCP/Web UI 公開 (exposes: "agent" | "mcp" | "webui")

ColdBox 8.1 のネイティブな AI Routing DSL を使って、エージェント、またはローカル MCP サーバーを HTTP 経由で公開します - あるいは、Web チャット UI で別途解説している、あらかじめビルドされたブラウザチャット UI として公開します。

エージェントを公開する:

// gateways/expose.bx
class {

	function configure() {
		return {
			exposes : "agent",
			path    : "/api/chat"
		};
	}

}

config/Router.bx に、以下を生成します。

route( "/api/chat" ).toAi( "GeneratedAgent" )

これは4 つのサブルート: POST /api/chat/invoke、POST /api/chat/stream (SSE)、POST /api/chat/batch、GET /api/chat/info を自動登録します。素の /api/chat パス自体はルーティング対象ではありません。

ローカル MCP サーバーを公開する (mcp/ 参照):

class {
	function configure() {
		return {
			exposes : "mcp",
			path    : "/mcp/tools",
			target  : "local-server"   // must match an mcp/*.bx entry's declared name
		};
	}
}

route( "/mcp/tools" ).toMCP( "local-server" ) を生成します。

v1 の Web チャット UI を公開する:

// gateways/chat.bx
class {
	function configure() {
		return {
			exposes     : "webui",
			path        : "/chat",
			apiKeyEnvVar: "CHAT_UI_API_KEY"   // optional - see below
		};
	}
}

実際の静的な <path>/index.html ファイル (直接配信され、ルートは不要です) に加えて、固定された <path>/api プレフィックス配下の専用 API を生成します。これにより、シェル自身のファイルと衝突することは決してありません。その API は toAi() ではなく生成された handlers/ChatUi.bx であり、このエントリは生成された SQLite ストアも一緒に持ってきます。

Web UI は単一の公開スイッチというより 1 つのサブシステムです - ルート一覧、ストア、会話と設定、ブランディングとテーマ、そしてなぜ toAi() を使わないのかは、すべて独自のページにあります: Web チャット UI。

検証: exposes は agent、mcp、webui のいずれかである必要があります。path は必須で、すべての公開エントリの間で一意である必要があります。mcp 公開の target は必須で、実在する mcp/* エントリの宣言された名前と一致する必要があります。webui の apiKeyEnvVar は完全に任意で、必須フィールドチェックはありません (下記参照)。

2. チャネルアダプタゲートウェイ (type: "mock" | "cli" | "http")

bx-ai の IGateway (外部配信 / human-in-the-loop 承認用のチャネルアダプタ) を名前で登録します - エージェント自身の REST API を公開するのとは別物です。

// gateways/slack.bx
class {
	function configure() {
		return {
			type         : "http",
			secretEnvVar : "SLACK_WEBHOOK_SECRET"
		};
	}
}

secretEnvVar は署名シークレットを保持する環境変数の名前を指定します - シークレットの値そのものではありません。Application.bx の onApplicationStart() に、以下を生成します。

aiGatewayRegistry().register( aiGateway( "http", { secret : getSystemSetting( "SLACK_WEBHOOK_SECRET", "" ) } ) )

シークレットはサーバー起動時にライブに解決され、このプロジェクトの他の箇所すべてと同じ「シークレットは常に外部に置く」というルールに従います (デプロイとシークレット 参照) - 生成されたソース内にリテラルとして埋め込まれることは決してないため、パッケージ化された .bxa にも含まれることは決してありません。環境変数が未設定の場合、bx-ai 自身の HttpGateway は空のシークレットを「署名が設定されていない」として扱い、起動時にクラッシュするのではなく、それに応じてリクエストを拒否します。

検証: type は mock、cli、http のいずれかである必要があります。type: "http" エントリには secretEnvVar が必須です。エントリ自身のファイル/ベース名は、すべてのチャネルアダプタエントリの間で一意である必要があります。mock はテスト専用です。cli は bx-ai 自身に組み込まれた human-in-the-loop 承認チャネルです (ブロッキングな stdin/stdout の A/R/Q プロンプト) - これは、ゲートウェイが指定されていない場合に HumanInTheLoopMiddleware がデフォルトでアタッチするもので、ゲートウェイレジストリに一切触れない BX Agents 自身の chat 動詞とは無関係です。

http タイプのエントリはさらに、実際の HTTP 配線を得ます: bx-ai 自身の GatewayRequestProcessor::processHttp() に直接プロキシする、生成された handlers/Gateway.bx アクションと、config/Router.bx の 3 つのルートです。

post( "/gateways/:gatewayName/events" ).toHandler( "Gateway.process" )
get( "/interactions/:requestID" ).toHandler( "Gateway.process" )
post( "/interactions/:requestID/decisions" ).toHandler( "Gateway.process" )

3. Push-style gateways (type: "telegram" / "slack" / "discord" / "email" / "whatsapp-cloud" / "teams" / "twilio" / "github" / "signal", and friends)

上記の mock/cli/http とは異なる種類のチャネルアダプタです - 受信 HTTP リクエストによって駆動されるのではなく、push 型ゲートウェイはプラットフォームへの独自の接続を保持し、受信メッセージが到着するたびにあなたのエージェントに push します。より「本物のチャットボット」に近い体験です。今日時点で 4 つの転送形式が存在します。

• ロングポーリング (Telegram、Email): スケジュールされたタスクが定期的にプラットフォームに「何か新着はある?」と尋ねます (Telegram の getUpdates、Email の IMAP ポーリング)。
• 永続的な WebSocket (Slack の Socket Mode 経由、Discord の Gateway API 経由): ゲートウェイが、プラットフォームがリアルタイムでイベントを push してくる、ライブで長時間持続する接続を保持します。
• Webhook、プル駆動 (WhatsApp Business Cloud API、Microsoft Teams、Twilio SMS、GitHub): このゲートウェイが独自の送信接続を保持するのではなく、プラットフォームが公開の HTTP エンドポイント経由で私たちを呼び出します - 管理すべきスケジューラタスクやソケットはありません。下記の各サブセクション参照。
• サーバー送信イベント (SSE) (Signal、ローカルで動く signal-cli デーモンに対して): ゲートウェイが開いたままにする、長時間持続する一方向のストリーミング HTTP 接続で、同じレスポンスボディを通して push されるイベントを読み取ります。下記の独自サブセクション参照。

// gateways/telegramChannel.bx
class {
	function configure() {
		return {
			type          : "telegram",
			botTokenEnvVar: "TELEGRAM_BOT_TOKEN"
		};
	}
}

// gateways/slackChannel.bx
class {
	function configure() {
		return {
			type          : "slack",
			botTokenEnvVar: "SLACK_BOT_TOKEN",   // xoxb-... - chat.postMessage/chat.update
			appTokenEnvVar: "SLACK_APP_TOKEN"    // xapp-... - apps.connections.open (Socket Mode)
		};
	}
}

// gateways/discordChannel.bx
class {
	function configure() {
		return {
			type          : "discord",
			botTokenEnvVar: "DISCORD_BOT_TOKEN"   // Authorization: Bot <token> on every REST call and inside Identify
			// intents: 37377   // optional override - defaults to GUILDS+GUILD_MESSAGES+DIRECT_MESSAGES+MESSAGE_CONTENT
		};
	}
}

// gateways/emailChannel.bx
class {
	function configure() {
		return {
			type              : "email",
			imapHostEnvVar    : "IMAP_HOST",
			imapUsernameEnvVar: "IMAP_USERNAME",
			imapPasswordEnvVar: "IMAP_PASSWORD",
			fromAddressEnvVar : "EMAIL_FROM_ADDRESS"
			// imapPort: 993   // optional override - defaults to 993 (IMAPS)
			// pollIntervalSeconds: 60   // optional override - defaults to 60
		};
	}
}

// gateways/whatsappCloud.bx
class {
	function configure() {
		return {
			type               : "whatsapp-cloud",
			accessTokenEnvVar  : "WHATSAPP_ACCESS_TOKEN",     // Graph API access token
			phoneNumberIdEnvVar: "WHATSAPP_PHONE_NUMBER_ID",  // the WhatsApp Business phone number ID sends go through
			appSecretEnvVar    : "WHATSAPP_APP_SECRET",       // HMAC key verifying X-Hub-Signature-256 on inbound webhooks
			verifyTokenEnvVar  : "WHATSAPP_VERIFY_TOKEN"      // shared secret Meta's GET verify handshake must echo back
			// apiVersion: "v21.0"   // optional override - defaults to "v21.0"
		};
	}
}

// gateways/teamsChannel.bx
class {
	function configure() {
		return {
			type                : "teams",
			appIdEnvVar         : "TEAMS_APP_ID",         // the bot's own Microsoft App ID (also the inbound JWT's required aud claim)
			appPasswordEnvVar   : "TEAMS_APP_PASSWORD"    // OAuth2 client-credentials secret
			// tenantId: "..."   // optional override for single-tenant apps - defaults to "botframework.com" (multi-tenant)
		};
	}
}

// gateways/twilioChannel.bx
class {
	function configure() {
		return {
			type            : "twilio",
			accountSidEnvVar: "TWILIO_ACCOUNT_SID",
			authTokenEnvVar : "TWILIO_AUTH_TOKEN",   // also the X-Twilio-Signature HMAC key
			fromEnvVar      : "TWILIO_FROM_NUMBER"   // the Twilio phone number outbound sends go through, E.164
			// messagingServiceSid: "MG..."   // optional - if set, used instead of `from` on outbound sends
			// publicUrl: "https://your-real-public-host/webhooks/twilio"   // optional override for reverse-proxy/tunnel deployments - see the Twilio subsection below
		};
	}
}

// gateways/githubChannel.bx
class {
	function configure() {
		return {
			type               : "github",
			tokenEnvVar        : "GITHUB_TOKEN",           // a personal access token (repo/issues+PR read+write scope)
			webhookSecretEnvVar: "GITHUB_WEBHOOK_SECRET",  // HMAC key verifying X-Hub-Signature-256 on inbound webhooks
			botNameEnvVar      : "GITHUB_BOT_NAME"         // the bot's own GitHub login - matched as "@botName" in comments
			// apiBaseUrl: "https://api.github.com"   // optional override - defaults to "https://api.github.com"
		};
	}
}

// gateways/signalChannel.bx
class {
	function configure() {
		return {
			type         : "signal",
			accountEnvVar: "MY_SIGNAL_ACCOUNT"   // the signal-cli-registered phone number this gateway sends/receives as, E.164
			// httpUrl: "http://127.0.0.1:8080"   // optional override - defaults to "http://127.0.0.1:8080", where signal-cli's own daemon HTTP API is expected to be listening
		};
	}
}

http の secretEnvVar と同じ「シークレットは常に外部に置く」ルールです - すべての *EnvVar キーは環境変数の名前を指定し、起動時に getSystemSetting() 経由でライブに解決され、リテラルとして埋め込まれることは決してありません。email の imapHost/fromAddress は暗号学的なシークレットではありませんが、それでもすべての値がデプロイごとに異なるため、同じ環境変数駆動のコンベンションがそのすべてに使われています。コアのタイプとは異なり、push 型ゲートウェイのクラスは bx-ai ではなく BX Agents 自身の内部にあるため (models/gateways/*.bx)、その登録は短い名前ではなく、生のクラスパスとしてレンダリングされます。

aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.TelegramGateway", { "botToken" : getSystemSetting( "TELEGRAM_BOT_TOKEN", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.SlackGateway", { "appToken" : getSystemSetting( "SLACK_APP_TOKEN", "" ), "botToken" : getSystemSetting( "SLACK_BOT_TOKEN", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.DiscordGateway", { "botToken" : getSystemSetting( "DISCORD_BOT_TOKEN", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.EmailGateway", { "imapHost" : getSystemSetting( "IMAP_HOST", "" ), "imapUsername" : getSystemSetting( "IMAP_USERNAME", "" ), "imapPassword" : getSystemSetting( "IMAP_PASSWORD", "" ), "fromAddress" : getSystemSetting( "EMAIL_FROM_ADDRESS", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.whatsapp.WhatsAppCloudGateway", { "accessToken" : getSystemSetting( "WHATSAPP_ACCESS_TOKEN", "" ), "phoneNumberId" : getSystemSetting( "WHATSAPP_PHONE_NUMBER_ID", "" ), "appSecret" : getSystemSetting( "WHATSAPP_APP_SECRET", "" ), "verifyToken" : getSystemSetting( "WHATSAPP_VERIFY_TOKEN", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.TeamsGateway", { "appId" : getSystemSetting( "TEAMS_APP_ID", "" ), "appPassword" : getSystemSetting( "TEAMS_APP_PASSWORD", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.TwilioGateway", { "accountSid" : getSystemSetting( "TWILIO_ACCOUNT_SID", "" ), "authToken" : getSystemSetting( "TWILIO_AUTH_TOKEN", "" ), "from" : getSystemSetting( "TWILIO_FROM_NUMBER", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.GitHubGateway", { "token" : getSystemSetting( "GITHUB_TOKEN", "" ), "webhookSecret" : getSystemSetting( "GITHUB_WEBHOOK_SECRET", "" ), "botName" : getSystemSetting( "GITHUB_BOT_NAME", "" ) } ) )
aiGatewayRegistry().register( aiGateway( "bxModules.bxagents.models.gateways.SignalGateway", { "account" : getSystemSetting( "MY_SIGNAL_ACCOUNT", "" ) } ) )

検証: type: "telegram" には botTokenEnvVar が必須です。type: "slack" には botTokenEnvVar と appTokenEnvVar の両方が必須です。type: "discord" には botTokenEnvVar が必須です。type: "email" には imapHostEnvVar、imapUsernameEnvVar、imapPasswordEnvVar、fromAddressEnvVar が必須です。type: "whatsapp-cloud" には accessTokenEnvVar、phoneNumberIdEnvVar、appSecretEnvVar、verifyTokenEnvVar が必須です。type: "teams" には appIdEnvVar と appPasswordEnvVar が必須です。type: "twilio" には accountSidEnvVar、authTokenEnvVar、fromEnvVar が必須です。type: "github" には tokenEnvVar、webhookSecretEnvVar、botNameEnvVar が必須です。type: "signal" には accountEnvVar が必須です - すべて http の secretEnvVar と同じ方法でチェックされます。

Slack の永続的な接続

SlackGateway は、java.net.http.HttpClient の非同期 WebSocket クライアントを通じて、implements="java:java.net.http.WebSocket$Listener" を直接実装する BoxLang のリスナークラス (models/gateways/support/SlackSocketListener.bx) からブリッジされる形で、自身の WebSocket を保持します - BoxLang はこれを、そのインターフェースの実際の JVM 実装としてコンパイルします。これは、インスタンスをそのまま HttpClient.newWebSocketBuilder().buildAsync( uri, listener ) に渡してもキャストエラーが発生しないこと (実際のネットワーク境界に到達した際に期待される java.net.ConnectException のみが発生すること) によって経験的に確認されています。クラスが実際に宣言しているメソッドだけが JDK インターフェースの default メソッドをオーバーライドします。実装されていないものは自動的に JDK 自身のデフォルト動作にフォールスルーします。これは、他のあらゆる永続接続ゲートウェイ (後述の Discord) が従う参照パターンでもあります。

再接続は、Slack 自身のプロトコルシグナル - disconnect フレーム (warning/refresh_requested) や予期しないソケットクローズ - によって能動的に駆動され、Slack が文書化して推奨する通り、古い接続を閉じる前に新しい接続を開きます。軽量なスケジューラウォッチドッグ (slack-watchdog-<name>、30 秒ごと) は、これらどちらのシグナルも発火しなかった場合のためのセーフティネットに過ぎません。

Discord の永続的な接続 - クライアント駆動の必須ハートビート

DiscordGateway も同じ方法 (models/gateways/support/DiscordSocketListener.bx、Slack と同じ implements="java:java.net.http.WebSocket$Listener" パターン) で接続しますが、Discord の Gateway プロトコルには Slack の Socket Mode にはない要件があります - サーバー自身の Hello フレーム (opcode 10) がクライアントに heartbeat_interval を伝え、クライアントはそのペースで自分から Heartbeat フレーム (opcode 1) を送り続ける必要があります。さもなければ Discord は接続を「ゾンビ化」したとみなして切断します。この間隔は Hello が届いて初めて分かる (接続前には分からない) ため、ハートビートはそれ自身のスケジューラタスク (discord-heartbeat-<name>) としてフレームハンドラの内部から動的に登録され、新しい Hello が届くたびに再登録されます - これは他のすべての push 型ゲートウェイの registerScheduledTasks() 時に固定されるタスクとも、Discord 自身のセーフティネットウォッチドッグ (discord-watchdog-<name>、30 秒ごと、Slack と同じ役割) とも異なります。

各ハートビートのティックは、直前のハートビートが実際に確認応答されたか (Heartbeat ACK、opcode 11) をチェックします - されていなければ、その接続はゾンビ化しているとみなされ、タイムアウトを待つのではなく能動的に再接続されます。それ以外の再接続は、Discord 自身が文書化しているセッションモデルに従います - Reconnect フレーム (opcode 7) や大半のクローズコードは、既存のセッションがある場合は新しい接続上での Resume (opcode 6、最後のシーケンス番号を再生) をトリガーします。d: false を持つ Invalid Session フレーム (opcode 9)、または Discord がセッション無効化と文書化しているクローズコード (4007、4009) は、代わりに新規の Identify (opcode 2) を強制します。小さな固定セットのクローズコード (4004 不正なトークン、4010 不正なシャード、4011 シャーディング必須、4012 不正な API バージョン、4013/4014 不正/未許可のインテント) は Discord 自身のドキュメントに従い回復不能です - このゲートウェイは、どうせ再び失敗するであろう接続を再試行するのではなく停止します。

Email - サーバーレベルの依存関係、そして劣化したスレッディング/HITL

EmailGateway は、自身のプラットフォームの API を直接話さない唯一の push 型ゲートウェイです。送信メールは、自前で組んだ HTTP/SMTP 呼び出しではなく、ColdBox 自身の cbmailservices モジュール (MailService@cbmailservices、その BXMail プロトコル - これ自体は bx-mail モジュールの BoxLang 自身の bx:mail コンポーネントを呼び出しているだけです) を経由します。どちらも実際の、サーバーレベルのモジュールインストールです - このプロジェクト自身の box.json の dependencies として宣言されています (そのため bx-agents をインストールするとサーバーにもそれらが引き込まれます) が、cbmailservices/bx-mail はどちらも、生成されたアプリを実際に実行するサーバー上で明示的なインストールが必要です (両モジュール自身のドキュメント/ソースに照らして確認済みです - どちらも ColdBox や BoxLang にプリインストールされて出荷されることはありません) - email ゲートウェイを持つプロジェクトを bxAgents serve/デプロイする前に、実際の box install (または同等のもの) を行ってください。EmailGateway は application.cbController.getWireBox() から手動で MailService@cbmailservices を解決します (ScheduledGatewayBase.resolveScheduler() 自身の docblock で理由を確認できます - このクラスは aiGateway() によって WireBox の外側で直接構築されるため、inject="" はここでは決して機能しません)。スケジューラ自体が解決される方法と同じです。

bx-mail も cbmailservices もメールの受信は行わない (送信のみ) ため、受信は JDK 標準の jakarta.mail API による手組みの IMAP です - このプロジェクト自身のクラスパス上で推移的に到達可能であることが確認済みです (bx-mail は commons-email2-jakarta に依存し、それ自体が jakarta.mail-api + Angus Mail の実装に依存します)。これは推測ではなく、今回のセッションで実際の jar に対して経験的に検証されています。スケジュールされたタスク (email-poll-<name>) が未読メールを求めて IMAP をポーリングします。Telegram のロングポーリングと同じ形です。

スレッディングと human-in-the-loop は、どちらもチャットプラットフォームのゲートウェイと比べて劣化しており、getDeclaredCapabilities() は意図的に "interactiveActions" を省いて正直にそれを表明しています。

• スレッディングは、通常の返信については実際の Message-ID/In-Reply-To/References ヘッダーを使います (ゲートウェイは自分が返信している受信 Message-ID を常に把握しているので、送信する返信に In-Reply-To を設定するのは確実です) - v1 の簡略化として、チェーン全体の完全な走査ではなく References の最初のエントリ (なければ In-Reply-To、それもなければメッセージ自身の Message-ID) でスレッド化します。
• Human-in-the-loop にはネイティブなボタン/コンポーネント表面がまったくありません - requestHumanInteraction() は、許可された決定キーワードを列挙したプレーンテキストのメールを送り、人間にその 1 つを最初の行として返信するよう求めます。その返信を正しい保留中リクエストに紐付ける処理は、通常の返信のようには In-Reply-To に頼れません (cbmailservices の send() は送信した承認メール自体がどんな Message-ID を割り当てられたかを公開しないため)。そのため、代わりに Subject 行に埋め込まれた [bxagents:<requestID>] タグ経由で行われます - 実際のメールベースのサポートチケットシステムが同じ理由で使うのと同じ手法です。返信の最初の行は、そのリクエスト自身の許可された決定と (完全一致またはプレフィックス一致、大小文字を区別せず) 照合されます。認識されない返信は再プロンプトされずそのまま通過し、bx-ai 自身の HITL コーディネーターに拒否させます。

WhatsApp Business Cloud API - Webhook 駆動、接続駆動ではない

WhatsAppCloudGateway は、他のすべての push 型ゲートウェイとは異なる形をしています。このゲートウェイが独自の送信接続 (ポーリングタスクや WebSocket) を保持するのではなく、Meta が公開 Webhook 経由で私たちを呼び出します。これは ScheduledGatewayBase ではなく、bx-ai の BaseGateway を直接 extends します - 管理すべきスケジューラタスクやソケットはなく、whatsapp-cloud ゲートウェイエントリが存在する場合にのみ書き込まれる、2 つの固定ルートに配線された生成済みの handlers/WhatsAppCloud.bx があるだけです。

get( "/webhooks/whatsapp-cloud" ).toHandler( "WhatsAppCloud.verify" )
post( "/webhooks/whatsapp-cloud" ).toHandler( "WhatsAppCloud.process" )

どちらのアクションも、ゲートウェイ自身の handleVerify()/handleWebhook() への薄いパススルーです - verify は Meta のサブスクリプションハンドシェイク (GET ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...) に応答し、モードとトークンが一致する場合にのみ (定数時間で比較したうえで) challenge をプレーンテキストとしてそのまま返します。process は、何かをパース/ディスパッチする前に、Meta 自身の X-Hub-Signature-256 ヘッダー (厳密な生の POST ボディ - event.getHTTPContent() - に対する HMAC-SHA256。再パース/再シリアライズされた JSON では、バイト列が変わり署名が壊れてしまうため決して使いません) を検証します。これは bx-ai 自身の HttpGateway/GatewaySecurity (異なるヘッダー名、異なる HMAC 構成) とは本質的に異なる方式であるため、ここでは再利用されていません - クラス自身の docblock を参照してください。

Hermes Agent's 自身の実際の本番用 WhatsApp Cloud アダプタ (gateway/platforms/whatsapp_cloud.py、MIT ライセンス) から直接移植されています - verify ハンドシェイク、署名方式、Webhook ペイロードの走査 (entry[].changes[].value.{messages,contacts})、送信メッセージ/インタラクティブボタンの形 (許可された決定が 3 つ以下ならネイティブなボタンとして、4 つ以上なら「タップして開く」リストとして描画され、WhatsApp 自身が文書化している制限に一致します)、そして長さの制限 (4096 文字のメッセージ、20 文字のボタンラベル、1024 文字のインタラクティブ本文テキスト) は、今回のセッションでそのソースから直接読み取られたもので、ゼロから再実装されたものではありません。受信メッセージは自身の wamid によって重複排除されます (Meta は 200 以外のあらゆる応答に対して、最大 7 日間 Webhook 配信を再試行します)。境界のある FIFO キャッシュ経由で、Hermes 自身の _dedup_wamid を模倣しています。

Microsoft Teams - Bot Framework Activity プロトコル

TeamsGateway は WhatsAppCloudGateway と同じ方法で Webhook 駆動です - BaseGateway を直接 extends し、Microsoft 自身の Bot Connector サービスが単一の生成済みルート経由で私たちを呼び出します。

post( "/webhooks/teams" ).toHandler( "Teams.process" )

WhatsApp Cloud とは異なり GET verify ハンドシェイクはありません (Bot Framework には Meta の hub.challenge に相当するものがありません) - すべての受信アクティビティは、ボディに対する HMAC 署名ではなく、Authorization ヘッダー内のベアラー JWT によって検証される署名済み POST として届きます。この JWT は Bot Connector 自身の JWKS (https://login.botframework.com/v1/.well-known/openidconfiguration → その jwks_uri) に対してチェックされます - RS256 署名、aud はボット自身の設定済み appId と一致する必要があり、iss は Bot Connector の固定された発行者文字列 (https://api.botframework.com) と一致する必要があります。どちらも 5 分間のクロックスキュー許容付きです。これは BoxLang 自身の Java 相互運用 (java.security.Signature、java.security.KeyFactory、java.math.BigInteger) から構築された、本物の RSA/JWT 検証です - 外部の JWT ライブラリはありません。送信呼び出しは別個の OAuth2 クライアントクレデンシャルトークンを使います (login.microsoftonline.com/{tenantId}/oauth2/v2.0/token から取得し、キャッシュされ、記載された有効期限の 60 秒前に再取得されます)。

Vercel Eve's 自身の実際の Teams チャネル (packages/eve/src/public/channels/teams/、MIT ライセンス) から移植されています - OAuth2 フロー、JWT 検証方式、v3/conversations/{id}/activities[/{activityId}] REST の三点セット、そして Adaptive Card による human-in-the-loop の形 (schema 1.5、許可された決定ごとに 1 つの Action.Submit ボタン) は、すべてこの実装を反映しています。Hermes Agent 自身の msgraph_webhook.py は無関係です。「Microsoft Webhook」という似た名前にもかかわらず、これは Microsoft Graph の変更通知Webhook (メールボックス/ドライブ/リストのリソース変更イベントという、送信 Teams メッセージングがまったく動作しない別の Microsoft 製品表面) を実装したものであり、ここには何も移植されていません。

Twilio SMS - 本質的に異なる署名方式、そしてデュアルパスのレスポンスモデル

TwilioGateway は WhatsAppCloudGateway/TeamsGateway と同じ方法で Webhook 駆動です。

post( "/webhooks/twilio" ).toHandler( "Twilio.process" )

Twilio 自身の Webhook 契約を、このプロジェクトの他のあらゆるゲートウェイと本質的に異なるものにしている点が 2 つあり、どちらも Vercel Eve の実際の Twilio チャネル (packages/eve/src/public/channels/twilio/、MIT ライセンス) から忠実に移植されています。

• 受信ボディは form-urlencoded です (Body、From、To、MessageSid、AccountSid)。JSON ではありません - TwilioGateway はこれを自分自身でパースします (java.net.URLDecoder)。JSON のデシリアライズは関与しません。
• 署名検証は X-Twilio-Signature: HMAC-SHA1、base64 エンコードです (このプロジェクトの他のあらゆる Webhook ゲートウェイは HMAC-SHA256、16 進エンコードを使っています) - 署名対象文字列は、実際のリクエスト URL に続けて、キーでアルファベット順にソートされたすべての POST パラメータ自身の key & value を (区切り文字なしで) そのまま連結したものです。URL 自体が署名対象の一部であるため、リバースプロキシやトンネルの背後で動くプロジェクト (ColdBox が event.getUrl() で見る URL が、Twilio が実際に POST した先と一致しない場合) には、任意の publicUrl config オーバーライドが必要です。Eve 自身のドキュメントがその webhookUrl オプションについて指摘しているのと同じ種類の落とし穴です。
• 同期 Webhook のレスポンスは常に空の TwiML <Response></Response> です - Twilio 自身のクラシックなデュアルパスモデルです。実際のエージェントの返信は、GatewaySession の非同期ターンが完了した後、Messages API への別個の deliver() REST 呼び出しを通じて、アウトオブバンドで後から送られます。Eve 自身の emptyTwilioResponse() と正確に一致します (Eve は同期的な TwiML <Message> でインラインに応答することは決してありません)。

送信は、Basic 認証の REST 呼び出しで POST /2010-04-01/Accounts/{AccountSid}/Messages.json に対して行われ、form エンコードされたボディ (To、Body、そして設定されていれば From または MessagingServiceSid) です。v1 は SMS テキストのみです - Eve 自身の Twilio チャネルは SMS+音声の複合チャネルです (/voice ルート、<Gather>/<Say> TwiML、通話文字起こし)。音声関連の部分は一切移植されていません。

GitHub - @mention によってゲートされた issue/PR コメントスレッド

GitHubGateway は、各 issue、PR、あるいはインラインレビューコメントスレッドを、1 つのチャット会話として扱います - エージェントは、コメント内で明示的に @メンション された場合に応答し、同じスレッドに新しいコメントを投稿して返信します。このセクションの他のあらゆるゲートウェイと同じ方法で Webhook 駆動です。

post( "/webhooks/github" ).toHandler( "GitHub.process" )

Vercel Eve の実際の GitHub チャネル (packages/eve/src/public/channels/github/、MIT ライセンス) から移植されています - X-Hub-Signature-256 の検証は、WhatsApp Cloud 自身の Meta 方式と同一の構成であることが確認されています (生ボディに対する HMAC-SHA256、16 進、sha256= プレフィックス) - このプロジェクトで唯一、独自の署名アルゴリズムが不要で他のゲートウェイの方式をそのまま再利用しているゲートウェイです。action: "created" を伴う issue_comment と pull_request_review_comment イベントのみがディスパッチされます (Eve 自身のデフォルトで処理されるイベント種別と一致しています - issues/pull_request/check_suite/check_run/workflow_run は Eve にもデフォルトのディスパッチがなく、ここにも配線されていません)。それ以外のすべてのイベント種別は (200 で) 確認応答されますが無視されます。このゲートウェイが対応しないイベントに対する GitHub の再試行/フック無効化挙動を避けるためです。

ディスパッチのゲートは、本物の @mention 要件です。Eve 自身の extractGitHubCommentTrigger() から移植されています - コメントは、@<botName> に続けて文字列の終わりか非識別子文字がある場合にのみエージェントに届きます (そのため mybot という名前のボットが @mybot2 に言及するコメントで発火することは決してありません) - これは、それを信頼する前に、今回のセッションで実際の正規表現先読みのスモークテストによって確認されています。マッチした @mention トークンは、テキストがエージェントに届く前に取り除かれます。ボットループの防止は Eve 自身の 3 部構成のガードを反映しています - コメントの著者が GitHub 自身の type: "Bot" を持つか、ログインが {botName}[bot] に一致するか、あるいは本文にこのゲートウェイ自身の <!-- bxagents:posted --> マーカー (投稿するすべてのコメントに付加されます) が含まれる場合、たとえメンションを含んでいても無視されます。

「会話」は、Eve 自身のモデルに一致する 2 つの形のいずれかで識別されます: 通常の issue/PR コメントスレッドは repo:{owner}/{repo}:issue:{issueNumber}、インライン PR レビューコメントスレッドは repo:{owner}/{repo}:review-comment:{reviewThreadRootCommentId} です - レビュースレッドへの返信は常に、返信されている特定のコメントではなくスレッドのルートコメント (comment.in_reply_to_id ?? comment.id) 宛てになり、複数メッセージのやり取りが 1 つのスレッドにまとまります。送信の返信は repos/{owner}/{repo}/issues/{issueNumber}/comments (通常のスレッド) または repos/{owner}/{repo}/pulls/{pullRequestNumber}/comments/{reviewCommentId}/replies (レビュースレッド) に POST されます。

"whatsapp-personal" というタイプはありません。 非公式の個人アカウントブリッジ (WhatsApp のマルチデバイス Web プロトコルで、Hermes Agent が Node.js/Baileys サブプロセス経由で到達する種類のもの) は調査されましたが、意図的に実装されませんでした - MIT ライセンスのネイティブ Java の選択肢だった Cobalt (com.github.auties00:cobalt) は、実際に Maven Central に公開されているバージョンでは商用/プロプライエタリな依存関係 (com.aspose:aspose-words) を引き込むことが判明し、サブプロセスブリッジによる移植もネイティブ JVM アプローチを優先して見送られました。gateways/* エントリで type: "whatsapp-personal" を宣言すると、他のあらゆる未サポートタイプと同様に「unknown type」検証エラーで失敗します。詳しい調査の全容は docs/known-limitations.md を参照してください。

Signal - 4 つ目の転送形式、外部の signal-cli デーモンに対して

SignalGateway は、上記の WhatsApp Cloud/Teams/Twilio/GitHub のように Webhook 駆動でもなければ、Slack/Discord のような WebSocket でもありません - Telegram/Slack/Discord/Email と同じように ScheduledGatewayBase を extends しますが、自身の接続はサーバー送信イベントです。java.net.http.HttpClient の非同期 API (sendAsync() + BodyHandlers.ofLines()) 経由で保持される、単一の長時間持続する GET {httpUrl}/api/v1/events?account=... リクエストで、signal-cli 自身のデーモンが同じレスポンスボディを通して push してくる 1 行 1 JSON イベントを読み取ります。送信はプレーンな JSON-RPC 2.0 です (POST {httpUrl}/api/v1/rpc、{"jsonrpc":"2.0","method":"send","params":{...},"id":...})。同じデーモンに対して行われます。

公式の Signal ボット API は存在しません - SignalGateway は、signal-cli が自身の daemon --http モードで動いているものと完全に通信します。これはこのゲートウェイが依存しているものの、自身では管理しない外部の前提条件であり、EmailGateway が外部の IMAP/SMTP サーバーと持つ関係と同じです。Hermes Agent's 自身の実際の Signal チャネルから移植されています - SSE/JSON-RPC のワイヤー形式、再接続のバックオフ定数 (2 秒から 60 秒への指数関数的増加、+20% のジッター)、そして 30 秒/120 秒のアイドルウォッチドッグは、すべてそのソースから直接読み取られたもので、ゼロから再実装されたものではありません。

GatewaySession - wiring the agent to every push-style gateway

少なくとも 1 つの push 型ゲートウェイエントリを持つプロジェクトは、生成された interceptors/GatewaySessionBootstrap.bx も得ます。これはプロジェクト内のすべての push 型ゲートウェイをまとめた単一の bx-ai GatewaySession を構築し、プロジェクトのルートエージェントに束縛し、ColdBox 自身のロードが完了した時点で一度だけ起動します。

// interceptors/GatewaySessionBootstrap.bx (GENERATED)
class {
	function afterConfigurationLoad( event, interceptData ) {
		var wirebox        = getController().getWireBox()
		var agent          = wirebox.getInstance( "GeneratedAgent" )
		var gatewaySession = aiGatewaySession(
			agent        : agent,
			gateways     : [ aiGatewayRegistry().get( "telegram" ) ],
			policy       : "queue",
			maxQueueDepth: 50
		)
		gatewaySession.start()
		application.bxaiGatewaySession = gatewaySession
	}
}

GatewaySession のポリシーは、ルートプロジェクトの Agent.bx 上の任意の gatewaySession ブロックで制御できます。

// Agent.bx
class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init( name: "...", model: aiModel( provider: "..." ) )
		return this
	}

	function configure() {
		return {
			gatewaySession: { policy: "queue", maxQueueDepth: 50 }   // both optional - these are the defaults
		};
	}

}

policy は reject/queue/steer/interrupt のいずれかである必要があります (bx-ai 自身の GatewaySession ポリシーの語彙です - 下の GatewaySession を参照) - これは build 時にチェックされるため、タイプミスはアプリが起動した際のランタイムエラーとして表面化するのではなく、大きく失敗します。

各ポリシーが、ターンがまだ実行中に届いたメッセージに対して実際に何をするか:

flowchart TD
    M["a message arrives on thread T"] --> B{"is a run already<br/>in flight on T?"}
    B -->|"no"| D["dispatch a new turn.<br/>The reply streams back through<br/>the gateway the message came from."]
    B -->|"yes"| P{"policy"}
    P -->|"reject"| R["Immediate 'busy' reply.<br/>Nothing is queued - the sender must resend."]
    P -->|"queue<br/>(the default)"| Q["Enqueue, up to maxQueueDepth.<br/>Runs as its own turn once<br/>the current one finishes."]
    P -->|"steer"| ST["agent.steerRun( T, text )<br/>Spliced into the SAME run at its next<br/>checkpoint - never a second turn."]
    P -->|"interrupt"| I["agent.cancelRun( T ), AND enqueue.<br/>The current turn winds down at its next<br/>checkpoint, then this message runs."]
    Q --> OVER{"queue already at<br/>maxQueueDepth?"}
    I --> OVER
    OVER -->|"yes"| R

    style D fill:#d4edda,stroke:#155724
    style R fill:#f8d7da,stroke:#721c24

push 型ゲートウェイはどうやって接続を維持するのか: 共有される ColdBox スケジューラ

新しいバックグラウンドループのプリミティブを用意するのではなく、push 型ゲートウェイはアプリ自身のライブな ColdBox スケジューラシングルトン (appScheduler@coldbox - プロジェクトに手書きの schedules/Scheduler.bx があれば、それが動いているのと同じもの) に到達し、そこに自身の名前付きタスクを動的に登録します - 例えば Telegram 向けの定期的なロングポーリングタスクです。1 つの共有スケジューラに、すべての push 型ゲートウェイがそれぞれ自身のタスクを登録します - ゲートウェイごとに 1 つのスケジューラを持つことは決してなく、プロジェクト自身の cron ジョブと衝突することもありません。

ロギング

すべての push 型ゲートウェイは、1 つの共有/デフォルトのアプリログにではなく、BoxLang の writeLog() を介して自身の gateway-<type> ログファイル (例えば gateway-telegram) に書き込みます - そのため、オペレーターは自分が気にするプラットフォームだけを、アプリが記録する他のすべてのノイズなしに tail できます。