Fix OpenAI API schema compatibility by flattening discriminated unions

[Copilot]

Fixes the OpenAI API error that occurred when using structured outputs with Pydantic discriminated unions. The CLI command treeagent --model-type openai "hello" was failing with:

Error code: 400 - {'error': {'message': "Invalid schema for response_format 'response': In context=('properties', 'response'), 'oneOf' is not permitted.", 'type': 'invalid_request_error', 'param': 'response_format', 'code': None}}

Problem

OpenAI's structured outputs API doesn't support oneOf or anyOf anywhere in JSON schemas, but Pydantic discriminated unions (like ModelResponse) generate schemas with oneOf at the root level:

{
  "oneOf": [
    {"$ref": "#/$defs/DecomposedResponse"},
    {"$ref": "#/$defs/ImplementedResponse"},
    {"$ref": "#/$defs/FollowUpResponse"},
    {"$ref": "#/$defs/FailedResponse"}
  ],
  "discriminator": {"propertyName": "type"}
}

The existing wrapping approach still placed oneOf inside properties.response, which OpenAI rejects.

Solution

Implemented a comprehensive schema flattening system that converts discriminated unions into OpenAI-compatible flat object schemas:

Key Changes

1. Schema Flattening: The new _flatten_discriminated_union() method converts oneOf schemas by:

   • Merging all possible properties from union alternatives into a single object schema
   • Creating an enum constraint for the discriminator field (type)
   • Preserving complex $defs references for nested types

2. Nullable Field Handling: Added _clean_oneof_anyof_recursive() to convert nullable fields from {"anyOf": [{"type": "string"}, {"type": "null"}]} to simple {"type": "string"} (optional)

3. Comprehensive Cleaning: Recursively removes all oneOf/anyOf structures throughout the entire schema tree

4. Response Processing: Updated _extract_response_from_openai_format() to work with flattened schemas (no unwrapping needed)

Before/After Example

Before (incompatible):

{
  "type": "object",
  "properties": {
    "response": {
      "oneOf": [...]  // ❌ OpenAI rejects this
    }
  }
}

After (compatible):

{
  "type": "object",
  "properties": {
    "type": {"type": "string", "enum": ["decomposed", "implemented", "follow_up_required", "failed"]},
    "content": {"type": "string"},
    "artifacts": {"type": "array", "items": {"type": "string"}},
    "subtasks": {"type": "array", "items": {"$ref": "#/$defs/Task"}},
    "follow_up_ask": {"$ref": "#/$defs/Task"},
    "error_message": {"type": "string"},
    "retryable": {"type": "boolean"}
  },
  "required": ["type"]
}

Testing

• All existing OpenAI accessor tests updated and passing
• Added comprehensive test case for full ModelResponse flattening
• Verified compatibility with all response types (ClarifierResponse, DesignerResponse, TesterResponse)
• End-to-end integration tests confirm the CLI scenario now works
• Non-union schemas continue to work unchanged (no regressions)

The fix maintains full backward compatibility while enabling TreeAgent to work seamlessly with OpenAI's structured outputs API.

Original prompt

$ treeagent --model-type openai "hello"
2025-09-28 11:43:35,938 [INFO] Executing root-task (REQUIREMENTS) using openai
2025-09-28 11:43:37,604 [ERROR] Task root-task failed: Error code: 400 - {'error': {'message': "Invalid schema for response_format 'response': In context=('properties', 'response'), 'oneOf' is not permitted.", 'type': 'invalid_request_error', 'param': 'response_format', 'code': None}}
Project Summary:
Completed Tasks: 0
In Progress Tasks: 0
Failed Tasks: 1
Queued Tasks: 0

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.