fix(protocols): accept return_token_budget for web_search tool

[Tobel158]

Description

Problem

web_search responses from upstream OpenAI include return_token_budget field, but SMG’s WebSearchTool schema rejects that unknown field, causing a 500 during ResponsesResponse deserialization. web_search_preview works fine because it does not include that field.

Solution

Added typed return_token_budget support to SMG’s non-preview web_search protocol model and regression tests for the upstream echo shape.

Changes

• Add return_token_budget support to the non-preview web_search Responses tool schema.
• Cover upstream ResponsesResponse.tools[] echo deserialization with a regression test.

Test Plan

After running SMG locally, register openai worker and perform a web_search request.
Previous experience (internal error):

 curl http://localhost:9999/v1/responses   -H "Content-Type: application/json"   -H "Authorization: Bearer sk-key"   -H "OpenAI-Project: 03262026_01"   -d '{
    "model": "gpt-5.1",
    "tools": [
      {
        "type": "web_search"
      }
    ],
    "input": "what is a positive news story from today?"
  }'
Response:
{"error":{"message":"Failed to deserialize upstream ResponsesResponse: unknown field `return_token_budget`, expected one of `filters`, `search_context_size`, `user_location`","type":"server_error","param":null,"code":"internal_error"}}

After Fix is added, successful response:

Checklist

• cargo +nightly fmt passes
• cargo clippy --all-targets --all-features -- -D warnings passes
• (Optional) Documentation updated
• (Optional) Please join us on Slack #sig-smg to discuss, review, and merge PRs

Summary by CodeRabbit

Release Notes

• New Features

  • Extended web search tool configuration with a new return_token_budget field to control token allocation behavior (supports default and unlimited settings).

• Tests

  • Added comprehensive test coverage for the new return_token_budget field to ensure proper serialization and deserialization.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR extends the WebSearchTool protocol struct with an optional return_token_budget field that accepts default or unlimited values. A new enum type defines the allowed values, and tests verify serialization preservation through round-trip deserialization.

Changes

Web Search Token Budget Support

Layer / File(s)	Summary
Type definition and contract crates/protocols/src/responses.rs	Adds WebSearchReturnTokenBudget enum with Default and Unlimited variants, and extends WebSearchTool struct with optional return_token_budget field using serde snake_case naming.
Testing and validation crates/protocols/tests/responses.rs	Updates existing test_web_search_tool_round_trip fixture to include return_token_budget: "default" and adds new test_web_search_response_tool_echo_accepts_return_token_budget to verify field preservation in serialization round-trips.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• lightseekorg/smg#1304: Also modifies WebSearchTool struct definition in crates/protocols/src/responses.rs for the web_search non-preview tool schema.

Suggested labels

protocols, tests

Suggested reviewers

• CatherineSue
• key4ng
• slin1237

Poem

🐰 A token budget field takes flight,
Default or unlimited, shining bright,
The protocol grows, test by test,
Web search now budgets its very best,
Round-trip serialized, all feels right! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding support for the return_token_budget field in the web_search tool schema.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/protocols/tests/responses.rs`:
- Around line 277-323: Add a unit test that covers the "unlimited" variant of
WebSearchReturnTokenBudget by creating a payload with "type": "web_search" and
"return_token_budget": "unlimited", deserializing it with serde_json::from_value
into ResponseTool, asserting it matches ResponseTool::WebSearch(_), and
asserting serde_json::to_value(&tool) equals the original payload (round-trip).
Place the new test (e.g. test_web_search_tool_return_token_budget_unlimited)
alongside test_web_search_response_tool_echo_accepts_return_token_budget and use
the same serde_json helpers to validate both deserialization and serialization
for the unlimited variant.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 20373078-59aa-41aa-8674-85e41656e6b0

📥 Commits

Reviewing files that changed from the base of the PR and between 253c79d and 7846e58.

📒 Files selected for processing (2)

• crates/protocols/src/responses.rs
• crates/protocols/tests/responses.rs

[gemini-code-assist]

Code Review

This pull request adds the "return_token_budget" field to the "WebSearchTool" struct and introduces the "WebSearchReturnTokenBudget" enum to support the new configuration options. Additionally, tests were updated and a new test case was added to verify the round-trip serialization of the new field. Feedback suggests clarifying the documentation for "return_token_budget" to ensure alignment with the OpenAI specification and distinguish it from "search_context_size".

[gemini-code-assist]

The term "context" in the comment for return_token_budget might be confusing as it overlaps with search_context_size. According to the OpenAI specification, return_token_budget refers to the budget for tokens returned in the search results, whereas search_context_size refers to the context budget. A more accurate description would be "Search-result token budget".

Suggested change

	/// Search-result context token budget. Spec enum: `"default" | "unlimited"`.
	/// Search-result token budget. Spec enum: "default" | "unlimited".

References

1. For protocol data structures that mirror an external API (e.g., OpenAI), prioritize alignment with the external specification over internal consistency.