create-workframe 0.1.0

package/workframe-api/stack_config.py

@@ -0,0 +1,427 @@
+"""Stack operator config (SMTP, deployment mode, install state). Env wins over file for VPS."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+DATA_DIR = Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data"))
+CONFIG_PATH = DATA_DIR / "stack_config.json"
+
+DEPLOYMENT_MODES = frozenset({"single_user_local", "trusted_team", "public_multi_user"})
+
+
+def normalize_smtp_secure(port: int, secure: str) -> str:
+    """Map provider port + secure hint to smtplib mode (ssl | starttls | none)."""
+    s = str(secure or "").strip().lower()
+    p = int(port or 587)
+    if s in {"ssl", "smtps", "1", "true", "yes"}:
+        return "ssl"
+    if s in {"none", "off", "false", "0", "plain"}:
+        return "none"
+    if p == 465:
+        return "ssl"
+    if s in {"starttls", "tls"}:
+        return "starttls"
+    if p in {587, 2525}:
+        return "starttls"
+    return "starttls"
+
+
+def _read_raw() -> dict[str, Any]:
+    if not CONFIG_PATH.is_file():
+        return {}
+    try:
+        with open(CONFIG_PATH, encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _write_raw(data: dict[str, Any]) -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = CONFIG_PATH.with_suffix(".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, sort_keys=True)
+    os.replace(tmp, CONFIG_PATH)
+    try:
+        os.chmod(CONFIG_PATH, 0o600)
+    except OSError:
+        pass
+
+
+def _stack_smtp_raw() -> dict[str, Any]:
+    raw = _read_raw()
+    smtp = raw.get("smtp")
+    return smtp if isinstance(smtp, dict) else {}
+
+
+def _stack_oauth_raw(key: str) -> dict[str, Any]:
+    block = _read_raw().get(key)
+    return block if isinstance(block, dict) else {}
+
+
+def _oauth_public(block: dict[str, Any]) -> dict[str, Any]:
+    client_id = str(block.get("client_id") or "").strip()
+    return {
+        "client_id": client_id,
+        "has_secret": bool(str(block.get("client_secret") or "").strip()),
+        "enabled": bool(client_id),
+    }
+
+
+def resolved_google_oauth() -> dict[str, str]:
+    go = _stack_oauth_raw("google_oauth")
+    return {
+        "client_id": str(go.get("client_id") or "").strip(),
+        "client_secret": str(go.get("client_secret") or "").strip(),
+    }
+
+
+def resolved_github_oauth() -> dict[str, str]:
+    gh = _stack_oauth_raw("github_oauth")
+    return {
+        "client_id": str(gh.get("client_id") or "").strip(),
+        "client_secret": str(gh.get("client_secret") or "").strip(),
+    }
+
+
+def resolved_stripe_connect() -> dict[str, str]:
+    st = _stack_oauth_raw("stripe_connect")
+    return {
+        "client_id": str(st.get("client_id") or "").strip(),
+        "client_secret": str(st.get("client_secret") or "").strip(),
+    }
+
+
+def github_oauth_for_workspace_settings(settings: dict[str, Any]) -> dict[str, Any]:
+    """Copy install-time GitHub OAuth app creds into workspace settings when present."""
+    gh = resolved_github_oauth()
+    if gh.get("client_id") and gh.get("client_secret"):
+        settings = dict(settings or {})
+        settings["github_oauth"] = dict(gh)
+    return settings
+
+
+def get_stack_config() -> dict[str, Any]:
+    raw = _read_raw()
+    smtp = raw.get("smtp") if isinstance(raw.get("smtp"), dict) else {}
+    return {
+        "deployment_mode": str(raw.get("deployment_mode") or "").strip(),
+        "app_base_url": str(raw.get("app_base_url") or "").strip(),
+        "install_complete": bool(raw.get("install_complete")),
+        "smtp": {
+            "provider": str(smtp.get("provider") or "").strip(),
+            "host": str(smtp.get("host") or "").strip(),
+            "port": int(smtp.get("port") or 587),
+            "user": str(smtp.get("user") or "").strip(),
+            "from": str(smtp.get("from") or smtp.get("from_address") or "").strip(),
+            "secure": str(smtp.get("secure") or "starttls").strip(),
+            "has_password": bool(str(smtp.get("password") or "").strip()),
+        },
+        "google_oauth": _oauth_public(_stack_oauth_raw("google_oauth")),
+        "github_oauth": _oauth_public(_stack_oauth_raw("github_oauth")),
+        "discord_oauth": _oauth_public(_stack_oauth_raw("discord_oauth")),
+        "telegram_login": _telegram_login_public(),
+        "stripe_connect": _oauth_public(_stack_oauth_raw("stripe_connect")),
+    }
+
+
+def _telegram_login_public() -> dict[str, Any]:
+    block = _stack_oauth_raw("telegram_login")
+    bot_username = str(block.get("bot_username") or "").strip().lstrip("@")
+    return {
+        "bot_username": bot_username,
+        "has_token": bool(str(block.get("bot_token") or "").strip()),
+        "enabled": bool(bot_username and str(block.get("bot_token") or "").strip()),
+    }
+
+
+def patch_stack_config(body: dict[str, Any]) -> dict[str, Any]:
+    raw = _read_raw()
+    if "deployment_mode" in body:
+        mode = str(body.get("deployment_mode") or "").strip().lower()
+        if mode not in DEPLOYMENT_MODES:
+            raise ValueError(f"invalid deployment_mode: {mode}")
+        raw["deployment_mode"] = mode
+        os.environ["WORKFRAME_DEPLOYMENT_MODE"] = mode
+    if "app_base_url" in body:
+        raw["app_base_url"] = str(body.get("app_base_url") or "").strip().rstrip("/")
+    if body.get("install_complete") is True:
+        raw["install_complete"] = True
+    if "smtp" in body and isinstance(body["smtp"], dict):
+        smtp = dict(raw.get("smtp") if isinstance(raw.get("smtp"), dict) else {})
+        creds_changed = False
+        for key in ("provider", "host", "user", "secure"):
+            if key in body["smtp"]:
+                val = str(body["smtp"][key] or "").strip()
+                if str(smtp.get(key) or "").strip() != val:
+                    creds_changed = True
+                smtp[key] = val
+        if "port" in body["smtp"]:
+            port_val = int(body["smtp"].get("port") or 587)
+            if int(smtp.get("port") or 587) != port_val:
+                creds_changed = True
+            smtp["port"] = port_val
+        if "password" in body["smtp"]:
+            pw = str(body["smtp"].get("password") or "")
+            if pw:
+                creds_changed = True
+                smtp["password"] = pw
+        elif "pass" in body["smtp"]:
+            pw = str(body["smtp"].get("pass") or "")
+            if pw:
+                creds_changed = True
+                smtp["password"] = pw
+        if "from" in body["smtp"] or "from_address" in body["smtp"]:
+            from_val = str(
+                body["smtp"].get("from") if "from" in body["smtp"] else body["smtp"].get("from_address") or ""
+            ).strip()
+            if from_val:
+                smtp["from"] = from_val
+            elif "from" in smtp:
+                del smtp["from"]
+        if "admin_email" in body["smtp"]:
+            admin_email = str(body["smtp"].get("admin_email") or "").strip().lower()
+            if admin_email:
+                smtp["admin_email"] = admin_email
+            elif "admin_email" in smtp:
+                del smtp["admin_email"]
+        if creds_changed:
+            smtp.pop("tested", None)
+        port = int(smtp.get("port") or 587)
+        smtp["secure"] = normalize_smtp_secure(port, str(smtp.get("secure") or ""))
+        raw["smtp"] = smtp
+    if "google_oauth" in body and isinstance(body["google_oauth"], dict):
+        go = raw.get("google_oauth") if isinstance(raw.get("google_oauth"), dict) else {}
+        for key in ("client_id", "client_secret"):
+            if key in body["google_oauth"]:
+                val = str(body["google_oauth"].get(key) or "").strip()
+                if val or key == "client_id":
+                    go[key] = val
+        raw["google_oauth"] = go
+    if "github_oauth" in body and isinstance(body["github_oauth"], dict):
+        gh = raw.get("github_oauth") if isinstance(raw.get("github_oauth"), dict) else {}
+        for key in ("client_id", "client_secret"):
+            if key in body["github_oauth"]:
+                val = str(body["github_oauth"].get(key) or "").strip()
+                if val or key == "client_id":
+                    gh[key] = val
+        raw["github_oauth"] = gh
+    if "discord_oauth" in body and isinstance(body["discord_oauth"], dict):
+        dc = raw.get("discord_oauth") if isinstance(raw.get("discord_oauth"), dict) else {}
+        for key in ("client_id", "client_secret"):
+            if key in body["discord_oauth"]:
+                val = str(body["discord_oauth"].get(key) or "").strip()
+                if val or key == "client_id":
+                    dc[key] = val
+        raw["discord_oauth"] = dc
+    if "telegram_login" in body and isinstance(body["telegram_login"], dict):
+        tg = raw.get("telegram_login") if isinstance(raw.get("telegram_login"), dict) else {}
+        if "bot_username" in body["telegram_login"]:
+            tg["bot_username"] = str(body["telegram_login"].get("bot_username") or "").strip().lstrip("@")
+        if "bot_token" in body["telegram_login"]:
+            token = str(body["telegram_login"].get("bot_token") or "").strip()
+            if token:
+                tg["bot_token"] = token
+        raw["telegram_login"] = tg
+    if "stripe_connect" in body and isinstance(body["stripe_connect"], dict):
+        st = raw.get("stripe_connect") if isinstance(raw.get("stripe_connect"), dict) else {}
+        for key in ("client_id", "client_secret"):
+            if key in body["stripe_connect"]:
+                val = str(body["stripe_connect"].get(key) or "").strip()
+                if val or key == "client_id":
+                    st[key] = val
+        raw["stripe_connect"] = st
+    if "site_branding" in body and isinstance(body["site_branding"], dict):
+        block = raw.get("site_branding") if isinstance(raw.get("site_branding"), dict) else {}
+        for key in ("title", "description", "theme_color"):
+            if key in body["site_branding"]:
+                block[key] = str(body["site_branding"].get(key) or "").strip()
+        raw["site_branding"] = block
+    _write_raw(raw)
+    return get_stack_config()
+
+
+def resolve_deployment_mode(env_default: str = "trusted_team") -> str:
+    """Explicit WORKFRAME_DEPLOYMENT_MODE env wins; stack_config applies only when env is unset."""
+    env_raw = (os.environ.get("WORKFRAME_DEPLOYMENT_MODE") or "").strip().lower()
+    if env_raw in DEPLOYMENT_MODES:
+        return env_raw
+    if env_raw:
+        return env_raw
+    try:
+        sc_mode = str(get_stack_config().get("deployment_mode") or "").strip().lower()
+        if sc_mode in DEPLOYMENT_MODES:
+            return sc_mode
+    except Exception:
+        pass
+    raw = (env_default or "trusted_team").strip().lower()
+    return raw if raw in DEPLOYMENT_MODES else "trusted_team"
+
+
+def effective_deployment_mode(env_default: str) -> str:
+    return resolve_deployment_mode(env_default)
+
+
+def resolved_smtp() -> dict[str, Any]:
+    """Env wins for host; secrets/from fall back to stack file when env omits them."""
+    stack = _stack_smtp_raw()
+    stack_host = str(stack.get("host") or "").strip()
+    stack_user = str(stack.get("user") or "").strip()
+    stack_pw = str(stack.get("password") or "").strip().replace(" ", "")
+    stack_from = str(stack.get("from") or "").strip()
+
+    env_host = os.environ.get("SMTP_HOST", "").strip()
+    if env_host:
+        port = int(os.environ.get("SMTP_PORT", "587"))
+        secure = normalize_smtp_secure(
+            port,
+            os.environ.get("SMTP_SECURE", "").strip().lower(),
+        )
+        user = os.environ.get("SMTP_USER", "").strip() or stack_user
+        password = (
+            os.environ.get("SMTP_PASSWORD") or os.environ.get("SMTP_PASS") or stack_pw or ""
+        ).strip().replace(" ", "")
+        from_addr = (
+            os.environ.get("SMTP_FROM") or os.environ.get("EMAIL_FROM") or stack_from or user or ""
+        ).strip()
+        return {
+            "host": env_host,
+            "port": port,
+            "user": user,
+            "password": password,
+            "from": from_addr or user,
+            "secure": secure,
+            "source": "env",
+        }
+
+    if not stack_host:
+        return {"source": "none"}
+    port = int(stack.get("port") or 587)
+    user = stack_user
+    return {
+        "host": stack_host,
+        "port": port,
+        "user": user,
+        "password": stack_pw,
+        "from": stack_from or user,
+        "secure": normalize_smtp_secure(port, str(stack.get("secure") or "starttls")),
+        "source": "stack_config",
+    }
+
+
+def smtp_configured() -> bool:
+    s = resolved_smtp()
+    return bool(s.get("host") and s.get("source") != "none")
+
+
+def smtp_tested() -> bool:
+    stack = _stack_smtp_raw()
+    return bool(stack.get("tested"))
+
+
+def smtp_has_password() -> bool:
+    stack = _stack_smtp_raw()
+    if str(stack.get("password") or "").strip():
+        return True
+    resolved = resolved_smtp()
+    return bool(str(resolved.get("password") or "").strip())
+
+
+def smtp_setup_complete() -> bool:
+    """SMTP tested and admin email saved — wizard may skip re-test."""
+    if not smtp_tested():
+        return False
+    stack = _stack_smtp_raw()
+    return bool(str(stack.get("admin_email") or "").strip()) and smtp_has_password() and smtp_configured()
+
+
+def mark_smtp_tested() -> None:
+    raw = _read_raw()
+    smtp = dict(raw.get("smtp") if isinstance(raw.get("smtp"), dict) else {})
+    smtp["tested"] = True
+    raw["smtp"] = smtp
+    _write_raw(raw)
+
+
+def _site_branding_public_payload() -> dict[str, Any]:
+    try:
+        import site_meta
+
+        return site_meta.site_branding_public()
+    except Exception:
+        return {
+            "title": "",
+            "description": "",
+            "theme_color": "",
+            "has_og_image": False,
+            "has_favicon": False,
+        }
+
+
+def public_stack_payload() -> dict[str, Any]:
+    cfg = get_stack_config()
+    smtp = cfg.get("smtp") or {}
+    go = cfg.get("google_oauth") or {}
+    gh = cfg.get("github_oauth") or {}
+    dc = cfg.get("discord_oauth") or {}
+    tg = cfg.get("telegram_login") or {}
+    st = cfg.get("stripe_connect") or {}
+    app_base = str(cfg.get("app_base_url") or "").strip().rstrip("/")
+    domain = ""
+    if app_base:
+        try:
+            from urllib.parse import urlparse
+
+            domain = (urlparse(app_base).hostname or "").strip()
+        except Exception:
+            domain = ""
+    return {
+        "deployment_mode": cfg.get("deployment_mode") or "",
+        "app_base_url": cfg.get("app_base_url") or "",
+        "install_complete": bool(cfg.get("install_complete")),
+        "smtp": {
+            "provider": smtp.get("provider") or "",
+            "host": smtp.get("host") or "",
+            "port": smtp.get("port") or 587,
+            "user": smtp.get("user") or "",
+            "from": smtp.get("from") or "",
+            "admin_email": smtp.get("admin_email") or "",
+            "secure": smtp.get("secure") or "starttls",
+            "configured": smtp_configured(),
+            "tested": smtp_tested(),
+            "setup_complete": smtp_setup_complete(),
+            "has_password": smtp_has_password(),
+        },
+        "google_oauth": {
+            "client_id": go.get("client_id") or "",
+            "has_secret": bool(go.get("has_secret")),
+            "enabled": bool(go.get("enabled")),
+        },
+        "github_oauth": {
+            "client_id": gh.get("client_id") or "",
+            "has_secret": bool(gh.get("has_secret")),
+            "enabled": bool(gh.get("enabled")),
+        },
+        "discord_oauth": {
+            "client_id": dc.get("client_id") or "",
+            "has_secret": bool(dc.get("has_secret")),
+            "enabled": bool(dc.get("enabled")),
+        },
+        "telegram_login": {
+            "bot_username": tg.get("bot_username") or "",
+            "has_token": bool(tg.get("has_token")),
+            "enabled": bool(tg.get("enabled")),
+            "domain": domain,
+        },
+        "stripe_connect": {
+            "client_id": st.get("client_id") or "",
+            "has_secret": bool(st.get("has_secret")),
+            "enabled": bool(st.get("enabled")),
+        },
+        "site_branding": _site_branding_public_payload(),
+    }

package/workframe-api/tests/db_setup.py

@@ -0,0 +1,13 @@
+"""Ensure workframe.db schema exists in isolated test temp dirs."""
+import server
+
+
+def ensure_workframe_schemas() -> None:
+    server._ensure_workframe_db_schema()
+    server._ensure_agent_runs_schema()
+    server._ensure_invites_schema()
+    server._ensure_memory_schema()
+    server._ensure_policies_schema()
+    server._ensure_budgets_grants_schema()
+    server._ensure_user_prefs_schema()
+    server._ensure_runtime_tokens_table()

package/workframe-api/tests/test_admin_updates_gated.py

@@ -0,0 +1,30 @@
+import os
+import unittest
+from unittest import mock
+
+import updates
+
+
+class AdminUpdatesGatedTests(unittest.TestCase):
+  def test_apply_update_disabled_without_flag(self) -> None:
+    with mock.patch.dict(os.environ, {"WORKFRAME_ENABLE_ADMIN_UPDATES": "0"}, clear=False):
+      with self.assertRaises(ValueError) as ctx:
+        updates.apply_update("workframe")
+      self.assertIn("admin_updates_disabled", str(ctx.exception))
+
+  def test_apply_update_enabled_with_flag(self) -> None:
+    with mock.patch.dict(os.environ, {"WORKFRAME_ENABLE_ADMIN_UPDATES": "1"}, clear=False):
+      with mock.patch.object(updates.Path, "exists", return_value=False):
+        with self.assertRaises(ValueError) as ctx:
+          updates.apply_update("workframe")
+        self.assertIn("docker_unavailable", str(ctx.exception))
+
+  def test_restart_gateway_disabled_without_flag(self) -> None:
+    with mock.patch.dict(os.environ, {"WORKFRAME_ENABLE_ADMIN_UPDATES": "0"}, clear=False):
+      with self.assertRaises(ValueError) as ctx:
+        updates.restart_gateway()
+      self.assertIn("admin_updates_disabled", str(ctx.exception))
+
+
+if __name__ == "__main__":
+  unittest.main()

package/workframe-api/tests/test_agent_dm_bootstrap.py

@@ -0,0 +1,196 @@
+"""Agent DM lane bootstrap — runtime + room + session parity with install complete."""
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import server
+from db_setup import ensure_workframe_schemas
+
+
+class AgentDmBootstrapTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        data = Path(self.tmp.name) / "data"
+        data.mkdir()
+        self.patches = [
+            mock.patch.object(server, "DATA_DIR", data),
+            mock.patch.object(server, "AUTH_DB_PATH", data / "auth.db"),
+            mock.patch.object(server, "_workframe_db_path", return_value=data / "workframe.db"),
+            mock.patch.dict(os.environ, {"WORKFRAME_PROJECT": "Workframe"}, clear=False),
+        ]
+        for patch in self.patches:
+            patch.start()
+            self.addCleanup(patch.stop)
+        ensure_workframe_schemas()
+        self.workspace_id = "ws-1"
+        self.user_id = "user-1"
+        self.agent_id = "a0000000-0000-4000-8000-000000000001"
+        self.agent_slug = "dev"
+        conn = server._workframe_db()
+        try:
+            now = "1"
+            conn.execute(
+                "INSERT INTO workspaces (id, slug, display_name, owner_id, status, created_at, updated_at) VALUES (?,?,?,?,?,?,?)",
+                (self.workspace_id, "default", "Workframe", self.user_id, "active", now, now),
+            )
+            conn.execute(
+                """
+                INSERT INTO agent_profiles (id, workspace_id, slug, display_name, status, created_at, updated_at)
+                VALUES (?, ?, ?, ?, 'available', ?, ?)
+                """,
+                (self.agent_id, self.workspace_id, self.agent_slug, "Dev", now, now),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    @mock.patch.object(server, "ensure_profile_api", return_value={"ok": True, "api_port": 1})
+    @mock.patch.object(server, "room_chat_bind", return_value={"ok": True, "session_id": "sid-1"})
+    @mock.patch.object(server, "_bootstrap_profile_providers", return_value=True)
+    @mock.patch.object(server, "ensure_runtime_profile")
+    @mock.patch.object(server, "resolve_validated_profile", side_effect=lambda slug: slug)
+    def test_bootstrap_creates_agent_profile_row_before_dm_room(
+        self,
+        _resolve,
+        _ensure_runtime,
+        _bootstrap,
+        _bind,
+        _ensure_api,
+    ) -> None:
+        conn = server._workframe_db()
+        try:
+            conn.execute("DELETE FROM agent_profiles WHERE workspace_id = ?", (self.workspace_id,))
+            conn.commit()
+            count = conn.execute(
+                "SELECT COUNT(*) FROM agent_profiles WHERE workspace_id = ? AND slug = ?",
+                (self.workspace_id, self.agent_slug),
+            ).fetchone()[0]
+        finally:
+            conn.close()
+        self.assertEqual(count, 0)
+
+        out = server.bootstrap_agent_dm_lane(self.user_id, self.workspace_id, self.agent_slug)
+        self.assertTrue(out["ok"], out)
+        self.assertTrue(str(out.get("room_id") or "").strip())
+
+        conn = server._workframe_db()
+        try:
+            row = conn.execute(
+                "SELECT id FROM agent_profiles WHERE workspace_id = ? AND slug = ?",
+                (self.workspace_id, self.agent_slug),
+            ).fetchone()
+            room = conn.execute(
+                "SELECT id FROM rooms WHERE workspace_id = ? AND room_type = 'direct' AND deleted_at IS NULL",
+                (self.workspace_id,),
+            ).fetchone()
+        finally:
+            conn.close()
+        self.assertIsNotNone(row)
+        self.assertIsNotNone(room)
+
+    @mock.patch.object(server, "ensure_profile_api", return_value={"ok": True, "api_port": 1})
+    @mock.patch.object(server, "room_chat_bind", return_value={"ok": True, "session_id": "sid-1"})
+    @mock.patch.object(server, "_create_room", return_value=(201, {"ok": True, "room": {"id": "room-dev", "room_type": "direct"}}))
+    @mock.patch.object(server, "_bootstrap_profile_providers", return_value=True)
+    @mock.patch.object(server, "ensure_runtime_profile")
+    @mock.patch.object(server, "resolve_validated_profile", side_effect=lambda slug: slug)
+    def test_bootstrap_agent_dm_lane_end_to_end(
+        self,
+        _resolve,
+        ensure_runtime,
+        _bootstrap,
+        _create_room,
+        _bind,
+        _ensure_api,
+    ) -> None:
+        out = server.bootstrap_agent_dm_lane(self.user_id, self.workspace_id, self.agent_slug)
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["room_id"], "room-dev")
+        self.assertEqual(out["session_id"], "sid-1")
+        ensure_runtime.assert_called_once()
+        _bind.assert_called_once()
+
+    @mock.patch.object(server, "ensure_profile_api", return_value={"ok": True, "api_port": 1})
+    @mock.patch.object(server, "room_chat_bind", return_value={"ok": True, "session_id": "sid-1"})
+    @mock.patch.object(server, "_create_room", return_value=(201, {"ok": True, "room": {"id": "room-dev", "room_type": "direct"}}))
+    @mock.patch.object(server, "_bootstrap_profile_providers", return_value=True)
+    @mock.patch.object(server, "ensure_runtime_profile")
+    @mock.patch.object(server, "resolve_validated_profile", side_effect=lambda slug: slug)
+    def test_bootstrap_skips_second_provider_bootstrap(
+        self,
+        _resolve,
+        _ensure_runtime,
+        bootstrap,
+        _create_room,
+        _bind,
+        ensure_api,
+    ) -> None:
+        server.bootstrap_agent_dm_lane(self.user_id, self.workspace_id, self.agent_slug)
+        bootstrap.assert_called_once()
+        ensure_api.assert_called_once_with(
+            mock.ANY,
+            self.user_id,
+            self.workspace_id,
+            bootstrap_providers=False,
+        )
+
+    @mock.patch.object(server, "ensure_runtime_profile", side_effect=ValueError("gateway down"))
+    @mock.patch.object(server, "resolve_validated_profile", side_effect=lambda slug: slug)
+    def test_bootstrap_agent_dm_lane_runtime_failure(self, _resolve, _ensure) -> None:
+        out = server.bootstrap_agent_dm_lane(self.user_id, self.workspace_id, self.agent_slug)
+        self.assertFalse(out["ok"])
+        self.assertIn("gateway down", str(out.get("error")))
+
+    @mock.patch.object(
+        server,
+        "ensure_profile_api",
+        side_effect=[
+            ValueError("profile api did not become healthy: u-user-dev"),
+            ValueError("profile api did not become healthy: u-user-dev"),
+            {"ok": True, "api_port": 1},
+        ],
+    )
+    @mock.patch.object(server, "room_chat_bind", return_value={"ok": True, "session_id": "sid-1"})
+    @mock.patch.object(server, "_create_room", return_value=(201, {"ok": True, "room": {"id": "room-dev", "room_type": "direct"}}))
+    @mock.patch.object(server, "_bootstrap_profile_providers", return_value=True)
+    @mock.patch.object(server, "ensure_runtime_profile")
+    @mock.patch.object(server, "resolve_validated_profile", side_effect=lambda slug: slug)
+    def test_bootstrap_retries_gateway_start_once(
+        self,
+        _resolve,
+        _ensure_runtime,
+        _bootstrap,
+        _create_room,
+        _bind,
+        ensure_api,
+    ) -> None:
+        out = server.bootstrap_agent_dm_lane(self.user_id, self.workspace_id, self.agent_slug)
+        self.assertTrue(out["ok"])
+        self.assertEqual(ensure_api.call_count, 3)
+
+    @mock.patch.object(server, "ensure_profile_api", return_value={"ok": True, "api_port": 1})
+    @mock.patch.object(server, "room_chat_bind", return_value={})
+    @mock.patch.object(server, "_create_room", return_value=(201, {"ok": True, "room": {"id": "room-dev", "room_type": "direct"}}))
+    @mock.patch.object(server, "_bootstrap_profile_providers", return_value=True)
+    @mock.patch.object(server, "ensure_runtime_profile")
+    @mock.patch.object(server, "resolve_validated_profile", side_effect=lambda slug: slug)
+    def test_bootstrap_bind_failure_returns_ok_false(
+        self,
+        _resolve,
+        ensure_runtime,
+        _bootstrap,
+        _create_room,
+        _bind,
+        _ensure_api,
+    ) -> None:
+        out = server.bootstrap_agent_dm_lane(self.user_id, self.workspace_id, self.agent_slug)
+        self.assertFalse(out["ok"])
+        self.assertEqual(out.get("error"), "room_chat_bind_failed")
+        ensure_runtime.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()