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

ksadk/studio/service.py

@@ -4,15 +4,20 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
+import json
 import logging
 import os
+import zipfile
+from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence
+from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Callable, Literal, cast
+from typing import Any, Callable, Literal, TypeVar, cast
 from urllib.parse import urlparse
 from uuid import uuid4
 
 from ksadk.api import AgentEngineClient
+from ksadk.conversations.contracts import ConversationCapability, ConversationSurface
 from ksadk.evaluation import (
     EvaluationConfig as PublicEvaluationConfig,
 )
@@ -39,10 +44,23 @@ from ksadk.evaluation.studio_build_adapter import (
 from ksadk.events.store import RuntimeEventStore
 from ksadk.observability.session_log import SessionLogError, export_session_log
 from ksadk.observability.trajectory import encode_sse, project_trajectory_event
+from ksadk.plugins.bundle_security import BundleSecurityError
+from ksadk.plugins.contracts import PluginManifest
+from ksadk.plugins.providers.legacy import LegacyHarnessSource
+from ksadk.plugins.providers.legacy_catalog import (
+    KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
+)
 from ksadk.runtime import RuntimeExecutor, build_default_runtime_registry
+from ksadk.scheduler.contracts import (
+    ScheduleCommandTemplate,
+    ScheduledTask,
+    ScheduledTaskTarget,
+    ScheduleSpec,
+)
 from ksadk.sessions.local_service import LocalSessionService
 from ksadk.studio.agent_avatar_assets import AgentAvatarAssetStore
 from ksadk.studio.agent_lifecycle import delete_framework_agent
+from ksadk.studio.attachment_store import ConversationAttachmentStore
 from ksadk.studio.authoring_coordinator import StudioAuthoringCoordinator
 from ksadk.studio.builder import AgentBundleBuilder
 from ksadk.studio.capabilities import builtin_tool_contracts
@@ -66,6 +84,8 @@ from ksadk.studio.codex_manifest import (
     CodexAgentManifest,
     CodexManifestRepository,
 )
+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.contracts import (
@@ -76,7 +96,10 @@ from ksadk.studio.contracts import (
     AgentTemplateComposeRequest,
     AgentTemplateComposition,
     BuildStatus,
+    BundleManifest,
     DeploymentRequest,
+    Diagnostic,
+    DiagnosticSeverity,
     Operation,
     OperationKind,
     RunEvent,
@@ -84,6 +107,13 @@ from ksadk.studio.contracts import (
     RuntimeRef,
     ToolContract,
 )
+from ksadk.studio.dsh_capability_service import (
+    StudioDshCapabilityService,
+)
+from ksadk.studio.dsh_provider_registration import (
+    StudioDshProviderRegistrationError,
+    StudioDshProviderRegistrationManager,
+)
 from ksadk.studio.errors import StudioError
 from ksadk.studio.event_store import RunEventStore
 from ksadk.studio.framework_run import FrameworkRunSpecResolver
@@ -91,11 +121,29 @@ from ksadk.studio.mcp_runtime import MCPRuntimeAdapter
 from ksadk.studio.model_client import CredentialResolver, OpenAICompatibleModelClient
 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.resource_authority import (
+    ResourceAuthorityPolicy,
+    SignedKnowledgeResourceAuthority,
+    resource_authority_policy_from_environment,
+)
+from ksadk.studio.resource_build_admission import (
+    admit_resource_build,
+    resource_build_required,
+)
 from ksadk.studio.resource_catalog import LocalResourceCatalog
-from ksadk.studio.run_service import StudioRunService
+from ksadk.studio.resource_connections import ResourceConnectionRepository
+from ksadk.studio.run_service import StudioRunService, StudioRunSpec
 from ksadk.studio.runtime_catalog import inspect_runtime_catalog
 from ksadk.studio.runtime_source import materialize_generated_runtime_source
+from ksadk.studio.scheduler_runtime import (
+    StudioScheduledKernelRegistry,
+    StudioSchedulerRuntimeError,
+)
+from ksadk.studio.scheduler_service import StudioSchedulerService
+from ksadk.studio.soul import soul_digest
 from ksadk.studio.templates import (
     compose_blank_agent,
     compose_research_agent,
@@ -105,6 +153,8 @@ from ksadk.studio.templates import (
 from ksadk.studio.validator import AgentValidator
 from ksadk.studio.workspace import Workspace
 
+_T = TypeVar("_T")
+
 _TRAJECTORY_KEEPALIVE_SECONDS = 15.0
 _EVALUATION_TARGET_LABELS = {
     TargetKind.A2A: "A2A Agent",
@@ -129,14 +179,78 @@ class StudioService:
         cloud_gateway: CloudDeploymentGateway | None = None,
         codex_runtime_inspector: RuntimeInspector | None = None,
         runtime_executor: RuntimeExecutor | None = None,
+        harness_reasoner: Any | None = None,
+        plugin_provider_manifests: Mapping[str, PluginManifest] | None = None,
+        plugin_provider_factories: Mapping[str, Any] | None = None,
+        legacy_harness_sources: Sequence[LegacyHarnessSource] = (),
+        dsh_provider_registration_manager: StudioDshProviderRegistrationManager | None = None,
+        dsh_capability_service: StudioDshCapabilityService | None = None,
+        resource_authority_policy: ResourceAuthorityPolicy | None = None,
     ) -> None:
+        provider_manifests = dict(plugin_provider_manifests or {})
+        provider_factories = dict(plugin_provider_factories or {})
+        if provider_manifests.keys() != provider_factories.keys():
+            raise ValueError(
+                "plugin provider manifests and factories must use the same exact references"
+            )
         self.workspace = Workspace(root)
         self.workspace.initialize()
+        self._startup_provider_manifests = provider_manifests
+        self._startup_provider_factories = provider_factories
+        self._active_provider_manifests = dict(provider_manifests)
+        self._dsh_provider_registration_manager = (
+            dsh_provider_registration_manager
+            or StudioDshProviderRegistrationManager.discover_or_create_workspace_default(
+                self.workspace.root
+            )
+        )
+        self.dsh_capabilities = (
+            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():
+            self._resource_dsh_provider_registration_manager = None
+            self.resource_dsh_capabilities = self.dsh_capabilities
+        else:
+            self._resource_dsh_provider_registration_manager = (
+                StudioDshProviderRegistrationManager.create_workspace_resource_default(
+                    self.workspace.root
+                )
+            )
+            self.resource_dsh_capabilities = (
+                StudioDshCapabilityService.create_workspace_resource_default(
+                    self.workspace.root
+                )
+            )
+        self._start_lock = asyncio.Lock()
+        self._started = False
+        self._closed = False
         self._apply_persisted_settings()
         self.avatar_assets = AgentAvatarAssetStore(self.workspace)
+        self.conversation_attachments = ConversationAttachmentStore(self.workspace)
         self.drafts = AgentDraftRepository(self.workspace)
         self.catalog = LocalResourceCatalog(self.workspace)
         self.builds = BuildRepository(self.workspace)
+        self.credentials = (
+            credential_resolver
+            or getattr(model_client, "credential_resolver", None)
+            or CredentialResolver(self.workspace)
+        )
+        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()
+        )
+        self.resource_authority = (
+            SignedKnowledgeResourceAuthority(
+                self.resource_connections, effective_resource_policy
+            )
+            if effective_resource_policy is not None
+            else None
+        )
         self.validator = AgentValidator()
         self.builder = AgentBundleBuilder(
             self.workspace,
@@ -147,12 +261,19 @@ class StudioService:
             ),
             repository=self.builds,
         )
+        self.plugin_compositions = StudioPluginCompositionCompiler(
+            self.workspace,
+            self.catalog,
+            provider_manifests=provider_manifests,
+        )
         self.event_store = RunEventStore(self.workspace)
         self.session_service = LocalSessionService(project_dir=str(self.workspace.root))
         self.runtime_events = RuntimeEventStore(self.session_service)
         self.codex_manifests = CodexManifestRepository(self.workspace)
         self.codex_builds = CodexBuildRepository(self.workspace)
         self.codex_drafts = CodexDraftRepository(self.workspace)
+        self.codex_plugin_snapshots = CodexPluginSnapshotStore(self.workspace)
+        self.codex_provider_builds = CodexProviderBuildManager(self)
         codex_builder_kwargs = {}
         if codex_runtime_inspector is not None:
             codex_builder_kwargs["runtime_inspector"] = codex_runtime_inspector
@@ -162,6 +283,10 @@ class StudioService:
             build_repository=self.codex_builds,
             resource_catalog=self.catalog,
             draft_repository=self.codex_drafts,
+            plugin_snapshot_store=self.codex_plugin_snapshots,
+            resource_connections=self.resource_connections,
+            provider_build=self.codex_provider_builds.prepare,
+            provider_validate=self.codex_provider_builds.bundle_root,
             **codex_builder_kwargs,
         )
         self.runtime_executor = runtime_executor or RuntimeExecutor(
@@ -174,17 +299,15 @@ class StudioService:
             session_service=self.session_service,
             runtime_events=self.runtime_events,
         )
-        self.credentials = (
-            credential_resolver
-            or getattr(model_client, "credential_resolver", None)
-            or CredentialResolver(self.workspace)
-        )
         self.codex_runs = CodexRunSpecResolver(
             self.workspace,
             build_repository=self.codex_builds,
             manifest_repository=self.codex_manifests,
             credential_resolver=self.credentials,
             resource_catalog=self.catalog,
+            draft_repository=self.codex_drafts,
+            plugin_snapshot_store=self.codex_plugin_snapshots,
+            provider_bundle_resolver=self.codex_provider_builds.bundle_root,
         )
         self.framework_runs = FrameworkRunSpecResolver(
             self.workspace,
@@ -194,6 +317,38 @@ class StudioService:
             credential_resolver=self.credentials
         )
         self.model_client = runtime_model_client
+        self.plugin_runs = StudioPluginRuntime(
+            self.workspace,
+            build_repository=self.builds,
+            session_service=self.session_service,
+            model_client=self.model_client,
+            secret_resolver=self.credentials,
+            codex_local_launch_resolver=self.codex_provider_builds.native_launch,
+            runtime_executor=self.runtime_executor,
+            harness_reasoner=harness_reasoner,
+            provider_manifests=provider_manifests,
+            provider_factories=provider_factories,
+            legacy_harness_sources=legacy_harness_sources,
+            dsh_capability_service=self.dsh_capabilities,
+            resource_dsh_capability_service=self.resource_dsh_capabilities,
+            resource_authority=self.resource_authority,
+            resource_connections=self.resource_connections,
+            resource_actor_ref="local-user",
+        )
+        self.run_service.plugin_runtime = self.plugin_runs
+        self.scheduler_runtimes = StudioScheduledKernelRegistry(
+            resolve_build=self.resolve_run_spec,
+            resolve_adapter_provider=self._scheduler_adapter_provider,
+            session_service=self.session_service,
+            runtime_executor=self.runtime_executor,
+        )
+        self.scheduler = StudioSchedulerService(
+            self.workspace,
+            runtime_registry=self.scheduler_runtimes,
+        )
+        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.cloud = CloudDeploymentService(
@@ -202,15 +357,772 @@ class StudioService:
             build_repository=self.builds,
         )
         self.operations = OperationManager(self.workspace)
-        self.evaluation_storage = EvaluationStorage(
-            self.workspace.resolve(".agentkit/evaluations")
-        )
+        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."""
+
+        async with self._start_lock:
+            self._ensure_open()
+            if self._started:
+                return
+            await self._bootstrap_official_dsh_defaults()
+            manifests, factories, manager_refs = await self._provider_snapshot(refresh=False)
+            self.plugin_compositions.replace_provider_registrations(manifests)
+            self.plugin_runs.replace_provider_registrations(manifests, factories)
+            self._active_provider_manifests = manifests
+            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
+
+    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
+            try:
+                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:
+                if safe_to_resume:
+                    await self.plugin_runs.resume_admission()
+
+    async def reconfigure_dsh_profile(
+        self,
+        operation: Callable[[], Awaitable[_T]],
+    ) -> _T:
+        """Run one Profile mutation while all Agent admission is suspended."""
+
+        async with self._start_lock:
+            self._ensure_open()
+            safe_to_resume = False
+            try:
+                await self.plugin_runs.suspend_admission()
+                await self.reset_dsh_capability_state()
+                try:
+                    result = await operation()
+                except BaseException as mutation_error:
+                    if (
+                        isinstance(mutation_error, StudioError)
+                        and mutation_error.code == "DSH_PROFILE_RECOVERY_REQUIRED"
+                    ):
+                        raise
+                    try:
+                        await self._bind_dsh_provider_registrations_locked(refresh=True)
+                        await self._refresh_dsh_catalog_resource(required=False)
+                        safe_to_resume = True
+                    except Exception as recovery_error:  # noqa: BLE001
+                        logging.getLogger(__name__).warning(
+                            "DSH provider recovery after mutation failure skipped: %s",
+                            recovery_error,
+                        )
+                    raise
+                await self._bind_dsh_provider_registrations_locked(refresh=True)
+                await self._refresh_dsh_catalog_resource(required=False)
+                safe_to_resume = True
+                return result
+            finally:
+                if safe_to_resume:
+                    await self.plugin_runs.resume_admission()
+
+    async def _bind_dsh_provider_registrations_locked(self, *, refresh: bool) -> None:
+        if self._dsh_provider_registration_manager is None:
+            self._dsh_provider_registration_manager = (
+                StudioDshProviderRegistrationManager.discover_or_create_workspace_default(
+                    self.workspace.root
+                )
+            )
+        await self._bootstrap_official_dsh_defaults()
+        manifests, factories, manager_refs = await self._provider_snapshot(refresh=refresh)
+        self.plugin_compositions.replace_provider_registrations(manifests)
+        self.plugin_runs.replace_provider_registrations(manifests, factories)
+        self._active_provider_manifests = manifests
+        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
+
+    async def reset_dsh_capability_state(self) -> None:
+        """Drop the current DSH capability/Core generation."""
+
+        self.catalog.clear_dsh_profile_mcp()
+        await self.dsh_capabilities.refresh()
+
+    async def refresh_dsh_catalog_resource(self):  # type: ignore[no-untyped-def]
+        """Validate and publish the current DSH Profile as a bindable MCP."""
+
+        _snapshot, resource = await self.dsh_capability_catalog_snapshot()
+        return resource
+
+    async def dsh_capability_catalog_snapshot(self):  # type: ignore[no-untyped-def]
+        """Atomically snapshot and publish one current DSH generation."""
+
+        async with self._start_lock:
+            self._ensure_open()
+            snapshot = await self.dsh_capabilities.capability_snapshot()
+            resource = self.catalog.replace_dsh_profile_mcp(snapshot.descriptor)
+            return snapshot, resource
+
+    async def ensure_dsh_catalog_available(self) -> None:
+        """Publish an explicitly enabled DSH Profile for the generic selector.
+
+        The normal Studio startup remains side-effect free for legacy users.
+        The generic MCP catalog request performs only a profile metadata check;
+        it starts the managed capability host when the user has already enabled
+        at least one DSH plugin.
+        """
+
+        async with self._start_lock:
+            self._ensure_open()
+            existing = self.catalog.list(kind="mcp", source="provider", limit=200)
+            if any(item.contract.get("materialization") == "dsh-profile" for item in existing):
+                return
+            checker = getattr(self.dsh_capabilities, "has_enabled_profile_plugins", None)
+            if checker is None:
+                return
+            try:
+                enabled = await checker()
+            except Exception as error:  # noqa: BLE001 - optional ecosystem boundary
+                logging.getLogger(__name__).warning("DSH catalog discovery skipped: %s", error)
+                return
+            if enabled:
+                await self._refresh_dsh_catalog_resource(required=False)
+
+    @asynccontextmanager
+    async def dsh_profile_read_transaction(self) -> AsyncIterator[None]:
+        """Fence a UI grant read against Profile mutation and shutdown."""
+
+        async with self._start_lock:
+            self._ensure_open()
+            yield
+
+    async def _refresh_dsh_catalog_resource(self, *, required: bool):  # type: ignore[no-untyped-def]
+        try:
+            snapshot = await self.dsh_capabilities.capability_snapshot()
+            return self.catalog.replace_dsh_profile_mcp(snapshot.descriptor)
+        except Exception as error:  # noqa: BLE001 - optional ecosystem boundary
+            self.catalog.clear_dsh_profile_mcp()
+            if required:
+                raise
+            logging.getLogger(__name__).warning(
+                "DSH capability catalog publication skipped: %s", error
+            )
+            return None
+
+    async def _bootstrap_official_dsh_defaults(self) -> None:
+        manager = self._dsh_provider_registration_manager
+        if manager is None:
+            return
+        try:
+            result = await manager.bootstrap_official_codex_provider()
+        except Exception as error:  # optional DSH must fail closed to legacy paths
+            logging.getLogger(__name__).warning(
+                "official DSH provider bootstrap skipped: %s", error
+            )
+        else:
+            if result in {"installed", "already_enabled"}:
+                logging.getLogger(__name__).info(
+                    "official Codex DSH provider bootstrap: %s", result
+                )
+        try:
+            resource_result = await manager.bootstrap_official_resource_plugins()
+        except Exception as error:  # optional DSH must fail closed to legacy paths
+            logging.getLogger(__name__).warning(
+                "official DSH resource bootstrap skipped: %s", error
+            )
+        else:
+            if resource_result in {"installed", "already_enabled"}:
+                logging.getLogger(__name__).info(
+                    "official platform resource DSH bootstrap: %s", resource_result
+                )
+        resource_manager = self._resource_dsh_provider_registration_manager
+        if resource_manager is None:
+            return
+        try:
+            resource_result = await resource_manager.bootstrap_official_resource_plugins()
+        except Exception as error:
+            logging.getLogger(__name__).warning(
+                "official resource execution Profile bootstrap skipped: %s", error
+            )
+        else:
+            if resource_result in {"installed", "already_enabled"}:
+                logging.getLogger(__name__).info(
+                    "official resource execution Profile bootstrap: %s", resource_result
+                )
+
+    async def _provider_snapshot(
+        self, *, refresh: bool
+    ) -> tuple[dict[str, PluginManifest], dict[str, Any], tuple[str, ...] | None]:
+        manifests = dict(self._startup_provider_manifests)
+        factories = dict(self._startup_provider_factories)
+        manager = self._dsh_provider_registration_manager
+        if manager is None:
+            return manifests, factories, None
+        try:
+            registrations = await (manager.refresh() if refresh else manager.start())
+        except StudioDshProviderRegistrationError as error:
+            logging.getLogger(__name__).warning(
+                "DSH AgentProvider discovery failed closed: %s", error.code
+            )
+            return manifests, factories, None
+        if registrations.manifests.keys() != registrations.factories.keys():
+            logging.getLogger(__name__).warning(
+                "DSH AgentProvider discovery returned a partial registration set"
+            )
+            return manifests, factories, None
+        for provider_ref, manifest in registrations.manifests.items():
+            if provider_ref in manifests and (
+                manifests[provider_ref] != manifest
+                or factories[provider_ref] is not registrations.factories[provider_ref]
+            ):
+                logging.getLogger(__name__).warning(
+                    "DSH AgentProvider registration conflicts with startup provider: %s",
+                    provider_ref,
+                )
+                return (
+                    dict(self._startup_provider_manifests),
+                    dict(self._startup_provider_factories),
+                    None,
+                )
+            manifests[provider_ref] = manifest
+            factories[provider_ref] = registrations.factories[provider_ref]
+        return manifests, factories, tuple(registrations.manifests)
+
+    def agent_provider_catalog(self) -> list[dict[str, Any]]:
+        """Return only external providers that reached Studio's bound selector."""
+
+        reserved = {
+            KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
+        }
+        package_by_ref: dict[str, str] = {}
+        display_name_by_ref: dict[str, str] = {}
+        manager = self._dsh_provider_registration_manager
+        if manager is not None:
+            package_by_ref = {
+                item.provider_ref: item.package_name
+                for item in manager.inventory.packages
+                if item.state == "bound" and item.provider_ref is not None
+            }
+            display_name_by_ref = {
+                item.provider_ref: item.display_name
+                for item in manager.inventory.packages
+                if item.state == "bound" and item.provider_ref is not None and item.display_name
+            }
+        items = []
+        for provider_ref, manifest in sorted(self._active_provider_manifests.items()):
+            if manifest.metadata.id in reserved:
+                continue
+            items.append(
+                {
+                    "providerRef": provider_ref,
+                    "pluginId": package_by_ref.get(provider_ref, manifest.metadata.id),
+                    "resolvedVersion": manifest.metadata.version,
+                    "displayName": display_name_by_ref.get(provider_ref, manifest.metadata.id),
+                    "state": "enabled",
+                    "compatible": True,
+                    "selectable": True,
+                    "reason": None,
+                    "permissions": list(manifest.spec.permissions),
+                    "isolation": manifest.spec.isolation,
+                    "configSchemaDeclared": manifest.spec.config_schema is not None,
+                    "secretFields": list(manifest.spec.secret_fields),
+                }
+            )
+        return items
+
+    def dsh_provider_runtime_state(self, package_name: str) -> dict[str, Any] | None:
+        """Project one manager-owned package lifecycle state for plugin APIs."""
+
+        manager = self._dsh_provider_registration_manager
+        if manager is None:
+            return None
+        status = next(
+            (item for item in manager.inventory.packages if item.package_name == package_name),
+            None,
+        )
+        if status is None:
+            return None
+        return {
+            "state": status.state,
+            "providerRef": status.provider_ref,
+            "errorCode": status.error_code,
+        }
+
     def runtime_catalog(self) -> list[dict]:
         return inspect_runtime_catalog(self.runtime_executor)
 
+    def _scheduler_adapter_provider(self, spec: StudioRunSpec):  # type: ignore[no-untyped-def]
+        if spec.plugin_bundle_root is not None:
+            return self.plugin_runs.kernel_adapter_provider(spec)
+        return lambda: self.runtime_executor.create_adapter(spec.launch_context)
+
+    def resolve_run_spec(
+        self,
+        build_id: str,
+        *,
+        model: str | None = None,
+        sandbox: str | None = None,
+        approval_mode: str | None = None,
+    ) -> StudioRunSpec:
+        """Resolve one immutable Build through its only compatible resolver."""
+
+        try:
+            self.codex_builds.get(build_id)
+        except Exception as exc:
+            if getattr(exc, "status_code", None) != 404:
+                raise
+        else:
+            # The record exists in the Codex repository. Any later resolution
+            # error belongs to that Build and must remain actionable; a nested
+            # 404 (for example a missing plugin snapshot) is not evidence that
+            # this is a framework Build.
+            return self.codex_runs.resolve(
+                build_id,
+                model=model,
+                sandbox=sandbox,
+                approval_mode=approval_mode,
+            )
+        framework_build = self.builds.get(build_id)
+        runtime_type = framework_build.runtime_type.strip().lower()
+        if runtime_type in {"harness", "plugin"}:
+            return self.plugin_runs.resolve(
+                build_id,
+                model=model,
+                approval_mode=approval_mode,
+            )
+        return self.framework_runs.resolve(
+            build_id,
+            model=model,
+            approval_mode=approval_mode,
+        )
+
+    def validate_schedule_build(
+        self,
+        build_ref: str | None,
+        *,
+        agent_id: str | None = None,
+    ) -> None:
+        """Reject a ScheduledTask target build that is not a real immutable Build.
+
+        The agent-scoped authoring path resolves the Build server-side via
+        :meth:`ensure_current_build`, so this guard is primarily for the raw
+        ``/api/v1/schedules`` surface that accepts a caller-supplied
+        ``agent_version_ref``.  A version name or tag (for example "v1") is
+        not an immutable Build id and must fail at admission with an actionable
+        error instead of collapsing into a later opaque DISPATCH_FAILED.
+        """
+        ref = (build_ref or "").strip()
+        if not ref:
+            raise StudioError(
+                "SCHEDULE_BUILD_REQUIRED",
+                "定时任务必须绑定一个已成功构建的 Build id（不能为空或使用版本名）",
+                status_code=422,
+                field="target.agentVersionRef",
+            )
+        try:
+            spec = self.resolve_run_spec(ref)
+        except StudioError as error:
+            if error.status_code == 404:
+                raise StudioError(
+                    "SCHEDULE_BUILD_UNAVAILABLE",
+                    f"定时任务绑定的 Build {ref!r} 不可用：请使用已成功构建的 Build id，而非版本名",
+                    status_code=422,
+                    field="target.agentVersionRef",
+                    details={"buildId": ref},
+                ) from error
+            raise
+        except Exception as error:
+            raise StudioError(
+                "SCHEDULE_BUILD_UNAVAILABLE",
+                f"定时任务绑定的 Build {ref!r} 不可用：{error}",
+                status_code=422,
+                field="target.agentVersionRef",
+                details={"buildId": ref},
+            ) from error
+        if agent_id and spec.agent_id != agent_id:
+            raise StudioError(
+                "SCHEDULE_AGENT_MISMATCH",
+                "定时任务绑定的 Build 与所选 Agent 不一致",
+                status_code=422,
+                field="target.agentVersionRef",
+                details={"buildId": ref, "agentId": agent_id},
+            )
+
+    def conversation_surface(
+        self,
+        build_id: str,
+        *,
+        session_id: str,
+    ) -> ConversationSurface:
+        """Describe the actual local composer contract for one Build/session.
+
+        This is intentionally conservative. It derives the declaration from
+        the resolved Build, rather than guessing support from a model name or
+        sending provider-specific fields to every Runtime.
+        """
+
+        spec = self.resolve_run_spec(build_id)
+        runtime_type = spec.launch_context.runtime_type.strip().lower()
+        runtime_mode: Literal["native", "translated"] = (
+            "native" if runtime_type == "codex" else "translated"
+        )
+        inputs = [ConversationCapability(name="text", mode="native")]
+        if spec.model:
+            inputs.append(ConversationCapability(name="model.select", mode=runtime_mode))
+        inputs.append(ConversationCapability(name="approval", mode=runtime_mode))
+        if runtime_type == "codex":
+            inputs.extend(
+                (
+                    # Studio projects image data URLs to native Codex ImageInput.
+                    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.
+                    ConversationCapability(name="attachment.file", mode="translated"),
+                    ConversationCapability(name="reasoning.effort", mode="native"),
+                    ConversationCapability(name="goal", mode="native"),
+                    ConversationCapability(name="plan", mode="native"),
+                )
+            )
+
+        outputs = [
+            ConversationCapability(name="text", mode="native"),
+            ConversationCapability(name="streaming", mode=runtime_mode),
+        ]
+        if runtime_type == "codex":
+            outputs.extend(
+                (
+                    ConversationCapability(name="reasoning", mode="native"),
+                    ConversationCapability(name="tool.inspect", mode="native"),
+                    ConversationCapability(name="approval", mode="native"),
+                    ConversationCapability(name="goal", mode="native"),
+                    ConversationCapability(name="plan", mode="native"),
+                    ConversationCapability(name="cancel", mode="native"),
+                )
+            )
+        return ConversationSurface(
+            surface_id=f"studio.build.{spec.build_id}",
+            session_id=session_id,
+            provider_ref=f"studio.runtime.{runtime_type}",
+            inputs=tuple(inputs),
+            outputs=tuple(outputs),
+        )
+
+    async def ensure_current_build(self, agent_id: str):
+        """Return the Build that is eligible for a local Studio turn.
+
+        This is deliberately one shared resolver for Web chat and Scheduler
+        authoring.  A Scheduler must never select a mutable Draft or a stale
+        Codex manifest merely because a UI happened to show it as an Agent.
+        """
+
+        await self.start()
+        if self.is_codex_agent(agent_id):
+            self.codex_agent_detail(agent_id)
+            builds = [
+                record
+                for record in self.codex_builds.list()
+                if record.agent_name == agent_id and self.codex_builder.is_current(record)
+            ]
+            if builds:
+                return builds[0]
+            return await asyncio.to_thread(self.codex_builder.build, agent_id)
+        draft = self.drafts.get(agent_id)
+        composition_required = self.plugin_compositions.required_for(draft)
+        resources_required = resource_build_required(draft)
+        for record in self.builds.list_for_agent(agent_id):
+            if record.status == BuildStatus.SUCCEEDED:
+                if (composition_required or resources_required) and (
+                    record.source_revision != draft.metadata.revision
+                    or (composition_required and not self._build_has_composition(record))
+                    or (resources_required and not self._build_has_resources(record))
+                ):
+                    continue
+                if composition_required:
+                    composition = self.plugin_compositions.compile_if_required(draft)
+                    if composition is None:  # pragma: no cover - guarded by required_for
+                        raise StudioError(
+                            "PLUGIN_COMPOSITION_REQUIRED",
+                            "当前 Agent 需要插件组合，但无法生成 Composition",
+                            status_code=409,
+                        )
+                    self.plugin_compositions.bind_build(
+                        composition,
+                        agent_id=draft.metadata.id,
+                        build_id=record.id,
+                    )
+                return record
+        if draft.spec.model is None and not draft.spec.bindings.model_profile_id:
+            raise StudioError(
+                "AGENT_MODEL_REQUIRED",
+                "当前 Agent 未绑定 Model Profile，请先在 Agent 配置中选择模型；"
+                "API Key 只提供访问凭证，不会自动绑定模型。",
+                status_code=422,
+                field="spec.bindings.modelProfileId",
+            )
+        return await asyncio.to_thread(self._build_agent_bundle, draft)
+
+    def _build_agent_bundle(self, draft: AgentDraft):
+        composition = self.plugin_compositions.compile_if_required(draft)
+        resource_build = None
+        if resource_build_required(draft):
+            dsh_profile = self.resource_dsh_capabilities.capture_resource_build_snapshot()
+            resource_build = admit_resource_build(
+                draft,
+                authority=self.resource_authority,
+                connections=self.resource_connections,
+                dsh_profile=dsh_profile,
+            )
+        try:
+            record = self.builder.build(
+                draft,
+                composition=composition,
+                resource_build=resource_build,
+            )
+        except BundleSecurityError as error:
+            first = error.findings[0]
+            reason = {
+                "literal-secret-field": "明文凭证",
+                "url-credentials": "含账号信息的 URL",
+                "local-home-path": "本机用户目录路径",
+                "invalid-structured-input": "无法解析的结构化数据",
+            }.get(first.kind, "敏感内容")
+            raise StudioError(
+                "BUNDLE_SECURITY_REJECTED",
+                f"AgentBundle 安全检查未通过：{first.path} 检测到{reason}",
+                status_code=422,
+                details={
+                    "securityFindings": [
+                        {
+                            "path": finding.path,
+                            "kind": finding.kind,
+                            "field": finding.field,
+                        }
+                        for finding in error.findings
+                    ]
+                },
+            ) from error
+        if composition is not None:
+            self.plugin_compositions.bind_build(
+                composition,
+                agent_id=draft.metadata.id,
+                build_id=record.id,
+            )
+        return record
+
+    def _build_has_composition(self, record: Any) -> bool:
+        """Reject stale pre-Phase-2 builds for a composed runtime.
+
+        This check is intentionally scoped to Harness/plugin runtimes. Legacy
+        ADK/LangGraph build selection retains its existing behavior.
+        """
+
+        if not record.artifact_path:
+            return False
+        try:
+            archive = self.workspace.resolve(record.artifact_path, must_exist=True)
+            with zipfile.ZipFile(archive) as bundle:
+                manifest = json.loads(bundle.read("manifest.json"))
+                names = frozenset(bundle.namelist())
+            return bool(
+                isinstance(manifest, dict)
+                and manifest.get("compositionProfileDigest")
+                and "composition-profile.json" in names
+                and "plugin-lock.json" in names
+            )
+        except (KeyError, OSError, UnicodeError, ValueError, zipfile.BadZipFile):
+            return False
+
+    def _build_has_resources(self, record: Any) -> bool:
+        if (
+            not record.artifact_path
+            or not record.resource_build_digest
+            or not record.resource_snapshot_digest
+        ):
+            return False
+        try:
+            archive = self.workspace.resolve(record.artifact_path, must_exist=True)
+            with zipfile.ZipFile(archive) as bundle:
+                manifest = BundleManifest.model_validate_json(bundle.read("manifest.json"))
+                names = frozenset(bundle.namelist())
+            return bool(
+                manifest.resource_build_digest == record.resource_build_digest
+                and manifest.resource_snapshot_digest == record.resource_snapshot_digest
+                and "platform-resources/resource-build.json" in names
+            )
+        except (KeyError, OSError, UnicodeError, ValueError, zipfile.BadZipFile):
+            return False
+
+    async def create_agent_schedule(
+        self,
+        agent_id: str,
+        *,
+        display_name: str,
+        prompt: str,
+        schedule: ScheduleSpec,
+        enabled: bool = True,
+        continuity: Literal["new_session", "continue_session"] = "new_session",
+        session_id: str | None = None,
+    ) -> ScheduledTask:
+        """Create a local-only schedule for the Kernel Runtime that owns it.
+
+        The browser provides only human intent (prompt/calendar/continuity).
+        The trusted Studio process resolves the immutable Build and concrete
+        Kernel instance.  Thus a task cannot be pointed at another Agent
+        Instance, smuggle a permit reference, or claim cloud scheduling.
+        """
+
+        await self.start()
+        build = await self.ensure_current_build(agent_id)
+        spec = self.resolve_run_spec(build.id)
+        await self.scheduler_runtimes.start()
+        try:
+            target = await self.scheduler_runtimes.ensure_build(
+                build.id,
+                expected_agent_id=agent_id,
+            )
+            runtime = self.scheduler_runtimes.runtime_for_build(build.id)
+        except StudioSchedulerRuntimeError as error:
+            raise StudioError(
+                error.code,
+                str(error),
+                status_code=409,
+                details={"agentId": agent_id, "buildId": build.id},
+            ) from error
+        if continuity == "continue_session" and not session_id:
+            raise StudioError(
+                "SCHEDULE_SESSION_REQUIRED",
+                "继续会话的定时任务必须选择一个已有会话。",
+                status_code=422,
+                field="sessionId",
+            )
+        if continuity == "continue_session":
+            await self._require_schedule_session_owner(agent_id, session_id)
+            self._require_schedule_continuation(runtime, spec.launch_context.runtime_type)
+        task = ScheduledTask(
+            task_id=f"sched-{uuid4().hex[:20]}",
+            display_name=display_name,
+            target=ScheduledTaskTarget(
+                agent_id=agent_id,
+                tenant_id=target.tenant_id,
+                agent_instance_id=target.agent_instance_id,
+                agent_version_ref=str(build.id),
+                session_id=session_id,
+                # This is an opaque local authority marker, never a browser
+                # supplied credential. The dispatcher obtains a short-lived
+                # in-process permit at the AgentControl ingress boundary.
+                authorization_ref="runtime://local-kernel-ingress",
+            ),
+            schedule=schedule,
+            command=ScheduleCommandTemplate(payload={"content": prompt}),
+            enabled=enabled,
+            continuity=continuity,
+        )
+        return self.scheduler.create_task(task)
+
+    async def _require_schedule_session_owner(self, agent_id: str, session_id: str | None) -> None:
+        session = (
+            await self.session_service.get_session_metadata(session_id) if session_id else None
+        )
+        if session is None or session.agent_id != agent_id:
+            raise StudioError(
+                "SCHEDULE_SESSION_INVALID",
+                "请选择该智能体已有的会话。",
+                status_code=422,
+                field="sessionId",
+            )
+
+    async def validate_schedule_session(
+        self, agent_id: str, continuity: str, session_id: str | None, build_id: str | None
+    ) -> None:
+        if continuity != "continue_session":
+            return
+        await self._require_schedule_session_owner(agent_id, session_id)
+        await self.scheduler_runtimes.ensure_build(build_id, expected_agent_id=agent_id)
+        runtime = self.scheduler_runtimes.runtime_for_build(build_id)
+        spec = self.resolve_run_spec(build_id)
+        self._require_schedule_continuation(runtime, spec.launch_context.runtime_type)
+
+    @staticmethod
+    def _require_schedule_continuation(runtime: Any, runtime_type: str) -> None:
+        """Fail closed unless the bound Provider can preserve one conversation.
+
+        Harness owns process-local Session history without exposing the generic
+        checkpoint ``resume`` verb. Codex and external adapters must declare
+        the typed resume capability. An older Runtime that lacks either proof
+        remains usable for normal conversations and ``new_session`` schedules;
+        only the optional follow-up mode is rejected.
+        """
+
+        if runtime_type.strip().lower() == "harness":
+            return
+        kernel = getattr(runtime, "kernel", None)
+        describe = getattr(kernel, "capabilities", None)
+        matrix = describe() if callable(describe) else None
+        resume = getattr(matrix, "resume", None)
+        if not bool(getattr(resume, "supported", False)):
+            raise StudioError(
+                "SCHEDULE_CONTINUATION_UNAVAILABLE",
+                "当前 Runtime 未声明可恢复的会话续接能力；可改用新会话定时任务。",
+                status_code=409,
+                field="continuity",
+                details={"runtimeType": runtime_type},
+            )
+
+    def list_agent_schedules(self, agent_id: str) -> list[ScheduledTask]:
+        return [task for task in self.scheduler.list_tasks() if task.target.agent_id == agent_id]
+
+    def get_agent_schedule(self, agent_id: str, task_id: str) -> ScheduledTask:
+        task = self.scheduler.get_task(task_id)
+        if task.target.agent_id != agent_id:
+            from ksadk.studio.errors import not_found
+
+            raise not_found("schedule", task_id)
+        return task
+
+    def update_agent_schedule(
+        self,
+        agent_id: str,
+        task_id: str,
+        *,
+        display_name: str,
+        prompt: str,
+        schedule: ScheduleSpec,
+        enabled: bool,
+        continuity: Literal["new_session", "continue_session"],
+        session_id: str | None,
+    ) -> ScheduledTask:
+        existing = self.get_agent_schedule(agent_id, task_id)
+        if continuity == "continue_session" and not session_id:
+            raise StudioError(
+                "SCHEDULE_SESSION_REQUIRED",
+                "继续会话的定时任务必须选择一个已有会话。",
+                status_code=422,
+                field="sessionId",
+            )
+        task = existing.model_copy(
+            update={
+                "display_name": display_name,
+                "schedule": schedule,
+                "command": ScheduleCommandTemplate(payload={"content": prompt}),
+                "enabled": enabled,
+                "continuity": continuity,
+                "target": existing.target.model_copy(update={"session_id": session_id}),
+            }
+        )
+        return self.scheduler.update_task(task_id, task)
+
+    async def run_agent_schedule_now(self, agent_id: str, task_id: str):
+        self.get_agent_schedule(agent_id, task_id)
+        return await self.scheduler.run_now(task_id)
+
     def codex_manifest_state(self, agent_id: str | None = None) -> dict:
         return self.codex_agents.manifest_state(agent_id)
 
@@ -306,7 +1218,8 @@ class StudioService:
         from ksadk.studio.errors import not_found
 
         runs = self.event_store.list_runs(session_id=session_id)
-        if not runs:
+        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(
@@ -315,9 +1228,54 @@ class StudioService:
                 status_code=409,
                 details={"sessionId": session_id},
             )
+        await self.plugin_runs.close_session(session_id)
         await self.session_service.delete_session(session_id)
         self.event_store.delete_session(session_id)
 
+    async def aclose(self) -> None:
+        """Release local provider activations and supervised plugin processes."""
+
+        async with self._start_lock:
+            if self._closed:
+                return
+            self._closed = True
+            cleanup = asyncio.create_task(self._close_owned_plugin_services())
+            interrupted = False
+            while not cleanup.done():
+                try:
+                    await asyncio.shield(cleanup)
+                except asyncio.CancelledError:
+                    interrupted = True
+            cleanup.result()
+            if interrupted:
+                raise asyncio.CancelledError
+
+    async def _close_owned_plugin_services(self) -> None:
+        first_error: BaseException | None = None
+        owned = [self.plugin_runs.aclose, self.dsh_capabilities.aclose]
+        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:
+            owned.append(self._dsh_provider_registration_manager.aclose)
+        if self._resource_dsh_provider_registration_manager is not None:
+            owned.append(self._resource_dsh_provider_registration_manager.aclose)
+        for close in owned:
+            try:
+                await close()
+            except BaseException as error:  # cleanup must continue
+                if first_error is None:
+                    first_error = error
+        if first_error is not None:
+            raise first_error
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise StudioError(
+                "STUDIO_SERVICE_CLOSED",
+                "Studio service 已关闭",
+                status_code=503,
+            )
+
     async def _require_runtime_session(self, session_id: str) -> None:
         if await self.session_service.get_session_metadata(session_id) is None:
             raise StudioError(
@@ -842,12 +1800,36 @@ class StudioService:
 
     def agent_detail(self, agent_id: str) -> dict:
         if self.is_codex_agent(agent_id):
-            return self.codex_agent_detail(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),
+        }
+
+    @staticmethod
+    def _soul_projection(draft: AgentDraft) -> dict[str, object]:
+        """Describe the reviewed Soul source without claiming runtime learning."""
+
+        soul = draft.spec.soul
+        runtime_type = draft.spec.runtime.type if draft.spec.runtime is not None else ""
+        compile_target = {
+            "codex": "managed-runtime.base_instructions",
+            "plugin": "instructions/soul.md",
+        }.get(runtime_type, "resolved-agent-spec.instructions.system")
+        return {
+            "present": soul is not None,
+            "source": "AgentSpec.soul",
+            "sourceRevision": draft.metadata.revision,
+            "schemaVersion": soul.schema_version if soul is not None else "agentkit.soul/v1",
+            "digest": soul_digest(soul) if soul is not None else None,
+            "digestAlgorithm": "sha256-canonical-json",
+            "compileTarget": compile_target,
+            "compileOrder": "before-instructions.system",
         }
 
     def create_studio_agent(
@@ -993,6 +1975,83 @@ class StudioService:
             return detail["validation"]
         return self.validator.validate(draft, level=level)
 
+    async def resource_binding_status(self, agent_id: str, *, activation_id: str) -> dict:
+        # 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,
+        )
+        if status is None:
+            raise StudioError(
+                "RESOURCE_ACTIVATION_NOT_FOUND", "未找到此 Agent 的资源运行实例",
+                status_code=404,
+            )
+        return status
+
+    def validate_resource_bindings(self, agent_id: str, *, expected_revision: int) -> dict:
+        from ksadk.resource_runtime.plugin_config import resource_plugin_config
+        from ksadk.studio.resource_binding_validation import resource_binding_diagnostics
+
+        draft = self.agent_detail(agent_id)["draft"]
+        if draft.metadata.revision != expected_revision:
+            raise StudioError(
+                "AGENT_REVISION_CONFLICT", "资源校验版本与当前 Agent 不一致", status_code=409,
+            )
+        diagnostics = resource_binding_diagnostics(
+            draft.spec.bindings.plugins, draft.spec.memory, self.resource_connections,
+        )
+        configs = [
+            (index, config)
+            for index, binding in enumerate(draft.spec.bindings.plugins)
+            if binding.enabled
+            for config in [
+                resource_plugin_config(
+                    binding.plugin_ref,
+                    binding.ecosystem,
+                    binding.config,
+                    enabled=True,
+                )
+            ]
+            if config is not None
+        ]
+        verified = []
+        if (
+            self.resource_authority is not None
+            and configs
+            and not any(item.severity == DiagnosticSeverity.ERROR for item in diagnostics)
+        ):
+            for index, config in configs:
+                try:
+                    verified.append(self.resource_authority.admit(config))
+                except StudioError as error:
+                    diagnostics.append(
+                        Diagnostic(
+                            severity=DiagnosticSeverity.ERROR,
+                            code=error.code,
+                            message=error.message,
+                            field=error.field
+                            or f"spec.bindings.plugins[{index}].config.binding",
+                        )
+                    )
+            current = self.agent_detail(agent_id)["draft"]
+            if current.metadata.revision != draft.metadata.revision:
+                raise StudioError(
+                    "AGENT_REVISION_CONFLICT",
+                    "资源校验期间 Agent 已变更，请刷新后重试",
+                    status_code=409,
+                )
+        authorization_verified = bool(configs) and len(verified) == len(configs)
+        if authorization_verified:
+            diagnostics = [
+                item for item in diagnostics if item.code != "RESOURCE_AUTHORITY_UNVERIFIED"
+            ]
+        return {
+            "revision": draft.metadata.revision,
+            "valid": not any(item.severity == "error" for item in diagnostics),
+            "authorizationVerified": authorization_verified,
+            "diagnostics": [item.model_dump(by_alias=True, mode="json") for item in diagnostics],
+        }
+
     def submit_studio_build(
         self,
         agent_id: str,
@@ -1000,32 +2059,11 @@ class StudioService:
         revision: int,
         idempotency_key: str,
     ) -> Operation:
-        runtime_type = self.agent_runtime_type(agent_id)
-        runtime = next(
-            (item for item in self.runtime_catalog() if item["runtimeType"] == runtime_type),
-            None,
-        )
-        if runtime is None:
-            from ksadk.studio.errors import StudioError
-
-            raise StudioError(
-                "RUNTIME_NOT_REGISTERED",
-                "Agent 引用的 RuntimeAdapter 未注册",
-                status_code=422,
-                details={"runtimeType": runtime_type},
-            )
-        if runtime["status"] != "ready":
-            from ksadk.studio.errors import StudioError
-
-            raise StudioError(
-                "RUNTIME_DEPENDENCY_MISSING",
-                f"{runtime['displayName']} Runtime 依赖未安装",
-                status_code=422,
-                details={
-                    "runtimeType": runtime_type,
-                    "installCommand": runtime["installCommand"],
-                },
-            )
+        # Codex build admission already runs the injected runtime inspector and
+        # pins its result into the immutable build.  Checking package metadata
+        # first would reject an explicitly supplied RuntimeExecutor/inspector
+        # (including an out-of-process Codex runtime) merely because the local
+        # Studio interpreter does not have the optional wheel installed.
         if self.is_codex_agent(agent_id):
             detail = self.agent_detail(agent_id)
             if revision != detail["draft"].metadata.revision:
@@ -1040,6 +2078,12 @@ class StudioService:
                 idempotency_key=idempotency_key,
                 agent_id=agent_id,
             )
+
+        # A framework Build compiles and seals source/configuration only.  Its
+        # optional Runtime dependency belongs to run preflight, and may live in
+        # a different process or deployment image.  Rejecting the Build from
+        # this Studio interpreter's package metadata would make portable
+        # bundles impossible and incorrectly couple authoring to execution.
         return self.submit_build(
             agent_id,
             revision=revision,
@@ -1271,8 +2315,7 @@ class StudioService:
             resolved.model_profile_ids = [
                 resource_id
                 for resource_id in resolved.model_profile_ids
-                if resource_id in known
-                or resource_id not in current.model_profile_ids
+                if resource_id in known or resource_id not in current.model_profile_ids
             ]
         resolved.skills = selected_for_materialization(
             candidate.skills,
@@ -1356,7 +2399,7 @@ class StudioService:
         snapshot = draft.model_copy(deep=True)
 
         async def runner(_operation_id: str):
-            return await asyncio.to_thread(self.builder.build, snapshot)
+            return await asyncio.to_thread(self._build_agent_bundle, snapshot)
 
         return self.operations.submit(
             kind=OperationKind.BUILD,
@@ -1420,21 +2463,13 @@ class StudioService:
     ):
         """Execute any immutable Studio Build through the canonical executor."""
 
-        try:
-            spec = self.codex_runs.resolve(
-                build_id,
-                model=model,
-                sandbox=sandbox,
-                approval_mode=approval_mode,
-            )
-        except Exception as exc:
-            if getattr(exc, "status_code", None) != 404:
-                raise
-            spec = self.framework_runs.resolve(
-                build_id,
-                model=model,
-                approval_mode=approval_mode,
-            )
+        await self.start()
+        spec = self.resolve_run_spec(
+            build_id,
+            model=model,
+            sandbox=sandbox,
+            approval_mode=approval_mode,
+        )
         if collaboration_mode or goal_objective or reasoning_effort:
             from dataclasses import replace
 
@@ -1660,12 +2695,14 @@ class StudioService:
                 evalset = load_evalset(path)
             except (EvalSetParseError, OSError):
                 continue
-            evalsets.append({
-                "path": path.relative_to(self.workspace.root).as_posix(),
-                "name": evalset.name,
-                "caseCount": len(evalset.cases),
-                "contentDigest": evalset.content_digest,
-            })
+            evalsets.append(
+                {
+                    "path": path.relative_to(self.workspace.root).as_posix(),
+                    "name": evalset.name,
+                    "caseCount": len(evalset.cases),
+                    "contentDigest": evalset.content_digest,
+                }
+            )
         evalsets.sort(key=lambda item: item["path"])
         return {"builds": builds, "evalsets": evalsets}
 
@@ -1840,9 +2877,7 @@ class StudioService:
             # this outbound control-plane request only, never in the Build or
             # deployment receipt.
             launch = self.codex_runs.resolve(build_id)
-            runtime_environment = dict(
-                (launch.launch_context.config or {}).get("env") or {}
-            )
+            runtime_environment = dict((launch.launch_context.config or {}).get("env") or {})
             # Retrying a YAML deployment must update the Agent that the prior
             # receipt already created.  CreateAgent can have succeeded before
             # a downstream Runtime-Service start failed; creating again would
@@ -1894,6 +2929,12 @@ class StudioService:
                 runner=managed_runtime_runner,
             )
 
+        # Do not turn a stale URL or a deleted Agent's Build into an accepted
+        # operation that can only fail later in the worker.  The Codex lookup
+        # above intentionally falls back to framework builds, so establish
+        # that the fallback record exists before returning HTTP 202.
+        self.builds.get(build_id)
+
         async def runner(_operation_id: str):
             return await self.cloud.deploy(build_id, request)
 
@@ -2026,14 +3067,10 @@ class StudioService:
 
         workspace_identity = str(self.workspace.root.resolve())
         region = (
-            os.environ.get("AGENTENGINE_REGION")
-            or os.environ.get("KSYUN_REGION")
-            or "cn-beijing-6"
+            os.environ.get("AGENTENGINE_REGION") or os.environ.get("KSYUN_REGION") or "cn-beijing-6"
         ).strip()
         access_key = (
-            os.environ.get("KSYUN_ACCESS_KEY")
-            or os.environ.get("KS3_ACCESS_KEY")
-            or "unsigned"
+            os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY") or "unsigned"
         ).strip()
 
         def opaque(value: str) -> str:
@@ -2053,36 +3090,26 @@ class StudioService:
             except Exception:
                 data = {}
         defaults = {
-            "sandbox": os.environ.get("KSADK_CODEX_SANDBOX", "read_only"),
+            "sandbox": os.environ.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")
             ),
             "cloudBucket": os.environ.get("KS3_BUCKET", ""),
-            "cloudAccountId": (
-                os.environ.get("KSYUN_ACCOUNT_ID", "").strip()
-            ),
+            "cloudAccountId": (os.environ.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()
+                (os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY", "")).strip()
                 and (
-                    os.environ.get("KSYUN_SECRET_KEY")
-                    or os.environ.get("KS3_SECRET_KEY", "")
+                    os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY", "")
                 ).strip()
             ),
             "cloudSignedAccountConfigured": bool(
-                (
-                    os.environ.get("KSYUN_ACCESS_KEY")
-                    or os.environ.get("KS3_ACCESS_KEY", "")
-                ).strip()
+                (os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY", "")).strip()
                 and (
-                    os.environ.get("KSYUN_SECRET_KEY")
-                    or os.environ.get("KS3_SECRET_KEY", "")
+                    os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY", "")
                 ).strip()
             ),
             "traceContent": os.environ.get("KSADK_STUDIO_TRACE_CONTENT", "1") != "0",
@@ -2191,26 +3218,34 @@ class StudioService:
         secret_key = (
             os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY", "")
         ).strip()
-        region = os.environ.get(
+        configured_region = os.environ.get(
             "AGENTENGINE_REGION", os.environ.get("KSYUN_REGION", "")
         ).strip()
-        if not all((access_key, secret_key, region)):
+        environment_region = os.environ.get("KSYUN_REGION", "").strip()
+        logical_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(
-            region=region,
+            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()
-        if not stream_base_url and region.lower() == "pre-online":
+        if not stream_base_url and is_preonline:
             # The pre-online KOP response path currently buffers SSE until
-            # EOF.  Its internal Server ingress validates the same V4
-            # signature and preserves the RunAgent streaming response.
+            # EOF, and KOP may not yet publish newly deployed native Action
+            # names.  Its internal Server ingress validates the same V4
+            # signature for RunAgent, ManagedRuntime, and plugin delivery.
             stream_base_url = "http://agent-api-pre.kspmas-internal.ksyun.com"
         stream_client = (
             AgentEngineClient(
                 base_url=stream_base_url,
-                region=region,
+                region=logical_region,
                 access_key=access_key,
                 secret_key=secret_key,
             )
@@ -2218,9 +3253,10 @@ class StudioService:
             else control_client
         )
         return DirectAgentEngineCloudDeploymentGateway(
-            region=region,
+            region=logical_region,
             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,
             ks3_credentials={
                 "access_key": access_key,