[Bugfix] Fix tool call arguments parsed as content/reasoning in harmony streaming

[jfrery]

Purpose

Fix streaming tool calling with openai/gpt-oss-120b. Tool call arguments were not being parsed properly in streaming mode -- they ended up in reasoning/content instead of being routed as proper tool_calls deltas.

The root cause is that extract_harmony_streaming_delta used a per-token-group heuristic that tracked tool call transitions via prev_recipient within a single chunk. This broke when:

• The model's channel transition from analysis to commentary with functions.* recipient arrived in multi-token batches, causing tool call JSON to be dumped into reasoning_content instead of structured tool_calls ([Bug]: Streaming tool call randomly failed when using gpt-oss-120b/20b #27641)
• stream_interval > 1 caused multiple messages to complete in one yield, losing tool call arguments or emitting arguments: "{}" ([Bug]: --stream-interval > 1 causes tool call arguments to be empty/lost #31501)
• The if not cur_channel and delta_text: cur_channel = "final" fallback misrouted reasoning tokens into content

This PR replaces the per-token-group heuristic with parser-level message diffing via a persistent HarmonyStreamingState dataclass that tracks emitted message count, tool call indices, and in-progress message state across chunks.

Fixes #27641
Fixes #31501
Related (closed): #28635, #30099, #25560
Related (open): #30222, #30204

Test Plan

python -m pytest tests/entrypoints/openai/test_serving_chat_stream_harmony.py -v

Test Result

18 passed

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.
• (Optional) Release notes update.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors.

You ask your reviewers to trigger select CI tests on top of fastcheck CI.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

🚀

[gemini-code-assist]

Code Review

This pull request refactors the harmony streaming delta extraction to use a more robust parser-level state diffing mechanism, replacing the previous per-token heuristic. The introduction of HarmonyStreamingState to persist state across chunks is a solid approach that should fix the described issues with tool call indexing and argument streaming across arbitrary chunk boundaries. The changes in stream_harmony.py are well-structured, and the tests have been updated thoroughly to cover the new implementation. I have one concern regarding a potential issue in serving.py where a remnant of the old logic might lead to incorrect behavior.

[mergify]

Hi @jfrery, the pre-commit checks have failed. Please run:

uv pip install pre-commit
pre-commit install
pre-commit run --all-files

Then, commit the changes and push to your branch.

For future commits, pre-commit will run automatically on changed files before each commit.

Tip

Is mypy or markdownlint failing?

mypy and markdownlint are run differently in CI. If the failure is related to either of these checks, please use the following commands to run them locally:

# For mypy (substitute "3.10" with the failing version if needed)
pre-commit run --hook-stage manual mypy-3.10
# For markdownlint
pre-commit run --hook-stage manual markdownlint

[ehfd]

CC @bbrowning @chaunceyjiang

[mergify]

Hi @jfrery, the pre-commit checks have failed. Please run:

uv pip install pre-commit
pre-commit install
pre-commit run --all-files

Then, commit the changes and push to your branch.

For future commits, pre-commit will run automatically on changed files before each commit.

Tip

Is mypy or markdownlint failing?

mypy and markdownlint are run differently in CI. If the failure is related to either of these checks, please use the following commands to run them locally:

# For mypy (substitute "3.10" with the failing version if needed)
pre-commit run --hook-stage manual mypy-3.10
# For markdownlint
pre-commit run --hook-stage manual markdownlint

[bbrowning]

For harmony models, won't this throw an exception (that we then log below) because we're not passing token ids into extract_tool_calls? See

vllm/vllm/tool_parsers/openai_tool_parser.py

Lines 40 to 43 in cc0d565

	if token_ids is None:
	raise NotImplementedError(
	"OpenAIToolParser requires token IDs and does not support text-based extraction." # noqa: E501
	)

[jfrery]

Good catch, you're right. Fixed by forwarding token_ids=token_ids. Added # type: ignore to match the non-streaming path at L1514

[bbrowning]

This should be DeltaMessage(reasoning=reasoning) since this is meant to emit reasoning, right?

[jfrery]

Indeed, fixed now uses DeltaMessage(reasoning=reasoning)

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @jfrery.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[ikaadil]

Hi @jfrery and @bbrowning do you have any update about this PR?