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

ksadk/studio/plugin_runtime_admission.py

@@ -0,0 +1,57 @@
+"""Admission fencing for Studio plugin-runtime maintenance windows."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from ksadk.plugins.host import PluginHostError
+
+_T = TypeVar("_T")
+
+
+class RuntimeAdmissionGate:
+    """Wait through bounded profile refreshes without admitting stale hosts."""
+
+    def __init__(self) -> None:
+        self._open = True
+        self._ready = asyncio.Event()
+        self._ready.set()
+
+    @property
+    def is_open(self) -> bool:
+        return self._open
+
+    def suspend(self) -> None:
+        self._open = False
+        self._ready.clear()
+
+    def resume(self) -> None:
+        self._open = True
+        self._ready.set()
+
+    def close(self) -> None:
+        self._open = False
+        self._ready.set()
+
+    async def wait(self) -> None:
+        try:
+            await asyncio.wait_for(self._ready.wait(), timeout=60)
+        except TimeoutError as exc:
+            raise PluginHostError(
+                "plugin_runtime_reconfiguring",
+                "Studio plugin runtime is still reconfiguring after 60 seconds",
+            ) from exc
+
+    async def resolve(self, factory: Callable[[], Awaitable[_T]]) -> _T:
+        deadline = asyncio.get_running_loop().time() + 60
+        while True:
+            try:
+                return await factory()
+            except PluginHostError as exc:
+                if exc.code != "plugin_runtime_reconfiguring" or (
+                    asyncio.get_running_loop().time() >= deadline
+                ):
+                    raise
+                await asyncio.sleep(0)

ksadk/studio/presentation.py

@@ -0,0 +1,92 @@
+"""Shared live/replay conversation projection for a persisted Studio Run."""
+
+from ksadk.conversations.contracts import ConversationItem
+from ksadk.conversations.runtime_projection import (
+    RuntimeConversationProjection,
+    conversation_identity,
+)
+from ksadk.events.canonical import parse_runtime_event
+from ksadk.events.content import DataContent
+
+
+class StudioConversationProjection:
+    def __init__(self, session_id, profile):
+        self.session_id = session_id
+        self.profile = profile
+        self.projection = None
+        self.prefix = []
+
+    def apply(self, event):
+        if event.type == "run.created":
+            self.session_id = event.data.get("sessionId") or self.session_id
+            return event.model_copy(
+                update={"data": {**event.data, "presentationProfile": self.profile}}
+            )
+        raw = event.data.get("runtimeEvent")
+        if not isinstance(raw, dict) or raw.get("schema_version") != 2:
+            item = event.data.get("conversationItem")
+            if self.projection is not None and isinstance(item, dict):
+                scoped = self.projection.scope_ledger_item(ConversationItem.model_validate(item))
+                scoped = scoped.model_copy(update={"run_id": event.run_id})
+                return event.model_copy(
+                    update={
+                        "data": {
+                            **event.data,
+                            "conversationItem": scoped.model_dump(
+                                mode="json", by_alias=True, exclude_none=True
+                            ),
+                        }
+                    }
+                )
+            return event
+        canonical = parse_runtime_event(raw)
+        snapshot = getattr(canonical, "snapshot", None) or getattr(canonical, "initial", None)
+        parts = snapshot.parts if snapshot else (getattr(canonical, "update", None),)
+        managed = any(
+            isinstance(part, DataContent)
+            and isinstance(part.data, dict)
+            and part.data.get("schema") == "execution.scope/v1"
+            for part in parts
+        )
+        if self.projection is None and not managed:
+            # Legacy providers may emit terminal-only snapshots or multiple
+            # resume lifecycles. Preserve that contract until a managed scope
+            # opts into the stricter canonical presentation lane.
+            self.prefix.append(canonical)
+            if self.profile == "agent-block-v1" and isinstance(
+                event.data.get("conversationItem"), dict
+            ):
+                item = dict(event.data["conversationItem"])
+                item["itemId"] = conversation_identity(
+                    canonical.run_id, canonical.scope_id, item["itemId"]
+                )
+                item["nativeRef"] = {**item.get("nativeRef", {}), "scopeId": canonical.scope_id}
+                return event.model_copy(update={"data": {**event.data, "conversationItem": item}})
+            return event
+        if self.projection is None:
+            if not self.session_id:
+                raise ValueError("presentation requires a persisted session identity")
+            self.projection = RuntimeConversationProjection(
+                self.session_id, profile=self.profile, kernel_interactions=True
+            )
+            for previous in self.prefix:
+                self.projection.apply(previous)
+            self.prefix.clear()
+        item = self.projection.apply(canonical)
+        data = dict(event.data)
+        if item is None:
+            data.pop("conversationItem", None)
+        else:
+            item = item.model_copy(update={"run_id": event.run_id})
+            data["conversationItem"] = item.model_dump(
+                mode="json", by_alias=True, exclude_none=True
+            )
+        event_type = event.type
+        if item is None and canonical.event_type in {
+            "interaction.requested",
+            "interaction.resolved",
+        }:
+            # Do not fall back to an actionable legacy form/approval event.
+            event_type = "runtime.interaction_observed"
+            data["interactionReadOnly"] = True
+        return event.model_copy(update={"type": event_type, "data": data})

ksadk/studio/provider_recovery.py

@@ -0,0 +1,59 @@
+"""Reattach approval-paused, Build-pinned Provider runs without replaying input."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from ksadk.runtime import RunHandle
+from ksadk.runtime.executor import RuntimeStartPreparation
+
+
+async def restore_waiting_provider_run(service, record, resolve_spec) -> bool:
+    if not record.runtime_handle or service.plugin_runtime is None:
+        return False
+    try:
+        spec = resolve_spec(record.build_id, model=record.model or None)
+        if (spec.plugin_bundle_root is None or spec.agent_id != record.agent_id
+                or spec.manifest_sha256 != record.manifest_sha256):
+            return False
+        adapter = service.plugin_runtime.kernel_adapter_provider(spec)()
+        matrix = adapter.capabilities()
+        if not (matrix.attach.supported and matrix.durable_restore.supported):
+            return False
+        handle = RunHandle.model_validate(record.runtime_handle)
+        if handle.run_id != record.id or handle.session_id != record.session_id:
+            return False
+        handle = await service.executor.attach(
+            spec.launch_context, handle,
+            preparation=RuntimeStartPreparation(context=spec.launch_context, adapter=adapter),
+        )
+    except Exception:
+        logging.getLogger(__name__).warning("Provider run %s could not reattach", record.id)
+        return False
+    key = (record.agent_id, record.session_id)
+    service._active_sessions.add(key)
+    task = asyncio.create_task(service._execute_runtime_record(
+        spec, record.input, record=record, restored_handle=handle,
+        provider_runtime_adapter=True,
+    ))
+    service._recovery_tasks.add(task)
+
+    def finished(done):
+        service._recovery_tasks.discard(done)
+        service._active_sessions.discard(key)
+        if not done.cancelled():
+            done.exception()
+
+    task.add_done_callback(finished)
+    await asyncio.sleep(0)
+    return not task.done()
+
+
+async def detach_recovered_runs(service) -> None:
+    service._detaching_recoveries = True
+    tasks = tuple(service._recovery_tasks)
+    for task in tasks:
+        task.cancel()
+    await asyncio.gather(*tasks, return_exceptions=True)
+    service._detaching_recoveries = False

ksadk/studio/public_output_store.py

@@ -0,0 +1,69 @@
+"""Run-scoped, bounded, redacted text artifacts; never raw tool receipts."""
+
+import hashlib
+import json
+import re
+
+from ksadk.harness.tool_display import display_text
+from ksadk.studio.errors import StudioError
+
+
+class PublicOutputStore:
+    MAX_BYTES = 1_048_576
+    MAX_RUN_BYTES = 8 * MAX_BYTES
+    MAX_FILES = 64
+
+    def __init__(self, workspace):
+        self.workspace = workspace
+
+    def _directory(self, run_id):
+        identity = hashlib.sha256(run_id.encode()).hexdigest()
+        return self.workspace.resolve(f".agentkit/assets/public-tool-output/{identity}")
+
+    def retain(self, run_id, text, *, incomplete=False):
+        # Sanitize a bounded prefix before persistence, including incomplete PEM
+        # blocks. Never save the original string, args, URLs or filesystem path.
+        bounded = text[: self.MAX_BYTES]
+        public = display_text(bounded, self.MAX_BYTES).encode("utf-8")
+        truncated = incomplete or len(text) > len(bounded) or len(public) > self.MAX_BYTES
+        public = public[: self.MAX_BYTES].decode("utf-8", errors="ignore")
+        body = json.dumps({"text": public, "truncated": truncated}, ensure_ascii=False)
+        encoded = body.encode("utf-8")
+        identity = hashlib.sha256(encoded).hexdigest()
+        directory = self._directory(run_id)
+        directory.mkdir(parents=True, exist_ok=True)
+        files = tuple(directory.glob("*.json"))
+        target = directory / f"{identity}.json"
+        if target.is_file() and not target.is_symlink():
+            return identity
+        if (
+            len(files) >= self.MAX_FILES
+            or sum(p.stat().st_size for p in files) + len(encoded) > self.MAX_RUN_BYTES
+        ):
+            return None
+        self.workspace.atomic_write_text(target.relative_to(self.workspace.root), body)
+        return identity
+
+    def read(self, run_id, identity):
+        missing = StudioError(
+            "PUBLIC_OUTPUT_NOT_FOUND", "公开输出不存在或不可访问", status_code=404
+        )
+        if not isinstance(identity, str) or not re.fullmatch(r"[0-9a-f]{64}", identity):
+            raise missing
+        target = self._directory(run_id) / f"{identity}.json"
+        if (
+            target.is_symlink()
+            or not target.is_file()
+            or target.stat().st_size > self.MAX_BYTES * 6 + 128
+        ):
+            raise missing
+        encoded = target.read_bytes()
+        if hashlib.sha256(encoded).hexdigest() != identity:
+            raise missing
+        try:
+            data = json.loads(encoded)
+            if not isinstance(data["text"], str) or type(data["truncated"]) is not bool:
+                raise ValueError("invalid artifact")
+        except (ValueError, KeyError, TypeError) as exc:
+            raise missing from exc
+        return data

ksadk/studio/recovery_page.py

@@ -0,0 +1,70 @@
+"""A small recovery document that needs neither Core nor built frontend assets."""
+
+RECOVERY_HTML = """<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Studio 恢复</title><style>
+body{font:16px/1.7 system-ui,sans-serif;color:#20262f;background:#f7f8fa;margin:0;padding:8vh 24px}
+main{max-width:680px;margin:auto}h1{font-size:28px}button,a{font:inherit}
+button{padding:8px 16px;margin:8px 12px 8px 0;cursor:pointer}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;background:white;
+border:1px solid #d7dce2;padding:20px;border-radius:8px}a{color:#245ab2}
+</style></head><body><main><h1>Studio 恢复</h1>
+<p>这里可以查看插件启动状态、重试或禁用 Teams。团队数据会保留。</p>
+<pre id="status" role="status">正在读取状态…</pre>
+<p id="error" role="alert"></p>
+<button id="refresh">刷新状态</button><button id="retry">重试插件启动</button>
+<button id="disable">禁用 Teams</button>
+<button id="repair" hidden>备份并升级兼容历史</button>
+<p><a href="/">返回 Studio</a> · <a href="/studio-shell/">打开基础工作区</a></p>
+</main><script>
+const statusNode = document.getElementById('status');
+const errorNode = document.getElementById('error');
+async function request(path, init = {}) {
+  if (init.method === 'POST') {
+    const bootstrap = await fetch('/api/v1/system/bootstrap', {credentials:'same-origin'});
+    if (!bootstrap.ok) throw new Error('本地会话不可用，请重新打开恢复页面。');
+    const session = await bootstrap.json();
+    init.headers = {...init.headers, 'X-CSRF-Token': session.csrfToken};
+  }
+  const response = await fetch(path, {...init, credentials:'same-origin'});
+  const body = await response.json();
+  if (!response.ok) {
+    const error = body.error || {};
+    const stage = error.details?.stage;
+    throw new Error([error.message || '请求失败', error.code, stage].filter(Boolean).join(' · '));
+  }
+  return body;
+}
+async function refresh() {
+  const [host, teams] = await Promise.all([
+    request('/api/v1/plugin-ecosystems/dsh/recovery'),
+    request('/api/v1/plugins/teams/lifecycle')
+  ]);
+  statusNode.textContent = JSON.stringify({host, teams}, null, 2);
+  document.getElementById('repair').hidden = teams.failure?.code !== 'artifact_migration_required';
+}
+async function run(action) {
+  errorNode.textContent = '';
+  document.querySelectorAll('button').forEach(button => button.disabled = true);
+  try { await action(); }
+  catch (error) { errorNode.textContent = error.message; }
+  finally { document.querySelectorAll('button').forEach(button => button.disabled = false); }
+}
+document.getElementById('refresh').onclick = () => run(refresh);
+document.getElementById('retry').onclick = () => run(async () => {
+  try { await request('/api/v1/plugin-ecosystems/dsh/core/session', {method:'POST'}); }
+  finally { await refresh(); }
+});
+document.getElementById('disable').onclick = () => run(async () => {
+  try { await request('/api/v1/plugins/teams/lifecycle', {
+    method:'POST', headers:{'Content-Type':'application/json'}, body:JSON.stringify({enabled:false})
+  }); }
+  finally { await refresh(); }
+});
+document.getElementById('repair').onclick = () => run(async () => {
+  try { await request('/api/v1/plugins/teams/repair', {method:'POST'}); }
+  finally { await refresh(); }
+});
+run(refresh);
+</script></body></html>"""

ksadk/studio/resource_authority.py

@@ -19,6 +19,8 @@ from urllib.parse import urlsplit, urlunsplit
 import requests
 from pydantic import Field, model_validator
 
+from ksadk.common.cloud_headers import build_cloud_headers
+from ksadk.identity.resolver import iam_endpoint_candidates, is_inner_account_error
 from ksadk.knowledge_base.client import KnowledgeBaseClient
 from ksadk.memory.adk.backends.sdk_ltm_backend import SdkLTMBackend
 from ksadk.plugins.contracts import PluginContractModel
@@ -39,6 +41,7 @@ _KSYUN_INTERNAL_HTTP_HOSTS = frozenset(
         "iam.internal.api.ksyun.com",
         "aicp.inner.api.ksyun.com",
         "aicp.internal.api.ksyun.com",
+        "agent-api-pre.kspmas-internal.ksyun.com",
     }
 )
 
@@ -86,7 +89,7 @@ def _canonical_endpoint(
 
 
 class ResourceAuthorityPolicy(PluginContractModel):
-    """Trusted host configuration; it is never populated from a Studio request."""
+    """Trusted local connection policy, not resource-binding claims or caller identity."""
 
     iam_endpoint: str
     iam_region: Identifier = "cn-beijing-6"
@@ -183,7 +186,7 @@ class _HardenedSdkTransport:
                 method=request.method,
                 url=url,
                 data=request.data,
-                headers=dict(request.header),
+                headers=build_cloud_headers(request.header),
                 auth=request.auth,
                 timeout=self.timeout,
                 verify=True,
@@ -362,6 +365,13 @@ class SignedKnowledgeResourceAuthority:
             credentials=credentials,
         )
     def _verify_identity(self, access_key: str, secret_key: str) -> _VerifiedIamIdentity:
+        """Verify the signing key, retrying the IAM intranet for inner accounts.
+
+        Inner-account AKs are rejected by the public IAM endpoint with
+        ``InnerAccountCanOnlyAccessThroughIntranet``.  The standalone identity
+        resolver already handles this case; Studio must use the same fallback
+        so a packaged app launched from Finder behaves like the CLI.
+        """
         try:
             from ksyun.client.iam.v20151101.client import (  # type: ignore[import-untyped]
                 IamClient,
@@ -378,28 +388,40 @@ class SignedKnowledgeResourceAuthority:
                 HttpProfile,
             )
 
-            endpoint = urlsplit(self.policy.iam_endpoint)
-            profile = ClientProfile()
-            profile.httpProfile = HttpProfile(
-                protocol=endpoint.scheme,
-                endpoint=endpoint.netloc,
-                # The hardened transport owns the configured base path.
-                path="/",
-                reqMethod="POST",
-                reqTimeout=self.policy.timeout_seconds,
-            )
-            client = IamClient(
-                Credential(access_key, secret_key), self.policy.iam_region, profile
-            )
-            client.request = _HardenedSdkTransport(
-                self.policy.iam_endpoint, timeout=self.policy.timeout_seconds
-            )
-            listed = _response_object(client.ListAllUserAccessKeys(ListAllUserAccessKeysRequest()))
-            identity = self._identity_from_iam_listing(listed, access_key)
-            request = GetUserRequest()
-            request.UserName = identity
-            user_response = _response_object(client.GetUser(request))
-            return self._identity_from_iam_user(user_response, identity)
+            endpoints = iam_endpoint_candidates(self.policy.iam_endpoint)
+            last_error: Exception | None = None
+            for iam_endpoint in endpoints:
+                try:
+                    endpoint = urlsplit(iam_endpoint)
+                    profile = ClientProfile()
+                    profile.httpProfile = HttpProfile(
+                        protocol=endpoint.scheme,
+                        endpoint=endpoint.netloc,
+                        # The hardened transport owns the configured base path.
+                        path="/",
+                        reqMethod="POST",
+                        reqTimeout=self.policy.timeout_seconds,
+                    )
+                    client = IamClient(
+                        Credential(access_key, secret_key), self.policy.iam_region, profile
+                    )
+                    client.request = _HardenedSdkTransport(
+                        iam_endpoint, timeout=self.policy.timeout_seconds
+                    )
+                    listed = _response_object(
+                        client.ListAllUserAccessKeys(ListAllUserAccessKeysRequest())
+                    )
+                    identity = self._identity_from_iam_listing(listed, access_key)
+                    request = GetUserRequest()
+                    request.UserName = identity
+                    user_response = _response_object(client.GetUser(request))
+                    return self._identity_from_iam_user(user_response, identity)
+                except Exception as error:
+                    last_error = error
+                    if not is_inner_account_error(error):
+                        break
+            assert last_error is not None
+            raise last_error
         except StudioError:
             raise
         except Exception as error:
@@ -582,29 +604,42 @@ def resource_allowed_operations(config: ResourceConfig) -> tuple[ResourceOperati
     if kind == "knowledge-base":
         return ("search_knowledge_base",)
     if kind == "memory-instance":
-        return ("load_memory", "save_memory", "memory_status")
+        return (
+            "load_memory",
+            "save_memory",
+            "update_memory",
+            "delete_memory",
+            "memory_status",
+        )
     return ("list_skills", "search_skills", "load_skill", "read_skill_resource")
 
 
-def resource_authority_policy_from_environment() -> ResourceAuthorityPolicy | None:
+def resource_authority_policy_from_environment(environment=None) -> ResourceAuthorityPolicy | None:
     """Build a trusted policy from operator-owned local Studio environment."""
 
-    access_key = os.environ.get("KSYUN_ACCESS_KEY", "").strip()
-    secret_key = os.environ.get("KSYUN_SECRET_KEY", "").strip()
-    endpoint = os.environ.get("AGENTENGINE_SERVER_URL", "").strip()
-    if not access_key or not secret_key or not endpoint:
+    environment = os.environ if environment is None else environment
+    access_key = environment.get("KSYUN_ACCESS_KEY", "").strip()
+    secret_key = environment.get("KSYUN_SECRET_KEY", "").strip()
+    # AgentEngineClient already has a well-known public control-plane default
+    # (with an inner-endpoint probe).  Resource discovery must use the same
+    # default so global AK/SK credentials do not force a redundant manual
+    # "connect" step just to materialize the local reference declaration.
+    endpoint = environment.get("AGENTENGINE_SERVER_URL", "").strip()
+    if not endpoint:
+        endpoint = "https://aicp.api.ksyun.com"
+    if not access_key or not secret_key:
         return None
     logical_region = (
-        os.environ.get("AGENTENGINE_REGION")
-        or os.environ.get("KSYUN_REGION")
+        environment.get("AGENTENGINE_REGION")
+        or environment.get("KSYUN_REGION")
         or "cn-beijing-6"
     ).strip()
     region = (
-        os.environ.get("AGENTENGINE_PRE_CONTROL_REGION", "cn-beijing-6").strip()
+        environment.get("AGENTENGINE_PRE_CONTROL_REGION", "cn-beijing-6").strip()
         if logical_region.lower() == "pre-online"
         else logical_region
     )
-    iam_endpoint = os.environ.get("KSADK_RESOURCE_IAM_ENDPOINT", "").strip()
+    iam_endpoint = environment.get("KSADK_RESOURCE_IAM_ENDPOINT", "").strip()
     if not iam_endpoint:
         try:
             endpoint_host = (

ksadk/studio/resource_catalog.py

@@ -48,7 +48,7 @@ from ksadk.studio.python_tool_inspection import PythonToolInspector
 from ksadk.studio.repository import load_yaml_file
 from ksadk.studio.skill_discovery import SkillDiscoveryService
 from ksadk.studio.workspace import Workspace
-from ksadk.toolsets import describe_agentengine_tools, get_agentengine_tools
+from ksadk.toolsets import describe_agentengine_tools
 
 _SLUG = re.compile(r"[^a-z0-9]+")
 _MAX_SKILL_ARCHIVE_BYTES = 50 * 1024 * 1024
@@ -1126,12 +1126,14 @@ class LocalResourceCatalog:
         return built
 
     def _build_builtin_tools(self) -> Iterable[ResourceDescriptor]:
-        runtime_tools = {
-            str(getattr(tool, "name", None) or getattr(tool, "__name__", "")): tool
-            for tool in get_agentengine_tools(profile="coding", mode="direct")
-        }
+        from ksadk.toolsets import META_DISPATCHER_TOOL_NAMES
+
         for descriptor in describe_agentengine_tools(profile="coding", mode="direct"):
             name = str(descriptor["name"])
+            if name in META_DISPATCHER_TOOL_NAMES:
+                # 调度类元工具不能绑定到 Agent（harness 构建校验会拒绝），
+                # 不应作为可绑定工具出现在目录与 UI 中。
+                continue
             group = str(descriptor.get("group") or "general")
             side_effects = [str(item) for item in descriptor.get("side_effects") or []]
             side_effect = _tool_side_effect(side_effects)
@@ -1142,18 +1144,18 @@ class LocalResourceCatalog:
                 )
                 if workspace_permission not in permissions:
                     permissions.append(workspace_permission)
-            runtime_tool = runtime_tools.get(name)
-            args_schema = getattr(runtime_tool, "args_schema", None)
-            input_schema = (
-                args_schema.model_json_schema()
-                if args_schema is not None and hasattr(args_schema, "model_json_schema")
-                else {"type": "object", "properties": {}}
-            )
+            input_schema = descriptor.get("input_schema")
+            if not isinstance(input_schema, dict):
+                raise ValueError(f"Builtin tool {name} has no argument contract")
             tool = ToolContract(
                 name=name,
                 version="1.0.0",
                 description=str(descriptor.get("description") or ""),
                 input_schema=input_schema,
+                # Browser inspection may spend 30 s loading and another 30 s
+                # capturing a busy page. The generic 20 s Python Tool lease
+                # killed it before Playwright could return a repairable error.
+                timeout_seconds=90 if name == "browser_inspect_workspace" else 20,
                 permissions=permissions,
                 side_effect=cast(Any, side_effect),
                 approval="always" if descriptor.get("requires_approval") else "never",