쿼리 엔진 & LLM API

쿼리 엔진은 사용자 메시지를 받아 LLM 응답을 생성하기까지의 모든 과정을 관장합니다. 네 개의 레이어로 구성됩니다:

• 레이어 1 — QueryEngine.submitMessage(): 프롬프트 검증, 시스템 프롬프트 구성, 모델 해석, 트랜스크립트 기록
• 레이어 2 — query() / queryLoop(): 도구 호출 루프 — 모델이 end_turn을 반환하거나 터미널 조건에 도달할 때까지 반복
• 레이어 3 — queryModel / callModel: Anthropic API 호출, withRetry()를 통한 재시도 및 폴백
• 레이어 4 — 스톱 훅 & 토큰 예산: 루프 종료 조건을 관리하고, 후속 작업(메모리 추출, 프롬프트 제안 등)을 트리거

사용자 메시지부터 최종 응답까지의 전체 흐름을 시퀀스 다이어그램으로 추적합니다.

QueryEngine은 하나의 대화 세션에 대한 모든 상태를 보유합니다. 핵심 상태로 mutableMessages(대화 히스토리), abortController(취소 제어), totalUsage(누적 토큰 사용량)를 관리합니다.

submitMessage()의 흐름:

1. 시스템 프롬프트 구축 — 정적 섹션 + 동적 섹션 + CLAUDE.md 주입
2. 사용자 입력 처리 — 검증, 모델 해석, 메시지 변환
3. API 호출 전 트랜스크립트를 디스크에 기록 — 프로세스가 중간에 종료되더라도 세션 재개가 가능하도록 보장
4. query() 호출로 실제 API 통신 시작

// QueryEngine — submitMessage 흐름 (간소화)
async submitMessage(userInput: UserInput) {
  const systemPrompt = await buildSystemPrompt()
  this.mutableMessages.push(userMessage)

  // 프로세스 종료 시에도 세션 재개 가능하도록 미리 기록
  await writeTranscript(this.mutableMessages)

  return await this.query(systemPrompt)
}

queryLoop()는 쿼리 엔진의 심장부입니다. while(true) 루프로 동작하며, 각 반복의 결과를 State 타입으로 표현합니다.

State는 두 가지 범주로 분류됩니다:

Continue 전환 — 루프가 계속되는 7가지 이유:

• max_output_tokens_escalate — 출력 토큰 한도 도달 시 더 높은 한도로 재시도
• max_output_tokens_recovery — 에스컬레이션 후 복구
• reactive_compact_retry — 컨텍스트 초과 시 압축 후 재시도
• collapse_drain_retry — 컨텍스트 붕괴 후 드레인 재시도
• stop_hook_blocking — 스톱 훅이 계속 진행을 요청
• token_budget_continuation — 토큰 예산 내에서 자동 계속
• needs_follow_up — 도구 호출 결과에 대한 후속 처리 필요

Terminal 종료 조건: end_turn, 예산 소진, 치명적 오류, 사용자 중단 등으로 루프가 종료됩니다.

// query.ts — queryLoop 상태 타입
type State = {
  messages: Message[]
  toolUseContext: ToolUseContext
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number
  hasAttemptedReactiveCompact: boolean
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
  stopHookActive: boolean | undefined
  turnCount: number
  transition: Continue | undefined   // 다시 루프한 이유
}

// queryLoop — State 타입 (간소화)
type State =
  | { kind: 'continue'; transition: { reason: ContinueReason } }
  | { kind: 'terminal'; result: QueryResult }

// reason 필드 = 이전 반복이 종료 대신 계속을 결정한 이유

Anthropic API와의 통신은 SSE(Server-Sent Events) 스트리밍으로 이루어집니다. 스트림 청크가 도착하는 대로 재구성되어 사용자에게 실시간으로 표시됩니다.

주요 메커니즘:

• SSE 스트림 재구성: 청크 단위로 도착하는 토큰을 어시스턴트 메시지로 조합
• 스트리밍 도구 실행: 도구 호출이 완전히 수신되기 전에도 부분적으로 파싱하여 실행 준비
• 툼스톤 메시지: API 오류나 중단 시 메시지 히스토리에 오류 마커를 삽입하여 후속 컨텍스트에서 참조 가능

대화가 길어지면 컨텍스트 윈도우를 초과할 수 있습니다. 쿼리 엔진은 5단계 파이프라인으로 컨텍스트를 자동 관리합니다:

1. applyToolResultBudget — 도구 결과의 크기를 예산 내로 잘라냄
2. snipCompact — 오래된 메시지의 도구 결과를 요약으로 대체
3. microcompact — 미세 압축: 공백 제거, 반복 패턴 축소
4. contextCollapse — 컨텍스트 붕괴: 대화의 큰 블록을 요약으로 대체
5. autoCompact — 자동 압축: LLM을 사용하여 전체 대화를 요약

이 단계들은 점진적으로 적용됩니다. 가벼운 방법부터 시도하고, 그래도 부족하면 더 공격적인 압축을 수행합니다.

// services/api/withRetry.ts — 백오프 공식
export function getRetryDelay(
  attempt: number,
  retryAfterHeader?: string | null,
  maxDelayMs = 32000,
): number {
  if (retryAfterHeader) {
    const seconds = parseInt(retryAfterHeader, 10)
    if (!isNaN(seconds)) return seconds * 1000
  }
  const baseDelay = Math.min(
    BASE_DELAY_MS * Math.pow(2, attempt - 1),
    maxDelayMs,
  )
  const jitter = Math.random() * 0.25 * baseDelay
  return baseDelay + jitter
}

handleStopHooks()는 모델이 end_turn을 반환했을 때 실행되며, 세 가지 카테고리의 훅을 처리합니다:

• Stop Hooks: 사용자 정의 종료 조건 — 훅이 "계속"을 반환하면 stop_hook_blocking 전환으로 루프 지속
• TaskCompleted: 작업 완료 시그널 — SDK 모드에서 자동 종료 트리거
• TeammateIdle: 팀메이트 에이전트가 유휴 상태인지 확인

Fire-and-Forget 백그라운드 작업: 스톱 훅 처리 후 다음 작업들이 백그라운드에서 실행됩니다:

• 메모리 추출 — 대화에서 학습한 내용을 MEMORY.md에 저장
• 프롬프트 제안 — 다음 사용자 입력에 대한 제안 생성
• 자동 드림 — 유휴 시간에 에이전트가 자율적으로 사고

SDK 경로에서는 토큰 예산이 설정되어 에이전트의 자동 계속을 관리합니다.

• 90% 완료 임계값: 예산의 90%를 소비하면 모델에게 마무리를 유도하는 신호를 보냄
• 500토큰 미만 체감 감소 감지: checkTokenBudget()이 3회 이상 연속으로 양쪽(입력+출력) 델타가 500토큰 미만이면 진전 없음으로 판단하고 조기 중단을 트리거

이 메커니즘은 모델이 동일한 패턴을 반복하며 토큰을 낭비하는 것을 방지합니다.