agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/studio/api.py

@@ -4,18 +4,25 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import hashlib
 import hmac
 import json
+import logging
 import os
 import secrets
+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
 
+import httpx
 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
 
@@ -26,13 +33,17 @@ from ksadk.conversations.contracts import (
     validate_conversation_input,
 )
 from ksadk.conversations.projector import project_conversation_item
+from ksadk.conversations.runtime_payloads import extract_responses_resume_input
 from ksadk.events.canonical import parse_runtime_event_lenient
 from ksadk.scheduler.contracts import ScheduledTask
+from ksadk.studio.api_a2a_routes import register_a2a_routes
 from ksadk.studio.api_catalog_routes import register_catalog_routes
 from ksadk.studio.api_contracts import (
     AgentScheduleRequest,
     AuthoringCommitRequest,
     BuildRequest,
+    CancelChildRequest,
+    ChildInputRequest,
     CloudAgentVersionRollbackRequest,
     CloudChatInteractionSubmitRequest,
     CloudChatMessageRequest,
@@ -42,12 +53,15 @@ from ksadk.studio.api_contracts import (
     CreateAgentRequest,
     ImportRootRequest,
     InteractionSubmitRequest,
+    LinkedDirectoryRequest,
     ProjectInspectRequest,
+    PromoteChildRequest,
     PromptCompileRequest,
     QuickAuthoringRequest,
     RollbackRequest,
     RunRequest,
     SessionExchangeRequest,
+    SteerRunRequest,
     StudioEvaluationCreate,
     ValidationRequest,
     WorkspaceOpenRequest,
@@ -79,6 +93,11 @@ 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 (
@@ -90,8 +109,24 @@ 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,
+)
+from ksadk.version import __version__ as _sdk_version
+
+logger = logging.getLogger(__name__)
 
 _WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
 _PUBLIC_API_PATHS = {
@@ -105,107 +140,38 @@ _LOCAL_HOSTS = {"127.0.0.1", "::1", "localhost", "testserver"}
 # convention.  This is a narrow transport normalizer, not a provider payload
 # rewrite: only fields owned by the frozen RuntimeEvent envelope/content
 # contracts are translated before strict parsing.
-_RUNTIME_EVENT_WIRE_ALIASES = {
-    "schemaVersion": "schema_version",
-    "eventId": "event_id",
-    "runId": "run_id",
-    "runSeq": "run_seq",
-    "scopeId": "scope_id",
-    "parentScopeId": "parent_scope_id",
-    "eventType": "event_type",
-    "itemId": "item_id",
-    "itemKind": "item_kind",
-    "interactionId": "interaction_id",
-    "interactionKind": "interaction_kind",
-    "continuationId": "continuation_id",
-    "resumeAttemptId": "resume_attempt_id",
-    "outputRefs": "output_refs",
-    "inputTokens": "input_tokens",
-    "outputTokens": "output_tokens",
-    "totalTokens": "total_tokens",
-    "cachedTokens": "cached_tokens",
-    "reasoningTokens": "reasoning_tokens",
-}
-_SOURCE_WIRE_ALIASES = {
-    "nativeEventId": "native_event_id",
-    "nativeCursor": "native_cursor",
-    "nativeRunId": "native_run_id",
-    "nativeItemId": "native_item_id",
-}
-_CONTENT_WIRE_ALIASES = {
-    "contentType": "content_type",
-    "partId": "part_id",
-    "callId": "call_id",
-    "artifactId": "artifact_id",
-    "mimeType": "mime_type",
-    "isError": "is_error",
-}
+import re as _re
 
+from ksadk.studio.api_cloud_chat_routes import _normalize_cloud_runtime_event_wire, _cloud_event_conversation_item, register_cloud_chat_routes
 
-def _normalize_cloud_runtime_event_wire(value: dict[str, Any]) -> dict[str, Any]:
-    """Normalize only historic REST casing at the RuntimeEvent boundary."""
+from ksadk.studio.api_cloud_chat_routes import _RUNTIME_EVENT_WIRE_ALIASES, _SOURCE_WIRE_ALIASES, _CONTENT_WIRE_ALIASES
 
-    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"] = {
-            _SOURCE_WIRE_ALIASES.get(key, key): item for key, item in source.items()
-        }
+# 内容 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 normalize_content(content: Any) -> Any:
-        if not isinstance(content, dict):
-            return content
-        return {_CONTENT_WIRE_ALIASES.get(key, key): item for key, item in content.items()}
-
-    normalized["update"] = normalize_content(normalized.get("update"))
-    for key in ("initial", "snapshot"):
-        snapshot = normalized.get(key)
-        if not isinstance(snapshot, dict):
-            continue
-        parts = snapshot.get("parts")
-        if isinstance(parts, list):
-            normalized[key] = {
-                **snapshot,
-                "parts": [normalize_content(part) for part in parts],
-            }
-    return normalized
-
-
-def _cloud_event_conversation_item(
-    event: dict[str, Any], *, session_id: str
-) -> dict[str, Any] | None:
-    """Project a complete cloud RuntimeEvent without inventing a browser item.
-
-    Cloud SessionEvent history has a compatibility envelope around the runtime
-    payload.  Keep the source event untouched, but add the same typed
-    ConversationItem that local Studio streams use whenever the nested event
-    validates against RuntimeEvent/v2.  A malformed or older envelope is still
-    observable to diagnostics, never guessed into an actionable chat card.
-    """
-
-    payload = event.get("payload") if isinstance(event.get("payload"), dict) else event
-    content = payload.get("content") if isinstance(payload.get("content"), dict) else {}
-    candidates = (
-        content.get("runtime_event"),
-        content.get("runtimeEvent"),
-        payload.get("runtime_event"),
-        payload.get("runtimeEvent"),
-        event.get("runtime_event"),
-        event.get("runtimeEvent"),
-    )
-    raw_event = next((candidate for candidate in candidates if isinstance(candidate, dict)), None)
-    if raw_event is None:
-        return None
-    try:
-        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,
-            run_id=runtime_event.run_id,
-        )
-    except (TypeError, ValueError):
-        return None
-    return item.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+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")
+
+
+_PYPI_LATEST_URL = "https://pypi.org/pypi/ksadk/json"
+
+
+def _version_key(value: str) -> tuple[int, ...]:
+    parts = [int(piece) for piece in value.split(".") if piece.isdigit()]
+    return tuple(parts) or (0,)
+
+
+async def _fetch_latest_ksadk_version() -> str:
+    async with httpx.AsyncClient(timeout=httpx.Timeout(6.0)) as client:
+        response = await client.get(_PYPI_LATEST_URL)
+        response.raise_for_status()
+        return str(response.json()["info"]["version"])
 
 
 def create_studio_app(
@@ -216,21 +182,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",
@@ -261,14 +320,18 @@ def create_studio_app(
         collaboration_mode: str | None = None,
         goal_objective: str | None = None,
         runtime_input: Any = None,
+        presentation_profile: Literal["flat-v1", "agent-block-v1"] = "flat-v1",
         idempotency_key: str,
     ) -> StreamingResponse:
         """Create an observer-only SSE response for one durable Studio run."""
 
         queue: asyncio.Queue = asyncio.Queue()
+        from ksadk.studio.presentation import StudioConversationProjection
+
+        presentation = StudioConversationProjection(session_id, presentation_profile)
 
         def observe(event):
-            queue.put_nowait(event)
+            queue.put_nowait(presentation.apply(event))
 
         # The Operation owns the runtime task. The SSE response is only one
         # observer, so refreshing or switching chats cannot cancel the Run.
@@ -285,6 +348,10 @@ def create_studio_app(
             runtime_input=runtime_input,
             idempotency_key=idempotency_key,
             on_event=observe,
+            **(
+                {"presentation_profile": presentation_profile}
+                if presentation_profile != "flat-v1" else {}
+            ),
         )
 
         async def render():
@@ -324,7 +391,8 @@ def create_studio_app(
 
     static_root = Path(__file__).with_name("static")
     shared_web = StudioSharedWebBridge(studio)
-    cloud_web = CloudSharedWebBridge(studio.cloud)
+    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")
 
@@ -379,8 +447,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(
@@ -391,7 +461,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(
@@ -404,11 +475,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"
@@ -466,18 +533,23 @@ def create_studio_app(
         )
 
     @app.get("/")
-    async def index():
-        path = static_root / "index.html"
-        html = path.read_text(encoding="utf-8")
-        # Vite filenames are content hashed and index.html is no-store. Keep
-        # entry module URLs byte-for-byte identical to their internal imports:
-        # adding a query only to the HTML entry makes browsers evaluate that
-        # module again when a lazy chunk imports the unversioned URL.
-        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",
@@ -486,6 +558,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)
@@ -591,6 +699,31 @@ def create_studio_app(
             or metadata.get("invocationId")
             or f"resp_{secrets.token_hex(12)}"
         )
+        resume_input = extract_responses_resume_input(payload.get("input"))
+        if resume_input is not None:
+            previous_response_id = str(payload.get("previous_response_id") or "").strip()
+            if not previous_response_id:
+                raise StudioError(
+                    "PREVIOUS_RESPONSE_REQUIRED",
+                    "恢复审批时必须提供 previous_response_id",
+                    status_code=422,
+                    field="previous_response_id",
+                )
+            if bool(payload.get("stream")):
+                return StreamingResponse(
+                    shared_web.stream_response_resume(
+                        previous_response_id=previous_response_id,
+                        response_id=response_id,
+                        resume_input=resume_input,
+                    ),
+                    media_type="text/event-stream",
+                    headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+                )
+            return await shared_web.invoke_response_resume(
+                previous_response_id=previous_response_id,
+                response_id=response_id,
+                resume_input=resume_input,
+            )
         bridge_payload: dict[str, Any] = {
             "AgentId": shared_web.resolve_agent_id(agent_id),
             "SessionId": session_id or f"ses_{secrets.token_hex(12)}",
@@ -603,10 +736,9 @@ def create_studio_app(
             "ReasoningEffort": reasoning_effort,
             "ModelExplicit": bool(str(payload.get("model") or "").strip()),
         }
-        bridge_payload["Model"] = shared_web.select_model(
-            bridge_payload["AgentId"],
-            bridge_payload["Model"],
-        )
+        # The shared bridge validates the model after ensuring the current
+        # immutable Build.  Do not validate here: provider-backed catalogs are
+        # discovered during a cold Build and may legitimately be empty now.
         if bool(payload.get("stream")):
             return StreamingResponse(
                 shared_web.stream_run(bridge_payload),
@@ -617,7 +749,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",
@@ -688,6 +820,10 @@ def create_studio_app(
                     data = await cloud_web.submit_interaction(
                         cloud_target, str(payload.get("SessionId") or ""), payload
                     )
+                elif action == "CancelRun" or (
+                    action == "RunAgent" and payload.get("Background") is True
+                ):
+                    data = await cloud_web.cloud.shared_web_action(cloud_target, action, payload)
                 elif action == "RunAgent":
                     # Open the upstream connection before StreamingResponse
                     # commits status 200, so admission failures remain a
@@ -721,7 +857,15 @@ def create_studio_app(
                     )
                 return {"Code": 0, "Message": "OK", "Data": data}
             if action == "GetAgentUiBootstrap":
-                data = shared_web.bootstrap(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.
@@ -741,6 +885,12 @@ def create_studio_app(
                 )
             elif action == "GetSession":
                 data = await shared_web.get_session(str(payload.get("SessionId") or ""))
+            elif action == "GetRunReceipt":
+                data = shared_web.run_receipt(
+                    shared_web.resolve_agent_id(requested_agent_id or None),
+                    str(payload.get("SessionId") or ""),
+                    str(payload.get("InvocationId") or ""),
+                )
             elif action == "CompactSession":
                 data = await shared_web.compact_session(
                     shared_web.resolve_agent_id(requested_agent_id or None),
@@ -771,9 +921,25 @@ 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 == "SteerRun":
+                instruction = payload.get("Text")
+                if (
+                    not isinstance(instruction, str)
+                    or not instruction.strip()
+                    or len(instruction) > 32768
+                ):
+                    raise StudioError(
+                        "RUN_STEER_INVALID", "插话内容必须是非空文本", status_code=422
+                    )
+                data = await shared_web.steer_run(
+                    str(payload.get("InvocationId") or ""),
+                    instruction,
+                    delivery=payload.get("Delivery", "replace"),
+                )
             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,
@@ -810,6 +976,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={
@@ -829,6 +999,34 @@ def create_studio_app(
                 },
             )
 
+    @app.get("/agentengine/api/v1/SubscribeSessionEvents")
+    async def shared_chat_subscribe_session_events(
+        request: Request,
+        session_id: str = Query(alias="SessionId"),
+        after_seq: int = Query(default=0, 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 not is_cloud_agent_id(requested_agent_id):
+            raise StudioError("CLOUD_AGENT_REQUIRED", "需要云端 Agent", status_code=400)
+        stream = await cloud_web.cloud.subscribe_cloud_session_events(
+            cloud_chat_target(requested_agent_id), session_id=session_id, after_seq=after_seq,
+        )
+        async def forward():
+            try:
+                async for chunk in stream:
+                    yield chunk
+            finally:
+                close = getattr(stream, "aclose", None)
+                if close is not None:
+                    await close()
+        return StreamingResponse(
+            forward(), media_type="text/event-stream",
+            headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+        )
+
     @app.get("/agentengine/api/v1/SubscribeRunEvents")
     async def shared_chat_subscribe_run_events(
         request: Request,
@@ -882,7 +1080,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",
@@ -896,18 +1102,21 @@ def create_studio_app(
         return {
             "serverVersion": "1.0.0",
             "apiVersion": "v1",
+            "sdkVersion": _sdk_version,
             "sessionTokenRequired": security_enabled,
             "csrfToken": csrf_secret,
             "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,
@@ -924,7 +1133,24 @@ 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/system/update-check")
+    async def update_check():
+        try:
+            latest = await _fetch_latest_ksadk_version()
+        except Exception as exc:  # noqa: BLE001 - 检查更新失败只降级展示，不进错误链路
+            return {
+                "currentVersion": _sdk_version,
+                "latestVersion": None,
+                "hasUpdate": False,
+                "error": type(exc).__name__,
+            }
+        return {
+            "currentVersion": _sdk_version,
+            "latestVersion": latest,
+            "hasUpdate": _version_key(latest) > _version_key(_sdk_version),
+        }
 
     @app.get("/api/v1/schedules")
     async def list_schedules():
@@ -1036,23 +1262,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()
@@ -1212,6 +1637,19 @@ def create_studio_app(
         display_input = "\n".join(text_parts).strip()
         if not display_input:
             display_input = "请处理本轮附件：" + "、".join(attachment_names)
+        from ksadk.a2a.presentation import negotiate_presentation_profile
+
+        requested_profile = conversation_input.extensions.get("ksadk.presentation", {}).get(
+            "profile"
+        )
+        presentation_profile = negotiate_presentation_profile(
+            producer_declares_capability=any(
+                capability.name == "agent.block" and capability.mode in {"native", "translated"}
+                for capability in surface.outputs
+            ),
+            requested_profile=requested_profile,
+            renderer_supports_agent_block=requested_profile == "agent-block-v1",
+        )
         return _stream_studio_run(
             build_id,
             user_input=display_input,
@@ -1222,6 +1660,7 @@ def create_studio_app(
             approval_mode=conversation_input.approval_mode,
             collaboration_mode=conversation_input.collaboration_mode,
             goal_objective=conversation_input.goal_objective,
+            presentation_profile=presentation_profile,
             runtime_input=runtime_parts if attachment_names else None,
             idempotency_key=key,
         )
@@ -1377,6 +1816,30 @@ 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 的 Host，不提前绑定下一轮 Session 配置。"""
+        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
+
+        from ksadk.studio.runtime_prewarm import prewarm_runtime_build
+
+        task = asyncio.create_task(prewarm_runtime_build(studio, build.id))
+        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):
         model_agent_id = shared_web.resolve_agent_id(agent_id)
@@ -1535,19 +1998,94 @@ 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}:steer", status_code=202)
+    async def steer_run(run_id: str, payload: SteerRunRequest):
+        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.steer_run(run_id, payload.text, delivery=payload.delivery)
 
     @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.get("/api/v1/runs/{run_id}/public-output/{artifact_id}")
+    async def public_tool_output(run_id: str, artifact_id: str):
+        from ksadk.studio.public_output_store import PublicOutputStore
+
+        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)
+        data = PublicOutputStore(runtime.workspace).read(run_id, artifact_id)
+        return Response(content=data["text"], media_type="text/plain; charset=utf-8", headers={
+            "Content-Disposition": 'attachment; filename="tool-output.txt"',
+            "X-Content-Type-Options": "nosniff", "Cache-Control": "private, no-store",
+            "X-Ksadk-Output-Truncated": str(data["truncated"]).lower(),
+        })
+
+    @app.get("/api/v1/runs/{run_id}/children")
+    async def child_tasks(run_id: str):
+        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.child_tasks(run_id)
+
+    @app.post("/api/v1/runs/{run_id}/children/{child_run_id}:cancel", status_code=202)
+    async def cancel_child(run_id: str, child_run_id: str, payload: CancelChildRequest):
+        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_child(run_id, child_run_id,
+                                                     command_id=payload.command_id)
+
+    @app.post("/api/v1/runs/{run_id}/children/{child_run_id}:promote", status_code=202)
+    async def promote_child(run_id: str, child_run_id: str, payload: PromoteChildRequest):
+        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.promote_child(run_id, child_run_id,
+                                                     command_id=payload.command_id)
+
+    @app.post("/api/v1/runs/{run_id}/children/{child_run_id}:send", status_code=202)
+    async def send_child_input(run_id: str, child_run_id: str, payload: ChildInputRequest):
+        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.send_child_input(
+            run_id, child_run_id, text=payload.text, command_id=payload.command_id,
+            expected_goal_revision=payload.expected_goal_revision,
+        )
 
     @app.post("/api/v1/runs/{run_id}/interactions/{interaction_id}:submit")
     async def submit_run_interaction(
@@ -1555,7 +2093,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,
@@ -1567,7 +2108,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 {
@@ -1621,7 +2165,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")
@@ -1631,7 +2178,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,
@@ -1645,10 +2195,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,
@@ -1719,15 +2272,61 @@ 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,
         request: Request,
         after: int = Query(default=0, ge=0),
+        presentation_profile: Literal["flat-v1", "agent-block-v1"] | None = Query(
+            default=None, alias="presentationProfile"
+        ),
     ):
         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, presentation_profile=presentation_profile
+        )
         return _sse(events)
 
     @app.get("/api/v1/traces/overview")
@@ -1742,6 +2341,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"),
@@ -1911,266 +2514,6 @@ def create_studio_app(
 
         return await studio.cloud.delete(deployment_id)
 
-    @app.get("/api/v1/deployments/{deployment_id}/cloud-chat/sessions")
-    async def list_cloud_chat_sessions(
-        deployment_id: str,
-        page: int = Query(default=1, ge=1),
-        size: int = Query(default=50, ge=1, le=100),
-    ):
-        """List Server-owned sessions for this local deployment receipt only."""
-
-        return await studio.cloud.list_cloud_chat_sessions(deployment_id, page=page, size=size)
-
-    @app.get("/api/v1/deployments/{deployment_id}/cloud-chat/models")
-    async def list_cloud_chat_models(deployment_id: str):
-        """List models through Studio's signed Server client."""
-
-        return await studio.cloud.list_cloud_chat_models(deployment_id)
-
-    @app.post(
-        "/api/v1/deployments/{deployment_id}/cloud-chat/sessions",
-        status_code=201,
-    )
-    async def create_cloud_chat_session(deployment_id: str):
-        """Create a cloud session via loopback-held AK/SK; no secret reaches JS."""
-
-        return await studio.cloud.create_cloud_chat_session(deployment_id)
-
-    @app.get("/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}/messages")
-    async def list_cloud_chat_messages(
-        deployment_id: str,
-        session_id: str,
-        after_seq_id: int | None = Query(default=None, alias="afterSeqId", ge=0),
-        limit: int = Query(default=100, ge=1, le=200),
-    ):
-        return await studio.cloud.list_cloud_chat_messages(
-            deployment_id,
-            session_id=session_id,
-            after_seq_id=after_seq_id,
-            limit=limit,
-        )
-
-    @app.get("/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}/events")
-    async def list_cloud_chat_events(
-        deployment_id: str,
-        session_id: str,
-        after_seq_id: int | None = Query(default=None, alias="afterSeqId", ge=0),
-        offset: int | None = Query(default=None, ge=0),
-        limit: int = Query(default=200, ge=1, le=1000),
-    ):
-        return await studio.cloud.list_cloud_chat_events(
-            deployment_id,
-            session_id=session_id,
-            after_seq_id=after_seq_id,
-            offset=offset,
-            limit=limit,
-        )
-
-    @app.get("/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}/events/stream")
-    async def stream_cloud_chat_events(
-        request: Request,
-        deployment_id: str,
-        session_id: str,
-        after_seq_id: int = Query(default=0, alias="afterSeqId", ge=0),
-    ):
-        """Stream canonical cloud events to the loopback browser.
-
-        The public cloud control plane currently exposes cursor reads for this
-        surface.  Keep that cursor in the Studio backend and present one SSE
-        response to the browser, so assistant deltas arrive before the durable
-        terminal message projection without exposing cloud credentials to JS.
-        """
-
-        async def event_stream() -> AsyncIterator[str]:
-            cursor = after_seq_id
-            idle_polls = 0
-            while not await request.is_disconnected():
-                payload = await studio.cloud.list_cloud_chat_events(
-                    deployment_id,
-                    session_id=session_id,
-                    after_seq_id=cursor,
-                    limit=200,
-                )
-                events = payload.get("events") or []
-                if not isinstance(events, list):
-                    events = []
-                terminal = False
-                emitted = False
-                for event in events:
-                    if not isinstance(event, dict):
-                        continue
-                    event_payload = (
-                        event.get("payload") if isinstance(event.get("payload"), dict) else event
-                    )
-                    seq = int(
-                        event_payload.get("seq")
-                        or event_payload.get("seq_id")
-                        or event_payload.get("source_session_seq")
-                        or event.get("seq")
-                        or event.get("seq_id")
-                        or 0
-                    )
-                    if seq and seq <= cursor:
-                        continue
-                    if seq:
-                        cursor = max(cursor, seq)
-                    event_type = str(
-                        event.get("event_type")
-                        or event.get("eventType")
-                        or event_payload.get("event_type")
-                        or event_payload.get("eventType")
-                        or ""
-                    ).lower()
-                    content = (
-                        event_payload.get("content")
-                        if isinstance(event_payload.get("content"), dict)
-                        else {}
-                    )
-                    status = str(event_payload.get("status") or content.get("status") or "").lower()
-                    event_is_terminal = event_type in {
-                        "run.completed",
-                        "run.complete",
-                        "run.succeeded",
-                        "run.failed",
-                        "run.cancelled",
-                        "run.expired",
-                        "run.error",
-                    } or (
-                        event_type in {"run_status", "run.status"}
-                        and status
-                        in {
-                            "completed",
-                            "complete",
-                            "succeeded",
-                            "success",
-                            "failed",
-                            "cancelled",
-                            "canceled",
-                            "expired",
-                            "error",
-                            "aborted",
-                        }
-                    )
-                    terminal = terminal or event_is_terminal
-                    emitted = True
-                    projected_event = dict(event)
-                    conversation_item = _cloud_event_conversation_item(
-                        event,
-                        session_id=session_id,
-                    )
-                    if conversation_item is not None:
-                        projected_event["conversationItem"] = conversation_item
-                    yield (
-                        (f"id: {seq}\n" if seq else "")
-                        + "event: session.event\n"
-                        + f"data: {json.dumps(projected_event, ensure_ascii=False)}\n\n"
-                    )
-                if terminal or payload.get("session_deleted"):
-                    break
-                idle_polls = 0 if emitted else idle_polls + 1
-                if idle_polls and idle_polls % 20 == 0:
-                    yield ": keepalive\n\n"
-                await asyncio.sleep(0.25)
-
-        return StreamingResponse(
-            event_stream(),
-            media_type="text/event-stream",
-            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
-        )
-
-    @app.delete(
-        "/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}",
-        status_code=204,
-    )
-    async def delete_cloud_chat_session(deployment_id: str, session_id: str):
-        await studio.cloud.delete_cloud_chat_session(deployment_id, session_id=session_id)
-        return Response(status_code=204)
-
-    @app.post(
-        "/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}/messages",
-        status_code=202,
-    )
-    async def send_cloud_chat_message(
-        deployment_id: str,
-        session_id: str,
-        payload: CloudChatMessageRequest,
-    ):
-        """Admit one cloud message through Server; response is a durable receipt."""
-
-        return await studio.cloud.send_cloud_chat_message(
-            deployment_id,
-            session_id=session_id,
-            content=payload.content,
-            model=payload.model,
-            model_options=payload.model_options,
-            tool_approval_mode=payload.tool_approval_mode,
-            collaboration_mode=payload.collaboration_mode,
-            goal_objective=payload.goal_objective,
-        )
-
-    @app.post(
-        "/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}/messages/stream"
-    )
-    async def stream_cloud_chat_message(
-        request: Request,
-        deployment_id: str,
-        session_id: str,
-        payload: CloudChatMessageRequest,
-    ):
-        """Proxy one signed foreground RunAgent SSE response to loopback UI."""
-
-        upstream = await studio.cloud.stream_cloud_chat_message(
-            deployment_id,
-            session_id=session_id,
-            content=payload.content,
-            model=payload.model,
-            model_options=payload.model_options,
-            tool_approval_mode=payload.tool_approval_mode,
-            collaboration_mode=payload.collaboration_mode,
-            goal_objective=payload.goal_objective,
-        )
-
-        async def proxy_stream() -> AsyncIterator[bytes]:
-            try:
-                while not await request.is_disconnected():
-                    try:
-                        chunk = await anext(upstream)
-                    except StopAsyncIteration:
-                        break
-                    if await request.is_disconnected():
-                        break
-                    yield chunk
-            finally:
-                close = getattr(upstream, "aclose", None)
-                if close is not None:
-                    await close()
-
-        return StreamingResponse(
-            proxy_stream(),
-            media_type="text/event-stream",
-            headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
-        )
-
-    @app.post(
-        "/api/v1/deployments/{deployment_id}/cloud-chat/sessions/{session_id}/interactions",
-        status_code=202,
-    )
-    async def submit_cloud_chat_interaction(
-        deployment_id: str,
-        session_id: str,
-        payload: CloudChatInteractionSubmitRequest,
-    ):
-        return await studio.cloud.submit_cloud_chat_interaction(
-            deployment_id,
-            session_id=session_id,
-            run_id=payload.run_id,
-            interaction_id=payload.interaction_id,
-            expected_revision=payload.expected_revision,
-            action=payload.action,
-            response=payload.response,
-            idempotency_key=payload.idempotency_key,
-        )
-
     @app.post("/api/v1/deployments/{deployment_id}:rollback", status_code=202)
     async def rollback_deployment(
         deployment_id: str,
@@ -2185,11 +2528,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(
@@ -2199,7 +2548,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)
@@ -2209,14 +2561,27 @@ def create_studio_app(
         studio,
         runtime_model_catalog=runtime_model_catalog,
     )
+    register_cloud_chat_routes(app, studio)
+    register_a2a_routes(app, studio)
     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
+        app,
+        studio,
+        session_secret=session_secret,
+        security_enabled=security_enabled,
+        fallback_url="/studio-shell/",
     )
 
     return app