OMX - Native Spark

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편 (본문)	Native & Spark	Rust 네이티브 도구는 뭔가

---

• Native & Spark는 Rust로 구현된 읽기 전용 탐색 엔진(explore-harness)과 적응적 출력 요약 사이드카(sparkshell)
• 셸 명령어 allowlist + 경로 탈출 차단 + read-only 샌드박스로 에이전트의 코드베이스 탐색을 안전하게 제한하며, 12줄 초과 출력을 LLM 기반으로 요약하여 컨텍스트 예산을 보호하는 네이티브 빠른 경로(native fast path)
• OMC에는 없는 OMX만의 고유 기능으로, Cargo 워크스페이스 빌드 + 멀티 플랫폼 배포 + SHA-256 검증 + 자동 hydration 캐싱을 갖춘 Rust-TypeScript 하이브리드 아키텍처

해당 개념이 필요한 이유

• 7편까지의 에이전트는 코드베이스 탐색 시 Codex CLI의 기본 셸 실행에 의존 — 실수로 쓰기 작업 가능, 파이프 조합으로 예측 불가한 명령 실행 가능
• 긴 셸 출력(예: rg 결과 수천 줄)이 그대로 컨텍스트에 들어가면 토큰 예산 낭비 + LLM 주의력 분산
• explore-harness는 안전한 읽기 전용 탐색, sparkshell은 출력 요약으로 컨텍스트 절약 — 두 도구가 이 간극을 메움

AS-IS (Codex CLI 기본 셸 — 무제한 실행)

sequenceDiagram
    autonumber
    participant CX as Codex CLI (에이전트)
    participant SH as Shell
    participant FS as 파일 시스템

    CX->>SH: rg "auth" src/ | head -50
    Note over SH: 파이프, 리다이렉션 허용
    SH->>FS: 읽기 + 잠재적 쓰기
    SH-->>CX: 수천 줄 원시 출력
    Note over CX: 전체 출력이 컨텍스트에 주입
    Note over CX: 토큰 예산 낭비
    Note over CX: 실수로 rm, mv 등 실행 가능

TO-BE (explore-harness + sparkshell — 안전 + 요약)

sequenceDiagram
    autonumber
    participant CX as Codex CLI (에이전트)
    participant EH as explore-harness (Rust)
    participant SS as sparkshell (Rust)
    participant LLM as Spark Model

    alt 탐색 작업
        CX->>EH: omx explore --prompt "API 엔드포인트 찾기"
        EH->>EH: allowlist 검증 (10개 명령어만)
        EH->>EH: 경로 탈출 차단
        EH->>EH: read-only 샌드박스 실행
        EH-->>CX: 마크다운 요약 반환
    else 긴 출력 명령
        CX->>SS: omx sparkshell rg "auth" src/
        SS->>SS: 명령 실행
        SS->>SS: 출력 12줄 초과?
        SS->>LLM: 요약 요청 (summary/failures/warnings)
        LLM-->>SS: 구조화된 요약
        SS-->>CX: 요약된 출력 (컨텍스트 절약)
    end

explore-harness — 읽기 전용 탐색 엔진 (소스: crates/omx-explore/src/main.rs)

Shell Allowlist — 허용되는 명령어 10개

const ALLOWED_DIRECT_COMMANDS: &[&str] = &[
    "rg", "grep", "ls", "find", "wc", "cat", "head", "tail", "pwd", "printf",
];

이 10개 명령어만 실행할 수 있다. 나머지는 모두 차단된다.

명령어별 제한 사항

명령어	추가 제한	이유
rg	--pre 차단, stdin(-) 차단	코드 실행 방지
grep	패턴 + 파일 경로 필수, stdin 차단	임의 입력 방지
find	-exec, -execdir, -ok, -delete, -fprint* 차단	쓰기/실행 방지
cat, head, wc	파일 경로 필수, stdin 차단	임의 입력 방지
tail	파일 경로 필수, -f, -F, --follow 차단	무한 대기 방지
ls, pwd, printf	추가 제한 없음	안전한 명령어

셸 메타 문자 전면 차단

// validate_shell_invocation()에서 차단하는 문자열
for fragment in ["\n", "\r", "&&", "||", ";", "|", ">", "<", "`", "$(", "${"] {
    if command.contains(fragment) {
        return Err(...);
    }
}

파이프, 리다이렉션, 논리 연산자, 서브셸, 변수 확장 — 셸 조합의 모든 경로를 차단한다.

✓ rg auth src                    # 단순 검색 — 허용
✓ find . -type f -name "*.ts"    # 파일 찾기 — 허용
✗ rg auth src | head             # 파이프 — 차단
✗ find . -exec rm {} +           # exec — 차단
✗ /usr/bin/rg needle             # 경로 지정 — 차단
✗ tail -f logfile                # follow 모드 — 차단

경로 탈출 방지 — 4단계 검증

OMX_EXPLORE_ROOT 환경 변수로 설정된 레포지토리 루트를 기준으로 모든 경로를 검증한다:

1. 정규화 — ., .. 컴포넌트 해석
2. 포함 확인 — 정규화된 경로가 repo root로 시작하는지 검증
3. 심링크 해석 — canonicalize로 심링크 탈출 감지
4. 정규 경로 확인 — 해석된 경로가 여전히 repo root 내에 있는지 재검증

✗ cat ../secret.txt              # ../ 탈출 — 차단
✗ cat /tmp/passwd                # 절대 경로 외부 — 차단
✗ cat linked-outside/secret      # 심링크 탈출 — 차단

Allowlist 환경 격리 — 래퍼 메커니즘

explore-harness는 실행 환경 자체를 격리한다:

sequenceDiagram
    autonumber
    participant EH as explore-harness
    participant TMP as /tmp/allowlist/bin/
    participant CX as codex exec
    participant W as wrapper (rg)
    participant RG as /usr/bin/rg (실제)

    EH->>TMP: 허용 명령어별 래퍼 스크립트 생성
    Note over TMP: PATH를 이 디렉토리로 교체
    EH->>CX: codex exec (PATH=tmp/bin, SHELL=wrapper-bash)
    CX->>W: rg pattern path
    W->>EH: --internal-allowlist-direct rg:/usr/bin/rg pattern path
    EH->>EH: allowlist 검증 + 경로 검증
    EH->>RG: exec /usr/bin/rg pattern path
    RG-->>CX: 결과

Codex가 실행할 수 있는 PATH를 임시 래퍼 디렉토리로 교체하여, allowlist 외 명령어는 아예 찾을 수 없게 만든다.

2단계 모델 Fallback

// 1차: Spark 모델 (저비용, 빠름)
let result = run_codex_with_model(&args.spark_model);
if result.exit_code == 0 { return Ok(result); }
 
// 2차: Fallback 모델 (고성능)
let fallback_result = run_codex_with_model(&args.fallback_model);

Spark 모델이 실패하면 Fallback 모델로 재시도한다. 양쪽 모두 실패하면 상세 에러를 반환한다.

Codex 호출 설정

command
    .arg("exec")
    .arg("-s").arg("read-only")                    // 샌드박스: 읽기 전용
    .arg("-c").arg("model_reasoning_effort=\"low\"") // 비용 절감
    .arg("-o").arg(&output_path)                    // 마크다운 아티팩트
    .env("PATH", &allowlist.bin_dir)                // 격리된 PATH
    .env("SHELL", &allowlist.shell_path)            // 격리된 SHELL
    .env("OMX_EXPLORE_ROOT", &args.cwd)             // 경로 검증 기준

설정	값	목적
--sandbox	read-only	읽기 전용 강제
model_reasoning_effort	"low"	토큰 비용 절감
PATH	임시 래퍼 디렉토리	allowlist 외 명령어 접근 차단
출력	마크다운 아티팩트	마크다운만 반환

sparkshell — 적응적 출력 요약 사이드카 (소스: native/omx-sparkshell/src/main.rs)

두 가지 실행 모드

enum SparkShellInput {
    Command(Vec<String>),                              // 직접 명령 실행
    TmuxPane { pane_id: String, tail_lines: usize },   // tmux pane 캡처
}

모드	명령어	용도
직접 실행	omx sparkshell rg "auth" src/	명령어 실행 + 요약
tmux 캡처	omx sparkshell --tmux-pane %3	Team 모드 Worker pane 출력 캡처

tmux 캡처 시 tail lines 범위: 100~1,000줄 (기본 200줄).

요약 판단 — 12줄 임계값

const DEFAULT_MAX_VISIBLE_LINES: usize = 12;
 
let line_count = combined_visible_lines(&output.stdout, &output.stderr);
 
if line_count <= threshold {
    // 원시 출력 그대로 반환
    write_raw_output(&output.stdout, &output.stderr)?;
} else {
    // LLM 기반 요약
    match summarize_output(&execution_argv, &output) {
        Ok(summary) => write(summary),
        Err(_) => write_raw_output(/* fallback */),
    }
}

12줄 이하면 원시 출력 반환, 초과하면 LLM 요약. 요약 실패 시 원시 출력으로 fallback. 환경 변수 OMX_SPARKSHELL_LINES로 임계값 조정 가능.

명령 패밀리 감지 — 11개 패밀리

요약 프롬프트에 명령 패밀리 컨텍스트를 추가하여 요약 품질을 높인다:

패밀리	명령어	설명
git	git	Repository inspection
node-js	npm, npx, pnpm, yarn, bun, node	Package management, builds
python	python, python3, pip, uv, poetry, pytest	Python 실행, 패키징
rust	cargo, rustc	Build, test, lint
go	go	Build, test, modules
ruby	bundle, rake, ruby	Ruby tasks
java-kotlin	mvn, gradle, gradlew, java, kotlinc	JVM builds
c-cpp	make, cmake, gcc, g++, clang	Native builds
csharp	dotnet	.NET SDK
swift	swift, xcodebuild	Apple builds
generic-shell	ls, cat, find, grep, sed, awk 등	기본 셸

요약 프롬프트 구성

"You summarize shell command output.
Return markdown bullets only. Allowed top-level sections: summary:, failures:, warnings:.
Do not suggest fixes, next steps, commands, or recommendations."

Command: {command_line}
Command family: {family_key}
Exit code: {exit_code}

STDOUT: {truncated_stdout}
STDERR: {truncated_stderr}

허용되는 출력 섹션 3개만: summary:, failures:, warnings:. 나머지(next steps:, notes: 등)는 정규화 과정에서 버려진다. “수정 방법 제안”이나 “다음 단계 추천”을 차단하여 순수 요약만 반환한다.

출력 truncation — 2단계 절단

LLM에 보내기 전 출력을 절단하여 토큰 비용을 관리한다:

단계	기준	기본값	전략
1. 줄 수 절단	OMX_SPARKSHELL_SUMMARY_MAX_LINES	400줄	head 50% + [... omitted ...] + tail 50%
2. 바이트 절단	OMX_SPARKSHELL_SUMMARY_MAX_BYTES	24,000바이트	UTF-8 안전 prefix/suffix 분할

모델 해석 — Spark + Fallback 2단계

순위	환경 변수	기본값
Spark 1순위	OMX_SPARKSHELL_MODEL	—
Spark 2순위	OMX_DEFAULT_SPARK_MODEL	—
Spark 3순위	OMX_SPARK_MODEL (레거시)	—
Spark 기본값	—	gpt-5.3-codex-spark
Fallback 1순위	OMX_SPARKSHELL_FALLBACK_MODEL	—
Fallback 2순위	OMX_DEFAULT_FRONTIER_MODEL	—
Fallback 기본값	—	gpt-5.4

Fallback 재시도 조건: rate limit(429), quota, model not found, unavailable, capacity 등 일시적 오류에만 재시도한다.

에러 처리와 exit code 보존

enum SparkshellError {
    InvalidArgs(String),        // Exit 2
    Io(io::Error),             // Exit 127 (not found), 126 (permission), 1 (other)
    SummaryTimeout(u64),       // Exit 1
    SummaryBridge(String),     // Exit 1
}

핵심 규칙: exit code는 항상 원본 명령어의 exit code를 반환한다. 요약 성공/실패와 무관하게, sparkshell은 원본 명령어가 실패했으면 실패를 그대로 전파한다.

CLI 라우팅 — explore와 sparkshell의 분기 (소스: src/cli/explore.ts)

라우팅 의사 결정

omx explore 명령어가 실행되면, TypeScript 레이어가 먼저 sparkshell 라우팅을 시도한다:

graph TD
    REQ["omx explore --prompt '...'"]
    REQ --> CLASSIFY["프롬프트 분류"]
    CLASSIFY --> |"git log, find, rg 등<br/>read-only 셸 명령"| SS["sparkshell 라우팅"]
    CLASSIFY --> |"복잡한 탐색 요청"| EH["explore-harness 라우팅"]
    SS --> |성공| DONE["결과 반환"]
    SS --> |실패/불가| EH
    EH --> |Spark 성공| DONE
    EH --> |Spark 실패| FB["Fallback 모델 재시도"]
    FB --> DONE

    style SS fill:#d4edda
    style EH fill:#cce5ff

sparkshell 라우팅 조건

// sparkshell로 라우팅되는 경우
// 1. git read-only 명령: log, diff, status, show, branch, rev-parse
// 2. "run " 접두사 + find/ls/rg/grep (경로 이스케이프 없는 경우)
 
const READ_ONLY_GIT_SUBCOMMANDS = new Set([
  'log', 'diff', 'status', 'show', 'branch', 'rev-parse',
]);

셸 메타 문자(|, &, ;, >, < 등)가 포함되면 sparkshell 라우팅에서 제외된다.

AGENTS.md 라우팅 가이드 (소스: src/hooks/explore-routing.ts)

USE_OMX_EXPLORE_CMD=true 환경 변수가 설정되면, AGENTS.md에 탐색 라우팅 가이드가 주입된다:

// 탐색 적합 패턴 (omx explore 추천)
const SIMPLE_EXPLORATION_PATTERNS = [
  /\b(where|find|locate|search|grep)\b/i,
  /\b(file|symbol|usage|reference)\b/i,
  /\bhow does\b/i,
  /\b(read[- ]?only|explor(e|ation)|inspect)\b/i,
];
 
// 탐색 부적합 패턴 (일반 Codex 경로 유지)
const NON_EXPLORATION_PATTERNS = [
  /\b(implement|write|edit|modify|refactor|fix)\b/i,
  /\b(test|lint|typecheck|compile|deploy)\b/i,
  /\b(migrate|rewrite|overhaul|redesign)\b/i,
];

에이전트가 “파일 찾기”, “심볼 검색” 같은 작업은 omx explore로, “구현”, “수정”, “테스트” 같은 작업은 일반 Codex 경로로 보내는 advisory 라우팅이다.

Explore 프롬프트 계약서 (소스: prompts/explore-harness.md, 4편 참고)

<identity>
You are OMX Explore, a low-cost shell-only repository exploration harness.
</identity>
 
<constraints>
- Read-only only. Never create, modify, delete, rename, or move files.
- Stay inside the current repository scope.
- Use shell inspection commands only.
- Prefer narrow, concrete lookup goals.
</constraints>
 
<allowed_commands>
rg, grep, ls, find, wc, cat, head, tail, pwd, printf
No pipes, redirection, &&, ||, ;, subshells, command substitution
</allowed_commands>

출력 형식은 4개 섹션으로 고정: ## Files, ## Relationships, ## Answer, ## Next steps.

네이티브 빌드 & 배포

Cargo 워크스페이스

[workspace]
members = ["crates/omx-explore", "native/omx-sparkshell"]
resolver = "2"
 
[workspace.package]
version = "0.10.1"
edition = "2021"
 
[profile.dist]
inherits = "release"
lto = "thin"

두 크레이트가 워크스페이스를 공유하며, dist 프로필에서 LTO(Link Time Optimization)를 적용한다.

바이너리 해석 우선순위 (5단계)

explore-harness와 sparkshell 모두 동일한 해석 체인을 따른다:

순위	소스	경로 예시
1	환경 변수 오버라이드	OMX_EXPLORE_BIN, OMX_SPARKSHELL_BIN
2	캐시된 네이티브 바이너리	~/.cache/oh-my-codex/native/0.10.1/darwin-arm64/omx-sparkshell/omx-sparkshell
3	패키지 내장 바이너리	bin/native/darwin-arm64/omx-sparkshell
4	레포지토리 빌드 결과	target/release/omx-sparkshell
5	Cargo 빌드 (최후 수단)	cargo run --release -p omx-explore-harness --

Hydration — 자동 네이티브 바이너리 다운로드

캐시에도 패키지에도 바이너리가 없으면, GitHub Release에서 자동 다운로드한다:

graph TD
    CHECK["캐시 확인"]
    CHECK --> |없음| MANIFEST["native-release-manifest.json 다운로드"]
    MANIFEST --> FIND["플랫폼/아키텍처 매칭"]
    FIND --> DL["아카이브 다운로드 (.tar.gz)"]
    DL --> SHA["SHA-256 체크섬 검증"]
    SHA --> |일치| EXTRACT["압축 해제 + 캐시 저장"]
    SHA --> |불일치| FAIL["에러: SHA256 mismatch"]
    EXTRACT --> DONE["바이너리 사용 가능"]

    style SHA fill:#fff3cd
    style FAIL fill:#f8d7da
    style DONE fill:#d4edda

항목	상세
매니페스트 URL	https://github.com/.../releases/download/v{version}/native-release-manifest.json
지원 플랫폼	macOS (arm64, x86_64), Linux (x64, arm64), Windows
무결성 검증	SHA-256 체크섬
캐시 경로	~/.cache/oh-my-codex/native/{version}/{platform}-{arch}/{product}/
비활성화	OMX_NATIVE_AUTO_FETCH=0

GLIBC 호환성 Fallback

Linux에서 바이너리의 GLIBC 버전이 시스템보다 높으면 실행이 실패한다:

const SPARKSHELL_GLIBC_INCOMPATIBLE_PATTERN = /GLIBC(?:XX)?_[0-9.]+['` ]+not found/i;

이 패턴을 감지하면 sparkshell은 요약 없이 원시 명령 실행으로 graceful fallback한다.

sparkshell 환경 변수 전체 맵

변수	기본값	용도
OMX_SPARKSHELL_MODEL	gpt-5.3-codex-spark	요약 Spark 모델
OMX_SPARKSHELL_FALLBACK_MODEL	gpt-5.4	요약 Fallback 모델
OMX_SPARKSHELL_LINES	12	요약 판단 줄 수 임계값
OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS	60000	요약 타임아웃 (ms)
OMX_SPARKSHELL_SUMMARY_MAX_LINES	400	프롬프트 최대 줄 수
OMX_SPARKSHELL_SUMMARY_MAX_BYTES	24000	프롬프트 최대 바이트
OMX_SPARKSHELL_BIN	—	바이너리 경로 오버라이드
OMX_NATIVE_AUTO_FETCH	1	자동 hydration (0=비활성화)
OMX_NATIVE_CACHE_DIR	~/.cache/oh-my-codex/native	캐시 디렉토리
USE_OMX_EXPLORE_CMD	—	탐색 라우팅 활성화

OMC와의 비교

항목	OMC	OMX
네이티브 도구	없음	explore-harness + sparkshell (Rust)
읽기 전용 탐색	Claude Code 기본 셸	allowlist 10개 명령어 + 4단계 경로 검증
출력 요약	없음	12줄 임계값 + LLM 적응적 요약
명령 패밀리 인식	없음	11개 패밀리별 맞춤 프롬프트
빌드 시스템	TypeScript만	Cargo 워크스페이스 + TypeScript 하이브리드
바이너리 배포	N/A	멀티 플랫폼 + SHA-256 + hydration
tmux 캡처	tmux capture-pane 직접	sparkshell —tmux-pane (요약 포함)
라우팅	없음	AGENTS.md advisory 라우팅 + regex 패턴 분류

핵심 차이: OMC는 에이전트 탐색에 별도 안전장치가 없으며, 출력도 그대로 컨텍스트에 들어간다. OMX는 Rust 네이티브 바이너리로 **보안(allowlist + 경로 검증 + 샌드박스)**과 **효율(적응적 요약 + 컨텍스트 절약)**을 동시에 확보한다.

참고 문서

• OMX GitHub