[vasspilka]

Description

The OpenAI Responses API decoder emits a builtin_tool_started meta chunk when a server-side builtin call (for example web_search_call) is added to the output. StreamServer used it only to record OTel builtin-tool timing, then dropped it from the public stream. Consumers saw the call only when it finished, so they had no way to show that a web search was in progress.

This keeps the chunk on the public stream as:

%ReqLLM.StreamChunk{
  type: :meta,
  metadata: %{builtin_tool_started: %{id: "ws_1", name: "web_search_call", index: 0}}
}

It's the counterpart of the existing finished builtin :tool_call chunk, which carries the same metadata.id.

• The telemetry-internal started_at_unix_nano timestamp is still stripped before the chunk reaches consumers.
• builtin_tool_started stays out of the merged stream metadata returned by await_metadata/2.
• OTel builtin_tool_timing is unchanged.
• guides/openai.md now documents the chunk next to the existing builtin tool call notes.

Type of Change

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Breaking Changes

None intended. Streams that use OpenAI Responses builtin tools now include one extra :meta chunk per builtin call. Consumers that match only on :content, :thinking, or :tool_call chunks are unaffected. A consumer that treats every :meta chunk as usage or finish metadata will now also see this one.

Testing

• Tests pass (mix test): REQ_LLM_FIXTURES_MODE=replay mix test, 5345 tests, 0 failures, 11 skipped
• Quality checks pass (mix quality): format, compile --warnings-as-errors, credo --strict, dialyzer (0 errors)

test/req_llm/stream_server/telemetry_test.exs now asserts that the public start chunk carries only id/name/index, and that builtin_tool_started doesn't leak into the merged metadata. The test also still checks the existing builtin timing behavior.

Checklist

• My code follows the project's style guidelines
• I have updated the documentation accordingly
• I have added tests that prove my fix/feature works
• All new and existing tests pass
• My commits follow conventional commit format
• I have NOT edited CHANGELOG.md (it is auto-generated by git_ops)

Related Issues

None.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}