Define public Responses adapter contract and conformance suite

[clutchpbcfo]

What changed

• add ADR 0001 for the narrow public POST /v1/responses compatibility profile;
• add an OpenAPI 3.1 specification and exact SSE event-order contract;
• specify auth, fail-closed model selection, errors, identifiers, durable local idempotency, disconnect behavior, usage limitations, and ownership boundaries;
• add black-box conformance tests backed only by fake/local upstream clients; and
• run OpenAPI lint, Python SDK, release-validation, and the Linux/macOS/Windows Node 20/22 matrix in CI.

Refresh after PR #4

This draft is rebased directly onto merged main at ad1580a5379eed69cc919271932ee082b8c3df88. The original contract intent is unchanged. Integration-only updates:

• pin the ADR to the merged gateway baseline;
• prove completed-response idempotency replay from protected local state across a gateway restart;
• preserve the adapter-owned disconnect reason in the fake upstream and assert the sanitized cancelled receipt with local_polling_only scope;
• assert X-Usage-Source: unavailable and omitted usage on JSON and SSE success; and
• refresh the proof receipt to show request IDs and hashed private operational references.

Honest compatibility boundary

• Idempotency is bounded, durable, and local. It is not provider-backed.
• A client disconnect aborts local polling. It does not prove native HyperAgent work stopped or prevent charges.
• Token/cost usage is unavailable from the documented MCP result, so usage is omitted rather than fabricated.
• No durable provider-side Response resource, retrieval route, cancellation route, or native token stream is claimed.

Effective diff

• No gateway implementation files changed.
• 12 files differ from current main: contract/spec/docs/workflow/package metadata and fake-backed conformance tests only.
• Effective size: 1,721 insertions, 4 deletions.

Baseline and head

• merged PR feat: harden Responses gateway operations #4 / current base: ad1580a5379eed69cc919271932ee082b8c3df88
• refreshed draft head: fc30254f9c477dc19d68a5f28a200ad157ec47f3
• public release tag remains v0.4.2 at 4e1372e3ad514aa4e438628a9e6af0588f6025a6

Local validation

• Node 22 full suite with Python SDK and real Codex CLI against local mocks: 76 passed, 0 failed, 0 skipped
• Node 20.19.5 full suite with Python SDK and real Codex CLI against local mocks: 76 passed, 0 failed, 0 skipped
• focused conformance suite: 23 passed, 0 failed, 0 skipped
• npm run lint:openapi: valid
• npm audit --omit=dev: 0 vulnerabilities
• syntax checks, npm pack --dry-run, and git diff --check: passed

Docker and gitleaks executables were not installed locally; the exact-head release-validation CI job owns those checks.

Requires HyperAgent platform support

1. Authoritative token and/or dollar usage in documented thread results.
2. A documented native thread-cancellation operation.
3. Provider-backed idempotency and authoritative lookup/reconciliation for ambiguous create_thread outcomes.

No HyperAgent credentials, calls, credits, undocumented APIs, publishing, deployment, tagging, external contact, or merge were used.