コマンドキュー（2026-01-16）

すべてのチャネルからの自動返信実行を小さなインプロセスキューでシリアライズし、複数のエージェント実行が衝突するのを防ぎつつ、セッション間の安全な並列処理を実現しています。

なぜ必要か

  • 自動返信はコストが高く（LLM呼び出し）、短い間隔で複数のメッセージが届くと衝突する可能性がある
  • シリアライズにより共有リソース（セッションファイル、ログ、CLI stdin）の競合が回避され、上流のレートリミットに引っかかるリスクも軽減される

動作の仕組み

  • レーン対応のFIFOキューが、設定可能な同時実行数上限で各レーンをドレインする（未設定レーンのデフォルトは1、mainは4、subagentは8）
  • runEmbeddedPiAgentはセッションキー（レーンsession:<key>）でエンキューし、セッションごとに1つだけアクティブな実行を保証する
  • 各セッション実行はさらにグローバルレーン（デフォルトはmain）にキューイングされ、全体の並列度はagents.defaults.maxConcurrentで制限される
  • 詳細ログが有効な場合、開始までに約2秒以上待機したキュー実行には短い通知が出力される
  • タイピングインジケーターはエンキュー時に即座に発火する（チャネルが対応している場合）ため、待機中でもユーザー体験は変わらない

キューモード（チャネルごと）

受信メッセージは現在の実行をステアリングしたり、次のターンを待ったり、あるいはその両方を行えます：

  • steer：現在の実行に即座に注入する（次のツール境界以降の保留中のツール呼び出しをキャンセル）。ストリーミングしていない場合はfollowupにフォールバック。
  • followup：現在の実行が終了した後、次のエージェントターンとしてキューに入れる。
  • collect：キューに溜まったメッセージを1つのフォローアップターンにまとめる（デフォルト）。異なるチャネル/スレッド宛のメッセージはルーティングを保持するため個別にドレインされる。
  • steer-backlog（別名steer+backlog）：今すぐステアリングし、かつフォローアップターン用にメッセージを保持する。
  • interrupt（レガシー）：そのセッションのアクティブな実行を中断し、最新のメッセージを実行する。
  • queue（レガシーエイリアス）：steerと同じ。

steer-backlogではステアリングされた実行の後にフォローアップレスポンスが返る場合があるため、ストリーミング画面では重複して見えることがあります。メッセージ1通に対して1つのレスポンスにしたい場合はcollect/steerを使ってください。 単独コマンドとして/queue collectを送信するか（セッション単位）、messages.queue.byChannel.discord: "collect"を設定してください。

デフォルト（設定なしの場合）：

  • すべての画面 → collect

グローバルまたはチャネル単位でmessages.queueで設定：

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

キューオプション

以下のオプションはfollowup、collect、steer-backlog（およびsteerがfollowupにフォールバックした場合）に適用されます：

  • debounceMs：フォローアップターン開始前に無入力期間を待つ（「続けて、続けて」の連投を防止）。
  • cap：セッションあたりのキュー上限数。
  • drop：オーバーフローポリシー（old、new、summarize）。

summarizeはドロップされたメッセージの短い箇条書きリストを保持し、合成フォローアッププロンプトとして注入します。 デフォルト：debounceMs: 1000、cap: 20、drop: summarize。

セッション単位のオーバーライド

  • 単独コマンドとして/queue <mode>を送信すると、現在のセッションにモードが保存される。
  • オプションは組み合わせ可能：/queue collect debounce:2s cap:25 drop:summarize
  • /queue defaultまたは/queue resetでセッションオーバーライドをクリア。

スコープと保証

  • Gateway返信パイプラインを使用するすべての受信チャネル（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat等）の自動返信エージェント実行に適用される。
  • デフォルトレーン（main）は受信＋メインハートビートのプロセス全体で共有。agents.defaults.maxConcurrentで複数セッションの並列実行を許可可能。
  • 追加レーン（例：cron、subagent）があるため、バックグラウンドジョブは受信返信をブロックせずに並列実行できる。
  • セッション単位のレーンにより、特定のセッションに同時にアクセスするエージェント実行は1つだけに保証される。
  • 外部依存やバックグラウンドワーカースレッドなし。純粋なTypeScript＋Promiseで実装。

トラブルシューティング

  • コマンドが詰まっているように見える場合は、詳細ログを有効にして「queued for …ms」の行を確認し、キューが正しくドレインされているか確認する。
  • キューの深さを確認するには、詳細ログを有効にしてキュータイミングの行を監視する。
arrow_back
前へ
Retry
次へ
Tools
arrow_forward