<!-- task=responses_provider_bridge plan=0 tag=API -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt.
> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields.
> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state.
> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume.

## Overview

date=2026-08-14
task=responses_provider_bridge, plan=0, tag=API

## For the Review Agent

> **[REVIEW AGENT ONLY]** Compare every item with source and run fresh verification. Implementation output is handoff evidence only. Append verdict and routing signals, archive the active pair, and create `complete.log`/archive the task directory only on PASS. WARN/FAIL must follow the code-review skill and include reviewer-proven root cause plus one selected fix.

## Implementation Item Completion

| Item | Status |
|---|---|
| API-1 Profile-selected Responses request bridge | [ ] |
| API-2 Convert provider responses and streams to Responses | [ ] |
| API-3 Lock compatibility with tests and contracts | [ ] |

## Implementation Checklist

- [ ] Implement API-1 profile-selected Responses request bridging and fail-closed admission without caller-specific branches.
- [ ] Implement API-2 provider response/stream conversion back to canonical Responses while preserving tools, reasoning, usage, errors, and exactly-one terminal.
- [ ] Implement API-3 focused regression coverage and synchronize the OpenAI outer contract and living spec.
- [ ] Run the focused/package verification and, after exact-source dev deployment, the two failed Codex direct-route cycles.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** Implementing agents must not modify or check this section.

- [ ] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`.
- [ ] Verify verdict, dimensions, and Required/Suggested/Nit classifications match.
- [ ] Run applicable required verification and record fresh output.
- [ ] For each Required/Suggested finding, record evidence, root cause, one selected fix, files/symbols/tests, and acceptance commands.
- [ ] Archive active review to `code_review_cloud_G08_0.log` and plan to `plan_local_G08_0.log`.
- [ ] Verify the Agent-Ops managed `.gitignore` block.
- [ ] On PASS, write `complete.log`, remove active markdown files, and move the task directory to `agent-task/archive/YYYY/MM/responses_provider_bridge/`.
- [ ] On WARN/FAIL, write the next filesystem state required by the code-review skill and do not write `complete.log`.

## Deviations from Plan

_Record actual deviations and reasons. If none, replace with `None`._

## Key Design Decisions

_Record actual implementation decisions._

## Reviewer Checkpoints

- Native Responses profile and nil-profile fallback remain byte-compatible.
- Selection is based only on request requirements and concrete protocol profile, never caller/agent identity.
- Unsupported Responses controls fail before provider dispatch rather than being dropped.
- Claude uses Messages wire and Gemini uses Chat wire; both return canonical Responses JSON/SSE.
- Gemini thought signature survives function call → `call_id` → function result replay.
- StreamGate remains the single response/terminal owner, including recovery attempts.
- Contract/spec match code and keep normalized non-provider limitations unchanged.

## Verification Results

### API-1 Focused Request Bridge

```bash
go test -count=1 ./apps/edge/internal/openai -run 'TestResponsesProtocolProfile(BridgesToAnthropicMessages|BridgesToGeminiChat|BridgeRejectsUnrepresentableControls|OperationPassthrough|OperationAdmissionTable)$'
```

_Paste actual stdout/stderr._

### API-2 Focused Response Bridge

```bash
go test -count=1 ./apps/edge/internal/openai -run 'TestResponses(ProtocolProfileAnthropicBridgeResponse|ProtocolProfileGeminiBridgeResponseAndSignature|ProviderBridgeStreaming|ProviderBridgeStreamingTerminalExactlyOnce|ProviderBridgeProviderErrorSanitized)$'
```

_Paste actual stdout/stderr._

### Package and Race Verification

```bash
gofmt -w apps/edge/internal/openai/provider_normalization.go apps/edge/internal/openai/responses_handler.go apps/edge/internal/openai/anthropic_bridge.go apps/edge/internal/openai/stream_gate_tunnel_codec.go apps/edge/internal/openai/responses_stream_gate.go apps/edge/internal/openai/responses_protocol_profile_test.go apps/edge/internal/openai/stream_gate_pipeline_test.go
go test -count=1 ./apps/edge/internal/openai -run 'TestResponses(ProtocolProfile|ProviderBridge)'
go test -count=1 ./apps/edge/internal/openai
go test -race -count=1 ./apps/edge/internal/openai -run 'TestResponsesProviderBridgeStreaming'
git diff --check
```

_Paste actual stdout/stderr._

### Contract/Spec Verification

```bash
rg --sort path -n 'Responses.*(Messages|Chat)|Gemini.*(signature|thought)' agent-contract/outer/openai-compatible-api.md agent-spec/input/openai-compatible-surface.md
```

_Paste actual stdout/stderr._

### External Dev Preflight and Codex Cycles

```bash
ssh toki@toki-labs.com '/bin/zsh -lc '\''cd /Users/toki/agent-work/iop-dev && git status --short --branch && git rev-parse HEAD && git rev-parse origin/dev && command -v go && go version && codex --version && claude --version && opencode --version && lsof -nP -iTCP:18083 -sTCP:LISTEN && lsof -nP -iTCP:18084 -sTCP:LISTEN'\'''
```

_Paste sanitized preflight, exact-source rebuild/deploy identity, and the two Codex → Claude/Gemini cycle outputs. Do not paste secrets or raw provider payloads._

---

> **[IMPLEMENTING AGENT — BEFORE SAVING]** Fill every implementation-owned section, leave review-only sections unchanged, and report ready for review.

## Section Ownership

| Section | Owner | Note |
|---|---|---|
| Header, Overview, Review instructions | Fixed | Implementer must not modify |
| Implementation Item Completion | Implementer | Check status only |
| Implementation Checklist | Implementer | Check boxes only; text/order fixed |
| Review-Only Checklist | Review agent | Implementer must not modify |
| Deviations, Key Design Decisions | Implementer | Replace placeholders with actual evidence |
| Reviewer Checkpoints | Fixed | Review oracle |
| Verification Results | Implementer, then reviewer | Implementer records initial output; reviewer reruns fresh |
| Code Review Result | Review agent appends | Not present in stub |