Ch2. 소스 코드 지도
packages/eve/src를 구현 책임별로 해부하고 엔터프라이즈 설계자가 읽어야 할 핵심 파일을 정리한다.
핵심 요약
packages/eve/src는 public API, discovery/compiler, runtime/harness, execution 계층으로 읽으면 구조가 명확해집니다.- Discovery와 compiler는 authored module을 곧바로 믿지 않고 manifest와
.eve/산출물로 실행 표면을 정규화합니다. - 운영자는 source file이 아니라 runtime graph, tool registry, durable execution driver를 리뷰 대상으로 삼아야 합니다.
이 장은 Eve 0.11.4의 packages/eve/src를 읽기 위한 지도입니다. 전체 파일을 무작정 따라가면 public, internal, execution, runtime, harness, setup, evals가 뒤섞여 보이지만 계층은 분명합니다.
디렉터리 책임
| 디렉터리 | 책임 | 읽는 목적 |
|---|---|---|
public/ | 사용자-facing API와 framework integrations | authoring contract 확인 |
discover/ | agent/ 파일 슬롯 탐색 | 어떤 파일이 권한 표면이 되는지 확인 |
compiler/ | source manifest를 compiled manifest/module map으로 변환 | 배포 산출물과 진단 artifact 이해 |
runtime/ | compiled graph를 실행 가능한 registry로 해석 | framework defaults, subagent, sandbox, hook 결합 이해 |
harness/ | AI SDK tool loop, compaction, HITL, telemetry | 한 turn의 품질/안전 메커니즘 이해 |
execution/ | Workflow session/turn/step orchestration | durable execution과 park/resume 이해 |
channel/ | channel adapter, send/receive/session helpers | delivery, continuation token, event handler 이해 |
client/ | TypeScript client, reducer, NDJSON stream | 앱/테스트/스크립트 호출 방식 이해 |
evals/ | eve eval runner와 assertion | regression gate 설계 |
setup/ | eve init, channel add, Vercel link/deploy helpers | bootstrap 자동화와 scaffolding 이해 |
shared/ | 공통 타입, schema, guard | manifest와 런타임 공통 계약 이해 |
공개 API는 public/에서 시작한다
packages/eve/src/index.ts는 거의 비어 있고 #public/index.js를 export합니다. 사용자가 import하는 표면은 다음처럼 분리됩니다.
| Import | 주 용도 |
|---|---|
eve | defineAgent, defineRemoteAgent |
eve/tools | defineTool, defineDynamic, disableTool, ExperimentalWorkflow |
eve/connections | MCP/OpenAPI connection 정의 |
eve/channels/* | Eve/Slack/GitHub/Teams 등 채널 |
eve/sandbox/* | Vercel/Docker/microsandbox/just-bash backend |
eve/evals | eval config와 eval case |
eve/client | 세션 생성, follow-up, stream 소비 |
운영 관점에서 public/은 “작성자가 건드릴 수 있는 API”이고, 나머지 디렉터리는 “Eve가 책임지는 실행 엔진”입니다. 내부 구현에 기댄 monkey patch는 피하세요.
Discovery와 Compiler는 authored code를 신뢰하지 않는다
discover/discover-agent.ts는 agent root를 읽고 슬롯별 source ref를 모읍니다. 이 단계의 핵심은 authored module을 import하지 않는다는 데 있습니다. 파일 경로, 확장자, 디렉터리 형태, markdown frontmatter 같은 정적 정보만 수집합니다.
읽어야 할 파일:
| 파일 | 핵심 역할 |
|---|---|
discover/project.ts | flat/nested agent root 해석 |
discover/discover-agent.ts | root entries를 슬롯별 discovery로 분기 |
discover/grammar.ts | tool/channel/hook 이름 검증, instructions discovery |
discover/skills.ts | flat skill, packaged skill, frontmatter 처리 |
discover/sandbox.ts | sandbox.ts vs sandbox/sandbox.ts와 workspace seed |
compiler/compile-agent.ts | discovery 실행, artifact write, diagnostic error 처리 |
compiler/manifest.ts | compiled manifest schema와 version |
이 구조 덕분에 eve info, eve build, .eve/diagnostics.json는 운영자가 신뢰할 수 있는 inspection surface가 됩니다.
Runtime은 graph와 registry를 만든다
runtime/resolve-agent-graph.ts는 compiled manifest를 실행 가능한 agent graph로 바꿉니다. 여기서 중요한 병합이 발생합니다.
- framework default tools와 authored tools 병합
disableTool()sentinel 처리- framework default channels와 authored channels 병합
- connections가 있으면
connection__searchdynamic resolver 추가 - subagent를 model-visible tool namespace에 등록
- sandbox registry, tool registry, hook registry 생성
그래서 실제 모델이 보는 도구 목록은 agent/tools/ 파일 목록 그대로가 아닙니다. built-in tools, authored overrides, disabled defaults, dynamic tools, subagents, connections를 모두 합친 결과입니다.
Harness는 한 turn의 품질 엔진이다
harness/tool-loop.ts는 Eve 실행의 중심입니다. AI SDK ToolLoopAgent를 사용하지만, Eve가 그 위에 다음 기능을 얹습니다.
| 기능 | 구현 관심사 |
|---|---|
| compaction | context window threshold, summary checkpoint |
| HITL | input.requested, approval/question park |
| dynamic capabilities | stream event 후 tool/skill/instruction resolver |
| telemetry | OTel parent span, runtimeContext, usage tags |
| provider tools | web_search provider mapping |
| tool output shaping | toModelOutput, authorization output redaction |
| runtime actions | subagent/remote agent action dispatch |
| code mode | experimental model-authored JS tool orchestration |
고급 사용자가 가장 자주 붙잡고 디버깅하는 곳도 이 레이어입니다. “왜 도구가 안 보이지?”, “왜 승인 후 메시지가 밀렸지?”, “왜 session.waiting에서 멈췄지?”는 대부분 harness와 execution이 맞물린 지점에서 생깁니다.
Execution은 durable workflow driver다
execution/workflow-entry.ts는 long-lived workflow body입니다. 여기서 session을 만들고, turn workflow를 dispatch하고, park hook을 만들고, runtime action result나 follow-up delivery를 받아 다음 turn으로 넘깁니다.
핵심 파일:
| 파일 | 역할 |
|---|---|
execution/workflow-entry.ts | session driver loop, park/resume, auth hook |
execution/turn-workflow.ts | 한 turn을 short-lived workflow로 실행 |
execution/workflow-steps.ts | durable "use step" 경계에서 harness 실행 |
execution/durable-session-store.ts | session snapshot과 migration-aware durable state |
execution/session.ts | HarnessSession 생성/재수화/compaction config |
execution/subagent-tool.ts | subagent 호출과 parent notification |
execution/remote-agent-dispatch.ts | 원격 Eve agent dispatch |
이 레이어를 이해하면 Eve의 내구성이 단순한 retry가 아님이 보입니다. session snapshot, continuation token, emission state, proxy input request state가 step result를 타고 이동합니다.
엔터프라이즈 코드 리뷰 관점
소스 지도는 코드 리뷰 체크리스트로 바로 바뀝니다.
| 변경 위치 | 리뷰 질문 |
|---|---|
agent/tools/** | 외부 부작용이 있는가? approval/idempotency가 있는가? output redaction이 있는가? |
agent/connections/** | token principal type, allow/block filter, approval이 적절한가? |
agent/channels/** | route auth가 fail-closed인가? body-supplied identity를 신뢰하지 않는가? |
agent/sandbox/** | network policy가 production에 맞는가? seed file에 비밀값이 없는가? |
agent/hooks/** | hook failure가 turn failure로 번지지 않도록 격리했는가? |
agent/subagents/** | root 권한을 불필요하게 복제하지 않았는가? |
evals/** | 변경된 risk surface를 실제 HTTP session으로 검증하는가? |
Eve를 도입할 때는 이 지도를 팀의 CODEOWNERS, PR template, release checklist에 반영하는 편이 좋습니다.