feat(server): add scoped Responses API support

[PhilipJohnBasile]

Summary

Adds a stateless, text-only /v1/responses adapter on the existing chat inference path. Supports structured text input, instructions, streaming/non-streaming output, JSON-schema text formats, client-executed function/custom tools, and namespace-grouped functions. Returned calls preserve their original names and namespaces.

Current-main integration complete

Review head: bee434d2ff386acdec33f0dc3327dcac0d8e8bf4.

Merged exact upstream 21be78b3f51820eecef020e5e4855c0715eaf9a5 through an ordinary two-parent commit. The request-observability conflict was resolved semantically: upstream's bounded client-turn/client-entry link metadata and the Responses-specific observability return path are both retained. A regression verifies valid request links survive and invalid header values are excluded. Two unused postcommit bookkeeping assignments were removed without changing template normalization or sentinel construction.

The previous current-main conflict blocker is addressed. Existing reasoning metadata, namespace handling, footer isolation, logprobs and recovery behavior remain covered.

Validation on the published source

Readiness run 34069355260, macOS ARM64, Python 3.11, real MLX imports:

• 484 tests passed, zero failures/errors/skips across OpenAI serving, Responses, request observability, endpoint hygiene, dashboard endpoints and import boundaries.
• Changed-source Ruff, Python compilation, and diff checks passed.
• The exact validated merge commit was published and the PR branch fast-forwarded without force. Fork-only audit helpers and workflows are not in the PR.

This is API/source validation, not a newly performed model or packaged-app smoke. Youssof's separate 2.11.3 integration (39b78054) and real Codex two-tool run remain the maintainer's runtime receipt; this branch must still be coordinated with that release integration rather than merged twice.

Hosted-tool decision and verified client setup

Keep explicit 400 errors for unsupported hosted tools, rather than silently removing requested capabilities. After configuring the local Responses provider:

codex -c 'web_search="disabled"' --disable image_generation

Optional --disable apps creates a deliberately smaller client capability profile; it is not a shell-network policy. Preserve existing provider/credential settings.

The exact Codex CLI 0.144.1 loopback capture is documented beside the endpoint in docs/api.md and docs/validation/codex-0.144.1-local-tool-profile.json. Capture run 34064490796 verified default web_search and hosted-disabled request construction without an account or model. Image generation was enabled but not advertised by that particular model/provider configuration; no universal default-tool or installed-connector size claim is made.

Deliberate limits

Hosted search/image/tool/MCP/code-interpreter execution, background jobs, response storage, previous_response_id, multimodal input and stream obfuscation are outside this route. Unsupported types and requested obfuscation fail explicitly. Clients resend full conversation and tool outputs. Existing Codex 0.146 fixtures are sanitized representative contracts, not raw requests.

Ready for source review with the current-main integration and focused tests completed. Maintainer review, required upstream checks and release coordination remain authoritative.

[youssofal]

Review queued for the next cycle, together with #193. The stateless adapter reusing the chat inference path is the right starting shape; the OpenAI 2.52 event validation is what I will test against first.

[youssofal]

The 2.8.0 refactor moved the request prologue this PR patches (RequestPolicy extraction), so this needs a semantic rebase, not a textual one. I want it in. Rebase onto v2.8.0 and I will run the Codex fixture matrix against it; the reasoning_effort high mapping changed too (now maps up to xhigh), so the _xhigh fixture is the one to re-check.

[PhilipJohnBasile]

Current-main refresh completed and the PR branch was force-updated as one clean signed-off commit.

• upstream main: 90d8c4b57233b61731269866b13d5af697284d8c
• exact PR head: ede7180e5e68d74e11626bd0097f25efb05605d6
• commit count ahead: 1
• intended changed files: 10
• temporary rebase workflow and tests/conftest.py diagnostics: absent from the final diff

The semantic resolution keeps the Responses reasoning metadata in RequestPolicy, preserves current logprobs and unclosed-reasoning recovery, keeps Responses-only footer suppression in both output paths, and preserves xhigh end-to-end. The current-main fixture adjustments retain the protocol assertions while accounting for the additional system message and closing the active reasoning block before OK.

Publication was gated on the frozen uv.lock toolchain on macOS ARM64 / Python 3.11. The focused Responses/OpenAI tests, RequestPolicy observability golden tests, Ruff, compileall, hygiene scan, diff check, and one-commit/clean-file assertions all passed before the force-update.

The upstream ci, hygiene, and build runs now show action_required because fork workflows require maintainer approval. They are queued, not failing.

[PhilipJohnBasile]

@youssofal The scoped Responses API branch is mergeable and the current-main integration/validation is complete. The remaining upstream checks are waiting for external-fork approval rather than failing tests. When convenient, please approve the workflows and review the frozen ede7180 head; I am holding the scope at text-only/stateless Responses compatibility with hosted tools explicitly disabled.

[youssofal]

Sorry for the silence here. The text only stateless scope is the right shape and the single clean commit makes it reviewable. I am not going to rush a merge of this size without reading the frozen head properly, it is next in the review queue after the current release work, and I will approve the workflow runs when I sit down with it.

[youssofal]

Thanks. Of the open API PRs this is the most useful one. A stateless /v1/responses adapter on the existing chat path, with real Codex fixtures, is exactly the bounded subset #193 asked for, and refusing hosted tools and obfuscation with a 400 is the right call.

It conflicts with main right now (the request prologue and the stats footer moved after your rebase), so it needs one more rebase before review. It is not in 2.11.2. It is first on the API list for the next release and will land under your name.

One question for the rebase. Codex sends web_search by default. What does a fresh Codex install see on its first request, and is there a one-line client setting we can put in the docs next to the endpoint?

[youssofal]

Update on the rebase: your 12 files are on the branch for the next release under your authorship, the unit tests pass, and a real codex exec (0.144.1) finished a two-tool file task through /v1/responses on the 27B in 23 seconds. It ran python3 hello.py, rewrote the file through the shell tool, ran it again and reported both outputs (12,069 tokens, streaming, no server errors). It ships with the next release.

Two things on the Codex side decide the first-request question:

1. Codex's default tool list includes hosted web_search and hosted image_generation. The adapter answers 400 for both, so out of the box the very first request fails until the user sets web_search = "disabled" and turns off image generation.
2. With Codex apps installed, the tools array is 615 KB of connector schemas (Asana, Figma, GitHub, Gmail, Slack and so on). The adapter counted it, correctly, as 185,986 tokens against a 131,072 window. With an empty CODEX_HOME the request drops to 47 KB and 6 tools.

A question for you, since you designed the rejection: should the adapter drop hosted tool types it cannot serve and say so (a warning in the response metadata and in the serve log), so Codex works with its defaults? Or keep the 400 and document both settings? The model never sees hosted tools either way. The apps bloat stays a documentation item.

[PhilipJohnBasile]

@youssofal Keep the explicit 400 as the default. Dropping hosted tools changes the requested capability set, and a response-metadata warning is not a reliable client acknowledgement. It also cannot preserve an explicitly selected unsupported tool. I would not trade a visible setup error for a successful-looking response that never had the requested capability.

I verified the client-side answer against @openai/codex@0.144.1 using a fresh CODEX_HOME and a loopback Responses capture endpoint. The one-line setup is:

codex -c 'web_search="disabled"' --disable image_generation

For a deliberately minimal local setup, append --disable apps. This is separate from disabling hosted tools and does not disable shell networking. Persistent equivalents are top-level web_search = "disabled" and [features] image_generation = false, with optional apps = false in that same table. Existing provider/credential configuration must be preserved.

Results: the default custom-provider capture advertised function, namespace, and web_search; both explicit hosted-disabled profiles advertised only function and namespace. features list confirmed image_generation=false, and apps=false in the minimal profile. Image generation was enabled by default but was not advertised by this particular fresh-home/model configuration, so I am not claiming every default request contains it. Your installed-client capture remains the relevant evidence for that case and the 615 KB app-schema payload.

The tested settings and limitations are now beside /v1/responses in docs/api.md at a47ea5e, with a committed receipt in docs/validation/codex-0.144.1-local-tool-profile.json. Reproducible capture run: https://github.com/PhilipJohnBasile/MTPLX/actions/runs/34064490796 . This tested request construction only; it did not run a model, use an account, test desktop app-server, or measure an installed connector profile.

Thanks for the 39b78054 integration and real two-tool receipt. These new commits are documentation/validation only, so they can accompany that integration without replacing your rebased runtime code. The adapter stays fail-closed, and the existing context-window guard stays intact.

[PhilipJohnBasile]

@youssofal The remaining current-main conflict is resolved in bee434d, an ordinary merge of 21be78b. The semantic resolution preserves both upstream's validated client-turn/client-entry links and the adapter observability return path, with a new regression. The hosted-tool policy remains explicit 400s, and the previously verified Codex settings remain documented.

The exact published source passed 484 API/Responses/observability/dashboard/import-boundary tests, Ruff, compilation and diff checks on macOS ARM64: https://github.com/PhilipJohnBasile/MTPLX/actions/runs/34069355260 . GitHub now reports the branch mergeable. Ready for source review and coordination with your separate 39b78054 release integration; this is not a request to land duplicate runtime work.