toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-incomplete-tool-call-syntax-gate.md
toki 8a4f6c55a1 sync: roadmap, skills, test inventory, streamgate package, docs updates 
- Update roadmap milestones and phase docs across multiple phases
- Update plan, code-review, create-roadmap, update-roadmap, finalize-task-routing skills
- Update dev-corp-runtime-deploy, dev-runtime-deploy, orchestrate-agent-task-loop skills
- Refactor agent-task-loop dispatch script
- Add streamgate Go package (commit_boundary, evidence_tail, filter_registry, stream_release)
- Add test inventory files (dev, dev-corp, unified)
- Update test smoke tests and rules for dev/dev-corp
- Update docs/edge-local-dev-guide and e2e scripts
- Update inventory-query Go package
- Remove deprecated templates and inventory.yaml files
- Add orchestrate-agent-task-loop tests
2026-07-25 11:41:08 +09:00

7.8 KiB
Raw Blame History

Milestone: OpenAI-compatible Incomplete Tool Call Syntax Gate

위치

목표

OpenAI-compatible provider stream이 terminal 상태로 닫혔지만 완성된 tool call과 raw/reasoning/content tool-call marker scanner 결과가 맞지 않는 케이스를 runtime에서 deterministic하게 판정한다. 이 Milestone은 tools[]나 tool_choice 존재 여부를 필수 증거로 삼지 않고, provider가 tool-call 문법을 시작했거나 완성한 흔적과 Edge가 조립한 assembled_tool_call_count의 불일치만 좁게 다룬다. 예: assembled_tool_call_count=0인데 assembled_reasoning="<tool_call|>"처럼 marker attempt가 남은 terminal 응답은 incomplete tool-call syntax로 분류한다.

상태

[계획]

승격 조건

  • 없음

구현 잠금

  • 상태: 잠금
  • SDD: 불필요
  • SDD 문서: 없음
  • SDD 사유: 현재 범위는 provider 원문/조립 결과를 비교하는 runtime classification과 관측 필드이며, public API/proto/config schema를 확정 변경하지 않는다. 감지 후 retry/error stream 정책을 확장할 경우 별도 SDD 필요 여부를 재판정한다.
  • 잠금 해제 조건: 아래 체크리스트
    • matcher가 의존할 marker grammar와 provider별 적용 범위가 정리되어 있다.
    • gate에 걸린 terminal 응답을 내부 retry로 처리할지 invalid-provider-output으로 처리할지 결정되어 있다.
    • content marker가 이미 downstream으로 흘렀을 때의 처리와 first-byte 전 buffer 필요 여부가 정리되어 있다.
  • 결정 필요: 아래 체크리스트
    • 초기 marker set을 Gemma 계열 <tool_call|> 중심으로 시작할지, provider별 registry로 시작할지 결정한다.
    • incomplete_at_eof, marker_attempt_count > assembled_tool_call_count, complete_marker_count > assembled_tool_call_count 각각의 action을 결정한다.
    • matched response를 1회 internal retry로 돌릴지, tool-call syntax error로 즉시 닫을지 결정한다.
    • reasoning-only marker와 content marker를 같은 severity로 볼지 결정한다.
    • gate 결과를 Pi/agent client가 볼 수 있는 error/metadata로 노출할지, Edge 로그/observation에만 남길지 결정한다.

범위

  • OpenAI-compatible Chat Completions provider passthrough/guarded stream의 terminal 응답 검사
  • raw provider chunk, assembled content, assembled reasoning에서 tool-call marker attempt/complete/incomplete EOF를 세는 scanner
  • assembled_tool_call_count와 scanner 결과의 불일치 판정
  • tools[], tool_choice, "tool이 필요했는가" 의미 판단과 독립적인 malformed/incomplete syntax 분류
  • Edge 실행 로그와 smoke evidence에 남길 gate observation 필드

기능

Epic: [syntax-gate] Incomplete Tool Call Syntax Gate

tool call marker가 존재하지만 완성된 tool call로 조립되지 않은 terminal 응답을 runtime에서 deterministic하게 잡는 capability를 묶는다.

  • [marker-scanner] incomplete_tool_call_syntax가 Stream Evidence Gate Core의 Filter interface를 구현하고, endpoint codec이 전달한 content/reasoning event에서 marker_attempt_count, complete_marker_count, incomplete_at_eof를 산출한다. filter가 raw request mutation이나 retry submit을 소유하지 않는다.
  • [count-mismatch] terminal 응답에서 marker_attempt_count > assembled_tool_call_count, complete_marker_count > assembled_tool_call_count, 또는 incomplete_at_eof=true이면 incomplete tool-call syntax로 분류한다.
  • [no-tool-choice-dependency] tools[] 또는 tool_choice가 로그/요청에 없거나 tool_choice가 생략된 요청도 marker/count mismatch만으로 판정한다. 명시 tool_choice=none인데 marker가 나오면 missing tool-call이 아니라 malformed provider output으로 분류한다.

Epic: [syntax-gate-integration] Syntax Gate Integration

syntax 판정 결과를 stream recovery, 운영 관측, fixture 검증에 연결하는 산출물을 묶는다.

  • [stream-boundary] reasoning-only marker와 content marker를 구분하고, Stream Evidence Gate Core의 bounded fragment_gate, 동일 immutable batch와 parallel all-complete barrier에서 marker scanner decision을 적용한다. retryable syntax 문제는 typed RecoveryIntent, 복구 불가는 fatal을 반환하며 stream-open marker는 rollback/exact replay하지 않는다. recovery는 strategy limit과 최초 실행 제외 기본값/절대 상한 3회의 request 전체 hard cap을 모두 소비하고 cap 소진을 다른 filter로 우회하지 않는다. Core buffer/Arbiter/Coordinator를 재구현하지 않는다.
  • [ops-signal] incomplete_tool_call_syntax stable filter id와 marker scanner count, assembled_tool_call_count, gate result를 Stream Evidence Gate Core의 FilterObservation timeline에 sanitized evidence로 남기고, provider/model/run id correlation으로 Edge 로그/observation과 연결한다. marker/raw content나 tool args는 남기지 않는다.
  • [fixture-tests] <tool_call|> 단독 종료, 완성된 marker와 parser count 불일치, 정상 tool call, marker 없는 최종 답변 fixture가 gate 기대값을 검증한다.

완료 리뷰

  • 상태: 없음
  • 요청일: 없음
  • 완료 근거: 기능 Task가 아직 충족되지 않았고, gate match 후 action 정책 결정이 남아 있다.
  • 검토 항목:
    • fixture test가 marker/count mismatch와 정상 종료를 구분한다.
    • dev-corp Pi 실패 사례와 같은 assembled_reasoning="<tool_call|>", assembled_tool_call_count=0 케이스가 gate에 걸린다.
    • gate action 정책과 stream boundary가 잠금 해제 조건과 일치한다.
  • agent-ui 상태 반영: 해당 없음
  • 리뷰 코멘트: 없음

범위 제외

  • tool 필요 여부를 의미적으로 판정하는 LLM judge
  • I will edit, 도구를 호출하겠다 같은 자연어 의도만 보고 missing tool-call로 판정하는 방식
  • tools[] 또는 tool_choice 존재 여부를 필수 증거로 삼는 gate
  • tool schema validation 실패 재시도
  • 모델 교체, Pi prompt 변경, provider option 변경
  • 무제한 retry 또는 recursive repair loop

작업 컨텍스트

  • 관련 경로: apps/edge/internal/openai, apps/edge/internal/service, apps/node/internal/adapters/openai_compat, openai-compatible-api.md
  • 표준선(선택): 이 gate는 "tool을 써야 했는가"가 아니라 "tool-call 문법을 시작/완성한 흔적과 조립된 tool call 수가 맞는가"만 판단한다.
  • 표준선(선택): tool_choice가 없으면 unknown으로 두고 이 gate의 필수 조건으로 쓰지 않는다.
  • 표준선(선택): marker scanner는 regex만으로 시작할 수 있지만 provider별 marker가 늘어나면 작은 state scanner/registry로 승격한다. scanner는 bounded fragment_gate requirement, FilterDecision과 선택적 intent만 반환하며 hold/release, 병렬 barrier, strategy budget, 최초 실행 제외 기본값/절대 상한 3회의 request 전체 recovery hard cap, rebuild/dispatch는 Core가 소유한다.
  • 상위 통합 후보: OpenAI-compatible Runtime Output Integrity Filter
  • 선행 작업: OpenAI-compatible Tool Call Boundary Hardening, Stream Evidence Gate Core, OpenAI-compatible 출력 검증 필터
  • 후속 작업: LLM 판별 기반 Missing Tool Call 재시도 Gate
  • 확인 필요: 구현 잠금 > 결정 필요 항목