cody-agent — 설계 (API 크레딧 우선 실행기)

[코디] 26.10.8(목) 1차 구축. 결정은 [페페], 검토 반영은 [코덱스]. 도구 = C:\dev\tools\cody-agent\ · 규칙 = rules.md · 상태 = handoff.md · devplan = C:\dev\devplan\cody-agent.html. 장부 = C:\dev\seedchain\rules\model-ledger.md §3 「tools · cody-agent」 L5(opus · max).

1. 목적 · 결정

• [페페] 26.10.8 「api로 에이전트 사용을 할 수 있는 시스템을 구축해서 api 남은 비용 10달러까지를 하한으로 사용하게 해. 그 뒤에는 요금제 사용으로 폴백」 + 「컨텍스트 훅과 함께 api 잔량 표시를 훅으로 걸어서 답변마다 표기」.
• 크레딧 = Max20x 월 $200(콘솔 구매 크레딧 $0 · 자동충전 OFF → 소진 시 400, 과금 0). 콘솔 만료 표기 「27년 10.17」 → [총괄] 매월 17일 KST 00:00 리셋 가정(config.json cycle 로 바꿀 수 있다 — 1회성이면 mode: fixed + expires_at).
• 하한 = 잔여 − 진행 중 예약 − 이번 런 상한 ≥ $10 이면 API, 아니면 구독(OAuth claude -p).
• 그릴링 답(26.10.8): Q1 B = 헤드리스 이관 + L1·L2 위임 동시 · Q2 B = 위임 상한 L3(opus·high) · Q3 A = 답변 꼬리 잔량 줄 즉시 강제(못 읽은 턴은 통과).
• 1차(이번) = 실행기·원장·폴백·잔량 훅·꼬리 강제·위임 기능. 호출부 이관은 2차(L4 회차).
• [코덱스] 반대 반영 = L3 편집 위임을 폴더·도구 제한만으로 맡기지 않는다 → 사본에서 실행, 패치만 반환, 세션이 검토 후 적용.
• [페페] 26.10.8 2차 그릴링 답: Q1 동적 소진 페이스 · Q2 질문 릴레이(사용자용 chat CLI 는 안 만든다 — resume 은 내부 기반) · Q3 상주 전부 이관(다른 워커 담당) · Q4 L4·L5 허용 단 패치형만 + 보완 전부 + «API 에이전트도 규칙파일을 읽도록 지시문에 포함» · Q5 PreToolUse 조건부 차단. → [코디] 2차 구축 = §2-1.

2. 실측 사실 (26.10.8 · CLI 2.1.288 npm · VS Code 확장 2.1.292)

2-1. 2차 (26.10.8 [코디] · L5 opus·max) — 구조 · 실측

구조(1차에 더한 것)

실측(CLI 2.1.288 · 원장 기록 · 권한 시험 = Haiku 5.5 · 통합 시험 = 장부 등급 모델)

2차 실측 API 비용 합 = 원장 $1.01(보수 max) · 단가표 $0.45(14런: Haiku 권한 시험 7 · L4 1 · 질문 릴레이 2 · ask 릴레이 2 · devplan 대기 표시 확인 ask 2).

남은 위험(2차)

• 허용목록의 Bash(python *)·node *·npm run * 은 임의 코드라 네트워크·파일쓰기를 못 막는다(실측: python -c "import urllib…" 통과) — 경계가 아니라 실수 방지. 진짜 경계 = 별도 계정·VM(§6).
• L1~L3(Bash 전체 허용)은 거부 규칙 밖 경로의 rm -rf 가 통과(F16) — 1차 호환으로 남김. 허용목록을 전 등급으로 넓히려면 config bash_allowlist_levels 한 줄.
• 부작용형 키워드 판정은 휴리스틱 — gate.log 로 오판을 보고 config gate.side_effect_keywords·negations 를 고친다.
• 질문 대기 중 세션 파일이 지워지면 answer = lost(4). run 은 이제 세션을 남긴다 → clean 이 사본과 함께 세션 폴더도 정리(목록 기본 · --yes = 승인 후).

3. 구조

C:\dev\tools\cody-agent\
  cody_agent.py      CLI 겸 import 모듈(표준 라이브러리만 · py3.9 호환)
  key_helper.py      apiKeyHelper — 원장에서 «진행 중 API 런»일 때만 키를 stdout 에
  config.json        grant·floor·cycle·예산·시간·단가 (등급→모델은 여기 없다 = 장부 파싱)
  livecheck_task.py  숨김 예약작업 \Cody\cody-agent-livecheck 등록·실행(V2c 재검증)
  livecheck.vbs      wscript → pythonw cody_agent.py livecheck
  agent_gate.py      (2차) PreToolUse Agent|Task 조건부 차단 훅 — config gate · state\gate.log
  tests\selftest.py · tests\fake_claude.py
  state\ledger.sqlite(runs·anchors·events·meta + 2차 waits) · state\balance.json(+pace·waiting) · state\livecheck.json · state\gate.log   (git 제외)
  runs\<run_id>\  result.json · patch.diff · stream.jsonl · debug.log (git 제외)
%TEMP%\cody-agent\ask\       ask 의 cwd(빈 폴더 + 시스템 프롬프트 sys-<해시>.txt)
%TEMP%\cody-agent\<run_id>\work   run 의 사본

3-1. 경로 판정 = 한 트랜잭션

decide() = BEGIN IMMEDIATE 안에서 잔액 계산 → 판정 → 예약 행 INSERT. 동시 5건이 같이 하한을 뚫지 못한다(V6 실측: 잔액 14·예산 1·하한 10 → 정확히 4건 API · 1건 구독). - ask = API 불가면 구독으로 실행(재실행). allow_sub=False 면 실행 안 하고 kind=floor 실패. - run = API 불가면 실행 안 함 → 종료코드 3 「세션의 Agent 도구(장부 worker)로」.

3-2. 원장(state\ledger.sqlite, WAL)

• runs = 런 1행(route api|sub|refused · status reserved→running→settled | orphan | released | sub→done | refused).
• 잔액 = (이번 주기 최신 앵커 또는 grant) − 앵커 이후 정산 합. 표시·판정 공용. 예약 = held(reserved·running·orphan) 합.
• 정산 1회: UPDATE … WHERE status IN (held) rowcount 로 두 번 빼지 않는다. 실비 = max(CLI total_cost_usd, 단가표×usage) — 메시지별 usage 로 캐시 쓰기 5m/1h·Haiku 100k 구간 구분, modelUsage 에만 있는 나머지는 보수 단가(쓰기 1h·긴 구간).
• 결과 없는 런 = orphan(예약 유지) — 만료로 환급하지 않는다. recover --scan(래퍼 죽은 런 표시) → recover <id> --actual X | --conservative(예약액 전액). 예외: init 도 못 받고 메시지 0 이면 API 요청 전 사망이 확실 → released.
• 앵커 = 콘솔 값으로 맞출 때 ledger anchor <금액> — 이전 계산값·차액을 같이 남긴다. 초기값 = 198.7(추정, config.json initial_anchor).
• 주기 = cycle_of()(월 리셋일·시각·시간대 설정). 앵커는 그 주기 안에서만 유효(새 주기 = grant).

3-3. 차단 오버레이(meta.block)

429 = retry-after(없으면 30초, 최대 120초) 대기 2회 → ask 는 구독. 5xx(overloaded·server_error) = 2회 재시도(5·10초) → ask 는 구독. max_budget(CLI error_max_budget_usd) = 실패 반환·재실행 없음.

3-4. 모드 · 알림

• 모드 = fallback if (차단 중 or 잔여 − ask 기본 예산($1) < 하한) else api. 예약은 모드에 안 넣는다(큰 런 하나로 모드가 깜빡이지 않게).
• 모드 전환·주기 리셋은 같은 트랜잭션 안에서 meta.mode·meta.cycle 과 비교 → 바꾼 프로세스 하나만 notify.py done 1회(V5 실측: 전환 1회·복귀 1회, 그 사이 ask 는 추가 알림 0).
• 매 상태 변경 뒤 state\balance.json 을 tmp→os.replace(재시도 20회)로 쓴다.

3-5. 실행(_run_claude)

claude.exe -p --output-format stream-json --verbose --no-session-persistence --disable-slash-commands
  --strict-mcp-config --restricted --setting-sources "" --permission-prompts none --model <전체 id> --effort <e>
  [API] --bare --max-budget-usd <상한> --settings {"apiKeyHelper": "pythonw key_helper.py --run <id>"}
  --tools "<프로필>" [--allowedTools …] [--permission-mode acceptEdits] [--system-prompt-file|--append-system-prompt-file]
프롬프트 = stdin(명령줄 32K 한도·프로세스 목록 노출 회피)

• env = 허용목록(PATH·SystemRoot·TEMP·USERPROFILE·APPDATA … ) + PYTHONUTF8=1 + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 + DISABLE_AUTOUPDATER=1. PATH 에서 %APPDATA%\npm(claude 실행 파일) 제거 → 위임 안에서 중첩 claude 불가(실측 CHILD_CLAUDE_FOUND=False).
• init 의 apiKeySource 가 기대(API=apiKeyHelper · 구독=none)와 다르면 즉시 kill.
• base_url_guard() = config api_base·우리 env·managed-settings 에 Anthropic 아닌 base URL 이 있으면 API 런 거부. 사용자·프로젝트 설정(세션 릴레이 폴백이 쓰는 ANTHROPIC_BASE_URL)은 --restricted+--setting-sources "" 로 무시된다.
• Windows Job Object(KILL_ON_JOB_CLOSE) — 시간 초과·래퍼 사망 시 claude.exe 와 손자(bash·git·python)까지 종료. 자식은 전부 CREATE_NO_WINDOW(V2c 실측: pythonw 부모 · Session 1 · 50ms 감시 13초 동안 새 창 0).
• cwd = %TEMP%\cody-agent\…(C:\dev 밖 — CLAUDE.md 꼬리표 누출 함정 [[headless-claude-cwd-leaks-claude-md]]). --bare 라 CLAUDE.md 도 안 실린다 → run 은 규칙 블록(말투·전체경로·금지사항)을 --append-system-prompt-file 로 주입.
• ask 의 시스템 프롬프트 = 기본은 짧은 문장으로 «교체»(Claude Code 기본 프롬프트 토큰을 안 낸다 — V2a 한 번 $0.0002).

3-6. 편집 위임(run)

1. git 리포면 git clone --shared --no-checkout + checkout --detach HEAD → 원본 작업트리의 수정·새 파일(무시 목록 제외)을 바이트 그대로 복사(삭제분은 사본에서도 삭제) → 사본에서 스냅샷 커밋 S. 원본 .git 에 흔적 0(worktree 목록 불변 실측). 비git 폴더 = 복사(500MB 한도) + 임시 git(core.autocrlf=false).
2. 도구 = Bash,Edit,Read · acceptEdits · --permission-prompts none · 규칙 블록 주입.
3. 끝나면 git add -A → git diff --cached --binary --full-index S = runs\<id>\patch.diff + --test 명령을 사본에서 실행한 결과 → result.json.
4. 적용은 세션이 검토 후 apply <run_id> [--check](git apply --check → git apply). 자동 적용 없음.

4. 검증 (26.10.8 · 총 API 비용 ≈ $0.037 = 원장 기록 $0.0252 + 원장 생성 전 키 주입 비교 시험 $0.0117)

5. 2차 이관 대상 (L4 회차 — 호출부마다 dry-run 후 재기동)

[코디] 26.10.8 23:40 KST 이관 완료 11곳(목록 밖 추가 3 = pfs kb-digest · devplan danggeun claude_json · devplan app.py 댓글) — 공용 어댑터 C:\dev\tools\cody_ask.py. 결과표 = handoff.md NOW · 보류 = fallback.py(대화형 세션엔 크레딧 불가) · 제외 = ainews judge(폐기) · 도구 필요 상주 4곳은 미결 4.

6. 남은 위험

• 보안 경계 아님: 같은 윈도우 계정이라 위임 작업의 Bash 가 C:\dev\.secrets 를 읽을 수는 있다(규칙 블록으로 금지만). 실제 경계 = 별도 계정·VM(코덱스 제안, 2차 검토). 키는 env·로그에 없다.
• --bare = 훅 없음 → ruleguard·텔레그램 승인 broker 가 위임 작업에선 안 돈다. 막는 장치 = 사본 + 패치 검토 + 도구 프로필 + 규칙 블록.
• 잔액은 추정 — 콘솔과 어긋나면 ledger anchor. 리셋 가정(매월 17일 KST 00:00)이 틀리면 첫 400 이 소진으로 잡고 1시간 재탐지가 복구한다.
• CLI 판이 바뀌면 init 형식·엔트리포인트 판정이 바뀔 수 있다 → livecheck_task.py run 1회로 재검증(rules.md).
• Haiku 는 CLI 가 단가를 몰라 --max-budget-usd 가 실제로 안 걸릴 수 있다(단가가 낮아 위험 작음).