ltcai 4.0.0 → 4.0.1

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "4.0.0"
+__version__ = "4.0.1"

package/latticeai/api/admin.py

@@ -55,6 +55,7 @@ def create_admin_router(
     invite_code: str,
     invite_gate_enabled: bool,
     default_port: int,
+    policy_matrix: Optional[Callable[[], List[Dict[str, object]]]] = None,
 ) -> APIRouter:
     router = APIRouter()
 
@@ -109,16 +110,6 @@ def create_admin_router(
             report["graph"] = {"error": str(e)}
         return report
 
-    # Canonical RBAC capability map — which product areas each role can reach.
-    # This is the real access policy the app enforces, not sample data.
-    _ROLE_CAPS = {
-        "owner": ["all"],
-        "admin": ["users", "policies", "audit", "security", "chat", "search", "files", "pipeline"],
-        "member": ["chat", "search", "files", "pipeline"],
-        "user": ["chat", "search", "files", "pipeline"],
-        "viewer": ["chat", "search"],
-    }
-
     @router.get("/admin/roles")
     async def admin_roles(request: Request):
         _, users = require_admin(request)
@@ -126,13 +117,21 @@ def create_admin_router(
         for email, user in users.items():
             role = (get_user_role(email, users) or "user").lower()
             counts[role] += 1
-        # Always surface the two RBAC tiers the app actually distinguishes so the
-        # matrix is meaningful even before extra users exist.
-        for base in ("admin", "user"):
-            counts.setdefault(base, counts.get(base, 0))
+        matrix = policy_matrix() if policy_matrix else [
+            {"role": "admin", "caps": ["all"]},
+            {"role": "user", "caps": ["chat", "search"]},
+        ]
+        policy_caps = {
+            str(item.get("role") or "user"): list(item.get("caps") or [])
+            for item in matrix
+            if isinstance(item, dict)
+        }
+        for role in policy_caps:
+            counts.setdefault(role, 0)
+        order = {"owner": 0, "admin": 1, "member": 2, "user": 3, "viewer": 4}
         roles = [
-            {"role": role, "members": counts.get(role, 0), "caps": _ROLE_CAPS.get(role, ["chat", "search"])}
-            for role in sorted(counts, key=lambda r: (r != "owner", r != "admin", r))
+            {"role": role, "members": counts.get(role, 0), "caps": policy_caps.get(role, [])}
+            for role in sorted(counts, key=lambda r: (order.get(r, 99), r))
         ]
         return {"roles": roles}
 

package/latticeai/api/agents.py

@@ -14,6 +14,8 @@ from typing import Any, Callable, Dict, List, Optional
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from latticeai.api.ui_redirects import app_redirect
+
 
 class AgentRunRequest(BaseModel):
     goal: str
@@ -41,6 +43,7 @@ def create_agents_router(
     ui_file_response: Optional[Callable[[Path], Any]] = None,
     static_dir: Optional[Path] = None,
     agent_runtime: Any = None,
+    run_executor: Any = None,
 ) -> APIRouter:
     from latticeai.core.multi_agent import AGENT_ROLES, ROLE_AGENT_IDS
     from latticeai.services.agent_runtime import AgentRuntime
@@ -91,12 +94,7 @@ def create_agents_router(
     @router.get("/agents")
     async def agents_page(request: Request):
         require_user(request)
-        if ui_file_response is None or static_dir is None:
-            raise HTTPException(status_code=404, detail="Multi-Agent UI not available.")
-        page = static_dir / "agents.html"
-        if not page.exists():
-            raise HTTPException(status_code=404, detail="Multi-Agent UI not found.")
-        return ui_file_response(page)
+        return app_redirect("agents", request)
 
     @router.get("/agents/api/roles")
     async def agent_roles(request: Request):
@@ -163,6 +161,15 @@ def create_agents_router(
         current_user = require_user(request)
         scope = gate_write(request)
         try:
+            if run_executor is not None:
+                return await run_executor.start_agent(
+                    req.goal,
+                    user_email=current_user or None,
+                    scope=scope,
+                    roles=req.roles or None,
+                    inputs=req.inputs,
+                    max_retries=req.max_retries,
+                )
             # Worker thread: an LLM-backed run blocks on model generation and
             # must not stall the event loop (the sync model bridge also
             # requires a loop-free thread).

package/latticeai/api/auth.py

@@ -12,6 +12,7 @@ from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse, RedirectResponse
 from pydantic import BaseModel
 
+from latticeai.core.users import normalize_email
 from latticeai.core.oidc import (
     OIDCValidationError,
     fetch_jwks as _default_fetch_jwks,
@@ -66,6 +67,7 @@ def create_auth_router(
     open_registration: bool,
     session_ttl: int,
     require_auth: bool = True,
+    ensure_identity: Optional[Callable[[str, Dict], None]] = None,
     verify_id_token: Callable[..., Dict] = _default_verify_id_token,
     fetch_jwks: Callable[[str], Awaitable[Dict]] = _default_fetch_jwks,
 ) -> APIRouter:
@@ -87,17 +89,20 @@ def create_auth_router(
         if not open_registration:
             raise HTTPException(status_code=403, detail="회원가입이 비활성화되어 있습니다. 관리자에게 문의하세요.")
         _enforce_password_policy(req.password)
+        email = normalize_email(req.email)
         users = load_users()
-        if req.email in users:
+        if email in users:
             raise HTTPException(status_code=400, detail="이미 존재하는 이메일입니다.")
         role = "admin" if not users else "user"
-        users[req.email] = {
+        users[email] = {
             "password": hash_password(req.password),
             "name": req.name,
             "nickname": req.nickname,
             "role": role,
             "disabled": False,
         }
+        if ensure_identity is not None:
+            ensure_identity(email, users[email])
         save_users(users)
         msg = "회원가입 성공! 첫 번째 사용자로 관리자 권한이 부여되었습니다." if role == "admin" else "회원가입 성공!"
         return {"status": "ok", "message": msg, "role": role}
@@ -105,19 +110,20 @@ def create_auth_router(
     @router.post("/login")
     async def login(req: UserLogin, request: Request):
         check_ip_rate_limit(client_ip(request), "login", max_calls=10, window_secs=300)
+        email = normalize_email(req.email)
         users = load_users()
-        user = users.get(req.email)
-        if not user or not verify_and_migrate(req.email, req.password, user.get("password", ""), users):
+        user = users.get(email)
+        if not user or not verify_and_migrate(email, req.password, user.get("password", ""), users):
             raise HTTPException(status_code=401, detail="이메일 또는 비밀번호가 틀렸습니다.")
         if user.get("disabled"):
             raise HTTPException(status_code=403, detail="비활성화된 계정입니다.")
-        role = get_user_role(req.email, users)
-        token = create_session(req.email)
+        role = get_user_role(email, users)
+        token = create_session(email)
         response = JSONResponse(content={
             "status": "ok",
             "nickname": user["nickname"],
             "name": user["name"],
-            "email": req.email,
+            "email": email,
             "role": role,
             "is_admin": role == "admin",
         })
@@ -202,7 +208,7 @@ def create_auth_router(
         except Exception as exc:  # discovery/JWKS fetch failure → fail closed
             logging.warning("SSO token validation error: %s", exc)
             raise HTTPException(status_code=502, detail="SSO 공급자 검증에 실패했습니다.")
-        email = payload.get("email") or payload.get("preferred_username") or payload.get("upn") or ""
+        email = normalize_email(payload.get("email") or payload.get("preferred_username") or payload.get("upn") or "")
         if not email:
             raise HTTPException(status_code=400, detail="이메일을 확인할 수 없습니다.")
         users = load_users()
@@ -216,6 +222,8 @@ def create_auth_router(
                 "disabled": False,
                 "sso": True,
             }
+            if ensure_identity is not None:
+                ensure_identity(email, users[email])
             save_users(users)
         if users[email].get("disabled"):
             raise HTTPException(status_code=403, detail="비활성화된 계정입니다.")
@@ -235,7 +243,7 @@ def create_auth_router(
 
     @router.post("/account/change-password")
     async def change_password(req: ChangePasswordRequest, request: Request):
-        email = require_user(request)
+        email = normalize_email(require_user(request))
         if not email:
             raise HTTPException(status_code=401, detail="인증이 필요합니다.")
         _enforce_password_policy(req.new_password)
@@ -251,7 +259,7 @@ def create_auth_router(
 
     @router.patch("/account/profile")
     async def update_profile(req: UpdateProfileRequest, request: Request):
-        email = require_user(request)
+        email = normalize_email(require_user(request))
         if not email:
             raise HTTPException(status_code=401, detail="인증이 필요합니다.")
         if req.name is not None and not req.name.strip():
@@ -271,7 +279,7 @@ def create_auth_router(
 
     @router.get("/account/profile")
     async def get_profile(request: Request):
-        email = require_user(request)
+        email = normalize_email(require_user(request))
         if not email:
             if require_auth:
                 raise HTTPException(status_code=401, detail="인증이 필요합니다.")

package/latticeai/api/invitations.py

@@ -0,0 +1,100 @@
+"""Invitation API: create, list, and accept workspace invitations."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+
+class InvitationCreateRequest(BaseModel):
+    email: Optional[str] = None
+    workspace_id: Optional[str] = None
+    role: str = "member"
+    expires_hours: int = 168
+
+
+def create_invitations_router(
+    *,
+    invitation_store,
+    workspace_service,
+    require_admin: Callable,
+    require_user: Callable[[Request], str],
+    user_id_for_email: Callable[[Optional[str]], Optional[str]],
+    append_audit_event: Callable[..., None],
+) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/invitations")
+    async def list_invitations(request: Request):
+        require_admin(request)
+        return {"invitations": invitation_store.list()}
+
+    @router.post("/invitations")
+    async def create_invitation(req: InvitationCreateRequest, request: Request):
+        admin_email, _ = require_admin(request)
+        actor_id = user_id_for_email(admin_email)
+        if req.workspace_id:
+            try:
+                workspace_service.store._require_permission(
+                    workspace_service.store._load_org(workspace_service.store.load_state(), req.workspace_id),
+                    actor_id,
+                    "manage_members",
+                )
+            except FileNotFoundError as exc:
+                raise HTTPException(status_code=404, detail=f"Workspace not found: {req.workspace_id}") from exc
+            except ValueError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+            except PermissionError as exc:
+                raise HTTPException(status_code=403, detail=str(exc)) from exc
+        if req.role not in {"owner", "admin", "member", "viewer"}:
+            raise HTTPException(status_code=400, detail="unknown invitation role")
+        invitation = invitation_store.create(
+            email=req.email,
+            workspace_id=req.workspace_id,
+            role=req.role,
+            created_by=actor_id,
+            expires_hours=req.expires_hours,
+        )
+        append_audit_event(
+            "invitation_created",
+            user_email=admin_email,
+            invitation_id=invitation.get("id"),
+            workspace_id=req.workspace_id,
+            role=req.role,
+        )
+        return {"invitation": invitation}
+
+    @router.post("/invitations/{token}/accept")
+    async def accept_invitation(token: str, request: Request):
+        email = require_user(request)
+        user_id = user_id_for_email(email)
+        if not user_id:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        try:
+            invitation = invitation_store.accept(token, accepted_by=user_id, email=email or None)
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=404, detail="Invitation not found") from exc
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc)) from exc
+        workspace_id = invitation.get("workspace_id")
+        if workspace_id:
+            try:
+                workspace_service.add_member(
+                    workspace_id,
+                    user_id=user_id,
+                    role=invitation.get("role") or "member",
+                    actor=invitation.get("created_by"),
+                )
+            except Exception as exc:
+                raise HTTPException(status_code=409, detail=str(exc)) from exc
+        append_audit_event(
+            "invitation_accepted",
+            user_email=email,
+            invitation_id=invitation.get("id"),
+            workspace_id=workspace_id,
+        )
+        return {"invitation": invitation}
+
+    return router

package/latticeai/api/knowledge_graph.py

@@ -10,9 +10,10 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Optional
 
 from fastapi import APIRouter, HTTPException, Request
-from fastapi.responses import FileResponse
 from pydantic import BaseModel
 
+from latticeai.api.ui_redirects import app_redirect
+
 
 class KnowledgeGraphIngestRequest(BaseModel):
     type: str
@@ -44,22 +45,14 @@ def create_knowledge_graph_router(
         """Serve the interactive knowledge graph canvas UI."""
         graph()
         require_user(request)
-        response = FileResponse(static_dir / "graph.html")
-        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
-        response.headers["Pragma"] = "no-cache"
-        response.headers["Expires"] = "0"
-        return response
+        return app_redirect("knowledge-graph", request)
 
     @router.get("/knowledge-graph")
     async def knowledge_graph_legacy_page(request: Request):
         """Backward-compatible route for the graph page."""
         graph()
         require_user(request)
-        response = FileResponse(static_dir / "graph.html")
-        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
-        response.headers["Pragma"] = "no-cache"
-        response.headers["Expires"] = "0"
-        return response
+        return app_redirect("knowledge-graph", request)
 
     @router.post("/knowledge-graph/curate")
     async def knowledge_graph_curate(request: Request):

package/latticeai/api/plugins.py

@@ -15,6 +15,8 @@ from typing import Any, Callable, Dict, Optional
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from latticeai.api.ui_redirects import app_redirect
+
 
 class PluginActionRequest(BaseModel):
     plugin_id: str
@@ -50,12 +52,7 @@ def create_plugins_router(
     @router.get("/plugins/sdk")
     async def plugins_sdk_page(request: Request):
         require_user(request)
-        if ui_file_response is None or static_dir is None:
-            raise HTTPException(status_code=404, detail="Plugin SDK UI not available.")
-        page = static_dir / "plugins.html"
-        if not page.exists():
-            raise HTTPException(status_code=404, detail="Plugin SDK UI not found.")
-        return ui_file_response(page)
+        return app_redirect("marketplace", request)
 
     @router.get("/plugins/registry")
     async def plugins_registry(request: Request):

package/latticeai/api/realtime.py

@@ -12,10 +12,12 @@ import secrets
 from pathlib import Path
 from typing import Any, Callable, Optional, Set
 
-from fastapi import APIRouter, HTTPException, Request
+from fastapi import APIRouter, Request
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 
+from latticeai.api.ui_redirects import app_redirect
+
 
 class PresenceRequest(BaseModel):
     client_id: Optional[str] = None
@@ -36,12 +38,7 @@ def create_realtime_router(
     @router.get("/activity")
     async def activity_page(request: Request):
         require_user(request)
-        if ui_file_response is None or static_dir is None:
-            raise HTTPException(status_code=404, detail="Activity UI not available.")
-        page = static_dir / "activity.html"
-        if not page.exists():
-            raise HTTPException(status_code=404, detail="Activity UI not found.")
-        return ui_file_response(page)
+        return app_redirect("activity", request)
 
     @router.get("/realtime/stream")
     async def realtime_stream(request: Request):

package/latticeai/api/static_routes.py

@@ -10,6 +10,8 @@ from typing import Callable, Optional
 from fastapi import APIRouter, Cookie, HTTPException, Request
 from fastapi.responses import FileResponse, HTMLResponse
 
+from latticeai.api.ui_redirects import app_redirect
+
 def ui_file_response(path: Path) -> FileResponse:
     response = FileResponse(path)
     response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
@@ -44,15 +46,15 @@ def create_static_routes_router(
     async def root(request: Request, code: Optional[str] = None, authorized: Optional[str] = Cookie(None)):
         """로그인/회원가입 페이지. 초대 게이트 활성화 시 코드 검증 후 진입."""
         if not INVITE_GATE_ENABLED:
-            return ui_file_response(STATIC_DIR / "account.html")
+            return app_redirect("account", request)
     
         # 1. 이미 쿠키로 인증된 경우
         if authorized == "true":
-            return ui_file_response(STATIC_DIR / "account.html")
+            return app_redirect("account", request)
     
         # 2. 초대 코드가 일치하는 경우 (최초 진입)
         if code == INVITE_CODE:
-            response = ui_file_response(STATIC_DIR / "account.html")
+            response = app_redirect("account", request)
             response.set_cookie(key="authorized", value="true", httponly=True, samesite="lax", max_age=60*60*24*7)
             return response
     
@@ -72,7 +74,7 @@ def create_static_routes_router(
     @api_router.get("/account")
     async def account_page():
         """Direct login/register page route used by logout and manual navigation."""
-        return ui_file_response(STATIC_DIR / "account.html")
+        return app_redirect("account")
     
     
     @api_router.get("/manifest.json")
@@ -105,7 +107,7 @@ def create_static_routes_router(
     
     @api_router.get("/chat")
     async def chat_page(request: Request):
-        return ui_file_response(STATIC_DIR / "chat.html")
+        return app_redirect("chat", request)
 
 
     @api_router.get("/app")
@@ -118,13 +120,8 @@ def create_static_routes_router(
 
 
     @api_router.get("/admin")
-    async def admin_page():
-        admin_path = STATIC_DIR / "admin.html"
-        if not admin_path.exists():
-            raise HTTPException(status_code=404, detail="Admin UI not found.")
-        response = FileResponse(admin_path)
-        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
-        return response
+    async def admin_page(request: Request):
+        return app_redirect("admin/users", request)
     
     # /workspace and /onboarding UI pages are served by the workspace router
     # (latticeai.api.workspace), included below after its dependencies are defined.

package/latticeai/api/ui_redirects.py

@@ -0,0 +1,26 @@
+"""Compatibility redirects from retired legacy pages into the v4 SPA."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import Request
+from fastapi.responses import RedirectResponse
+
+
+def app_redirect(fragment: str, request: Optional[Request] = None) -> RedirectResponse:
+    """Redirect a legacy GET route to the equivalent /app hash route.
+
+    Existing browser bookmarks keep working while the legacy HTML/JS/CSS pages
+    are removed from the shipped artifact. Query strings are preserved after the
+    hash so SPA route params remain addressable.
+    """
+
+    frag = fragment.strip("/")
+    query = ""
+    if request is not None and request.url.query:
+        query = f"?{request.url.query}"
+    return RedirectResponse(url=f"/app#/{frag}{query}", status_code=308)
+
+
+__all__ = ["app_redirect"]

package/latticeai/api/workflow_designer.py

@@ -19,6 +19,8 @@ from typing import Any, Callable, Dict, List, Optional
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from latticeai.api.ui_redirects import app_redirect
+
 
 class WorkflowDefinitionRequest(BaseModel):
     name: str
@@ -62,6 +64,8 @@ def create_workflow_designer_router(
     ui_file_response: Optional[Callable[[Path], Any]] = None,
     static_dir: Optional[Path] = None,
     hooks: Any = None,
+    run_executor: Any = None,
+    trigger_service: Any = None,
 ) -> APIRouter:
     from latticeai.core.workflow_engine import (
         WorkflowEngine,
@@ -76,12 +80,7 @@ def create_workflow_designer_router(
     @router.get("/workflows")
     async def workflows_page(request: Request):
         require_user(request)
-        if ui_file_response is None or static_dir is None:
-            raise HTTPException(status_code=404, detail="Workflow Designer UI not available.")
-        page = static_dir / "workflows.html"
-        if not page.exists():
-            raise HTTPException(status_code=404, detail="Workflow Designer UI not found.")
-        return ui_file_response(page)
+        return app_redirect("workflows", request)
 
     @router.get("/workflows/api/definitions")
     async def list_definitions(request: Request, q: str = ""):
@@ -151,6 +150,16 @@ def create_workflow_designer_router(
             workflow = store.get_workflow(workflow_id, workspace_id=scope)
         except FileNotFoundError as exc:
             raise HTTPException(status_code=404, detail=f"Workflow not found: {exc}") from exc
+        if run_executor is not None:
+            result = await run_executor.start_workflow(
+                workflow,
+                workflow_id=workflow_id,
+                user_email=current_user or None,
+                scope=scope,
+                inputs=req.inputs,
+            )
+            append_audit_event("workflow_run_queued", user_email=current_user, workflow_id=workflow_id, status="queued")
+            return result
         runners = build_runners(current_user or None, scope)
         engine = WorkflowEngine(runners, hooks=hooks)
         result = engine.run(workflow, inputs=req.inputs)
@@ -170,6 +179,23 @@ def create_workflow_designer_router(
         append_audit_event("workflow_run", user_email=current_user, workflow_id=workflow_id, status=result.status)
         return {"run": run, "result": result.as_dict()}
 
+    @router.post("/workflows/api/runs/{run_id}/stop")
+    async def stop_run(run_id: str, request: Request):
+        require_user(request)
+        scope = gate_write(request)
+        if run_executor is None:
+            try:
+                run = store.get_workflow_run(run_id, workspace_id=scope)
+            except FileNotFoundError as exc:
+                raise HTTPException(status_code=404, detail=f"Workflow run not found: {run_id}") from exc
+            return {
+                "stopped": False,
+                "reason": "asynchronous cancellation is not supported by the synchronous runtime",
+                "run_id": run_id,
+                "status": run.get("status"),
+            }
+        return run_executor.cancel(run_id, kind="workflow", scope=scope)
+
     @router.post("/workflows/api/runs/{run_id}/resume")
     async def resume_run(run_id: str, req: WorkflowResumeRequest, request: Request):
         """Decide a paused (awaiting_approval) run: approve → the paused node
@@ -221,6 +247,13 @@ def create_workflow_designer_router(
         scope = gate_read(request)
         return store.list_workflow_runs(limit=limit, workspace_id=scope)
 
+    @router.get("/workflows/api/triggers")
+    async def trigger_status(request: Request):
+        require_user(request)
+        if trigger_service is None:
+            return {"running": False, "tick_seconds": None, "armed": []}
+        return trigger_service.describe()
+
     @router.get("/workflows/api/runs/{run_id}/replay")
     async def workflow_run_replay(run_id: str, request: Request):
         require_user(request)

package/latticeai/api/workspace.py

@@ -20,6 +20,7 @@ from typing import Dict, List, Optional
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from latticeai.api.ui_redirects import app_redirect
 from latticeai.services.app_context import AppContext
 
 
@@ -161,7 +162,6 @@ def create_workspace_router(context: AppContext) -> APIRouter:
     remove_skill_directory = context.remove_skill_directory
     redact_secret_text = context.redact_secret_text
     capability_registry = context.capability_registry
-    ui_file_response = context.ui_file_response
 
     svc = service
     WORKSPACE_OS = service.store
@@ -173,7 +173,6 @@ def create_workspace_router(context: AppContext) -> APIRouter:
     KNOWLEDGE_GRAPH = context.knowledge_graph
     LOCAL_KG_WATCHER = context.local_kg_watcher
     SKILLS_DIR = context.skills_dir
-    STATIC_DIR = context.static_dir
     LOCAL_MODEL = context.local_model
     PUBLIC_MODEL = context.public_model
     _fetch_skills_marketplace = context.fetch_skills_marketplace
@@ -214,18 +213,12 @@ def create_workspace_router(context: AppContext) -> APIRouter:
     @router.get("/workspace")
     async def workspace_page(request: Request):
         require_user(request)
-        workspace_path = STATIC_DIR / "workspace.html"
-        if not workspace_path.exists():
-            raise HTTPException(status_code=404, detail="Workspace OS UI not found.")
-        return ui_file_response(workspace_path)
+        return app_redirect("workspace-admin", request)
 
     @router.get("/onboarding")
     async def onboarding_page(request: Request):
         require_user(request)
-        workspace_path = STATIC_DIR / "workspace.html"
-        if not workspace_path.exists():
-            raise HTTPException(status_code=404, detail="Workspace OS UI not found.")
-        return ui_file_response(workspace_path)
+        return app_redirect("workspace-admin", request)
 
     # ── Workspace OS summary / onboarding ─────────────────────────────────
 
@@ -387,6 +380,27 @@ def create_workspace_router(context: AppContext) -> APIRouter:
         append_audit_event("workspace_snapshot_export", user_email=current_user, snapshot_id=snapshot_id, path=result.get("export_path"))
         return result
 
+    @router.post("/workspace/snapshots/{snapshot_id}/restore")
+    async def workspace_snapshot_restore(snapshot_id: str, request: Request):
+        current_user = require_user(request)
+        snapshot = _load_snapshot_authorized(request, snapshot_id)
+        scope = _gate_write(request)
+        if snapshot.get("workspace_id") and snapshot.get("workspace_id") != scope:
+            raise HTTPException(status_code=403, detail="snapshot belongs to a different workspace")
+        try:
+            result = WORKSPACE_OS.restore_snapshot(
+                snapshot_id,
+                graph=_workspace_graph(),
+                workspace_id=scope,
+                user_email=current_user or None,
+            )
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=404, detail=f"Snapshot not found: {exc}") from exc
+        except ValueError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        append_audit_event("workspace_snapshot_restore", user_email=current_user, snapshot_id=snapshot_id, restore_id=result.get("restore", {}).get("id"))
+        return result
+
     @router.get("/workspace/time-machine")
     async def workspace_time_machine(request: Request, limit: int = 100):
         require_user(request)