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

ksadk/studio/service.py

@@ -7,6 +7,7 @@ import hashlib
 import json
 import logging
 import os
+import time
 import zipfile
 from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence
 from contextlib import asynccontextmanager
@@ -88,6 +89,7 @@ from ksadk.studio.codex_plugin_store import CodexPluginSnapshotStore
 from ksadk.studio.codex_provider_build import CodexProviderBuildManager
 from ksadk.studio.codex_run import CodexRunSpecResolver
 from ksadk.studio.compiler import AgentCompiler
+from ksadk.studio.configuration import SETTINGS_ENV, WorkspaceConfiguration
 from ksadk.studio.contracts import (
     AgentAppearance,
     AgentBindings,
@@ -102,6 +104,7 @@ from ksadk.studio.contracts import (
     DiagnosticSeverity,
     Operation,
     OperationKind,
+    OperationStatus,
     RunEvent,
     RunStatus,
     RuntimeRef,
@@ -123,7 +126,7 @@ from ksadk.studio.model_profile_service import test_model_profile_connection
 from ksadk.studio.operations import OperationManager
 from ksadk.studio.plugin_composition import StudioPluginCompositionCompiler
 from ksadk.studio.plugin_runtime import StudioPluginRuntime
-from ksadk.studio.repository import AgentDraftRepository, BuildRepository, load_yaml_file
+from ksadk.studio.repository import AgentDraftRepository, BuildRepository
 from ksadk.studio.resource_authority import (
     ResourceAuthorityPolicy,
     SignedKnowledgeResourceAuthority,
@@ -149,9 +152,11 @@ from ksadk.studio.templates import (
     compose_research_agent,
     default_agent_spec,
     list_agent_templates,
+    with_harness_provider_permissions,
 )
 from ksadk.studio.validator import AgentValidator
 from ksadk.studio.workspace import Workspace
+from ksadk.studio.workspace_registry import WorkspaceRegistry
 
 _T = TypeVar("_T")
 
@@ -186,6 +191,7 @@ class StudioService:
         dsh_provider_registration_manager: StudioDshProviderRegistrationManager | None = None,
         dsh_capability_service: StudioDshCapabilityService | None = None,
         resource_authority_policy: ResourceAuthorityPolicy | None = None,
+        configuration_overrides: dict[str, str] | None = None,
     ) -> None:
         provider_manifests = dict(plugin_provider_manifests or {})
         provider_factories = dict(plugin_provider_factories or {})
@@ -195,6 +201,8 @@ class StudioService:
             )
         self.workspace = Workspace(root)
         self.workspace.initialize()
+        self.workspace_registry = WorkspaceRegistry()
+        self.workspace_record = self.workspace_registry.open(self.workspace.root)
         self._startup_provider_manifests = provider_manifests
         self._startup_provider_factories = provider_factories
         self._active_provider_manifests = dict(provider_manifests)
@@ -208,9 +216,11 @@ class StudioService:
             dsh_capability_service
             or StudioDshCapabilityService.discover_or_create_workspace_default(self.workspace.root)
         )
-        if dsh_capability_service is not None or os.environ.get(
-            "KSADK_DSH_HOME", ""
-        ).strip() or os.environ.get("KSADK_DSH_PROFILE", "").strip():
+        if (
+            dsh_capability_service is not None
+            or os.environ.get("KSADK_DSH_HOME", "").strip()
+            or os.environ.get("KSADK_DSH_PROFILE", "").strip()
+        ):
             self._resource_dsh_provider_registration_manager = None
             self.resource_dsh_capabilities = self.dsh_capabilities
         else:
@@ -220,13 +230,18 @@ class StudioService:
                 )
             )
             self.resource_dsh_capabilities = (
-                StudioDshCapabilityService.create_workspace_resource_default(
-                    self.workspace.root
-                )
+                StudioDshCapabilityService.create_workspace_resource_default(self.workspace.root)
             )
         self._start_lock = asyncio.Lock()
+        self._profile_maintenance = False
         self._started = False
+        self._dsh_startup_task: asyncio.Task[None] | None = None
+        self._dsh_ready = False
         self._closed = False
+        self.configuration = WorkspaceConfiguration(
+            self.workspace, overrides=configuration_overrides
+        )
+        self._resource_authority_policy_override = resource_authority_policy
         self._apply_persisted_settings()
         self.avatar_assets = AgentAvatarAssetStore(self.workspace)
         self.conversation_attachments = ConversationAttachmentStore(self.workspace)
@@ -236,18 +251,16 @@ class StudioService:
         self.credentials = (
             credential_resolver
             or getattr(model_client, "credential_resolver", None)
-            or CredentialResolver(self.workspace)
+            or CredentialResolver(self.workspace, configuration=self.configuration)
         )
         self.resource_connections = ResourceConnectionRepository(self.workspace, self.credentials)
         effective_resource_policy = (
             resource_authority_policy
             if resource_authority_policy is not None
-            else resource_authority_policy_from_environment()
+            else resource_authority_policy_from_environment(self.configuration.environment())
         )
         self.resource_authority = (
-            SignedKnowledgeResourceAuthority(
-                self.resource_connections, effective_resource_policy
-            )
+            SignedKnowledgeResourceAuthority(self.resource_connections, effective_resource_policy)
             if effective_resource_policy is not None
             else None
         )
@@ -341,16 +354,32 @@ class StudioService:
             resolve_adapter_provider=self._scheduler_adapter_provider,
             session_service=self.session_service,
             runtime_executor=self.runtime_executor,
+            state_dir=self.workspace.resolve(".agentkit/plugin-runtime/state"),
         )
         self.scheduler = StudioSchedulerService(
             self.workspace,
             runtime_registry=self.scheduler_runtimes,
         )
+        from ksadk.studio.execution_host import StudioExecutionHost
+        from ksadk.studio.teams_installation import create_teams_installation
+        from ksadk.studio.workspace_plugins import WorkspacePluginRegistry
+
+        self.workspace_plugins = WorkspacePluginRegistry()
+        self.execution_host = StudioExecutionHost(
+            self.scheduler_runtimes,
+            state_path=self.workspace.resolve(".agentkit/plugin-runtime/execution-host.sqlite"),
+        )
+        self.plugin_runs.execution_policy_resolver = self.execution_host
+        self.teams_installation = create_teams_installation(self)
+        from ksadk.studio.channel_connections import StudioChannelConnections
+
+        self.channel_connections = StudioChannelConnections(self)
         from ksadk.studio.scheduler_assistant import StudioScheduleAssistant
 
         self.run_service.schedule_assistant = StudioScheduleAssistant(self)
         self.mcp_runtime = MCPRuntimeAdapter(self.workspace, credentials=self.credentials)
         self._cloud_gateway_override = cloud_gateway
+        self._profile_maintenance = False
         self.cloud = CloudDeploymentService(
             self.workspace,
             gateway=cloud_gateway or self._configured_cloud_gateway(),
@@ -360,13 +389,37 @@ class StudioService:
         self.evaluation_storage = EvaluationStorage(self.workspace.resolve(".agentkit/evaluations"))
         self.authoring = StudioAuthoringCoordinator(self)
         self.codex_agents = CodexAgentService(self)
-
-    async def start(self) -> None:
-        """Bind ready managed DSH registrations before build or execution."""
-
+        self._current_codex_builds: dict[str, CodexBuildRecord] = {}
+        # agent_detail 进程内 TTL 缓存：bootstrap/list_models/list_sessions 等
+        # 转发接口在会话切换时反复调用 agent_detail，每次都重做 builds 全扫 +
+        # validator.validate（100-300ms）。5s TTL 把切换/刷新的重复读折叠掉；
+        # create/update/delete agent 时主动失效。
+        self._agent_detail_cache: dict[str, tuple[float, dict[str, Any]]] = {}
+        self._agent_detail_ttl = 5.0
+
+    async def start(self, *, wait_for_dsh: bool = True) -> None:
+        """Start local state and optionally wait for the managed DSH profile."""
+        # Desktop workspace switching must not queue behind an in-flight DSH
+        # discovery task.  The service is already usable while that optional
+        # task finishes in the background; callers that explicitly request
+        # readiness still await the task below.
+        if self._started and not wait_for_dsh:
+            return
+        async with self._start_lock:
+            self._ensure_open()
+            if not self._started:
+                await self.scheduler_runtimes.start()
+                self._started = True
+                self._dsh_startup_task = asyncio.create_task(self._initialize_dsh())
+                self.channel_connections.start_background()
+            task = self._dsh_startup_task
+        if wait_for_dsh and task is not None:
+            await asyncio.shield(task)
+
+    async def _initialize_dsh(self) -> None:
         async with self._start_lock:
             self._ensure_open()
-            if self._started:
+            if self._dsh_ready:
                 return
             await self._bootstrap_official_dsh_defaults()
             manifests, factories, manager_refs = await self._provider_snapshot(refresh=False)
@@ -376,21 +429,32 @@ class StudioService:
             manager = self._dsh_provider_registration_manager
             if manager is not None and manager_refs is not None:
                 manager.mark_bound(manager_refs)
-            self._started = True
+            self._dsh_ready = True
 
     async def refresh_dsh_provider_registrations(self) -> None:
         """Rebind the exact current DSH Profile and release stale activations."""
 
         async with self._start_lock:
             self._ensure_open()
-            safe_to_resume = False
+            await self.execution_host.set_admission_open(False)
+            await self.scheduler_runtimes.set_admission_open(False)
+            self._profile_maintenance = True
+            safe_to_resume = True
             try:
+                await self._require_profile_idle()
+                safe_to_resume = False
                 await self.plugin_runs.suspend_admission()
                 await self.reset_dsh_capability_state()
                 await self._bind_dsh_provider_registrations_locked(refresh=True)
                 await self._refresh_dsh_catalog_resource(required=False)
                 safe_to_resume = True
             finally:
+                # 维护窗标志是纯同步状态，无条件复位：任何异常/取消路径都不得
+                # 把整个会话面永久留在 503。admission 的恢复语义不变（恢复失败
+                # 仍按契约保持关闭，由测试 test_failed_profile_rebind_* 保障）。
+                self._profile_maintenance = False
+                await self.execution_host.set_admission_open(safe_to_resume)
+                await self.scheduler_runtimes.set_admission_open(safe_to_resume)
                 if safe_to_resume:
                     await self.plugin_runs.resume_admission()
 
@@ -402,12 +466,21 @@ class StudioService:
 
         async with self._start_lock:
             self._ensure_open()
-            safe_to_resume = False
+            await self.execution_host.set_admission_open(False)
+            await self.scheduler_runtimes.set_admission_open(False)
+            self._profile_maintenance = True
+            safe_to_resume = True
             try:
+                await self._require_profile_idle()
+                safe_to_resume = False
                 await self.plugin_runs.suspend_admission()
                 await self.reset_dsh_capability_state()
                 try:
                     result = await operation()
+                except asyncio.CancelledError:
+                    # 取消中的任务做不了 recovery；维护窗标志在 finally 无条件
+                    # 复位，避免一次取消把会话面永久 503。
+                    raise
                 except BaseException as mutation_error:
                     if (
                         isinstance(mutation_error, StudioError)
@@ -429,9 +502,45 @@ class StudioService:
                 safe_to_resume = True
                 return result
             finally:
+                # 维护窗标志是纯同步状态，无条件复位：任何异常/取消路径都不得
+                # 把整个会话面永久留在 503。admission 的恢复语义不变（恢复失败
+                # 仍按契约保持关闭，由测试 test_failed_profile_rebind_* 保障）。
+                self._profile_maintenance = False
+                await self.execution_host.set_admission_open(safe_to_resume)
+                await self.scheduler_runtimes.set_admission_open(safe_to_resume)
                 if safe_to_resume:
                     await self.plugin_runs.resume_admission()
 
+    async def _require_profile_idle(self) -> None:
+        pending = await self.scheduler_runtimes.unsettled_sessions()
+        active_operations = [
+            operation for operation in self.operations.list()
+            if operation.status in {OperationStatus.QUEUED, OperationStatus.RUNNING}
+        ]
+        if pending or active_operations:
+            raise StudioError("DSH_PROFILE_IN_USE",
+                "仍有执行或审批正在进行，请结束执行后再变更插件 Profile", status_code=409)
+
+    def _require_direct_session(self, session_id: str | None) -> None:
+        if self._profile_maintenance:
+            raise StudioError("DSH_PROFILE_MAINTENANCE", "插件宿主正在维护", status_code=503)
+        if session_id:
+            from ksadk.studio.execution_host import ExecutionHostError
+
+            try:
+                self.execution_host.require_unreserved_session(session_id)
+            except ExecutionHostError as error:
+                raise StudioError(error.code, str(error), status_code=error.status) from error
+
+    def _require_direct_run(self, run_id: str) -> None:
+        from ksadk.studio.execution_host import ExecutionHostError
+
+        self._require_direct_session(None)
+        try:
+            self.execution_host.require_unreserved_run(run_id)
+        except ExecutionHostError as error:
+            raise StudioError(error.code, str(error), status_code=error.status) from error
+
     async def _bind_dsh_provider_registrations_locked(self, *, refresh: bool) -> None:
         if self._dsh_provider_registration_manager is None:
             self._dsh_provider_registration_manager = (
@@ -448,6 +557,7 @@ class StudioService:
         if manager is not None and manager_refs is not None:
             manager.mark_bound(manager_refs)
         self._started = True
+        self._dsh_ready = True
 
     async def reset_dsh_capability_state(self) -> None:
         """Drop the current DSH capability/Core generation."""
@@ -531,6 +641,17 @@ class StudioService:
                 logging.getLogger(__name__).info(
                     "official Codex DSH provider bootstrap: %s", result
                 )
+        try:
+            harness_result = await manager.bootstrap_official_harness_provider()
+        except Exception as error:
+            logging.getLogger(__name__).warning(
+                "official Harness DSH provider bootstrap skipped: %s", error
+            )
+        else:
+            if harness_result in {"installed", "already_enabled"}:
+                logging.getLogger(__name__).info(
+                    "official Harness DSH provider bootstrap: %s", harness_result
+                )
         try:
             resource_result = await manager.bootstrap_official_resource_plugins()
         except Exception as error:  # optional DSH must fail closed to legacy paths
@@ -768,6 +889,7 @@ class StudioService:
         sending provider-specific fields to every Runtime.
         """
 
+        self._require_direct_session(session_id)
         spec = self.resolve_run_spec(build_id)
         runtime_type = spec.launch_context.runtime_type.strip().lower()
         runtime_mode: Literal["native", "translated"] = (
@@ -784,7 +906,7 @@ class StudioService:
                     ConversationCapability(name="attachment.image", mode="native"),
                     # Bounded UTF-8/code attachments are made model-visible as
                     # deterministic text parts by the Responses compatibility
-                    # adapter.  Binary files remain unavailable in Phase 2.
+                    # adapter.  Binary files remain unavailable in Release.
                     ConversationCapability(name="attachment.file", mode="translated"),
                     ConversationCapability(name="reasoning.effort", mode="native"),
                     ConversationCapability(name="goal", mode="native"),
@@ -826,14 +948,24 @@ class StudioService:
         await self.start()
         if self.is_codex_agent(agent_id):
             self.codex_agent_detail(agent_id)
+            manifest_snapshot = self.codex_manifests.load(agent_id)
+            cached = self._current_codex_builds.get(agent_id)
+            if cached is not None and cached.manifest_sha256 == manifest_snapshot.manifest_sha256:
+                try:
+                    return self.codex_builds.get(cached.id)
+                except StudioError:
+                    self._current_codex_builds.pop(agent_id, None)
             builds = [
                 record
                 for record in self.codex_builds.list()
                 if record.agent_name == agent_id and self.codex_builder.is_current(record)
             ]
             if builds:
+                self._current_codex_builds[agent_id] = builds[0]
                 return builds[0]
-            return await asyncio.to_thread(self.codex_builder.build, agent_id)
+            built = await asyncio.to_thread(self.codex_builder.build, agent_id)
+            self._current_codex_builds[agent_id] = built
+            return built
         draft = self.drafts.get(agent_id)
         composition_required = self.plugin_compositions.required_for(draft)
         resources_required = resource_build_required(draft)
@@ -853,6 +985,8 @@ class StudioService:
                             "当前 Agent 需要插件组合，但无法生成 Composition",
                             status_code=409,
                         )
+                    if not self._build_has_composition(record, composition=composition):
+                        continue
                     self.plugin_compositions.bind_build(
                         composition,
                         agent_id=draft.metadata.id,
@@ -917,7 +1051,7 @@ class StudioService:
             )
         return record
 
-    def _build_has_composition(self, record: Any) -> bool:
+    def _build_has_composition(self, record: Any, *, composition: Any = None) -> bool:
         """Reject stale pre-Phase-2 builds for a composed runtime.
 
         This check is intentionally scoped to Harness/plugin runtimes. Legacy
@@ -936,6 +1070,13 @@ class StudioService:
                 and manifest.get("compositionProfileDigest")
                 and "composition-profile.json" in names
                 and "plugin-lock.json" in names
+                and (
+                    composition is None
+                    or (
+                        manifest.get("compositionProfileDigest") == composition.profile_digest
+                        and manifest.get("pluginLockDigest") == composition.plugin_lock_digest
+                    )
+                )
             )
         except (KeyError, OSError, UnicodeError, ValueError, zipfile.BadZipFile):
             return False
@@ -1140,12 +1281,15 @@ class StudioService:
         name: str | None = None,
         labels: dict[str, str] | None = None,
     ) -> AgentDraft:
-        return self.codex_agents.create(
+        created = self.codex_agents.create(
             agent_id=agent_id,
             spec=spec,
             name=name,
             labels=labels,
         )
+        self._current_codex_builds.pop(agent_id, None)
+        self.invalidate_agent_detail(agent_id)
+        return created
 
     def update_codex_agent(
         self,
@@ -1155,15 +1299,20 @@ class StudioService:
         expected_revision: int,
         name: str | None = None,
     ) -> AgentDraft:
-        return self.codex_agents.update(
+        updated = self.codex_agents.update(
             agent_id,
             spec,
             expected_revision=expected_revision,
             name=name,
         )
+        self._current_codex_builds.pop(agent_id, None)
+        self.invalidate_agent_detail(agent_id)
+        return updated
 
     def delete_codex_agent(self, agent_id: str, *, purge: bool = False) -> None:
         self.codex_agents.delete(agent_id, purge=purge)
+        self._current_codex_builds.pop(agent_id, None)
+        self.invalidate_agent_detail(agent_id)
 
     def codex_agent_detail(self, agent_id: str | None = None) -> dict:
         return self.codex_agents.detail(agent_id)
@@ -1199,6 +1348,7 @@ class StudioService:
         idempotency_key: str,
         on_event: Callable[[RunEvent], None] | None = None,
     ) -> Operation:
+        self._require_direct_session(session_id)
         return self.codex_agents.submit_run(
             build_id,
             user_input,
@@ -1217,17 +1367,23 @@ class StudioService:
     async def delete_session(self, session_id: str) -> None:
         from ksadk.studio.errors import not_found
 
+        self._require_direct_session(session_id)
         runs = self.event_store.list_runs(session_id=session_id)
         session = await self.session_service.get_session_metadata(session_id)
         if not runs and session is None:
             raise not_found("session", session_id)
-        if any(run.status == RunStatus.RUNNING for run in runs):
-            raise StudioError(
-                "SESSION_RUN_ACTIVE",
-                "会话仍在运行，请先停止运行后再删除",
-                status_code=409,
-                details={"sessionId": session_id},
-            )
+        # 磁盘停在 RUNNING 的 run 只有仍在本进程内执行时才阻止删除；
+        # 崩溃/重启遗留的僵尸 RUNNING 一律回收为 canceled 后放行删除。
+        for run in runs:
+            if run.status == RunStatus.RUNNING:
+                if self.run_service.is_run_executing(run.id):
+                    raise StudioError(
+                        "SESSION_RUN_ACTIVE",
+                        "会话仍在运行，请先停止运行后再删除",
+                        status_code=409,
+                        details={"sessionId": session_id},
+                    )
+                await self.run_service.reap_stale_running_run(run.id)
         await self.plugin_runs.close_session(session_id)
         await self.session_service.delete_session(session_id)
         self.event_store.delete_session(session_id)
@@ -1238,6 +1394,8 @@ class StudioService:
         async with self._start_lock:
             if self._closed:
                 return
+            if self._dsh_startup_task is not None and not self._dsh_startup_task.done():
+                self._dsh_startup_task.cancel()
             self._closed = True
             cleanup = asyncio.create_task(self._close_owned_plugin_services())
             interrupted = False
@@ -1251,8 +1409,20 @@ class StudioService:
                 raise asyncio.CancelledError
 
     async def _close_owned_plugin_services(self) -> None:
+        from ksadk.studio.provider_recovery import detach_recovered_runs
+
+        await detach_recovered_runs(self.run_service)
         first_error: BaseException | None = None
-        owned = [self.plugin_runs.aclose, self.dsh_capabilities.aclose]
+        owned = [
+            self.channel_connections.close,
+            self.workspace_plugins.close, self.plugin_runs.aclose, self.dsh_capabilities.aclose,
+            self.scheduler_runtimes.close, self.execution_host.close,
+        ]
+        # The model client owns a keep-alive connection pool shared by all
+        # turns. Close it with the Studio service so shutdown remains clean.
+        close_model_client = getattr(self.model_client, "aclose", None)
+        if close_model_client is not None:
+            owned.append(close_model_client)
         if self.resource_dsh_capabilities is not self.dsh_capabilities:
             owned.append(self.resource_dsh_capabilities.aclose)
         if self._dsh_provider_registration_manager is not None:
@@ -1277,6 +1447,7 @@ class StudioService:
             )
 
     async def _require_runtime_session(self, session_id: str) -> None:
+        self._require_direct_session(session_id)
         if await self.session_service.get_session_metadata(session_id) is None:
             raise StudioError(
                 "SESSION_NOT_FOUND",
@@ -1799,17 +1970,29 @@ class StudioService:
         return values[:limit]
 
     def agent_detail(self, agent_id: str) -> dict:
+        cached = self._agent_detail_cache.get(agent_id)
+        if cached and cached[0] > time.monotonic():
+            return cached[1]
         if self.is_codex_agent(agent_id):
             detail = self.codex_agent_detail(agent_id)
             detail["soulProjection"] = self._soul_projection(detail["draft"])
-            return detail
-        draft = self.drafts.get(agent_id)
-        return {
-            "draft": draft,
-            "builds": self.builds.list_for_agent(agent_id)[:10],
-            "validation": self.validator.validate(draft),
-            "soulProjection": self._soul_projection(draft),
-        }
+        else:
+            draft = self.drafts.get(agent_id)
+            detail = {
+                "draft": draft,
+                "builds": self.builds.list_for_agent(agent_id)[:10],
+                "validation": self.validator.validate(draft),
+                "soulProjection": self._soul_projection(draft),
+            }
+        self._agent_detail_cache[agent_id] = (time.monotonic() + self._agent_detail_ttl, detail)
+        return detail
+
+    def invalidate_agent_detail(self, agent_id: str | None = None) -> None:
+        """Invalidate cached agent_detail after create/update/delete/build."""
+        if agent_id is None:
+            self._agent_detail_cache.clear()
+        else:
+            self._agent_detail_cache.pop(agent_id, None)
 
     @staticmethod
     def _soul_projection(draft: AgentDraft) -> dict[str, object]:
@@ -1850,6 +2033,8 @@ class StudioService:
         )
         selected = runtime or resolved_spec.runtime
         resolved_spec.runtime = selected
+        if selected is not None and selected.type == "harness" and spec is None:
+            resolved_spec = with_harness_provider_permissions(resolved_spec)
         if selected is not None and selected.type == "codex":
             return cast(
                 AgentDraft,
@@ -1860,7 +2045,7 @@ class StudioService:
                     labels=labels,
                 ),
             )
-        return cast(
+        created = cast(
             AgentDraft,
             self.create_agent(
                 agent_id=agent_id,
@@ -1871,6 +2056,8 @@ class StudioService:
                 labels=labels,
             ),
         )
+        self.invalidate_agent_detail(agent_id)
+        return created
 
     def update_studio_agent(
         self,
@@ -1942,17 +2129,21 @@ class StudioService:
                 appearance,
                 expected_revision=expected_revision,
             )
-        return self.drafts.update_appearance(
+        updated = self.drafts.update_appearance(
             agent_id,
             appearance,
             expected_revision=expected_revision,
         )
+        self.invalidate_agent_detail(agent_id)
+        return updated
 
     def delete_studio_agent(self, agent_id: str, *, purge: bool = False) -> None:
         if self.is_codex_agent(agent_id):
             self.delete_codex_agent(agent_id, purge=purge)
+            self.invalidate_agent_detail(agent_id)
             return
         delete_framework_agent(self, agent_id, purge=purge)
+        self.invalidate_agent_detail(agent_id)
 
     def validate_studio_agent(
         self,
@@ -1979,11 +2170,13 @@ class StudioService:
         # Check workspace ownership, but never project the mutable draft as runtime state.
         await asyncio.to_thread(self.agent_detail, agent_id)
         status = await self.dsh_capabilities.resource_runtime_status(
-            agent_id=agent_id, activation_id=activation_id,
+            agent_id=agent_id,
+            activation_id=activation_id,
         )
         if status is None:
             raise StudioError(
-                "RESOURCE_ACTIVATION_NOT_FOUND", "未找到此 Agent 的资源运行实例",
+                "RESOURCE_ACTIVATION_NOT_FOUND",
+                "未找到此 Agent 的资源运行实例",
                 status_code=404,
             )
         return status
@@ -1995,10 +2188,14 @@ class StudioService:
         draft = self.agent_detail(agent_id)["draft"]
         if draft.metadata.revision != expected_revision:
             raise StudioError(
-                "AGENT_REVISION_CONFLICT", "资源校验版本与当前 Agent 不一致", status_code=409,
+                "AGENT_REVISION_CONFLICT",
+                "资源校验版本与当前 Agent 不一致",
+                status_code=409,
             )
         diagnostics = resource_binding_diagnostics(
-            draft.spec.bindings.plugins, draft.spec.memory, self.resource_connections,
+            draft.spec.bindings.plugins,
+            draft.spec.memory,
+            self.resource_connections,
         )
         configs = [
             (index, config)
@@ -2029,8 +2226,7 @@ class StudioService:
                             severity=DiagnosticSeverity.ERROR,
                             code=error.code,
                             message=error.message,
-                            field=error.field
-                            or f"spec.bindings.plugins[{index}].config.binding",
+                            field=error.field or f"spec.bindings.plugins[{index}].config.binding",
                         )
                     )
             current = self.agent_detail(agent_id)["draft"]
@@ -2114,6 +2310,7 @@ class StudioService:
         runtime_input: Any = None,
         on_event: Callable[[RunEvent], None] | None = None,
     ) -> Operation:
+        self._require_direct_session(session_id)
         try:
             self.codex_builds.get(build_id)
         except Exception as exc:
@@ -2230,12 +2427,14 @@ class StudioService:
             preview,
             catalog=self.catalog,
         )
-        return self.drafts.update(
+        updated = self.drafts.update(
             agent_id,
             spec,
             expected_revision=expected_revision,
             name=name,
         )
+        self.invalidate_agent_detail(agent_id)
+        return updated
 
     def update_agent_bindings(
         self,
@@ -2424,6 +2623,7 @@ class StudioService:
         idempotency_key: str,
         on_event: Callable[[RunEvent], None] | None = None,
     ) -> Operation:
+        self._require_direct_session(session_id)
         async def runner(_operation_id: str):
             return await self.run_build(
                 build_id,
@@ -2464,6 +2664,7 @@ class StudioService:
         """Execute any immutable Studio Build through the canonical executor."""
 
         await self.start()
+        self._require_direct_session(session_id)
         spec = self.resolve_run_spec(
             build_id,
             model=model,
@@ -3081,41 +3282,68 @@ class StudioService:
             "cloudCredential": opaque(f"{region}\0{access_key}"),
         }
 
+    @staticmethod
+    def frontend_assets() -> dict[str, Any]:
+        import re
+
+        entry = Path(__file__).with_name("static") / "index.html"
+        if not entry.is_file():
+            return {"entryAssets": []}
+        assets = re.findall(
+            r'(?:src|href)="(/static/assets/[^"<>]+\.(?:js|css))"',
+            entry.read_text(encoding="utf-8"),
+        )
+        return {"entryAssets": [Path(asset).name for asset in assets]}
+
     def get_settings(self) -> dict[str, Any]:
-        path = self.workspace.resolve(".agentkit/settings.yaml")
-        data: dict[str, Any] = {}
-        if path.is_file():
-            try:
-                data = load_yaml_file(path) or {}
-            except Exception:
-                data = {}
+        data = self.configuration.settings()
+        environment = self.configuration.environment()
         defaults = {
-            "sandbox": os.environ.get("KSADK_CODEX_SANDBOX", "workspace-write-auto"),
+            "sandbox": environment.get("KSADK_CODEX_SANDBOX", "workspace-write-auto"),
             "buildAfterCreate": True,
             "codexProxy": current_proxy_mode(),
-            "cloudRegion": os.environ.get(
-                "AGENTENGINE_REGION", os.environ.get("KSYUN_REGION", "cn-beijing-6")
+            "cloudRegion": environment.get(
+                "AGENTENGINE_REGION", environment.get("KSYUN_REGION", "cn-beijing-6")
             ),
-            "cloudBucket": os.environ.get("KS3_BUCKET", ""),
-            "cloudAccountId": (os.environ.get("KSYUN_ACCOUNT_ID", "").strip()),
+            "cloudServerUrl": environment.get("AGENTENGINE_SERVER_URL", ""),
+            "cloudBucket": environment.get("KS3_BUCKET", ""),
+            "cloudAccountId": (environment.get("KSYUN_ACCOUNT_ID", "").strip()),
             # AK/SK 不回显(避免本地 UI 回传 secret);只暴露配置状态。
             # 已配置 = 启动环境或已持久化 settings 里 AK+SK 齐全。
             "cloudAccountConfigured": bool(
-                (os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY", "")).strip()
+                (
+                    environment.get("KSYUN_ACCESS_KEY") or environment.get("KS3_ACCESS_KEY", "")
+                ).strip()
                 and (
-                    os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY", "")
+                    environment.get("KSYUN_SECRET_KEY") or environment.get("KS3_SECRET_KEY", "")
                 ).strip()
             ),
             "cloudSignedAccountConfigured": bool(
-                (os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY", "")).strip()
+                (
+                    environment.get("KSYUN_ACCESS_KEY") or environment.get("KS3_ACCESS_KEY", "")
+                ).strip()
                 and (
-                    os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY", "")
+                    environment.get("KSYUN_SECRET_KEY") or environment.get("KS3_SECRET_KEY", "")
                 ).strip()
             ),
-            "traceContent": os.environ.get("KSADK_STUDIO_TRACE_CONTENT", "1") != "0",
+            "traceContent": environment.get("KSADK_STUDIO_TRACE_CONTENT", "1") != "0",
         }
         defaults.update({k: v for k, v in data.items() if k in defaults and v is not None})
-        defaults["codexProxy"] = normalize_proxy_mode(defaults.get("codexProxy"))
+        for key, name in SETTINGS_ENV.items():
+            if key in defaults:
+                value, _source = self.configuration.resolve(name)
+                if value is not None:
+                    defaults[key] = value
+        defaults["configurationSources"] = {
+            key: self.configuration.resolve(name)[1] for key, name in SETTINGS_ENV.items()
+        }
+        defaults["platformResourceMissingFields"] = [
+            key
+            for key in ("cloudAccessKey", "cloudSecretKey", "cloudServerUrl")
+            if not self.configuration.resolve(SETTINGS_ENV[key])[0]
+        ]
+        defaults["platformResourcesConfigured"] = self.resource_authority is not None
+        defaults["codexProxy"] = normalize_proxy_mode(environment.get("KSADK_CODEX_USE_PROXY"))
         return defaults
 
     def update_settings(self, payload: dict[str, Any]) -> dict[str, Any]:
@@ -3125,6 +3353,7 @@ class StudioService:
             "codexProxy",
             "cloudRegion",
             "cloudBucket",
+            "cloudServerUrl",
             "traceContent",
             # 云账号:AK/SK 留空 = 不修改(保留已存值);AccountID 可单独更新。
             "cloudAccessKey",
@@ -3153,35 +3382,102 @@ class StudioService:
             raise StudioError("SETTINGS_INVALID", "sandbox 取值非法", status_code=422)
         if "codexProxy" in data and data["codexProxy"] not in {"auto", "forced", "direct"}:
             raise StudioError("SETTINGS_INVALID", "codexProxy 取值非法", status_code=422)
-        path = self.workspace.resolve(".agentkit/settings.yaml")
-        self.workspace.atomic_write_yaml(path, data)
-        # env 桥接用落盘后的全量数据:局部更新(只改 AccountID)时,
-        # 已持久化的 AK/SK 也要继续桥接,否则签名凭证丢失。
+        for key in (
+            "cloudAccessKey",
+            "cloudSecretKey",
+            "cloudAccountId",
+            "cloudRegion",
+            "cloudBucket",
+            "cloudServerUrl",
+        ):
+            if key in data:
+                if (
+                    not isinstance(data[key], str)
+                    or len(data[key]) > 2048
+                    or any(ord(c) < 32 for c in data[key])
+                ):
+                    raise StudioError(
+                        "SETTINGS_INVALID", "配置值格式无效", status_code=422, field=key
+                    )
+                data[key] = data[key].strip()
+        if data.get("cloudServerUrl"):
+            from ksadk.studio.resource_authority import _canonical_endpoint
+
+            try:
+                data["cloudServerUrl"] = _canonical_endpoint(
+                    data["cloudServerUrl"],
+                    allow_loopback_http=False,
+                    allow_ksyun_internal_http=True,
+                )
+            except ValueError as error:
+                raise StudioError(
+                    "SETTINGS_INVALID",
+                    "控制面地址必须是有效的 HTTPS 服务地址",
+                    status_code=422,
+                    field="cloudServerUrl",
+                ) from error
+        if (
+            "cloudAccessKey" in data
+            and data["cloudAccessKey"] != self.configuration.resolve("KSYUN_ACCESS_KEY")[0]
+        ):
+            if not data.get("cloudSecretKey"):
+                raise StudioError(
+                    "SETTINGS_INVALID",
+                    "切换 Access Key 时请同时填写对应的 Secret Key",
+                    status_code=422,
+                    field="cloudSecretKey",
+                )
+            data.setdefault("cloudAccountId", "")
+        candidate_environment = self.configuration.environment()
+        for key, name in SETTINGS_ENV.items():
+            if key in data and name not in self.configuration.overrides:
+                candidate_environment[name] = str(data[key])
         try:
-            persisted = load_yaml_file(path) or {}
-        except Exception:
-            persisted = data
-        self._apply_settings_to_env(persisted if isinstance(persisted, dict) else data)
+            candidate_policy = (
+                self._resource_authority_policy_override
+                or resource_authority_policy_from_environment(candidate_environment)
+            )
+        except ValueError as error:
+            raise StudioError(
+                "SETTINGS_INVALID", "云端连接配置无效，请检查控制面地址和区域", status_code=422
+            ) from error
+        self.plugin_runs.check_configuration_mutable()
+        self.configuration.update_settings(data)
+        self._apply_persisted_settings()
+        self.resource_authority = (
+            SignedKnowledgeResourceAuthority(self.resource_connections, candidate_policy)
+            if candidate_policy is not None
+            else None
+        )
+        self.plugin_runs.replace_resource_authority(self.resource_authority)
         if self._cloud_gateway_override is None:
             self.cloud.gateway = self._configured_cloud_gateway()
         return self.get_settings()
 
-    def _apply_persisted_settings(self) -> None:
-        """启动时把 settings.yaml 回填到进程环境。
+    async def apply_settings(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Drain old credentials/leases before making a new account visible."""
+        async with self._start_lock:
+            if self.run_service.has_active_runs():
+                raise StudioError(
+                    "SETTINGS_RUNTIME_BUSY", "请等待当前运行结束后再保存设置", status_code=409
+                )
+            try:
+                await self.plugin_runs.suspend_admission()
+                return self.update_settings(payload)
+            finally:
+                await self.plugin_runs.resume_admission()
 
-        update_settings 只在 PUT 时桥接 env;重启后 env 丢失,运行解析
-        (如 _resolve_sandbox 读 KSADK_CODEX_SANDBOX)会回落默认,表现为
-        「设置页显示 workspace-write-auto,实际运行 read-only」。
-        """
-        path = self.workspace.resolve(".agentkit/settings.yaml")
-        if not path.is_file():
-            return
-        try:
-            data = load_yaml_file(path) or {}
-        except Exception:
-            return
-        if isinstance(data, dict):
-            self._apply_settings_to_env(data)
+    def _apply_persisted_settings(self) -> None:
+        data = self.configuration.settings()
+        environment = self.configuration.environment()
+        self._apply_settings_to_env(data)
+        for name in (
+            *SETTINGS_ENV.values(),
+            *self.configuration.dotenv,
+            *self.configuration.overrides,
+        ):
+            if name in environment:
+                os.environ[name] = environment[name]
 
     @staticmethod
     def _apply_settings_to_env(data: dict[str, Any]) -> None:
@@ -3208,34 +3504,33 @@ class StudioService:
         if data.get("cloudAccountId"):
             os.environ["KSYUN_ACCOUNT_ID"] = str(data["cloudAccountId"])
 
-    @staticmethod
-    def _configured_cloud_gateway() -> CloudDeploymentGateway:
+    def _configured_cloud_gateway(self) -> CloudDeploymentGateway:
         """Compose the existing signed Code deployment path from process-only credentials."""
 
+        environment = self.configuration.environment()
         access_key = (
-            os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY", "")
+            environment.get("KSYUN_ACCESS_KEY") or environment.get("KS3_ACCESS_KEY", "")
         ).strip()
         secret_key = (
-            os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY", "")
+            environment.get("KSYUN_SECRET_KEY") or environment.get("KS3_SECRET_KEY", "")
         ).strip()
-        configured_region = os.environ.get(
-            "AGENTENGINE_REGION", os.environ.get("KSYUN_REGION", "")
+        configured_region = environment.get(
+            "AGENTENGINE_REGION", environment.get("KSYUN_REGION", "")
         ).strip()
-        environment_region = os.environ.get("KSYUN_REGION", "").strip()
+        environment_region = environment.get("KSYUN_REGION", "").strip()
         logical_region = (
-            "pre-online"
-            if environment_region.lower() == "pre-online"
-            else configured_region
+            "pre-online" if environment_region.lower() == "pre-online" else configured_region
         )
         if not all((access_key, secret_key, logical_region)):
             return UnavailableCloudGateway()
         control_client = AgentEngineClient(
+            base_url=environment.get("AGENTENGINE_SERVER_URL") or None,
             region=logical_region,
             access_key=access_key,
             secret_key=secret_key,
         )
         is_preonline = logical_region.lower() == "pre-online"
-        stream_base_url = os.environ.get("AGENTENGINE_STREAM_SERVER_URL", "").strip()
+        stream_base_url = environment.get("AGENTENGINE_STREAM_SERVER_URL", "").strip()
         if not stream_base_url and is_preonline:
             # The pre-online KOP response path currently buffers SSE until
             # EOF, and KOP may not yet publish newly deployed native Action
@@ -3257,7 +3552,7 @@ class StudioService:
             client=control_client,
             stream_client=stream_client,
             managed_runtime_client=stream_client if is_preonline else None,
-            bucket=os.environ.get("KS3_BUCKET", "").strip() or None,
+            bucket=environment.get("KS3_BUCKET", "").strip() or None,
             ks3_credentials={
                 "access_key": access_key,
                 "secret_key": secret_key,