bamboo-coding 0.1.0__py3-none-any.whl

controller/app/schemas/__init__.py

@@ -0,0 +1,23 @@
+from .agent_messages import (
+    AgentRegisterMessage,
+    ClientStatusMessage,
+    RegisterRequestMessage,
+    TaskEventMessage,
+    TaskMessage,
+    TaskQueryMessage,
+    TaskQueryResultMessage,
+    TaskResultMessage,
+)
+from .public import PublicRepositorySummary
+
+__all__ = [
+    "AgentRegisterMessage",
+    "ClientStatusMessage",
+    "PublicRepositorySummary",
+    "RegisterRequestMessage",
+    "TaskEventMessage",
+    "TaskMessage",
+    "TaskQueryMessage",
+    "TaskQueryResultMessage",
+    "TaskResultMessage",
+]

controller/app/schemas/agent_messages.py

@@ -0,0 +1,21 @@
+from shared.protocol import (
+    AgentRegisterMessage,
+    ClientStatusMessage,
+    RegisterRequestMessage,
+    TaskEventMessage,
+    TaskMessage,
+    TaskQueryMessage,
+    TaskQueryResultMessage,
+    TaskResultMessage,
+)
+
+__all__ = [
+    "AgentRegisterMessage",
+    "ClientStatusMessage",
+    "RegisterRequestMessage",
+    "TaskEventMessage",
+    "TaskMessage",
+    "TaskQueryMessage",
+    "TaskQueryResultMessage",
+    "TaskResultMessage",
+]

controller/app/schemas/public.py

@@ -0,0 +1,3 @@
+from shared.protocol import PublicRepositorySummary, PublicRootSummary
+
+__all__ = ["PublicRepositorySummary", "PublicRootSummary"]

controller/app/services/agents.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+import json
+from uuid import uuid4
+
+from controller.app.core.errors import AgentApprovalError
+from controller.app.db.session import ControllerDatabase
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _decode_agent(row) -> dict | None:
+    if row is None:
+        return None
+    payload = dict(row)
+    payload["client_info"] = json.loads(payload.pop("client_info_json"))
+    return payload
+
+
+class AgentService:
+    def __init__(self, database: ControllerDatabase):
+        self.database = database
+
+    def create_registration_request(self, client_id: str) -> dict:
+        now = _now()
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM agents WHERE client_id = ?", (client_id,)).fetchone()
+            if row is None:
+                agent_id = str(uuid4())
+                conn.execute(
+                    "INSERT INTO agents (agent_id, client_id, token, approval_status, status, client_info_json, created_at, updated_at, last_seen_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                    (agent_id, client_id, None, "pending", "pending", json.dumps({}), now, now, None),
+                )
+                row = conn.execute("SELECT * FROM agents WHERE client_id = ?", (client_id,)).fetchone()
+            return _decode_agent(row)
+
+    def approve_registration(self, client_id: str, token: str) -> dict:
+        now = _now()
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM agents WHERE client_id = ?", (client_id,)).fetchone()
+            if row is None:
+                self.create_registration_request(client_id)
+            conn.execute(
+                "UPDATE agents SET token = ?, approval_status = ?, updated_at = ? WHERE client_id = ?",
+                (token, "approved", now, client_id),
+            )
+            row = conn.execute("SELECT * FROM agents WHERE client_id = ?", (client_id,)).fetchone()
+            return _decode_agent(row)
+
+    def approve_agent(self, agent_id: str, token: str) -> dict:
+        now = _now()
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM agents WHERE agent_id = ?", (agent_id,)).fetchone()
+            if row is None:
+                raise AgentApprovalError(f"Unknown agent: {agent_id}")
+            conn.execute(
+                "UPDATE agents SET token = ?, approval_status = ?, updated_at = ? WHERE agent_id = ?",
+                (token, "approved", now, agent_id),
+            )
+            row = conn.execute("SELECT * FROM agents WHERE agent_id = ?", (agent_id,)).fetchone()
+            return _decode_agent(row)
+
+    def register_connection(self, client_id: str, token: str, client_info: dict) -> dict:
+        now = _now()
+        with self.database.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM agents WHERE client_id = ? AND token = ?",
+                (client_id, token),
+            ).fetchone()
+            if row is None or row["approval_status"] != "approved":
+                raise AgentApprovalError(f"Agent {client_id} is not approved")
+            conn.execute(
+                "UPDATE agents SET status = ?, client_info_json = ?, updated_at = ?, last_seen_at = ? WHERE client_id = ?",
+                ("connected", json.dumps(client_info), now, now, client_id),
+            )
+            row = conn.execute("SELECT * FROM agents WHERE client_id = ?", (client_id,)).fetchone()
+            return _decode_agent(row)
+
+    def get_agent_by_token(self, token: str) -> dict | None:
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM agents WHERE token = ?", (token,)).fetchone()
+            return _decode_agent(row)
+
+    def get_agent_by_client_id(self, client_id: str) -> dict | None:
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM agents WHERE client_id = ?", (client_id,)).fetchone()
+            return _decode_agent(row)
+
+    def get_agent_by_id(self, agent_id: str) -> dict | None:
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM agents WHERE agent_id = ?", (agent_id,)).fetchone()
+            return _decode_agent(row)
+
+    def list_agents(self) -> list[dict]:
+        with self.database.connection() as conn:
+            rows = conn.execute("SELECT * FROM agents ORDER BY created_at ASC").fetchall()
+            return [_decode_agent(row) for row in rows]
+
+    def mark_disconnected(self, agent_id: str) -> None:
+        now = _now()
+        with self.database.connection() as conn:
+            conn.execute(
+                "UPDATE agents SET status = ?, updated_at = ? WHERE agent_id = ?",
+                ("disconnected", now, agent_id),
+            )

controller/app/services/registrations.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from controller.app.services.agents import AgentService
+from shared.protocol import RegisterRequestMessage
+
+
+class RegistrationService:
+    def __init__(self, agents: AgentService):
+        self.agents = agents
+
+    def ensure_pending(self, client_id: str) -> RegisterRequestMessage:
+        self.agents.create_registration_request(client_id)
+        return RegisterRequestMessage(approved=False, client_id=client_id, message="pending approval")
+
+    def approve(self, client_id: str, token: str) -> RegisterRequestMessage:
+        self.agents.approve_registration(client_id=client_id, token=token)
+        return RegisterRequestMessage(approved=True, client_id=client_id, token=token, message="approved")

controller/app/services/repositories.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+import os
+
+from controller.app.core.errors import RepositoryNotFoundError
+from controller.app.db.session import ControllerDatabase
+from shared.protocol import PublicRepositorySummary, PublicRootSummary
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _normalize_path(path_value: str) -> str:
+    return str(Path(path_value).expanduser().resolve())
+
+
+class RepositoryService:
+    def __init__(self, database: ControllerDatabase):
+        self.database = database
+
+    def upsert_repository_binding(self, agent_id: str, repo_id: str, name: str, path: str, status: str) -> dict:
+        now = _now()
+        normalized_path = _normalize_path(path)
+        storage_key = _normalize_path(repo_id) if repo_id else normalized_path
+        with self.database.connection() as conn:
+            conn.execute(
+                """
+                INSERT INTO repositories (repo_id, agent_id, name, path, status, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(repo_id) DO UPDATE SET
+                    agent_id = excluded.agent_id,
+                    name = excluded.name,
+                    path = excluded.path,
+                    status = excluded.status,
+                    updated_at = excluded.updated_at
+                """,
+                (storage_key, agent_id, name, normalized_path, status, now, now),
+            )
+            return self.get_repository_binding(storage_key)
+
+    def upsert_root_binding(self, agent_id: str, path: str, name: str, status: str) -> dict:
+        normalized_path = _normalize_path(path)
+        return self.upsert_repository_binding(agent_id=agent_id, repo_id=normalized_path, name=name, path=normalized_path, status=status)
+
+    def list_public_repositories(self) -> list[PublicRepositorySummary]:
+        return self.list_public_roots()
+
+    def list_public_roots(self) -> list[PublicRootSummary]:
+        with self.database.connection() as conn:
+            rows = conn.execute("SELECT path, name, status FROM repositories ORDER BY path ASC").fetchall()
+        return [PublicRootSummary(path=row["path"], name=row["name"], status=row["status"]) for row in rows]
+
+    def get_repository_binding(self, repo_id: str) -> dict | None:
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM repositories WHERE repo_id = ?", (_normalize_path(repo_id),)).fetchone()
+            return dict(row) if row is not None else None
+
+    def get_root_binding(self, path: str) -> dict | None:
+        return self.get_repository_binding(path)
+
+    def require_repository_binding(self, repo_id: str) -> dict:
+        binding = self.get_repository_binding(repo_id)
+        if binding is None:
+            raise RepositoryNotFoundError(f"Unknown repository: {repo_id}")
+        return binding
+
+    def find_root_bindings_for_path(self, path: str) -> list[dict]:
+        normalized_target = _normalize_path(path)
+        with self.database.connection() as conn:
+            rows = conn.execute("SELECT * FROM repositories ORDER BY LENGTH(path) DESC, path ASC").fetchall()
+        bindings: list[dict] = []
+        for row in rows:
+            binding = dict(row)
+            binding_path = _normalize_path(binding["path"])
+            try:
+                contains = os.path.commonpath([binding_path, normalized_target]) == binding_path
+            except ValueError:
+                contains = False
+            if contains:
+                binding["path"] = binding_path
+                bindings.append(binding)
+        return bindings

controller/app/services/router.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+import os
+from pathlib import Path
+from typing import Awaitable, Callable
+from uuid import uuid4
+
+from controller.app.services.repositories import RepositoryService
+from controller.app.services.tasks import TaskService
+from shared.protocol import TaskMessage
+
+
+SendJson = Callable[[dict], Awaitable[None]]
+
+
+def _normalize_path(path_value: str) -> str:
+    return str(Path(path_value).expanduser().resolve())
+
+
+def _path_is_within_root(path_value: str, root_path: str) -> bool:
+    if not root_path:
+        return False
+    normalized_target = _normalize_path(path_value)
+    normalized_root = _normalize_path(root_path)
+    try:
+        return os.path.commonpath([normalized_root, normalized_target]) == normalized_root
+    except ValueError:
+        return False
+
+
+@dataclass
+class LiveAgent:
+    agent_id: str
+    send_json: SendJson
+    capabilities: list[dict]
+    roots: list[dict]
+
+    def supports(self, capability: str, action: str) -> bool:
+        for item in self.capabilities:
+            if item.get("capability") != capability:
+                continue
+            if action in (item.get("actions") or []):
+                return True
+        return False
+
+
+class TaskRouter:
+    def __init__(self, repositories: RepositoryService, tasks: TaskService, timeout_seconds: float = 15.0):
+        self.repositories = repositories
+        self.tasks = tasks
+        self.timeout_seconds = timeout_seconds
+        self.live_agents: dict[str, LiveAgent] = {}
+        self.pending_tasks: dict[str, asyncio.Future] = {}
+        self.pending_tasks_history: list[str] = []
+
+    def attach_agent(
+        self,
+        *,
+        agent_id: str,
+        send_json: SendJson,
+        capabilities: list[dict],
+        roots: list[dict] | None = None,
+        repositories: list[dict] | None = None,
+    ) -> None:
+        self.live_agents[agent_id] = LiveAgent(
+            agent_id=agent_id,
+            send_json=send_json,
+            capabilities=capabilities,
+            roots=roots if roots is not None else (repositories or []),
+        )
+
+    def detach_agent(self, agent_id: str) -> None:
+        self.live_agents.pop(agent_id, None)
+
+    async def dispatch_task(self, path: str, capability: str, action: str, params: dict, agent_id: str | None = None) -> dict:
+        normalized_path = _normalize_path(path)
+        selected_agent_id = agent_id
+
+        if selected_agent_id is not None:
+            live_agent = self.live_agents.get(selected_agent_id)
+            if live_agent is None:
+                raise RuntimeError(f"No live agent for selected client {selected_agent_id}")
+            if not live_agent.supports(capability, action):
+                raise RuntimeError(f"Selected client {selected_agent_id} does not support {capability}:{action}")
+            if not any(_path_is_within_root(normalized_path, root.get("path", "")) for root in live_agent.roots):
+                raise RuntimeError(f"Path {normalized_path} is outside selected client roots")
+        else:
+            candidate_bindings = self.repositories.find_root_bindings_for_path(normalized_path)
+            routed: list[tuple[dict, LiveAgent]] = []
+            for binding in candidate_bindings:
+                live_agent = self.live_agents.get(binding["agent_id"])
+                if live_agent is None:
+                    continue
+                if not live_agent.supports(capability, action):
+                    continue
+                routed.append((binding, live_agent))
+
+            if not routed:
+                raise RuntimeError(f"No live agent for path {normalized_path}")
+            if len(routed) > 1:
+                raise RuntimeError(f"Ambiguous path owner for {normalized_path}")
+
+            binding, live_agent = routed[0]
+            selected_agent_id = binding["agent_id"]
+
+        task_id = str(uuid4())
+        task = TaskMessage(task_id=task_id, path=normalized_path, capability=capability, action=action, params=params)
+        self.tasks.create_task(
+            task_id=task_id,
+            repo_id=normalized_path,
+            capability=capability,
+            action=action,
+            params=params,
+            agent_id=selected_agent_id,
+        )
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        self.pending_tasks[task_id] = future
+        self.pending_tasks_history.append(task_id)
+        await live_agent.send_json(task.model_dump())
+        try:
+            return await asyncio.wait_for(future, timeout=self.timeout_seconds)
+        finally:
+            self.pending_tasks.pop(task_id, None)
+
+    async def handle_event(self, *, task_id: str, status: str, message: str | None = None, details: dict | None = None) -> dict:
+        return self.tasks.append_event(task_id, status=status, message=message, details=details)
+
+    async def handle_result(self, task_id: str, success: bool, result: dict | None, error: str | None) -> dict:
+        stored = self.tasks.store_result(task_id, success=success, result=result, error=error)
+        future = self.pending_tasks.get(task_id)
+        if future is None or future.done() or not stored["inserted"]:
+            return stored
+        if success:
+            future.set_result(result or {})
+        else:
+            future.set_exception(RuntimeError(error or "Task failed"))
+        return stored

controller/app/services/tasks.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+import json
+
+from controller.app.core.errors import TaskNotFoundError
+from controller.app.db.session import ControllerDatabase
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _decode_task(row) -> dict | None:
+    if row is None:
+        return None
+    payload = dict(row)
+    payload["params"] = json.loads(payload.pop("params_json"))
+    result_json = payload.pop("result_json")
+    payload["result"] = json.loads(result_json) if result_json else None
+    payload["success"] = None if payload["result_success"] is None else bool(payload["result_success"])
+    return payload
+
+
+class TaskService:
+    def __init__(self, database: ControllerDatabase):
+        self.database = database
+
+    def create_task(self, task_id: str, repo_id: str, capability: str, action: str, params: dict, agent_id: str | None = None) -> dict:
+        now = _now()
+        with self.database.connection() as conn:
+            conn.execute(
+                "INSERT INTO tasks (task_id, repo_id, agent_id, capability, action, params_json, status, created_at, updated_at, terminal_at, result_success, result_json, error) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (task_id, repo_id, agent_id, capability, action, json.dumps(params), "queued", now, now, None, None, None, None),
+            )
+            row = conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
+            return _decode_task(row)
+
+    def append_event(self, task_id: str, status: str, message: str | None = None, details: dict | None = None) -> dict:
+        now = _now()
+        details = details or {}
+        with self.database.connection() as conn:
+            task = conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
+            if task is None:
+                raise TaskNotFoundError(f"Unknown task: {task_id}")
+            conn.execute(
+                "INSERT INTO task_events (task_id, status, message, details_json, created_at) VALUES (?, ?, ?, ?, ?)",
+                (task_id, status, message, json.dumps(details), now),
+            )
+            conn.execute(
+                "UPDATE tasks SET status = ?, updated_at = ? WHERE task_id = ?",
+                (status, now, task_id),
+            )
+        return {"task_id": task_id, "status": status, "message": message, "details": details}
+
+    def list_events(self, task_id: str) -> list[dict]:
+        with self.database.connection() as conn:
+            rows = conn.execute(
+                "SELECT task_id, status, message, details_json, created_at FROM task_events WHERE task_id = ? ORDER BY id ASC",
+                (task_id,),
+            ).fetchall()
+        return [
+            {
+                "task_id": row["task_id"],
+                "status": row["status"],
+                "message": row["message"],
+                "details": json.loads(row["details_json"]),
+                "created_at": row["created_at"],
+            }
+            for row in rows
+        ]
+
+    def store_result(self, task_id: str, success: bool, result: dict | None = None, error: str | None = None) -> dict:
+        now = _now()
+        result = result or {}
+        terminal_status = "succeeded" if success else "failed"
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
+            if row is None:
+                raise TaskNotFoundError(f"Unknown task: {task_id}")
+            if row["result_success"] is not None:
+                return {"inserted": False, "task": _decode_task(row)}
+            conn.execute(
+                "UPDATE tasks SET status = ?, updated_at = ?, terminal_at = ?, result_success = ?, result_json = ?, error = ? WHERE task_id = ?",
+                (terminal_status, now, now, int(success), json.dumps(result), error, task_id),
+            )
+            updated = conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
+        return {"inserted": True, "task": _decode_task(updated)}
+
+    def get_task(self, task_id: str) -> dict | None:
+        with self.database.connection() as conn:
+            row = conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
+            return _decode_task(row)
+
+    def get_result(self, task_id: str) -> dict | None:
+        task = self.get_task(task_id)
+        if task is None or task["success"] is None:
+            return None
+        return {
+            "task_id": task_id,
+            "success": task["success"],
+            "result": task["result"] or {},
+            "error": task["error"],
+        }

controller/app/services/terminals.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Awaitable, Callable
+
+from controller.app.services.router import TaskRouter, _normalize_path, _path_is_within_root
+from shared.protocol import (
+    TerminalCloseMessage,
+    TerminalClosedMessage,
+    TerminalHeartbeatMessage,
+    TerminalInputMessage,
+    TerminalOpenMessage,
+    TerminalOutputMessage,
+    TerminalResizeMessage,
+    TerminalStatusMessage,
+)
+
+
+SendJson = Callable[[dict], Awaitable[None]]
+
+
+@dataclass
+class BrowserTerminalSession:
+    terminal_id: str
+    agent_id: str
+    path: str
+    cols: int
+    rows: int
+    send_json: SendJson
+
+
+class TerminalRelayService:
+    def __init__(self, router: TaskRouter):
+        self.router = router
+        self.sessions: dict[str, BrowserTerminalSession] = {}
+
+    async def open_browser_terminal(
+        self,
+        *,
+        terminal_id: str,
+        agent_id: str,
+        path: str,
+        cols: int,
+        rows: int,
+        send_json: SendJson,
+    ) -> str:
+        normalized_path = _normalize_path(path)
+        live_agent = self.router.live_agents.get(agent_id)
+        if live_agent is None:
+            raise RuntimeError(f"No live agent for selected client {agent_id}")
+        if not live_agent.supports('terminal.open', 'post'):
+            raise RuntimeError(f"Selected client {agent_id} does not support terminal.open:post")
+        if not any(_path_is_within_root(normalized_path, root.get('path', '')) for root in live_agent.roots):
+            raise RuntimeError(f"Path {normalized_path} is outside selected client roots")
+
+        session = BrowserTerminalSession(
+            terminal_id=terminal_id,
+            agent_id=agent_id,
+            path=normalized_path,
+            cols=cols,
+            rows=rows,
+            send_json=send_json,
+        )
+        self.sessions[terminal_id] = session
+        await send_json(TerminalStatusMessage(terminal_id=terminal_id, status='connecting').model_dump())
+        await live_agent.send_json(
+            TerminalOpenMessage(terminal_id=terminal_id, path=normalized_path, cols=cols, rows=rows).model_dump()
+        )
+        return terminal_id
+
+    async def forward_browser_message(self, terminal_id: str, payload: dict) -> None:
+        session = self.sessions.get(terminal_id)
+        if session is None:
+            return
+        live_agent = self.router.live_agents.get(session.agent_id)
+        if live_agent is None:
+            await self.handle_terminal_closed(TerminalClosedMessage(terminal_id=terminal_id, reason='client_disconnected'))
+            return
+
+        message_type = payload.get('type')
+        if message_type == 'terminal_input':
+            message = TerminalInputMessage(**payload)
+            await live_agent.send_json(message.model_dump())
+        elif message_type == 'terminal_resize':
+            message = TerminalResizeMessage(**payload)
+            await live_agent.send_json(message.model_dump())
+        elif message_type == 'terminal_close':
+            message = TerminalCloseMessage(**payload)
+            await live_agent.send_json(message.model_dump())
+
+    async def handle_terminal_status(self, message: TerminalStatusMessage) -> None:
+        await self._safe_send_to_browser(message.terminal_id, message.model_dump())
+
+    async def handle_terminal_output(self, message: TerminalOutputMessage) -> None:
+        await self._safe_send_to_browser(message.terminal_id, message.model_dump())
+
+    async def handle_terminal_heartbeat(self, message: TerminalHeartbeatMessage) -> None:
+        await self._safe_send_to_browser(message.terminal_id, message.model_dump())
+
+    async def handle_terminal_closed(self, message: TerminalClosedMessage) -> None:
+        session = self.sessions.pop(message.terminal_id, None)
+        if session is None:
+            return
+        try:
+            await session.send_json(message.model_dump())
+        except Exception:
+            return
+
+    async def close_browser_terminal(self, terminal_id: str, reason: str = 'browser_disconnected') -> None:
+        session = self.sessions.pop(terminal_id, None)
+        if session is None:
+            return
+        live_agent = self.router.live_agents.get(session.agent_id)
+        if live_agent is None:
+            return
+        if live_agent.supports('terminal.close', 'post'):
+            await live_agent.send_json(TerminalCloseMessage(terminal_id=terminal_id, reason=reason).model_dump())
+
+    async def close_agent_sessions(self, agent_id: str, reason: str = 'client_disconnected') -> None:
+        terminal_ids = [terminal_id for terminal_id, session in self.sessions.items() if session.agent_id == agent_id]
+        for terminal_id in terminal_ids:
+            session = self.sessions.pop(terminal_id, None)
+            if session is None:
+                continue
+            try:
+                await session.send_json(TerminalClosedMessage(terminal_id=terminal_id, reason=reason).model_dump())
+            except Exception:
+                continue
+
+    async def _safe_send_to_browser(self, terminal_id: str, payload: dict) -> None:
+        session = self.sessions.get(terminal_id)
+        if session is None:
+            return
+        try:
+            await session.send_json(payload)
+        except Exception:
+            self.sessions.pop(terminal_id, None)
+            await self.close_remote_terminal(terminal_id, session.agent_id, reason='browser_send_failed')
+
+    async def close_remote_terminal(self, terminal_id: str, agent_id: str, reason: str) -> None:
+        live_agent = self.router.live_agents.get(agent_id)
+        if live_agent is None:
+            return
+        if live_agent.supports('terminal.close', 'post'):
+            try:
+                await live_agent.send_json(TerminalCloseMessage(terminal_id=terminal_id, reason=reason).model_dump())
+            except Exception:
+                return