agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/studio/api.py

@@ -4,19 +4,24 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import hashlib
 import hmac
 import json
+import logging
 import os
 import secrets
-import time
+import shutil
+import subprocess
+import sys
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Any, Literal
+from urllib.parse import quote
 
 from fastapi import FastAPI, File, Header, Query, Request, Response, UploadFile
 from fastapi.exceptions import RequestValidationError
-from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+from fastapi.responses import FileResponse, JSONResponse, RedirectResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.background import BackgroundTask
 
@@ -43,6 +48,7 @@ from ksadk.studio.api_contracts import (
     CreateAgentRequest,
     ImportRootRequest,
     InteractionSubmitRequest,
+    LinkedDirectoryRequest,
     ProjectInspectRequest,
     PromptCompileRequest,
     QuickAuthoringRequest,
@@ -79,6 +85,13 @@ from ksadk.studio.api_helpers import (
 )
 from ksadk.studio.api_memory_routes import register_memory_routes
 from ksadk.studio.api_plugin_routes import register_plugin_routes
+from ksadk.studio.api_resource_connections import register_resource_connection_routes
+from ksadk.studio.channel_connections import (
+    CHANNEL_ACTIONS,
+    ChannelAgentConnectionInput,
+    ChannelConnectionSettings,
+)
+from ksadk.studio.cloud_shared_web import CloudSharedWebBridge, cloud_chat_target, is_cloud_agent_id
 from ksadk.studio.codex_manifest import CodexAgentManifest
 from ksadk.studio.contracts import (
     AgentAppearance,
@@ -89,8 +102,23 @@ from ksadk.studio.contracts import (
     OperationStatus,
 )
 from ksadk.studio.errors import StudioError
+from ksadk.studio.native_documents import (
+    NativeDocumentActionRequest,
+    document_metadata,
+    is_local_desktop_request,
+    perform_document_action,
+)
+from ksadk.studio.run_activity import register_activity_routes
+from ksadk.studio.run_documents import read_document
 from ksadk.studio.service import StudioService
 from ksadk.studio.shared_web import StudioSharedWebBridge
+from ksadk.studio.workspace_registry import (
+    LinkedDirectoryPolicy,
+    WorkspaceRegistry,
+    WorkspaceRuntimeManager,
+)
+
+logger = logging.getLogger(__name__)
 
 _WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
 _PUBLIC_API_PATHS = {
@@ -144,9 +172,7 @@ _CONTENT_WIRE_ALIASES = {
 def _normalize_cloud_runtime_event_wire(value: dict[str, Any]) -> dict[str, Any]:
     """Normalize only historic REST casing at the RuntimeEvent boundary."""
 
-    normalized = {
-        _RUNTIME_EVENT_WIRE_ALIASES.get(key, key): item for key, item in value.items()
-    }
+    normalized = {_RUNTIME_EVENT_WIRE_ALIASES.get(key, key): item for key, item in value.items()}
     source = normalized.get("source")
     if isinstance(source, dict):
         normalized["source"] = {
@@ -198,9 +224,7 @@ def _cloud_event_conversation_item(
     if raw_event is None:
         return None
     try:
-        runtime_event = parse_runtime_event_lenient(
-            _normalize_cloud_runtime_event_wire(raw_event)
-        )
+        runtime_event = parse_runtime_event_lenient(_normalize_cloud_runtime_event_wire(raw_event))
         item = project_conversation_item(
             runtime_event,  # type: ignore[arg-type]
             session_id=session_id,
@@ -211,6 +235,21 @@ def _cloud_event_conversation_item(
     return item.model_dump(by_alias=True, exclude_none=True, mode="json")
 
 
+import re as _re
+
+# 内容 hash 文件名（如 index-CQj_Jm9z.js）可安全 immutable 强缓存；
+# index.html 与动态 HTML 仍需每次校验。
+_HASHED_ASSET_RE = _re.compile(r"-[A-Za-z0-9_]{8,}\.(js|css|woff2?|ttf|png|svg|webp|mp4|wasm)$")
+
+
+def _cache_control_for(path: str, response: Any) -> str:
+    if path.startswith(("/api/", "/v1/")):
+        return "no-store"
+    if _HASHED_ASSET_RE.search(path) and 200 <= response.status_code < 300:
+        return "public, max-age=31536000, immutable"
+    return response.headers.get("Cache-Control", "no-cache")
+
+
 def create_studio_app(
     root: Path | str,
     *,
@@ -219,21 +258,114 @@ def create_studio_app(
     csrf_token: str | None = None,
     security_enabled: bool = True,
 ) -> FastAPI:
-    studio = service or StudioService(root)
+    initial_service = service or StudioService(root)
+    studio = WorkspaceRuntimeManager(
+        initial_service, lambda workspace_root: StudioService(workspace_root)
+    )
     session_secret = session_token or secrets.token_urlsafe(32)
     csrf_secret = csrf_token or secrets.token_urlsafe(24)
+    session_cookie_name = "agentkit_studio_session_" + hashlib.sha256(
+        session_secret.encode("utf-8")
+    ).hexdigest()[:16]
+    legacy_session_cookie_name = "agentkit_studio_session"
 
     @asynccontextmanager
     async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+        lazy_desktop_start = os.environ.get("KSADK_STUDIO_LAZY_START") == "1"
+        warmups: set[asyncio.Task[None]] = set()
+
+        def schedule_runtime_warmup(runtime: StudioService) -> None:
+            async def warm_runtime() -> None:
+                try:
+                    await runtime.start()
+                except Exception:
+                    # Runtime warmup is best effort; core Studio remains usable
+                    # while optional DSH capability discovery is unavailable.
+                    return
+                # The Channel UI is a wheel-owned client bundle.  Bootstrap it
+                # after the listener is available and through the same Profile
+                # maintenance fence used by other DSH mutations.
+                if (
+                    os.environ.get("KSADK_STUDIO_CHANNEL_DEFAULT", "1")
+                    .strip()
+                    .lower()
+                    not in {"0", "false", "no", "off"}
+                    and not os.environ.get("KSADK_DSH_HOME", "").strip()
+                    and not os.environ.get("KSADK_DSH_PROFILE", "").strip()
+                ):
+                    try:
+                        from ksadk.plugins.dsh_channels import (
+                            channel_default_bootstrap_needed,
+                            configure_channel_profile,
+                        )
+                        from ksadk.studio.api_plugin_routes import _studio_dsh_options
+
+                        home, profile, command, _ = _studio_dsh_options(runtime)
+                        # 可选 bootstrap 必须先确认 DSH 命令真实可用：无工具链的
+                        # 环境进入 Profile 维护栅栏后，恢复失败会按契约保持
+                        # admission 关闭，导致整个会话面永久 503（回归过）。
+                        if command and shutil.which(str(command[0])) is None:
+                            logger.info(
+                                "Channel 默认激活跳过：DSH 命令不可用 (%s)",
+                                command[0],
+                            )
+                        elif profile == "web" and command and channel_default_bootstrap_needed(home):
+                            async def configure_channel():
+                                await asyncio.to_thread(
+                                    configure_channel_profile,
+                                    workspace=runtime.workspace.root,
+                                    dsh_home=home,
+                                    dsh_command=command,
+                                )
+
+                            await runtime.reconfigure_dsh_profile(configure_channel)
+                    except Exception as error:
+                        logger.info("Channel 默认激活未完成（可手动启用）: %s", error)
+
+                if os.environ.get(
+                    "KSADK_STUDIO_TEAMS_DEFAULT", "1"
+                ).strip().lower() not in {"0", "false", "no", "off"}:
+                    installation = getattr(runtime, "teams_installation", None)
+                    if installation is not None and not installation.status().get("enabled"):
+                        try:
+                            await installation.enable()
+                        except Exception as error:
+                            # 默认启用是预期行为，但 DSH 工具链/权威不可用时必须静默
+                            # 降级，核心 Studio 与其他插件不受影响；页面仍保留手动入口。
+                            logger.info(
+                                "Teams 默认激活未完成（可手动启用）: %s", error
+                            )
+
+            task = asyncio.create_task(warm_runtime())
+            warmups.add(task)
+            task.add_done_callback(warmups.discard)
+
         try:
-            await studio.start()
-            await studio.run_service.recover_interrupted()
+            app.state.runtime_warmups = schedule_runtime_warmup
+            await studio.start(wait_for_dsh=not lazy_desktop_start)
+            # Optional plugin activation must not hold the HTTP listener closed
+            # while DSH starts subprocesses or acquires an authority lease.
+            schedule_runtime_warmup(studio.active)
+            # Pre-resolve the entry redirect choice once off the request path;
+            # failures are swallowed and ``index()`` has its own bounded wait.
+            probe_warmup = getattr(
+                studio.active.dsh_capabilities, "schedule_plugin_probe_warmup", None
+            )
+            if callable(probe_warmup):
+                probe_warmup()
+            await studio.run_service.recover_interrupted(studio.resolve_run_spec)
             await studio.scheduler.start_if_available()
             yield
         finally:
-            await studio.scheduler.stop()
-            await studio.aclose()
-            studio.credentials.clear_session()
+            app.state.runtime_warmups = None
+            for task in tuple(warmups):
+                task.cancel()
+            if warmups:
+                await asyncio.gather(*warmups, return_exceptions=True)
+            for runtime in studio.services():
+                await runtime.scheduler.stop()
+                await runtime.aclose()
+                runtime.credentials.clear_session()
 
     app = FastAPI(
         title="AgentKit Local Studio",
@@ -246,6 +378,11 @@ def create_studio_app(
     app.state.studio_service = studio
     app.state.session_token = session_secret
     app.state.csrf_token = csrf_secret
+    from ksadk.studio.dsh_models import studio_model_projection
+
+    studio.dsh_capabilities.model_projection = lambda: studio_model_projection(
+        studio.catalog, studio.credentials
+    )
 
     def _stream_studio_run(
         build_id: str,
@@ -321,8 +458,9 @@ def create_studio_app(
         )
 
     static_root = Path(__file__).with_name("static")
-    _studio_startup_epoch = str(int(time.time()))
     shared_web = StudioSharedWebBridge(studio)
+    register_activity_routes(app, studio, resolve_run_id=shared_web.resolve_run_reference)
+    cloud_web = CloudSharedWebBridge(studio)
     app.state.shared_web_bridge = shared_web
     app.mount("/static", StaticFiles(directory=static_root), name="studio-static")
 
@@ -377,8 +515,10 @@ def create_studio_app(
             or shared_web_api
             or responses_api
         ):
-            supplied = request.cookies.get("agentkit_studio_session") or request.headers.get(
-                "X-AgentKit-Session"
+            supplied = (
+                request.cookies.get(session_cookie_name)
+                or request.cookies.get(legacy_session_cookie_name)
+                or request.headers.get("X-AgentKit-Session")
             )
             if not supplied or not hmac.compare_digest(supplied, session_secret):
                 return _error_response(
@@ -389,7 +529,8 @@ def create_studio_app(
                     ),
                     request,
                 )
-            if (studio_api or responses_api) and request.method in _WRITE_METHODS:
+            channel_api = shared_web_api and request.url.path.rsplit("/", 1)[-1] in CHANNEL_ACTIONS
+            if (studio_api or responses_api or channel_api) and request.method in _WRITE_METHODS:
                 csrf = request.headers.get("X-CSRF-Token")
                 if not csrf or not hmac.compare_digest(csrf, csrf_secret):
                     return _error_response(
@@ -402,11 +543,7 @@ def create_studio_app(
                     )
         response = await call_next(request)
         response.headers["X-Request-Id"] = request.state.request_id
-        response.headers["Cache-Control"] = (
-            "no-store"
-            if request.url.path.startswith(("/api/", "/v1/"))
-            else response.headers.get("Cache-Control", "no-cache")
-        )
+        response.headers["Cache-Control"] = _cache_control_for(request.url.path, response)
         response.headers["X-Content-Type-Options"] = "nosniff"
         response.headers["X-Frame-Options"] = "DENY"
         response.headers["Referrer-Policy"] = "no-referrer"
@@ -464,29 +601,23 @@ def create_studio_app(
         )
 
     @app.get("/")
-    async def index():
-        path = static_root / "index.html"
-        html = path.read_text(encoding="utf-8")
-        # Inject a startup-scoped version so a restarted Studio with a rebuilt
-        # bundle always wins over a stale browser tab.  The bundle filenames
-        # are already content-hashed; this only defeats cached index.html.
-        if "?v=" not in html:
-            import re
-
-            def _add_version(match: "re.Match[str]") -> str:
-                attr, path_part = match.group(1), match.group(2)
-                return f'{attr}="/static/assets/{path_part}?v={_studio_startup_epoch}"'
-
-            html = re.sub(
-                r'(src|href)="/static/assets/([^"]+)"',
-                _add_version,
-                html,
-            )
-        response = Response(content=html, media_type="text/html")
-        response.headers["Cache-Control"] = "no-store"
+    @app.get("/studio-recovery/")
+    @app.get("/studio-shell/")
+    async def index(request: Request):
+        from ksadk.studio.entry import studio_entry_response
+
+        response = await studio_entry_response(studio, request, static_root)
         if security_enabled:
             response.set_cookie(
-                "agentkit_studio_session",
+                session_cookie_name,
+                session_secret,
+                httponly=True,
+                samesite="strict",
+                secure=False,
+                path="/",
+            )
+            response.set_cookie(
+                legacy_session_cookie_name,
                 session_secret,
                 httponly=True,
                 samesite="strict",
@@ -495,6 +626,42 @@ def create_studio_app(
             )
         return response
 
+    @app.get("/api/v1/plugin-ecosystems/dsh/recovery")
+    async def dsh_recovery_status():
+        # This endpoint must remain a read-only snapshot: no Core startup, Profile
+        # projection, credential resolution, or filesystem repair is attempted.
+        return studio.dsh_capabilities.startup_status
+
+    @app.get("/api/v1/plugins/workspace-contributions")
+    async def workspace_contributions():
+        """Expose enabled UI contributions without booting the DSH Core."""
+        from ksadk.plugins.dsh_channels import channel_workspace_contributions
+        from ksadk.plugins.dsh_home import studio_dsh_home
+
+        runtime = studio.active
+        contributions = await asyncio.to_thread(
+            channel_workspace_contributions,
+            studio_dsh_home(runtime.workspace.root),
+            os.environ.get("KSADK_DSH_PROFILE", "").strip() or "web",
+        )
+        # Teams remains served by its existing lifecycle endpoint; this endpoint
+        # only adds client-only contributions that have no domain lifecycle.
+        return {"items": contributions}
+
+    @app.get("/api/v1/channels/connection")
+    async def channel_connection_status():
+        return studio.channel_connections.status()
+
+    @app.put("/api/v1/channels/connection")
+    async def configure_channel_connection(payload: ChannelConnectionSettings):
+        return await studio.channel_connections.configure(payload)
+
+    @app.put("/api/v1/channels/agents/{agent_id}/connection")
+    async def configure_channel_agent_connection(
+        agent_id: str, payload: ChannelAgentConnectionInput
+    ):
+        return await studio.channel_connections.configure_agent(agent_id, payload)
+
     @app.get("/favicon.ico")
     async def favicon():
         return Response(status_code=204)
@@ -526,9 +693,31 @@ def create_studio_app(
     async def openai_responses(payload: dict[str, Any]):
         metadata = payload.get("metadata")
         metadata = metadata if isinstance(metadata, dict) else {}
-        agent_id = str(metadata.get("agent_id") or metadata.get("agentId") or "") or None
+        agentengine_metadata = metadata.get("agentengine")
+        agentengine_metadata = (
+            agentengine_metadata if isinstance(agentengine_metadata, dict) else {}
+        )
+        agent_id = (
+            str(
+                metadata.get("agent_id")
+                or metadata.get("agentId")
+                or agentengine_metadata.get("agent_id")
+                or agentengine_metadata.get("agentId")
+                or ""
+            )
+            or None
+        )
         requested_approval_mode = (
-            str(metadata.get("approval_mode") or metadata.get("approvalMode") or "").strip().lower()
+            str(
+                metadata.get("approval_mode")
+                or metadata.get("approvalMode")
+                or agentengine_metadata.get("tool_approval_mode")
+                or agentengine_metadata.get("approval_mode")
+                or agentengine_metadata.get("approvalMode")
+                or ""
+            )
+            .strip()
+            .lower()
         )
         if requested_approval_mode and requested_approval_mode not in {"ask", "risk", "full"}:
             raise StudioError(
@@ -538,7 +727,13 @@ def create_studio_app(
                 field="metadata.approval_mode",
             )
         collaboration_mode = (
-            str(metadata.get("collaboration_mode") or metadata.get("collaborationMode") or "")
+            str(
+                metadata.get("collaboration_mode")
+                or metadata.get("collaborationMode")
+                or agentengine_metadata.get("collaboration_mode")
+                or agentengine_metadata.get("collaborationMode")
+                or ""
+            )
             .strip()
             .lower()
         )
@@ -550,7 +745,11 @@ def create_studio_app(
                 field="metadata.collaboration_mode",
             )
         goal_objective = str(
-            metadata.get("goal_objective") or metadata.get("goalObjective") or ""
+            metadata.get("goal_objective")
+            or metadata.get("goalObjective")
+            or agentengine_metadata.get("goal_objective")
+            or agentengine_metadata.get("goalObjective")
+            or ""
         ).strip()
         reasoning = payload.get("reasoning")
         reasoning = reasoning if isinstance(reasoning, dict) else {}
@@ -594,7 +793,7 @@ def create_studio_app(
 
     @app.post("/v1/responses/{response_id}/cancel")
     async def cancel_openai_response(response_id: str):
-        result = shared_web.cancel_run(response_id)
+        result = await shared_web.cancel_run(response_id)
         return {
             "id": response_id,
             "object": "response",
@@ -618,26 +817,121 @@ def create_studio_app(
         try:
             cookie_agent_id = request.cookies.get("agentkit_studio_chat_agent")
             requested_agent_id = str(payload.get("AgentId") or cookie_agent_id or "")
+            cloud_mode = is_cloud_agent_id(requested_agent_id)
+            if cloud_mode:
+                # Cloud agents project onto the same shared-web action
+                # contract through the cloud-chat proxy, so the ksadk-web
+                # headless data layer drives them like hosted-ui does.
+                cloud_target = cloud_chat_target(requested_agent_id)
+                data = None
+                if action == "GetAgentUiBootstrap":
+                    data = await cloud_web.bootstrap(cloud_target)
+                elif action == "ListAgentModels":
+                    data = await cloud_web.list_models(cloud_target)
+                elif action == "ListSessions":
+                    data = await cloud_web.list_sessions(
+                        cloud_target,
+                        page=int(payload.get("Page") or 1),
+                        page_size=int(payload.get("PageSize") or 30),
+                    )
+                elif action == "CreateSession":
+                    data = await cloud_web.create_session(cloud_target)
+                elif action == "GetSession":
+                    data = await cloud_web.get_session(
+                        cloud_target, str(payload.get("SessionId") or "")
+                    )
+                elif action == "DeleteSession":
+                    data = await cloud_web.delete_session(
+                        cloud_target, str(payload.get("SessionId") or "")
+                    )
+                elif action == "ListSessionMessages":
+                    data = await cloud_web.list_messages(
+                        cloud_target,
+                        str(payload.get("SessionId") or ""),
+                        after_seq_id=_optional_int(payload.get("AfterSeqId")),
+                        before_seq_id=_optional_int(payload.get("BeforeSeqId")),
+                        limit=int(payload.get("Limit") or 50),
+                    )
+                elif action == "ListSessionEvents":
+                    data = await cloud_web.list_session_events(
+                        cloud_target,
+                        str(payload.get("SessionId") or ""),
+                        after_seq_id=_optional_int(payload.get("AfterSeqId")),
+                        offset=_optional_int(payload.get("Offset")),
+                        limit=int(payload.get("Limit") or 200),
+                    )
+                elif action == "SubmitInteraction":
+                    data = await cloud_web.submit_interaction(
+                        cloud_target, str(payload.get("SessionId") or ""), payload
+                    )
+                elif action == "RunAgent":
+                    # Open the upstream connection before StreamingResponse
+                    # commits status 200, so admission failures remain a
+                    # structured HTTP error instead of an empty SSE body.
+                    upstream_stream = await cloud_web.open_run_stream(cloud_target, payload)
+                    return StreamingResponse(
+                        cloud_web.stream_run(
+                            cloud_target,
+                            payload,
+                            upstream_stream=upstream_stream,
+                        ),
+                        media_type="text/event-stream",
+                        headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+                    )
+                elif action in {
+                    "GetResponseFeedback",
+                    "UpsertResponseFeedback",
+                    "DeleteResponseFeedback",
+                    "ListSessionCheckpoints",
+                    "ListToolReceipts",
+                }:
+                    data = {"Feedback": None} if action == "GetResponseFeedback" else {}
+                else:
+                    return JSONResponse(
+                        status_code=404,
+                        content={
+                            "Code": 404,
+                            "Message": f"Studio 尚未实现云端共享 Web 动作：{action}",
+                            "Data": {},
+                        },
+                    )
+                return {"Code": 0, "Message": "OK", "Data": data}
             if action == "GetAgentUiBootstrap":
-                data = shared_web.bootstrap(shared_web.resolve_agent_id(requested_agent_id or None))
-            elif action == "ListAgentModels":
-                data = shared_web.list_models(
-                    shared_web.resolve_agent_id(requested_agent_id or None)
+                bootstrap_agent_id = shared_web.resolve_agent_id(
+                    requested_agent_id or None
                 )
+                # 冷启动时 provider 模型描述符尚未发现；绑定 model:provider:*
+                # 的 Agent（尤其 Harness）若直接解析会 RESOURCE_NOT_FOUND，
+                # 前端只能无限转圈。访问资源库不应该是打开对话的前置条件。
+                if not bootstrap_agent_id.startswith(("ar-", "account:")):
+                    await runtime_model_catalog()
+                data = shared_web.bootstrap(bootstrap_agent_id)
+            elif action == "ListAgentModels":
+                model_agent_id = shared_web.resolve_agent_id(requested_agent_id or None)
+                # A cold Studio process has no discovered provider descriptors.
+                # Resolve the same cached catalog as Resources before projecting
+                # model windows; visiting Resources must not be a prerequisite.
+                await runtime_model_catalog()
+                data = shared_web.list_models(model_agent_id)
             elif action == "ListSessions":
-                data = shared_web.list_sessions(
+                data = await shared_web.list_sessions(
                     shared_web.resolve_agent_id(requested_agent_id or None),
                     page=int(payload.get("Page") or 1),
                     page_size=int(payload.get("PageSize") or 30),
                 )
             elif action == "CreateSession":
-                data = shared_web.create_session(
+                data = await shared_web.create_session(
                     shared_web.resolve_agent_id(requested_agent_id or None)
                 )
             elif action == "GetSession":
-                data = shared_web.get_session(str(payload.get("SessionId") or ""))
+                data = await shared_web.get_session(str(payload.get("SessionId") or ""))
+            elif action == "CompactSession":
+                data = await shared_web.compact_session(
+                    shared_web.resolve_agent_id(requested_agent_id or None),
+                    str(payload.get("SessionId") or ""),
+                )
             elif action == "DeleteSession":
-                data = shared_web.delete_session(str(payload.get("SessionId") or ""))
+                data = await shared_web.delete_session(str(payload.get("SessionId") or ""))
             elif action == "ListSessionMessages":
                 data = await shared_web.list_messages(
                     str(payload.get("SessionId") or ""),
@@ -648,8 +942,12 @@ def create_studio_app(
             elif action == "ListSessionEvents":
                 data = await shared_web.list_session_events(str(payload.get("SessionId") or ""))
             elif action == "RunAgent":
+                # A cold process has not discovered provider model descriptors
+                # yet. Run admission may need to materialize a current Build,
+                # so chat must not depend on visiting the Models page first.
+                await runtime_model_catalog()
                 return StreamingResponse(
-                    shared_web.stream_run(payload),
+                    shared_web.stream_run(payload, shared_ui=True),
                     media_type="text/event-stream",
                     headers={
                         "Cache-Control": "no-store",
@@ -657,7 +955,35 @@ def create_studio_app(
                     },
                 )
             elif action == "CancelRun":
-                data = shared_web.cancel_run(str(payload.get("InvocationId") or ""))
+                data = await shared_web.cancel_run(str(payload.get("InvocationId") or ""))
+            elif action == "SubmitInteraction":
+                run_id = str(payload.get("RunId") or "")
+                studio._require_direct_run(run_id)
+                interaction_id = str(payload.get("InteractionId") or "")
+                resolved = await studio.run_service.submit_interaction(
+                    run_id,
+                    interaction_id,
+                    name=str(payload.get("Action") or "submit"),
+                    data=(
+                        dict(payload.get("Response"))
+                        if isinstance(payload.get("Response"), dict)
+                        else {}
+                    ),
+                    expected_revision=int(payload.get("ExpectedRevision") or 0),
+                    idempotency_key=str(payload.get("IdempotencyKey") or ""),
+                )
+                data = {
+                    "schema_version": 1,
+                    "command_id": str(
+                        resolved.get("eventId")
+                        or resolved.get("resolutionEventId")
+                        or f"interaction:{interaction_id}"
+                    ),
+                    "status": "accepted",
+                    "message_id": None,
+                    "run_id": run_id,
+                    "accepted_seq": int(resolved.get("eventId") or 0),
+                }
             elif action in {
                 "GetResponseFeedback",
                 "UpsertResponseFeedback",
@@ -669,6 +995,10 @@ def create_studio_app(
             elif action == "ListToolReceipts":
                 data = {"ToolReceipts": []}
             else:
+                # Channel-related actions: proxy to channel backend
+                if action in CHANNEL_ACTIONS:
+                    status, body = await studio.channel_connections.proxy(action, payload)
+                    return JSONResponse(status_code=status, content=body)
                 return JSONResponse(
                     status_code=404,
                     content={
@@ -689,12 +1019,37 @@ def create_studio_app(
             )
 
     @app.get("/agentengine/api/v1/SubscribeRunEvents")
-    async def shared_chat_subscribe_run_events():
-        async def completed_stream():
-            yield "event: done\ndata: [DONE]\n\n"
-
+    async def shared_chat_subscribe_run_events(
+        request: Request,
+        session_id: str = Query(alias="SessionId"),
+        invocation_id: str = Query(alias="InvocationId"),
+        after_seq_id: int = Query(default=0, alias="AfterSeqId", ge=0),
+        agent_id: str | None = Query(default=None, alias="AgentId"),
+    ):
+        requested_agent_id = str(
+            agent_id or request.cookies.get("agentkit_studio_chat_agent") or ""
+        )
+        if is_cloud_agent_id(requested_agent_id):
+            cloud_target = cloud_chat_target(requested_agent_id)
+            return StreamingResponse(
+                cloud_web.subscribe_run_events(
+                    cloud_target,
+                    session_id,
+                    invocation_id,
+                    after_seq_id=after_seq_id,
+                ),
+                media_type="text/event-stream",
+                headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+            )
+        # Validate before StreamingResponse sends headers; invalid identities
+        # remain ordinary actionable HTTP errors.
+        await shared_web.subscription_run_id(session_id, invocation_id)
         return StreamingResponse(
-            completed_stream(),
+            shared_web.subscribe_run_events(
+                session_id,
+                invocation_id,
+                after_seq_id=after_seq_id,
+            ),
             media_type="text/event-stream",
             headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
         )
@@ -716,7 +1071,15 @@ def create_studio_app(
                 status_code=401,
             )
         response.set_cookie(
-            "agentkit_studio_session",
+            session_cookie_name,
+            session_secret,
+            httponly=True,
+            samesite="strict",
+            secure=False,
+            path="/",
+        )
+        response.set_cookie(
+            legacy_session_cookie_name,
             session_secret,
             httponly=True,
             samesite="strict",
@@ -735,13 +1098,15 @@ def create_studio_app(
             "workspace": {
                 "name": studio.workspace.root.name,
                 "path": str(studio.workspace.root),
+                "workspaceId": studio.workspace_record.workspace_id,
             },
             "operationScope": studio.deployment_operation_scope(),
+            "frontend": studio.frontend_assets(),
             "features": {
                 "build": True,
                 "run": True,
                 "runtimeRegistry": True,
-                "runtimeTypes": ["codex", "adk", "langgraph"],
+                "runtimeTypes": ["harness", "codex", "adk", "langgraph"],
                 "evaluation": True,
                 "deployment": True,
                 "cloudRebuild": False,
@@ -758,12 +1123,13 @@ def create_studio_app(
 
     @app.put("/api/v1/system/settings")
     async def update_settings(payload: dict[str, Any]):
-        return studio.update_settings(payload)
+        return await studio.apply_settings(payload)
 
     @app.get("/api/v1/schedules")
     async def list_schedules():
         return {
             "items": studio.scheduler.list_tasks(),
+            "taskOccurrences": studio.scheduler.task_occurrence_summaries(),
             "availability": studio.scheduler.availability(),
         }
 
@@ -835,6 +1201,10 @@ def create_studio_app(
         task_id: str,
         payload: AgentScheduleRequest,
     ):
+        existing = studio.get_agent_schedule(agent_id, task_id)
+        await studio.validate_schedule_session(
+            agent_id, payload.continuity, payload.session_id, existing.target.agent_version_ref
+        )
         return studio.update_agent_schedule(
             agent_id,
             task_id,
@@ -865,23 +1235,222 @@ def create_studio_app(
         studio.get_agent_schedule(agent_id, task_id)
         return {"items": studio.scheduler.list_occurrences(task_id, limit=limit)}
 
+    def _decode_text_file(path: Path) -> str:
+        """Decode with an encoding fallback chain so legacy GBK/GB18030 files
+        written by agents preview correctly instead of turning into mojibake."""
+        raw = path.read_bytes()
+        for encoding in ("utf-8-sig", "utf-8", "gb18030"):
+            try:
+                return raw.decode(encoding)
+            except UnicodeDecodeError:
+                continue
+        return raw.decode("utf-8", errors="replace")
+
+    @app.get("/api/v1/workspace/file")
+    async def read_workspace_file(path: str = Query(...), download: bool = Query(default=False)):
+        """Read one file inside the workspace (or a linked directory) for preview.
+
+        Absolute paths outside the workspace and its linked directories are
+        rejected, as are oversized files; preview clients render the payload
+        according to the returned contentType.
+        """
+        import mimetypes
+        from urllib.parse import quote
+
+        raw = Path(path).expanduser()
+        candidate = raw if raw.is_absolute() else studio.workspace.root / raw
+        try:
+            resolved = candidate.resolve()
+        except OSError as error:
+            raise StudioError("WORKSPACE_FILE_INVALID", "文件路径无效", status_code=422) from error
+
+        allowed_roots = [studio.workspace.root.resolve()]
+        for item in LinkedDirectoryPolicy(studio.workspace.root).list():
+            linked = Path(item.path).expanduser().resolve()
+            if linked.is_dir():
+                allowed_roots.append(linked)
+        if not any(
+            resolved == root or resolved.is_relative_to(root) for root in allowed_roots
+        ):
+            raise StudioError(
+                "WORKSPACE_FILE_FORBIDDEN", "路径不在工作区（或链接目录）内", status_code=403
+            )
+        if not resolved.is_file():
+            raise StudioError("WORKSPACE_FILE_NOT_FOUND", "文件不存在", status_code=404)
+        size = resolved.stat().st_size
+        if size > 2 * 1024 * 1024:
+            raise StudioError(
+                "WORKSPACE_FILE_TOO_LARGE", "文件超过 2MB 预览上限", status_code=413
+            )
+        suffix = resolved.suffix.lower()
+        if suffix in {
+            ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico",
+        }:
+            content_type = mimetypes.guess_type(resolved.name)[0] or "application/octet-stream"
+            media_category = "image"
+            payload: bytes | str = resolved.read_bytes()
+        elif suffix in {".md", ".markdown"}:
+            content_type, media_category = "text/markdown", "markdown"
+            payload = _decode_text_file(resolved)
+        else:
+            text_types = {
+                ".txt", ".json", ".csv", ".tsv", ".log", ".py", ".js", ".ts", ".tsx",
+                ".jsx", ".html", ".css", ".yaml", ".yml", ".toml", ".xml", ".sh",
+                ".sql", ".rs", ".go", ".java", ".c", ".cpp", ".h", ".diff", ".ini",
+            }
+            if suffix not in text_types:
+                raise StudioError(
+                    "WORKSPACE_FILE_UNSUPPORTED", "该文件类型暂不支持预览", status_code=415
+                )
+            content_type, media_category = "text/plain", "text"
+            payload = _decode_text_file(resolved)
+        response = {
+            "path": str(resolved),
+            "name": resolved.name,
+            "sizeBytes": size,
+            "contentType": content_type,
+            "mediaCategory": media_category,
+        }
+        if download:
+            quoted = quote(resolved.name)
+            return Response(
+                content=payload if isinstance(payload, bytes) else payload.encode("utf-8"),
+                media_type=content_type,
+                headers={"Content-Disposition": f"attachment; filename*=UTF-8''{quoted}"},
+            )
+        if media_category == "image":
+            import base64
+
+            response["dataBase64"] = base64.b64encode(payload).decode("ascii")
+        else:
+            response["content"] = payload
+        return response
+
     @app.post("/api/v1/workspaces:open")
     async def open_workspace(payload: WorkspaceOpenRequest):
-        # This endpoint only reconnects to the daemon's already-bound root.  Do
-        # not resolve or otherwise touch a caller-provided filesystem path.
-        requested = os.path.normcase(os.path.abspath(os.path.expanduser(payload.path)))
-        bound_root = os.path.normcase(str(studio.workspace.root))
-        if requested != bound_root:
+        try:
+            # A user-selected directory is itself the workspace. The registry
+            # entry is created as part of opening it; callers do not need to
+            # pre-register paths in a separate settings screen.
+            record = studio.switch(payload.path, create=True)
+            # Start local state immediately, but keep optional DSH/Profile
+            # discovery off the workspace-switch response path.
+            runtime = studio.active
+            await runtime.start(wait_for_dsh=False)
+            schedule_runtime_warmup = getattr(app.state, "runtime_warmups", None)
+            if schedule_runtime_warmup is not None:
+                schedule_runtime_warmup(runtime)
+        except FileNotFoundError as error:
+            raise StudioError("WORKSPACE_NOT_FOUND", "工作区目录不存在", status_code=404) from error
+        response = {
+            "name": record.name,
+            "path": record.path,
+            "workspaceId": record.workspace_id,
+        }
+        # Preserve the legacy reconnect response shape for the daemon root;
+        # switched workspaces include the stable identity for scoped clients.
+        if os.path.normcase(record.path) == os.path.normcase(str(initial_service.workspace.root)):
+            response.pop("workspaceId", None)
+        return response
+
+    @app.post("/api/v1/workspaces:choose")
+    async def choose_workspace_directory():
+        """Open the host folder chooser for a local Web Studio session."""
+        if sys.platform != "darwin":
+            raise StudioError(
+                "WORKSPACE_PICKER_UNAVAILABLE",
+                "当前系统没有可用的原生目录选择器，请输入目录路径",
+                status_code=501,
+            )
+        script = (
+            'tell application "System Events" to set selectedFolder to choose folder '
+            'with prompt "选择 AgentKit Studio 工作区"\n'
+            'POSIX path of selectedFolder'
+        )
+        result = await asyncio.to_thread(
+            subprocess.run,
+            ["osascript", "-e", script],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            return {"path": None, "cancelled": True}
+        path = result.stdout.strip()
+        return {"path": path or None, "cancelled": not bool(path)}
+
+    @app.get("/api/v1/workspaces")
+    async def list_workspaces():
+        active_path = os.path.normcase(str(studio.workspace.root))
+        items = []
+        for record in WorkspaceRegistry().list():
+            item = record.__dict__.copy()
+            item["active"] = os.path.normcase(record.path) == active_path
+            items.append(item)
+        return {"items": items}
+
+    @app.post("/api/v1/workspaces/{workspace_id}/linked-directories")
+    async def add_linked_directory(workspace_id: str, payload: LinkedDirectoryRequest):
+        record = next(
+            (r for r in WorkspaceRegistry().list() if r.workspace_id == workspace_id), None
+        )
+        if record is None or os.path.normcase(record.path) != os.path.normcase(
+            str(studio.workspace.root)
+        ):
             raise StudioError(
-                "WORKSPACE_PATH_FORBIDDEN",
-                "当前 Daemon 不允许切换到启动 root 之外的工作区",
-                status_code=403,
+                "WORKSPACE_NOT_FOUND", "工作区不存在或不属于当前 Studio", status_code=404
+            )
+        item = LinkedDirectoryPolicy(studio.workspace.root).set(
+            payload.path, payload.mode, payload.label
+        )
+        return item.__dict__
+
+    @app.get("/api/v1/workspaces/{workspace_id}/linked-directories")
+    async def list_linked_directories(workspace_id: str):
+        record = next(
+            (r for r in WorkspaceRegistry().list() if r.workspace_id == workspace_id), None
+        )
+        if record is None or os.path.normcase(record.path) != os.path.normcase(
+            str(studio.workspace.root)
+        ):
+            raise StudioError(
+                "WORKSPACE_NOT_FOUND", "工作区不存在或不属于当前 Studio", status_code=404
             )
         return {
-            "name": studio.workspace.root.name,
-            "path": str(studio.workspace.root),
+            "items": [item.__dict__ for item in LinkedDirectoryPolicy(studio.workspace.root).list()]
         }
 
+    @app.delete("/api/v1/workspaces/{workspace_id}/linked-directories")
+    async def remove_linked_directory(workspace_id: str, path: str):
+        record = next(
+            (r for r in WorkspaceRegistry().list() if r.workspace_id == workspace_id), None
+        )
+        if record is None or os.path.normcase(record.path) != os.path.normcase(
+            str(studio.workspace.root)
+        ):
+            raise StudioError(
+                "WORKSPACE_NOT_FOUND", "工作区不存在或不属于当前 Studio", status_code=404
+            )
+        return {"removed": LinkedDirectoryPolicy(studio.workspace.root).remove(path)}
+
+    @app.get("/api/v1/workspaces/{workspace_id}/linked-directories/authorize")
+    async def authorize_linked_directory(
+        workspace_id: str,
+        path: str,
+        operation: Literal["read", "write"] = "read",
+    ):
+        record = next(
+            (r for r in WorkspaceRegistry().list() if r.workspace_id == workspace_id), None
+        )
+        if record is None or os.path.normcase(record.path) != os.path.normcase(
+            str(studio.workspace.root)
+        ):
+            raise StudioError(
+                "WORKSPACE_NOT_FOUND", "工作区不存在或不属于当前 Studio", status_code=404
+            )
+        allowed = LinkedDirectoryPolicy(studio.workspace.root).authorize(path, operation)
+        return {"path": path, "operation": operation, "allowed": allowed}
+
     @app.get("/api/v1/codex/manifest")
     async def get_codex_manifest():
         return studio.codex_manifest_state()
@@ -970,6 +1539,7 @@ def create_studio_app(
         unrelated Build.
         """
 
+        await runtime_model_catalog()
         build = await studio.ensure_current_build(agent_id)
         return {
             "buildId": build.id,
@@ -1205,9 +1775,53 @@ def create_studio_app(
     async def get_agent(agent_id: str):
         return studio.agent_detail(agent_id)
 
+    @app.post("/api/v1/agents/{agent_id}/runtime:prewarm", status_code=202)
+    async def prewarm_agent_runtime(agent_id: str, payload: dict[str, Any]):
+        """后台预热当前 Build 的 Provider 激活（MCP/图编译），不执行任何 turn。
+
+        首 token 延迟的主因是首轮 open_activation 时的 MCP spawn/health/list
+        （实测 ~12s）。前端在进入会话时 fire-and-forget 调用本端点，把这段
+        开销移到用户输入之前；失败静默（首轮照旧现场预热）。
+        """
+        session_id = str(payload.get("sessionId") or "")
+        if not session_id:
+            raise StudioError(
+                "SESSION_ID_REQUIRED", "缺少 sessionId", status_code=422
+            )
+        try:
+            build = await studio.ensure_current_build(agent_id)
+        except StudioError as exc:
+            raise StudioError(
+                "BUILD_NOT_FOUND", f"Agent 尚无可运行的 Build：{exc.message}",
+                status_code=404,
+            ) from exc
+
+        async def warm() -> None:
+            try:
+                spec = studio.resolve_run_spec(build.id)
+                runtime = studio.run_service.plugin_runtime
+                if runtime is None:
+                    return
+                kernel_adapter = getattr(runtime, "kernel_adapter", None)
+                if kernel_adapter is None:
+                    return
+                # 打开并保留激活（以 session 为 key）；下一轮 RunAgent 直接复用，
+                # 不再现场 spawn/health/list MCP。
+                await kernel_adapter(spec, session_id=session_id)
+            except Exception as error:
+                logger.info("runtime prewarm for %s skipped: %s", agent_id, error)
+
+        task = asyncio.create_task(warm())
+        app.state.runtime_prewarms = getattr(app.state, "runtime_prewarms", set())
+        app.state.runtime_prewarms.add(task)
+        task.add_done_callback(app.state.runtime_prewarms.discard)
+        return {"status": "prewarming", "buildId": build.id}
+
     @app.get("/api/v1/agents/{agent_id}/models")
     async def get_agent_models(agent_id: str):
-        return shared_web.list_models(shared_web.resolve_agent_id(agent_id))
+        model_agent_id = shared_web.resolve_agent_id(agent_id)
+        await runtime_model_catalog()
+        return shared_web.list_models(model_agent_id)
 
     @app.put("/api/v1/agents/{agent_id}")
     async def update_agent(
@@ -1308,6 +1922,7 @@ def create_studio_app(
         payload: BuildRequest,
         idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
     ):
+        await runtime_model_catalog()
         return studio.submit_studio_build(
             agent_id,
             revision=payload.revision,
@@ -1360,19 +1975,34 @@ def create_studio_app(
 
     @app.get("/api/v1/runs/{run_id}")
     async def get_run(run_id: str):
-        return studio.event_store.get(run_id)
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        return runtime.event_store.get(run_id)
 
     @app.post("/api/v1/runs/{run_id}:cancel", status_code=202)
     async def cancel_run(run_id: str):
-        return await studio.run_service.cancel_run(run_id)
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        runtime._require_direct_run(run_id)
+        return await runtime.run_service.cancel_run(run_id)
 
     @app.post("/api/v1/runs/{run_id}:pause", status_code=202)
     async def pause_run(run_id: str):
-        return await studio.run_service.pause_run(run_id)
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        runtime._require_direct_run(run_id)
+        return await runtime.run_service.pause_run(run_id)
 
     @app.post("/api/v1/runs/{run_id}:resume", status_code=202)
     async def resume_run(run_id: str):
-        return await studio.run_service.resume_run(run_id)
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        runtime._require_direct_run(run_id)
+        return await runtime.run_service.resume_run(run_id)
 
     @app.post("/api/v1/runs/{run_id}/interactions/{interaction_id}:submit")
     async def submit_run_interaction(
@@ -1380,7 +2010,10 @@ def create_studio_app(
         interaction_id: str,
         payload: InteractionSubmitRequest,
     ):
-        return await studio.run_service.submit_interaction(
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        return await runtime.run_service.submit_interaction(
             run_id,
             interaction_id,
             name=payload.name,
@@ -1392,7 +2025,10 @@ def create_studio_app(
     @app.get("/api/v1/runs/{run_id}/context")
     async def get_run_context(run_id: str):
         """Runtime Context Evidence：planned/projected/actual + 精度 + ownership。"""
-        record = studio.event_store.get(run_id)
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        record = runtime.event_store.get(run_id)
         plan = record.context_plan or {}
         evidence = record.prompt_evidence or {}
         return {
@@ -1446,7 +2082,10 @@ def create_studio_app(
 
     @app.delete("/api/v1/sessions/{session_id}", status_code=204)
     async def delete_studio_session(session_id: str):
-        await studio.delete_session(session_id)
+        runtime = await studio.runtime_for_session(session_id)
+        if runtime is None:
+            raise StudioError("SESSION_NOT_FOUND", "会话不存在", status_code=404)
+        await runtime.delete_session(session_id)
         return Response(status_code=204)
 
     @app.get("/api/v1/sessions/{session_id}/events")
@@ -1456,7 +2095,10 @@ def create_studio_app(
         invocation_id: str | None = Query(default=None, alias="invocationId"),
         limit: int = Query(default=100, ge=1, le=500),
     ):
-        return await studio.trajectory_page(
+        runtime = await studio.runtime_for_session(session_id)
+        if runtime is None:
+            raise StudioError("SESSION_NOT_FOUND", "会话不存在", status_code=404)
+        return await runtime.trajectory_page(
             session_id,
             before_seq_id=before_seq_id,
             invocation_id=invocation_id,
@@ -1470,10 +2112,13 @@ def create_studio_app(
         after_seq_id: int = Query(default=0, ge=0, alias="afterSeqId"),
         invocation_id: str | None = Query(default=None, alias="invocationId"),
     ):
-        await studio._require_runtime_session(session_id)
+        runtime = await studio.runtime_for_session(session_id)
+        if runtime is None:
+            raise StudioError("SESSION_NOT_FOUND", "会话不存在", status_code=404)
+        await runtime._require_runtime_session(session_id)
         last = request.headers.get("Last-Event-ID")
         cursor = int(last) if last and last.isdigit() else after_seq_id
-        stream = studio.stream_trajectory(
+        stream = runtime.stream_trajectory(
             session_id,
             cursor,
             invocation_id=invocation_id,
@@ -1544,6 +2189,44 @@ def create_studio_app(
     async def list_runs(session_id: str | None = Query(default=None, alias="sessionId")):
         return {"items": studio.event_store.list_runs(session_id=session_id)}
 
+    @app.get("/api/v1/workspaces/runs")
+    async def list_workspace_runs():
+        """后台入口：聚合所有已打开 workspace 的运行，并保留归属。"""
+        return {"items": studio.all_runs()}
+
+    @app.get("/api/v1/workspaces/operations")
+    async def list_workspace_operations():
+        return {"items": studio.all_operations()}
+
+    @app.get("/api/v1/runs/{run_id}/documents/metadata")
+    def run_document_metadata(run_id: str, path: str, request: Request):
+        return document_metadata(studio, run_id, path, local=is_local_desktop_request(request))
+
+    @app.post("/api/v1/runs/{run_id}/documents/actions")
+    def run_document_action(run_id: str, payload: NativeDocumentActionRequest, request: Request):
+        return perform_document_action(
+            studio, run_id, payload, local=is_local_desktop_request(request)
+        )
+
+    @app.get("/api/v1/runs/{run_id}/documents/content")
+    def run_document(run_id: str, path: str, preview: bool = False):
+        file_path, content = read_document(studio, run_id, path)
+        if preview:
+            return JSONResponse(
+                {"name": file_path.name, "content": content},
+                headers={"Cache-Control": "no-store"},
+            )
+        return Response(
+            content,
+            media_type="text/markdown",
+            headers={
+                "Content-Disposition": "attachment; filename*=UTF-8''"
+                + quote(file_path.name),
+                "X-Content-Type-Options": "nosniff",
+                "Cache-Control": "no-store",
+            },
+        )
+
     @app.get("/api/v1/runs/{run_id}/events")
     async def run_events(
         run_id: str,
@@ -1552,7 +2235,10 @@ def create_studio_app(
     ):
         last = request.headers.get("Last-Event-ID")
         cursor = int(last) if last and last.isdigit() else after
-        events = await studio.run_service.events(run_id, after=cursor)
+        runtime = studio.runtime_for_run(run_id)
+        if runtime is None:
+            raise StudioError("RUN_NOT_FOUND", "运行不存在", status_code=404)
+        events = await runtime.run_service.events(run_id, after=cursor)
         return _sse(events)
 
     @app.get("/api/v1/traces/overview")
@@ -1567,6 +2253,10 @@ def create_studio_app(
             status=status,
         )
 
+    @app.get("/api/v1/workspaces/traces")
+    async def list_workspace_traces():
+        return {"items": studio.all_traces()}
+
     @app.get("/api/v1/traces")
     async def list_traces(
         agent_id: str | None = Query(default=None, alias="agentId"),
@@ -1668,7 +2358,7 @@ def create_studio_app(
     async def list_deployments():
         """Read local deployment receipts without implicit cloud refreshes."""
 
-        return {"items": studio.cloud.list()}
+        return {"items": studio.cloud.list(), "currentIdentity": studio.cloud.cached_identity()}
 
     @app.get("/api/v1/cloud-agents")
     async def list_account_cloud_agents(
@@ -2010,11 +2700,17 @@ def create_studio_app(
 
     @app.get("/api/v1/operations/{operation_id}")
     async def get_operation(operation_id: str):
-        return studio.operations.get(operation_id)
+        runtime = studio.runtime_for_operation(operation_id)
+        if runtime is None:
+            raise StudioError("OPERATION_NOT_FOUND", "操作不存在", status_code=404)
+        return runtime.operations.get(operation_id)
 
     @app.post("/api/v1/operations/{operation_id}:cancel")
     async def cancel_operation(operation_id: str):
-        return studio.operations.cancel(operation_id)
+        runtime = studio.runtime_for_operation(operation_id)
+        if runtime is None:
+            raise StudioError("OPERATION_NOT_FOUND", "操作不存在", status_code=404)
+        return runtime.operations.cancel(operation_id)
 
     @app.get("/api/v1/operations/{operation_id}/events")
     async def operation_events(
@@ -2024,7 +2720,10 @@ def create_studio_app(
     ):
         last = request.headers.get("Last-Event-ID")
         cursor = int(last) if last and last.isdigit() else after
-        events = studio.operations.events(operation_id, after=cursor)
+        runtime = studio.runtime_for_operation(operation_id)
+        if runtime is None:
+            raise StudioError("OPERATION_NOT_FOUND", "操作不存在", status_code=404)
+        events = runtime.operations.events(operation_id, after=cursor)
         if "application/json" in request.headers.get("Accept", ""):
             return {"items": events}
         return _sse(events)
@@ -2035,6 +2734,24 @@ def create_studio_app(
         runtime_model_catalog=runtime_model_catalog,
     )
     register_memory_routes(app, studio)
+    register_resource_connection_routes(app, studio)
     register_plugin_routes(app, studio)
+    async def workspace_plugin_api(scope, receive, send):
+        # The plugin registry belongs to the active workspace. Mounting the
+        # initial service registry directly would keep lifecycle/routes pinned
+        # to the first folder after a workspace switch.
+        await studio.active.workspace_plugins.api(scope, receive, send)
+
+    app.mount("/api/v1", workspace_plugin_api, name="workspace-plugin-api")
+
+    from ksadk.studio.dsh_application import register_dsh_application
+
+    register_dsh_application(
+        app,
+        studio,
+        session_secret=session_secret,
+        security_enabled=security_enabled,
+        fallback_url="/studio-shell/",
+    )
 
     return app