feat: prewarm thought engine node on bridge startup

server.py

@@ -13,9 +13,11 @@ and visualize reasoning trees through this bridge.
 ==========================================================================
 """
 
+import asyncio
 import os
 import json
 import httpx
+from contextlib import asynccontextmanager
 from typing import Optional
 from mcp.server.mcpserver import MCPServer
 from starlette.applications import Starlette
@@ -30,6 +32,44 @@ NODE_URL = os.getenv(
 )
 
 mcp = MCPServer("thought-engine-bridge")
+_node_prewarm_started = False
+_node_prewarm_task: asyncio.Task | None = None
+
+
+async def _prewarm_node() -> None:
+    """Best-effort bounded wake/readiness probe for the downstream Node."""
+    for attempt in range(3):
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(f"{NODE_URL}/health")
+            if response.status_code == 200:
+                payload = response.json()
+                if payload.get("status") == "ok":
+                    return
+        except Exception:
+            pass
+
+        if attempt < 2:
+            await asyncio.sleep(0.25)
+
+
+@asynccontextmanager
+async def _bridge_lifespan(app: Starlette, modern_lifespan):
+    global _node_prewarm_started, _node_prewarm_task
+
+    async with modern_lifespan(app):
+        if not _node_prewarm_started:
+            _node_prewarm_started = True
+            _node_prewarm_task = asyncio.create_task(_prewarm_node())
+        try:
+            yield
+        finally:
+            if _node_prewarm_task is not None and not _node_prewarm_task.done():
+                _node_prewarm_task.cancel()
+                try:
+                    await _node_prewarm_task
+                except asyncio.CancelledError:
+                    pass
 
 
 # ── HTTP Helper ────────────────────────────────────────────────
@@ -397,7 +437,7 @@ def build_app() -> Starlette:
             *modern.routes,
             *legacy.routes,
         ],
-        lifespan=modern.router.lifespan_context,
+        lifespan=lambda app: _bridge_lifespan(app, modern.router.lifespan_context),
     )
 
 

tests/test_modern_mcp.py

@@ -132,7 +132,7 @@ async def test_thought_node_identity_preserves_node_rest_mapping() -> None:
                     payload = json.loads(result.content[0].text)
                     assert client.protocol_version == "2026-07-28"
                     assert payload == EXPECTED_IDENTITY
-    assert calls == [("GET", "/"), ("GET", "/")]
+    assert calls == [("GET", "/health"), ("GET", "/"), ("GET", "/")]
 
 
 @pytest.mark.asyncio
@@ -189,10 +189,15 @@ async def test_modern_remains_available_after_legacy_disconnect() -> None:
 
 
 @pytest.mark.asyncio
-async def test_health_is_bridge_local_and_advertises_both_transports() -> None:
+async def test_health_is_bridge_local_and_advertises_both_transports(monkeypatch) -> None:
     bridge = _load_bridge()
     node_calls = 0
 
+    async def no_prewarm() -> None:
+        return None
+
+    monkeypatch.setattr(bridge, "_prewarm_node", no_prewarm)
+
     class FailingAsyncClient:
         async def __aenter__(self):
             nonlocal node_calls
@@ -202,7 +207,7 @@ async def test_health_is_bridge_local_and_advertises_both_transports() -> None:
         async def __aexit__(self, *args):
             return None
 
-    bridge.httpx.AsyncClient = FailingAsyncClient
+    monkeypatch.setattr(bridge.httpx, "AsyncClient", FailingAsyncClient)
     async with _serve(bridge.app) as port:
         async with httpx2.AsyncClient() as client:
             response = await client.get(f"http://127.0.0.1:{port}/health")
@@ -212,3 +217,68 @@ async def test_health_is_bridge_local_and_advertises_both_transports() -> None:
     assert payload["streamable_http_endpoint"] == "/mcp"
     assert payload["sse_endpoint"] == "/sse"
     assert node_calls == 0
+
+
+@pytest.mark.asyncio
+async def test_bridge_lifespan_starts_one_nonblocking_node_prewarm_per_process() -> None:
+    bridge = _load_bridge()
+    started = 0
+    blocker = asyncio.Event()
+
+    async def fake_prewarm() -> None:
+        nonlocal started
+        started += 1
+        await blocker.wait()
+
+    bridge._prewarm_node = fake_prewarm
+
+    first_app = bridge.build_app()
+    async with first_app.router.lifespan_context(first_app):
+        await asyncio.sleep(0)
+        assert started == 1
+        assert not blocker.is_set()
+
+    second_app = bridge.build_app()
+    async with second_app.router.lifespan_context(second_app):
+        await asyncio.sleep(0)
+        assert started == 1
+
+    blocker.set()
+
+
+@pytest.mark.asyncio
+async def test_node_prewarm_retries_health_until_ready() -> None:
+    calls = 0
+
+    async def node_health(request: Request) -> JSONResponse:
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            return JSONResponse({"status": "warming"}, status_code=503)
+        return JSONResponse({"status": "ok"})
+
+    node_app = Starlette(routes=[Route("/health", node_health)])
+    async with _serve(node_app) as node_port:
+        bridge = _load_bridge()
+        bridge.NODE_URL = f"http://127.0.0.1:{node_port}"
+        await bridge._prewarm_node()
+
+    assert calls == 2
+
+
+@pytest.mark.asyncio
+async def test_node_prewarm_exhaustion_is_best_effort() -> None:
+    calls = 0
+
+    async def node_health(request: Request) -> JSONResponse:
+        nonlocal calls
+        calls += 1
+        return JSONResponse({"status": "warming"}, status_code=503)
+
+    node_app = Starlette(routes=[Route("/health", node_health)])
+    async with _serve(node_app) as node_port:
+        bridge = _load_bridge()
+        bridge.NODE_URL = f"http://127.0.0.1:{node_port}"
+        await bridge._prewarm_node()
+
+    assert calls == 3