agenticreplay 0.1.0 → 0.1.2

package/docs/i18n/README.ko.md

@@ -1,598 +0,0 @@
-# AgenticReplay
-
-<sub>[English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · **한국어** · [Deutsch](README.de.md) · [Français](README.fr.md) · [Español](README.es.md) · [العربية](README.ar.md)</sub>
-
-### 새벽 2시에 에이전트가 뭔가를 망가뜨렸다. 아침 9시에 그대로 재생하라 — 정확하게, 오프라인으로, 몇 번이든.
-
-어떤 코딩 에이전트든 기록한다. 네트워크를 끈 채 바이트 단위로 재현한다. 임의의 단계에서 다른 모델로
-분기시켜 누가 맞히는지 본다.
-
-</a>
-
-Claude, GPT, Gemini, Grok, DeepSeek, Qwen 등에 닿는다. `agenticreplay setup`이 기본으로 가리키는 곳이고,
-`agenticreplay compare`가 공급자 계정 네 개가 아니라 명령 하나면 되는 이유다.
-
-
-<br clear="left">
-
-[![License](https://img.shields.io/badge/code-Apache--2.0-blue)](../../LICENSE)
-[![Spec](https://img.shields.io/badge/trace%20spec-CC%20BY%204.0-blue)](../../spec/agenticreplay-trace-v0.md)
-[![Node](https://img.shields.io/badge/node-20%2B-brightgreen)](#설치)
-[![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Agents%20SDK%20%C2%B7%20AI%20SDK%20%C2%B7%20any-black)](#설치)
-[![Good first issues](https://img.shields.io/badge/good%20first%20issues-12-orange)](../good-first-issues.md)
-
-![Claude Code 실행을 기록하고, 오프라인으로 재생하고, 두 모델로 분기시키는 장면](../demo-cli.gif)
-
-<sup>한 세션에서 나온 실제 출력 — Claude Code 실행을 기록하고, 네트워크를 끄고 재생한 뒤,
-체크포인트 4에서 두 모델로 분기시켜 `npx tsc --noEmit`로 채점했다. 연출은 하나도 없다.</sup>
-
-## 세 개의 명령으로 시작하기
-
-npm 패키지 `agenticreplay`가 PATH에 `agenticreplay` 명령을 설치합니다. 에이전트 안에는 아무것도 설치되지 않습니다.
-
-```console
-npm i -g agenticreplay             # 패키지는 agenticreplay, 설치되는 명령은 agenticreplay
-
-agenticreplay record claude              # 당신의 에이전트를, 손대지 않은 채, 하던 대로
-agenticreplay replay last                # 같은 실행을 한 번 더 — 통신 없음, 토큰 없음, 과금 없음
-agenticreplay replay last --from 4 --model claude-haiku-4-5 --ui
-```
-
-사람들이 머무는 이유는 세 번째 줄이다. 같은 파일, 같은 대화 앞부분, 4단계부터만 다른 모델.
-변수는 모델 하나뿐이고, 그래서 답에 의미가 생긴다.
-
-## 검증 범위
-
-지원되는 API 트래픽을 캡처합니다. 본문은 기본적으로 64 MiB까지 보관하며, 중단된 전송은 불완전한 상태로 남아 재생할 수 없습니다. 클라이언트 검증 현황과 제한은 [`docs/agenticreplay-acceptance.md`](../agenticreplay-acceptance.md)에 정리되어 있습니다.
-
-## 왜 만들었나
-
-오늘날 에이전트 디버깅은 고고학에 가깝다. 터미널을 거슬러 올라가고, 다시 돌리면 다른 실패가 나오고,
-남의 하네스에 print를 끼워 넣는다. 존재하는 도구들은 관측 도구다. 이번 실행이 4.12달러가 들었고
-61k 토큰을 썼다고 알려준다 — 그건 당신의 질문이 아니다. 당신의 질문은
-*왜 내 마이그레이션 파일을 지웠는가*이다.
-
-AgenticReplay의 답은 그 실행 자체를 돌려주는 것이다.
-
-|  | 관측 도구 | AgenticReplay |
-|---|---|---|
-| 실행 비용을 알려준다 | ✅ | ✅ |
-| 어느 도구 호출이 파일을 지웠는지 알려준다 | 가끔 | ✅ |
-| 에이전트를 다시 돌려 같은 답을 낸다 | ❌ | ✅ 오프라인, 바이트 단위 |
-| 모델을 바꿔 4단계부터 다시 돌린다 | ❌ | ✅ |
-| 에이전트 개조가 필요하다 | 보통 SDK 래퍼 | ❌ 환경 변수 두 개 |
-| 터미널을 닫은 뒤에도 쓸 수 있다 | ❌ | ✅ 파일이니까 |
-| 모델 API 바깥까지 본다 — 셸 종료 코드, 파일 쓰기 | ❌ | ✅ 매 턴 |
-| 돌려세울 API 엔드포인트가 없는 에이전트를 기록한다 | ❌ | ✅ 직접 켜는 `--tls-intercept` |
-
-마지막 두 줄은 SDK 래퍼로는 구조적으로 닿을 수 없는 것들이다. 포착은 에이전트 **아래** — 프로세스와
-소켓 경계 — 에서 일어나므로, 그 에이전트가 당신 것인지, 고칠 수 있는지, 애초에 API 키를 들고 있는지는
-상관이 없다. ChatGPT 구독으로 로그인한 Codex CLI는 자기 백엔드와 TLS로 말하고 어디로도 돌려세울 base
-URL이 없지만, agenticreplay는 그래도 기록한다.
-[하네스가 방향을 바꾸지 않을 때](#하네스가-방향을-바꾸지-않을-때)를 보라.
-
-## 어떻게 작동하나
-
-모델 API는 상태를 갖지 않으므로, 에이전트는 매 턴 대화 전체를 다시 보낸다 — 직전 턴의 도구 결과까지.
-**따라서 모델 앞에 놓인 프록시는 루프 전체를 본다**: 각 요청, 각 스트리밍 응답, 모델이 낸 모든 도구 호출,
-하네스가 만든 모든 도구 결과. 도구 전체가 이 성질 하나 위에 서 있고, 그래서
-**AgenticReplay는 당신의 에이전트에 손대지 않는다** — 로컬 프록시를 띄우고, 환경 변수 두 개를 설정하고,
-비켜선다.
-
-프로토콜이 볼 수 없는 것을 잡는 층이 셋 더 있다. 종료 코드, 실제 소요 시간, 어느 스트림에서 나온
-바이트인지, 그리고 아무에게도 알리지 않고 쓰인 파일. 다섯 번째는 base-URL 변수를 아예 읽지 않는 에이전트를 위한 것이다 —
-아래 「어떤 에이전트가 되나」를 보라.
-
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-flowchart LR
-    A["<b>당신의 에이전트</b><br/><i>수정 없음</i>"]
-
-    subgraph agenticreplay["agenticreplay · 다섯 개의 포착 층"]
-        direction TB
-        P["<b>프록시</b><br/>base-URL 환경 변수"]
-        SH["<b>PATH 심</b><br/>종료 코드 · 시간 · 스트림"]
-        MC["<b>JSON-RPC 분기</b><br/>MCP 설정 재작성"]
-        FS["<b>그림자 git 인덱스</b><br/>턴마다의 작업 공간"]
-        FH["<b>fetch 훅</b><br/>오리진이 코드에 박힌 경우"]
-    end
-
-    A --> P & SH & MC & FS & FH
-    agenticreplay ==> T[("<b>하나의 트레이스</b><br/>.agenticreplay/runs/run_a1b2c3")]
-```
-
-넷 모두 같은 타임라인에 놓이며, 순서는 agenticreplay가 읽은 시점이 아니라 실제로 일어난 시점을 따른다.
-
-### 정확 재생, 분기, 비교는 하나다
-
-세 개의 서브시스템이 아니다. **커서**를 가진 같은 프록시다. 커서란 기록된 스트림에서
-디스크로 답하기를 멈추고 네트워크로 답하기 시작하는 지점이다.
-
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-flowchart LR
-    subgraph disk["디스크에서 · 바이트 단위 · 통신 차단"]
-        direction LR
-        T1["턴 1"] --> T2["턴 2"] --> T3["턴 3"] --> T4["턴 4"]
-    end
-    T4 ==> CUR{{"<b>커서</b>"}}
-    CUR ==> T5
-    subgraph net["네트워크에서 · 지정한 어떤 모델이든"]
-        direction LR
-        T5["턴 5"] --> T6["턴 6"] --> T7["…"]
-    end
-```
-
-| 명령 | 커서 위치 | 얻는 것 |
-|---|---|---|
-| `agenticreplay replay last` | 끝 | 실행 전체를 한 번 더, **통신 차단** — 토큰도 과금도 변동도 없음 |
-| `agenticreplay replay last --from 4 --model X` | 체크포인트 4 | 4까지는 동일, 이후에는 다른 모델이 이어받음 |
-| `agenticreplay compare last --from 4 --models a,b` | 체크포인트 4에서 여러 번 | 표 하나, 변수 하나 — 모델 |
-
-**체크포인트**는 기록되는 것이 아니라 *도출*된다. 대화 앞부분이 온전하고 작업 공간 스냅숏이 있는
-모든 지점이 그것이다. 그래서 모든 분기는 실제로 존재했음이 증명된 상태에서 시작한다.
-
-## 실제 버그 추적은 이렇게 생겼다
-
-에이전트는 실패하는 인증 테스트를 고쳐야 했다. 종료 코드는 0인데 테스트는 여전히 빨갛다.
-먼저 실제로 무엇을 했는지 본다:
-
-```console
-$ agenticreplay show last
-run_6473f858b59e  generic-openai@0.1.0  14 events  exit 0
-
-SEQ  KIND   WHAT                                            DETAIL
-0    RUN    run started                                     generic-openai
-1    SNAP   tree 919d32ba037537b43814c83779963b2cc3023db7   0 changed
-2    MODEL  claude-opus-5                                   1 messages
-3    MODEL  claude-opus-5                                   stop: tool_use · 100 in · 20 out
-4    TOOL   edit_file                                       {"path":"auth.ts",…}
-5    SNAP   tree c6af62b75c0c8b8938bd6087328b5148f3dcd534   1 changed
-6    FILE   auth.ts                                         modified +1 −3
-7    TOOL   edit_file                                       ok
-8    MODEL  claude-opus-5                                   3 messages
-9    MODEL  claude-opus-5                                   stop: end_turn · 101 in · 5 out
-10   SNAP   tree c6af62b75c0c8b8938bd6087328b5148f3dcd534   0 changed
-11   SHELL  ["sh","-c","node --check nonexistent-file.ts"]  /tmp/hunt
-12   SHELL  shell result                                    exit 1 · 43ms
-13   RUN    run ended                                       exit 0
-
-info usage input=201 output=25 cost=$0.004890
-```
-
-모델 자신의 기록으로는 알 수 없고 실행의 종료 코드가 감춰버린 사실 셋: 파일은 실제로 바뀌었고
-(seq 6, `+1 −3`), 에이전트가 돌린 확인은 **실패했으며** (seq 12, `exit 1`), 그런데도 끝냈다.
-실행이 0으로 끝난 건 *에이전트*가 0으로 끝났기 때문일 뿐이다.
-
-이 마지막 사실은 자기 명령을 가질 만하다. `agenticreplay show`는 일이 일어난 순서를 주고,
-`agenticreplay graph`는 무엇이 무엇을 낳았는지를 준다.
-
-```console
-$ agenticreplay graph last
-FROM              TO               KIND      WHY
-3 model.response  4 tool.call      recorded  tool_use block in the response
-4 tool.call       6 fs.change      inferred  changed path appears in tool input, same or previous turn
-4 tool.call       7 tool.result    recorded  tool result answers its call
-7 tool.result     8 model.request  recorded  tool_result block in the request
-
-  1 inferred — derived from this trace, not recorded in it
-```
-
-간선에는 두 종류가 있고, 그 차이가 중요하다. **recorded** 간선은 실행 당시에 기록된 것이다.
-`tool_use` 블록은 그것을 내보낸 응답 안에 물리적으로 들어 있기 때문이다. **inferred** 간선은
-방금 이름 붙은 규칙으로 유도된 것이다 — 파일시스템 스냅샷은 도구 호출마다가 아니라 턴마다
-한 번 찍히므로, 파일 변경을 *특정* 호출에 귀속시키는 것은 좋은 추측이지 사실이 아니다. 유도된
-간선은 결코 트레이스에 다시 쓰이지 않는다. 체크포인트가 유도되고 기록되지 않는 것과 같다.
-
-`agenticreplay export last --card bug.svg`는 그 사슬을 이슈에 붙일 그림으로 그리고, `--graph-card`는
-실행 전체를 그 사슬을 밝혀 그린다.
-
-SVG는 GitHub 이슈에서는 보이지만 중요한 다른 곳에서는 거의 보이지 않는다 — X는 업로드로 받지
-않고, Slack과 Discord는 미리보기를 주지 않는다. 그러니 파일 이름을 `.png`로 하면 PNG를, `.gif`로
-하면 사슬이 한 홉씩 쌓이는 GIF를 얻는다. 이 경로에는 브라우저가 필요하지만 agenticreplay는 브라우저에
-의존하지 않는다. `docs/media/README.md`가 렌더 도구를 `package.json` 밖에 두어, `npm ci`를
-실행하는 사람이 Chromium 내려받기를 부담하지 않게 한다. 없으면 agenticreplay가 그것을 고치는 한 줄을
-알려준다. `agenticreplay doctor`는 어느 쪽이든 보고하고, `.svg`는 아무것도 필요로 하지 않는다.
-
-```console
-agenticreplay export last --card bug.png       # the chain, ready to post
-agenticreplay export last --card bug.gif       # the same chain, one hop per frame
-npm i --no-save playwright-core pngjs gifenc   # only needed for the two above
-```
-
-이제 원하는 만큼, 공짜로 재현한다:
-
-```console
-$ agenticreplay replay last
-info replay.done reused=2/2 canonical_exact=2 divergences=0 unmatched=0 exit=0
-```
-
-통신 없음, 토큰 없음, 변동 없음. 그다음 진짜 궁금한 것을 묻는다 — *다른 모델이었다면 맞혔을까?*
-
-```console
-$ agenticreplay compare last --from 5 --models claude-opus-5,claude-haiku-4-5 --verify "npm test"
-MODEL             VERDICT  TOKENS  COST       WALL  RUN
-claude-opus-5     pass     201/25  $0.004890  0.3s  run_1457b35062ba
-claude-haiku-4-5  pass     201/25  $0.000326  0.3s  run_b8ee08479fb6
-```
-
-둘 다 통과했다. 하나는 **15배** 싸다. 같은 파일, 같은 대화 앞부분, 같은 체크포인트 —
-바뀐 것은 모델뿐이고, 그것이 저 숫자에 의미를 주는 유일한 이유다.
-
-## 타임라인
-
-`agenticreplay replay last --ui`(또는 `agenticreplay ui`)는 실행을 자기 완결적인 HTML 파일 하나로 연다. 계속 띄워둘
-서버도, 네트워크도, 설치할 것도 없다. 걸러 보고, 한 단계씩 넘기고, 스페이스를 누르면 당시의 속도로
-재생된다.
-
-![AgenticReplay 타임라인: 42개 이벤트를 도구 루프만 남기고 걸러낸 화면](../demo-viewer.gif)
-
-모든 층이 같은 타임라인에 놓이므로 실행을 넷이 아니라 하나의 이야기로 읽을 수 있다. 모델의 각 턴과
-토큰 수, 각 도구 호출의 인자와 결과, 셸 명령의 종료 코드와 소요 시간, 그리고 파일시스템 변경과
-그것이 만들어낸 트리.
-
-`agenticreplay export last -o bug.html`은 그 페이지를 이슈에 첨부할 수 있는 파일 하나로 쓴다. 외부 참조가
-전혀 없고 — CI가 그것을 검증한다 — 그래서 다운로드 폴더에서도, 비행기 안에서도, 5년 뒤에도 열린다.
-
-## 같은 과제, 다른 모델
-
-`agenticreplay compare`는 기록된 실행 하나를 같은 체크포인트에서, 같은 파일과 같은 대화 앞부분으로 여러
-모델에 분기시키고, 당신이 고른 명령으로 각각을 채점한다. 변수는 모델뿐이고, 그래서 답에 의미가 생긴다.
-
-![비교표: 같은 체크포인트에서 분기한 두 모델, 둘 다 통과, 실제 토큰 수와 비용 포함](../compare-card.png)
-
-```console
-agenticreplay compare last --from 4 \
-  --models claude-sonnet-5,claude-haiku-4-5 \
-  --verify "npm test" \
-  --share verdict.svg          # 위의 카드, 이슈에 바로 붙일 수 있다
-```
-
-### 여러 모델로 향하게 하기
-
-모델을 비교한다는 건 여러 공급자에 닿는다는 뜻이고, 그걸 손으로 하려면 `--upstream-anthropic`과
-`--upstream-openai`가 있다는 것, 게이트웨이 하나가 두 형식을 다 다룰 수 있다는 것, 키를 어디에 두는지를
-알아야 한다. 모두 실재하지만 어느 것도 스스로 발견할 수 없다. 그래서 대신 물어보는 명령이 있다:
-
-```console
-$ agenticreplay setup
-API key (stored 0600; leave blank for none):
-
-  6 models available:
-    anthropic/claude-opus-5
-    anthropic/claude-haiku-4-5
-    openai/gpt-5.2
-    ...
-
-$ agenticreplay models
-MODEL                      $/MTOK IN  $/MTOK OUT
-anthropic/claude-opus-5    15         75
-anthropic/claude-haiku-4-5 1          5
-openai/gpt-5.2             1.25       10
-some-local-model           —          —
-```
-
-`agenticreplay setup`은 파일만 쓰는 게 아니라 그 게이트웨이가 실제로 무엇을 제공하는지 묻는다. 그래서 잘못된
-URL이나 죽은 키는 비교 도중의 401이 아니라 지금 여기서의 답이 된다. 고른 모델도 저장하므로 그 뒤로는
-`agenticreplay compare last --verify "npm test"`에 모델 목록도 업스트림 플래그도 필요 없다. `agenticreplay models`는
-알아본 모델에만 가격을 매기고 모르는 것에는 대시를 둔다. 모르는 모델에 숫자를 지어내는 것이야말로
-비교표가 존재한 적 없는 비용을 인용하게 되는 경로이기 때문이다.
-
-키 하나로 Claude, GPT, Gemini, Grok, DeepSeek, Qwen 등이 서빙된다. `agenticreplay compare`가 원하는 모양
-그대로다. 모델 id는 공급자로 네임스페이스가 붙지만(`anthropic/claude-sonnet-4.6`,
-`openai/gpt-4o-mini`) agenticreplay가 처리한다. 네임스페이스가 통신 형식을 고르고, 가격 계산 전에 떼어진다.
-
-이건 *기본값*이지 목적지가 아니다. 덮어 쓰거나 `--gateway <url>`을 넘기면 OpenAI 호환 `/v1/models`와
-채팅 엔드포인트를 말하는 것이라면 무엇이든 똑같이 동작한다 — 다른 호스팅 게이트웨이든,
-직접 돌리는 것이든.
-
-그리고 그것은 **당신이** 어딘가로 보내달라고 한 트래픽에 대해서만 기본값이다. 게이트웨이를 설정하지
-않으면 `agenticreplay record`는 에이전트 자신의 호출을 원래 말하던 그 공급자에게, 에이전트 자신의 키로 그대로
-중계한다. agenticreplay는 당신이 설정한 적 없는 기록의 경로를 바꾸지 않는다. 그건 녹화 버튼을 누른 부작용으로
-소스 코드를 제3자에게 보내는 일이 될 테니까.
-
-비대화식: `agenticreplay setup --key <k>`는 기본값을 쓰고, `agenticreplay setup --gateway <url> --key <k>`는 다른 것을
-지정하며, `--key-env <VAR>`는 자격 증명을 디스크에 두는 대신 환경 변수에서 읽는다.
-
-키는 결코 트레이스에 닿지 않는다. 키는 나가는 요청에만 붙고, 기록되는 것은 **들어온** 요청에서 인증을
-떼어내어 구성한다. 누가 규칙을 기억하기 때문이 아니라 구조상 기록에 보이지 않는다는 뜻이다.
-플래그가 그 트래픽을 발급한 게이트웨이가 아닌 곳으로 보내면 키는 통째로 보류된다.
-
-## 어떤 에이전트가 되나
-
-하네스를 기록할 수 있는지는 두 가지가 정한다. 프록시로 향하게 할 수 있는지, 그리고 도착한 트래픽의
-와이어 형식을 agenticreplay가 아는지.
-
-| 에이전트 | 포착 방법 | 상태 |
-|---|---|---|
-| **Claude Code** | `ANTHROPIC_BASE_URL` | 동작 — 실제 버그 수정으로 검증됨, [자세히](../validation.md) |
-| **Codex CLI**(API 키) | `OPENAI_BASE_URL` → Responses API | 동작 |
-| **Codex CLI**(ChatGPT 로그인) | `--tls-intercept` → Responses API | 동작. 다만 직접 내려야 할 결정이 하나 있다 |
-| **OpenAI Agents SDK** | `OPENAI_BASE_URL` → Responses API | 동작 |
-| **Vercel AI SDK** | fetch 훅 — `agenticreplay record node -- node app.mjs` | 동작 |
-| **LangGraph / LangChain** | `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL` | 될 것이다 — 공식 클라이언트를 거치지만 아직 테스트가 없다 |
-| **grok-cli**(텔레그램 봇 포함) | `agenticreplay record grok` — `GROK_BASE_URL`, 그리고 서브에이전트용 fetch 훅 | 동작 |
-| **OpenClaw** | `agenticreplay record openclaw` — 게이트웨이는 훅으로, 그것이 띄우는 에이전트는 상속된 변수로 | 동작 |
-| **opencode** | `agenticreplay record opencode` | 어댑터 있음. 두 오리진 모두 돌린다 |
-| **Hermes**(Nous Research) | `AGENTICREPLAY_BASE_URL_VARS=… agenticreplay record generic-openai -- hermes …` | 될 것이다 — 프로바이더마다 덮어쓴다. 아래 참고 |
-| **그 밖의 모든 것** | `agenticreplay record generic-openai -- <cmd>` | base-URL 변수를 읽으면 동작. 읽지 않으면 `agenticreplay record node -- <cmd>` |
-
-실제 하네스로 끝까지 돌려본 것은 Claude Code뿐이다. 나머지는 어댑터 계약과 픽스처가 지킨다. 픽스처는
-각 어댑터가 실제로 어떤 변수를 설정하는지 기록하므로, 하네스가 읽는 변수 이름을 바꾸면 빨개지는 것은
-검사이지 빈 트레이스가 아니다.
-
-이 중 둘은 환경 변수만으로는 부족하다. 명령을 고르기 전에 알아둘 값어치가 있다.
-
-**Responses API를 쓰는 하네스.** OpenAI Agents SDK와 Codex CLI는 둘 다 chat completions가 아니라
-`/v1/responses`를 기본으로 쓴다. agenticreplay가 이 형식을 알므로 특별히 할 일은 없다 — 다만 그전 빌드를
-쓰고 있다면 증상은 트레이스가 비는 것이 아니라 에이전트가 첫 턴에 `404`를 받는 것이었다.
-
-**base-URL 변수를 전혀 읽지 않는 하네스.** `@ai-sdk/openai`는 생성자 인자로만 오리진을 받는다. 그래서
-Vercel AI SDK로 만든 에이전트는 `agenticreplay record` 아래에서 멀쩡히 돌고, 0으로 끝나고, 트레이스는 빈다.
-`node` 어댑터가 정확히 그것을 위한 것이다. 실행 디렉터리에 작은 프리로드를 쓰고 `NODE_OPTIONS`를
-거기로 향하게 해, 허용 목록에 있는 프로바이더 호스트에 한해서만 `globalThis.fetch`를 돌린다.
-
-```console
-agenticreplay record node -- node agent.mjs
-agenticreplay record node -- npm run agent
-AGENTICREPLAY_INSTRUMENT_HOSTS='contoso.openai.azure.com' agenticreplay record node -- node agent.mjs
-```
-
-기본값이 아니라 별도 어댑터인 이유는 `NODE_OPTIONS`가 에이전트가 띄우는 모든 Node 프로세스에
-전해지기 때문이다. 필요한 줄 알 때는 치를 만한 값이지만, Python 하네스를 기록하는 사람에게 강요할
-것은 아니다.
-
-Bun은 `NODE_OPTIONS`를 받아들이지만 그 안의 `--require`는 무시한다. 그래서 `BUN_OPTIONS=--preload`도
-함께 설정해 Bun 기반 에이전트까지 포함한다. 이건 진짜 `bun`으로 확인했다. 막으려는 것이 소리 없는
-실패 — 훅이 돌지 않고, 트래픽이 그대로 프로바이더로 가고, 아무것도 기록되지 않는 — 이기 때문이다.
-
-**그래도 트레이스가 비면**, `agenticreplay record`는 조용히 끝나지 않고 그렇다고 말한다.
-
-```console
-warn capture.empty exchanges=0 cause="the agent never called the proxy — it may not read a base-URL variable" set=ANTHROPIC_BASE_URL,OPENAI_API_BASE,OPENAI_BASE_URL next="agenticreplay doctor"
-```
-
-**agenticreplay가 모르는 base-URL 변수.** 전부 나열하는 건 가망이 없다. Hermes 하나의 `.env.example`에만
-`NOVITA_BASE_URL`, `GLM_BASE_URL`, `KIMI_BASE_URL`, `MINIMAX_BASE_URL`, `HF_BASE_URL`,
-`NEBIUS_BASE_URL` 등 십수 개가 있다. agenticreplay에 박아 넣은 목록은 다음 주면 낡는다. 그러니 변수 이름을
-직접 알려주면 된다.
-
-```console
-AGENTICREPLAY_BASE_URL_VARS='OPENROUTER_BASE_URL' agenticreplay record generic-openai -- hermes
-AGENTICREPLAY_BASE_URL_VARS='GLM_BASE_URL,KIMI_BASE_URL' agenticreplay record generic-openai -- my-agent
-```
-
-각 이름은 `/v1`이 붙어 프록시를 가리킨다. OpenAI 호환 덮어쓰기가 원하는 형태다. `=<path>`로 바꿀 수
-있고 `=/`면 오리진만 남는다.
-
-**코딩 에이전트를 띄우는 게이트웨이.** OpenClaw는 직접 코딩하지 않는다. Claude Code, Codex,
-opencode를 자식 프로세스로 띄운다. 게이트웨이 자신의 호출은 fetch 훅이, 띄워진 에이전트의 호출은
-평범한 환경 변수가 잡는다 — OpenClaw가 그것을 읽어서가 아니라 **자식 프로세스가 부모의 환경을
-상속**하기 때문이다. 이건 agenticreplay가 아니라 운영체제의 성질이라, 테스트가 지키고 있다.
-
-## 하네스가 방향을 바꾸지 않을 때
-
-base-URL 주입은 base-URL 변수를 읽는 모든 하네스를 포착하고, fetch 훅은 읽지 않는 Node·Bun
-에이전트를 메운다. ChatGPT 구독으로 로그인한 Codex CLI는 둘 다 아니다. 자기 백엔드와 TLS로 말하므로
-바꿔 칠 오리진도, 우리가 닿을 `fetch`도 없다. `--tls-intercept`가 그 답이고, 인증 기관을 발급하는 일이므로 일부러 따로 내려야 하는 결정으로
-두었다.
-
-```console
-agenticreplay record codex --tls-intercept
-agenticreplay record codex --tls-intercept --tls-hosts 'api.openai.com,*.chatgpt.com'
-```
-
-CA는 그 실행에만 고유하며, agenticreplay가 띄운 에이전트만이 — 그 자식 프로세스 자신의 환경을 통해, 시스템이나
-브라우저 신뢰 저장소는 결코 건드리지 않고 — 신뢰하고, 실행이 끝나면 삭제된다. agenticreplay가 어딘가에 설치하자고
-제안하는 일은 없다. 허용 목록 밖의 호스트는 읽지 않고 터널링되어 주소와 바이트 수로만 기록된다.
-경로도 본문도 없다. agenticreplay가 평문을 가진 적이 없기 때문이다. 전부 가로채 달라는 요청은 들어주는 대신
-거절된다.
-
-거기서 돌아오는 것은 로그 한 줄이 아니다. 가로챈 요청은 다른 것과 똑같은 wire dialect로 파싱되어
-평범한 교환으로 트레이스에 들어간다 — 오프라인으로 재생할 수 있고, 다른 모델로 분기할 수 있으며,
-그 실행에는 당신의 API 키가 한 번도 들어간 적이 없다.
-
-`agenticreplay replay --model`, `agenticreplay fork`, `agenticreplay compare`에서도 동작한다. 같은 이유로 실제 에이전트를 띄우기
-때문이다.
-
-## 에이전트, 스크립트, CI를 위해
-
-트레이스는 파일이다 — 관측 대시보드가 될 수 없는 단 하나가 그것이다. 그래서 실패한 실행에 대해 가장
-쓸모 있는 질문은 **에이전트**가 던질 수 있는 질문이다. *내 지난 실행을 재생하고 무엇이 어긋났는지
-말해줘.* 모든 명령이 데이터로 답하고, agenticreplay는 자기 자신을 MCP로 내놓는다.
-
-```console
-$ agenticreplay replay last --json
-{"runId":"run_a278eea7b535","mode":"exact","traceRunId":"run_687e3f84b208","matchedExact":2,"divergences":0,"unmatched":0,"liveCalls":0,"exitCode":0}
-
-$ agenticreplay show last --json | jq '.events[] | select(.kind == "TOOL")'
-$ agenticreplay checkpoints last --json | jq '.[-1].seq'
-```
-
-stdout에는 JSON 문서 하나, 진단은 stderr — 기록 중인 에이전트 자신의 출력까지 stderr로 보내므로,
-실행이 떠드는 동안에도 그 문서는 계속 파싱된다. 실패도 JSON으로 답하고 종료 코드는 0이 아니다.
-`--json`은 `list`, `show`, `events`, `checkpoints`, `graph`, `record`, `replay`, `compare`, `doctor`를 덮는다.
-
-**도구로서.** `agenticreplay mcp`는 stdio로 트레이스 저장소를 에이전트에게 내준다.
-
-```json
-{ "mcpServers": { "agenticreplay": { "command": "agenticreplay", "args": ["mcp"] } } }
-```
-
-`agenticreplay_list_runs`, `agenticreplay_show_run`, `agenticreplay_checkpoints`, `agenticreplay_graph`, `agenticreplay_replay`, `agenticreplay_compare`. 재생은 공짜이고
-오프라인이다. `agenticreplay_compare`는 자기 설명 안에서 진짜 토큰을 쓴다고 말한다. 도구를 고르는 모델이 읽는
-것은 그 문자열뿐이기 때문이다.
-
-**코드에서**, 셸을 거치고 싶지 않다면:
-
-```ts
-import { AgenticReplay } from 'agenticreplay';
-
-const agenticreplay = new AgenticReplay({ cwd: process.cwd() });
-const { unmatched, divergences } = await agenticreplay.replay('last');
-const timeline = await agenticreplay.show('last');
-```
-
-당신의 stdout에 절대 쓰지 않고 `process.exit`도 부르지 않는다 — 둘 다 테스트가 지킨다. 그 둘 중
-하나라도 하는 라이브러리 위에는 아무것도 세울 수 없기 때문이다.
-
-## 현재 상태
-
-초기 단계다. `v0`는 위 세 명령의 걸어 다니는 골격이다.
-
-| 기능 | 상태 |
-|---|---|
-| 트레이스 형식 v0 + JSON Schema | 동작 |
-| Anthropic / OpenAI 호환 모델 포착 | 동작 |
-| OpenAI Responses API 포착 | 동작 — OpenAI Agents SDK와 Codex CLI가 기본으로 쓰는 형식. 기록·오프라인 재생·분기 모두 되고, 분기는 에이전트가 쓰는 와이어 형식에 그대로 남는다 |
-| base-URL 변수를 읽지 않는 에이전트 | 동작 — `agenticreplay record node -- <cmd>`가 실행 디렉터리에 프리로드를 쓰고, 허용 목록의 프로바이더 호스트에만 `globalThis.fetch`를 돌린다. Bun은 `NODE_OPTIONS` 안의 `--require`를 무시하므로 Node와 Bun 둘 다 지원. Vercel AI SDK 에이전트는 이렇게 포착한다 |
-| agenticreplay가 읽지 못하는 호출 | 동작 — 거부하지 않고 전달하며 `net.request` / `net.response`로 기록한다. 증거이지 재생 가능한 턴은 아니다. 아무것도 포착하지 못한 기록은 조용히 끝나지 않고 경고한다 |
-| 기계가 읽는 출력(`--json`) | 동작 — stdout에 JSON 문서 하나, 진단은 stderr, 실패도 JSON |
-| 인과 그래프(`agenticreplay graph`) | 동작 — 무엇이 무엇을 낳았는지를 표 또는 JSON으로. 각 간선은 트레이스가 기록한 것인지 agenticreplay가 방금 유도한 것인지를 말하고, 어느 쪽이든 규칙을 이름으로 밝힌다. `--to N`은 한 사건을 낳은 사슬로 좁힌다 |
-| 공유용 카드 | 동작 — `agenticreplay export --card`는 인과 사슬 하나를, `--graph-card`는 그 사슬을 밝힌 실행 전체를, `compare --share`는 판정 표를 그린다. `.svg`는 언제나, `.png`와 `.gif`는 선택적 렌더 도구가 있을 때. `agenticreplay doctor`가 보고하고 `npm ci`는 절대 끌어오지 않는다 |
-| MCP 서버(`agenticreplay mcp`) | 동작 — stdio로 여섯 개 도구. 에이전트가 자기 실행 기록을 읽고 재생할 수 있다 |
-| 프로그래밍 API(`AgenticReplay`) | 동작 — 명령은 이것이 돌려준 것을 그릴 뿐이라, 터미널은 하나의 사실에 대한 하나의 뷰다 |
-| 발산 보고가 붙은 정확 재생 | 동작 — 기록된 파일시스템을 작업 트리 위에 복원하고 끝나면 되돌린다. `--worktree`는 임시 사본, `--in-place`는 아무것도 복원하지 않음. 재생이 *발견한* 것(발산, 미일치 요청)을 담은 자기 자신의 run을 쓰고, 단지 되풀이한 부분은 부모를 가리킨다. `--no-trace`로 생략 |
-| 체크포인트에서의 분기 재생 | 동작 — 분기는 자신의 파일시스템 스냅숏을 기록하므로, 그것 자체를 다시 분기할 수 있다 |
-| 파일시스템 스냅숏과 diff | 동작 |
-| 단일 파일 HTML 내보내기 | 동작 |
-| MCP 호출 기록 | 동작 — `--mcp-config <path>`로 켠다. 재생과 분기는 기록이 쓴 설정에서 다시 계측하므로 이 층이 분기점에서 끊기지 않는다 |
-| 사후 제거(`agenticreplay scrub`) | 동작 |
-| 셸 포착(`PATH` 심) | 동작 — 종료 코드, 소요 시간, stdout/stderr 분리. `--no-shell`로 생략 |
-| 모델 외 네트워크 포착 | 동작 — `--tls-intercept`로 켠다. 띄운 에이전트만 신뢰하는 실행별 CA를 발급하고, 허용 목록 호스트를 복호화하고, 나머지는 읽지 않고 터널링하며, 끝나면 키를 지운다 |
-| 진짜 에이전트로 검증됨 | Claude Code가 진짜 버그를 진짜로 고친 실행 하나를 기록하고, 처음부터 끝까지 오프라인으로 재생하고, 체크포인트에서 분기하고, 내보냈다. 그 과정에서 픽스처로는 만들 수 없는 네 가지가 깨졌고, 모두 고쳤다 — [진짜 에이전트가 찾아낸 것](../validation.md) |
-| 구독 인증 하네스 | Claude Code는 동작. ChatGPT 구독의 Codex CLI는 자기 백엔드와 말하고 base-URL 변수를 읽지 않으므로 `--tls-intercept`가 필요하다 |
-
-## 설치
-
-```console
-npm i -g agenticreplay
-agenticreplay doctor
-```
-
-```console
-git clone https://github.com/askdkc/AgenticReplay && cd AgenticReplay
-npm ci && npm run build
-npm install -g ./packages/cli     # `agenticreplay`(그리고 `agenticreplay`)를 PATH에 올린다
-agenticreplay doctor                       # node, git, 그리고 찾을 수 있는 에이전트를 확인한다
-```
-
-저장소 루트에서 `npm install -g .`을 해도 아무것도 설치되지 않는다. 루트는 자기 바이너리가 없는
-workspace이고 `agenticreplay`는 `packages/cli`에 있다.
-
-`v0`가 게시되는 순간 설치는 `npx agenticreplay doctor` 하나가 되고 이 절도 그렇게 바뀐다. 릴리스는 태그로
-열리는 게이트 워크플로다 — [`RELEASING.md`](../../RELEASING.md) 참고.
-
-**실행에는 Node 24+**(CLI 자체의 `engines`는 `>=24.0.0`). 개발에도 `>=24.0.0`이 필요하다.
-테스트 툴체인이 그렇기 때문이고, 루트 `package.json`이 그것을 따로 선언해 두어 `npm ci`가 먼저
-알려준다. 계정도, 가입도, API 키 변경도 필요 없다.
-
-## 기록은 어디에 저장되나
-
-모든 것은 **기록한 프로젝트 안의 `.agenticreplay/runs/`**에 남는다. 프로젝트별이며 전역 저장소를 결코 쓰지 않으므로
-트레이스는 그것이 속한 체크아웃과 함께 다닌다. run 디렉터리 하나가 스스로를 설명하는 하나의 단위다:
-
-```
-.agenticreplay/
-  .gitignore          # 내용은 `*` 하나 — 저장소가 스스로를 제외하므로 트레이스를 실수로 커밋할 수 없다
-  runs/run_d0a2ee7ce615/
-    manifest.json     # 누가, 언제, 어떤 어댑터로, git 커밋, 각종 개수, 무결성 다이제스트
-    events.jsonl      # 타임라인, 한 줄에 JSON 객체 하나, 추가 전용
-    blobs/            # 4 KB를 넘는 페이로드를 내용 주소로 저장, 중복 제거
-    fs/               # 그림자 git 인덱스: 매 턴의 작업 공간
-    redactions.json   # 무엇이 제거되었는지 규칙과 개수로 — 값 자체는 결코 남기지 않음
-```
-
-예전 세션 찾기:
-
-```console
-agenticreplay list                       # 여기의 모든 run, 최신순, 무엇에서 분기했는지와 함께
-agenticreplay show run_d0a2ee7ce615      # 터미널에서 보는 타임라인
-agenticreplay replay last                # `last` = 가장 최근 기록(재생 트레이스는 건너뛴다)
-agenticreplay replay run_d0a2ee7ce615    # 또는 직접 지목
-agenticreplay gc --older-than 7d --dry-run   # 무엇이 회수될지, 실행하기 전에
-```
-
-`agenticreplay list`는 run 디렉터리를 직접 읽으므로 누군가 보내준 트레이스에서도 동작한다. `.agenticreplay/runs/`에
-넣으면 모든 명령이 본다. 색인도 없고, 망가질 데이터베이스도 없다.
-
-## 프라이버시
-
-트레이스는 로컬이고 모드 `0600`이며, 레코더는 자체 네트워크 연결을 하지 않는다. 비밀은 쓰기 경로에서
-제거된다. 환경 변수 포착은 기본 거부, 인증 헤더는 결코 쓰지 않으며, 알려진 키 모양과 고엔트로피
-문자열은 안정적인 자리표시자로 대체된다.
-
-제거는 최선의 완화이지 보장이 아니다. **트레이스는 민감한 것으로 다뤄라** — 대략 셸 히스토리에
-힙 덤프를 더한 정도다.
-
-```console
-agenticreplay export last -o bug.html          # 무엇을 쓰려는지 먼저 출력한다
-agenticreplay scrub last --match my-hostname   # 사후에 무언가를 제거한다
-```
-
-`agenticreplay scrub`은 `events.jsonl`, manifest, 모든 텍스트 blob을 다시 쓰고, 표준 탐지기를 다시 돌리고,
-무결성 다이제스트를 갱신하며, 바이너리 blob은 바이트 단위로 그대로 둔다.
-
-파일시스템 스냅숏은 다시 쓸 수 없다. git 객체는 자기 내용의 해시로 주소가 매겨지므로 하나를 고치면
-id가 바뀌고, 그것을 가리키는 모든 트리가 다시 쓰여야 하고, 그 트리를 가리키는 이후의 모든 이벤트도
-그래야 한다 — 실패하면 더 이상 복원되지 않는 run이 남는 역사 재작성이다. 그래서 scrub은 스냅숏
-저장소를 *검색*하고, 당신의 문자열이 아직 거기 있으면 그렇다고 말한다. 청소하지 못한 트레이스를
-깨끗하다고 보고하지 않는다. `--drop-fs`는 저장소를 통째로 지운다. 대가는 그 run을 더 이상 분기할 수
-없게 되는 것이다.
-
-## 무엇이 열려 있고 무엇이 아닌가
-
-언제나 열려 있고 Apache-2.0: 트레이스 형식, core, CLI, 뷰어, 어댑터, 그리고 provider 인터페이스.
-
-곳은 딱 하나다 — 게이트웨이를 지정하지 않으면 `agenticreplay setup`이 그것을 제안한다. 그것은 당신이 답하기로
-한 질문에 대해 눈에 보이고 덮어 쓸 수 있는 기본값이지, 무엇인가가 스스로 타는 경로가 아니다. 모든 모델
-경로는 어디로든 향하게 할 수 있는 평범한 URL 그대로이며, 그 origin을 다르게 다루는 코드 경로는 없다.
-
-`@agenticreplay/plugin-api`의 공개 `Provider` 인터페이스만 쓸 수 있고 그 뒤에 사적 API는 없다.
-아직 벤더 플러그인이 없으므로 이를 강제하는 CI 작업(`scripts/check-neutrality.mjs`)은 그렇다고 말하고
-no-op으로 통과한다. 하나가 등장하는 순간부터는 workspace 소스가 아니라 게시된 패키지를 상대로 빌드하기
-시작한다. 언젠가 플러그인이 어떤 능력을 필요로 한다면, 그 능력은 먼저 공개 인터페이스에 들어가고,
-한 벤더의 모양에 맞춰진 것이 아님을 보이는 두 번째 구현이 함께 온다.
-
-## 문서
-
-**지금 문제가 있다면 여기서 시작:**
-
-- [에이전트가 뭔가를 망가뜨렸다. 원인을 어떻게 찾나?](../how-to/debug-a-failing-agent-run.md)
-- [내 에이전트는 왜 그 파일을 지웠나?](../how-to/why-did-my-agent-delete-my-file.md)
-- [다른 모델이었다면 맞혔을까?](../how-to/compare-models-on-the-same-failure.md)
-
-**레퍼런스:**
-
-- [`spec/agenticreplay-trace-v0.md`](../../spec/agenticreplay-trace-v0.md) — 규범으로서의 트레이스 형식
-- [`docs/architecture.md`](../architecture.md) — 포착, 재생, 분기가 실제로 동작하는 방식
-- [`docs/validation.md`](../validation.md) — 진짜 에이전트를 처음 만났을 때 무엇이 깨졌나
-- [`docs/launch-path.md`](../launch-path.md) — 무엇이 되었고, 무엇이 안 되었고, 다음은 무엇인지
-- [`docs/plugins.md`](../plugins.md) — 어댑터나 provider 작성하기
-- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — 5분 개발 루프
-- [Good first issues](../good-first-issues.md) — 12개, 시작할 파일과 함께
-
-## 도움이 필요한 곳
-
-형식은 v0이고 걸어 다니는 골격은 동작한다. 프로젝트 생애에서 가장 흥미로운 지점이다. 결정을 바꾸는
-비용이 아직 싸고, 시작할 파일까지 적혀 있는 명백한 일이 많다.
-
-- **[good first issue 12개](../good-first-issues.md)**, 각각 파일과 테스트를 지목해 두었다.
-- **어댑터를 써라.** 파일 하나, 픽스처 하나. 하네스가 base-URL 변수를 읽는다면 스무 줄쯤이다 —
-  [docs/plugins.md](../plugins.md).
-- **리더를 다시 구현하라.** 명세가 CC BY 4.0인 것은 의도적이다. Python 리더는 이미 있다. Go와 Rust는
-  비어 있다.
-- **재생을 깨뜨려라.** 매칭 사다리가 이것의 심장이고, 그것을 개선하는 가장 빠른 길은 그것이 틀리는
-  실제 기록이다. `agenticreplay export last -o bug.html`을 붙여 이슈를 열어라 — 자기 완결적인 파일 하나이고,
-  먼저 빼내고 싶은 것이 있다면 `agenticreplay scrub`이 있다.
-
-오후 하나를 아꼈다면, ⭐ 하나가 다른 사람들이 찾는 데 도움이 된다.
-
-## 라이선스
-
-코드는 Apache-2.0. 트레이스 명세는 CC BY 4.0이므로 누구든 다시 구현해도 된다.
-
----
-
-<sub>
-</sub>