コマンドキュー (2026-01-16)

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

理由

  • 自動返信実行はコストが高く（LLM呼び出し）、複数のインバウンドメッセージが近接して到着すると衝突する可能性があります。
  • シリアライズにより、共有リソース（セッションファイル、ログ、CLI標準入力）の競合を回避し、上流のレート制限に達する可能性を減らします。

動作方法

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

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

インバウンドメッセージは、現在の実行を誘導したり、次のターンを待ったり、またはその両方を行うことができます：

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

steer-backlogは、steerされた実行の後にfollowup応答を受け取ることができるため、ストリーミング画面では重複しているように見える場合があります。インバウンドメッセージごとに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：followupターンを開始する前に静かになるのを待つ（「続けて、続けて」を防ぐ）。
  • cap：セッションごとの最大キューイングメッセージ数。
  • drop：オーバーフローポリシー（old、new、summarize）。

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

セッションごとのオーバーライド

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

スコープと保証

  • ゲートウェイ返信パイプラインを使用するすべてのインバウンドチャネル（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchatなど）の自動返信エージェント実行に適用されます。
  • デフォルトレーン（main）はインバウンド+メインハートビートのプロセス全体で共有されます。agents.defaults.maxConcurrentを設定して、複数のセッションを並列実行できます。
  • 追加のレーン（例：cron、subagent）が存在する場合があり、バックグラウンドジョブはインバウンド返信をブロックせずに並列実行できます。
  • セッションごとのレーンは、特定のセッションに一度に1つのエージェント実行のみが触れることを保証します。
  • 外部依存関係やバックグラウンドワーカースレッドはありません。純粋なTypeScript + promiseです。

トラブルシューティング

  • コマンドがスタックしているように見える場合は、詳細ログを有効にし、「queued for …ms」行を探してキューが処理されていることを確認してください。
  • キューの深さが必要な場合は、詳細ログを有効にし、キューのタイミング行を監視してください。
← ドキュメントに戻る