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

ksadk/harness/sandbox.py

@@ -0,0 +1,141 @@
+"""Invocation-owned execution policy for Harness sandbox tools."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+class SandboxPolicyDenied(PermissionError):
+    """Raised before execution when a Harness sandbox action violates policy."""
+
+
+_READ_COMMANDS = frozenset({"cat", "head", "ls", "pwd", "stat", "tail", "wc"})
+_NO_PATH_COMMANDS = frozenset({"pwd"})
+_REQUIRE_PATH_COMMANDS = frozenset({"cat", "head", "stat", "tail", "wc"})
+_VALUE_OPTIONS = frozenset({"-n", "--bytes", "--lines", "--max-unchanged-stats"})
+_SHELL_OPERATORS = frozenset({"|", "||", "&", "&&", ";", ">", ">>", "<", "<<"})
+
+
+class HarnessSandboxExecutor:
+    """Run a deliberately small read-only command surface inside one workspace.
+
+    Commands are executed without a shell. Path operands are resolved before the
+    child process starts, including symlinks, so reads cannot escape the configured
+    workspace. The narrow command surface also excludes network clients and process
+    launchers entirely.
+    """
+
+    def __init__(self, *, workspace_root: str | Path, read_only: bool = True) -> None:
+        self._workspace_root = Path(workspace_root).expanduser().resolve()
+        self._workspace_root.mkdir(parents=True, exist_ok=True)
+        self._read_only = read_only
+
+    @property
+    def workspace_root(self) -> Path:
+        return self._workspace_root
+
+    @property
+    def read_only(self) -> bool:
+        return self._read_only
+
+    async def read_file(self, path: str) -> dict[str, Any]:
+        target = self._resolve_path(path)
+        content = await asyncio.to_thread(target.read_text, encoding="utf-8")
+        return {
+            "ok": True,
+            "path": target.relative_to(self._workspace_root).as_posix(),
+            "content": content,
+            "policy": "read-only",
+        }
+
+    async def run_command(self, command: str) -> dict[str, Any]:
+        argv = self._validate_command(command)
+        completed = await asyncio.to_thread(
+            subprocess.run,
+            argv,
+            cwd=self._workspace_root,
+            env={"PATH": os.environ.get("PATH", "")},
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+        return {
+            "ok": completed.returncode == 0,
+            "command": " ".join(argv),
+            "stdout": completed.stdout,
+            "stderr": completed.stderr,
+            "exit_code": completed.returncode,
+            "policy": "read-only",
+        }
+
+    def _validate_command(self, command: str) -> list[str]:
+        try:
+            argv = shlex.split(str(command or ""), posix=True)
+        except ValueError as exc:
+            raise SandboxPolicyDenied(f"read-only sandbox denied malformed command: {exc}") from exc
+        if not argv:
+            raise SandboxPolicyDenied("read-only sandbox denied empty command")
+        if any(argument in _SHELL_OPERATORS for argument in argv):
+            raise SandboxPolicyDenied(
+                "read-only sandbox denied shell redirection, pipelines, or command chaining"
+            )
+        executable = argv[0]
+        if executable not in _READ_COMMANDS:
+            raise SandboxPolicyDenied(
+                f"read-only sandbox denied command {executable!r}; network, write, and "
+                "dangerous process actions are not allowed"
+            )
+        if executable in _NO_PATH_COMMANDS:
+            if len(argv) != 1:
+                raise SandboxPolicyDenied(
+                    f"read-only sandbox denied arguments for command {executable!r}"
+                )
+            return argv
+
+        normalized = [executable]
+        skip_option_value = False
+        saw_path = False
+        for argument in argv[1:]:
+            if skip_option_value:
+                normalized.append(argument)
+                skip_option_value = False
+                continue
+            if argument == "--":
+                normalized.append(argument)
+                continue
+            if argument in _VALUE_OPTIONS:
+                normalized.append(argument)
+                skip_option_value = True
+                continue
+            if argument.startswith("-"):
+                normalized.append(argument)
+                continue
+            target = self._resolve_path(argument)
+            normalized.append(str(target))
+            saw_path = True
+        if executable in _REQUIRE_PATH_COMMANDS and not saw_path:
+            raise SandboxPolicyDenied(
+                f"read-only sandbox denied command {executable!r} without a workspace path"
+            )
+        return normalized
+
+    def _resolve_path(self, path: str) -> Path:
+        raw = str(path or "").strip()
+        if not raw:
+            raise SandboxPolicyDenied("read-only sandbox requires a workspace path")
+        candidate = Path(raw)
+        if not candidate.is_absolute():
+            candidate = self._workspace_root / candidate
+        resolved = candidate.expanduser().resolve()
+        if resolved != self._workspace_root and self._workspace_root not in resolved.parents:
+            raise SandboxPolicyDenied(f"read-only sandbox denied path outside workspace: {raw!r}")
+        return resolved
+
+
+__all__ = ["HarnessSandboxExecutor", "SandboxPolicyDenied"]

ksadk/harness/tools.py

@@ -0,0 +1,222 @@
+"""Tool catalog for one Harness runner."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+from ksadk.compat.adk_compat import Agent, InMemorySessionService, InvocationContext, ToolContext
+from ksadk.harness.config import McpToolSpec
+from ksadk.harness.sandbox import HarnessSandboxExecutor
+from ksadk.mcp_runtime import MCPServerConfig, build_mcp_toolset
+
+ToolHandler = Callable[[dict[str, Any], str | None], Awaitable[Any]]
+
+
+@dataclass(frozen=True)
+class HarnessTool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    handler: ToolHandler
+    source: str
+
+    @property
+    def openai_schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    async def call(self, arguments: dict[str, Any], *, call_id: str | None = None) -> Any:
+        return await self.handler(arguments, call_id)
+
+
+def sandbox_tools(sandbox: HarnessSandboxExecutor) -> list[HarnessTool]:
+    async def _read_file(arguments: dict[str, Any], call_id: str | None) -> Any:
+        del call_id
+        return await sandbox.read_file(str(arguments.get("path") or ""))
+
+    async def _run_command(arguments: dict[str, Any], call_id: str | None) -> Any:
+        del call_id
+        return await sandbox.run_command(str(arguments.get("command") or ""))
+
+    return [
+        HarnessTool(
+            name="sandbox_read_file",
+            description="Read one UTF-8 file inside the Harness workspace.",
+            parameters={
+                "type": "object",
+                "properties": {"path": {"type": "string"}},
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+            handler=_read_file,
+            source="sandbox",
+        ),
+        HarnessTool(
+            name="sandbox_run_command",
+            description=(
+                "Run an allowlisted read-only command inside the Harness workspace. "
+                "Writes, network access, and dangerous process actions are denied."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {"command": {"type": "string"}},
+                "required": ["command"],
+                "additionalProperties": False,
+            },
+            handler=_run_command,
+            source="sandbox",
+        ),
+    ]
+
+
+async def load_mcp_tools(spec: McpToolSpec) -> tuple[Any, list[HarnessTool]]:
+    config = MCPServerConfig(
+        name=spec.name,
+        url=spec.url,
+        api_key=spec.api_key,
+        tool_filter=spec.tool_filter,
+        tool_name_prefix=spec.tool_name_prefix,
+    )
+    toolset = build_mcp_toolset(config)
+    try:
+        native_tools = await toolset.get_tools_with_prefix()
+    except Exception as exc:
+        await toolset.close()
+        raise RuntimeError(
+            f"Harness MCP server {spec.name!r} at {spec.url!r} failed to start: {exc}"
+        ) from exc
+
+    available_names = {str(tool.name) for tool in native_tools}
+    expected_names = {
+        f"{spec.tool_name_prefix}_{name}" if spec.tool_name_prefix else name
+        for name in spec.tool_filter
+    }
+    missing_names = sorted(expected_names - available_names)
+    if missing_names:
+        await toolset.close()
+        raise RuntimeError(
+            f"Harness MCP server {spec.name!r} at {spec.url!r} did not expose configured "
+            f"tool(s): {missing_names}"
+        )
+    if not native_tools:
+        await toolset.close()
+        raise RuntimeError(
+            f"Harness MCP server {spec.name!r} at {spec.url!r} exposed no callable tools"
+        )
+
+    tools: list[HarnessTool] = []
+    for native_tool in native_tools:
+        # ADK's declaration builder is private and changed across 1.x/2.x.
+        # MCP exposes the original public tool schema, which is stable across
+        # the supported versions.
+        raw_tool = getattr(native_tool, "raw_mcp_tool", None)
+        parameters = getattr(raw_tool, "inputSchema", None)
+        if parameters is None:
+            parameters = getattr(raw_tool, "input_schema", None)
+        if parameters is None:
+            parameters = getattr(native_tool, "input_schema", None)
+        if not isinstance(parameters, dict):
+            parameters = {"type": "object", "properties": {}}
+        parameters = _normalize_json_schema(parameters)
+
+        async def _call(
+            arguments: dict[str, Any],
+            call_id: str | None,
+            *,
+            _native_tool=native_tool,
+            _tool_name=str(native_tool.name),
+        ) -> Any:
+            try:
+                context = await _new_tool_context(call_id or _tool_name)
+                result = await _native_tool.run_async(args=arguments, tool_context=context)
+                return _normalize_tool_result(result, context)
+            except Exception as exc:
+                raise RuntimeError(
+                    f"Harness MCP tool {_tool_name!r} on server {spec.name!r} failed: {exc}"
+                ) from exc
+
+        tools.append(
+            HarnessTool(
+                name=str(native_tool.name),
+                description=str(getattr(native_tool, "description", None) or "MCP tool"),
+                parameters=parameters,
+                handler=_call,
+                source=f"mcp:{spec.name}",
+            )
+        )
+    return toolset, tools
+
+
+async def _new_tool_context(tool_name: str) -> Any:
+    """Build a real ADK ToolContext for a standalone MCP invocation."""
+    service = InMemorySessionService()
+    session = await service.create_session(
+        app_name="ksadk-harness",
+        user_id="harness",
+        session_id=f"tool-{uuid.uuid4().hex}",
+    )
+    invocation = InvocationContext(
+        session_service=service,
+        invocation_id=f"harness-tool-{tool_name}",
+        # ADK 1.34 requires an agent while 2.x makes it optional. Supplying a
+        # minimal public Agent keeps the same ToolContext construction on both.
+        agent=Agent(name="harness_tool", model="gemini-2.0-flash"),
+        session=session,
+    )
+    return ToolContext(invocation_context=invocation, function_call_id=tool_name)
+
+
+def _normalize_tool_result(result: Any, context: Any) -> Any:
+    """Keep MCP failures structured so the reasoner can produce a final answer."""
+    confirmations = getattr(context.actions, "requested_tool_confirmations", {})
+    if confirmations:
+        error = result.get("error") if isinstance(result, dict) else None
+        return {
+            "ok": False,
+            "confirmation_required": True,
+            "confirmation_ids": sorted(str(item) for item in confirmations),
+            "error": str(error or "tool confirmation is required"),
+        }
+    if isinstance(result, dict) and result.get("error") is not None:
+        return {"ok": False, "error": str(result["error"])}
+    return result
+
+
+def tool_result_text(result: Any) -> str:
+    if isinstance(result, str):
+        return result
+    if isinstance(result, dict):
+        content = result.get("content")
+        if isinstance(content, list):
+            texts = [
+                str(item.get("text"))
+                for item in content
+                if isinstance(item, dict) and item.get("text") is not None
+            ]
+            if texts:
+                return "\n".join(texts)
+    return json.dumps(result, ensure_ascii=False, default=str)
+
+
+def _normalize_json_schema(value: Any) -> Any:
+    if isinstance(value, dict):
+        normalized = {key: _normalize_json_schema(item) for key, item in value.items()}
+        schema_type = normalized.get("type")
+        if isinstance(schema_type, str):
+            normalized["type"] = schema_type.lower()
+        return normalized
+    if isinstance(value, list):
+        return [_normalize_json_schema(item) for item in value]
+    return value
+
+
+__all__ = ["HarnessTool", "load_mcp_tools", "sandbox_tools", "tool_result_text"]

ksadk/hermes_terminal.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import ctypes
+import importlib
 import io
 import json
 import os
@@ -89,6 +90,7 @@ def build_start_frame(
     argv: Sequence[str],
     cols: int,
     rows: int,
+    session_id: str | None = None,
     cwd: str | None = None,
     options: Mapping[str, Any] | None = None,
 ) -> str:
@@ -105,6 +107,9 @@ def build_start_frame(
     normalized_cwd = str(cwd or "").strip()
     if normalized_cwd:
         payload["cwd"] = normalized_cwd
+    normalized_session_id = str(session_id or "").strip()
+    if normalized_session_id:
+        payload["session_id"] = normalized_session_id
     if options:
         payload["options"] = dict(options)
     return json.dumps(payload, ensure_ascii=False)
@@ -123,7 +128,9 @@ def validate_terminal_exec_argv(argv: Iterable[str]) -> list[str]:
     return validate_exec_argv_with_policy(argv, policy=GENERIC_TERMINAL_EXEC_POLICY)
 
 
-def build_terminal_exec_validator(policy: TerminalExecPolicy) -> Callable[[Iterable[str]], list[str]]:
+def build_terminal_exec_validator(
+    policy: TerminalExecPolicy,
+) -> Callable[[Iterable[str]], list[str]]:
     def _validator(argv: Iterable[str]) -> list[str]:
         return validate_exec_argv_with_policy(argv, policy=policy)
 
@@ -190,30 +197,34 @@ def _raw_terminal(stdin: Any):
 
 
 @contextlib.contextmanager
-def _windows_raw_terminal(stdin: Any, *, kernel32: Any | None = None, msvcrt_module: Any | None = None):
+def _windows_raw_terminal(
+    stdin: Any, *, kernel32: Any | None = None, msvcrt_module: Any | None = None
+):
     if not hasattr(stdin, "fileno") or not hasattr(stdin, "isatty") or not stdin.isatty():
         yield
         return
 
+    resolved_kernel32: Any = kernel32
+    resolved_msvcrt: Any = msvcrt_module
     try:
-        if kernel32 is None:
-            kernel32 = ctypes.windll.kernel32
-        if msvcrt_module is None:
-            import msvcrt as msvcrt_module  # type: ignore[no-redef]
+        if resolved_kernel32 is None:
+            resolved_kernel32 = getattr(ctypes, "windll").kernel32
+        if resolved_msvcrt is None:
+            resolved_msvcrt = importlib.import_module("msvcrt")
     except Exception:
         yield
         return
 
     try:
         fd = stdin.fileno()
-        handle = msvcrt_module.get_osfhandle(fd)
+        handle = resolved_msvcrt.get_osfhandle(fd)
     except Exception:
         yield
         return
 
     original_mode = wintypes.DWORD()
     try:
-        if not kernel32.GetConsoleMode(handle, ctypes.byref(original_mode)):
+        if not resolved_kernel32.GetConsoleMode(handle, ctypes.byref(original_mode)):
             yield
             return
     except Exception:
@@ -233,7 +244,7 @@ def _windows_raw_terminal(stdin: Any, *, kernel32: Any | None = None, msvcrt_mod
     )
 
     try:
-        if not kernel32.SetConsoleMode(handle, raw_mode):
+        if not resolved_kernel32.SetConsoleMode(handle, raw_mode):
             yield
             return
     except Exception:
@@ -244,14 +255,18 @@ def _windows_raw_terminal(stdin: Any, *, kernel32: Any | None = None, msvcrt_mod
         yield
     finally:
         with contextlib.suppress(Exception):
-            kernel32.SetConsoleMode(handle, int(original_mode.value))
+            resolved_kernel32.SetConsoleMode(handle, int(original_mode.value))
 
 
-async def _connect_websocket(ws_url: str, headers: dict[str, str], ssl_context: ssl.SSLContext | None):
+async def _connect_websocket(
+    ws_url: str, headers: dict[str, str], ssl_context: ssl.SSLContext | None
+):
     try:
         import websockets
     except ImportError as e:
-        raise RuntimeError("missing dependency websockets, please install ksadk with websocket support") from e
+        raise RuntimeError(
+            "missing dependency websockets, please install ksadk with websocket support"
+        ) from e
 
     kwargs: dict[str, Any] = {"subprotocols": [TERMINAL_SUBPROTOCOL]}
     if ssl_context is not None:
@@ -404,6 +419,7 @@ async def run_hermes_terminal_session(
                 argv=normalized_argv,
                 cols=size.cols,
                 rows=size.rows,
+                session_id=session_id,
                 cwd=cwd,
                 options=options,
             )

ksadk/identity/resolver.py

@@ -31,11 +31,11 @@ _KRN_ACCOUNT_RE = re.compile(r"krn:ksc:iam::([^:]+):user/")
 class ResolvedIdentity:
     """AK/SK 反查到的身份信息。"""
 
-    user_uuid: Optional[str]        # 子账号 UserId（X-Ksc-User-uuid 值）；主账号 AK 时 None
+    user_uuid: Optional[str]  # 子账号 UserId（X-Ksc-User-uuid 值）；主账号 AK 时 None
     main_account_id: Optional[str]  # 从 Krn 提取的主账号 ID
-    user_name: Optional[str]        # 子账号 UserName（调试用）
-    krn: Optional[str]              # 原始 Krn（调试用）
-    ak_fingerprint: str             # sha256(AK)[:16]，缓存 key
+    user_name: Optional[str]  # 子账号 UserName（调试用）
+    krn: Optional[str]  # 原始 Krn（调试用）
+    ak_fingerprint: str  # sha256(AK)[:16]，缓存 key
 
 
 # ---------------------------------------------------------------------------
@@ -107,14 +107,20 @@ def _should_retry_intranet(error: Exception | None) -> bool:
 def _import_iam_sdk():
     """惰性导入 ksyun IAM SDK，失败返回 None。"""
     try:
-        from ksyun.client.iam.v20151101.client import IamClient
-        from ksyun.client.iam.v20151101.models import (
+        from ksyun.client.iam.v20151101.client import (  # type: ignore[import-untyped]
+            IamClient,
+        )
+        from ksyun.client.iam.v20151101.models import (  # type: ignore[import-untyped]
             GetUserRequest,
             ListAllUserAccessKeysRequest,
         )
-        from ksyun.common.credential import Credential
-        from ksyun.common.profile.client_profile import ClientProfile
-        from ksyun.common.profile.http_profile import HttpProfile
+        from ksyun.common.credential import Credential  # type: ignore[import-untyped]
+        from ksyun.common.profile.client_profile import (  # type: ignore[import-untyped]
+            ClientProfile,
+        )
+        from ksyun.common.profile.http_profile import (  # type: ignore[import-untyped]
+            HttpProfile,
+        )
     except Exception as exc:
         logger.warning("导入 ksyun IAM SDK 失败: %s", exc)
         return None

ksadk/ids.py

@@ -0,0 +1,32 @@
+"""统一 id 铸造规范。
+
+历史上 session / run(invocation) id 各层格式混杂：
+
+- agentengine-server hosted 会话: ``sess-<16 hex>``（conversation_service）
+- ksadk 本地 session: 裸 ``<16 hex>``（sessions/base.generate_id）
+- ksadk 后台 run: ``inv_<32 hex>``（server/app RunAgent）
+- ksadk conversation turn: 裸 ``uuid4``（conversations/runtime）
+- research-ui run_agent 模式: ``run_<session段>``（由 session id 推导）
+
+新代码统一走这里：
+
+- session id: ``sess-<16 hex>``，与 agentengine-server 对齐。
+- run/invocation id: ``run_<32 hex>``，每次 run 唯一且固定长度。
+
+id 均为不透明字符串，仅在铸造时保证格式，消费方不做结构解析。
+"""
+
+from __future__ import annotations
+
+import uuid
+
+
+def new_session_id() -> str:
+    """铸造 session id：``sess-<16 hex>``。"""
+    return f"sess-{uuid.uuid4().hex[:16]}"
+
+
+def new_run_id(session_id: str | None = None) -> str:
+    """铸造固定长度 opaque run/invocation id：``run_<32 hex>``。"""
+    del session_id
+    return f"run_{uuid.uuid4().hex}"

ksadk/knowledge_base/adk_tool.py

@@ -36,7 +36,7 @@ def create_adk_tool():
         可直接注入到 ADK Agent 的工具对象
     """
     try:
-        from google.adk.tools import FunctionTool
+        from ksadk.compat.adk_compat import FunctionTool
 
         return FunctionTool(func=search_knowledge_base)
     except ImportError: