fix: expand $ref references in JSON Schema for Gemini compatibility

[high726]

Summary

Gemini API rejects schemas containing $ref alongside other fields, causing errors like:

$ref 'QuestionOption' was set alongside unsupported fields. If a schema node has $ref set, then only description and default can be set alongside it

This fix adds $ref expansion in ProviderTransform.schema() before sending schemas to Gemini.

Fixes#12295

Changes

• Expands $ref references by inlining definitions from $defs/definitions
• Handles nested $ref references recursively
• Protects against circular references by returning { type: "object" }
• Preserves additional fields (like description) when expanding
• Removes $defs/definitions after expansion
• Only applies to Gemini models (does not affect other providers)

Files Changed

File	Change
packages/opencode/src/provider/transform.ts	Add expandRefs() function before sanitizeGemini()
packages/opencode/test/provider/transform.test.ts	Add 7 test cases for $ref expansion

Test Cases

• ✅ Expands simple $ref with $defs
• ✅ Expands $ref in array items
• ✅ Expands nested $ref references
• ✅ Handles circular $ref by returning simple object
• ✅ Expands definitions (legacy format)
• ✅ Preserves description when expanding $ref
• ✅ Does not expand $ref for non-Gemini providers

Related Issues

• Gemini API rejects MCP tool schemas with $defs references google-gemini/gemini-cli#13326 - Gemini API rejects MCP tool schemas with $defs references
• Error with Gemini models when MCP enabled #5832 - Error with Gemini models when MCP enabled
• Gemini Bad Request with Github Copilot #8417 - Gemini Bad Request with Github Copilot

Related PRs

• fix: apply schema transformation to MCP tools for Gemini compatibility #11968 - Applies schema transformation to MCP tools (this PR complements that fix by handling $ref)

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Potential Related PR Found

PR #11968 - "fix: apply schema transformation to MCP tools for Gemini compatibility"

Why it's related: According to the PR description (line 53), PR #11968 applies schema transformation to MCP tools and is directly complementary to this PR. The current PR (#12292) handles $ref expansion while #11968 handles the broader schema transformation for MCP tools with Gemini. These are related fixes addressing the same issue from different angles.

This appears to be the primary related PR. The other results are either the current PR itself or unrelated changes.

[github-actions]

Closing this pull request because it has had no updates for more than 60 days. If you plan to continue working on it, feel free to reopen or open a new PR.