에이전트 루프 · 도구 시스템 — oxicode ⇄ oxios 해부

0. 전체 지도 — 호출이 지나는 5개 층

같은 루프를 두 소비자가 쓴다. oxicode CLI는 TUI에서 바로 SDK로, oxios는 Web WS·Telegram 표면에서 게이트웨이→오케스트레이터→수퍼바이저를 거쳐 같은 SDK 계약층으로 내려온다.

1. 도구의 정체 — 하나의 트레이트, 두 벌의 옷

oxicode에서 도구는 enum도 구조체 등록도 아닌 async 트레이트다. 실행 로직(Rust 세계)과 모델에게 보이는 정의(JSON 세계)가 서로 다른 타입으로 분리돼 있다 — 이것이 "같은 도구가 공급자를 바꿔도 동작하는" 비결이다.

pub trait AgentTool: Send + Sync {
    fn name(&self) -> &str;                      // "bash"
    fn label(&self) -> &str;                     // UI 표시용
    fn description(&self) -> &str;               // ← 모델이 읽는 설명
    fn parameters_schema(&self) -> Value;        // ← JSON Schema
    fn essential(&self) -> bool { false }        // 컨텍스트 축소 시에도 유지
    fn tool_tier(&self) -> ToolTier { ToolTier::Exec }  // 권한 티어

    async fn execute(&self, tool_call_id: &str, params: Value,
        signal: Option<oneshot::Receiver<()>>,     // 취소 신호
        ctx: &ToolContext) -> Result<AgentToolResult, ToolError>;

    fn to_definition(&self) -> ToolDefinition;   // LLM 전송용 변환
    // … 총 15개 메서드 (render_call · intent · execution_mode · tab slot …)
}
// oxicode-agent/src/tools.rs:744-873 — 트레이트다 (enum/구조체 아님)

// oxicode-ai/src/providers/anthropic.rs:205-207, 664-680
body["tools"] = json!([{
    "name": "bash",
    "description": "Run a shell command …",
    "input_schema": { "type": "object", "properties": { … } }
}]);
// 같은 정의가 방언만 바껴 나간다 —
// OpenAI openai.rs:598-620 · Ollama ollama.rs:210-225 · Gemini google_shared.rs:210

ToolTier { Read, Write, Exec }(tools.rs:732-742)는 도구의 위험도 등급이다. 읽기 도구와 셸 실행이 같은 승인 정책을 통과하면 안 되기 때문 — 아래 §3 관문에서 이 등급이 그대로 승인 판정의 기준이 된다. 구체 예: BashTool(tools/bash.rs:168-171 구조체, :490-540 impl)는 essential = true라 컨텍스트 절약을 위해 도구를 골라 낼 때도 살아남는다.

2. 등록 — ToolRegistry로 모이는 3갈래 공급원

레지스트리는 HashMap<String, Arc<dyn AgentTool>> 하나다(tools.rs:997-1003). 정적 내장·외부 MCP·호스트 커널 도구가 전부 같은 이름 공간에 등록되고, 루프는 그 출처를 구분하지 않는다. 구분하는 책임은 등록하는 쪽에 있다.

oxios가 주입하는 도구 30+ — 실제 목록

// oxicode-sdk/src/kernel_bridge.rs:111-124 — 호스트 도구 주입 계약
pub trait KernelToolProvider: Send + Sync {
    fn tool_names(&self) -> Vec<&str>;
    fn register_tools(&self, registry: &ToolRegistry, context: &KernelToolContext);
}
// KernelToolContext(:24-80) = workspace · agent_id · session_id · permissions

3. 호출 1회의 관문 — ToolCall에서 ToolResult까지 9단계

모델이 tool_use 블록을 내놓는 순간부터 결과가 히스토리에 꽂히기까지, 도구 호출은 9개의 관문을 순서대로 통과한다. 면접에서 "에이전트 안전성"을 묻는다면 이 9단계가 답이다.

승인 판정 — 3분기와 opt-in 설계

주의 — 권한 시스템은 opt-in이다. ApprovalConfig.require_approval_for가 비어 있으면 전부 즉시 허용된다(tool_exec.rs:292-294). .oxi 권한 규칙 파일 같은 건 없고 정책은 전부 코드/훅으로 주입한다 — 파일 기반 설정은 MCP에만 있다(.oxicode/mcp.json + 동의 파일 mcp-consent.json, consent.rs:210). 제품 수준의 정책(권한·감사·비용)은 oxios가 SDK port(AccessGate·authorizer)로 끼워 넣는다 — agent_runtime.rs:1046-1054에서 authorizer · tracer · cost_tracker를 AgentBuilder에 꽂는 게 그 지점.

4. 루프 해부 — 2중 while과 1턴의 14단계

run_loop(mod.rs:761)는 상태 머신이 아니라 플래그 기반 2중 루프다. 안쪽 while이 "1턴"의 단위(모델 응답 → 도구 실행 → 결과 삽입), 바깥 loop는 실행 중 개입(steering·follow-up)을 놓치지 않기 위한 재드레인 층이다. 이중 구조가 "에이전트가 일하는 도중에 말을 걸 수 있는" 이유다.

1턴 전체 시퀀스 — 14단계

1. 1 TurnStart { turn_number } mod.rs:794-804
2. 2 steering 메시지 처리 — 실행 중 끼어든 사용자 입력을 히스토리에 삽입 mod.rs:806-814, :675-703
3. 3 poll_external_queues — 훅이 새로 넣은 steer/follow-up 드레인 mod.rs:816-818, :465
4. 4 maybe_compact — 토큰 임계면 컨텍스트 압축 (아래 §6) mod.rs:820-821
5. 5 append_only.sync_from — prefix-stable 컨텍스트 동기화 mod.rs:823-825
6. 6 stream_assistant_response — 시스템 프롬프트+도구 정의 조립 → LLM 스트리밍 mod.rs:827-829, streaming.rs:68-129
7. 7 StreamOutcome 분기 — Error→재시도/종료 · Aborted→종료 · TTSR 위반→부분 출력 폐기 후 재시도 mod.rs:831-972, retry.rs
8. 8 extract_tool_calls — tool_use 없으면 has_more_tool_calls = false mod.rs:986-990, helpers.rs:7
9. 9 execute_tool_calls — 9 관문 통과 (시퀀셜/병렬 분기) mod.rs:991-1015, tool_exec.rs:340-355
10. 10 ToolResult 메시지 삽입 → 루프 가드 → soft-requirement 검사 mod.rs:1020-1169
11. 11 TurnEnd 이벤트 → should_stop_after_turn (external_stop이면 즉시 종료) mod.rs:1176-1190, helpers.rs:50
12. 12 안쪽 while 판정 — has_more_tool_calls || pending_messages mod.rs:794, :1201-1206
13. 13 바깥 loop — late steering · follow-up · final steering 재드레인 mod.rs:1212-1234
14. 14 todo 리마인더 (유계: signature dedup + 상한) 후 없으면 break mod.rs:1240-1257

TTSR(Time-Traveling Stream Rules) — 스트리밍 중 프로젝트 룰 위반을 TextDelta마다 검사해(ttsr.rs, streaming.rs:316-360) 위반 시 그 턴의 부분 출력을 버리고 룰을 시스템 리마인더로 주입한 뒤 재시도한다(mod.rs:885-938). omp의 TtsrManager 이식이며 Regex + AST(ast-grep) 2종 매칭을 지원한다. (구 보고서의 "Textual Trajectory Stream Rule" 표기는 오기다.)

5. 살아있는 루프 — 컴팩션 · 스트리밍 · 훅 · 세션

6. oxios — 루프를 만들지 않고 루프를 산다

oxios의 가장 중요한 설계 결정: 자체 에이전트 루프를 작성하지 않았다. run_agent(agent_runtime.rs:737)는 SDK의 AgentBuilder로 Agent를 조립하고 run_streaming() 한 번을 기다리기만 한다. oxios가 소유한 것은 루프 주변이다 — 표면·오케스트레이션·도구·정책.

// oxios/crates/oxios-kernel/src/agent_runtime.rs — run_agent(:737)
let mut builder = engine.oxi()            // oxicode-sdk Oxicode 진입점
    .agent(agent_config)                  // AgentBuilder (RFC-014 Phase D)
    .workspace(&workspace)
    .system_prompt(system_prompt);
// … authorizer · tracer · cost_tracker · rate limit · token budget (:1046-1066)

let built = builder.build()?;

// SDK builder의 .tool()은 concrete 타입만 받는데 oxios 도구는 Arc<dyn AgentTool>.
// SDK가 pre-built ToolRegistry 주입을 지원하지 않으므로
// build 후 agent.tools() 레지스트리에 register_arc로 주입한다 (:1071-1078).
for tool in cspace_tool_arcs {
    agent_tools.register_arc(tool);
}

// 루프는 여기서 시작되지 않는다 — 소유권은 SDK에 있다.
let result = agent.run_streaming(prompt, move |event| { … }).await;  // :1109-1110

supervisor가 두 개다 — 역할이 다르다

7. 면접 답변 스크립트