iop/agent-spec/testing/agent-comparison-benchmark.md

spec_doc_type	spec_id	status	source_evidence
spec	testing/agent-comparison-benchmark	구현됨	type path notes code scripts/agent_comparison_benchmark.py validate, preflight, run, resume, status, score, report 공개 CLI type path notes code scripts/agent_benchmark/manifest.py manifest 정규화, 경로 격리, fixture와 입력 digest 검증 type path notes code scripts/agent_benchmark/attempts.py append-only run/attempt 저장과 preflight, 실행, 재개 lifecycle type path notes code scripts/agent_benchmark/connectivity.py caller capability, requested/effective binding과 blocker 분류 type path notes code scripts/agent_benchmark/measurement.py source-aware timing과 usage 정규화 type path notes code scripts/agent_benchmark/web_validation.py 정적 웹 산출물과 desktop/mobile 자동 gate 검증 type path notes code scripts/agent_benchmark/scoring.py 익명화 입력, fresh evaluator와 scoring attempt 처리 type path notes code scripts/agent_benchmark/reporting.py deterministic Markdown 보고서 생성 type path notes test scripts/agent_benchmark/connectivity_integration_test.py 세 caller의 IOP binding, lifecycle, 격리와 실패 경계 통합 검증 type path notes test scripts/agent_benchmark/scoring_test.py unscored, scoring_failed, 새 scoring attempt와 익명화 검증 type path notes test scripts/agent_benchmark/reporting_test.py all-status, 동점과 raw evidence 포인터 보고 검증 type path notes test scripts/agent_benchmark/skill_contract_test.py project-local skill과 공개 CLI 계약 검증 type path notes contract agent-contract/outer/openai-compatible-api.md agy와 Codex가 사용하는 IOP OpenAI-compatible ingress 계약 type path notes contract agent-contract/outer/anthropic-compatible-api.md Claude Code가 사용하는 IOP Anthropic-compatible ingress 계약 type path notes contract agent-contract/inner/edge-config-runtime-refresh.md model, route, execution preset과 protocol profile 설정 계약 type path notes roadmap agent-roadmap/archive/phase/knowledge-tool-optimization-extension/milestones/agent-comparison-benchmark-pipeline.md bench-01 완료 범위와 evidence 집계 type path notes sdd agent-roadmap/archive/sdd/knowledge-tool-optimization-extension/agent-comparison-benchmark-pipeline/SDD.md benchmark lifecycle, 실패 보존, 채점과 secret-safe evidence 결정

스펙: Agent 비교 벤치마크 파이프라인

목적

Claude Code, agy, Codex가 IOP를 경유해 수행하는 동일 과업을 설정만 바꿔 반복 실행하고, 연결 상태부터 실행·검증·채점·보고까지 재현 가능한 evidence로 남기는 현재 benchmark harness를 설명한다.

기능 목록

기능	설명
manifest 검증	caller, IOP direct/preset route, model, effort, fixture, 반복 횟수, timeout, evaluator와 agent-test/runs/<output-id> 경로를 검증하고 canonical digest를 만든다.
연결 preflight	Claude Code, agy, Codex의 binary/config와 IOP endpoint·auth·model·effort·stream binding을 확인하고 ready, registration_required, implementation_gap으로 분류한다.
격리 실행과 재개	각 cell/repetition을 동일 checksum의 clean workspace와 fresh caller session에서 실행하며, 제품 결과·harness 정합성·process 종료를 독립 결과로 보존한다. top-level state는 running, completed, timed_out, cancelled, interrupted의 controller 상태만 나타내며, 실패한 attempt는 덮어쓰지 않는다.
측정과 evidence	제출, 첫 출력, 첫 파일 쓰기, model/tool/queue, finish/idle 시간을 관측 source와 함께 정규화한다. token은 보고 주체와 미제공 상태를 보존하며 임의 추정값을 authoritative 값과 섞지 않는다.
웹 자동 검증	product/harness 성공 여부와 무관하게 모든 terminal workspace에서 필수 HTML/CSS/JS와 로컬 이미지, 외부 asset 금지, desktop/mobile render, console/asset 오류, 반응형·접근성 gate와 screenshot을 확인한다.
익명 품질 채점	필수 자동 gate를 통과한 결과만 identity를 가린 뒤 manifest에 고정된 fresh evaluator로 100점 rubric을 평가한다. 부적격 결과는 unscored, 평가 실패는 scoring_failed로 남기며 retry는 새 scoring attempt id를 사용한다.
상태와 보고	validate, preflight, run, resume, status, score, report CLI를 제공하고, controller/product/harness/process/artifact/scoring 축과 동점을 raw evidence 포인터와 함께 deterministic Markdown으로 만든다.

범위

• 포함: benchmark manifest, caller adapter binding, run/attempt 저장, 격리 workspace, source-aware timing/usage, 정적 웹 gate, 익명 채점, Markdown 보고.
• 제외: IOP runtime 자체 구현, provider credential 등록, 실제 9개 비교군 실행과 모델 우열 결론. 해당 실행과 결론은 [bench-02]가 소유한다.

주요 흐름

flowchart LR
  Operator[사용자 또는 project skill] --> CLI[benchmark CLI]
  CLI --> Manifest[manifest 검증]
  Manifest --> Preflight[caller와 IOP preflight]
  Preflight --> Store[append-only run store]
  Store --> Attempt[clean workspace와 fresh session attempt]
  Attempt --> Evidence[timing, usage와 web evidence]
  Evidence --> Score[익명 evaluator scoring]
  Score --> Report[deterministic Markdown report]

계약

• OpenAI-compatible caller ingress는 OpenAI-Compatible API를 따른다.
• Claude Code ingress는 Anthropic-Compatible Messages API를 따른다.
• model, direct/preset route와 protocol profile의 기준은 Edge Config And Runtime Refresh를 따른다.
• 사용자-facing orchestration과 안전한 실행 순서는 IOP Agent Comparison Benchmark skill이 소유하고, 제품 호출과 evidence 생성은 deterministic Python pipeline이 소유한다.

설정/데이터/이벤트

• manifest의 matrix cell은 stable id, caller, IOP route kind, requested/effective model과 effort를 가진다. unsupported alias나 effort는 다른 값으로 대체하지 않고 fail-closed한다.
• run state는 agent-test/runs/<output-id>/<run-id>/ 아래에 격리되며 manifest digest가 다른 상태를 재개하지 않는다.
• preflight는 scored attempt가 아니며, 실행 중 실패·timeout·cancel과 scoring 실패는 기존 attempt를 수정하지 않고 보존한다.
• caller parser는 raw terminal 문자열 대신 CallerEvent(finish|idle), CallerTerminal(succeeded|failed)와 typed metric만 반환한다. Claude result가 마지막 active assistant snapshot을 직접 완성하면 adapter가 typed finish와 idle을 함께 투영하고, assistant가 이미 finish를 냈으면 result는 idle만 투영한다. synthetic API error와 agy ERROR result는 product=failed, harness=passed가 될 수 있으며 parser malformed는 product=unknown, harness=failed로 구분한다.
• durable lifecycle/measurement/attempt evidence는 product, harness, process 객체를 그대로 저장한다. run exit 0과 scoring eligibility는 product succeeded, harness passed, process exited/exit 0/no signal, artifact passed를 모두 요구한다.
• 배포 qualification은 동일 clean source에서 5-cell direct manifest를 unscored canary로 한 번 실행해 네 gate 5/5를 확인한 뒤 fresh C01-C09 preflight ready=9까지만 수행한다. hybrid 또는 scored C01-C09 실행은 후속 승인 전에는 할당하지 않는다.
• lifecycle supervisor는 exit watcher와 출력 reader를 join한 뒤 하나의 child return code를 동결해 lifecycle result와 cleanup receipt가 동일한 exit/signal을 갖게 한다. 불일치 evidence는 resume에서 fail-closed한다.
• raw credential과 private endpoint는 tracked manifest, event, log, screenshot과 report에 기록하지 않는다.
• report는 run state의 canonical evidence에서 생성되며 성공하지 않은 결과를 0점으로 변환하거나 동점에 임의 순위를 부여하지 않는다.

검증

• python3 -m unittest discover -s scripts/agent_benchmark -p '*_test.py' - 전체 benchmark unit/integration 계약이 통과한다.
• python3 -m unittest scripts.agent_benchmark.reporting_test scripts.agent_benchmark.skill_contract_test - 공개 보고 CLI와 project-local skill 계약이 통과한다.
• python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-manifest.example.json - 표준 manifest가 유효하다.
• python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-supported-direct.example.json - 지원 direct route fixture가 유효하다.
• python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-direct-preflight.example.json - direct preflight fixture가 유효하다.

한계와 주의사항

• example manifest와 fake adapter 테스트 통과는 실제 provider credential, endpoint 또는 preset의 live readiness를 의미하지 않는다. 실제 실행 전 redacted preflight가 필요하다.
• 현재 living spec은 비교 파이프라인의 구현 상태만 다룬다. 9개 scored cell 실행, 비교 결과와 결론은 후속 [bench-02] evidence로 관리한다.
• caller나 IOP가 제공하지 않은 usage는 unavailable로 남으며, 서로 다른 clock/source의 중첩 구간을 임의로 합산하지 않는다.
• benchmark 결과는 허용된 agent-test/runs/ 경계 안에만 생성한다.

변경 기록

• 2026-08-12: caller terminal을 closed typed observation으로 바꾸고 product/harness/process 결과, failure-inclusive artifact gate, 독립 CLI/report/scoring gate와 direct-first qualification을 구현했다.
• 2026-08-12: official Claude result-direct/API-error 및 agy ERROR terminal을 lifecycle 계약에 맞게 분리하고, timeout cleanup result/receipt가 같은 child exit snapshot을 사용하도록 동기화했다.
• 2026-08-12: [bench-01] 종료 감사에서 확인한 421개 benchmark test, manifest/CLI 계약과 구현 evidence를 기준으로 생성했다.