Document ChatGPT auth flows, WHAM endpoints, and inference request/response shapes

[Skarian]

Motivation

• The API documentation was missing many request parameters and response shapes needed to implement the CLI against ChatGPT‑authenticated backends.
• Clarify the scope of API_SPEC.md to explicitly cover ChatGPT OAuth/device‑code login flows and all downstream WHAM and inference APIs used when AuthMode::ChatGPT is active.
• Eliminate confusion about transport versus auth by documenting that Responses can use SSE or WebSocket per provider wire_api configuration.

Description

• Expanded API_SPEC.md with complete request and response field lists for OAuth authorize and POST /oauth/token (authorization code and token‑exchange flows) and the device code endpoints, including exact form/json fields and returned tokens.
• Added WHAM endpoint schemas for GET /wham/usage (RateLimitStatusPayload and nested objects), GET /wham/tasks/list (PaginatedListTaskListItem and TaskListItem), GET /wham/tasks/{task_id} (CodeTaskDetailsResponse, Turn, TurnItem, Worklog, TurnError), POST /wham/tasks (request body shape produced by the Cloud Tasks client), and sibling turns endpoint shape.
• Documented inference endpoints under /backend-api/codex including GET /models response (ModelsResponse and ModelInfo fields), POST /responses and POST /chat/completions request fields, and the responses_websocket transport behavior and handshake headers.
• Added streaming/event shapes (ResponseEvent variants and ResponseItem variants) used by Codex to consume SSE/WebSocket/Chat streaming, and linked these to in‑repo types and builders.

Testing

• No automated tests were run because this is a documentation‑only change.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 836e4b6b52

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Document interval as string only (number parsing fails)

This line says the device-code interval can be a string or number, but codex-rs/login/src/device_code_auth.rs parses it with String::deserialize in deserialize_interval, which rejects numeric JSON values. If the server returns a numeric interval (a common OAuth device-code response pattern), login will fail to parse. Either update the doc to say the value must be a string or update the deserializer to accept numbers; otherwise implementers will be misled.

Useful? React with 👍 / 👎.