Command Queue (16/01/2026)

Chúng ta xử lý tuần tự các lượt auto-reply từ tin nhắn đến (tất cả channel) thông qua một hàng đợi nhỏ trong process để tránh nhiều lượt chạy Agent va chạm nhau, đồng thời vẫn cho phép chạy song song an toàn giữa các session.

Tại sao cần Command Queue

  • Các lượt auto-reply có thể tốn kém (gọi LLM) và có thể va chạm khi nhiều tin nhắn đến gần cùng lúc.
  • Xử lý tuần tự giúp tránh tranh chấp tài nguyên dùng chung (file session, log, CLI stdin) và giảm khả năng bị giới hạn tốc độ từ upstream.

Cách hoạt động

  • Hàng đợi FIFO có nhận biết lane, xử lý từng lane với giới hạn concurrency có thể cấu hình (mặc định là 1 cho các lane chưa cấu hình; lane main mặc định là 4, subagent là 8).
  • runEmbeddedPiAgent đưa vào hàng đợi theo session key (lane session:<key>) để đảm bảo chỉ có một lượt chạy active cho mỗi session.
  • Mỗi lượt chạy session sau đó được đưa vào global lane (main theo mặc định) để tổng số lượt chạy song song bị giới hạn bởi agents.defaults.maxConcurrent.
  • Khi bật verbose logging, các lượt chạy trong hàng đợi sẽ hiển thị thông báo ngắn nếu chúng đợi hơn ~2 giây trước khi bắt đầu.
  • Typing indicator vẫn kích hoạt ngay khi đưa vào hàng đợi (nếu channel hỗ trợ) nên trải nghiệm người dùng không thay đổi trong khi chờ đến lượt.

Queue mode (theo từng channel)

Tin nhắn đến có thể điều hướng lượt chạy hiện tại, chờ lượt tiếp theo, hoặc cả hai:

  • steer: inject ngay vào lượt chạy hiện tại (hủy các tool call đang chờ sau tool boundary tiếp theo). Nếu không streaming, sẽ fallback sang followup.
  • followup: đưa vào hàng đợi cho lượt Agent tiếp theo sau khi lượt chạy hiện tại kết thúc.
  • collect: gộp tất cả tin nhắn trong hàng đợi thành một lượt followup duy nhất (mặc định). Nếu tin nhắn nhắm đến các channel/thread khác nhau, chúng sẽ được xử lý riêng lẻ để giữ nguyên routing.
  • steer-backlog (hay steer+backlog): điều hướng ngay và giữ lại tin nhắn cho lượt followup.
  • interrupt (legacy): hủy lượt chạy active của session đó, sau đó chạy tin nhắn mới nhất.
  • queue (legacy alias): giống steer.

Steer-backlog có nghĩa là các bạn có thể nhận được response followup sau lượt chạy đã điều hướng, nên các giao diện streaming có thể trông như bị trùng lặp. Nên dùng collect/steer nếu các bạn muốn một response cho mỗi tin nhắn đến.

Gửi /queue collect như một lệnh độc lập (theo session) hoặc đặt messages.queue.byChannel.discord: "collect".

Mặc định (khi không đặt trong config):

  • Tất cả surface → collect

Cấu hình toàn cục hoặc theo channel qua messages.queue:

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

Tùy chọn Queue

Các tùy chọn áp dụng cho followup, collect, và steer-backlog (và cho steer khi nó fallback sang followup):

  • debounceMs: đợi yên tĩnh trước khi bắt đầu lượt followup (tránh “continue, continue”).
  • cap: số tin nhắn tối đa trong hàng đợi cho mỗi session.
  • drop: chính sách xử lý tràn (old, new, summarize).

Summarize giữ một danh sách bullet ngắn về các tin nhắn bị bỏ và inject nó như một prompt followup tổng hợp.

Mặc định: debounceMs: 1000, cap: 20, drop: summarize.

Override theo session

  • Gửi /queue <mode> như một lệnh độc lập để lưu mode cho session hiện tại.
  • Các tùy chọn có thể kết hợp: /queue collect debounce:2s cap:25 drop:summarize
  • /queue default hoặc /queue reset xóa override của session.

Phạm vi và đảm bảo

  • Áp dụng cho các lượt chạy Agent auto-reply trên tất cả inbound channel sử dụng gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, v.v.).
  • Lane mặc định (main) là process-wide cho inbound + main heartbeat; đặt agents.defaults.maxConcurrent để cho phép nhiều session chạy song song.
  • Có thể tồn tại các lane bổ sung (ví dụ cron, subagent) để các background job có thể chạy song song mà không chặn inbound reply.
  • Các lane theo session đảm bảo chỉ có một lượt chạy Agent chạm vào một session tại một thời điểm.
  • Không có dependency bên ngoài hoặc background worker thread; thuần TypeScript + promise.

Troubleshooting

  • Nếu lệnh có vẻ bị kẹt, bật verbose log và tìm dòng “queued for …ms” để xác nhận hàng đợi đang xử lý.
  • Nếu các bạn cần biết độ sâu hàng đợi, bật verbose log và theo dõi các dòng queue timing.