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

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
@@ -123,7 +124,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 +193,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 +240,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 +251,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:

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:

ksadk/knowledge_base/client.py

@@ -101,9 +101,13 @@ class KnowledgeBaseClient(BaseModel):
             return self._aicp_client
 
         try:
-            from ksyun.common import credential
-            from ksyun.common.profile.client_profile import ClientProfile
-            from ksyun.common.profile.http_profile import HttpProfile
+            from ksyun.common 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 ImportError:
             raise ImportError(
                 "kingsoftcloud-sdk-python is required for knowledge base. "
@@ -140,9 +144,7 @@ class KnowledgeBaseClient(BaseModel):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(
-            cred, self.region, profile=client_profile
-        )
+        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为 RetrieveKnowledge 所需的 2025-11-14
         # SDK 的 _apiVersion 由导入的模块版本决定，可能不匹配
@@ -159,19 +161,20 @@ class KnowledgeBaseClient(BaseModel):
         """构建 RetrieveKnowledge 请求参数 (JSON 嵌套格式)"""
         effective_top_k = top_k if top_k is not None else self.top_k
 
-        params = {
+        retrieval_model: dict[str, Any] = {
+            "SearchMethod": self.search_method,
+            "TopK": effective_top_k,
+            "RerankingEnable": self.reranking_enable,
+        }
+        params: dict[str, Any] = {
             "DatasetId": self.dataset_id,
             "Query": query,
-            "RetrievalModel": {
-                "SearchMethod": self.search_method,
-                "TopK": effective_top_k,
-                "RerankingEnable": self.reranking_enable,
-            },
+            "RetrievalModel": retrieval_model,
         }
 
         if self.score_threshold_enabled:
-            params["RetrievalModel"]["ScoreThresholdEnabled"] = True
-            params["RetrievalModel"]["ScoreThreshold"] = self.score_threshold
+            retrieval_model["ScoreThresholdEnabled"] = True
+            retrieval_model["ScoreThreshold"] = self.score_threshold
 
         return params
 
@@ -205,9 +208,7 @@ class KnowledgeBaseClient(BaseModel):
 
         return results
 
-    def search(
-        self, query: str, top_k: Optional[int] = None
-    ) -> List[KnowledgeBaseResult]:
+    def search(self, query: str, top_k: Optional[int] = None) -> List[KnowledgeBaseResult]:
         """检索知识库
 
         Args:
@@ -221,18 +222,14 @@ class KnowledgeBaseClient(BaseModel):
         params = self._build_params(query, top_k)
 
         logger.info(
-            f"Searching knowledge base: dataset_id={self.dataset_id}, "
-            f"query='{query[:50]}'"
+            f"Searching knowledge base: dataset_id={self.dataset_id}, " f"query='{query[:50]}'"
         )
 
         try:
-            response = client.call(
-                "RetrieveKnowledge", params, options={"IsPostJson": True}
-            )
+            response = client.call("RetrieveKnowledge", params, options={"IsPostJson": True})
             results = self._parse_response(response)
             logger.info(
-                f"Knowledge base returned {len(results)} results "
-                f"for query='{query[:50]}'"
+                f"Knowledge base returned {len(results)} results " f"for query='{query[:50]}'"
             )
             return results
         except Exception as e:
@@ -252,8 +249,7 @@ class KnowledgeBaseClient(BaseModel):
         dataset_id = os.environ.get("KSADK_KB_DATASET_ID", "")
         if not dataset_id:
             raise ValueError(
-                "KSADK_KB_DATASET_ID environment variable is required "
-                "to enable knowledge base."
+                "KSADK_KB_DATASET_ID environment variable is required " "to enable knowledge base."
             )
 
         access_key = (
@@ -283,9 +279,7 @@ class KnowledgeBaseClient(BaseModel):
             endpoint=connection["endpoint"],
             scheme=connection["scheme"],
             top_k=int(os.environ.get("KSADK_KB_TOP_K", "5")),
-            search_method=os.environ.get(
-                "KSADK_KB_SEARCH_METHOD", "intelligence_search"
-            ),
+            search_method=os.environ.get("KSADK_KB_SEARCH_METHOD", "intelligence_search"),
             score_threshold=score_threshold,
             score_threshold_enabled=score_threshold_enabled,
             reranking_enable=reranking_enable,