# OpenAI-Compatible API Contract

## 계약 메타

- id: `iop.openai-compatible-api`
- boundary: `outer`
- status: active
- 원본 경로:
  - `apps/edge/internal/openai/routes.go`
  - `apps/edge/internal/openai/principal.go`
  - `apps/edge/internal/authprojection/cache.go`
  - `apps/edge/internal/openai/chat_handler.go`
  - `apps/edge/internal/openai/responses_handler.go`
  - `apps/edge/internal/openai/usage_metrics.go`
  - `apps/edge/internal/openai/stream_gate_dispatcher.go`
  - `apps/edge/internal/openai/stream_gate_runtime.go`
  - `apps/edge/internal/openai/stream_gate_stall_recovery_test.go`
  - `apps/edge/internal/openai/common_types.go`
  - `apps/edge/internal/openai/sse_writer.go`
  - `apps/edge/internal/openai/chat_types.go`
  - `apps/edge/internal/openai/responses_types.go`
  - `apps/node/internal/adapters/openai_compat/openai_compat.go`
  - `packages/go/config/config.go`
  - `configs/edge.yaml`
- human docs: `docs/openai-compatible-api-contract.md`

## 범위

이 문서는 외부 프로젝트가 IOP Edge의 OpenAI-compatible HTTP 표면을 호출할 때 확인할 계약 원문이다.
IOP 내부 실행은 `adapter + target` 기준이며, OpenAI-compatible 경계에서는 호환성을 위해 `model`을 사용한다.
IOP 고유 실행 문맥은 별도 `iop` wrapper field를 만들지 않고 OpenAI request의 `metadata`에 둔다.
기본 설계 기준은 OpenAI-compatible request/response surface 보존이다. OpenAI-compatible provider로 raw passthrough 되는 경로는 선택된 provider가 지원하는 표준 field와 provider extension field를 IOP allowlist로 제한하지 않는다. 단, Chat 출력 상한의 호환 alias인 `max_tokens`와 `max_completion_tokens`는 selected protocol profile이 선언한 wire spelling으로 정규화하며, 둘 다 있으면 target-native field 값을 우선한다. IOP 고유 field나 추상화 field는 OpenAI-compatible 기본 surface 위에 더하는 확장으로만 사용하며, 그 밖의 provider-native OpenAI-compatible field를 대체하거나 금지하지 않는다.
라우팅의 1차 기준은 request `model`이 가리키는 route/provider capability다. 선택된 provider가 OpenAI-compatible provider이면 Edge는 provider tunnel passthrough를 사용하고, 그 외 Ollama/native 실행은 normalized path를 사용한다. 라우팅과 응답 형태를 caller metadata selector로 고르지 않는다. 2차 처리는 OpenAI `metadata` container에서 IOP가 아는 bounded key만 발췌해 principal, usage/observability 같은 내부 문맥으로 쓰는 방식이다.
서로 다른 외부 `model` key가 같은 `nodes[].providers[].id`를 참조하면 일반·long-context capacity는 model group별이 아니라 해당 provider resource 하나에서 공유된다. Edge provider-pool queue의 전체 pending 상한과 timeout도 model group 공통 root policy를 사용한다.

## Auth

Edge 설정의 `openai.bearer_token`이 비어 있지 않으면 OpenAI-compatible HTTP 표면은 다음 헤더를 요구한다.

```http
Authorization: Bearer <token>
```

토큰이 없거나 일치하지 않으면 `401 unauthorized` OpenAI-compatible error response를 반환한다. `openai.bearer_token`이 빈 값이면 auth를 적용하지 않는다.

### Principal token hash mapping auth

Edge 설정에 `openai.principal_tokens[]`가 설정된 경우, caller는 기존과 동일한 `Authorization: Bearer <token>` 헤더를 보낸다. Edge는 요청된 raw token의 SHA-256 hash를 계산하여 `token_hash_sha256`과 매칭한다. 매칭 성공 시 내부 dispatch metadata 후보로 `iop_principal_ref`, `iop_principal_alias`, `iop_token_ref`, `iop_principal_source`가 채워진다. 매칭할 entry가 없으면 `401 unauthorized`를 반환한다.

### Managed projection auth

`credential_plane.enabled=true` selects managed mode at startup. The Control Plane supplies the initial secret-free `PrincipalProjection` in the authenticated mTLS hello and pushes strictly newer generations after durable credential mutations. The Edge installs the same bounded immutable cache used by OpenAI and Anthropic ingress. Managed startup and reconnect fail closed if an accepted hello omits a valid projection.

In managed mode, OpenAI-compatible routes authenticate `Authorization: Bearer <IOP token>` by hashing the token and matching the projected digest. Static principal mappings and the legacy bearer are prohibited by configuration and never act as fallbacks. Unknown or removed digests, malformed headers, and expired snapshots return `401 unauthorized` before model lookup or dispatch. Expiry never returns the process to legacy behavior.

When managed mode is active, model discovery (`GET /v1/models`) lists only active
projected public route identities for the authenticated principal: `route_alias` when
it is non-empty, otherwise `route_id`. Request model resolution accepts that same
public identity and binds the request strictly to one projected route's `slot_id`,
`profile_id`, and `upstream_model`.
Unknown, inactive, or cross-principal routes never fall back to legacy `model_routes`,
global catalog, or single-target default.

The authenticated principal, its routes, and projection generation are captured from
one immutable snapshot for the entire request. A public `route_id` is not a provider
resource or a credential slot: inside this verified managed gate it resolves to exactly
one internal catalog model group and a selector-compatible provider resource set.
`credential_slot_ref` is trusted attribution/lease scope only. The Edge overwrites
caller metadata with the trusted route and credential revisions, preserves those values
and the internal model group across recovery admission, and fails closed on missing or
ambiguous catalog binding (`no fallback`). Public response model echoes remain the
caller-selected route.

After provider-pool admission, Edge validates the exact route/slot/profile/model/revision/generation binding, acquires a short-lived signed lease over the authenticated Control Plane connection, and revalidates the binding immediately before the Node send. The lease is sealed to the selected Node and is consumed only immediately before provider execution. Revocation, disable, rotation, projection expiry, or any stale binding fails closed without route, provider, or same-model slot fallback.

### Metadata 정책

- caller-provided `metadata.user`는 identity source가 아니며 사용되지 않는다.
- caller가 `metadata.iop_principal_*`를 보내도 authenticated context 값이 overwrite한다.
- `metadata`는 route/response mode selector가 아니다. Edge는 model 기반 route 선택 뒤 IOP가 아는 metadata key만 실행 문맥과 관측용으로 발췌한다.

### Legacy fallback

`openai.principal_tokens[]`가 설정되어 있더라도, raw token이 어떤 `principal_tokens` entry에도 매칭되지 않으면 `openai.bearer_token`이 설정된 경우 legacy 단일 bearer auth가 unmapped fallback으로 동작한다. `openai.bearer_token`과 `openai.principal_tokens[]`가 모두 설정된 경우, principal token 매칭이 실패하면 legacy fallback을 시도하고, 그래도 실패하면 `401 unauthorized`를 반환한다.

### Managed versus legacy provider credentials

- Managed mode obtains provider authentication only from the projected credential slot and sealed Node-targeted lease. `openai.provider_auth` and every static provider credential source are rejected at config load. A caller-supplied legacy provider credential header is rejected with `400 invalid_request_error` before a Node request.
- Legacy mode may use `openai.provider_auth.enabled=true`: the caller supplies a raw provider token in `openai.provider_auth.from_header` (default `X-IOP-Provider-Authorization`), and Edge forwards it to the configured target header/scheme. This raw token is distinct from inbound IOP authorization and is never inferred from `Authorization: Bearer <IOP token>`.
- Both modes preserve the public OpenAI-compatible request/response schema. Credential selection is an internal authenticated route operation, never a caller metadata or response-shape selector.

금지:

- raw provider token을 Edge config, tracked docs, roadmap, task artifact, metric label에 저장하지 않는다.
- host-local `~/.claude/anthropic_key.sh`, `~/.codex/config.toml`, env helper 파일을 OpenAI-compatible provider token source of truth로 읽지 않는다.
- missing required provider auth error body나 log에 raw header 값을 echo하지 않는다.
- managed mode에서 raw credential header, slot alias, lease id, key material, ciphertext, or target URL을 response, log, event, task evidence, or public metric label에 기록하지 않는다.

## 오류 응답

현재 IOP가 직접 만드는 OpenAI-compatible 오류 body는 `error.type`과 `error.message`만 가진다. 내부 `writeError` 호출의 `code` 인자는 별도 JSON `code`가 아니라 현재 `error.type` 값으로 직렬화된다.

```json
{
  "error": {
    "type": "node_dispatch_error",
    "message": "provider dispatch failed"
  }
}
```

- non-stream 오류는 해당 HTTP status와 JSON envelope 하나로 반환한다.
- normalized Chat Completions stream의 런타임 오류는 같은 `type/message` envelope를 SSE `data`로 한 번 쓰고 `[DONE]`으로 종료한다.
- normalized `/v1/responses`는 현재 streaming을 지원하지 않는다. provider-pool raw passthrough stream은 선택된 provider의 status/header/body를 그대로 relay하며 IOP envelope로 감싸지 않는다.
- unmarked caller-workspace selector의 upstream Chat 응답이 HTTP `400`이면 동일 요청 안에서 재시도하지 않고 caller에게 HTTP `400`, `error.type="invalid_request_error"`로 한 번 투영한다. Provider body와 endpoint는 private으로 유지한다. Upstream `5xx`와 transport failure는 기존 sanitized `502` 경계를 유지한다.

### Stream Evidence Gate ingress 및 terminal 오류

Chat Completions와 Responses ingress에는 configured request snapshot 상한이 body 첫 read 전에 적용된다. body 또는 typed semantic view가 상한을 넘거나 rebuild peak 회계가 실패하면 provider admission 없이 HTTP `413`, `error.type="invalid_request_error"` 한 번으로 종료한다. 이 오류의 `message`는 내부 byte 수, snapshot reference, Core 오류 이름을 노출하지 않는다. 기존 public error body는 계속 `error.type`과 `error.message`만 가지며 size/trace/causes 같은 필드를 추가하지 않는다.

The bounded ingress/size error behavior is an active contract. Every supported Chat Completions, normalized Responses, and provider-tunnel request uses one request-local StreamGate runtime as the sole response and liveness owner. The runtime stages response status/headers and opening events until the first safe release, gathers all applicable filter results, and executes exactly one release, terminal, or bounded recovery outcome. `openai.stream_evidence_gate.enabled=false` preserves the existing endpoint-native compatibility behavior inside the runtime; it does not route the request to a legacy owner.

복구 요청 조립 또는 dispatch가 실패하면 endpoint별 오류 하나만 보낸다. 내부 원인 사슬은 raw stack trace, provider endpoint/body, user prompt, output/reasoning 원문, tool args/result, 인증 정보를 포함하지 않으며 외부 JSON/SSE에 `causes`, `stack`, `trace` 같은 확장 필드로 노출하지 않는다.

The always-on runtime does not automatically enable a semantic detector. Only `repeat_guard`, `schema_gate`, and `provider_error` explicitly present in `openai.stream_evidence_gate.filters[]` enter the configured semantic portion of the request-start registry; `schema_gate` participates only when `metadata.scheme` is present. The private typed-stall registration remains present independently. Semantic filter selection depends on endpoint, environment, model group/model, actual provider, and execution path, never on a caller, SDK, or agent product name.

For every supported Chat or Responses normalized or tunnel attempt, an Edge-confirmed typed `response_stalled` terminal is safe to recover only before any caller-visible commit and only when the request has no cancellation or tool/side-effect boundary, retains its request snapshot and recovery owner, and has remaining shared recovery budget. The replacement has a new attempt identity and prefers another provider; an exact `available` probe may permit the avoided provider only when no alternate remains. Every other typed or generic provider failure remains one sanitized terminal response and exposes no provider failure body or metadata.

The private liveness cycle emits operational evidence only: one `iop_edge_liveness_recovery_eligibility_total{execution_path,provider_health,commit_state,eligibility}` decision and at most one `iop_edge_liveness_recovery_results_total{execution_path,provider_health,recovery_result}` outcome. Each label is closed; the projection never labels or logs correlation, attempt, run, session, model, provider, node, plan, credential, raw payload, or terminal text. When the constructor-owned generic observation sink is active, its private liveness and selected ExactReplay lifecycle rows are replaced by `edge_liveness_recovery_observation` safe logs; explicitly installed sinks retain their original immutable observations.

When a selected continuation plan addresses the request-local recovery source, the Rebuilder constructs a new request from retained assistant content/reasoning and the fixed English resume directive only. It never copies caller turns, Responses `input`, or caller `instructions`: Chat uses an assistant message followed by the fixed directive, while Responses uses assistant output/reasoning items plus that directive as `instructions`. The retained values are preserved byte-for-byte except for the selected content or reasoning byte cursor that excludes the repeated tail. If the caller omitted `temperature`, continuation attempts use `0.2`, `0.4`, and `0.6` in strategy-attempt order; an explicit caller temperature is preserved. A missing model context window, or a rebuilt prompt plus the fixed completion reserve above that window, fails closed before any replacement dispatch or recovery-budget consumption. This builder does not invoke a translator, local model, or `RecoveryPlanPreparer`.

`repeat_guard` inspects only the current request's endpoint-native history and current provider stream. Chat reads role-separated `content` and the plain `reasoning_content`, `reasoning`, and `reasoning_text` aliases; Responses reads its own message/reasoning/function-call item shapes. A user occurrence excludes the same assistant anchor. Missing reasoning history remains zero occurrences: Edge does not infer a session, TTL, or lineage. Signed, encrypted, unknown, final-content, tool-argument, and tool-result values are never sanitation targets or observation payloads. Completed identical action/result fingerprints establish no progress; a changed completed result is progress, while a different action alone is not. Tool release or a side-effect boundary disables automatic continuation.

차단(`blocking`) filter가 실제 target에 적용되면 해당 provider는 policy capability를 광고해야 한다. 후보 모두가 capability를 만족하지 않으면 Edge는 provider dispatch 전에 OpenAI-compatible HTTP `400`과 `error.type="invalid_request_error"`로 종료한다. `observe_only`와 disabled filter는 candidate admission을 막지 않는다. response start/opening event는 blocking filter의 all-complete 결과 전에는 commit하지 않는다. `repeat_guard` actively returns sanitized pass, safe-stop, or continuation decisions from the configured Unicode rolling window (500 runes by default) and committed look-behind. A continuation keeps the already released prefix, removes the repeated pending tail, suppresses one byte-identical replacement opening/prefix, and emits one final endpoint terminal marker. `schema_gate` and `provider_error` remain lifecycle foundations until their matcher Tasks are implemented; an unmatched provider error never creates exact replay.

## Usage attribution and request terminal metrics

- `iop_openai_requests_total` is emitted exactly once for each OpenAI-compatible request terminal. Its route dimension is `route_model`; `response_mode`, `status`, and `usage_source` describe the final committed HTTP result.
- Provider token and reasoning counters are emitted once for every actual provider attempt that reports usage, including an attempt that is later rejected, aborted, or replaced before the request terminal.
- Canonical provider-attempt dimensions are `usage_attribution`, strict actual `provider_id`, actual `served_model`, `route_model`, `endpoint`, and the attempt response mode. A missing strict provider/model binding does not fall back to adapter or node identity and does not create a provider usage series.
- Managed provider-attempt token/reasoning series also carry the stable `credential_slot_ref` and immutable `credential_revision` from the verified lease scope. These values are safe references, not a slot alias or credential. Request-terminal series remain exactly once per public request and omit slot/revision because recovery may contain multiple attempts.
- `usage_attribution="model_group"` is an explicit query-time rollup policy. It does not duplicate token counters or replace the canonical actual-provider series; operators roll up those series by `route_model` when the policy requests model-group attribution.
- `usage_source="provider_reported"` means at least one actual attempt supplied provider token fields. Reasoning text without provider token fields remains `usage_source="unavailable"`, while the separate reasoning-observation and estimate counters may still advance.
- `node_id` is retained only in the internal attempt binding. Node, attempt, run, request, session, and lease identifiers, slot aliases, raw credentials, private keys, target URLs, and raw request/response content are excluded from public metric labels.
- Prometheus schema and runtime emission are part of this contract. Grafana/query migration and completion evidence remain separate work and are not declared complete here.

## Responses API

Endpoint:

```http
POST /v1/responses
Content-Type: application/json
```

Normalized provider 실행으로 라우팅되는 요청의 최소 형태:

```json
{
  "model": "local-model",
  "input": "요청 내용을 요약해줘."
}
```

현재 `/v1/responses`에서 허용하는 표준형 요청 예시:

```json
{
  "model": "local-model",
  "instructions": "응답은 짧게 작성해.",
  "input": "요청 내용을 요약해줘.",
  "stream": false,
  "background": false,
  "max_output_tokens": 4096,
  "temperature": 0,
  "top_p": 1,
  "metadata": {
    "request_id": "req-001",
    "task_id": "task-123"
  }
}
```

필드 의미:

- `model`: Edge가 내부 `adapter + target`으로 해석할 외부 route 이름이다. IOP Edge에서는 라우팅을 위해 필수다.
- `instructions`: OpenAI Responses API의 top-level instruction field다. 있으면 `input` 앞에 배치해 normalized provider 입력을 만든다.
- `input`: provider에 전달할 사용자 요청이다. normalized(non-provider) route는 현재 string input만 지원한다.
- `stream`: normalized(non-provider) route는 현재 `false` 또는 생략만 지원한다. Provider-pool passthrough는 provider가 지원하는 stream 값을 보존한다.
- `background`: normalized(non-provider) route는 현재 `false` 또는 생략만 지원한다. Provider-pool passthrough는 provider가 지원하는 값을 보존한다.
- `metadata`: OpenAI 표준 metadata container다. bounded string key/value를 허용하며 caller-defined 관측 문맥으로 처리한다. 실행 디렉터리, runtime, session 소유권을 선택하는 제어 표면이 아니고 `source`는 지원하지 않는다.
- `metadata.request_id`, `metadata.task_id`: caller-defined metadata 예시다. 특별한 wrapper나 제품 전용 field가 아니다.
- `max_output_tokens`: 출력 길이 상한이다. 내부 provider option의 `max_tokens`로 전달된다.
- `temperature`: 생성 다양성 option이다. 대상 adapter가 지원하지 않으면 무시될 수 있다.
- `top_p`: nucleus sampling option이다. 대상 adapter가 지원하지 않으면 무시될 수 있다.
- `reasoning.effort`: provider tunnel route에서는 canonical IOP effort 등급을 operation별 protocol normalization으로 매핑한다. exact 등급이 없으면 선언된 가장 가까운 하위 등급만 사용하며 상향하지 않는다. 같은 `reasoning` object의 다른 field는 보존한다.

Normalized route 금지:

- `metadata.cli` 같은 runtime 전용 wrapper를 추가하지 않는다.
- `metadata.inference`처럼 `model` route와 겹치는 target wrapper를 추가하지 않는다.
- `metadata.nomadcode`처럼 특정 소비자 제품명에 묶인 wrapper를 추가하지 않는다.
- `metadata.source`처럼 의미가 불명확한 호출 출처 field를 추가하지 않는다.
- root-level `iop` 같은 별도 wrapper field를 추가하지 않는다.
- normalized(non-provider) `/v1/responses`에 `options` wrapper를 추가하지 않는다. Responses API option은 OpenAI 표준 top-level field를 따른다.
- `session_id`, `timeout_sec`, `workspace` 같은 IOP 실행 제어 field를 request body 계약에 추가하지 않는다.

현재 구현 메모:

- normalized(non-provider) `/v1/responses` route는 strict field validation을 유지하며 non-streaming string input만 지원한다.
- provider-pool model group route(`models[]`)의 `/v1/responses` 호출은 concrete protocol profile이 선택한 wire로 tunnel dispatch한다. Native Responses operation은 served target과 operation별 `reasoning.effort`만 rewrite하고 body/SSE를 raw passthrough한다. Anthropic Messages 또는 OpenAI Chat profile은 `instructions`, message/input, function call/result, tools, tool choice, parallel calls, output limit, stream, structured output 및 선언된 reasoning mapping을 모두 보존할 수 있을 때만 각각 `/v1/messages` 또는 `/v1/chat/completions`로 변환한다. Bridge 응답은 canonical Responses JSON/SSE로 다시 렌더하며 provider-native framing을 caller에게 노출하지 않는다. 표현 불가능한 control은 provider dispatch 전에 `400 invalid_request_error`로 거부한다. 이 선택은 caller/SDK identity가 아니라 request requirement와 profile에만 따른다.
- Gemini Chat bridge의 `extra_content.google.thought_signature`는 opaque Responses `call_id`에 캡슐화한다. caller가 후속 `function_call_output`에 그 값을 replay하면 Edge가 original tool id와 signature를 복원한다. Managed mode injects the selected slot lease at the Node; legacy mode may apply configured provider-auth forwarding. 이 경로도 normalized `SubmitRun`으로 fallback하지 않는다.
- provider-pool model group route는 provider candidate를 먼저 선택한다. 선택된 provider가 OpenAI-compatible 호출 방식을 지원하면 `ProviderTunnelRequest` passthrough를 사용하고, Ollama/native provider이면 normalized `RunRequest`를 사용한다. provider type만으로 Ollama를 candidate set에서 제거하지 않으며, OpenAI-compatible provider의 tunnel 구현이 없으면 normalized fallback이 아니라 unsupported/implementation error다.
- provider-pool pending request는 lease 반환, config refresh, provider disable, Node disconnect/reconnect 때 live config와 dispatch-ready registry에서 candidate를 다시 계산한다. 후보가 full인 상태는 queue policy에 따라 계속 대기하지만 live candidate가 모두 사라지면 원래 queue timeout까지 기다리지 않고 terminal unavailable로 끝난다.
- provider-pool admission/unavailable 실패는 현재 외부 error envelope를 유지해 HTTP `502`와 `type="node_dispatch_error"`로 반환한다. 별도 public status code나 response field를 추가하지 않으며 error message에는 raw token이나 private endpoint를 포함하지 않는다.
- direct legacy provider route(`openai.model_routes[]`의 `openai_compat`/`vllm` adapter)도 OpenAI-compatible provider이면 raw provider tunnel을 사용한다. Non-provider normalized route는 raw tunnel을 쓰지 않고 normalized IOP output path를 사용한다.
- Responses provider passthrough usage uses `endpoint="responses"`, the caller route alias in `route_model`, and the selected actual provider/served model on each attempt. Observation data is never inserted into the provider body.
- `metadata`는 최대 16개 string key/value를 허용한다. key는 64자 이하, value는 512자 이하를 기준으로 한다.
- 다른 Responses API 표준 field는 구현 필요가 생길 때 계약을 갱신한 뒤 추가한다.

## Chat Completions

`/v1/chat/completions`도 같은 metadata 원칙을 따른다. Normalized route에서 Chat Completions의 sampling option은 해당 endpoint의 OpenAI-compatible top-level request field를 따르며, `/v1/responses`와 마찬가지로 별도 `options` wrapper를 두지 않는다. Provider-pool passthrough route에서는 selected provider가 지원하는 OpenAI-compatible field와 provider extension field를 보존한다.

```json
{
  "model": "local-model",
  "messages": [
    {
      "role": "user",
      "content": "요청 내용을 요약해줘."
    }
  ]
}
```

Normalized(non-provider) Chat Completions route가 해석하는 request field:

- `model`
- `messages`
- `stream`
- `metadata`
- `max_tokens`
- `max_completion_tokens`
- `temperature`
- `top_p`
- `presence_penalty`
- `frequency_penalty`
- `seed`
- `stop`
- `response_format`
- `tools`
- `tool_choice`
- `parallel_tool_calls`
- `stream_options`
- `store`
- `think`
- `reasoning_effort`
- `thinking_token_budget`
- `include_reasoning`

Provider-pool raw passthrough route는 위 목록을 provider request allowlist로 사용하지 않는다. 이 경로의 기본은 selected OpenAI-compatible provider가 지원하는 요청 surface 보존이며, `chat_template_kwargs`, provider별 `extra_body`/template option, 새 OpenAI-compatible field처럼 IOP가 아직 해석하지 않는 top-level field도 model rewrite 후 provider로 전달되어야 한다. 단, Chat 출력 상한 alias는 selected profile에 맞춰 `max_tokens` 또는 `max_completion_tokens` 하나로 정규화하고 둘 다 있으면 target-native 값을 보존한다. 해당 field의 성공/실패 의미는 provider가 결정하고, IOP는 provider HTTP status/header/body를 relay한다.

### Chat Completions routing and response

Chat Completions의 실행 경로는 caller가 보낸 `model`의 route/provider capability로 결정한다.

- provider-pool model group route(`models[]`)는 candidate를 선택한 뒤 selected provider가 OpenAI-compatible 호출 방식을 지원하면 provider HTTP status/header/body를 Node가 열어 기존 Edge-Node tunnel로 relay하고, Edge가 caller에게 쓴다. 요청 body는 라우팅에 필요한 envelope만 읽고 `model` alias를 selected provider의 served target으로 rewrite하는 것을 기본으로 하며, provider가 지원하는 OpenAI-compatible field와 provider extension field를 보존한다.
- Provider-pool Chat과 unmarked caller-workspace의 selector/Work/Review 요청은 selected protocol profile이 선언한 출력 상한 wire spelling을 사용한다. OpenAI Chat wire는 `max_completion_tokens`, Gemini Chat wire는 `max_tokens`로 정규화한다. 형식이 bounded인 selector PLAN/REVIEW seed는 caller SDK의 큰 기본 completion limit과 분리해 최대 4096 output tokens만 허용한다. Selector provider에는 prepare 단계의 canonical `prepare(path)` 또는 pair-write 단계의 단일 `iop_write_artifact_pair(plan_content,review_content)` schema만 보여준다. Selector instruction은 모든 PLAN field를 English ASCII로 작성하도록 요구하고 Edge는 non-ASCII PLAN을 caller write 전에 거부한다. Edge는 검증된 atomic pair를 PLAN/REVIEW 두 write로 확장하고 admitted caller tool의 실제 schema(예: `bash(command)`)로 각각 encode해 caller에게 투영한다. 따라서 selector에게 두 parallel tool call 생성을 요구하지 않는다. Work provider의 전체 task prompt는 relative PLAN path와 고정 영문 `Read it and complete the task.`뿐이며 ordinary caller tools만 보인다. Work가 PLAN을 성공적으로 읽은 뒤 non-empty terminal report를 반환하면 Edge가 completed REVIEW template을 렌더·검증하고 단일 caller write로 투영한다. Work provider는 REVIEW handoff tool이나 protocol을 소유하지 않는다. Work/Review provider가 반환한 reserved-artifact operation은 실제 provider tool의 path alias(예: `filePath`)를 발행된 canonical path로 복원하고, 선택된 caller binding의 실제 tool 이름·argument mapping으로 정규화한 뒤 같은 codec으로 encode한다. 이 변환이 필요한 command-mode binding stage는 provider delta를 caller에게 선행 방출하지 않고 bounded stage를 수집·검증·매핑한 뒤 endpoint-native 응답으로 한 번 투영하며, 직접 투영 가능한 structured binding의 기존 progressive stream은 유지한다. Cleanup은 이미 caller-stage-only인 단일 call ID를 그대로 발행·해시하며 outer sequencer로 재투영하지 않는다. Caller continuation은 SDK가 assistant message에 추가·생략하는 content/reasoning/provider metadata가 아니라 발행된 tool-call ID·이름·arguments의 의미 해시로 issue를 결속한다. Unmarked 내부 stage가 function tools와 reasoning effort를 함께 요구하고 selected OpenAI profile의 Chat wire가 이를 지원하지 않으면, 같은 profile의 Responses operation이 두 요구를 보존할 때 내부 wire만 Responses로 전환한다. 이 내부 operation은 body와 tunnel metadata 모두 `stream=false`인 단일 buffered stage이며, provider가 거부하는 generic SDK sampling defaults인 `temperature`와 `top_p`를 전달하지 않고 mapped effort를 generation control로 사용한다. Result decoder는 caller protocol이 아니라 selected operation을 우선하여 Responses JSON을 기존 hot-path 공통 stage shape로 복원하며, caller-visible Chat surface와 caller/agent identity로 분기하지 않는다.
- selected provider가 Ollama/native provider처럼 normalized execution을 요구하면 Edge는 normalized `RunRequest` path를 사용한다. 이 경로는 OpenAI-compatible 표면을 입력/출력 compatibility layer로 제공하되, backend 호출은 normalized adapter 계약을 따른다.
- `metadata`는 경로 선택자가 아니다. Edge는 route 결정 뒤 인증 principal, usage/observability 등 IOP가 아는 bounded metadata key만 발췌한다. 이 발췌 정보는 provider body를 바꾸는 selector가 아니며, passthrough 응답 body에 IOP marker/event/envelope를 섞지 않는다.
- Chat Completions 성공 응답의 top-level `model` echo가 provider-served model이면 caller가 요청한 IOP model alias로 정규화할 수 있다. reasoning/content/tool_calls 같은 provider payload field는 보존한다.
- Selected protocol profile의 `normalization.tool_calls.chat_completions.wire`가 `gemini_openai_chat`일 때만 Edge는 Gemini의 opaque `extra_content.google.thought_signature`를 표준 `tool_calls[].id` 안에 캡슐화하고 provider extension field를 caller 응답에서 제거한다. Caller는 받은 tool-call id를 assistant history와 tool result의 `tool_call_id`에 변경 없이 replay해야 한다. 다음 요청에서 Edge는 원래 id와 signature를 복원해 Gemini provider에 전달한다. 다른 profile, signature 없는 Gemini 응답, tool call 없는 응답에는 적용하지 않으며 caller/SDK 이름으로 분기하지 않는다. IOP prefix를 가진 malformed id와 충돌하는 signature는 provider dispatch 전에 거부한다.

IOP 확장 think 제어 field:

- `think` (bool, optional): thinking/reasoning 생성 활성화 여부를 표현하는 IOP 확장 field다. 생략하면 provider 기본값을 유지한다. `false`는 thinking 생성을 끄도록 요청하고, `true`는 provider가 지원하면 thinking 생성을 명시 활성화한다.
- `reasoning_effort` (string, optional): `none`, `low`, `medium`, `high`, `xhigh`, `max` 중 하나인 IOP 확장 field다. `none`은 `think=false`와 같은 disable 의미로 처리한다. provider profile이 operation별 effort scale을 더 작게 선언하면 exact 또는 가장 가까운 하위 등급으로 매핑하고, 상향 매핑은 config load에서 거부한다.
- `thinking_token_budget` (int, optional): IOP 확장 thinking token budget. 0 이상이어야 한다.
- `include_reasoning` (bool, optional): OpenAI-compatible 응답에서 `reasoning_content` 노출 여부. non-provider normalized route에서는 생략하거나 `true`이면 provider reasoning delta/message를 노출할 수 있고, `false`이면 provider가 reasoning을 생성해도 response의 `reasoning_content`를 제거한다. provider-pool pure `passthrough`는 provider body 보존이 우선이며, 현재 IOP가 이 field만으로 reasoning field를 제거한다고 보장하지 않는다.

이 field들은 provider-native field의 대체물이 아니다. Provider-pool passthrough caller는 선택된 provider가 지원하는 native field(예: vLLM/Qwen 계열의 `chat_template_kwargs.enable_thinking=false`)를 그대로 보낼 수 있어야 하며, IOP 확장 field는 provider-native field가 없거나 normalized backend를 호출할 때의 추가 호환 표면이다.

### dev-corp `gemma4:26b` provider-pool passthrough 파라미터 범위

이 표는 dev-corp의 `gemma4:26b` provider-pool route에서, 현재 provider/vLLM 최적화 값을 변경하지 않고 standard OpenAI-compatible caller가 요청 파라미터만 바꿔 측정할 때의 계약상 기대 범위다. Provider-pool passthrough는 이 표에 없는 provider-native OpenAI-compatible field도 금지하지 않는다. Pi TUI의 고정 호출 방식이나 다른 model/provider route의 동작으로 일반화하지 않는다.

| 요청 파라미터 | 현재 기대 동작 | 권장 판정 |
| --- | --- | --- |
| `stream=false`, `think` 생략 | provider에 non-stream Chat Completions 요청으로 전달되고 Edge는 provider JSON body를 relay한다. reasoning field가 있으면 보존될 수 있다. | standard OpenAI-compatible caller에서 non-stream 동작 측정 가능. reasoning을 숨기려면 client에서 `choices[].message.reasoning_content`, `reasoning` 등 provider reasoning field를 제거한다. |
| `stream=true`, `think` 생략 | provider SSE body를 relay한다. reasoning delta가 있으면 보존될 수 있다. | streaming 동작 측정 가능. client는 `choices[].delta.reasoning_content`, `reasoning`, `reasoning_text` 같은 reasoning delta를 선택적으로 무시한다. |
| `include_reasoning=false` | field는 수신/전달될 수 있지만 pure `passthrough`에서 IOP-side filtering을 보장하지 않는다. provider가 무시하면 reasoning field가 그대로 올 수 있다. | 현재 IOP 설정을 바꾸지 않는 조건에서는 hide-only 스위치로 보지 않는다. client-side filtering을 기준으로 둔다. |
| `think=false` | Edge validation conflict가 없으면 요청은 통과하고 model catalog의 default thinking budget 주입은 억제된다. 이후 provider body에 `think:false`가 반영될 수 있으나, 현재 `gemma4:26b` provider 최적화 값과 충돌하거나 backend별로 무시/실패/품질 저하가 날 수 있다. | “숨기기만” 하는 옵션이 아니다. dev-corp `gemma4:26b` 기본 안정 호출에서는 생략한다. |
| `reasoning_effort="none"` | `think=false`와 같은 disable 의도로 해석되어 default thinking budget 주입을 억제한다. provider tunnel에서는 runtime/provider 지원 여부에 의존한다. | `think=false`와 같은 이유로 기본 안정 호출에서는 생략한다. |
| 명시적 `thinking_token_budget` | 0 이상이면 conflict validation 후 provider tunnel body에 반영될 수 있다. catalog 기본 budget 대신 caller 값으로 provider thinking budget을 바꾸는 요청이다. | 최적화된 `gemma4:26b` 기본값을 바꾸는 측정으로만 사용한다. 일반 표준 안정 호출에서는 생략한다. |
| provider-native field 예: `chat_template_kwargs` | selected provider가 해당 OpenAI-compatible extension을 지원하면 IOP provider-pool passthrough는 이를 보존하고 provider로 전달해야 한다. | 이 field를 IOP 추상 field로 치환하지 않는다. provider가 거부하면 provider error를 relay한다. |
| `/v1/responses` 호출 | provider-pool route에서 selected tunnel candidate가 Responses operation/capability를 선언하면 raw `passthrough`로 provider `POST /v1/responses`에 전달한다. This is not exclusive to the `openai_responses` driver. `model`만 rewrite하고 selected provider가 지원하는 field는 보존하며 `stream:true`는 raw SSE로 relay한다. usage metric은 endpoint=`responses`로 측정한다. | Provider가 `/v1/responses`를 지원하면 그대로 측정할 수 있다. Provider가 지원하지 않으면 provider error를 relay한다. Chat 기반 호출은 `/v1/chat/completions`를 쓴다. |

현재 구현에서 `think=false`를 “provider에는 기본 think를 유지하되 IOP가 응답에서 reasoning만 감추는 hide-only 모드”로 해석하지 않는다. 그런 동작이 필요하면 provider/vLLM 설정 변경이 아니라 Edge provider-pool passthrough 응답 filtering 정책을 별도 구현/계약 갱신해야 한다.

Reasoning-only 완료 처리 (non-provider normalized route):

- provider가 reasoning은 생성했지만 최종 assistant `content`와 `tool_calls` 없이 완료하면 Edge는 성공 응답을 빈 content로 끝내지 않는다.
- `include_reasoning` 생략 또는 `true`인 요청은 기존 reasoning 본문을 `reasoning_content`에 유지하고, `content`가 비어 있으면 reasoning 본문을 fallback content로도 반환한다. `finish_reason`이 `stop`이 아니면 fallback content 뒤에 IOP notice를 붙인다.
- `include_reasoning=false`인 요청은 reasoning 본문을 노출하지 않는다. 대신 `content`에 IOP notice를 넣어 "reasoning was hidden" 상태와 `finish_reason`을 알린다.
- streaming 응답도 같은 정책을 따른다. reasoning-only 완료 시 최종 finish chunk와 `[DONE]` 전에 fallback 또는 hidden-reasoning notice를 `content` delta로 한 번 전송한다.
- Chat Completions provider-pool pure `passthrough` 응답 body에는 이 normalized fallback/filtering 정책을 적용하지 않는다.

Provider별 think-control 정책:

아래 정책은 normalized adapter execution path 또는 IOP 확장 field를 provider-specific request로 변환해야 하는 경로의 기준이다. Chat Completions provider-pool pure `passthrough`는 provider-native OpenAI-compatible field를 우선 보존한다. 따라서 caller가 이미 `chat_template_kwargs` 같은 provider-native field를 보냈다면 IOP 확장 field 변환은 이를 대체하거나 삭제하지 않는다.

- `vLLM`:
  - `think=false` 또는 `reasoning_effort=none` -> 내부 `chat_template_kwargs.enable_thinking=false`
  - `think=true` 또는 budget-only -> 내부 `chat_template_kwargs.enable_thinking=true`
  - `thinking_token_budget` -> 내부 `chat_template_kwargs.thinking_token_budget`
  - `reasoning_effort=low|medium|high` -> `unsupported think control` 오류 반환
- `vLLM-MLX`:
  - `think=true` 또는 budget-only -> 내부 `chat_template_kwargs.enable_thinking=true`
  - `thinking_token_budget` -> 내부 `chat_template_kwargs.thinking_token_budget`
  - `think=false` 또는 `reasoning_effort=none` -> `unsupported think control` 오류 반환. vLLM-MLX 런타임은 스트리밍 응답 전체를 `reasoning_content`로 표기하고 `enable_thinking=false`로도 reasoning 생성을 멈추지 않으므로, think disable을 조용한 성공(200 reasoning stream)으로 처리하지 않고 명시 오류를 반환한다.
  - `reasoning_effort=low|medium|high` -> `unsupported think control` 오류 반환
- `Lemonade`:
  - `think=false` 또는 `reasoning_effort=none` -> 내부 `chat_template_kwargs.enable_thinking=false`. 이 런타임은 top-level `think` field를 무시하므로 top-level `think`를 사용하지 않는다.
  - `think=true` 또는 budget-only -> 내부 `chat_template_kwargs.enable_thinking=true`
  - `thinking_token_budget` -> 내부 `chat_template_kwargs.thinking_token_budget`
  - `reasoning_effort=low|medium|high` -> `unsupported think control` 오류 반환
- Unknown / 기타 provider: 요청 field를 그대로 전달하되, provider가 지원하지 않는 값은 backend 또는 adapter error가 될 수 있다.

Provider pool model catalog의 `models[]` entry가 generation policy를 제공하면 Edge는 요청을 내부 실행 또는 Chat Completions provider tunnel로 넘기기 전에 다음 값을 보정할 수 있다. 단, provider-pool raw passthrough에서는 caller가 명시한 provider-native OpenAI-compatible field를 삭제하거나 IOP 추상 field로 대체하지 않는다.

- `default_max_tokens`: caller가 출력 token limit을 생략했을 때 `max_tokens` 또는 `max_output_tokens`로 주입한다.
- `min_max_tokens`: caller가 너무 작은 출력 token limit을 보냈을 때 해당 값까지 올린다. caller 값이 더 크면 보존한다.
- `default_thinking_token_budget`: caller가 `thinking_token_budget`과 provider-native thinking budget field를 모두 생략했을 때 내부 실행 입력 또는 Chat Completions provider tunnel body에 주입할 수 있다. strict output가 함께 활성화된 normalized 경로에서는 Edge가 `think=true`도 함께 주입해 provider adapter가 지원하는 request shape로 전달할 수 있다. Provider-pool passthrough에서는 provider-native field 보존이 우선이다.

Conflict 정책:

- `reasoning_effort`가 비어 있거나 `none|low|medium|high|xhigh|max` 외 값이면 400 에러.
- `thinking_token_budget`가 음수이면 400 에러.
- `think=false`와 `reasoning_effort=low|medium|high`가 함께 있으면 400 에러.
- `think=false`일 때 `thinking_token_budget`를 설정하면 400 에러.
- `reasoning_effort=none`일 때 `thinking_token_budget`를 설정하면 400 에러.

Strict output 모드:

- strict output가 활성화되면 non-provider normalized route에서 `think=true`가 명시되지 않은 요청은 내부 실행 입력에서 `think=false`로 낮춘다.
- strict output만으로 OpenAI-compatible provider model group route를 normalized path로 전환하지 않는다. provider model group에서 selected provider가 OpenAI-compatible provider이면 계속 raw `passthrough`다.
- provider-pool `models[]` entry의 `default_thinking_token_budget`가 적용되는 모델은 catalog의 thinking policy를 기본값으로 사용할 수 있다. 이 경우에도 caller가 provider-native thinking field를 명시했다면 해당 field가 우선하며, IOP가 `think=true`나 `thinking_token_budget`으로 대체하지 않는다.

`tools`가 있는 Chat Completions 요청에서 provider route(`openai_compat`, `vllm`, `ollama`, provider pool)는 forced tool 선택 객체와 `"none"` 같은 명시적 `tool_choice`를 backend에 전달한다. 단, `"auto"`는 OpenAI-compatible 기본값과 같으므로 provider request에서는 생략한다. 일부 vLLM 계열 backend는 explicit/default `"auto"`를 `--enable-auto-tool-choice`/`--tool-call-parser` 없이 400으로 거부한다. 이 400이 발생하고 요청 tool이 정확히 1개이면 Node adapter는 해당 tool에 대한 forced `tool_choice`로 1회 재시도한다. forced tool도 `--tool-call-parser` 요구로 거부되거나 여러 tool이라 forced를 고를 수 없으면, Node adapter는 `tools`/`tool_choice`를 제거하고 text tool-call system instruction을 leading system message에 병합해 1회 재시도하며 완료 metadata에 `openai_text_tool_fallback: "true"`를 싣는다.
provider가 native OpenAI-compatible `tool_calls`를 반환하면 Node는 내부 `RunEvent.metadata["openai_tool_calls"]` JSON으로 보존하고, Edge는 이를 OpenAI-compatible `message.tool_calls` 또는 stream `delta.tool_calls`로 반환하며 `finish_reason: "tool_calls"`를 사용한다.
provider native `tool_calls[].function.arguments`는 OpenAI 계약에 맞는 JSON string으로 반환한다. 단, provider가 요청 `tools[].function.parameters` schema상 배열/객체여야 하는 값을 JSON 문자열로 이중 인코딩한 경우 Edge는 해당 `arguments` JSON만 schema 기준으로 복원해 다시 JSON string으로 직렬화한다.
요청에 `tools[]`가 있고 provider가 native `tool_calls` 없이 assistant content에 raw text tool-call 블록을 담아 응답하면, provider route(`openai_compat`, `vllm`, `ollama`, provider pool)에서 Edge는 그 블록을 요청 tool schema 기준으로 구조화하거나 차단한다. 이 정규화가 인식하는 텍스트 블록의 최소 형태는 `<tool_call><function=<name>><parameter=<key>>JSON-or-text</parameter></function></tool_call>` XML 형식과 `{{function_name(key=Python/JSON-like-literal)}}` mustache 형식이다.
후보 tool 이름이 요청 `tools[]`에 있고 arguments가 파싱되어 해당 tool의 `function.parameters` schema를 만족하면, Edge는 이를 OpenAI `tool_calls`로 정규화하고 raw 블록을 `content`에서 제거한 뒤 `finish_reason: "tool_calls"`로 반환한다. 요청 `tools[]`에 없는 tool 이름, unclosed/function 정의 누락 같은 malformed 블록, schema를 위반하는 arguments는 성공 content로 반환하지 않고 tool validation 실패로 처리한다. non-stream과 strict buffered stream 응답은 bounded tool-validation attempt 한도까지 run을 재시도하고, 그래도 실패하면 `tool_validation_error`로 응답한다. live SSE 스트림은 raw 블록을 content delta로 flush하지 않고 `tool_validation_error` 이벤트로 스트림을 종료한다.
요청에 `tools[]`가 없으면 assistant content의 tool-call 유사 텍스트는 파싱하거나 합성하지 않고 backend content 원문으로 그대로 둔다. 자연어 추론은 어떤 경우에도 `tool_calls`로 변환하지 않는다.
raw `<tool_call>`/`{{...}}` 블록과 `<|mask_end|>` 같은 알려진 chat-template sentinel은 성공 응답의 `content`나 SSE delta에 노출하지 않는다. sentinel은 content와 reasoning 양쪽에서, streaming chunk 경계에 걸쳐 분할되더라도 sanitize한다.
text tool-call을 구조화할 때 Edge는 route와 무관하게 요청의 `tools[].function.parameters` schema를 기준으로 arguments를 정규화한다. 예를 들어 tool schema가 `commands: string[]`만 허용하면 command 객체 입력도 shell string 배열로 접고, `commands: {command,args}[]`를 허용하면 shell 문법이 없는 명령을 structured argv로 만든다. schema에 없는 UI 설명용 `description`이나 실행 위치 힌트용 `runInTerminal`은 command 객체와 최상위 args에서 제거하되, `cd`, `command -v`, `&&`, pipe, redirect, quote 등 shell 해석이 필요한 명령은 schema가 허용할 때 `commands: ["cd /work && git status"]` 같은 shell string으로 유지한다.
`parallel_tool_calls`, `stream_options`, `store`는 클라이언트 호환성을 위해 수신하지만 현재 Edge 실행 의미에는 반영하지 않는다.

금지:

- `metadata.source`, `metadata.cli`, `metadata.inference`, `metadata.nomadcode`, `metadata.workspace`
- normalized(non-provider) route에서 `options`, `format`, `keep_alive` 같은 backend/provider 전용 request wrapper를 OpenAI-compatible 표준 field처럼 요구하는 방식. 이 금지는 provider-pool raw passthrough에서 selected provider가 지원하는 OpenAI-compatible extension field 보존에는 적용하지 않는다.
- `session_id`, `timeout_sec`, `workspace` 같은 IOP 실행 제어 field

## Legacy Completions

`POST /v1/completions`는 현재 IOP Edge OpenAI-compatible 표면에서 제공하지 않는다.
text completion 형태의 신규 호출은 `/v1/responses`를 사용하고, message 기반 호출은 `/v1/chat/completions`를 사용한다.

## Routing

In legacy mode, Edge 설정이 `openai.model_routes[]`를 제공하면 `model`은 먼저 route catalog에서 해석된다.
매칭 route가 없으면 기존 fallback 규칙에 따라 `openai.target` 또는 요청의 `model`을 내부 target으로 사용한다.

Managed mode does not use those fallbacks. The public model must be an active projected route id or alias owned by the authenticated principal, and that route must resolve uniquely to its configured resource selector, profile, and upstream model.

Top-level `models[]`가 있으면 IOP `/v1/models`와 provider-pool dispatch의 static catalog source of truth다. Seulgivibe provider는 runtime adapter type을 `openai_compat`로 정규화하되 provider family label로 `seulgivibe_claude` 또는 `seulgivibe_openai`를 보존할 수 있다. Tracked catalog 예시는 model/provider mapping만 담고 실제 endpoint credential이나 raw user token은 담지 않는다.
`models[]` provider mapping은 OpenAI-compatible provider와 normalized-only provider를 같은 model group 안에 둘 수 있다. dispatch는 기존 capacity + priority + availability 기준으로 provider를 한 번 선택하고, client request field가 아니라 selected provider capability로 passthrough 또는 normalized execution path를 결정한다.

## 관련 계약

- `iop.anthropic-compatible-api`: `agent-contract/outer/anthropic-compatible-api.md` (shared auth, metadata, ingress, model catalog, and provider tunnel). Anthropic handlers do not currently emit the OpenAI usage metric series described above.
- `iop.edge-node-runtime-wire`: `agent-contract/inner/edge-node-runtime-wire.md` (provider tunnel, protocol profile wire)
- `iop.edge-config-runtime-refresh`: `agent-contract/inner/edge-config-runtime-refresh.md` (protocol profile config, overlay, alias)
