Streaming on ICE-ICE-BEAR-BLOG

Claude Code 하네스 해부학 #1 — 진입점에서 응답까지, 요청 하나의 여정

Mon, 06 Apr 2026 00:00:00 +0900

개요

Claude Code의 소스 구조를 27세션에 걸쳐 체계적으로 해부하는 시리즈의 첫 번째 글이다. 이 포스트에서는 사용자가 터미널에 “hello"를 입력했을 때, 응답이 화면에 출력되기까지 거치는 11개 TypeScript 파일의 전체 콜스택을 추적한다.

분석 대상: 11개 핵심 파일

#	경로	줄 수	역할
1	`entrypoints/cli.tsx`	302	CLI 부트스트랩, 인자 파싱, 모드 라우팅
2	`main.tsx`	4,683	메인 REPL 컴포넌트, Commander 설정
3	`commands.ts`	754	커맨드 레지스트리
4	`context.ts`	189	시스템 프롬프트 조립, CLAUDE.md 주입
5	`QueryEngine.ts`	1,295	세션 관리, SDK 인터페이스
6	`query.ts`	1,729	핵심 턴 루프 — API + 도구 실행
7	`services/api/client.ts`	389	HTTP 클라이언트, 4개 프로바이더 라우팅
8	`services/api/claude.ts`	3,419	Messages API 래퍼, SSE 스트리밍, 재시도
9	`services/tools/toolOrchestration.ts`	188	동시성 파티셔닝
10	`services/tools/StreamingToolExecutor.ts`	530	스트리밍 중 도구 실행
11	`services/tools/toolExecution.ts`	1,745	도구 디스패치, 권한 검사

총 15,223줄을 추적한다.

1. 진입과 부트스트랩: cli.tsx -> main.tsx

cli.tsx는 302줄에 불과하지만, 놀라울 정도로 많은 패스트-패스(fast-path) 분기가 존재한다:

cli.tsx:37 --version -> 즉시 출력, import 0개
cli.tsx:53 --dump-system -> 최소 import
cli.tsx:100 --daemon-worker -> 워커 전용 경로
cli.tsx:112 remote-control -> 브릿지 모드
cli.tsx:185 ps/logs/attach -> 백그라운드 세션
cli.tsx:293 기본 경로 -> main.tsx 동적 import

설계 의도: --version 하나를 위해 main.tsx의 4,683줄을 로딩하지 않겠다는 것이다. CLI 도구의 체감 응답성에 직접 영향을 미치는 최적화다.

기본 경로에서는 동적 import로 main.tsx를 로드한다:

// cli.tsx:293-297
const { main: cliMain } = await import('../main.js');
await cliMain();

main.tsx가 4,683줄인 이유는 다음을 모두 포함하기 때문이다:

사이드 이펙트 import (1-209행): profileCheckpoint, startMdmRawRead, startKeychainPrefetch — 모듈 평가 시점에 병렬 서브프로세스를 시작하여 약 65ms의 macOS keychain 읽기를 숨긴다
Commander 설정 (585행~): CLI 인자 파싱, 10+개 모드별 분기
React/Ink REPL 렌더링: 터미널 UI 마운트
헤드리스 경로 (-p/--print): UI 없이 QueryEngine 직접 사용

2. 프롬프트 조립: context.ts의 dual-memoize

context.ts는 189줄의 작은 파일이지만 시스템 프롬프트의 동적 부분을 전담한다. 두 개의 메모이즈된 함수가 핵심이다:

getSystemContext() (context.ts:116): git 상태(branch, status, 최근 커밋)를 수집
getUserContext() (context.ts:155): CLAUDE.md 파일들을 탐색/파싱

왜 분리했는가? Anthropic Messages API의 프롬프트 캐싱 전략과 직결된다. 시스템 프롬프트와 사용자 컨텍스트의 캐시 수명이 다르므로 cache_control을 서로 다르게 적용해야 한다. memoize로 감싸서 세션 내 한 번만 계산한다.

context.ts:170-176에서 setCachedClaudeMdContent()를 호출하는 것은 순환 의존성을 끊기 위한 장치다 — yoloClassifier가 CLAUDE.md 내용을 필요로 하지만, 직접 import하면 permissions -> yoloClassifier -> claudemd -> permissions 순환이 발생한다.

3. AsyncGenerator 체인: 아키텍처의 척추

Claude Code의 전체 데이터 플로우는 AsyncGenerator 체인으로 구성된다:

QueryEngine.submitMessage()* -> query()* -> queryLoop()* -> queryModelWithStreaming()*

모든 핵심 함수가 async function*이다. 이는 단순한 구현 선택이 아니라 아키텍처적 결정이다:

Backpressure: 소비자가 느리면 생산자도 대기
취소: AbortController와 결합하여 즉각적인 취소 가능
합성: yield*로 제너레이터 체인을 자연스럽게 연결
상태 관리: 루프 내 로컬 변수가 턴 간 상태를 자연스럽게 유지

QueryEngine.submitMessage() (QueryEngine.ts:209)의 시그니처를 보면:

async *submitMessage(
 prompt: string | ContentBlockParam[],
 options?: { uuid?: string; isMeta?: boolean },
): AsyncGenerator<SDKMessage, void, unknown>

SDK 모드에서 각 메시지는 yield로 스트리밍되며, Node.js의 backpressure가 자연스럽게 구현된다.

4. 핵심 턴 루프: query.ts의 while(true)

query.ts(1,729줄)의 queryLoop()가 실제 API+도구 루프다:

// query.ts:307
while (true) {
 // 1. queryModelWithStreaming() 호출 -> SSE 스트림
 // 2. 스트리밍 이벤트를 yield
 // 3. 도구 호출 감지 -> runTools()/StreamingToolExecutor
 // 4. 도구 결과를 메시지에 추가
 // 5. stop_reason == "end_turn" -> break
 // stop_reason == "tool_use" -> continue
}

State 타입(query.ts:204)이 중요하다. messages, toolUseContext, autoCompactTracking, maxOutputTokensRecoveryCount 등 루프 상태를 명시적 레코드로 관리하여, continue 사이트에서 한 번에 갱신한다.

5. API 통신: 4개 프로바이더와 캐싱

client.ts:88의 getAnthropicClient()는 4가지 프로바이더를 지원한다:

프로바이더	SDK	동적 import 이유
Anthropic Direct	`Anthropic`	기본, 즉시 로딩
AWS Bedrock	`AnthropicBedrock`	AWS SDK 수 MB
Azure Foundry	`AnthropicFoundry`	Azure Identity 수 MB
GCP Vertex	`AnthropicVertex`	Google Auth 수 MB

claude.ts(3,419줄)의 핵심 함수 체인:

queryModelWithStreaming() (claude.ts:752)
 -> queryModel()
 -> withRetry()
 -> anthropic.beta.messages.stream() (SDK 호출)

캐싱 전략은 getCacheControl() (claude.ts:358)이 1시간 TTL 여부를 사용자 유형, 피처 플래그, 쿼리 소스에 따라 결정한다.

6. 도구 오케스트레이션: 3-tier 동시성

flowchart TD
 TC["도구 호출 배열<br/>[ReadFile, ReadFile, Bash, ReadFile]"]
 P["partitionToolCalls()<br/>toolOrchestration.ts:91"]
 B1["Batch 1<br/>ReadFile + ReadFile<br/>isConcurrencySafe=true"]
 B2["Batch 2<br/>Bash<br/>isConcurrencySafe=false"]
 B3["Batch 3<br/>ReadFile<br/>isConcurrencySafe=true"]
 PAR["Promise.all()<br/>최대 10개 동시"]
 SEQ["순차 실행"]
 PAR2["Promise.all()"]

 TC --> P
 P --> B1
 P --> B2
 P --> B3
 B1 --> PAR
 B2 --> SEQ
 B3 --> PAR2

 style B1 fill:#e8f5e9
 style B2 fill:#ffebee
 style B3 fill:#e8f5e9

StreamingToolExecutor(530줄)는 이 배치 파티셔닝을 스트리밍 컨텍스트로 확장한다. API 응답이 스트리밍되는 도중에 도구 호출을 감지하면 즉시 실행을 시작한다:

addTool() (StreamingToolExecutor.ts:76) — 큐에 추가
processQueue() (StreamingToolExecutor.ts:140) — 동시성 확인 후 즉시 실행
getRemainingResults() (StreamingToolExecutor.ts:453) — 모든 도구 완료 대기

에러 전파 규칙: Bash 에러만 형제 도구를 취소한다 (siblingAbortController). Read/WebFetch 에러는 다른 도구에 영향을 주지 않는다. 이는 Bash 명령 간의 암묵적 의존성(mkdir 실패 -> 후속 명령 무의미)을 반영한 설계다.

전체 데이터 플로우

sequenceDiagram
 participant User as 사용자
 participant CLI as cli.tsx
 participant Main as main.tsx
 participant QE as QueryEngine
 participant Query as query.ts
 participant Claude as claude.ts
 participant API as Anthropic API
 participant Tools as toolOrchestration
 participant Exec as toolExecution

 User->>CLI: "hello" 입력
 CLI->>Main: dynamic import
 Main->>QE: new QueryEngine()
 QE->>Query: query()
 Query->>Claude: queryModelWithStreaming()
 Claude->>API: anthropic.beta.messages.stream()
 API-->>Claude: SSE 스트림

 alt stop_reason == end_turn
 Claude-->>User: 응답 출력
 else stop_reason == tool_use
 Claude-->>Query: tool_use blocks
 Query->>Tools: partitionToolCalls()
 Tools->>Exec: runToolUse()
 Exec->>Exec: canUseTool() + tool.call()
 Exec-->>Query: 도구 결과
 Note over Query: while(true) 다음 반복
 end

Rust 갭 지도 미리보기

동일한 요청을 Rust 포트에서 추적한 결과, 31개 갭을 식별했다:

우선순위	갭 수	핵심 예시
P0 (치명적)	2	동기 ApiClient, StreamingToolExecutor 부재
P1 (높음)	6	3-tier 동시성, 프롬프트 캐싱, Agent 도구
P2 (보통)	7	멀티 프로바이더, 노력 제어, 샌드박스
구현 완료	11	자동 압축, SSE 파서, OAuth, 설정 로딩

구현 완료율: 36% (11/31). 다음 포스트에서 이 갭들의 핵심인 대화 루프를 깊이 파고든다.

인사이트

AsyncGenerator가 아키텍처의 척추다 — 단순한 구현 기법이 아니라 backpressure, 취소, 합성을 한 번에 해결하는 설계 결정이다. Rust에서는 Stream trait이 대응하지만 yield* 합성의 인체공학이 크게 다르다.
main.tsx 4,683줄은 기술 부채다 — Commander 설정, React 컴포넌트, 상태 관리가 한 파일에 혼재. 역사적 성장의 결과로, 모듈 분리의 기회가 된다.
도구 동시성이 단순하지 않다 — “전부 병렬” 또는 “전부 직렬"이 아닌 3계층 모델(읽기 배치, 쓰기 순차, Bash 형제 취소)은 실전 에이전트 하네스의 핵심 설계 요소다.

다음 포스트: #2 — 대화 루프의 심장, StreamingToolExecutor와 7개의 continue

Claude Code 하네스 해부학 #2 — 대화 루프의 심장, StreamingToolExecutor와 7개의 continue

Mon, 06 Apr 2026 00:00:00 +0900

개요

시리즈 첫 번째 글에서 “hello” 한마디가 11개 파일을 관통하는 여정을 추적했다. 이번 포스트에서는 그 여정의 심장부인 query.ts 1,729줄의 while(true) 루프를 완전 해부한다. 7가지 continue 경로가 만드는 탄력적 실행 모델, StreamingToolExecutor의 4단계 상태 머신, 그리고 partitionToolCalls()의 3계층 동시성 모델을 분석한 뒤, Rust 프로토타입에서 이를 어떻게 재현했는지 대조한다.

분석 대상: 10개 핵심 파일

#	경로	줄 수	역할
1	`query/config.ts`	46	이뮤터블 런타임 게이트 스냅샷
2	`query/deps.ts`	40	테스트 가능한 I/O 경계 (DI)
3	`query/tokenBudget.ts`	93	토큰 예산 관리, 자동 연속/중단 결정
4	`query/stopHooks.ts`	473	Stop/TaskCompleted/TeammateIdle 훅
5	`query.ts`	1,729	핵심 – while(true) 턴 루프
6	`QueryEngine.ts`	1,295	세션 래퍼, SDK 인터페이스
7	`toolOrchestration.ts`	188	도구 파티셔닝 + 동시성 제어
8	`StreamingToolExecutor.ts`	530	SSE 중 도구 파이프라이닝
9	`toolExecution.ts`	1,745	도구 디스패치, 권한 검사
10	`toolHooks.ts`	650	Pre/PostToolUse 훅 파이프라인

총 6,789줄의 핵심 오케스트레이션 코드를 해부한다.

1. queryLoop()의 7가지 continue 경로

query.ts의 queryLoop() 함수(query.ts:241)는 단순한 API 호출 루프가 아니다. 7가지 continue 사유를 가진 탄력적 실행기다. 각 경로는 고유한 장애 시나리오를 처리한다:

사유	행	설명
`collapse_drain_retry`	1114	컨텍스트 축소 드레인 후 재시도
`reactive_compact_retry`	1162	반응형 압축 후 재시도 (413 복구)
`max_output_tokens_escalate`	1219	8k -> 64k 토큰 에스컬레이션
`max_output_tokens_recovery`	1248	“이어서 작성하라” 넛지 메시지 주입
`stop_hook_blocking`	1303	Stop 훅이 블로킹 에러 반환
`token_budget_continuation`	1337	토큰 예산 미달로 계속
`next_turn`	1725	도구 실행 완료 후 다음 턴

State 타입이 핵심이다 (query.ts:204-217). 루프 상태를 10개 필드의 레코드로 관리한다. 왜 개별 변수가 아닌 레코드인가? continue 사이트가 7곳이며, 각각 state = { ... }으로 한 번에 갱신한다. 9개 변수를 개별 할당하면 하나를 빠뜨리는 실수가 발생하기 쉽다. 레코드 갱신은 타입 시스템이 누락을 잡아준다.

루프 한 반복의 전체 흐름

1. 전처리 (365-447): snip 압축, 마이크로 컴팩트, 컨텍스트 축소
2. 자동 압축 (454-543): 성공 시 메시지 교체 후 continue
3. 블로킹 한도 검사 (628-648): 토큰 임계값 초과 시 즉시 종료
4. API 스트리밍 (654-863): SSE 이벤트를 for await로 소비
5. 도구 없는 종료 경로 (1062-1357): 413 복구, max_output 복구, stop 훅
6. 도구 있는 계속 경로 (1360-1728): 나머지 도구 실행 -> next_turn

2. StreamingToolExecutor의 4단계 상태 머신

StreamingToolExecutor.ts(530줄)는 Claude Code에서 가장 정교한 동시성 패턴이다. 핵심 아이디어: API 응답이 아직 스트리밍되는 동안 이미 완성된 도구 호출의 실행을 시작한다.

모델이 [ReadFile("a.ts"), ReadFile("b.ts"), Bash("make test")]를 한 번에 호출하는 경우, 파이프라이닝 없이는 세 도구 블록이 모두 도착한 후에야 실행이 시작된다. 파이프라이닝에서는 ReadFile("a.ts") 블록이 완성되는 즉시 파일 읽기가 시작된다.

stateDiagram-v2
 [*] --> queued: addTool()
 queued --> executing: processQueue()<br/>canExecuteTool() == true
 queued --> completed: 사전 취소<br/>getAbortReason() != null

 executing --> completed: 도구 실행 완료<br/>또는 sibling abort

 completed --> yielded: getCompletedResults()<br/>순서대로 yield

 yielded --> [*]

 note right of queued
 processQueue()는 addTool()
 + 이전 도구 완료 시 자동 트리거
 end note

 note right of completed
 Bash 에러 시
 siblingAbortController.abort()
 형제 도구만 취소
 end note

동시성 결정 로직 (canExecuteTool, line 129)

실행 가능 조건:
 - 현재 실행 중인 도구가 없음 (executingTools.length === 0)
 - 또는: 이 도구가 concurrencySafe이고 실행 중인 모든 도구도 concurrencySafe

read-only 도구끼리는 병렬 실행이 가능하지만, write 도구가 하나라도 있으면 그 도구가 끝날 때까지 다음 도구는 대기한다.

siblingAbortController – 계층적 취소

siblingAbortController(line 46-61)는 toolUseContext.abortController의 자식이다. Bash 도구가 에러를 발생시키면 siblingAbortController.abort('sibling_error')를 호출하여 형제 도구만 취소한다. 부모 컨트롤러는 영향을 받지 않으므로 전체 쿼리는 계속 실행된다.

왜 Bash 에러만 형제를 취소하는가? mkdir -p dir && cd dir && make에서 mkdir이 실패하면 후속 명령은 무의미하다. ReadFile이나 WebFetch 실패는 독립적이므로 다른 도구에 영향을 주지 않아야 한다.

3. partitionToolCalls – 3계층 동시성 모델

toolOrchestration.ts(188줄)는 도구 실행의 동시성 모델 전체를 정의한다.

flowchart TD
 TC["도구 호출 배열<br/>[ReadFile, ReadFile, Bash, ReadFile]"]
 P["partitionToolCalls()<br/>toolOrchestration.ts:91"]
 B1["Batch 1<br/>ReadFile + ReadFile<br/>isConcurrencySafe=true"]
 B2["Batch 2<br/>Bash<br/>isConcurrencySafe=false"]
 B3["Batch 3<br/>ReadFile<br/>isConcurrencySafe=true"]
 PAR["Promise.all()<br/>최대 10개 동시"]
 SEQ["순차 실행"]
 PAR2["Promise.all()"]

 TC --> P
 P --> B1
 P --> B2
 P --> B3
 B1 --> PAR
 B2 --> SEQ
 B3 --> PAR2

 style B1 fill:#e8f5e9
 style B2 fill:#ffebee
 style B3 fill:#e8f5e9

규칙은 단순하다: 연속된 isConcurrencySafe 도구는 하나의 배치로 묶고, 그렇지 않은 도구는 각각 독립 배치가 된다. 이 결정은 도구 정의 자체에서 나온다 – tool.isConcurrencySafe(parsedInput) 호출로 결정된다. 같은 도구라도 입력에 따라 동시성 안전성이 달라질 수 있다.

컨텍스트 수정자와 경쟁 조건

왜 배치 완료 후 순서대로 적용하는가? 병렬 실행 중 컨텍스트 수정자를 즉시 적용하면 경쟁 조건이 발생한다. A가 먼저 완료되어 컨텍스트를 수정하면, 아직 실행 중인 B는 수정 전 컨텍스트로 시작했지만 수정 후 컨텍스트를 보게 된다. 배치 완료 후 원래 도구 순서대로 적용하면 결정론적 결과를 보장한다 (toolOrchestration.ts:54-62).

4. 도구 실행 파이프라인과 훅

toolExecution.ts(1,745줄)의 runToolUse()(line 337)가 개별 도구 호출의 전체 생명주기를 관리한다:

runToolUse() 진입점
 1. findToolByName() -- deprecated 별칭으로 재시도 (345-356)
 2. abort 체크 -- 이미 취소되었으면 CANCEL_MESSAGE (415)
 3. streamedCheckPermissionsAndCallTool() -- 권한 + 실행 + 훅 (455)
 -> checkPermissionsAndCallTool():
 a. Zod 스키마로 입력 유효성 검사 (615)
 b. tool.validateInput() 커스텀 검증 (683)
 c. 투기적 분류기 (Bash 전용, 740)
 d. runPreToolUseHooks() (800)
 e. resolveHookPermissionDecision() (921)
 f. tool.call() 실제 실행 (1207)
 g. runPostToolUseHooks() 결과 변환

resolveHookPermissionDecision의 핵심 불변식

resolveHookPermissionDecision()(toolHooks.ts:332)에서 훅의 allow가 settings.json의 deny/ask 규칙을 바이패스하지 않는다 (toolHooks.ts:373). 훅이 allow해도 checkRuleBasedPermissions()를 통과해야 한다. 이것은 “훅은 자동화 도우미이지 보안 우회가 아니다"라는 설계 원칙을 반영한다.

훅 결과가 allow일 때:
 -> checkRuleBasedPermissions() 호출
 -> null이면 통과 (규칙 없음)
 -> deny이면 규칙이 훅을 오버라이드
 -> ask이면 사용자 프롬프트 필요

5. Rust 대조 – 152줄 vs 1,729줄

Rust의 ConversationRuntime::run_turn()은 152줄의 단일 loop {} (conversation.rs:183-272)로 구성된다. TS의 7가지 continue 경로 중 Rust에 존재하는 것은 next_turn(도구 실행 완료 후 다음 턴) 딱 하나뿐이다.

TS continue 사유	Rust 상태	이유
`collapse_drain_retry`	미구현	컨텍스트 축소 없음
`reactive_compact_retry`	미구현	413 복구 없음
`max_output_tokens_escalate`	미구현	8k->64k 에스컬레이션 없음
`max_output_tokens_recovery`	미구현	멀티턴 넛지 없음
`stop_hook_blocking`	미구현	Stop 훅 없음
`token_budget_continuation`	미구현	토큰 예산 시스템 없음
`next_turn`	구현됨	도구 결과 후 API 재호출

가장 치명적인 갭: 동기적 API 소비

Rust의 ApiClient 트레이트 시그니처가 모든 것을 말해준다:

fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError>;

반환 타입이 Vec<AssistantEvent>다. 스트리밍이 아니다. SSE 이벤트를 모두 수집한 후 벡터로 반환한다. 이로 인해 모델이 5개 ReadFile을 호출할 때, TS는 첫 번째 ReadFile이 스트리밍 중에 실행 완료될 수 있지만, Rust는 5개 모두 스트리밍이 끝난 후에야 순차 실행을 시작한다. 레이턴시 차이가 도구 수에 비례하여 증가한다.

6. Rust 프로토타입 – 갭 브릿지

S04 프로토타입에서 P0 갭 3개를 브릿지하는 오케스트레이션 레이어를 구현했다:

flowchart LR
 subgraph TS["TS 스트리밍 파이프라인"]
 direction TB
 ts1["SSE 이벤트 스트림"]
 ts2["StreamingToolExecutor<br/>4-state machine"]
 ts3["getCompletedResults()<br/>yield 순서 보장"]
 ts1 --> ts2 --> ts3
 end

 subgraph Rust["Rust 프로토타입"]
 direction TB
 rs1["EventStream<br/>tokio async"]
 rs2["StreamingPipeline<br/>tokio::spawn + mpsc"]
 rs3["MessageEnd 후<br/>채널 수집 + 정렬"]
 rs1 --> rs2 --> rs3
 end

 subgraph Bridge["핵심 매핑"]
 direction TB
 b1["yield -> tx.send()"]
 b2["yield* -> 채널 전달"]
 b3["for await -> while let recv()"]
 end

 TS ~~~ Bridge ~~~ Rust

 style TS fill:#e1f5fe
 style Rust fill:#fff3e0
 style Bridge fill:#f3e5f5

프로토타입의 3가지 구현

1. 비동기 스트리밍: ApiClient 트레이트를 비동기 스트림으로 확장. MessageStream::next_event()가 이미 비동기이므로 소비 측만 변경하면 된다.

2. 도구 파이프라이닝: ToolUseEnd 이벤트 수신 시 누적된 입력으로 ToolCall을 조립하고 tokio::spawn으로 즉시 백그라운드 실행을 시작한다. mpsc::unbounded_channel로 완료 순서로 수집하고 나중에 원래 순서로 정렬한다.

3. 3-tier 동시성: ToolCategory enum(ReadOnly/Write/BashLike)에 따라 파티셔닝. ReadOnly 배치는 Semaphore(10) + tokio::spawn으로 최대 10개 병렬. BashLike는 순차 실행 + 에러 시 나머지 중단.

프로토타입 커버리지

TS 기능	프로토타입	상태
`partitionToolCalls()` 3-tier	`partition_into_runs()` + `ToolCategory`	구현
`runToolsConcurrently()` max 10	`Semaphore(10)` + `tokio::spawn`	구현
`siblingAbortController`	BashLike에서 `break`	단순화
`StreamingToolExecutor.addTool()`	`ToolUseEnd` 시 `tokio::spawn`	구현
PreToolUse hook deny/allow	`HookDecision::Allow/Deny`	구현
PostToolUse output transform	`HookResult::transformed_output`	구현
4-state machine (queued->yielded)	spawned/completed 2-state	미완성
413 복구 / max_output 에스컬레이션	–	미구현
`preventContinuation`	–	미구현

정지 조건 비교

조건	TS	Rust
도구 없음 (end_turn)	`handleStopHooks()` 실행 후 종료	즉시 `break`
토큰 예산 초과	`checkTokenBudget()` 3가지 결정	없음
max_output_tokens	에스컬레이션 + 멀티턴 복구	없음
413 prompt-too-long	컨텍스트 축소 + 반응형 압축	에러 전파
maxTurns	`maxTurns` 파라미터 (query.ts:1696)	`max_iterations`
수확 체감	3회 이상 + 500토큰 미만 증가	없음

tokenBudget.ts(93줄)의 checkTokenBudget()은 프롬프트 크기가 아닌 응답 연속 여부를 제어한다. COMPLETION_THRESHOLD = 0.9(전체 버짓의 90% 미만이면 계속), DIMINISHING_THRESHOLD = 500(연속 3회 이상 매번 500토큰 미만 생성 시 수확 체감으로 중단). nudgeMessage가 명시적으로 “do not summarize"를 지시한다.

설계 결정의 핵심 – 왜 AsyncGenerator인가

전체 파이프라인이 async function* 체인이다:

QueryEngine.submitMessage()* -> query()* -> queryLoop()* -> deps.callModel()*
runTools()* -> runToolUse()* -> handleStopHooks()* -> executeStopHooks()*

이 선택의 핵심 이점: 제어 흐름의 반전 없이 복잡한 상태 기계를 구현할 수 있다. 7가지 continue 경로에서 state = { ... }로 상태를 명시적으로 구성하고 continue하면 된다. 콜백 기반이었다면 상태 관리가 분산되어 7가지 복구 경로의 정합성을 보장하기 어려웠을 것이다.

Rust에서는 yield 키워드가 안정화되지 않았으므로, tokio::sync::mpsc 채널로 대체한다. yield -> tx.send(), yield* -> 채널 전달, for await...of -> while let Some(v) = rx.recv().

인사이트

query.ts의 7가지 continue는 “에러 처리"가 아니라 “탄력성 엔진"이다 – 413 에러에서 컨텍스트를 축소하고, max_output에서 토큰을 에스컬레이션하며, stop 훅 블로킹에서 에러를 모델에 피드백한다. 이 복구 파이프라인이 장시간 자율 작업의 안정성을 보장한다. Rust에서 이를 재현하려면 단순한 loop {} 이상의 상태 관리가 필요하다.
StreamingToolExecutor는 성능 최적화가 아니라 UX 결정이다 – 도구 5개를 직렬로 실행하면 사용자가 체감하는 대기 시간이 직렬 합산이 된다. 파이프라이닝은 벤치마크 수치가 아니라 “응답을 기다리는” 시간을 줄이는 사용자 경험 요소다. Rust 프로토타입에서 tokio::spawn + mpsc 채널로 이를 20줄 이내에 구현할 수 있었다.
정적 파티셔닝 + 런타임 동시성의 이중 구조가 안전성과 성능을 양립시킨다 – partitionToolCalls()가 컴파일 타임에 배치를 나누고, canExecuteTool()이 런타임에 실행 가능 여부를 판단한다. 이 이중 구조 덕분에 비스트리밍 경로(runTools)와 스트리밍 경로(StreamingToolExecutor)가 동일한 동시성 의미론을 공유한다.

다음 포스트: #3 – 42개 도구의 설계 철학, BashTool부터 AgentTool까지