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로 직접 검증합니다.
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이 있으면 connection__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, load_skill, connection__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로 다루는 편이 안전합니다.