fix(agents): offload blocking filesystem IO in the custom-agent router off the event loop (#3457)

* fix(agents): offload blocking filesystem IO in delete_agent off the event loop

delete_agent is an async route handler but resolved the agent directory (Paths.base_dir -> Path.resolve), probed it (Path.exists), and removed it (shutil.rmtree) directly on the event loop, blocking it for the duration of every delete. Surfaced by 'make detect-blocking-io'.

Move the resolve/exists/rmtree sequence into a sync helper run via asyncio.to_thread, mapping its outcome back to the existing 404/409/500 responses (behavior unchanged). Adds a tests/blocking_io/ regression anchor under the strict Blockbuster gate, mirroring test_skills_load.py (#1917).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(agents): offload blocking filesystem IO in create_agent_endpoint too

Like delete_agent, the async create_agent_endpoint resolved and created the agent directory and wrote config.yaml + SOUL.md (with rmtree cleanup on failure) directly on the event loop. Move the whole create-or-409 sequence into a sync helper run via asyncio.to_thread; behavior is unchanged (201 / 409 / 500). Extends the blocking_io regression anchor to cover create as well as delete and renames it to test_agents_router.py.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: ly-wang19 <ly-wang19@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

backend/tests/blocking_io/test_agents_router.py

@@ -0,0 +1,64 @@
+"""Regression anchors: the custom-agent router must not block the event loop.
+
+``app.gateway.routers.agents.create_agent_endpoint`` and ``delete_agent`` are
+async route handlers that resolve the agent directory (``Paths.base_dir`` calls
+``Path.resolve``), probe it (``Path.exists``), and create/remove it (``mkdir``,
+config/SOUL writes, ``shutil.rmtree``) — all blocking IO. Both offload that work
+via ``asyncio.to_thread``; if any of it regresses back onto the event loop, the
+strict Blockbuster gate raises ``BlockingError`` and these tests fail.
+
+Imports live at module scope so the one-time FastAPI app construction (which
+reads files while building OpenAPI schemas) happens at collection time, not on
+the event loop under test. Test-side path resolution is itself offloaded with
+``asyncio.to_thread`` (matching ``test_uploads_middleware``) so only the
+handlers' own filesystem access is exercised on the loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from app.gateway.routers.agents import AgentCreateRequest, create_agent_endpoint, delete_agent
+from deerflow.config.agents_api_config import load_agents_api_config_from_dict
+from deerflow.config.paths import get_paths
+from deerflow.runtime.user_context import get_effective_user_id
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_create_agent_does_not_block_event_loop(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setenv("DEER_FLOW_HOME", str(tmp_path))
+    monkeypatch.setattr("deerflow.config.paths._paths", None)
+    load_agents_api_config_from_dict({"enabled": True})
+    try:
+        response = await create_agent_endpoint(AgentCreateRequest(name="loop-make-agent", soul="You are a test agent."))
+        assert response is not None
+
+        user_id = get_effective_user_id()
+        # test-side check (resolution offloaded; not exercised on the loop)
+        agent_dir = await asyncio.to_thread(get_paths().user_agent_dir, user_id, "loop-make-agent")
+        assert await asyncio.to_thread((agent_dir / "config.yaml").exists)
+    finally:
+        load_agents_api_config_from_dict({})
+
+
+async def test_delete_agent_does_not_block_event_loop(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setenv("DEER_FLOW_HOME", str(tmp_path))
+    monkeypatch.setattr("deerflow.config.paths._paths", None)
+    load_agents_api_config_from_dict({"enabled": True})
+    try:
+        user_id = get_effective_user_id()
+        user_id = get_effective_user_id()
+        # test-side seeding (resolution offloaded; not exercised on the loop)
+        agent_dir = await asyncio.to_thread(get_paths().user_agent_dir, user_id, "loop-test-agent")
+        await asyncio.to_thread(agent_dir.mkdir, parents=True, exist_ok=True)
+        await asyncio.to_thread((agent_dir / "config.yaml").write_text, "name: loop-test-agent\n", encoding="utf-8")
+
+        await delete_agent("loop-test-agent")
+
+        assert not await asyncio.to_thread(agent_dir.exists)
+    finally:
+        load_agents_api_config_from_dict({})