creating-letta-code-channels

Letta Code チャネルの作成

Letta Code のチャネルサポートを追加またはデバッグする際に使用します。

最初に検討する方法

• ヘッドレスでの実験、コミュニティプラグイン、ワークフローの迅速なテストには、ユーザープラグイン（~/.letta/channels/<id>/）を使用します。
• チャネルに専用の Desktop UI、カスタムのアカウントスナップショット、Slack／Discord 形式の自動ルーティング、豊富なプロトコルフィールド、または移行・互換性用のシムが必要な場合は、ファーストパーティチャネル（src/channels/<id>/）を使用します。

ユーザープラグインでファーストパーティの ID を上書きすることはできません。telegram、slack、discord は ~/.letta/channels/ に配置しても無視されます。telegram-test、whatsapp-community、custom-chat などの ID を使用してください。

基本的なワークフロー

1. ~/letta/letta-code またはワークツリーで作業します。
2. 動的プラグインを使用するブランチでは、src/channels/README.md を読みます。
3. ユーザープラグインを作成する場合は、次のファイルを作成します。
   • ~/.letta/channels/<id>/channel.json
   • ~/.letta/channels/<id>/plugin.mjs
   • ~/.letta/channels/<id>/accounts.json
4. どちらの返信モードでも messageActions を実装します。明示的なツール返信と自動リレーのテキストには、共通の送信アダプターパスが使用されます。
5. テストでは dmPolicy: "pairing" から始めるか、既知のヘッドレス環境では allowlist／open を使用します。
6. 次の 4 つの経路をすべてテストします。
   • プラグインの検出／インポート
   • 着信 adapter.onMessage(msg) からルーティング／ペアリングまで
   • ルーティングされたチャネル通知がエージェントに届くこと
   • 送信動作が、アカウントに記録された返信モードと一致すること。ツールモードでは明示的な MessageChannel 配信、リレーモードでは確定済みテキストの自動配信になります。
7. 対象を絞ったテストを実行し、その後 bun run typecheck、bun run lint、bun run build を実行します。

参考資料

必要なものだけを読みます。

• references/user-plugins.md — 動的プラグインのマニフェスト／アカウント／ランタイム／ヘッドレスの流れと注意点。
• references/first-party-channels.md — ファーストパーティチャネルのファイルカスケードと安全性チェック。
• references/testing.md — スモークテストのチェックリストとコマンド。

スキャフォールドヘルパー

同梱のスキャフォールドを使って、最小限のユーザープラグインのひな形を作成します。<path-to-this-skill> をこのスキルのディレクトリパスに置き換えてください。

npx tsx <path-to-this-skill>/scripts/scaffold-user-channel-plugin.ts \
  my-channel "My Channel" \
  --runtime-package [email protected] \
  --runtime-module some-sdk

これにより channel.json、plugin.mjs、accounts.example.json が作成されます。TODO になっている着信／送信の実装を、実際の SDK 呼び出しに置き換えてください。

重要な教訓

• reply_mode が未設定または無効な場合、アカウントはデフォルトでツールモードになります。既存の保存済みアカウントには、実際の ID、ルートフィールド、認証情報を保持したまま "reply_mode": "relay" を追加してください。
• リレーには PR 4043 を含むビルドが必要です。v0.34.1 はこれより前のバージョンです。オンデバイスのゲートウェイが配信を実装します。リモートホストではトランスポートと、入力ごとに記録されたポリシーを提供する必要があります。これはホストの違いであり、エージェントの状態による制限ではありません。モードの変更は新しい入力に適用され、処理中またはキュー内の入力には適用されません。
• 宛先が 1 つのリレー入力は、MessageChannel を使わずに確定済みテキストを送信します。未確定のエラー／キャンセルテキスト、推論、サブエージェントの出力は除外されます。宛先が複数の入力では明示的な返信が必要で、一斉送信は行われません。キュー内の入力は個別に保持されます。リアクション、ファイル、能動的な送信にはツールモードを使用してください。
• 公開チャネルでは、検証済みのオペレーターへのルーティングがない限り、ツールの承認／制御プロンプトを表示しないでください。承認プロンプトを公開するとツール入力が漏えいし、偽造された approve の返信を招くおそれがあります。
• ユーザープラグインのランタイム解決で、親ディレクトリや開発環境の node_modules を対象に含めてはいけません。ランタイムモジュールは、明示的に指定されたランタイムディレクトリからのみ解決してください。
• ヘッドレスのペアリングは CLI を優先します。letta channels pair --channel <id> --code <code> --agent <agent-id> --conversation <conversation-id> を使用します。
• 実行中のリスナーは、次の着信ミス時に pairing.yaml と routing.yaml を再読み込みします。アダプター／アカウントの設定自体が変更された場合にのみ、再起動してください。