131 lines
7.2 KiB
Markdown
131 lines
7.2 KiB
Markdown
<!-- 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 |
|