agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

ksadk/toolsets/sandbox.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
+import logging
 import os
 import shlex
 import time
-import logging
 from typing import Any
 from uuid import uuid4
 
@@ -15,7 +15,6 @@ from ksadk.tools.result_budget import budget_text_fields
 from ksadk.toolsets._langchain import as_tool
 from ksadk.toolsets.workspace import workspace_root
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -30,11 +29,19 @@ def _gateway():
     return default_tool_gateway(_SANDBOX_TOOL_POLICIES)
 
 
+def _dict_result(value: Any, *, tool_name: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{tool_name} returned {type(value).__name__}, expected dict")
+    return dict(value)
+
+
 def sandbox_backend_name() -> str:
     explicit = os.environ.get("KSADK_SANDBOX_BACKEND", "").strip().lower()
     if explicit:
         return explicit
-    if os.environ.get("KSADK_SANDBOX_TEMPLATE_ID") or os.environ.get("KSADK_SKILL_RUNTIME_TEMPLATE_ID"):
+    if os.environ.get("KSADK_SANDBOX_TEMPLATE_ID") or os.environ.get(
+        "KSADK_SKILL_RUNTIME_TEMPLATE_ID"
+    ):
         return "e2b"
     return "none"
 
@@ -47,15 +54,26 @@ def _sandbox_execution_backend_name() -> str:
 def sandbox_status() -> dict:
     """Report configured AgentEngine sandbox status and boundaries."""
 
-    return _gateway().invoke("sandbox_status", _sandbox_status_impl)
+    return _dict_result(
+        _gateway().invoke("sandbox_status", _sandbox_status_impl),
+        tool_name="sandbox_status",
+    )
 
 
 def _sandbox_status_impl() -> dict[str, Any]:
     backend = sandbox_backend_name()
-    timeout = int(os.environ.get("KSADK_SANDBOX_TIMEOUT") or os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT") or "600")
+    timeout = int(
+        os.environ.get("KSADK_SANDBOX_TIMEOUT")
+        or os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT")
+        or "600"
+    )
     idle_ttl = _int_env("KSADK_SANDBOX_IDLE_TTL_SECONDS", 300)
     max_sessions = _int_env("KSADK_SANDBOX_MAX_SESSIONS", 0)
-    template_id = os.environ.get("KSADK_SANDBOX_TEMPLATE_ID") or os.environ.get("KSADK_SKILL_RUNTIME_TEMPLATE_ID") or ""
+    template_id = (
+        os.environ.get("KSADK_SANDBOX_TEMPLATE_ID")
+        or os.environ.get("KSADK_SKILL_RUNTIME_TEMPLATE_ID")
+        or ""
+    )
     isolated = backend not in {"local", "local_process", "pod", "pod_process"}
     latest = GLOBAL_SANDBOX_REGISTRY.latest()
     now = time.time()
@@ -89,7 +107,19 @@ def run_command(
 ) -> dict[str, Any]:
     """Run a shell command inside the configured isolated sandbox."""
 
-    return _gateway().invoke("run_command", _run_command_impl, command, cwd, timeout, env, background, approval=approval)
+    return _dict_result(
+        _gateway().invoke(
+            "run_command",
+            _run_command_impl,
+            command,
+            cwd,
+            timeout,
+            env,
+            background,
+            approval=approval,
+        ),
+        tool_name="run_command",
+    )
 
 
 def _run_command_impl(
@@ -102,11 +132,15 @@ def _run_command_impl(
     command_text = str(command or "").strip()
     if not command_text:
         return {"ok": False, "error_message": "command is required"}
-    policy = check_command_policy(command_text)
+    policy = _dict_result(check_command_policy(command_text), tool_name="check_command_policy")
     if not policy.get("ok"):
         return policy
     if background:
-        return {"ok": False, "error_type": "background_not_supported", "error_message": "background commands are not supported in P0"}
+        return {
+            "ok": False,
+            "error_type": "background_not_supported",
+            "error_message": "background commands are not supported in P0",
+        }
     try:
         entry, _created = _sandbox_entry("ksadk-direct")
         result = entry.session.run_command(command_text, timeout=timeout, env=env, cwd=cwd)
@@ -119,7 +153,15 @@ def _run_command_impl(
             "stderr": result.stderr,
             "exit_code": result.exit_code,
         }
-        return budget_text_fields(payload, tool_name="run_command", fields=("stdout", "stderr"), metadata={"tool_use_id": entry.sandbox_id})
+        return _dict_result(
+            budget_text_fields(
+                payload,
+                tool_name="run_command",
+                fields=("stdout", "stderr"),
+                metadata={"tool_use_id": entry.sandbox_id},
+            ),
+            tool_name="run_command",
+        )
     except SandboxError as exc:
         return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
     except Exception as exc:
@@ -135,7 +177,12 @@ def run_code(
 ) -> dict[str, Any]:
     """Run a code snippet through the sandbox; this is not a shell replacement."""
 
-    return _gateway().invoke("run_code", _run_code_impl, code, language, timeout, env, approval=approval)
+    return _dict_result(
+        _gateway().invoke(
+            "run_code", _run_code_impl, code, language, timeout, env, approval=approval
+        ),
+        tool_name="run_code",
+    )
 
 
 def _run_code_impl(
@@ -152,7 +199,10 @@ def _run_code_impl(
         return {
             "ok": False,
             "error_type": "isolated_sandbox_required",
-            "error_message": "run_code requires an isolated sandbox backend; local_process and pod_process are not supported for snippet execution",
+            "error_message": (
+                "run_code requires an isolated sandbox backend; local_process and "
+                "pod_process are not supported for snippet execution"
+            ),
             "backend": backend_name,
             "boundary": _sandbox_boundary(backend_name),
         }
@@ -181,7 +231,15 @@ def _run_code_impl(
             "stderr": result.stderr,
             "exit_code": result.exit_code,
         }
-        return budget_text_fields(payload, tool_name="run_code", fields=("stdout", "stderr"), metadata={"tool_use_id": entry.sandbox_id})
+        return _dict_result(
+            budget_text_fields(
+                payload,
+                tool_name="run_code",
+                fields=("stdout", "stderr"),
+                metadata={"tool_use_id": entry.sandbox_id},
+            ),
+            tool_name="run_code",
+        )
     except SandboxError as exc:
         return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
     except Exception as exc:
@@ -300,10 +358,18 @@ def _int_env(name: str, default: int) -> int:
 
 def _sandbox_boundary(backend: str) -> str:
     if backend in {"local", "local_process"}:
-        return "executes as a local child process; shares local filesystem, env allowlist, and network"
+        return (
+            "executes as a local child process; shares local filesystem, env allowlist, and network"
+        )
     if backend in {"pod", "pod_process"}:
-        return "executes inside the agent pod; shares pod filesystem, env allowlist, network, and service account"
-    return "Sandbox tools execute commands and code only through the configured isolated sandbox backend; they never expose the host shell."
+        return (
+            "executes inside the agent pod; shares pod filesystem, env allowlist, "
+            "network, and service account"
+        )
+    return (
+        "Sandbox tools execute commands and code only through the configured isolated "
+        "sandbox backend; they never expose the host shell."
+    )
 
 
 def get_sandbox_tools() -> list:

ksadk/toolsets/skills.py

@@ -18,15 +18,18 @@ from ksadk.skills.service_env import (
     user_skill_space_ids,
 )
 from ksadk.skills.tool_defs import (
-    build_execute_skills_tool as build_runtime_execute_skills_tool,
+    _skill_manifest_item,
     load_remote_skill_manifests,
     resolve_skill_space_ids,
 )
+from ksadk.skills.tool_defs import (
+    build_execute_skills_tool as build_runtime_execute_skills_tool,
+)
 from ksadk.tools.gateway import ToolPolicy, default_tool_gateway
 from ksadk.toolsets._langchain import as_tool
 
-
 _SKILL_TOOL_POLICIES = {
+    "list_skill_spaces": ToolPolicy(risk_level="low"),
     "list_skills": ToolPolicy(risk_level="low"),
     "search_skills": ToolPolicy(risk_level="low"),
     "load_skill": ToolPolicy(risk_level="low", side_effects=("skill_cache_write",)),
@@ -38,27 +41,132 @@ def _gateway():
     return default_tool_gateway(_SKILL_TOOL_POLICIES)
 
 
-def list_skills() -> dict[str, Any]:
-    """List skills discoverable from configured Skill Spaces."""
+def _dict_result(value: Any, *, tool_name: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{tool_name} returned {type(value).__name__}, expected dict")
+    return dict(value)
+
 
+def list_skill_spaces() -> dict[str, Any]:
+    """List visible Skill Spaces with id/name/description, so the model can pick one by intent.
+
+    多 space 场景下,先调用本工具了解可选 space,再按用户意图用
+    ``search_skills(query, space_id=...)`` 或 ``load_skill(name, space_id=...)`` 定向查找。
+    """
+
+    configured = resolve_skill_space_ids()
     try:
-        manifests = load_remote_skill_manifests(resolve_skill_space_ids())
+        client = _skill_service_client()
+        payload = client.list_skill_spaces()
+        spaces = _parse_skill_spaces(payload)
+        configured_set = set(configured)
+        for space in spaces:
+            space["configured"] = space["space_id"] in configured_set
+        if not spaces:
+            # 服务不支持 ListSkillSpaces 时,退化为返回已配置的 space id。
+            spaces = [
+                {"space_id": sid, "space_name": "", "description": "", "configured": True}
+                for sid in configured
+            ]
+        return {
+            "ok": True,
+            "configured_space_ids": configured,
+            "spaces": spaces,
+            "usage": (
+                "根据用户意图从这些 space 中选一个 space_id,再用 "
+                "search_skills(query, space_id=...) 在该 space 内搜索,或用 "
+                "load_skill(skill_name, space_id=...) 精确加载该 space 下的 skill。"
+            ),
+        }
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error_type": type(exc).__name__,
+            "error_message": str(exc),
+            "configured_space_ids": configured,
+            "spaces": [
+                {"space_id": sid, "space_name": "", "description": "", "configured": True}
+                for sid in configured
+            ],
+        }
+
+
+def _parse_skill_spaces(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    data = payload.get("Data") or payload.get("data") or {}
+    raw = (
+        data.get("SkillSpaces")
+        or data.get("skill_spaces")
+        or data.get("Spaces")
+        or data.get("spaces")
+        or data.get("Items")
+        or data.get("items")
+        or []
+    )
+    spaces: list[dict[str, Any]] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        spaces.append(
+            {
+                "space_id": str(
+                    item.get("SkillSpaceId")
+                    or item.get("skill_space_id")
+                    or item.get("SpaceId")
+                    or item.get("space_id")
+                    or ""
+                ),
+                "space_name": str(
+                    item.get("SkillSpaceName")
+                    or item.get("skill_space_name")
+                    or item.get("SpaceName")
+                    or item.get("space_name")
+                    or ""
+                ),
+                "description": str(item.get("Description") or item.get("description") or ""),
+            }
+        )
+    return spaces
+
+
+def list_skills(space_id: str | None = None) -> dict[str, Any]:
+    """List skills discoverable from configured Skill Spaces, optionally limited to one space.
+
+    ``space_id`` 指定时只列该 space(user space id 或 ``"public"``);缺省列出全部已配置 space。
+    """
+
+    space_ids = [space_id] if space_id else resolve_skill_space_ids()
+    try:
+        if space_id:
+            client = _skill_service_client()
+            manifests = [
+                _skill_manifest_item(skill, space_id=sid)
+                for sid, skill in _iter_remote_skills(client, space_id=space_id)
+                if skill.name
+            ]
+        else:
+            manifests = load_remote_skill_manifests(space_ids)
         return {
             "ok": True,
             "skills": manifests,
-            "skill_space_ids": resolve_skill_space_ids(),
+            "skill_space_ids": space_ids,
+            "space_id": space_id,
         }
     except Exception as exc:
         return {
             "ok": False,
             "error_type": type(exc).__name__,
             "error_message": str(exc),
-            "skill_space_ids": resolve_skill_space_ids(),
+            "skill_space_ids": space_ids,
+            "space_id": space_id,
         }
 
 
-def load_skill(skill_name: str) -> dict[str, Any]:
-    """Download and load a skill's SKILL.md instructions from configured Skill Spaces."""
+def load_skill(skill_name: str, space_id: str | None = None) -> dict[str, Any]:
+    """Download and load a skill's SKILL.md instructions from configured Skill Spaces.
+
+    ``space_id`` 指定时只在该 space 内按名匹配,用于多 space 下精确定位、避免同名冲突;
+    缺省按配置顺序(user space 优先于 public)取第一个匹配。
+    """
 
     target = str(skill_name or "").strip().lower()
     if not target:
@@ -66,7 +174,7 @@ def load_skill(skill_name: str) -> dict[str, Any]:
     try:
         client = _skill_service_client()
         available: list[str] = []
-        for space_id, skill in _iter_remote_skills(client):
+        for sid, skill in _iter_remote_skills(client, space_id=space_id):
             if not skill.name:
                 continue
             available.append(skill.name)
@@ -79,7 +187,7 @@ def load_skill(skill_name: str) -> dict[str, Any]:
                 "execution_context": "outer_agent",
                 "name": local_skill.name,
                 "description": local_skill.description,
-                "space_id": space_id,
+                "space_id": sid,
                 "skill_id": skill.skill_id,
                 "version_id": skill.version_id,
                 "version": skill.version,
@@ -88,31 +196,52 @@ def load_skill(skill_name: str) -> dict[str, Any]:
                 "has_scripts_dir": (local_skill.root_dir / "scripts").is_dir(),
                 "script_files": _script_files(local_skill.root_dir),
                 "instructions": local_skill.body,
-                "usage": "Read these instructions and complete the user's task in the outer agent unless the skill explicitly requires isolated execution.",
+                "usage": (
+                    "Read these instructions and complete the user's task in the outer "
+                    "agent unless the skill explicitly requires isolated execution."
+                ),
             }
         return {
             "ok": False,
             "error_message": f"Skill not found: {skill_name}",
+            "space_id": space_id,
             "available_skills": available,
         }
     except Exception as exc:
         return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
 
 
-def search_skills(query: str, max_results: int = 10) -> dict[str, Any]:
-    """Search skills by name, aliases, tags, description, and examples."""
+def search_skills(query: str, max_results: int = 10, space_id: str | None = None) -> dict[str, Any]:
+    """Search skills by name, aliases, tags, description, and examples.
+
+    ``space_id`` 指定时只在该 space 内搜索;缺省聚合全部已配置 space。结果带 ``space_id``,
+    便于后续 ``load_skill(name, space_id=...)`` 精确定位。
+    """
 
     query_text = str(query or "").strip()
     if not query_text:
         return {"ok": False, "error_message": "query is required"}
     try:
         client = _skill_service_client()
-        refs = [skill for _, skill in _iter_remote_skills(client)]
+        pairs = list(_iter_remote_skills(client, space_id=space_id))
+        # 建立 skill 标识 -> space_id 映射,给结果回填来源 space(cache_key 与 match 去重一致)。
+        space_of: dict[str, str] = {}
+        for sid, skill in pairs:
+            space_of.setdefault(skill.cache_key or skill.skill_id or skill.name, sid)
+        refs = [skill for _, skill in pairs]
         matches = match_skill_refs(refs, query_text, limit=max_results)
+        results = []
+        for match in matches:
+            item = match.to_dict()
+            item["space_id"] = space_of.get(
+                match.skill.cache_key or match.skill.skill_id or match.skill.name, ""
+            )
+            results.append(item)
         return {
             "ok": True,
             "query": query,
-            "results": [match.to_dict() for match in matches],
+            "space_id": space_id,
+            "results": results,
         }
     except Exception as exc:
         return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
@@ -125,43 +254,64 @@ def execute_skills(
 ) -> dict[str, Any]:
     """Execute a workflow through the configured Skill Runtime."""
 
-    return _gateway().invoke(
-        "execute_skills",
-        _execute_skills_impl,
-        workflow_prompt,
-        skill_names,
-        approval=approval,
+    return _dict_result(
+        _gateway().invoke(
+            "execute_skills",
+            _execute_skills_impl,
+            workflow_prompt,
+            skill_names,
+            approval=approval,
+        ),
+        tool_name="execute_skills",
     )
 
 
-def _execute_skills_impl(workflow_prompt: str, skill_names: list[str] | str | None = None) -> dict[str, Any]:
+def _execute_skills_impl(
+    workflow_prompt: str, skill_names: list[str] | str | None = None
+) -> dict[str, Any]:
     try:
         backend = create_skill_runtime_backend()
         raw_tool = build_runtime_execute_skills_tool(backend=backend)
         result = raw_tool(workflow_prompt, skill_names)
-        if isinstance(result, dict):
-            result.setdefault("execution_context", f"skill-runtime/{_skill_execution_backend()}")
-        return result
+        if not isinstance(result, dict):
+            return {
+                "ok": False,
+                "error_type": "invalid_skill_runtime_result",
+                "error_message": (f"skill runtime returned {type(result).__name__}, expected dict"),
+            }
+        result.setdefault("execution_context", f"skill-runtime/{_skill_execution_backend()}")
+        return dict(result)
     except SkillRuntimeError as exc:
         return {
             "ok": False,
             "error_type": "skill_runtime_disabled",
             "error_message": str(exc),
-            "hint": "Configure KSADK_SKILL_RUNTIME_BACKEND=local_process/e2b or KSADK_SANDBOX_TEMPLATE_ID for isolated Skill workflow execution.",
+            "hint": (
+                "Configure KSADK_SKILL_RUNTIME_BACKEND=local_process/e2b or "
+                "KSADK_SANDBOX_TEMPLATE_ID for isolated Skill workflow execution."
+            ),
         }
     except Exception as exc:
         return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
 
 
 def get_skill_tools() -> list:
-    return [as_tool(list_skills), as_tool(search_skills), as_tool(load_skill), as_tool(execute_skills)]
+    return [
+        as_tool(list_skills),
+        as_tool(list_skill_spaces),
+        as_tool(search_skills),
+        as_tool(load_skill),
+        as_tool(execute_skills),
+    ]
 
 
 def _skill_execution_backend() -> str:
     explicit = os.environ.get("KSADK_SKILL_RUNTIME_BACKEND", "").strip().lower()
     if explicit:
         return explicit
-    if os.environ.get("KSADK_SANDBOX_TEMPLATE_ID") or os.environ.get("KSADK_SKILL_RUNTIME_TEMPLATE_ID"):
+    if os.environ.get("KSADK_SANDBOX_TEMPLATE_ID") or os.environ.get(
+        "KSADK_SKILL_RUNTIME_TEMPLATE_ID"
+    ):
         return "e2b"
     return "disabled"
 
@@ -177,21 +327,34 @@ def _skill_service_client() -> SkillServiceClient:
     )
 
 
-def _iter_remote_skills(client: SkillServiceClient):
-    for space_id in user_skill_space_ids():
+def _iter_space_skills(client: SkillServiceClient, space_id: str):
+    """遍历单个 space 的 active skill;space_id="public" 走 premade 列表。"""
+
+    if space_id == "public":
+        listing = client.list_available_premade_skills()
+        for skill in select_public_skill_refs(listing.active_skills()):
+            yield listing.space_id or "public", skill
+    else:
         listing = client.list_skills_by_space_id(space_id)
         for skill in listing.active_skills():
             yield space_id, skill
+
+
+def _iter_remote_skills(client: SkillServiceClient, space_id: str | None = None):
+    """遍历配置的 space;space_id 指定时只遍历该 space(user 或 "public")。"""
+
+    if space_id:
+        yield from _iter_space_skills(client, space_id)
+        return
+    for user_space_id in user_skill_space_ids():
+        yield from _iter_space_skills(client, user_space_id)
     if public_skill_space_ids():
-        listing = client.list_available_premade_skills()
-        for skill in select_public_skill_refs(listing.active_skills()):
-            yield listing.space_id or "public", skill
+        yield from _iter_space_skills(client, "public")
 
 
 def _get_or_download_package(client: SkillServiceClient, skill):
     cache_dir = Path(
-        os.environ.get("KSADK_SKILL_CACHE_DIR")
-        or Path(tempfile.gettempdir()) / "ksadk-skill-cache"
+        os.environ.get("KSADK_SKILL_CACHE_DIR") or Path(tempfile.gettempdir()) / "ksadk-skill-cache"
     )
     store = PackageStore(cache_dir=cache_dir)
     package = store.get_cached(skill)
@@ -211,7 +374,5 @@ def _script_files(root_dir: Path) -> list[str]:
     if not scripts_dir.is_dir():
         return []
     return [
-        str(path.relative_to(root_dir))
-        for path in sorted(scripts_dir.rglob("*"))
-        if path.is_file()
+        str(path.relative_to(root_dir)) for path in sorted(scripts_dir.rglob("*")) if path.is_file()
     ][:20]