Ch4. Compiler와 Runtime Graph
Eve가 source manifest를 compiled manifest와 runtime agent graph로 바꾸는 과정을 분석한다.
핵심 요약
- Eve의 안정성은 source manifest, compiled manifest, runtime graph를 분리하는 데서 나옵니다.
- tool registry는 framework default, authored tool, connection tool, dynamic tool이 한데 합쳐지는 충돌 표면입니다.
- 배포 게이트에서는
.eve/산출물과 manifest version을 운영 artifact로 직접 검증합니다.
소스 분석의 범위
내부 파일 경로·타입·manifest 분석은 2026-06의 0.11.4 체크아웃 기준입니다. 현재 0.82.0의 공개 계약은 공식 API 문서와 설치 패키지의 타입을 확인합니다. 내부 심볼을 애플리케이션 API로 import하지 않습니다.
Eve의 안정성은 “작성된 파일을 그때그때 해석해서 실행”하지 않는 데서 나옵니다. 빌드/런타임 경계에서 manifest와 module map을 만들어 두고, runtime은 그 산출물을 읽어 registry를 구성합니다.
Pipeline 개요
compileAgent()의 의미
compiler/compile-agent.ts의 compileAgent()는 다음 순서로 동작합니다.
resolveDiscoveryProject()로 app root와 agent root를 찾는다.discoverAgent()로 source manifest와 diagnostics를 만든다.writeCompilerArtifacts()로.eve/artifact를 쓴다.- discovery error가 있으면
CompileAgentError를 던진다. - warning은 console에 출력하고 result를 반환한다.
여기서 핵심은 error가 있어도 artifact는 남는다는 점입니다. 실패한 빌드도 들여다볼 수 있어야 하니까요.
Manifest version을 운영 표면으로 본다
compiler/manifest.ts에는 COMPILED_AGENT_MANIFEST_VERSION = 29가 정의되어 있습니다. 이 버전은 runtime이 compiled manifest를 어떻게 읽을지 결정하는 schema 계약입니다.
엔터프라이즈 운영에서는 다음을 기록해야 합니다.
| 값 | 왜 필요한가 |
|---|---|
| Eve package version | public API와 behavior 기준 |
| compiled manifest version | 배포 artifact schema 기준 |
| discovery manifest version | source scan 결과 schema 기준 |
| durable session version | in-flight session migration 기준 |
Eve 업그레이드 때는 “npm package update”만 보지 말고 manifest/durable session version 변화까지 확인합니다.
Runtime graph 해석
runtime/resolve-agent-graph.ts는 compiled manifest를 runtime-owned graph로 바꿉니다.
이 단계에서 실제 model-visible surface가 확정됩니다.
| 병합 대상 | 규칙 |
|---|---|
| framework tools | 기본 tool set을 준비한다. |
| authored tools | 같은 이름이면 framework default를 override한다. |
| disabled framework tools | disableTool()이 framework default를 제거한다. |
| connections | connection이 있으면 eve__search dynamic resolver를 추가한다. |
| subagents | subagent를 tool namespace에 등록한다. |
| framework channels | 기본 Eve HTTP channel을 포함한다. |
| authored channels | 같은 이름이면 default channel을 override한다. |
| disabled framework channels | disableRoute()로 default route를 제거한다. |
그래서 “이 agent가 가진 tool 목록”은 파일 목록 하나로 판단하면 안 됩니다. eve info나 compiled manifest/runtime inspection을 기준으로 봅니다.
Tool registry와 이름 충돌
Subagent도 tool처럼 모델에게 노출됩니다. 예를 들어 agent/subagents/researcher/는 researcher tool이 됩니다. 이 이름은 authored tool namespace와 같습니다.
충돌 예:
agent/tools/researcher.ts
agent/subagents/researcher/agent.tsEve는 이런 충돌을 build/runtime resolution에서 거부합니다. 엔터프라이즈라면 namespace convention을 미리 정해 두는 편이 안전합니다.
| 종류 | 추천 이름 |
|---|---|
| 일반 tool | 동사 기반: query_warehouse, create_ticket |
| subagent | 역할 기반: researcher, reviewer, operator |
| connection tool | Eve가 connection__<name>__<tool>로 qualified |
| dynamic tool map | <fileSlug>__<key> |
Framework defaults를 통제하는 법
기본 harness는 bash, read_file, write_file, glob, grep, web_fetch, web_search, todo, ask_question, agent, eve__skill, eve__search를 상황에 따라 노출합니다.
위험한 default는 세 가지 방식으로 다룹니다.
| 방식 | 예 | 의미 |
|---|---|---|
| disable | agent/tools/bash.ts에서 disableTool() | 모델에게 capability 자체를 숨김 |
| override | default tool을 spread하고 wrapper 실행 | 로깅, 제한, 정책 추가 |
| author new | 새 tool 작성 | domain-specific action 추가 |
프로덕션에서는 최소한 bash, web_fetch, write_file의 정책은 검토합니다. sandbox가 격리돼 있어도 open egress와 file write는 그대로 공격면입니다.
Runtime node는 agent별 독립 실행 단위다
ResolvedRuntimeAgentNode는 다음 registry를 가집니다.
| Registry | 의미 |
|---|---|
toolRegistry | model-visible authored/framework tools |
subagentRegistry | local/remote subagent delegation tools |
hookRegistry | stream event subscribers |
sandboxRegistry | agent별 sandbox backend와 workspace resources |
channels | mounted route/channel definitions |
turnAgent | harness가 사용할 prompt/model/tool snapshot |
Declared subagent도 자체 node를 가집니다. 권한 격리는 여기서 출발합니다. root와 child는 같은 runtime graph 안에 있지만 tool, skill, sandbox registry는 node마다 다릅니다.
turnAgent는 한 turn의 실행 스냅샷이다
runtime/agent/bootstrap.ts의 createResolvedRuntimeTurnAgent()는 resolved agent를 harness가 실행할 수 있는 형태로 줄입니다.
turnAgent에 들어가는 것:
- agent id/name
- composed base prompt
- model reference
- compaction model
- output schema
- prepared tools
- workspace spec
- node id
운영 관점에서 turnAgent는 “현재 배포에서 한 turn이 어떤 모델/프롬프트/도구/워크스페이스로 실행될지”를 찍어 둔 스냅샷입니다.
HMR과 production prompt snapshot
execution/session.ts에는 refreshSessionFromTurnAgent()가 있습니다. 세션은 history와 state를 보존하면서 model/tool metadata를 refresh합니다. 다만 production에서는 session-start system prompt를 보존하는 쪽이 기본이고, dev HMR에서는 authored source에서 refresh할 수 있습니다.
이 차이가 운영에서 크게 작용합니다.
| 상황 | 기준 |
|---|---|
| 장기 세션 중 prompt 수정 | 기존 세션 prompt가 자동으로 바뀐다고 가정하지 않는다. |
| 운영 중 hotfix | 새 세션과 기존 세션의 behavior 차이를 추적한다. |
| regulated workflow | 세션 시작 시점 prompt version을 감사 로그에 남긴다. |
배포 게이트
Compiler/runtime pipeline을 운영 게이트로 바꾸면 다음과 같습니다.
| Gate | 확인 |
|---|---|
| Discovery gate | .eve/diagnostics.json error/warning 없음 |
| Surface gate | compiled manifest의 tools/connections/channels 목록 승인 |
| Default tool gate | 위험 default disabled/overridden 여부 |
| Subagent gate | tool namespace 충돌 없음, 권한 축소 확인 |
| Manifest gate | Eve version, manifest version, artifact hash 기록 |
| Eval gate | surface 변경마다 최소 smoke eval 통과 |
Eve의 파일시스템 모델은 읽기 쉬운 대신 파일 하나만 추가해도 권한 표면이 금세 불어납니다. Compiler/runtime artifact를 release evidence로 다루는 편이 안전합니다.