Ironclaw — 코어 루프 분석

1. 이중 엔진 아키텍처

Ironclaw는 동일한 에이전트 루프를 두 가지 엔진으로 구현한다. 이는 점진적 진화 전략이다.

2. V1 에이전트 루프 (Rust) V1

2.1 run_agentic_loop() — 메인 루프

pub async fn run_agentic_loop(
    delegate: &mut dyn LoopDelegate,
    reason_ctx: &mut ReasoningContext,
    config: &LoopConfig,
) -> Result<LoopOutcome> {

    let mut iteration_state = IterationState::new();
    let mut dup_tracker = DuplicateToolCallTracker::new();  // 중복 도구 호출 감지

    // ═══════════════════════════════════════════════════════
    // 메인 루프: max_iterations (기본 50) 까지 반복
    // ═══════════════════════════════════════════════════════
    for iteration in 1..=config.max_iterations {

        // ── (1) 신호 확인: 취소, 중단, 메시지 주입 ──
        if let Some(signal) = delegate.check_signals().await {
            match signal {
                LoopSignal::Stop => return Ok(LoopOutcome::Stopped),
                LoopSignal::InjectMessages(msgs) => {
                    reason_ctx.messages.extend(msgs);
                }
            }
        }

        // ── (2) 사전 LLM 호출 준비: 비용 가드, 도구 갱신 ──
        delegate.before_llm_call(reason_ctx).await?;

        // ── (3) LLM 호출 ──
        let response = delegate.call_llm(reason_ctx, config).await?;

        // ── (4) 응답 유형별 분기 ──
        match response {
            // 텍스트 응답 → 종료할지 판단
            RespondResult::Text(text) => {
                match handle_text_response(&text, &mut iteration_state, config) {
                    TextAction::Return => {
                        return Ok(LoopOutcome::Completed(text));
                    }
                    TextAction::NudgeToolUse => {
                        // "도구를 실제로 호출하세요" 메시지 주입
                        reason_ctx.messages.push(tool_intent_nudge_message());
                        iteration_state.tool_intent_nudge_count += 1;
                    }
                    TextAction::ForceText => {
                        // 너무 많은 넛지 후 → 텍스트로 강제 종료
                        return Ok(LoopOutcome::Completed(text));
                    }
                }
            }

            // 도구 호출 → 실행 후 결과를 컨텍스트에 추가
            RespondResult::ToolCalls(tool_calls) => {
                // 잘린 도구 호출 처리 (finish_reason == Length)
                if response.finish_reason == FinishReason::Length {
                    iteration_state.truncated_count += 1;
                    if iteration_state.truncated_count >= 3 {
                        // 3회 연속 잘림 → 강제 텍스트 모드
                        config.force_text = true;
                        continue;
                    }
                    // 잘린 도구 호출 폐기, 다른 접근 유도
                    reason_ctx.messages.push(truncated_warning_message());
                    continue;
                }

                // 중복 도구 호출 검사
                let dup_result = dup_tracker.check(&tool_calls);
                match dup_result {
                    DupAction::Allow => {}
                    DupAction::Warn => {
                        // 3회 연속 동일 실패 → 경고 주입
                        reason_ctx.messages.push(duplicate_warning_message());
                    }
                    DupAction::ForceText => {
                        // 5회 연속 → 강제 텍스트 모드
                        config.force_text = true;
                        continue;
                    }
                }

                // ── 도구 실행 ──
                let results = delegate.execute_tool_calls(&tool_calls).await?;

                // ── 피드백 지점: 결과를 컨텍스트에 추가 ──
                for result in results {
                    reason_ctx.messages.push(result);  // ← 다음 LLM 호출의 입력이 됨
                }
            }
        }

        // ── (5) 반복 후 처리 ──
        delegate.after_iteration(iteration, &iteration_state).await?;
    }

    // max_iterations 도달
    Ok(LoopOutcome::MaxIterationsReached)
}

3. V2 오케스트레이터 (Python on Monty VM) V2

3.1 run_loop() — Python 오케스트레이터

def run_loop(context, goal, actions, state, config):
    """V2 에이전트 루프. Monty VM 위에서 실행되는 Python 코드.
    호스트 함수(__llm_complete__, __execute_code_step__ 등)는
    Rust 런타임이 제공한다."""

    max_iterations = config.get("max_iterations", 30)
    step_count = state.get("step_count", 0)

    # 첫 스텝에서 문서 검색 + 스킬 목록 주입
    if step_count == 0:
        # 이전 스레드의 지식을 현재 스레드에 자동 주입
        docs = __retrieve_docs__(goal, 5)  # 목표 기반 관련 문서 검색
        skills = __list_skills__()
        if docs:
            context.append({"role": "system", "content": format_docs(docs)})
        if skills:
            context.append({"role": "system", "content": format_skills(skills)})

    working_messages = list(context)

    # ═══════════════════════════════════════════════════════
    # 메인 루프
    # ═══════════════════════════════════════════════════════
    for step in range(step_count, max_iterations):

        # (1) 정지 신호 확인
        signal = __check_signals__()
        if signal == "stop":
            return {"status": "stopped"}

        # (2) 예산 확인 (토큰/시간/비용)
        budget_status = __check_budget__()
        if budget_status.get("exceeded"):
            return {"status": "budget_exceeded", "reason": budget_status["reason"]}

        # (3) 컨텍스트 압축 — 85% 임계치
        if should_compact(working_messages, config):
            working_messages = compact_if_needed(working_messages, state, config)

        # (4) LLM 호출
        response = __llm_complete__(working_messages, actions)

        # (5) 응답 유형별 처리
        response_type = response.get("type")

        if response_type == "text":
            text = response["content"]

            # FINAL() 추출 — 명시적 종료 신호
            final_answer = extract_final(text)
            if final_answer is not None:
                return {"status": "completed", "answer": final_answer}

            # 도구 의도 넛지: "검색해볼게요"라고만 하고 안 하면
            if has_tool_intent(text) and state.get("nudge_count", 0) < 2:
                working_messages.append({
                    "role": "user",
                    "content": "Please use the available tools to take action, "
                              "don't just describe what you would do."
                })
                state["nudge_count"] = state.get("nudge_count", 0) + 1
                continue

            # 실행 의무 체크
            if state.get("obligation_enabled"):
                working_messages.append({
                    "role": "user",
                    "content": "You must take action using tools. Do not just respond with text."
                })
                continue

            # 일반 텍스트 → 종료
            return {"status": "completed", "answer": text}

        elif response_type == "code":
            # CodeAct: 코드 블록 직접 실행
            result = __execute_code_step__(response["code"])
            output = format_output(result)
            working_messages.append({"role": "User", "content": output})

            # 연속 에러 추적
            if result.get("error"):
                state["consecutive_errors"] = state.get("consecutive_errors", 0) + 1
                if state["consecutive_errors"] >= config.get("max_consecutive_errors", 5):
                    return {"status": "failed", "reason": "max_consecutive_errors"}
            else:
                state["consecutive_errors"] = 0

        elif response_type == "actions":
            # 구조화된 도구 호출 (여러 개 병렬 실행)
            results = __execute_actions_parallel__(response["actions"])
            for result in results:
                working_messages.append({
                    "role": "ActionResult",
                    "content": format_action_result(result)
                })

        # 상태 저장 (재개 가능)
        state["step_count"] = step + 1
        state["working_messages"] = working_messages

    # max_iterations 도달
    return {"status": "max_iterations"}

3.2 FINAL() — 명시적 종료 신호

def extract_final(text):
    """LLM 출력에서 FINAL("답변") 패턴을 추출.
    다양한 형태를 모두 파싱한다."""

    # 지원하는 형태들:
    # FINAL("답변")
    # FINAL('답변')
    # FINAL(\"\"\"여러 줄 답변\"\"\")
    # FINAL(따옴표 없는 답변)
    # FINAL(중첩(괄호)가 있는 답변)

    patterns = [
        r'FINAL\("([^"]*?)"\)',          # 쌍따옴표
        r"FINAL\('([^']*?)'\)",          # 홑따옴표
        r'FINAL\("""(.*?)"""\)',         # 삼중따옴표
        r'FINAL\(([^)]*)\)',             # 미따옴표
    ]

    for pattern in patterns:
        match = re.search(pattern, text, re.DOTALL)
        if match:
            return match.group(1).strip()

    # 중첩 괄호 처리
    if "FINAL(" in text:
        return extract_balanced_parens(text)

    return None

4. 루프 보호 메커니즘

4.1 DuplicateToolCallTracker — 동일 실패 반복 방지

struct DuplicateToolCallTracker {
    history: VecDeque<ToolCallFingerprint>,
    consecutive_duplicates: usize,
}

impl DuplicateToolCallTracker {
    fn check(&mut self, tool_calls: &[ToolCall]) -> DupAction {
        let fingerprint = compute_fingerprint(tool_calls);

        if self.history.back() == Some(&fingerprint) {
            self.consecutive_duplicates += 1;
        } else {
            self.consecutive_duplicates = 0;
        }

        self.history.push_back(fingerprint);

        match self.consecutive_duplicates {
            0..=2 => DupAction::Allow,       // 1-2회: 허용
            3..=4 => DupAction::Warn,        // 3-4회: 경고 주입
            _ => DupAction::ForceText,       // 5회+: 강제 텍스트 모드
        }
    }
}

4.2 잘린 도구 호출 처리

// LLM 출력이 max_tokens에 의해 잘린 경우
// finish_reason == Length → 도구 호출 JSON이 불완전

if response.finish_reason == FinishReason::Length {
    iteration_state.truncated_count += 1;

    if iteration_state.truncated_count >= 3 {
        // 3회 연속 잘림 → 도구가 너무 큰 출력을 만드는 것
        // 강제 텍스트 모드로 전환
        config.force_text = true;
        continue;
    }

    // 잘린 도구 호출 폐기 → 다른 접근 유도
    reason_ctx.messages.push(Message {
        role: "system",
        content: "Your previous tool call was truncated due to output length. \
                  Please try a different approach with shorter arguments, \
                  or break the task into smaller steps."
    });
}

4.3 도구 의도 넛지 (Tool Intent Nudge)

// LLM이 "검색해볼게요", "파일을 확인하겠습니다" 같은 텍스트만 출력하고
// 실제 도구를 호출하지 않는 경우

const TOOL_INTENT_NUDGE: &str = "You expressed intent to use tools but didn't \
    actually call any. Please use the available tools to take action \
    rather than describing what you would do.";

fn handle_text_response(
    text: &str,
    state: &mut IterationState,
    config: &LoopConfig
) -> TextAction {

    // 도구 의도가 감지되고, 넛지 횟수가 한도 미만이면
    if has_tool_intent(text)
        && state.tool_intent_nudge_count < config.max_tool_intent_nudges // 기본 2
    {
        return TextAction::NudgeToolUse;
    }

    // 넛지 한도 초과 → 그냥 텍스트 응답으로 종료
    if state.tool_intent_nudge_count >= config.max_tool_intent_nudges {
        return TextAction::ForceText;
    }

    TextAction::Return
}

5. 자기 수리 시스템 SELF-REPAIR

pub struct RepairTask {
    stuck_threshold: Duration,        // 멈춤 판단 시간
    max_repair_attempts: usize,       // 최대 복구 시도 횟수
    check_interval: Duration,        // 감시 주기
}

impl RepairTask {
    /// 백그라운드에서 주기적으로 실행되는 감시 루프
    pub async fn run(&self, db: &Database) {
        loop {
            sleep(self.check_interval).await;

            // ── (A) 멈춘 작업 감지 및 복구 ──
            let stuck_jobs = db.find_stuck_jobs(self.stuck_threshold).await;
            for job in stuck_jobs {
                if job.repair_attempts >= self.max_repair_attempts {
                    // 최대 시도 초과 → Failed로 전환 (알림 스팸 방지)
                    db.update_job_status(job.id, Status::Failed).await;
                } else {
                    // InProgress로 복구 시도
                    db.update_job_status(job.id, Status::InProgress).await;
                    db.increment_repair_attempts(job.id).await;
                }
            }

            // ── (B) 고장난 도구 감지 및 재빌드 ──
            let broken_tools = db.find_broken_tools(5).await;  // 5회+ 실패
            for tool in broken_tools {
                // 내장 도구는 재빌드 대상에서 제외
                if is_protected_tool_name(&tool.name) {
                    continue;
                }

                // LLM을 사용하여 WASM 도구 자동 재빌드
                let builder = SoftwareBuilder::new();
                builder.rebuild(tool).await;
            }
        }
    }
}

6. 3계층 메모리 아키텍처 MEMORY

6.1 계층 구조

6.2 문서 검색 + 컨텍스트 자동 주입

// V2 루프의 첫 스텝에서 자동 실행 (default.py, 756행)

# 목표(goal)에 기반한 관련 문서 검색
docs = __retrieve_docs__(goal, max_results=5)

# RetrievalEngine의 검색 로직:
# 1. 키워드 매칭으로 후보 필터링
# 2. 문서 타입별 가중치 적용
#    Spec(0.5) > Skill(0.45) > Lesson(0.4) > Plan(0.3)
#    > Issue(0.2) > Summary(0.1) > Note(0.05)
# 3. 상위 N개를 시스템 메시지로 주입

if docs:
    context.append({
        "role": "system",
        "content": format_docs(docs)
    })

6.3 컨텍스트 모니터 — 사용률 기반 전략 선택

// src/agent/context_monitor.rs

pub fn recommend_strategy(usage_percent: f64) -> CompactionStrategy {
    match usage_percent {
        p if p > 95.0 => {
            // 위험: 공격적 절단 (최근 3턴만 유지)
            CompactionStrategy::Truncate { keep_recent: 3 }
        }
        p if p > 85.0 => {
            // 경고: LLM 요약 (최근 5턴 유지)
            CompactionStrategy::Summarize { keep_recent: 5 }
        }
        p if p > 80.0 => {
            // 안전: 워크스페이스로 이동
            CompactionStrategy::MoveToWorkspace
        }
        _ => CompactionStrategy::None
    }
}

// 안전장치: 워크스페이스 쓰기 실패 시 턴을 절대 삭제하지 않음
if let Err(e) = workspace.write(turns_to_archive).await {
    warn!("Workspace write failed: {}. NOT deleting turns.", e);
    return;  // 정보 손실 방지
}

7. 자기 수정 오케스트레이터 V2 ONLY

// 오케스트레이터 로딩 로직

pub fn load_orchestrator(store: &MemoryStore) -> String {

    // 자기 수정이 비활성화되어 있으면 컴파일된 v0 코드 사용
    if !env::var("ORCHESTRATOR_SELF_MODIFY").is_ok() {
        return default_orchestrator_v0();
    }

    // Store에서 최신 오케스트레이터 코드 로드
    let latest = store.get_latest("orchestrator/default.py");

    match latest {
        Some(code) => {
            // Python 구문 검증
            if !validate_python_syntax(&code) {
                warn!("Modified orchestrator has syntax errors, falling back");
                return default_orchestrator_v0();
            }

            // 실패 카운터 확인
            let failures = store.get_failure_count("orchestrator");
            if failures >= MAX_FAILURES_BEFORE_ROLLBACK {  // = 3
                warn!("Orchestrator failed {} times, rolling back", failures);
                return default_orchestrator_v0();
            }

            code
        }
        None => default_orchestrator_v0()
    }
}

// 보호 장치: memory_write에서 오케스트레이터 경로 보호
fn is_protected_orchestrator_path(path: &str) -> bool {
    let normalized = normalize_path(path);  // dot-segment 우회 방지
    normalized.starts_with("orchestrator/")
}

// 자기 수정 활성화 시 인간 승인 필수
fn requires_approval(&self, params: &WriteParams) -> ApprovalRequirement {
    if is_protected_orchestrator_path(&params.path) {
        ApprovalRequirement::Always  // 항상 인간 승인 필요
    } else {
        ApprovalRequirement::UnlessAutoApproved
    }
}

8. 종합 인사이트