[himanshumehta]

Fixes the receive-task crash from #7151, which @davidzhao linked as the root cause of #5742.

Gemini Live can send one LiveServerMessage that carries both a terminal server_content (turn_complete=True) and a tool_call. _recv_task handles server_content first. On turn_complete it calls _mark_current_generation_done(), which closes function_ch. _handle_tool_calls then calls send_nowait on the closed channel, which raises ChanClosed. That ends the receive task, so the session reconnects and the tool call is lost. For an end_call tool, that means the call is never ended.

This takes the shape @longcw suggested in his review of #7164:

• the per-message dispatch moves out of _recv_task into _handle_live_server_message(response);
• the two handlers no longer finalize the generation themselves;
• the loop finalizes once, after both handlers, if turn_complete or tool_call is present.

if response.server_content:
    self._handle_server_content(response.server_content)
if response.tool_call:
    self._handle_tool_calls(response.tool_call)
if ((sc := response.server_content) and sc.turn_complete) or response.tool_call:
    self._mark_current_generation_done()

A tool call on its own still ends the generation, as on main. That part has to stay. AgentActivity sends tool outputs only after the generation's streams close (L4671, then L4942). BLOCKING is the server default on every model except Gemini 3.8. If Gemini waits for the tool output before it ends the turn, which #6285's timed-drain design suggests, then holding the generation open until turn_complete would stall every tool call. I haven't confirmed that against live Gemini, so this PR keeps main's behaviour for a lone tool call. test_lone_tool_call_finalizes_generation pins this.

Credit and prior work:

• fix(google): deliver tool calls before combined turn completion #7164 by @noooooooookro. It found the same fix with a defer_completion flag. This PR implements longcw's review suggestion on it. fix(google): deliver tool calls before combined turn completion #7164 has had no activity since 2026-09-09, and its CLA is unsigned.
• fix(google): drain realtime audio after tool calls #6285 by @Anrahya. It drains audio after tool calls on a timer, with no activity since 2026-07-01. This PR does not take that approach.

If either author would rather continue their PR, I'm happy to close this and offer the tests there.

Proof of concept: the real receive loop on main vs this PR

poc_combined_message.py builds a real RealtimeSession and calls its real _recv_task with a fake Gemini stream that sends two messages:

1. one audio chunk;
2. one message carrying turn_complete=True and tool_call(end_call).

Version	Tool calls reaching function_stream	Receive task	Session
main c2b2f5cbd	none: end_call is lost	raises ChanClosed	reconnect forced
this PR	['end_call']	no error	no reconnect

Test results

• tests/test_plugin_google_realtime.py: 77 passed. There are 3 new tests:
  • test_combined_turn_complete_and_tool_call_finalizes_once: the call is delivered, the generation finalizes exactly once, and nothing raises;
  • test_lone_tool_call_finalizes_generation: the guard against the stall;
  • test_tool_call_is_recorded_after_the_turn_it_ends: chat_ctx keeps main's order of user, assistant, then function_call. Devin caught this regression in the first commit.
• _handle_tool_calls now returns its calls, and the loop inserts them into chat_ctx after finalizing.
• Existing tests that called _handle_tool_calls / _handle_server_content directly and expected them to finalize now go through _handle_live_server_message. Their assertions are unchanged.
• Mutation checks:

Mutation	Result
Drop or response.tool_call from the loop	test_lone_tool_call_finalizes_generation fails
Put _mark_current_generation_done() back in _handle_server_content	test_combined_turn_complete_and_tool_call_finalizes_once fails
Insert the tool calls into chat_ctx before finalizing	test_tool_call_is_recorded_after_the_turn_it_ends fails

• ruff format --check, ruff check and scripts/check_types.py (748 files) are clean.
• Full --unit --audio_eot run: 2 failures in tests/test_room.py (test_joins_after, test_published_after). These are FFI connect timeouts in a file this PR doesn't touch, and both pass when re-run.

Repro (about 15 s)

From a checkout of this branch, run PYTHON="uv run python" bash poc.sh, using poc.sh. It:

• runs the PoC against main's realtime_api.py and against this PR's;
• runs the test file;
• applies each mutation in turn.

It restores the file when it exits.

main c2b2f5cbd generations=1  tool calls delivered=[]  receive-task error=ChanClosed  reconnect=yes
this PR        generations=1  tool calls delivered=['end_call']  receive-task error=None  reconnect=no

Diagrams

flowchart TD
    A[LiveServerMessage] --> B{response.server_content present?}
    B -->|yes| C[_handle_server_content - no self-finalize]
    B -->|no| D
    C --> D{response.tool_call present?}
    D -->|yes| E[_handle_tool_calls - no self-finalize]
    D -->|no| F
    E --> F{server_content.turn_complete OR tool_call present?}
    F -->|yes| G[_mark_current_generation_done - exactly once]
    F -->|no| H[generation stays open]
    G --> I[function_ch / message_ch / text_ch / audio_ch closed]

Loading

sequenceDiagram
    participant Gemini
    participant RecvTask as _recv_task
    participant SC as _handle_server_content
    participant TC as _handle_tool_calls
    participant Gen as generation channels
    participant AA as AgentActivity

    Gemini->>RecvTask: LiveServerMessage(server_content(turn_complete=True), tool_call)
    alt base c2b2f5cbd6 (bug #7151)
        RecvTask->>SC: handle server_content
        SC->>Gen: _mark_current_generation_done() closes function_ch
        RecvTask->>TC: handle tool_call
        TC->>Gen: function_ch.send_nowait(call)
        Gen-->>TC: ChanClosed - recv task crashes, call lost, reconnect forced
    else R1 fix (this commit)
        RecvTask->>SC: handle server_content, no finalize
        RecvTask->>TC: handle tool_call, no finalize
        TC->>Gen: function_ch.send_nowait(call) - ok, channel still open
        RecvTask->>Gen: _mark_current_generation_done() once, after both handlers
        Gen->>AA: all 4 channels close cleanly; call delivered; AgentActivity awaits exe_task, sends tool output via update_chat_ctx
    end

Loading

Scope

• What this fixes: the combined-message crash (Google realtime: a response carrying both a terminal server_content and a tool_call kills the receive task #7151). That is the root cause davidzhao pointed to for Gemini realtime: trailing audio truncated when a tool call ends the turn #5742.
• Not fixed: audio that Gemini sends in a later message, after a tool call. On main and in this PR, that audio starts a second generation. I haven't changed this, because keeping the first generation open could stall BLOCKING tools, as described above. It needs a capture from a live Gemini session to settle.
• What the evidence covers: a fake Gemini stream driving the real session code. I did not run against live Gemini.

cc @davidzhao @longcw

[devin-ai-integration]

Devin Review found 2 potential issues.

[devin-ai-integration]

🟡 New message handler lacks required documentation

_handle_live_server_message has no docstring, despite the repository's requirement to document every new method.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[himanshumehta]

I'm leaving this one as it is. AGENTS.md asks for Google-style docstrings where a docstring is written, and the private per-message handlers in this file don't have one: _handle_server_content, _handle_tool_calls, _handle_usage_metadata and _handle_go_away. _handle_live_server_message is the same kind of method, so it follows that convention. Its behaviour is pinned by test_combined_turn_complete_and_tool_call_finalizes_once, test_lone_tool_call_finalizes_generation and test_tool_call_is_recorded_after_the_turn_it_ends.

[longcw]

lgtm. something nit:

[longcw]

nit: return the list of llm.FunctionCall instead of tuple of str?

[himanshumehta]

Done in b1f2501. _handle_tool_calls now returns list[llm.FunctionCall].

One thing came up while doing it. ChatContext.insert orders items by created_at, and a FunctionCall built inside _handle_tool_calls is created before _mark_current_generation_done adds the assistant message. Inserting it as-is put the call ahead of the message, and test_tool_call_is_recorded_after_the_turn_it_ends went red:

FAILED tests/test_plugin_google_realtime.py::test_tool_call_is_recorded_after_the_turn_it_ends
1 failed, 77 passed

So the loop inserts each call with the insertion time:

for call in calls:
    self._chat_ctx.insert(call.model_copy(update={"created_at": time.time()}))

The call sent on function_ch is still a separate instance, as on main.

Tests:

• New test_handle_tool_calls_returns_the_function_calls. It failed on 776dbb6 (assert all(isinstance(call, llm.FunctionCall) ...)) and passes now.
• uv run pytest tests/test_plugin_google_realtime.py tests/test_realtime_*.py: 255 passed.
• ruff check, ruff format --check and mypy -p livekit.plugins.google: clean.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}