ltcai 1.1.0 → 1.3.0

package/latticeai/server_app.py

@@ -101,6 +101,13 @@ from latticeai.core.enterprise import (
     capability_registry,
     detect_edition,
 )
+from latticeai.services.workspace_service import WorkspaceService
+from latticeai.services.model_service import ModelService
+from latticeai.services.chat_service import ChatService
+from latticeai.api.workspace import create_workspace_router
+from latticeai.api.health import create_health_router
+from latticeai.api.models import create_models_router
+from latticeai.api.mcp import create_mcp_router
 from latticeai.core.agent import (
     AgentState,
     AgentRunContext,
@@ -357,6 +364,9 @@ SSO_FILE = DATA_DIR / "sso_config.json"
 KNOWLEDGE_GRAPH = KnowledgeGraphStore(DATA_DIR / "knowledge_graph.sqlite", DATA_DIR / "knowledge_graph_blobs") if ENABLE_GRAPH else None
 LOCAL_KG_WATCHER = LocalKnowledgeWatcher(lambda: KNOWLEDGE_GRAPH) if ENABLE_GRAPH else None
 WORKSPACE_OS = WorkspaceOSStore(DATA_DIR)
+# Service layer (latticeai.services) wraps the store with scope/permission
+# guardrails; routers and the app assembly share this single instance.
+WORKSPACE_SERVICE = WorkspaceService(WORKSPACE_OS)
 
 def _require_graph():
     if not ENABLE_GRAPH or KNOWLEDGE_GRAPH is None:
@@ -455,25 +465,7 @@ def save_sso_config(update: Dict[str, object]) -> Dict[str, object]:
     _sso_discovery_cache_url = ""
     return current
 
-class McpRecommendRequest(BaseModel):
-    query: str
-    limit: int = 5
-
-class McpInstallRequest(BaseModel):
-    mcp_id: str
-
-class McpCustomRequest(BaseModel):
-    name: str
-    package: str
-    description: str = ""
-    category: str = "custom"
-    icon: str = "🔌"
-    env_vars: List[Dict] = []
-
-class SkillInstallRequest(BaseModel):
-    plugin: str
-    skill: str
-
+# MCP/skill request models moved to latticeai.api.mcp (v1.3.0).
 DEFAULT_VPC_CONFIG = {
     "provider": "AWS",
     "region": "ap-northeast-2",
@@ -727,6 +719,10 @@ def get_history():
         logging.warning("get_history failed: %s", e)
         return []
 
+# Chat service seam: behaviour-preserving façade for history access and
+# Workspace-OS answer-trace recording used by the (unchanged) streaming chat path.
+CHAT_SERVICE = ChatService(store=WORKSPACE_OS, get_history=get_history)
+
 def conversation_title(item: Dict) -> str:
     content = str(item.get("content") or "").strip()
     content = re.sub(r"\s+", " ", content)
@@ -1317,22 +1313,8 @@ async def admin_page():
     response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
     return response
 
-@app.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)
-
-
-@app.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)
+# /workspace and /onboarding UI pages are served by the workspace router
+# (latticeai.api.workspace), included below after its dependencies are defined.
 
 @app.get("/status")
 async def status():
@@ -1406,133 +1388,9 @@ class ChatRequest(BaseModel):
     image_data: Optional[str] = None     # Base64 이미지 데이터 (VLM용)
 
 
-class LoadModelRequest(BaseModel):
-    model_id: str                         # HuggingFace repo id 또는 로컬 경로
-    adapter_path: Optional[str] = None   # LoRA adapter (선택)
-    draft_model_id: Optional[str] = None # Speculative decoding draft model (선택)
-    engine: Optional[str] = None
-    user_email: Optional[str] = None
-
-
-class InstallEngineRequest(BaseModel):
-    engine: str
-
-
-class SetApiKeyRequest(BaseModel):
-    provider: str
-    key: str
-    user_email: Optional[str] = None
-
-
-class PullModelRequest(BaseModel):
-    model: str
-
-class PrepareModelRequest(BaseModel):
-    model: str
-    engine: Optional[str] = None
-    user_email: Optional[str] = None
-
-class VerifyCloudRequest(BaseModel):
-    force: bool = False
-    provider: Optional[str] = None
-
-
-class WorkspaceOnboardingStepRequest(BaseModel):
-    step: str
-    status: str = "complete"
-    data: Dict = {}
-    error: str = ""
-
-
-class WorkspaceOnboardingCompleteRequest(BaseModel):
-    data: Dict = {}
-
-
-class WorkspaceSnapshotRequest(BaseModel):
-    name: str = "Workspace snapshot"
-
-
-class WorkspaceSnapshotCompareRequest(BaseModel):
-    before_id: str
-    after_id: str
-
-
-class WorkspaceMemoryRequest(BaseModel):
-    kind: str
-    content: str
-    tags: List[str] = []
-    memory_id: Optional[str] = None
-    metadata: Dict = {}
-
-
-class WorkspaceAgentRunRequest(BaseModel):
-    agent_id: str = "agent:executor"
-    status: str = "ok"
-    input: str = ""
-    output: str = ""
-    timeline: List[Dict] = []
-    relationships: List[str] = []
-
-
-class WorkspaceWorkflowRequest(BaseModel):
-    name: str
-    steps: List[Dict] = []
-    metadata: Dict = {}
-
-
-class WorkspaceWorkflowEventRequest(BaseModel):
-    event_type: str
-    payload: Dict = {}
-
-
-class WorkspaceComputerMemoryRequest(BaseModel):
-    enabled: bool = False
-    consent: Dict = {}
-    scopes: List[str] = []
-
-
-class WorkspaceComputerActivityRequest(BaseModel):
-    activity: Dict = {}
-
-
-class WorkspaceSkillActionRequest(BaseModel):
-    skill: str
-    plugin: Optional[str] = None
-    enabled: Optional[bool] = None
-    version: Optional[str] = None
-    metadata: Dict = {}
-
-
-class WorkspaceVSCodeRequest(BaseModel):
-    action: str
-    file_path: Optional[str] = None
-    language: Optional[str] = None
-    content: str = ""
-    selection: str = ""
-    prompt: str = ""
-
-
-class WorkspaceCreateRequest(BaseModel):
-    name: str
-    settings: Dict = {}
+# Model/engine request models moved to latticeai.api.models (v1.3.0).
 
-
-class WorkspaceUpdateRequest(BaseModel):
-    name: Optional[str] = None
-    settings: Optional[Dict] = None
-
-
-class WorkspaceMemberRequest(BaseModel):
-    user_id: str
-    role: str = "member"
-
-
-class WorkspaceMemberRoleRequest(BaseModel):
-    role: str
-
-
-class WorkspaceActivateRequest(BaseModel):
-    workspace_id: str
+# Workspace request models moved to latticeai.api.workspace (v1.2.0 modularization).
 
 
 class GardenRequest(BaseModel):
@@ -1687,10 +1545,6 @@ class LocalWriteRequest(BaseModel):
     approval_token: Optional[str] = None
 
 
-class McpCallRequest(BaseModel):
-    action: str
-    args: Dict = {}
-
 
 class ToolGitDiffRequest(BaseModel):
     path: Optional[str] = None
@@ -1736,562 +1590,37 @@ def _workspace_graph():
     return KNOWLEDGE_GRAPH if (ENABLE_GRAPH and KNOWLEDGE_GRAPH) else None
 
 
-def _workspace_scope(request: Request) -> Optional[str]:
-    """Resolve the active workspace for scoping from an optional header/query.
-
-    Returns ``None`` when unset so the store falls back to the active workspace
-    (Personal by default), preserving pre-1.1 behaviour for legacy clients.
-    """
-    header = request.headers.get("X-Workspace-Id")
-    if header and header.strip():
-        return header.strip()
-    query = request.query_params.get("workspace_id")
-    return query.strip() if query and query.strip() else None
-
-
-@app.get("/workspace/os")
-async def workspace_os_summary(request: Request):
-    user = require_user(request)
-    summary = WORKSPACE_OS.summary()
-    summary["graph"] = _graph_stats_safe()
-    summary["models"] = _workspace_models_payload()
-    summary["workspace_registry"] = WORKSPACE_OS.list_workspaces(user_id=user or None)
-    summary["edition"] = capability_registry.describe()
-    return summary
-
-
-@app.get("/workspace/onboarding/status")
-async def workspace_onboarding_status(request: Request):
-    require_user(request)
-    return WORKSPACE_OS.onboarding_status(load_users(), _graph_stats_safe())
-
-
-@app.post("/workspace/onboarding/step")
-async def workspace_onboarding_step(req: WorkspaceOnboardingStepRequest, request: Request):
-    current_user = require_user(request)
-    return WORKSPACE_OS.update_onboarding_step(
-        req.step,
-        status=req.status,
-        data=req.data,
-        error=req.error,
-        user_email=current_user or None,
-    )
-
-
-@app.post("/workspace/onboarding/complete")
-async def workspace_onboarding_complete(req: WorkspaceOnboardingCompleteRequest, request: Request):
-    current_user = require_user(request)
-    append_audit_event("onboarding_complete", user_email=current_user, platform="AI Workspace OS")
-    return WORKSPACE_OS.complete_onboarding(req.data, user_email=current_user or None)
-
-
-@app.get("/workspace/onboarding/hardware")
-async def workspace_onboarding_hardware(request: Request):
-    require_user(request)
-    env = await asyncio.to_thread(scan_environment)
-    sysinfo = await local_sysinfo(request)
-    payload = {"environment": env, "sysinfo": sysinfo, "scanned_at": datetime.now().isoformat()}
-    WORKSPACE_OS.update_onboarding_step("hardware", status="complete", data=payload, user_email=get_current_user(request))
-    return payload
-
-
-@app.get("/workspace/onboarding/model-recommendations")
-async def workspace_onboarding_model_recommendations(request: Request):
-    require_user(request)
-    env = await asyncio.to_thread(scan_environment)
-    recommendations = get_recommendations(env)
-    payload = {
-        "environment": env,
-        "recommendations": recommendations,
-        "default_local_model": LOCAL_MODEL,
-        "default_public_model": PUBLIC_MODEL,
-    }
-    WORKSPACE_OS.update_onboarding_step("model_recommendation", status="complete", data=payload, user_email=get_current_user(request))
-    return payload
-
-
-@app.get("/workspace/traces")
-async def workspace_traces(request: Request, conversation_id: Optional[str] = None, limit: int = 50):
-    require_user(request)
-    return WORKSPACE_OS.list_traces(conversation_id=conversation_id, limit=limit, workspace_id=_workspace_scope(request))
-
-
-@app.get("/workspace/indexing")
-async def workspace_indexing_dashboard(request: Request):
-    require_user(request)
-    graph = _workspace_graph()
-    watcher_status = LOCAL_KG_WATCHER.status() if LOCAL_KG_WATCHER else {"available": False, "active": {}}
-    return WORKSPACE_OS.build_indexing_dashboard(graph, watcher_status)
-
-
-@app.post("/workspace/indexing/{source_id}/pause")
-async def workspace_indexing_pause(source_id: str, request: Request):
-    require_user(request)
-    _require_graph()
-    return WORKSPACE_OS.pause_indexing(KNOWLEDGE_GRAPH, source_id, LOCAL_KG_WATCHER)
-
-
-@app.post("/workspace/indexing/{source_id}/resume")
-async def workspace_indexing_resume(source_id: str, request: Request):
-    require_user(request)
-    _require_graph()
-    return WORKSPACE_OS.resume_indexing(KNOWLEDGE_GRAPH, source_id, LOCAL_KG_WATCHER)
-
-
-@app.post("/workspace/indexing/{source_id}/remove")
-async def workspace_indexing_remove(source_id: str, request: Request):
-    require_user(request)
-    _require_graph()
-    return WORKSPACE_OS.remove_index_source(KNOWLEDGE_GRAPH, source_id, LOCAL_KG_WATCHER)
-
-
-@app.get("/workspace/snapshots")
-async def workspace_snapshots(request: Request):
-    require_user(request)
-    return WORKSPACE_OS.list_snapshots(workspace_id=_workspace_scope(request))
-
-
-@app.post("/workspace/snapshots")
-async def workspace_snapshot_create(req: WorkspaceSnapshotRequest, request: Request):
-    current_user = require_user(request)
-    result = WORKSPACE_OS.create_snapshot(
-        name=req.name,
-        graph=_workspace_graph(),
-        history=get_history(),
-        settings=_workspace_settings_payload(),
-        models=_workspace_models_payload(),
-        workspace_id=_workspace_scope(request),
-    )
-    append_audit_event("workspace_snapshot", user_email=current_user, snapshot_id=result["snapshot"]["id"])
-    return result
-
-
-@app.post("/workspace/snapshots/compare")
-async def workspace_snapshot_compare(req: WorkspaceSnapshotCompareRequest, request: Request):
-    require_user(request)
-    try:
-        return WORKSPACE_OS.compare_snapshots(req.before_id, req.after_id)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Snapshot not found: {exc}") from exc
-
-
-@app.get("/workspace/snapshots/{snapshot_id}")
-async def workspace_snapshot_get(snapshot_id: str, request: Request):
-    require_user(request)
-    try:
-        return WORKSPACE_OS.get_snapshot(snapshot_id)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Snapshot not found: {exc}") from exc
-
-
-@app.get("/workspace/snapshots/{snapshot_id}/{area}")
-async def workspace_snapshot_area(snapshot_id: str, area: str, request: Request):
-    require_user(request)
-    try:
-        return WORKSPACE_OS.snapshot_view(snapshot_id, area)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Snapshot not found: {exc}") from exc
-
-
-@app.post("/workspace/snapshots/{snapshot_id}/export")
-async def workspace_snapshot_export(snapshot_id: str, request: Request):
-    current_user = require_user(request)
-    try:
-        result = WORKSPACE_OS.export_snapshot(snapshot_id)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Snapshot not found: {exc}") from exc
-    append_audit_event("workspace_snapshot_export", user_email=current_user, snapshot_id=snapshot_id, path=result.get("export_path"))
-    return result
-
-
-@app.get("/workspace/time-machine")
-async def workspace_time_machine(request: Request, limit: int = 100):
-    require_user(request)
-    return WORKSPACE_OS.timeline(get_audit_log(), limit=limit, workspace_id=_workspace_scope(request))
-
-
-@app.get("/workspace/time-machine/{snapshot_id}/{area}")
-async def workspace_time_machine_view(snapshot_id: str, area: str, request: Request):
-    require_user(request)
-    try:
-        return WORKSPACE_OS.snapshot_view(snapshot_id, area)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Snapshot not found: {exc}") from exc
-
-
-@app.get("/workspace/memories")
-async def workspace_memories(request: Request, kind: Optional[str] = None):
-    current_user = require_user(request)
-    return WORKSPACE_OS.list_memories(user_email=current_user or None, kind=kind, workspace_id=_workspace_scope(request))
-
-
-@app.get("/workspace/memories/search")
-async def workspace_memory_search(q: str, request: Request, limit: int = 20):
-    current_user = require_user(request)
-    return WORKSPACE_OS.search_memories(q, user_email=current_user or None, limit=limit, workspace_id=_workspace_scope(request))
-
-
-@app.post("/workspace/memories")
-async def workspace_memory_upsert(req: WorkspaceMemoryRequest, request: Request):
-    current_user = require_user(request)
-    try:
-        record = WORKSPACE_OS.upsert_memory(
-            kind=req.kind,
-            content=req.content,
-            tags=req.tags,
-            memory_id=req.memory_id,
-            metadata=req.metadata,
-            user_email=current_user or None,
-            graph=_workspace_graph(),
-            workspace_id=_workspace_scope(request),
-        )
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    return {"memory": record}
-
-
-@app.delete("/workspace/memories/{memory_id}")
-async def workspace_memory_delete(memory_id: str, request: Request):
-    require_user(request)
-    try:
-        return WORKSPACE_OS.delete_memory(memory_id)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Memory not found: {exc}") from exc
-
-
-@app.get("/workspace/agents")
-async def workspace_agents(request: Request):
-    require_user(request)
-    return WORKSPACE_OS.list_agents(workspace_id=_workspace_scope(request))
-
-
-@app.post("/workspace/agents/runs")
-async def workspace_agent_run(req: WorkspaceAgentRunRequest, request: Request):
-    current_user = require_user(request)
-    run = WORKSPACE_OS.record_agent_run(
-        agent_id=req.agent_id,
-        status=req.status,
-        input_text=req.input,
-        output_text=req.output,
-        timeline=req.timeline,
-        relationships=req.relationships,
-        user_email=current_user or None,
-        graph=_workspace_graph(),
-        workspace_id=_workspace_scope(request),
-    )
-    return {"run": run}
-
-
-@app.get("/workspace/relationships/{node_id:path}")
-async def workspace_relationships(node_id: str, request: Request, target_id: Optional[str] = None):
-    require_user(request)
-    _require_graph()
-    return WORKSPACE_OS.relationship_explorer(KNOWLEDGE_GRAPH, node_id, target_id=target_id)
-
-
-@app.get("/workspace/computer-memory")
-async def workspace_computer_memory(request: Request):
-    require_user(request)
-    return WORKSPACE_OS.load_state().get("computer_memory")
-
-
-@app.post("/workspace/computer-memory")
-async def workspace_computer_memory_config(req: WorkspaceComputerMemoryRequest, request: Request):
-    current_user = require_user(request)
-    try:
-        config = WORKSPACE_OS.configure_computer_memory(
-            enabled=req.enabled,
-            approved_by=current_user or None,
-            consent=req.consent,
-            scopes=req.scopes or None,
-        )
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    append_audit_event("computer_memory_config", user_email=current_user, enabled=req.enabled)
-    return {"computer_memory": config}
-
-
-@app.post("/workspace/computer-memory/activity")
-async def workspace_computer_memory_activity(req: WorkspaceComputerActivityRequest, request: Request):
-    require_user(request)
-    return WORKSPACE_OS.record_computer_activity(req.activity, graph=_workspace_graph())
-
-
-@app.get("/workspace/workflows")
-async def workspace_workflows(request: Request, q: str = ""):
-    require_user(request)
-    return WORKSPACE_OS.list_workflows(query=q, workspace_id=_workspace_scope(request))
-
-
-@app.post("/workspace/workflows")
-async def workspace_workflow_create(req: WorkspaceWorkflowRequest, request: Request):
-    current_user = require_user(request)
-    workflow = WORKSPACE_OS.create_workflow(
-        name=req.name,
-        steps=req.steps,
-        metadata=req.metadata,
-        user_email=current_user or None,
-        graph=_workspace_graph(),
-        workspace_id=_workspace_scope(request),
-    )
-    return {"workflow": workflow}
-
-
-@app.post("/workspace/workflows/{workflow_id}/events")
-async def workspace_workflow_event(workflow_id: str, req: WorkspaceWorkflowEventRequest, request: Request):
-    require_user(request)
-    try:
-        return {"workflow": WORKSPACE_OS.record_workflow_event(workflow_id, req.event_type, req.payload)}
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workflow not found: {exc}") from exc
-
-
-@app.get("/workspace/skills")
-async def workspace_skills(request: Request):
-    require_user(request)
-    marketplace = []
-    try:
-        marketplace = await _fetch_skills_marketplace()
-    except Exception as exc:
-        logging.warning("workspace skills marketplace unavailable: %s", exc)
-    return WORKSPACE_OS.list_skill_registry(SKILLS_DIR, marketplace)
-
-
-@app.post("/workspace/skills/install")
-async def workspace_skill_install(req: WorkspaceSkillActionRequest, request: Request):
-    admin_email, _ = require_admin(request)
-    if req.plugin:
-        result = await install_skill(req.plugin, req.skill)
-    else:
-        result = {"status": "recorded", "skill": req.skill}
-    entry = WORKSPACE_OS.mark_skill_installed(req.skill, version=req.version or "local", metadata={"install_result": result, **req.metadata})
-    append_audit_event("skill_install", user_email=admin_email, plugin=req.plugin, skill=req.skill, workspace_os=True)
-    return {"skill": entry, "install": result}
-
-
-@app.post("/workspace/skills/uninstall")
-async def workspace_skill_uninstall(req: WorkspaceSkillActionRequest, request: Request):
-    admin_email, _ = require_admin(request)
-    removal = remove_skill_directory(SKILLS_DIR, req.skill)
-    entry = WORKSPACE_OS.mark_skill_uninstalled(req.skill)
-    append_audit_event("skill_uninstall", user_email=admin_email, skill=req.skill, workspace_os=True)
-    return {"skill": entry, "removal": removal}
-
-
-@app.post("/workspace/skills/enable")
-async def workspace_skill_enable(req: WorkspaceSkillActionRequest, request: Request):
-    require_user(request)
-    return {"skill": WORKSPACE_OS.set_skill_enabled(req.skill, True)}
-
-
-@app.post("/workspace/skills/disable")
-async def workspace_skill_disable(req: WorkspaceSkillActionRequest, request: Request):
-    require_user(request)
-    return {"skill": WORKSPACE_OS.set_skill_enabled(req.skill, False)}
-
-
-@app.post("/workspace/skills/update")
-async def workspace_skill_update(req: WorkspaceSkillActionRequest, request: Request):
-    admin_email, _ = require_admin(request)
-    if req.plugin:
-        result = await install_skill(req.plugin, req.skill)
-    else:
-        result = {"status": "version_recorded", "skill": req.skill}
-    entry = WORKSPACE_OS.mark_skill_installed(req.skill, version=req.version or "latest", metadata={"update_result": result, **req.metadata})
-    append_audit_event("skill_update", user_email=admin_email, plugin=req.plugin, skill=req.skill, workspace_os=True)
-    return {"skill": entry, "update": result}
-
-
-@app.get("/workspace/audit-timeline")
-async def workspace_audit_timeline(
-    request: Request,
-    user: Optional[str] = None,
-    event_type: Optional[str] = None,
-    model: Optional[str] = None,
-    since: Optional[str] = None,
-    until: Optional[str] = None,
-    limit: int = 100,
-):
-    require_admin(request)
-    return WORKSPACE_OS.filter_audit_timeline(
-        get_audit_log(),
-        user=user,
-        event_type=event_type,
-        model=model,
-        since=since,
-        until=until,
-        limit=limit,
-    )
-
-
-@app.post("/workspace/vscode/send")
-async def workspace_vscode_send(req: WorkspaceVSCodeRequest, request: Request):
-    current_user = require_user(request)
-    content = req.selection or req.content or req.prompt
-    workflow = WORKSPACE_OS.create_workflow(
-        name=f"VS Code: {req.action}",
-        steps=[
-            {"action": req.action, "file_path": req.file_path, "language": req.language},
-            {"action": "send_to_lattice", "chars": len(content or "")},
-        ],
-        metadata={
-            "file_path": req.file_path,
-            "language": req.language,
-            "content_preview": redact_secret_text(content or "")[:500],
-        },
-        user_email=current_user or None,
-        graph=_workspace_graph(),
-    )
-    if _workspace_graph() is not None and content:
-        try:
-            _workspace_graph().ingest_event(
-                "VSCodeWorkflow",
-                req.action,
-                user_email=current_user or None,
-                source="vscode",
-                metadata={
-                    "file_path": req.file_path,
-                    "language": req.language,
-                    "chars": len(content),
-                    "workflow_id": workflow["id"],
-                },
-            )
-        except Exception as exc:
-            logging.warning("vscode workflow graph ingest failed: %s", exc)
-    return {"status": "ok", "workflow": workflow}
-
-
-# ── Organization Workspaces, membership, roles, and edition seam ─────────────────
-
-@app.get("/workspace/registry")
-async def workspace_registry(request: Request):
-    user = require_user(request)
-    return WORKSPACE_OS.list_workspaces(user_id=user or None)
-
-
-@app.get("/workspace/editions")
-async def workspace_editions(request: Request):
-    require_user(request)
-    return capability_registry.describe()
-
-
-@app.post("/workspace/activate")
-async def workspace_activate(req: WorkspaceActivateRequest, request: Request):
-    user = require_user(request)
-    try:
-        return WORKSPACE_OS.set_active_workspace(req.workspace_id, user_id=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workspace not found: {exc}") from exc
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-
-
-@app.post("/workspace/orgs")
-async def workspace_org_create(req: WorkspaceCreateRequest, request: Request):
-    user = require_user(request)
-    try:
-        workspace = WORKSPACE_OS.create_organization_workspace(
-            name=req.name,
-            owner_user_id=user or None,
-            settings=req.settings,
-        )
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    append_audit_event("workspace_created", user_email=user, workspace_id=workspace["workspace_id"])
-    return {"workspace": workspace}
-
-
-@app.get("/workspace/orgs/{workspace_id}")
-async def workspace_org_get(workspace_id: str, request: Request):
-    user = require_user(request)
-    try:
-        return {"workspace": WORKSPACE_OS.get_workspace(workspace_id, user_id=user or None)}
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workspace not found: {exc}") from exc
-
-
-@app.get("/workspace/orgs/{workspace_id}/summary")
-async def workspace_org_summary(workspace_id: str, request: Request):
-    user = require_user(request)
-    try:
-        return WORKSPACE_OS.workspace_summary(workspace_id, user_id=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workspace not found: {exc}") from exc
-
-
-@app.patch("/workspace/orgs/{workspace_id}")
-async def workspace_org_update(workspace_id: str, req: WorkspaceUpdateRequest, request: Request):
-    user = require_user(request)
-    try:
-        workspace = WORKSPACE_OS.update_workspace(workspace_id, name=req.name, settings=req.settings, actor=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workspace not found: {exc}") from exc
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    append_audit_event("workspace_updated", user_email=user, workspace_id=workspace_id)
-    return {"workspace": workspace}
-
-
-@app.post("/workspace/orgs/{workspace_id}/archive")
-async def workspace_org_archive(workspace_id: str, request: Request):
-    user = require_user(request)
-    try:
-        workspace = WORKSPACE_OS.archive_workspace(workspace_id, actor=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workspace not found: {exc}") from exc
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    append_audit_event("workspace_archived", user_email=user, workspace_id=workspace_id)
-    return {"workspace": workspace}
-
-
-@app.post("/workspace/orgs/{workspace_id}/members")
-async def workspace_org_add_member(workspace_id: str, req: WorkspaceMemberRequest, request: Request):
-    user = require_user(request)
-    try:
-        workspace = WORKSPACE_OS.add_member(workspace_id, user_id=req.user_id, role=req.role, actor=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Workspace not found: {exc}") from exc
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    append_audit_event("workspace_member_added", user_email=user, workspace_id=workspace_id, member=req.user_id, role=req.role)
-    return {"workspace": workspace}
-
-
-@app.patch("/workspace/orgs/{workspace_id}/members/{user_id}")
-async def workspace_org_update_member(workspace_id: str, user_id: str, req: WorkspaceMemberRoleRequest, request: Request):
-    user = require_user(request)
-    try:
-        workspace = WORKSPACE_OS.update_member_role(workspace_id, user_id=user_id, role=req.role, actor=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Not found: {exc}") from exc
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    append_audit_event("workspace_member_role_updated", user_email=user, workspace_id=workspace_id, member=user_id, role=req.role)
-    return {"workspace": workspace}
-
-
-@app.delete("/workspace/orgs/{workspace_id}/members/{user_id}")
-async def workspace_org_remove_member(workspace_id: str, user_id: str, request: Request):
-    user = require_user(request)
-    try:
-        workspace = WORKSPACE_OS.remove_member(workspace_id, user_id=user_id, actor=user or None)
-    except FileNotFoundError as exc:
-        raise HTTPException(status_code=404, detail=f"Not found: {exc}") from exc
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    append_audit_event("workspace_member_removed", user_email=user, workspace_id=workspace_id, member=user_id)
-    return {"workspace": workspace}
+# ── Workspace OS + Organization router (latticeai.api.workspace, v1.2.0) ──────
+app.include_router(create_workspace_router(
+    service=WORKSPACE_SERVICE,
+    require_user=require_user,
+    require_admin=require_admin,
+    get_current_user=get_current_user,
+    append_audit_event=append_audit_event,
+    graph_stats=_graph_stats_safe,
+    workspace_models=_workspace_models_payload,
+    workspace_settings=_workspace_settings_payload,
+    get_history=get_history,
+    get_audit_log=get_audit_log,
+    require_graph=_require_graph,
+    workspace_graph=_workspace_graph,
+    knowledge_graph=KNOWLEDGE_GRAPH,
+    local_kg_watcher=LOCAL_KG_WATCHER,
+    load_users=load_users,
+    scan_environment=scan_environment,
+    local_sysinfo=local_sysinfo,
+    get_recommendations=get_recommendations,
+    fetch_skills_marketplace=_fetch_skills_marketplace,
+    install_skill=install_skill,
+    remove_skill_directory=remove_skill_directory,
+    redact_secret_text=redact_secret_text,
+    skills_dir=SKILLS_DIR,
+    capability_registry=capability_registry,
+    ui_file_response=ui_file_response,
+    static_dir=STATIC_DIR,
+    local_model=LOCAL_MODEL,
+    public_model=PUBLIC_MODEL,
+))
 
 
 # ── Health & Info ──────────────────────────────────────────────────────────────
@@ -4182,284 +3511,51 @@ async def verify_cloud_models(force: bool = False, provider_filter: Optional[str
         results[model_ref] = record
     return results
 
-@app.get("/health")
-async def health(request: Request):
-    base = {
-        "status": "ok",
-        "version": APP_VERSION,
-        "mode": APP_MODE,
-        "platform": "AI Workspace OS",
-    }
-    if not get_current_user(request) and REQUIRE_AUTH:
-        return base
-    engines = await asyncio.to_thread(engine_status)
-    return {
-        **base,
-        "current_model": router.current_model_id,
-        "loaded_models": router.loaded_model_ids,
-        "device": "Apple Silicon MLX" if not IS_PUBLIC_MODE else "Public cloud/API runtime",
-        "features": runtime_features(),
-        "providers": router.detected_cloud_models(),
-        "engines": engines,
-    }
-
-
-@app.get("/mode")
-@app.get("/runtime_features")
-async def mode():
-    return runtime_features()
-
-
-@app.get("/engines")
-async def engines():
-    return {"engines": await asyncio.to_thread(engine_status), "current": router.current_model_id}
-
-
-@app.post("/engines/install")
-async def engines_install(req: InstallEngineRequest, request: Request):
-    require_user(request)
-    return install_engine(req.engine)
-
-@app.post("/engines/verify-cloud")
-async def engines_verify_cloud(req: VerifyCloudRequest, request: Request):
-    require_user(request)
-    results = await verify_cloud_models(force=req.force, provider_filter=req.provider)
-    return {"verified": results, "ttl_seconds": CLOUD_VERIFY_TTL_SECONDS}
-
-
-@app.post("/engines/pull-model")
-async def pull_ollama_model(req: PullModelRequest, request: Request):
-    require_user(request)
-    model_ref = normalize_local_model_request(req.model, None)
-    if not model_ref:
-        raise HTTPException(status_code=400, detail="모델 식별자가 비어 있습니다.")
-
-    if ":" in model_ref and model_ref.split(":", 1)[0].strip().lower() in {"ollama", "vllm", "lmstudio", "llamacpp", "local_mlx", "mlx"}:
-        provider, model_name = model_ref.split(":", 1)
-        provider = provider.strip().lower()
-        model_name = model_name.strip()
-    else:
-        provider, model_name = "local_mlx", model_ref
-
-    if not model_name:
-        raise HTTPException(status_code=400, detail="모델 이름이 비어 있습니다.")
-
-    if provider == "ollama":
-        ensure_ollama_server()
-        ollama = local_binary("ollama")
-        if not ollama:
-            raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
-        try:
-            completed = subprocess.run(
-                [ollama, "pull", model_name],
-                capture_output=True, text=True, timeout=900, check=False,
-            )
-        except subprocess.TimeoutExpired:
-            raise HTTPException(status_code=408, detail="모델 다운로드 시간이 초과되었습니다.")
-        if completed.returncode != 0:
-            raise HTTPException(status_code=500, detail=completed.stderr[-2000:] or "pull 실패")
-        return {"provider": provider, "model": model_name, "returncode": completed.returncode}
-
-    if provider == "lmstudio":
-        raise HTTPException(
-            status_code=400,
-            detail=(
-                "LM Studio 모델은 Lattice에서 Hugging Face로 pull하지 않습니다. "
-                "LM Studio 앱에서 모델을 다운로드하고 Local Server를 켠 뒤 모델을 로드하세요. "
-                "그러면 모델 선택창에 실제 /v1/models 항목이 표시됩니다."
-            ),
-        )
-
-    if provider in {"vllm", "llamacpp", "local_mlx", "mlx"}:
-        download_provider = "local_mlx" if provider == "mlx" else provider
-        result = download_hf_model(model_name, download_provider)
-        return {"provider": provider, "model": model_name, "returncode": 0, **result}
-
-    raise HTTPException(status_code=400, detail=f"{provider} 엔진 모델 다운로드는 아직 자동화되지 않았습니다.")
-
-
-@app.post("/engines/prepare-model")
-async def engines_prepare_model(req: PrepareModelRequest, request: Request):
-    require_user(request)
-    return await prepare_and_load_model(
-        req.model,
-        request,
-        engine=req.engine,
-        user_email=req.user_email,
-    )
-
-
-@app.post("/engines/prepare-model/stream")
-async def engines_prepare_model_stream(req: PrepareModelRequest, request: Request):
-    require_user(request)
-
-    async def event_stream():
-        try:
-            async for chunk in prepare_and_load_model_stream(
-                req.model,
-                request,
-                engine=req.engine,
-                user_email=req.user_email,
-            ):
-                yield chunk
-        except HTTPException as exc:
-            yield sse_event("error", {
-                "status_code": exc.status_code,
-                "detail": exc.detail or "모델 준비에 실패했습니다.",
-            })
-        except Exception as exc:
-            logging.exception("model prepare stream failed")
-            yield sse_event("error", {
-                "status_code": 500,
-                "detail": str(exc)[-1000:] or "모델 준비에 실패했습니다.",
-            })
-
-    return StreamingResponse(
-        event_stream(),
-        media_type="text/event-stream",
-        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
-    )
-
-
-@app.post("/setup/set-api-key")
-async def set_api_key(req: SetApiKeyRequest, request: Request):
-    from llm_router import OPENAI_COMPATIBLE_PROVIDERS
-    config = OPENAI_COMPATIBLE_PROVIDERS.get(req.provider)
-    if not config:
-        raise HTTPException(status_code=400, detail="알 수 없는 프로바이더입니다.")
-    if not req.key.strip():
-        raise HTTPException(status_code=400, detail="API 키가 비어있습니다.")
-    current_user = get_current_user(request)
-    if REQUIRE_AUTH and not current_user:
-        raise HTTPException(status_code=401, detail="인증이 필요합니다.")
-    # req.user_email 을 통한 타 계정 위조를 방지: 관리자가 아니면 본인 이메일만 허용
-    if req.user_email and req.user_email != current_user:
-        users = load_users()
-        if get_user_role(current_user or "", users) != "admin":
-            raise HTTPException(status_code=403, detail="다른 사용자의 API 키를 설정할 권한이 없습니다.")
-    target_email = (req.user_email or current_user or "").strip()
-    if not target_email:
-        raise HTTPException(status_code=400, detail="사용자 식별이 필요합니다. 로그인 후 다시 시도하세요.")
-    set_user_api_key(target_email, req.provider, req.key.strip())
-    return {"ok": True, "provider": req.provider, "user_email": target_email, "scope": "user"}
-
-
-def _recommended_with_engine_options(items: List[Dict[str, object]]) -> List[Dict[str, object]]:
-    """피드백 #1: 추천 모델에 엔진별 선택지(engine_options)를 붙여 내려준다.
-
-    프론트에서 추천 카드를 누르는 순간 어느 엔진/실제 모델로 다운로드/로드할지가
-    이미 확정되도록 한다.
-    """
-    out: List[Dict[str, object]] = []
-    for item in items:
-        base = {
-            "id": item["id"],
-            "name": item["name"],
-            "tag": item["tag"],
-            "size": item["size"],
-            "display_name": item.get("name") or item.get("id"),
-        }
-        short_id = str(item["id"]).lower()
-        aliases = MODEL_ENGINE_ALIASES.get(short_id) or {}
-        options: List[Dict[str, str]] = []
-        for engine_name in ("local_mlx", "ollama", "lmstudio", "llamacpp", "vllm"):
-            real = aliases.get(engine_name)
-            if not real:
-                continue
-            options.append({
-                "engine": engine_name,
-                "model_id": real,
-                "load_id": real if engine_name == "local_mlx" else f"{engine_name}:{real}",
-            })
-        # 어느 엔진도 alias가 없으면 local_mlx 카탈로그 자체를 사용한다.
-        if not options:
-            options.append({
-                "engine": "local_mlx",
-                "model_id": item["id"],
-                "load_id": item["id"],
-            })
-        base["engine_options"] = options
-        base["recommended_engine"] = options[0]["engine"]
-        out.append(base)
-    return out
-
-
-@app.get("/models")
-async def list_models():
-    """HuggingFace 추천 모델 목록 및 로드 상태 반환"""
-    recommended = _recommended_with_engine_options(
-        list(filter_lower_family_versions(ENGINE_MODEL_CATALOG.get("local_mlx", [])))
-    )
-    return {
-        "recommended": recommended,
-        "cloud": router.detected_cloud_models(),
-        "engines": await asyncio.to_thread(engine_status),
-        "loaded": router.loaded_model_ids,
-        "current": router.current_model_id,
-        "compat_profiles": _list_compat_profiles(),
-    }
-
-
-@app.get("/models/compat-profiles")
-async def list_model_compat_profiles(request: Request):
-    """피드백 #3: Model Compatibility Layer 캐시 상태를 조회한다."""
-    require_user(request)
-    return {"profiles": _list_compat_profiles()}
-
-
-# ── Model Management ───────────────────────────────────────────────────────────
-
-@app.post("/models/load")
-async def load_model(req: LoadModelRequest, request: Request):
-    """모델 로드 (이미 로드됐으면 캐시에서 즉시 반환)"""
-    try:
-        model_id = req.model_id
-        requested_engine = req.engine or (model_id.split(":", 1)[0] if ":" in model_id else "local_mlx")
-        if IS_PUBLIC_MODE and not ALLOW_LOCAL_MODELS and requested_engine in {"local_mlx", "mlx"}:
-            raise HTTPException(
-                status_code=400,
-                detail="Public mode blocks local MLX model loading. Use openai:, openrouter:, groq:, together:, or set LATTICEAI_ALLOW_LOCAL_MODELS=true.",
-            )
-        return await prepare_and_load_model(
-            model_id,
-            request,
-            engine=req.engine,
-            user_email=req.user_email,
-            adapter_path=req.adapter_path,
-            draft_model_id=req.draft_model_id,
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-@app.post("/models/switch/{model_id:path}")
-async def switch_model(model_id: str, request: Request):
-    """이미 로드된 모델 중 활성 모델 전환 (즉시, 재로드 없음)"""
-    require_user(request)
-    try:
-        router.switch_model(model_id)
-        return {"status": "ok", "current": router.current_model_id}
-    except KeyError:
-        raise HTTPException(status_code=404, detail=f"Model '{model_id}' not loaded. Call /models/load first.")
-
-
-@app.delete("/models/unload/{model_id:path}")
-async def unload_model(model_id: str, request: Request):
-    """모델 언로드 → 메모리 해제"""
-    require_user(request)
-    router.unload_model(model_id)
-    return {"status": "ok", "unloaded": model_id}
+# ── Health / status / engine-summary router (latticeai.api.health, v1.2.0) ───
+# /health, /mode, /runtime_features, /engines(GET) now live in the health router.
+# Heavier engine mutation endpoints remain below in server_app.
+MODEL_SERVICE = ModelService(
+    model_router=router,
+    runtime_features=runtime_features,
+    is_public=IS_PUBLIC_MODE,
+)
+app.include_router(create_health_router(
+    model_service=MODEL_SERVICE,
+    engine_status=engine_status,
+    get_current_user=get_current_user,
+    require_auth=REQUIRE_AUTH,
+    app_version=APP_VERSION,
+    app_mode=APP_MODE,
+))
 
 
-@app.delete("/models/unload-all")
-async def unload_all_models(request: Request):
-    """로드된 모든 모델 언로드 → 메모리 해제"""
-    require_user(request)
-    unloaded = router.loaded_model_ids
-    router.unload_all()
-    return {"status": "ok", "unloaded": unloaded}
+# ── Model / Engine router (latticeai.api.models, v1.3.0) ─────────────────────
+app.include_router(create_models_router(
+    model_router=router,
+    require_user=require_user,
+    get_current_user=get_current_user,
+    load_users=load_users,
+    get_user_role=get_user_role,
+    install_engine=install_engine,
+    verify_cloud_models=verify_cloud_models,
+    normalize_local_model_request=normalize_local_model_request,
+    download_hf_model=download_hf_model,
+    prepare_and_load_model=prepare_and_load_model,
+    prepare_and_load_model_stream=prepare_and_load_model_stream,
+    sse_event=sse_event,
+    ensure_ollama_server=ensure_ollama_server,
+    local_binary=local_binary,
+    engine_status=engine_status,
+    filter_lower_family_versions=filter_lower_family_versions,
+    list_compat_profiles=_list_compat_profiles,
+    set_user_api_key=set_user_api_key,
+    engine_model_catalog=ENGINE_MODEL_CATALOG,
+    model_engine_aliases=MODEL_ENGINE_ALIASES,
+    cloud_verify_ttl_seconds=CLOUD_VERIFY_TTL_SECONDS,
+    is_public_mode=IS_PUBLIC_MODE,
+    allow_local_models=ALLOW_LOCAL_MODELS,
+    require_auth=REQUIRE_AUTH,
+))
 
 
 # ── Chat / Completion ──────────────────────────────────────────────────────────
@@ -4615,7 +3711,7 @@ async def chat(req: ChatRequest, request: Request):
             except Exception:
                 pass
 
-    trace_seed = WORKSPACE_OS.build_graph_trace(
+    trace_seed = CHAT_SERVICE.build_graph_trace(
         req.message,
         KNOWLEDGE_GRAPH if (ENABLE_GRAPH and KNOWLEDGE_GRAPH) else None,
         context,
@@ -4653,7 +3749,7 @@ async def chat(req: ChatRequest, request: Request):
                     full_text += footnote
                 session.update(graph_md, full_text, req.conversation_id)
                 save_to_history("assistant", full_text, source=req.source or "web", conversation_id=req.conversation_id, **history_user)
-                trace_record = WORKSPACE_OS.record_trace(
+                trace_record = CHAT_SERVICE.record_trace(
                     question=req.message,
                     response=full_text,
                     conversation_id=req.conversation_id,
@@ -4679,7 +3775,7 @@ async def chat(req: ChatRequest, request: Request):
                 result += footnote
             session.update(graph_md, result, req.conversation_id)
             save_to_history("assistant", str(result), source=req.source or "web", conversation_id=req.conversation_id, **history_user)
-            trace_record = WORKSPACE_OS.record_trace(
+            trace_record = CHAT_SERVICE.record_trace(
                 question=req.message,
                 response=str(result),
                 conversation_id=req.conversation_id,
@@ -4716,7 +3812,7 @@ async def chat(req: ChatRequest, request: Request):
         result = await router.generate(req.message, full_context, req.max_tokens, req.temperature, req.image_data)
 
         save_to_history("assistant", str(result), source=req.source or "web", conversation_id=req.conversation_id, **history_user)
-        trace_record = WORKSPACE_OS.record_trace(
+        trace_record = CHAT_SERVICE.record_trace(
             question=req.message,
             response=str(result),
             conversation_id=req.conversation_id,
@@ -4820,12 +3916,12 @@ async def _stream_chat(
         yield f"data: {json.dumps({'chunk': clean_chunk, 'model': router.current_model_id}, ensure_ascii=False)}\n\n"
     history_user = get_history_user(req.user_email, req.user_nickname)
     save_to_history("assistant", full_response, source=req.source or "web", conversation_id=req.conversation_id, **history_user)
-    trace_record = WORKSPACE_OS.record_trace(
+    trace_record = CHAT_SERVICE.record_trace(
         question=req.message,
         response=full_response,
         conversation_id=req.conversation_id,
         user_email=effective_email or req.user_email,
-        trace=trace_seed or WORKSPACE_OS.build_graph_trace(
+        trace=trace_seed or CHAT_SERVICE.build_graph_trace(
             req.message,
             KNOWLEDGE_GRAPH if (ENABLE_GRAPH and KNOWLEDGE_GRAPH) else None,
             context,
@@ -6103,324 +5199,24 @@ async def tools_permissions(request: Request):
     return {"status": "ok", "permissions": list_tool_permissions()}
 
 
-@app.get("/mcp/tools")
-async def mcp_tools():
-    installed = load_mcp_installs().get("installed", {})
-    registry = await _get_combined_registry()
-    tools = []
-    for name, description in MCP_TOOL_DESCRIPTIONS.items():
-        policy = TOOL_GOVERNANCE.get(name, _TOOL_GOVERNANCE_DEFAULT)
-        tools.append({
-            "name": name,
-            "description": description,
-            "permission": get_tool_permission(name),
-            "governance": {
-                "risk":         policy["risk"],
-                "destructive":  policy["destructive"],
-                "shell":        policy["shell"],
-                "network":      policy["network"],
-                "auto_approve": policy["auto_approve"],
-                "sandbox":      policy["sandbox"],
-                "rollback":     policy["rollback"],
-            },
-        })
-    return {
-        "status": "ok",
-        "workspace": str(AGENT_ROOT),
-        "installed_mcps": [mcp_public_item(item, installed) for item in registry],
-        "tools": tools,
-    }
-
-
-@app.post("/mcp/recommend")
-async def mcp_recommend(req: McpRecommendRequest, request: Request):
-    require_user(request)
-    return {"recommendations": await recommend_mcps(req.query, req.limit)}
-
-
-@app.post("/mcp/install")
-async def mcp_install(req: McpInstallRequest, request: Request):
-    admin_email, _ = require_admin(request)
-    append_audit_event("mcp_install", user_email=admin_email, mcp_id=req.mcp_id)
-    return await install_mcp(req.mcp_id)
-
-
-@app.get("/mcp/installed")
-async def mcp_installed(request: Request):
-    require_user(request)
-    installed = load_mcp_installs().get("installed", {})
-    registry = await _get_combined_registry()
-    return {"installed": [mcp_public_item(item, installed) for item in registry]}
-
-
-@app.get("/mcp/connectors/{mcp_id}")
-async def mcp_connector(mcp_id: str, request: Request):
-    require_user(request)
-    registry = await _get_combined_registry()
-    item = next((e for e in registry if e["id"] == mcp_id), None)
-    if not item or item.get("install_mode") != "connector":
-        raise HTTPException(status_code=404, detail="커넥터를 찾을 수 없습니다.")
-    installed = load_mcp_installs().get("installed", {})
-    public = mcp_public_item(item, installed)
-    public["instructions"] = [
-        "Codex 또는 ChatGPT 앱의 Connectors 설정을 엽니다.",
-        f"{item['name']} 항목을 선택하고 계정을 인증합니다.",
-        "인증 후 Lattice AI에서 이 MCP를 다시 활성화하면 작업에 사용할 수 있습니다.",
-    ]
-    return public
-
-
-@app.post("/mcp/registry/refresh")
-async def mcp_registry_refresh(request: Request):
-    require_user(request)
-    mcp_registry._REMOTE_REGISTRY_FETCHED_AT = None
-    registry = await _get_combined_registry()
-    return {"status": "ok", "total": len(registry), "remote": len(mcp_registry._REMOTE_REGISTRY_CACHE)}
-
-
-@app.get("/mcp/claude-code-servers")
-async def mcp_claude_code_servers(request: Request):
-    """Read ~/.claude/settings.json mcpServers and return them as Lattice MCP items."""
-    require_user(request)
-    settings_path = Path.home() / ".claude" / "settings.json"
-    if not settings_path.exists():
-        return {"servers": []}
-    try:
-        with open(settings_path, "r", encoding="utf-8") as f:
-            settings = json.load(f)
-        mcp_servers = settings.get("mcpServers", {})
-        servers = []
-        for name, cfg in mcp_servers.items():
-            cmd = cfg.get("command", "")
-            args = cfg.get("args", [])
-            package = " ".join([cmd] + args) if args else cmd
-            env = cfg.get("env", {})
-            env_vars = [{"name": k, "value": v} for k, v in env.items()]
-            servers.append({
-                "id": f"claude-code:{name}",
-                "name": name,
-                "description": f"Claude Code MCP: {package}",
-                "package": package,
-                "icon": "🤖",
-                "category": "Claude Code",
-                "source": "claude-code",
-                "installed": True,
-                "env_vars": env_vars,
-            })
-        return {"servers": servers}
-    except Exception as e:
-        logging.warning("mcp_claude_code_servers failed: %s", e)
-        return {"servers": []}
-
-
-_CUSTOM_MCP_FILE = DATA_DIR / "custom_mcps.json"
-
-def _load_custom_mcps() -> List[Dict]:
-    if not _CUSTOM_MCP_FILE.exists():
-        return []
-    try:
-        with open(_CUSTOM_MCP_FILE, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except Exception:
-        return []
-
-def _save_custom_mcps(items: List[Dict]):
-    with open(_CUSTOM_MCP_FILE, "w", encoding="utf-8") as f:
-        json.dump(items, f, ensure_ascii=False, indent=2)
-
-
-@app.get("/mcp/custom")
-async def mcp_custom_list(request: Request):
-    """Return user-added custom MCP entries."""
-    require_user(request)
-    return {"custom": _load_custom_mcps()}
-
-
-@app.post("/mcp/custom")
-async def mcp_custom_add(req: McpCustomRequest, request: Request):
-    """Save a custom MCP entry (admin-only)."""
-    admin_email, _ = require_admin(request)
-    append_audit_event("mcp_custom_add", user_email=admin_email, name=req.name, package=req.package)
-    if not req.name.strip():
-        raise HTTPException(status_code=400, detail="name은 필수입니다.")
-    if not req.package.strip():
-        raise HTTPException(status_code=400, detail="package는 필수입니다.")
-    items = _load_custom_mcps()
-    entry = {
-        "id": f"custom:{req.name.strip().lower().replace(' ', '-')}",
-        "name": req.name.strip(),
-        "package": req.package.strip(),
-        "description": req.description.strip(),
-        "category": req.category or "custom",
-        "icon": req.icon or "🔌",
-        "env_vars": req.env_vars or [],
-        "install_mode": "npm",
-        "source": "custom",
-        "installed": False,
-        "added_at": datetime.now().isoformat(),
-    }
-    # overwrite if same id
-    items = [e for e in items if e["id"] != entry["id"]]
-    items.append(entry)
-    _save_custom_mcps(items)
-    return {"status": "ok", "entry": entry}
-
-
-@app.delete("/mcp/custom/{mcp_id:path}")
-async def mcp_custom_delete(mcp_id: str, request: Request):
-    """Remove a custom MCP entry."""
-    require_admin(request)
-    items = _load_custom_mcps()
-    before = len(items)
-    items = [e for e in items if e["id"] != mcp_id]
-    if len(items) == before:
-        raise HTTPException(status_code=404, detail="항목을 찾을 수 없습니다.")
-    _save_custom_mcps(items)
-    return {"status": "ok"}
-
-
-# ── Skills & Plugin Directory endpoints ───────────────────────────────────────
-
-@app.get("/skills/marketplace")
-async def skills_marketplace(request: Request, category: Optional[str] = None, author: Optional[str] = None):
-    """Skills 마켓플레이스 (Anthropic Apache-2.0 + 검증된 서드파티 MIT/Apache-2.0)"""
-    require_user(request)
-    skills = await _fetch_skills_marketplace()
-    installed_names = {d.name for d in SKILLS_DIR.iterdir() if d.is_dir()} if SKILLS_DIR.exists() else set()
-    filtered = skills
-    if category:
-        filtered = [s for s in filtered if s.get("category", "").lower() == category.lower()]
-    if author:
-        filtered = [s for s in filtered if s.get("author", "").lower() == author.lower()]
-    return {
-        "skills": [{**s, "installed": s["skill"] in installed_names} for s in filtered],
-        "total": len(filtered),
-        "authors": sorted({s["author"] for s in skills}),
-        "categories": sorted({s["category"] for s in skills}),
-    }
-
-
-@app.post("/skills/install")
-async def skills_install(req: SkillInstallRequest, request: Request):
-    """skill을 로컬 skills 디렉터리에 설치 (Apache-2.0 / MIT, 관리자 전용)"""
-    admin_email, _ = require_admin(request)
-    append_audit_event("skill_install", user_email=admin_email, plugin=req.plugin, skill=req.skill)
-    return await install_skill(req.plugin, req.skill)
-
-
-@app.get("/skills/list")
-async def skills_list(request: Request):
-    """로컬에 설치된 skills 목록"""
-    require_user(request)
-    if not SKILLS_DIR.exists():
-        return {"skills": []}
-    skills = []
-    for skill_dir in sorted(SKILLS_DIR.iterdir()):
-        if not skill_dir.is_dir():
-            continue
-        skill_md = skill_dir / "SKILL.md"
-        if not skill_md.exists():
-            continue
-        lines = skill_md.read_text(encoding="utf-8").splitlines()
-        desc = next((l.split(":", 1)[1].strip() for l in lines if l.startswith("description:")), "")
-        comment = lines[0] if lines else ""
-        if "anthropics/claude-plugins-official" in comment:
-            source = "anthropic"
-        elif "Source:" in comment:
-            source = "third-party"
-        else:
-            source = "local"
-        skills.append({"name": skill_dir.name, "description": desc, "source": source})
-    return {"skills": skills, "total": len(skills)}
-
-
-@app.post("/skills/marketplace/refresh")
-async def skills_marketplace_refresh(request: Request):
-    """Skills 마켓플레이스 캐시 강제 갱신"""
-    require_user(request)
-    mcp_registry._SKILLS_MARKETPLACE_FETCHED_AT = None
-    skills = await _fetch_skills_marketplace()
-    by_author = {}
-    for s in skills:
-        by_author[s["author"]] = by_author.get(s["author"], 0) + 1
-    return {"status": "ok", "total": len(skills), "by_author": by_author}
-
-
-@app.get("/plugins/directory")
-async def plugins_directory(
-    request: Request,
-    category: Optional[str] = None,
-    license: Optional[str] = None,
-    q: Optional[str] = None,
-):
-    """오픈소스 플러그인 디렉터리 (Apache-2.0 / MIT / MIT-0, 런타임 fetch)"""
-    require_user(request)
-    plugins = await _fetch_plugin_directory()
-    filtered = plugins
-    if category:
-        filtered = [p for p in filtered if p.get("category", "").lower() == category.lower()]
-    if license:
-        filtered = [p for p in filtered if p.get("license", "").lower() == license.lower()]
-    if q:
-        q_lower = q.lower()
-        filtered = [
-            p for p in filtered
-            if q_lower in p.get("name", "").lower()
-            or q_lower in p.get("description", "").lower()
-            or q_lower in p.get("author", "").lower()
-        ]
-    return {
-        "plugins": filtered,
-        "total": len(filtered),
-        "categories": sorted({p["category"] for p in plugins if p.get("category")}),
-        "licenses": sorted({p["license"] for p in plugins if p.get("license")}),
-    }
-
-
-@app.post("/plugins/directory/refresh")
-async def plugins_directory_refresh(request: Request):
-    """플러그인 디렉터리 캐시 강제 갱신"""
-    require_user(request)
-    mcp_registry._PLUGIN_DIRECTORY_FETCHED_AT = None
-    plugins = await _fetch_plugin_directory()
-    by_license = {}
-    for p in plugins:
-        lic = p.get("license", "unknown")
-        by_license[lic] = by_license.get(lic, 0) + 1
-    return {"status": "ok", "total": len(plugins), "by_license": by_license}
-
-
-@app.post("/mcp/call")
-async def mcp_call(req: McpCallRequest, request: Request):
-    current_user = require_user(request)
-    args = req.args or {}
-    if req.action == "knowledge_graph_ingest":
-        _require_graph()
-        return KNOWLEDGE_GRAPH.ingest_message(
-            args.get("role") or ("assistant" if args.get("type") == "ai_response" else "user"),
-            args.get("content") or "",
-            user_email=args.get("user_email") or current_user,
-            user_nickname=args.get("user_nickname"),
-            source=args.get("source") or "mcp",
-            conversation_id=args.get("conversation_id"),
-            raw=args,
-        )
-    if req.action == "knowledge_graph_search":
-        _require_graph()
-        return KNOWLEDGE_GRAPH.search(args.get("query") or args.get("q") or "", args.get("limit", 30))
-    if req.action == "knowledge_graph_graph":
-        _require_graph()
-        return KNOWLEDGE_GRAPH.graph(args.get("limit", 300))
-    if req.action == "knowledge_graph_context":
-        _require_graph()
-        return {
-            "context": KNOWLEDGE_GRAPH.context_for_query(
-                args.get("query") or args.get("q") or "",
-                args.get("limit", 6),
-            )
-        }
-    _check_tool_role(req.action, current_user)
-    return _tool_response(execute_tool, req.action, req.args or {})
+# ── MCP / skills / plugins router (latticeai.api.mcp, v1.3.0) ────────────────
+app.include_router(create_mcp_router(
+    require_user=require_user,
+    require_admin=require_admin,
+    append_audit_event=append_audit_event,
+    load_mcp_installs=load_mcp_installs,
+    recommend_mcps=recommend_mcps,
+    install_mcp=install_mcp,
+    mcp_public_item=mcp_public_item,
+    get_tool_permission=get_tool_permission,
+    tool_governance=TOOL_GOVERNANCE,
+    tool_governance_default=_TOOL_GOVERNANCE_DEFAULT,
+    check_tool_role=_check_tool_role,
+    tool_response=_tool_response,
+    require_graph=_require_graph,
+    knowledge_graph=KNOWLEDGE_GRAPH,
+    data_dir=DATA_DIR,
+))
 
 
 # ── P-Reinforce Knowledge Gardener ────────────────────────────────────────────