Chore/sync latest openapi spec

[nezhyborets]

What

1. Make make generate download the latest spec before generating.
2. Generate

Why

Planning one working on the project. Better to do it with the updated and complete types set.

Affected Areas

• Scripts. New generated file differs, so some scripts had to be updated to accommodate that.

More Info

• The Demo app currently fails to build locally on newer Xcode toolchains (unrelated to this PR's changes — a pre-existing linker incompatibility with the pinned ExyteChat 2.7.10 dependency). Fixing it requires a breaking ExyteChat 2.x → 3.x migration of DemoChat, which we'll do separately. Tracked in Demo app fails to build on newer Xcode: ExyteChat 2.x needs a 3.x migration #444.

[Copilot]

🟡 Changes recommended

The critical tool-facade decoding issue and unresolved public API compatibility breaks must be addressed.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Synchronizes the project with the latest OpenAPI specification and updates related models, generation scripts, documentation, and tests.

Changes:

• Downloads the latest specification before generation.
• Updates response schemas, output items, mocks, and fixtures.
• Generalizes generation workarounds and documents the workflow.

File summaries

File	Summary
Tests/OpenAITests/ResponseObjectCodingTests.swift	Updates response decoding fixtures.
Tests/OpenAITests/MockServerSentEvent.swift	Updates the annotation fixture.
Tests/OpenAITests/Extensions/ResponseObject+Mock.swift	Updates response mocks for new fields.
Sources/OpenAI/Public/Schemas/Facade/OutputItem.swift	Critical (1 vote): The Tool facade lacks the programmatic_tool_calling case, so valid responses may fail decoding.
Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift	Moderate (1 vote each): Six existing public members are retyped or changed incompatibly without compatibility shims or documented allowlisting.
Scripts/fix_recursive_reference.py	Generalizes recursive-reference handling.
Scripts/extract_components.py	Removes duplicate generated typealiases.
Makefile	Moderate (3 votes): Interrupted downloads can truncate the tracked specification; use a temporary file and atomic replacement.
CONTRIBUTING.md	Documents the updated generation workflow.

Review details

Suppressed comments (6)

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:17

• ResponseObject.Truncation is an existing public typealias, but this changes its underlying type from Schemas.ResponseProperties.TruncationPayload to Schemas.Response.Value3Payload.TruncationPayload. CONTRIBUTING.md:34-44,71-79 requires public symbols to remain additive and unavoidable breaks to be explicitly allowlisted and documented; the current allowlist and Unreleased changelog have no entry for this break. Please preserve a compatibility type where possible, or record the accepted break and migration before merging.

    public typealias Truncation = Schemas.Response.Value3Payload.TruncationPayload

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:28

• This retypes the existing public conversation member from Schemas.Conversation2? to Schemas.ResponseConversation?, which is a source/API break for clients compiled against the old member. The additive-only policy in CONTRIBUTING.md:34-44,71-79 requires a compatibility shim where possible or an explicit allowlist and CHANGELOG migration for an unavoidable break; neither is included here.

    /// The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation.
    public let conversation: Schemas.ResponseConversation?

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:45

• This retypes the existing public instructions member from String? to the generated Instructions? one-of. That breaks source compatibility for every caller using the old string property, contrary to the additive-only API policy in CONTRIBUTING.md:34-44,71-79; retain a deprecated compatibility surface or explicitly allowlist and document the unavoidable break.

    /// A system (or developer) message inserted into the model's context, either as a plain string or a list of input items.
    ///
    /// When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.
    public let instructions: Instructions?

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:56

• Changing metadata from nonoptional [String: String] to optional is a public retype that forces existing consumers to add unwrapping, while the updated OpenAPI Response still lists metadata as required (openapi.yaml:61254-61266). This conflicts with the additive-only policy in CONTRIBUTING.md:34-44; preserve the existing facade type where possible, or explicitly allowlist and document the break.

    /// Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
    ///
    /// Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
    public let metadata: [String: String]?

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:133

• Making the existing public toolChoice member nonoptional is another public retype and changes both source compatibility and decoding behavior for payloads that omit the key. The additive-only policy in CONTRIBUTING.md:34-44,71-79 requires retaining compatibility where possible or documenting/allowlisting an unavoidable break; only the test fixtures were updated here.

    /// How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools the model can call.
    public let toolChoice: Schemas.ToolChoiceParam

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:119

• This retypes the existing public serviceTier member from Schemas.ServiceTier? to Schemas.ServiceTierResponses?, so downstream code using the previous enum type no longer compiles. CONTRIBUTING.md:34-44,71-79 requires preserving public symbols or explicitly accepting breaks through the allowlist and CHANGELOG; this PR does neither for this change.

    public let serviceTier: Schemas.ServiceTierResponses?

• Files reviewed: 9/11 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Critical public API and decoding issues remain, along with a generation race and missing stream coverage.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

Makefile:49

• Both commands use the single fixed openapi.yaml.tmp path. Concurrent make generate/make download-spec invocations can overwrite or move each other's temporary file, causing one generation to read a partially written spec or fail on mv; use a per-invocation temporary file and remove it with a trap before the final move.

	curl -fsSL "$(OPENAPI_SPEC_URL)" -o "$(PROJECT_DIR)/openapi.yaml.tmp"
	mv "$(PROJECT_DIR)/openapi.yaml.tmp" "$(PROJECT_DIR)/openapi.yaml"

• Files reviewed: 18/20 changed files
• Comments generated: 9
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved schema mappings, service-tier compatibility, and Demo output-item handling issues block approval.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

Sources/OpenAI/Public/Schemas/Facade/OutputItem.swift:38

• These newly decodable output-item variants are not handled by DemoChat: its non-streaming and streaming output handlers fall through to StoreError.unhandledOutputItem for .program, .programOutput, and .additionalTools (see Demo/DemoChat/Sources/ResponsesStore.swift:498,672,711). A valid response using these items will therefore fail in the Demo; add explicit handling/ignoring cases in all three switches, with coverage, before exposing them here.

    /// A program item generated by the model.
    case program(Schemas.Program)
    /// The output of a program item.
    case programOutput(Schemas.ProgramOutput)

• Files reviewed: 19/21 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

Makefile:49

• If curl is interrupted or fails after creating the fixed-name temp file, openapi.yaml.tmp is left behind because there is no cleanup. Since the root .gitignore does not ignore this path, a failed make download-spec leaves an untracked artifact that can be accidentally staged; use a unique temp file with an EXIT trap (or remove the temp file on failure) before moving it into place.

	curl -fsSL "$(OPENAPI_SPEC_URL)" -o "$(PROJECT_DIR)/openapi.yaml.tmp"
	mv "$(PROJECT_DIR)/openapi.yaml.tmp" "$(PROJECT_DIR)/openapi.yaml"

Sources/OpenAI/Public/Schemas/Facade/ResponseStreamEvent.swift:322

• These branches add a second, independent decoding dispatch table for the public ResponseStreamEvent facade, but the new tests exercise only ModelResponseEventsStreamInterpreter's private dispatch path. A typo here would leave JSONDecoder().decode(ResponseStreamEvent.self, from:) broken while the interpreter tests still pass; add direct facade-decoding tests for the new reasoning-text, shell-call, and custom-tool-input events (similar to ResponseFunctionCallArgumentsDoneEventTests.testResponseStreamEventFacadeExposesName).

        case .responseReasoningTextDelta:
            self = .reasoningText(.delta(try Schemas.ResponseReasoningTextDeltaEvent(from: decoder)))
        case .responseReasoningTextDone:
            self = .reasoningText(.done(try Schemas.ResponseReasoningTextDoneEvent(from: decoder)))

• Files reviewed: 21/23 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The Makefile cleanup trap is not POSIX-portable, and requested positive decoding and round-trip fixtures are missing.

Review details

Suppressed comments (3)

Makefile:55

• make recipes run under /bin/sh, and EXIT is not a portable trap condition on POSIX shells such as dash (used by default on Linux). On those systems this trap command fails, so a successful download leaves the temporary openapi.yaml.XXXXXX file behind and a failed/interrupted transfer is not cleaned up as intended. Use the POSIX 0 condition here, or explicitly run this recipe with Bash.

	trap 'rm -f "$$tmp"' EXIT; \

Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift:64

• The new response fields added here are only covered by the minimal-response fixtures with those keys absent. Add at least one positive decoding fixture containing moderation, prompt_cache_diagnostics, prompt_cache_options, the union-shaped instructions, and a response service_tier; otherwise incorrect generated types, coding keys, or requiredness can pass the current tests unnoticed.

    /// Moderation results or errors for the response input and output.
    public let moderation: Schemas.Moderation?

Sources/OpenAI/Public/Schemas/Facade/OutputItem.swift:44

• The new facade mappings for program, programOutput, and additionalTools are not exercised by any test. Because OutputItem.init(from:) delegates to the generated one-of and then switches over its cases, a generated case/type mismatch can compile successfully but still fail at runtime. Add decode/round-trip fixtures for these three discriminator values, following InputItemCodingTests.

    /// A program item generated by the model.
    case program(Schemas.Program)
    /// The output of a program item.
    case programOutput(Schemas.ProgramOutput)
    /// A tool search call.
    case toolSearchCall(Schemas.ToolSearchCall)
    /// The output of a tool search call.
    case toolSearchOutput(Schemas.ToolSearchOutput)
    /// The additional tools made available for a request.
    case additionalTools(Schemas.AdditionalTools)

• Files reviewed: 21/23 changed files
• Comments generated: 0 new
• Review effort level: Lite