fix(api): eliminate schema mismatches in Responses compact endpoint

[EleanorWho]

Summary

• Make CompactResponseRequest.model nullable (str | None) to match OpenAI's ModelIdsCompaction type
• Add post-generation schema transforms that inject a ModelIdsResponses reference into the model field and restructure the input field's anyOf to nest string + array inside a oneOf wrapper, matching the OpenResponses spec structure
• Reduces /responses/compact conformance issues from 3 to 1 and improves the Responses category score from 88.8% to 89.7%

What was fixed

Field	Before	After
model	Type added: ['string']; Union variants removed: 3	Eliminated
input	Union variants added: 2; removed: 1	Eliminated
output.items	Union variants added: 4	Unchanged (see below)

Why output.items cannot be fully resolved

The remaining issue (Union variants added: 4) has two causes:

1. Structural: OGX uses a nested anyOf[oneOf[8 discriminated types], ref, ref, ref] generated by Pydantic's left_to_right union mode, while OpenAI uses a flat oneOf[25]. Flattening the union and renaming components to match changes the issue to removed: 14 but doesn't reduce the issue count — the score stays the same.

2. Missing tool types: OpenAI's ItemField includes 14 tool types not implemented in OGX: ToolSearchCall, ToolSearchOutput, ImageGenToolCall, ComputerToolCall, ComputerToolCallOutput, CodeInterpreterToolCall, LocalShellToolCall, LocalShellToolCallOutput, FunctionShellCall, FunctionShellCallOutput, ApplyPatchToolCall, ApplyPatchToolCallOutput, CustomToolCall, CustomToolCallOutput.

If needed, stub Pydantic models (just type: Literal["xxx"] + model_config = ConfigDict(extra="allow")) could be added for these 14 types to fully eliminate the issue.

Why this triggers oasdiff breaking change detection

The structural changes (anyOf → oneOf wrapping for input, adding ModelIdsResponses variant to model) are flagged by oasdiff as breaking changes because the schema structure differs from the previous generated output. The API accepts and returns the same data — no runtime behavior changes.

Test plan

• uv run pre-commit run --all-files — all hooks pass except api-conformance (expected, see above)
• uv run pytest tests/unit/ -x --tb=short — 2367 tests pass
• uv run ./scripts/run_openapi_generator.sh — all specs generate and validate
• PATH="$HOME/go/bin:$PATH" uv run python scripts/openai_coverage.py --update --generate-docs — Responses score 88.8% → 89.7%, compact issues 3 → 1

🤖 Generated with Claude Code

---

[github-actions]

✱ Stainless preview builds

This PR will update the llama-stack-client SDKs with the following commit message.

fix(api): eliminate schema mismatches in Responses compact endpoint

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ llama-stack-client-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

✅ llama-stack-client-node studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/llama-stack-client-node/14a42f0c803d67302ac49e0c04317299be756f27/dist.tar.gz

✅ llama-stack-client-python studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/llama-stack-client-python/dbbc727c612a503beb9636546a8cfea8076e8ea2/ogx_client-0.8.0a2-py3-none-any.whl

✅ llama-stack-client-go studio · conflict

Your SDK build had at least one new note diagnostic, which is a regression from the base state.

New diagnostics (1 note)

💡 Go/SchemaUnionDiscriminatorMissing: Union has object variants but no discriminator.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-27 11:07:01 UTC

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @EleanorWho please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[mattf]

@EleanorWho which spec are you using as a reference?

https://www.openresponses.org/reference#compaction-endpoint and https://developers.openai.com/api/reference/resources/responses/methods/compact both show the model as required.

[EleanorWho]

@EleanorWho which spec are you using as a reference?

https://www.openresponses.org/reference#compaction-endpoint and https://developers.openai.com/api/reference/resources/responses/methods/compact both show the model as required.

Hi @mattf , I use ogx/docs/static/openai-spec-2.3.0.yml (the raw OpenAPI spec that oasdiff compares against) as a reference.
At line 47981, we have:

    ModelIdsCompaction:
      anyOf:
        - $ref: '#/components/schemas/ModelIdsResponses'
        - type: string
        - type: 'null'

The model field on CompactResponseMethodPublicBody references ModelIdsCompaction, which includes a null variant, so the str | None change matches the spec.

As for the reference links you mentioned, I guess the rendered docs pages appear to simplify this by hiding the nullable annotation.

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @EleanorWho please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[cdoern]

@EleanorWho PTAL at the conflicts here

[mattf]

@EleanorWho which spec are you using as a reference?
https://www.openresponses.org/reference#compaction-endpoint and https://developers.openai.com/api/reference/resources/responses/methods/compact both show the model as required.

Hi @mattf , I use ogx/docs/static/openai-spec-2.3.0.yml (the raw OpenAPI spec that oasdiff compares against) as a reference. At line 47981, we have:

    ModelIdsCompaction:
      anyOf:
        - $ref: '#/components/schemas/ModelIdsResponses'
        - type: string
        - type: 'null'

The model field on CompactResponseMethodPublicBody references ModelIdsCompaction, which includes a null variant, so the str | None change matches the spec.

As for the reference links you mentioned, I guess the rendered docs pages appear to simplify this by hiding the nullable annotation.

@EleanorWho this is tough -

• https://www.openresponses.org/openapi/openapi.json says model is required
• https://www.openresponses.org/reference#compaction-endpoint says model is required
• https://developers.openai.com/api/reference/resources/responses/methods/compact says model is required
• https://raw.githubusercontent.com/openai/openai-openapi/refs/heads/master/openapi.yaml says it is nullable

and empirically it's required -

$ curl https://api.openai.com/v1/responses/compact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": "Create a simple landing page for a dog petting cafe."
      },
      {
        "role": "assistant",
        "content": "Here is a basic HTML landing page..."
      },
      {
        "role": "user",
        "content": "Now make it mobile friendly."
      }
    ]
  }'
{
  "error": {
    "message": "Missing required parameter: 'model'.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "missing_required_parameter"
  }
}

looks like a bug in the openai/openai-openai spec.

@cdoern where does our copy of the spec come from?