명령 대기열(2026-01-16)

여러 에이전트 실행이 충돌하는 것을 방지하는 동시에 세션 전체에서 안전한 병렬 처리를 허용하기 위해 작은 프로세스 내 대기열을 통해 인바운드 자동 응답 실행(모든 채널)을 직렬화합니다.

왜?

자동 회신 실행은 비용이 많이 들 수 있으며(LLM 호출) 여러 인바운드 메시지가 가까이 도착하면 충돌할 수 있습니다.
직렬화는 공유 리소스(세션 파일, 로그, CLI 표준 입력)에 대한 경쟁을 방지하고 업스트림 속도 제한 가능성을 줄입니다.

작동 방식

레인 인식 FIFO 대기열은 구성 가능한 동시성 한도로 각 레인을 비웁니다(구성되지 않은 레인의 경우 기본값 1, 기본 기본값은 4, 하위 에이전트는 8).
runEmbeddedPiAgent는 세션당 하나의 활성 실행만 보장하기 위해 세션 키(레인 session:<key>)로 대기열에 추가됩니다.
각 세션 실행은 전역 레인(기본적으로 main)에 대기열에 추가되므로 전체 병렬 처리는 agents.defaults.maxConcurrent로 제한됩니다.
자세한 로깅이 활성화되면 대기열에 있는 실행이 시작되기 전에 ~2초 이상 기다린 경우 짧은 알림을 보냅니다.
입력 표시기는 대기열에 추가될 때 즉시 실행되므로(채널에서 지원하는 경우) 차례를 기다리는 동안 사용자 경험은 변경되지 않습니다.

대기열 모드(채널별)

인바운드 메시지는 현재 실행을 조정하거나 후속 차례를 기다리거나 두 가지를 모두 수행할 수 있습니다.

steer: 현재 실행에 즉시 삽입합니다(다음 도구 경계 이후 보류 중인 도구 호출을 취소합니다). 스트리밍하지 않는 경우 후속 조치로 돌아갑니다.
followup: 현재 실행이 끝난 후 다음 에이전트 차례를 위해 대기열에 추가됩니다.
collect: 대기 중인 모든 메시지를 단일 후속 조치 차례(기본값)로 통합합니다. 메시지가 다른 채널/스레드를 대상으로 하는 경우 라우팅을 유지하기 위해 개별적으로 드레이닝됩니다.
steer-backlog (일명 steer+backlog): 지금 방향을 바꾸고 **후속 회전을 위한 메시지를 보존하세요.
interrupt (레거시): 해당 세션에 대한 활성 실행을 중단한 다음 최신 메시지를 실행합니다.
queue (기존 별칭): steer와 동일합니다.

조향 백로그는 조향 실행 후 후속 응답을 얻을 수 있음을 의미합니다. 스트리밍 표면은 중복된 것처럼 보일 수 있습니다. 원하는 경우 collect/steer를 선호합니다. 인바운드 메시지당 하나의 응답. /queue collect를 독립 실행형 명령(세션별)으로 보내거나 messages.queue.byChannel.discord: "collect"을 설정합니다.

기본값(구성에서 설정되지 않은 경우):

모든 표면 → collect

messages.queue를 통해 전역적으로 또는 채널별로 구성합니다.

json5

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

대기열 옵션

옵션은 followup, collect 및 steer-backlog에 적용됩니다(후속 작업으로 되돌아가는 경우 steer에도 적용됩니다).

debounceMs: 후속 턴을 시작하기 전에 조용해질 때까지 기다립니다(“계속, 계속” 방지).
cap: 세션당 대기 중인 최대 메시지 수입니다.
drop: 오버플로 정책 (old, new, summarize).

요약은 삭제된 메시지의 짧은 글머리 기호 목록을 유지하고 이를 종합 후속 프롬프트로 삽입합니다. 기본값: debounceMs: 1000, cap: 20, drop: summarize.

세션별 재정의

현재 세션의 모드를 저장하기 위해 /queue <mode>를 독립형 명령으로 보냅니다.
옵션을 조합할 수 있습니다: /queue collect debounce:2s cap:25 drop:summarize
/queue default 또는 /queue reset는 세션 재정의를 지웁니다.

범위 및 보증

게이트웨이 응답 파이프라인(WhatsApp 웹, Telegram, Slack, Discord, Signal, iMessage, 웹 채팅 등)을 사용하는 모든 인바운드 채널에서 실행되는 자동 응답 에이전트에 적용됩니다.
기본 레인(main)은 인바운드 + 기본 하트비트에 대한 프로세스 전체입니다. 여러 세션을 병렬로 허용하려면 agents.defaults.maxConcurrent을 설정하세요.
인바운드 응답을 차단하지 않고 백그라운드 작업을 병렬로 실행할 수 있도록 추가 레인(예: cron, subagent)이 존재할 수 있습니다.
세션별 레인은 한 번에 하나의 에이전트 실행만 지정된 세션에 닿도록 보장합니다.
외부 종속성이나 백그라운드 작업자 스레드가 없습니다. 순수 TypeScript + 약속.

문제 해결

명령이 중단된 것 같으면 자세한 로그를 활성화하고 "queued for ...ms" 줄을 찾아 대기열이 소모되고 있는지 확인하세요.
대기열 깊이가 필요한 경우 자세한 로그를 활성화하고 대기열 타이밍 라인을 살펴보세요.

명령 대기열(2026-01-16) ​

왜? ​

작동 방식 ​

대기열 모드(채널별) ​

대기열 옵션 ​

세션별 재정의 ​

범위 및 보증 ​

문제 해결 ​