명령 큐 (2026-01-16)

수신 자동 응답 실행(모든 채널)을 작은 프로세스 내 큐를 통해 직렬화하여, 여러 에이전트 실행이 충돌하는 것을 방지하면서도 세션 간 안전한 병렬 처리를 허용합니다.

이유

  • 자동 응답 실행은 비용이 많이 들 수 있으며(LLM 호출), 여러 수신 메시지가 가까운 시간에 도착하면 충돌할 수 있습니다.
  • 직렬화를 통해 공유 리소스(세션 파일, 로그, CLI stdin) 경합을 방지하고 업스트림 속도 제한 발생 가능성을 줄입니다.

작동 방식

  • 레인 인식 FIFO 큐가 구성 가능한 동시성 상한으로 각 레인을 처리합니다(미구성 레인의 기본값 1, main 기본값 4, subagent 기본값 8).
  • runEmbeddedPiAgent는 세션 키(session:<key> 레인)로 큐에 넣어 세션당 하나의 활성 실행만 보장합니다.
  • 각 세션 실행은 전역 레인(기본값 main)에 큐잉되어 전체 병렬 처리가 agents.defaults.maxConcurrent로 제한됩니다.
  • 상세 로깅이 활성화된 경우 시작 전 약 2초 이상 대기한 큐 실행은 짧은 알림을 출력합니다.
  • 타이핑 표시는 큐에 넣는 즉시 발생하므로(채널이 지원하는 경우) 대기 중에도 사용자 경험은 동일합니다.

큐 모드 (채널별)

수신 메시지는 현재 실행을 조정하거나, 후속 턴을 기다리거나, 둘 다 수행할 수 있습니다:

  • steer: 현재 실행에 즉시 주입 (다음 도구 경계 이후 대기 중인 도구 호출 취소). 스트리밍 중이 아니면 followup으로 폴백.
  • followup: 현재 실행이 끝난 후 다음 에이전트 턴으로 큐잉.
  • collect: 큐에 쌓인 모든 메시지를 하나의 후속 턴으로 통합 (기본값). 메시지가 다른 채널/스레드를 대상으로 하는 경우 라우팅을 유지하기 위해 개별적으로 처리됩니다.
  • steer-backlog (별칭 steer+backlog): 지금 조정하고 동시에 후속 턴을 위해 메시지 보존.
  • interrupt (레거시): 해당 세션의 활성 실행을 중단하고 최신 메시지를 실행.
  • queue (레거시 별칭): steer와 동일.

steer-backlog는 조정된 실행 이후 후속 응답을 받을 수 있어 스트리밍 환경에서 중복처럼 보일 수 있습니다. 수신 메시지당 하나의 응답을 원하면 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으로 세션 오버라이드를 초기화합니다.

범위 및 보장

  • 게이트웨이 응답 파이프라인을 사용하는 모든 수신 채널(WhatsApp 웹, Telegram, Slack, Discord, Signal, iMessage, 웹챗 등)의 자동 응답 에이전트 실행에 적용됩니다.
  • 기본 레인(main)은 수신 + 메인 하트비트에 대해 프로세스 전역이며, agents.defaults.maxConcurrent를 설정하여 여러 세션의 병렬 처리를 허용할 수 있습니다.
  • 추가 레인(예: cron, subagent)이 있어 백그라운드 작업이 수신 응답을 차단하지 않고 병렬로 실행될 수 있습니다.
  • 세션별 레인은 지정된 세션에 대해 한 번에 하나의 에이전트 실행만 수행되도록 보장합니다.
  • 외부 의존성이나 백그라운드 워커 스레드 없이 순수 TypeScript + Promise로 구현됩니다.

문제 해결

  • 명령이 멈춘 것 같다면 상세 로그를 활성화하고 “queued for …ms” 행을 확인하여 큐가 정상적으로 처리되고 있는지 확인하세요.
  • 큐 깊이를 확인하려면 상세 로그를 활성화하고 큐 타이밍 행을 모니터링하세요.
arrow_back
이전
Retry
다음
Tools
arrow_forward