[Bug]: blender agent hangs in tool execution

[klkr1]

Quick check

• I've searched existing issues and didn't find a duplicate.
• This issue relates to Gaia Agent UI (gaia chat --ui).
• This issue relates to a CLI command (gaia ...) or the SDK.

GAIA version

0.17.6

What happened?

1. install blender mcp server (blender 4.5.2) and run it on port 9876
2. run gaia blender --example 1 --logging-level DEBUG
3. gaia hangs in tool execution, Executing animation runs, cannot be interrupted with "CTRL+C"

GAIA debug log:
[2026-05-08 22:11:26] | DEBUG | gaia.agents.base.agent._parse_llm_response | agent.py:1090 | [PARSE] Valid JSON response
[2026-05-08 22:11:26] | DEBUG | gaia.agents.base.agent._process_query_impl | agent.py:2593 | Parsed response: {'thought': 'The user wants to clear the current Blender scene to start fresh. This is a simple single-step operation using the clear_scene function.', 'goal': 'Remove all objects from the current Blender scene', 'tool': 'clear_scene', 'tool_args': {}}
🧠 Thought: The user wants to clear the current Blender scene to start fresh. This is a simple single-step operation
using the clear_scene function.
🎯 Goal: Remove all objects from the current Blender scene
[2026-05-08 22:11:26] | DEBUG | gaia.agents.base.agent._process_query_impl | agent.py:2832 | Tool call detected: clear_scene with args {}

🔧 Executing operation
Tool: clear_scene
[2026-05-08 22:11:26] | DEBUG | gaia.agents.base.agent._execute_tool | agent.py:1354 | Executing tool clear_scene with args: {}
⠹ Executing clear_scene

Blender MCP server log:
SimpleMCP server started on localhost:9876
Connected to client: ('127.0.0.1', 65360)
Client handler started
Client disconnected
Client handler stopped
Connected to client: ('127.0.0.1', 64412)
Client handler started
Executing handler for execute_code

----- EXECUTING CODE IN BLENDER -----

import bpy

Select all objects

bpy.ops.object.select_all(action='SELECT')

Delete all selected objects

bpy.ops.object.delete()

Return info about the cleared scene

object_count = len(bpy.context.scene.objects)
result = {
"object_count": object_count,
"message": "Scene cleared successfully"
}

print("Scene cleared successfully")

----- CODE EXECUTION OUTPUT -----
Scene cleared successfully
----- CODE EXECUTION COMPLETE -----
----- RETURNED RESULT -----
{'object_count': 0, 'message': 'Scene cleared successfully'}

Handler execution complete

What did you expect to happen?

gaia blender should finish the tool execution

Acceptance criteria

• 'gaia blender' should finish cleanly after tool execution

Environment

OS: Windows 11 25H2
CPU: AMD Ryzen 7 3700X
GPU: AMD Radeon RX 9060 XT
Lemonade: 10.3.0
Installer: Gaia UI and uv
Blender 4.5.2

[github-actions]

Thanks for the detailed report and logs — those server-side traces made this very easy to pinpoint. 🟡

Root cause

This is a regression in the Blender MCP client, not the server. The hang is in src/gaia/mcp/blender_mcp_client.py:62-68:

chunks = []
while True:
    chunk = sock.recv(65536)
    if not chunk:
        break
    chunks.append(chunk)
response = b"".join(chunks).decode("utf-8")

The client reads in a loop and only exits when recv() returns empty, which on a TCP socket only happens when the server sends FIN (i.e. closes its end).

But the Blender server (src/gaia/mcp/blender_mcp_server.py:113-177) was designed to keep the connection open and accept further commands on the same socket — its _handle_client loops on client.recv(8192) until the client disconnects. So after clear_scene's response is sent, the GAIA client sits forever in recv() waiting for bytes that will never come, while the server happily sits in its own recv() waiting for the next command. Classic deadlock.

This explains exactly what your logs show:

• The first connection (port 65360) closes cleanly — that's an unrelated probe/test.
• The second connection (port 64412) executes clear_scene successfully, prints Handler execution complete, sends the JSON response — and then both ends just sit there.

When it was introduced

Pre-#428, the client used a single recv(65536) (one-shot read, returns whatever's available) and worked correctly with the server's persistent-connection design. PR #428 (b2ace80d, March 2026) changed it to the chunk-until-EOF loop above, which is incompatible with this server's protocol. Versions before 0.16.x shouldn't exhibit this.

Fix direction

The cleanest fix is to make the client parse JSON incrementally and break out of the read loop as soon as a complete response has been decoded — same approach the server already uses on its side (blender_mcp_server.py:128-166). Roughly:

buffer = b""
while True:
    chunk = sock.recv(65536)
    if not chunk:
        break
    buffer += chunk
    try:
        parsed_response = json.loads(buffer.decode("utf-8"))
        break  # got a complete JSON response
    except json.JSONDecodeError:
        continue  # keep reading

A short sock.settimeout(...) wouldn't hurt either, so a misbehaving server can't hang the agent indefinitely.

Workaround until a fix lands

If you need to unblock yourself today, you can locally patch send_command in src/gaia/mcp/blender_mcp_client.py to revert to a single-shot read or drop in the incremental-parse loop above. There isn't a user-side workaround via flags — the client always uses this code path.

Next steps

I'll leave this for a maintainer to triage and fix; the bug is well-localized and the patch is small. cc @kovtcharov-amd — happy to send a PR if that helps.

References:

• Client: src/gaia/mcp/blender_mcp_client.py:46-92
• Server (persistent-connection handler): src/gaia/mcp/blender_mcp_server.py:113-177
• BlenderAgent guide: docs/guides/blender.mdx