​

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

​

なぜ必要か

• 自動返信の実行は高コストになる可能性があります（LLM 呼び出しなど）。複数の受信メッセージが短時間に到着すると、実行が衝突するおそれがあります。
• 直列化することで、共有リソース（セッションファイル、ログ、CLI stdin）の競合を避け、上流のレート制限に達する可能性を減らします。

​

How it works

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

​

キューモード（チャンネル別）

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

• すべてのサーフェス → collect

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

​

キューオプション

• debounceMs: フォローアップターンを開始する前に静止状態を待ちます（「continue, continue」を防止）。
• cap: セッションあたりの最大キュー済みメッセージ数。
• drop: オーバーフローポリシー（old、new、summarize）。

​

セッション毎の上書き

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

​

適用範囲と保証

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

​

トラブルシューティング

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