refactor: remove main session key references and enhance agent-gateway associations

backend/app/services/agent_provisioning.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from abc import ABC, abstractmethod
 import hashlib
 import json
 import re
@@ -19,7 +20,6 @@ from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_sessi
 from app.services.gateway_agents import (
     gateway_agent_session_key,
     gateway_openclaw_agent_id,
-    parse_gateway_agent_session_key,
 )
 
 if TYPE_CHECKING:
@@ -146,22 +146,6 @@ def _slugify(value: str) -> str:
     return slug or uuid4().hex
 
 
-def _agent_id_from_session_key(session_key: str | None) -> str | None:
-    value = (session_key or "").strip()
-    if not value:
-        return None
-    # Dedicated Mission Control gateway-agent session keys are not gateway config agent ids.
-    if parse_gateway_agent_session_key(value) is not None:
-        return None
-    if not value.startswith("agent:"):
-        return None
-    parts = value.split(":")
-    if len(parts) < _SESSION_KEY_PARTS_MIN:
-        return None
-    agent_id = parts[1].strip()
-    return agent_id or None
-
-
 def _clean_str(value: object) -> str | None:
     if isinstance(value, str) and value.strip():
         return value.strip()
@@ -436,70 +420,6 @@ def _session_key(agent: Agent) -> str:
     return f"agent:{_agent_key(agent)}:main"
 
 
-async def _supported_gateway_files(config: GatewayClientConfig) -> set[str]:
-    try:
-        agents_payload = await openclaw_call("agents.list", config=config)
-        agents = []
-        default_id = None
-        if isinstance(agents_payload, dict):
-            agents = list(agents_payload.get("agents") or [])
-            default_id = agents_payload.get("defaultId") or agents_payload.get(
-                "default_id",
-            )
-        agent_id = default_id or (agents[0].get("id") if agents else None)
-        if not agent_id:
-            return set(DEFAULT_GATEWAY_FILES)
-        files_payload = await openclaw_call(
-            "agents.files.list",
-            {"agentId": agent_id},
-            config=config,
-        )
-        if isinstance(files_payload, dict):
-            files = files_payload.get("files") or []
-            supported: set[str] = set()
-            for item in files:
-                if not isinstance(item, dict):
-                    continue
-                name = item.get("name")
-                if isinstance(name, str) and name:
-                    supported.add(name)
-            return supported or set(DEFAULT_GATEWAY_FILES)
-    except OpenClawGatewayError:
-        pass
-    return set(DEFAULT_GATEWAY_FILES)
-
-
-async def _reset_session(session_key: str, config: GatewayClientConfig) -> None:
-    if not session_key:
-        return
-    await openclaw_call("sessions.reset", {"key": session_key}, config=config)
-
-
-async def _gateway_agent_files_index(
-    agent_id: str,
-    config: GatewayClientConfig,
-) -> dict[str, dict[str, Any]]:
-    try:
-        payload = await openclaw_call(
-            "agents.files.list",
-            {"agentId": agent_id},
-            config=config,
-        )
-        if isinstance(payload, dict):
-            files = payload.get("files") or []
-            index: dict[str, dict[str, Any]] = {}
-            for item in files:
-                if not isinstance(item, dict):
-                    continue
-                name = item.get("name")
-                if isinstance(name, str) and name:
-                    index[name] = dict(item)
-            return index
-    except OpenClawGatewayError:
-        pass
-    return {}
-
-
 def _render_agent_files(
     context: dict[str, str],
     agent: Agent,
@@ -548,67 +468,205 @@ def _render_agent_files(
     return rendered
 
 
-async def _gateway_default_agent_id(
-    config: GatewayClientConfig,
-    *,
-    fallback_session_key: str | None = None,
-) -> str | None:
-    try:
-        payload = await openclaw_call("agents.list", config=config)
-    except OpenClawGatewayError:
-        return _agent_id_from_session_key(fallback_session_key)
+@dataclass(frozen=True, slots=True)
+class GatewayAgentRegistration:
+    """Desired gateway runtime state for one agent."""
 
-    agent_id = _extract_agent_id(payload)
-    if agent_id:
-        return agent_id
-    return _agent_id_from_session_key(fallback_session_key)
+    agent_id: str
+    name: str
+    workspace_path: str
+    heartbeat: dict[str, Any]
 
 
-async def _patch_gateway_agent_list(
-    agent_id: str,
-    workspace_path: str,
-    heartbeat: dict[str, Any],
-    config: GatewayClientConfig,
-) -> None:
-    cfg = await openclaw_call("config.get", config=config)
-    if not isinstance(cfg, dict):
-        msg = "config.get returned invalid payload"
-        raise OpenClawGatewayError(msg)
-    base_hash = cfg.get("hash")
-    data = cfg.get("config") or cfg.get("parsed") or {}
-    if not isinstance(data, dict):
-        msg = "config.get returned invalid config"
-        raise OpenClawGatewayError(msg)
-    agents = data.get("agents") or {}
-    lst = agents.get("list") or []
-    if not isinstance(lst, list):
-        msg = "config agents.list is not a list"
-        raise OpenClawGatewayError(msg)
+class GatewayControlPlane(ABC):
+    """Abstract gateway runtime interface used by agent lifecycle managers."""
 
-    updated = False
-    new_list: list[dict[str, Any]] = []
-    for entry in lst:
-        if isinstance(entry, dict) and entry.get("id") == agent_id:
-            new_entry = dict(entry)
-            new_entry["workspace"] = workspace_path
-            new_entry["heartbeat"] = heartbeat
-            new_list.append(new_entry)
-            updated = True
+    @abstractmethod
+    async def ensure_agent_session(self, session_key: str, *, label: str | None = None) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def reset_agent_session(self, session_key: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_agent_session(self, session_key: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def upsert_agent(self, registration: GatewayAgentRegistration) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_agent(self, agent_id: str, *, delete_files: bool = True) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_supported_files(self) -> set[str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_agent_files(self, agent_id: str) -> dict[str, dict[str, Any]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def set_agent_file(self, *, agent_id: str, name: str, content: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def patch_agent_heartbeats(
+        self,
+        entries: list[tuple[str, str, dict[str, Any]]],
+    ) -> None:
+        raise NotImplementedError
+
+
+class OpenClawGatewayControlPlane(GatewayControlPlane):
+    """OpenClaw gateway RPC implementation of the lifecycle control-plane contract."""
+
+    def __init__(self, config: GatewayClientConfig) -> None:
+        self._config = config
+
+    async def ensure_agent_session(self, session_key: str, *, label: str | None = None) -> None:
+        if not session_key:
+            return
+        await ensure_session(session_key, config=self._config, label=label)
+
+    async def reset_agent_session(self, session_key: str) -> None:
+        if not session_key:
+            return
+        await openclaw_call("sessions.reset", {"key": session_key}, config=self._config)
+
+    async def delete_agent_session(self, session_key: str) -> None:
+        if not session_key:
+            return
+        await openclaw_call("sessions.delete", {"key": session_key}, config=self._config)
+
+    async def _agent_ids(self) -> set[str]:
+        payload = await openclaw_call("agents.list", config=self._config)
+        raw_agents: object = payload
+        if isinstance(payload, dict):
+            raw_agents = payload.get("agents") or []
+        if not isinstance(raw_agents, list):
+            return set()
+        ids: set[str] = set()
+        for item in raw_agents:
+            agent_id = _extract_agent_id_from_item(item)
+            if agent_id:
+                ids.add(agent_id)
+        return ids
+
+    async def upsert_agent(self, registration: GatewayAgentRegistration) -> None:
+        agent_ids = await self._agent_ids()
+        if registration.agent_id in agent_ids:
+            await openclaw_call(
+                "agents.update",
+                {
+                    "agentId": registration.agent_id,
+                    "name": registration.name,
+                    "workspace": registration.workspace_path,
+                },
+                config=self._config,
+            )
         else:
-            new_list.append(entry)
-    if not updated:
-        new_list.append(
-            {"id": agent_id, "workspace": workspace_path, "heartbeat": heartbeat},
+            # `agents.create` derives `agentId` from `name`, so create with the target id
+            # and then set the human-facing name in a follow-up update.
+            await openclaw_call(
+                "agents.create",
+                {
+                    "name": registration.agent_id,
+                    "workspace": registration.workspace_path,
+                },
+                config=self._config,
+            )
+            if registration.name != registration.agent_id:
+                await openclaw_call(
+                    "agents.update",
+                    {
+                        "agentId": registration.agent_id,
+                        "name": registration.name,
+                        "workspace": registration.workspace_path,
+                    },
+                    config=self._config,
+                )
+        await self.patch_agent_heartbeats(
+            [(registration.agent_id, registration.workspace_path, registration.heartbeat)],
         )
 
-    patch: dict[str, Any] = {"agents": {"list": new_list}}
-    channels_patch = _channel_heartbeat_visibility_patch(data)
-    if channels_patch is not None:
-        patch["channels"] = channels_patch
-    params = {"raw": json.dumps(patch)}
-    if base_hash:
-        params["baseHash"] = base_hash
-    await openclaw_call("config.patch", params, config=config)
+    async def delete_agent(self, agent_id: str, *, delete_files: bool = True) -> None:
+        await openclaw_call(
+            "agents.delete",
+            {"agentId": agent_id, "deleteFiles": delete_files},
+            config=self._config,
+        )
+
+    async def list_supported_files(self) -> set[str]:
+        agents_payload = await openclaw_call("agents.list", config=self._config)
+        agent_id = _extract_agent_id(agents_payload)
+        if not agent_id:
+            return set(DEFAULT_GATEWAY_FILES)
+        files_payload = await openclaw_call(
+            "agents.files.list",
+            {"agentId": agent_id},
+            config=self._config,
+        )
+        if not isinstance(files_payload, dict):
+            return set(DEFAULT_GATEWAY_FILES)
+        files = files_payload.get("files") or []
+        if not isinstance(files, list):
+            return set(DEFAULT_GATEWAY_FILES)
+        supported: set[str] = set()
+        for item in files:
+            if not isinstance(item, dict):
+                continue
+            name = item.get("name")
+            if isinstance(name, str) and name:
+                supported.add(name)
+        return supported or set(DEFAULT_GATEWAY_FILES)
+
+    async def list_agent_files(self, agent_id: str) -> dict[str, dict[str, Any]]:
+        payload = await openclaw_call(
+            "agents.files.list",
+            {"agentId": agent_id},
+            config=self._config,
+        )
+        if not isinstance(payload, dict):
+            return {}
+        files = payload.get("files") or []
+        if not isinstance(files, list):
+            return {}
+        index: dict[str, dict[str, Any]] = {}
+        for item in files:
+            if not isinstance(item, dict):
+                continue
+            name = item.get("name")
+            if isinstance(name, str) and name:
+                index[name] = dict(item)
+        return index
+
+    async def set_agent_file(self, *, agent_id: str, name: str, content: str) -> None:
+        await openclaw_call(
+            "agents.files.set",
+            {"agentId": agent_id, "name": name, "content": content},
+            config=self._config,
+        )
+
+    async def patch_agent_heartbeats(
+        self,
+        entries: list[tuple[str, str, dict[str, Any]]],
+    ) -> None:
+        base_hash, raw_list, config_data = await _gateway_config_agent_list(self._config)
+        entry_by_id = _heartbeat_entry_map(entries)
+        new_list = _updated_agent_list(raw_list, entry_by_id)
+
+        patch: dict[str, Any] = {"agents": {"list": new_list}}
+        channels_patch = _channel_heartbeat_visibility_patch(config_data)
+        if channels_patch is not None:
+            patch["channels"] = channels_patch
+        params = {"raw": json.dumps(patch)}
+        if base_hash:
+            params["baseHash"] = base_hash
+        await openclaw_call("config.patch", params, config=self._config)
 
 
 async def _gateway_config_agent_list(
@@ -673,6 +731,177 @@ def _updated_agent_list(
     return new_list
 
 
+class BaseAgentLifecycleManager(ABC):
+    """Base class for scalable board/main agent lifecycle managers."""
+
+    def __init__(self, gateway: Gateway, control_plane: GatewayControlPlane) -> None:
+        self._gateway = gateway
+        self._control_plane = control_plane
+
+    @abstractmethod
+    def _agent_id(self, agent: Agent) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def _build_context(
+        self,
+        *,
+        agent: Agent,
+        auth_token: str,
+        user: User | None,
+        board: Board | None,
+    ) -> dict[str, str]:
+        raise NotImplementedError
+
+    def _template_overrides(self) -> dict[str, str] | None:
+        return None
+
+    async def _set_agent_files(
+        self,
+        *,
+        agent_id: str,
+        rendered: dict[str, str],
+        existing_files: dict[str, dict[str, Any]],
+    ) -> None:
+        for name, content in rendered.items():
+            if content == "":
+                continue
+            if name in PRESERVE_AGENT_EDITABLE_FILES:
+                entry = existing_files.get(name)
+                if entry and not bool(entry.get("missing")):
+                    continue
+            try:
+                await self._control_plane.set_agent_file(
+                    agent_id=agent_id,
+                    name=name,
+                    content=content,
+                )
+            except OpenClawGatewayError as exc:
+                if "unsupported file" in str(exc).lower():
+                    continue
+                raise
+
+    async def provision(
+        self,
+        *,
+        agent: Agent,
+        session_key: str,
+        auth_token: str,
+        user: User | None,
+        options: ProvisionOptions,
+        board: Board | None = None,
+        session_label: str | None = None,
+    ) -> None:
+        if not self._gateway.workspace_root:
+            msg = "gateway_workspace_root is required"
+            raise ValueError(msg)
+        if not agent.openclaw_session_id:
+            agent.openclaw_session_id = session_key
+        await self._control_plane.ensure_agent_session(
+            session_key,
+            label=session_label or agent.name,
+        )
+
+        agent_id = self._agent_id(agent)
+        workspace_path = _workspace_path(agent, self._gateway.workspace_root)
+        heartbeat = _heartbeat_config(agent)
+        await self._control_plane.upsert_agent(
+            GatewayAgentRegistration(
+                agent_id=agent_id,
+                name=agent.name,
+                workspace_path=workspace_path,
+                heartbeat=heartbeat,
+            ),
+        )
+
+        context = self._build_context(
+            agent=agent,
+            auth_token=auth_token,
+            user=user,
+            board=board,
+        )
+        supported = await self._control_plane.list_supported_files()
+        supported.update({"USER.md", "SELF.md", "AUTONOMY.md"})
+        existing_files = await self._control_plane.list_agent_files(agent_id)
+        include_bootstrap = _should_include_bootstrap(
+            action=options.action,
+            force_bootstrap=options.force_bootstrap,
+            existing_files=existing_files,
+        )
+        rendered = _render_agent_files(
+            context,
+            agent,
+            supported,
+            include_bootstrap=include_bootstrap,
+            template_overrides=self._template_overrides(),
+        )
+
+        for name in PRESERVE_AGENT_EDITABLE_FILES:
+            content = rendered.get(name)
+            if not content:
+                continue
+            with suppress(OSError):
+                _ensure_workspace_file(workspace_path, name, content, overwrite=False)
+
+        await self._set_agent_files(
+            agent_id=agent_id,
+            rendered=rendered,
+            existing_files=existing_files,
+        )
+        if options.reset_session:
+            await self._control_plane.reset_agent_session(session_key)
+
+
+class BoardAgentLifecycleManager(BaseAgentLifecycleManager):
+    """Provisioning manager for board-scoped agents."""
+
+    def _agent_id(self, agent: Agent) -> str:
+        return _agent_key(agent)
+
+    def _build_context(
+        self,
+        *,
+        agent: Agent,
+        auth_token: str,
+        user: User | None,
+        board: Board | None,
+    ) -> dict[str, str]:
+        if board is None:
+            msg = "board is required for board-scoped agent provisioning"
+            raise ValueError(msg)
+        return _build_context(agent, board, self._gateway, auth_token, user)
+
+
+class GatewayMainAgentLifecycleManager(BaseAgentLifecycleManager):
+    """Provisioning manager for organization gateway-main agents."""
+
+    def _agent_id(self, agent: Agent) -> str:
+        return gateway_openclaw_agent_id(self._gateway)
+
+    def _build_context(
+        self,
+        *,
+        agent: Agent,
+        auth_token: str,
+        user: User | None,
+        board: Board | None,
+    ) -> dict[str, str]:
+        _ = board
+        return _build_main_context(agent, self._gateway, auth_token, user)
+
+    def _template_overrides(self) -> dict[str, str] | None:
+        return MAIN_TEMPLATE_MAP
+
+
+def _control_plane_for_gateway(gateway: Gateway) -> OpenClawGatewayControlPlane:
+    if not gateway.url:
+        msg = "Gateway url is required"
+        raise OpenClawGatewayError(msg)
+    return OpenClawGatewayControlPlane(
+        GatewayClientConfig(url=gateway.url, token=gateway.token),
+    )
+
+
 async def patch_gateway_agent_heartbeats(
     gateway: Gateway,
     *,
@@ -682,22 +911,8 @@ async def patch_gateway_agent_heartbeats(
 
     Each entry is (agent_id, workspace_path, heartbeat_dict).
     """
-    if not gateway.url:
-        msg = "Gateway url is required"
-        raise OpenClawGatewayError(msg)
-    config = GatewayClientConfig(url=gateway.url, token=gateway.token)
-    base_hash, raw_list, config_data = await _gateway_config_agent_list(config)
-    entry_by_id = _heartbeat_entry_map(entries)
-    new_list = _updated_agent_list(raw_list, entry_by_id)
-
-    patch: dict[str, Any] = {"agents": {"list": new_list}}
-    channels_patch = _channel_heartbeat_visibility_patch(config_data)
-    if channels_patch is not None:
-        patch["channels"] = channels_patch
-    params = {"raw": json.dumps(patch)}
-    if base_hash:
-        params["baseHash"] = base_hash
-    await openclaw_call("config.patch", params, config=config)
+    control_plane = _control_plane_for_gateway(gateway)
+    await control_plane.patch_agent_heartbeats(entries)
 
 
 async def sync_gateway_agent_heartbeats(gateway: Gateway, agents: list[Agent]) -> None:
@@ -716,57 +931,6 @@ async def sync_gateway_agent_heartbeats(gateway: Gateway, agents: list[Agent]) -
     await patch_gateway_agent_heartbeats(gateway, entries=entries)
 
 
-async def _remove_gateway_agent_list(
-    agent_id: str,
-    config: GatewayClientConfig,
-) -> None:
-    cfg = await openclaw_call("config.get", config=config)
-    if not isinstance(cfg, dict):
-        msg = "config.get returned invalid payload"
-        raise OpenClawGatewayError(msg)
-    base_hash = cfg.get("hash")
-    data = cfg.get("config") or cfg.get("parsed") or {}
-    if not isinstance(data, dict):
-        msg = "config.get returned invalid config"
-        raise OpenClawGatewayError(msg)
-    agents = data.get("agents") or {}
-    lst = agents.get("list") or []
-    if not isinstance(lst, list):
-        msg = "config agents.list is not a list"
-        raise OpenClawGatewayError(msg)
-
-    new_list = [
-        entry for entry in lst if not (isinstance(entry, dict) and entry.get("id") == agent_id)
-    ]
-    if len(new_list) == len(lst):
-        return
-    patch = {"agents": {"list": new_list}}
-    params = {"raw": json.dumps(patch)}
-    if base_hash:
-        params["baseHash"] = base_hash
-    await openclaw_call("config.patch", params, config=config)
-
-
-async def _get_gateway_agent_entry(
-    agent_id: str,
-    config: GatewayClientConfig,
-) -> dict[str, Any] | None:
-    cfg = await openclaw_call("config.get", config=config)
-    if not isinstance(cfg, dict):
-        return None
-    data = cfg.get("config") or cfg.get("parsed") or {}
-    if not isinstance(data, dict):
-        return None
-    agents = data.get("agents") or {}
-    lst = agents.get("list") or []
-    if not isinstance(lst, list):
-        return None
-    for entry in lst:
-        if isinstance(entry, dict) and entry.get("id") == agent_id:
-            return entry
-    return None
-
-
 def _should_include_bootstrap(
     *,
     action: str,
@@ -781,32 +945,6 @@ def _should_include_bootstrap(
     return not bool(entry and entry.get("missing"))
 
 
-async def _set_agent_files(
-    *,
-    agent_id: str,
-    rendered: dict[str, str],
-    existing_files: dict[str, dict[str, Any]],
-    client_config: GatewayClientConfig,
-) -> None:
-    for name, content in rendered.items():
-        if content == "":
-            continue
-        if name in PRESERVE_AGENT_EDITABLE_FILES:
-            entry = existing_files.get(name)
-            if entry and not bool(entry.get("missing")):
-                continue
-        try:
-            await openclaw_call(
-                "agents.files.set",
-                {"agentId": agent_id, "name": name, "content": content},
-                config=client_config,
-            )
-        except OpenClawGatewayError as exc:
-            if "unsupported file" in str(exc).lower():
-                continue
-            raise
-
-
 async def provision_agent(
     agent: Agent,
     request: AgentProvisionRequest,
@@ -815,57 +953,17 @@ async def provision_agent(
     gateway = request.gateway
     if not gateway.url:
         return
-    if not gateway.workspace_root:
-        msg = "gateway_workspace_root is required"
-        raise ValueError(msg)
-    client_config = GatewayClientConfig(url=gateway.url, token=gateway.token)
     session_key = _session_key(agent)
-    await ensure_session(session_key, config=client_config, label=agent.name)
-
-    agent_id = _agent_key(agent)
-    workspace_path = _workspace_path(agent, gateway.workspace_root)
-    heartbeat = _heartbeat_config(agent)
-    await _patch_gateway_agent_list(agent_id, workspace_path, heartbeat, client_config)
-
-    context = _build_context(
-        agent,
-        request.board,
-        gateway,
-        request.auth_token,
-        request.user,
+    control_plane = _control_plane_for_gateway(gateway)
+    manager = BoardAgentLifecycleManager(gateway, control_plane)
+    await manager.provision(
+        agent=agent,
+        board=request.board,
+        session_key=session_key,
+        auth_token=request.auth_token,
+        user=request.user,
+        options=request.options,
     )
-    supported = set(await _supported_gateway_files(client_config))
-    supported.update({"USER.md", "SELF.md", "AUTONOMY.md"})
-    existing_files = await _gateway_agent_files_index(agent_id, client_config)
-    include_bootstrap = _should_include_bootstrap(
-        action=request.options.action,
-        force_bootstrap=request.options.force_bootstrap,
-        existing_files=existing_files,
-    )
-
-    rendered = _render_agent_files(
-        context,
-        agent,
-        supported,
-        include_bootstrap=include_bootstrap,
-    )
-
-    # Ensure editable template files exist locally (best-effort) without overwriting.
-    for name in PRESERVE_AGENT_EDITABLE_FILES:
-        content = rendered.get(name)
-        if not content:
-            continue
-        with suppress(OSError):
-            # Local workspace may not be writable/available; fall back to gateway API.
-            _ensure_workspace_file(workspace_path, name, content, overwrite=False)
-    await _set_agent_files(
-        agent_id=agent_id,
-        rendered=rendered,
-        existing_files=existing_files,
-        client_config=client_config,
-    )
-    if request.options.reset_session:
-        await _reset_session(session_key, client_config)
 
 
 async def provision_main_agent(
@@ -876,52 +974,21 @@ async def provision_main_agent(
     gateway = request.gateway
     if not gateway.url:
         return
-    session_key = (request.session_key or gateway.main_session_key or "").strip()
+    session_key = (request.session_key or gateway_agent_session_key(gateway) or "").strip()
     if not session_key:
         msg = "gateway main agent session_key is required"
         raise ValueError(msg)
-    client_config = GatewayClientConfig(url=gateway.url, token=gateway.token)
-    await ensure_session(
-        session_key,
-        config=client_config,
-        label=agent.name or "Gateway Agent",
+    control_plane = _control_plane_for_gateway(gateway)
+    manager = GatewayMainAgentLifecycleManager(gateway, control_plane)
+    await manager.provision(
+        agent=agent,
+        session_key=session_key,
+        auth_token=request.auth_token,
+        user=request.user,
+        options=request.options,
+        session_label=agent.name or "Gateway Agent",
     )
 
-    # Keep gateway default agent intact and use a dedicated OpenClaw agent id for Mission Control.
-    if not gateway.workspace_root:
-        msg = "gateway_workspace_root is required"
-        raise ValueError(msg)
-    agent_id = gateway_openclaw_agent_id(gateway)
-    workspace_path = _workspace_path(agent, gateway.workspace_root)
-    heartbeat = _heartbeat_config(agent)
-    await _patch_gateway_agent_list(agent_id, workspace_path, heartbeat, client_config)
-
-    context = _build_main_context(agent, gateway, request.auth_token, request.user)
-    supported = set(await _supported_gateway_files(client_config))
-    supported.update({"USER.md", "SELF.md", "AUTONOMY.md"})
-    existing_files = await _gateway_agent_files_index(agent_id, client_config)
-    include_bootstrap = _should_include_bootstrap(
-        action=request.options.action,
-        force_bootstrap=request.options.force_bootstrap,
-        existing_files=existing_files,
-    )
-
-    rendered = _render_agent_files(
-        context,
-        agent,
-        supported,
-        include_bootstrap=include_bootstrap,
-        template_overrides=MAIN_TEMPLATE_MAP,
-    )
-    await _set_agent_files(
-        agent_id=agent_id,
-        rendered=rendered,
-        existing_files=existing_files,
-        client_config=client_config,
-    )
-    if request.options.reset_session:
-        await _reset_session(session_key, client_config)
-
 
 async def cleanup_agent(
     agent: Agent,
@@ -933,16 +1000,11 @@ async def cleanup_agent(
     if not gateway.workspace_root:
         msg = "gateway_workspace_root is required"
         raise ValueError(msg)
-    client_config = GatewayClientConfig(url=gateway.url, token=gateway.token)
-
+    control_plane = _control_plane_for_gateway(gateway)
     agent_id = _agent_key(agent)
-    entry = await _get_gateway_agent_entry(agent_id, client_config)
-    await _remove_gateway_agent_list(agent_id, client_config)
+    await control_plane.delete_agent(agent_id, delete_files=True)
 
     session_key = _session_key(agent)
-    await openclaw_call("sessions.delete", {"key": session_key}, config=client_config)
-
-    workspace_path = entry.get("workspace") if entry else None
-    if not workspace_path:
-        workspace_path = _workspace_path(agent, gateway.workspace_root)
-    return workspace_path
+    with suppress(OpenClawGatewayError):
+        await control_plane.delete_agent_session(session_key)
+    return None

backend/app/services/board_leads.py

@@ -78,6 +78,9 @@ async def ensure_board_lead_agent(
         if existing.name != desired_name:
             existing.name = desired_name
             changed = True
+        if existing.gateway_id != request.gateway.id:
+            existing.gateway_id = request.gateway.id
+            changed = True
         desired_session_key = lead_session_key(board)
         if not existing.openclaw_session_id:
             existing.openclaw_session_id = desired_session_key
@@ -107,6 +110,7 @@ async def ensure_board_lead_agent(
         name=config_options.agent_name or lead_agent_name(board),
         status="provisioning",
         board_id=board.id,
+        gateway_id=request.gateway.id,
         is_board_lead=True,
         heartbeat_config=DEFAULT_HEARTBEAT_CONFIG.copy(),
         identity_profile=merged_identity_profile,

backend/app/services/board_snapshot.py

@@ -12,14 +12,12 @@ from app.core.time import utcnow
 from app.models.agents import Agent
 from app.models.approvals import Approval
 from app.models.board_memory import BoardMemory
-from app.models.gateways import Gateway
 from app.models.tasks import Task
 from app.schemas.agents import AgentRead
 from app.schemas.approvals import ApprovalRead
 from app.schemas.board_memory import BoardMemoryRead
 from app.schemas.boards import BoardRead
 from app.schemas.view_models import BoardSnapshot, TaskCardRead
-from app.services.gateway_agents import gateway_agent_session_key
 from app.services.task_dependencies import (
     blocked_by_dependency_ids,
     dependency_ids_by_task_id,
@@ -47,17 +45,10 @@ def _computed_agent_status(agent: Agent) -> str:
     return agent.status
 
 
-async def _gateway_main_session_keys(session: AsyncSession) -> set[str]:
-    gateways = await Gateway.objects.all().all(session)
-    return {gateway_agent_session_key(gateway) for gateway in gateways}
-
-
-def _agent_to_read(agent: Agent, main_session_keys: set[str]) -> AgentRead:
+def _agent_to_read(agent: Agent) -> AgentRead:
     model = AgentRead.model_validate(agent, from_attributes=True)
     computed_status = _computed_agent_status(agent)
-    is_gateway_main = bool(
-        agent.openclaw_session_id and agent.openclaw_session_id in main_session_keys,
-    )
+    is_gateway_main = agent.gateway_id is not None and agent.board_id is None
     return model.model_copy(
         update={
             "status": computed_status,
@@ -129,13 +120,12 @@ async def build_board_snapshot(session: AsyncSession, board: Board) -> BoardSnap
         dependency_ids=list({*all_dependency_ids}),
     )
 
-    main_session_keys = await _gateway_main_session_keys(session)
     agents = (
         await Agent.objects.filter_by(board_id=board.id)
         .order_by(col(Agent.created_at).desc())
         .all(session)
     )
-    agent_reads = [_agent_to_read(agent, main_session_keys) for agent in agents]
+    agent_reads = [_agent_to_read(agent) for agent in agents]
     agent_name_by_id = {agent.id: agent.name for agent in agents}
 
     pending_approvals_count = int(

backend/app/services/gateway_agents.py

@@ -29,17 +29,3 @@ def gateway_openclaw_agent_id_for_id(gateway_id: UUID) -> str:
 def gateway_openclaw_agent_id(gateway: Gateway) -> str:
     """Return the dedicated OpenClaw config `agentId` for a gateway agent."""
     return gateway_openclaw_agent_id_for_id(gateway.id)
-
-
-def parse_gateway_agent_session_key(session_key: str | None) -> UUID | None:
-    """Parse a gateway id from a dedicated gateway-agent session key."""
-    value = (session_key or "").strip()
-    if not (value.startswith(_GATEWAY_AGENT_PREFIX) and value.endswith(_GATEWAY_AGENT_SUFFIX)):
-        return None
-    gateway_id = value[len(_GATEWAY_AGENT_PREFIX) : -len(_GATEWAY_AGENT_SUFFIX)]
-    if not gateway_id:
-        return None
-    try:
-        return UUID(gateway_id)
-    except ValueError:
-        return None

backend/app/services/template_sync.py

@@ -34,7 +34,6 @@ from app.services.agent_provisioning import (
 from app.services.gateway_agents import (
     gateway_agent_session_key,
     gateway_openclaw_agent_id,
-    parse_gateway_agent_session_key,
 )
 
 _TOOLS_KV_RE = re.compile(r"^(?P<key>[A-Z0-9_]+)=(?P<value>.*)$")
@@ -179,54 +178,6 @@ async def _with_gateway_retry(
     return await backoff.run(fn)
 
 
-def _agent_id_from_session_key(session_key: str | None) -> str | None:
-    value = (session_key or "").strip()
-    if not value:
-        return None
-    # Dedicated Mission Control gateway-agent session keys are not gateway config agent ids.
-    if parse_gateway_agent_session_key(value) is not None:
-        return None
-    if not value.startswith("agent:"):
-        return None
-    parts = value.split(":")
-    if len(parts) < SESSION_KEY_PARTS_MIN:
-        return None
-    agent_id = parts[1].strip()
-    return agent_id or None
-
-
-def _extract_agent_id_from_list(items: object) -> str | None:
-    if not isinstance(items, list):
-        return None
-    for item in items:
-        if isinstance(item, str) and item.strip():
-            return item.strip()
-        if not isinstance(item, dict):
-            continue
-        for key in ("id", "agentId", "agent_id"):
-            raw = item.get(key)
-            if isinstance(raw, str) and raw.strip():
-                return raw.strip()
-    return None
-
-
-def _extract_agent_id(payload: object) -> str | None:
-    """Extract a default gateway agent id from common list payload shapes."""
-    if isinstance(payload, list):
-        return _extract_agent_id_from_list(payload)
-    if not isinstance(payload, dict):
-        return None
-    for key in ("defaultId", "default_id", "defaultAgentId", "default_agent_id"):
-        raw = payload.get(key)
-        if isinstance(raw, str) and raw.strip():
-            return raw.strip()
-    for key in ("agents", "items", "list", "data"):
-        agent_id = _extract_agent_id_from_list(payload.get(key))
-        if agent_id:
-            return agent_id
-    return None
-
-
 def _gateway_agent_id(agent: Agent) -> str:
     session_key = agent.openclaw_session_id or ""
     if session_key.startswith("agent:"):
@@ -304,27 +255,6 @@ async def _get_existing_auth_token(
     return token or None
 
 
-async def _gateway_default_agent_id(
-    config: GatewayClientConfig,
-    *,
-    fallback_session_key: str | None = None,
-    backoff: _GatewayBackoff | None = None,
-) -> str | None:
-    try:
-
-        async def _do_list() -> object:
-            return await openclaw_call("agents.list", config=config)
-
-        payload = await (backoff.run(_do_list) if backoff else _do_list())
-        agent_id = _extract_agent_id(payload)
-        if agent_id:
-            return agent_id
-    except OpenClawGatewayError:
-        pass
-    # Avoid falling back to dedicated gateway session keys, which are not agent ids.
-    return _agent_id_from_session_key(fallback_session_key)
-
-
 async def _paused_board_ids(session: AsyncSession, board_ids: list[UUID]) -> set[UUID]:
     if not board_ids:
         return set()
@@ -532,7 +462,8 @@ async def _sync_main_agent(
     main_session_key = gateway_agent_session_key(ctx.gateway)
     main_agent = (
         await Agent.objects.all()
-        .filter(col(Agent.openclaw_session_id) == main_session_key)
+        .filter(col(Agent.gateway_id) == ctx.gateway.id)
+        .filter(col(Agent.board_id).is_(None))
         .first(ctx.session)
     )
     if main_agent is None: