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

ksadk/harness/config.py

@@ -0,0 +1,181 @@
+"""HarnessApp yaml 配置 — 最小子集 + 严格校验 (goal-08)。
+
+本期硬边界(防膨胀):**只支持最小子集** ``model`` / ``prompt``(instruction)/
+``mcp_tools`` / ``sandbox``。超出子集的字段(memory/knowledge/workflow/tracing 等)
+**明确报"暂不支持"**,不硬翻、不静默忽略。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml  # type: ignore[import-untyped]
+
+#: 顶层允许的最小子集字段。
+_ALLOWED_TOP_LEVEL = frozenset({"model", "prompt", "mcp_tools", "sandbox", "runtime"})
+#: runtime 允许的值。
+_ALLOWED_RUNTIME = frozenset({"yaml", "codex"})
+#: mcp_tools 单项允许字段。
+_ALLOWED_MCP_TOOL = frozenset({"name", "url", "api_key", "tool_filter", "tool_name_prefix"})
+#: sandbox 允许字段。
+_ALLOWED_SANDBOX = frozenset({"read_only"})
+
+#: 已知但本期不支持的字段,给出更明确的指引。
+_KNOWN_UNSUPPORTED = {
+    "memory": "memory(记忆)暂不支持,后续阶段提供",
+    "knowledge": "knowledge(知识库)暂不支持,后续阶段提供",
+    "workflow": "workflow(工作流编排)暂不支持,后续阶段提供",
+    "tracing": "tracing(可观测)暂不支持,后续阶段提供",
+    "skills": "skills(技能)暂不支持,后续阶段提供",
+}
+
+
+class HarnessConfigError(ValueError):
+    """HarnessApp yaml 配置错误(含"暂不支持"指引)。"""
+
+
+@dataclass(frozen=True)
+class McpToolSpec:
+    """MCP 工具条目(最小子集)。"""
+
+    name: str
+    url: str
+    api_key: Optional[str] = None
+    tool_filter: tuple[str, ...] = ()
+    tool_name_prefix: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class SandboxPolicy:
+    """sandbox 策略。默认 read-only(goal-08:sandbox 默认 read-only)。"""
+
+    read_only: bool = True
+
+
+@dataclass(frozen=True)
+class HarnessConfig:
+    """HarnessApp 的最小 yaml 配置。"""
+
+    model: str
+    prompt: str
+    mcp_tools: tuple[McpToolSpec, ...] = ()
+    sandbox: SandboxPolicy = field(default_factory=SandboxPolicy)
+    runtime: str = "yaml"
+    """runtime 后端:``yaml``(YamlAgentRunner+LiteLLM)| ``codex``(CodexRunner+codex CLI)。"""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], *, source: str = "yaml") -> "HarnessConfig":
+        if not isinstance(data, dict):
+            raise HarnessConfigError(f"{source}: 顶层必须是 mapping,得到 {type(data).__name__}")
+
+        _reject_unknown_keys(data, _ALLOWED_TOP_LEVEL, where=source)
+
+        model = _require_str(data, "model", source)
+        prompt = _require_str(data, "prompt", source)
+
+        runtime = str(data.get("runtime", "yaml")).strip().lower()
+        if runtime not in _ALLOWED_RUNTIME:
+            raise HarnessConfigError(
+                f"{source}: runtime 仅支持 {sorted(_ALLOWED_RUNTIME)},得到 {runtime!r}"
+            )
+
+        mcp_tools = tuple(
+            _parse_mcp_tool(item, index, source)
+            for index, item in enumerate(
+                _require_list(data.get("mcp_tools", []), "mcp_tools", source)
+            )
+        )
+        sandbox = _parse_sandbox(data.get("sandbox", {}), source)
+        return cls(
+            model=model, prompt=prompt, mcp_tools=mcp_tools, sandbox=sandbox, runtime=runtime
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> "HarnessConfig":
+        path = Path(path)
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except yaml.YAMLError as exc:
+            raise HarnessConfigError(f"{path}: YAML 解析失败: {exc}") from exc
+        if data is None:
+            data = {}
+        return cls.from_dict(data, source=str(path))
+
+
+def _reject_unknown_keys(data: dict[str, Any], allowed: frozenset[str], *, where: str) -> None:
+    for key in data:
+        if key in allowed:
+            continue
+        if key in _KNOWN_UNSUPPORTED:
+            raise HarnessConfigError(f"{where}: 字段 {key!r} —— {_KNOWN_UNSUPPORTED[key]}")
+        raise HarnessConfigError(
+            f"{where}: 未知字段 {key!r};本期最小子集仅支持 {sorted(allowed)},"
+            "超出子集的字段不予支持(不静默忽略)"
+        )
+
+
+def _require_str(data: dict[str, Any], key: str, where: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise HarnessConfigError(f"{where}: 字段 {key!r} 必填且必须是非空字符串")
+    return value.strip()
+
+
+def _require_list(value: Any, key: str, where: str) -> list:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise HarnessConfigError(f"{where}: 字段 {key!r} 必须是 list")
+    return value
+
+
+def _parse_mcp_tool(item: Any, index: int, where: str) -> McpToolSpec:
+    if not isinstance(item, dict):
+        raise HarnessConfigError(f"{where}: mcp_tools[{index}] 必须是 mapping")
+    _reject_unknown_keys(item, _ALLOWED_MCP_TOOL, where=f"{where}.mcp_tools[{index}]")
+    name = _require_str(item, "name", f"{where}.mcp_tools[{index}]")
+    url = _require_str(item, "url", f"{where}.mcp_tools[{index}]")
+    tool_filter = item.get("tool_filter", ())
+    if not isinstance(tool_filter, (list, tuple)) or not all(
+        isinstance(t, str) for t in tool_filter
+    ):
+        raise HarnessConfigError(f"{where}.mcp_tools[{index}].tool_filter 必须是字符串 list")
+    api_key = item.get("api_key")
+    if api_key is not None and not isinstance(api_key, str):
+        raise HarnessConfigError(f"{where}.mcp_tools[{index}].api_key 必须是字符串")
+    prefix = item.get("tool_name_prefix")
+    if prefix is not None and not isinstance(prefix, str):
+        raise HarnessConfigError(f"{where}.mcp_tools[{index}].tool_name_prefix 必须是字符串")
+    return McpToolSpec(
+        name=name,
+        url=url,
+        api_key=api_key,
+        tool_filter=tuple(tool_filter),
+        tool_name_prefix=prefix,
+    )
+
+
+def _parse_sandbox(value: Any, where: str) -> SandboxPolicy:
+    if value is None:
+        return SandboxPolicy()
+    if not isinstance(value, dict):
+        raise HarnessConfigError(f"{where}: sandbox 必须是 mapping")
+    _reject_unknown_keys(value, _ALLOWED_SANDBOX, where=f"{where}.sandbox")
+    read_only = value.get("read_only", True)
+    if not isinstance(read_only, bool):
+        raise HarnessConfigError(f"{where}.sandbox.read_only 必须是 bool")
+    if not read_only:
+        raise HarnessConfigError(
+            f"{where}.sandbox.read_only=false 暂不支持;Harness 当前只提供执行层强制的只读策略"
+        )
+    return SandboxPolicy(read_only=read_only)
+
+
+__all__ = [
+    "HarnessConfig",
+    "HarnessConfigError",
+    "McpToolSpec",
+    "SandboxPolicy",
+]

ksadk/harness/reasoner.py

@@ -0,0 +1,105 @@
+"""Reasoning boundary used by the Harness runner."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Protocol, Sequence
+
+
+@dataclass(frozen=True)
+class HarnessToolCall:
+    call_id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class HarnessReasoningTurn:
+    final_text: str | None = None
+    tool_calls: tuple[HarnessToolCall, ...] = ()
+
+
+class HarnessReasoner(Protocol):
+    async def complete(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[Any],
+    ) -> HarnessReasoningTurn: ...
+
+
+class LiteLLMHarnessReasoner:
+    """Use the project's OpenAI-compatible LiteLLM configuration for tool reasoning."""
+
+    async def complete(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[Any],
+    ) -> HarnessReasoningTurn:
+        del prompt
+        try:
+            from litellm import acompletion
+        except ImportError as exc:  # pragma: no cover - depends on optional install
+            raise RuntimeError(
+                "Harness reasoning requires the 'adk' extra (litellm); "
+                "install ksadk[adk] or inject a HarnessReasoner"
+            ) from exc
+
+        resolved_model = model if "/" in model else f"openai/{model}"
+        kwargs: dict[str, Any] = {
+            "model": resolved_model,
+            "messages": list(messages),
+            "tools": [tool.openai_schema for tool in tools],
+            "tool_choice": "auto",
+        }
+        base_url = os.getenv("OPENAI_BASE_URL")
+        api_key = os.getenv("OPENAI_API_KEY")
+        if base_url:
+            kwargs["base_url"] = base_url
+        if api_key:
+            kwargs["api_key"] = api_key
+        response = await acompletion(**kwargs)
+        choices = getattr(response, "choices", None) or []
+        if not choices:
+            raise RuntimeError(f"Harness model {model!r} returned no choices")
+        message = choices[0].message
+        calls: list[HarnessToolCall] = []
+        for index, call in enumerate(getattr(message, "tool_calls", None) or []):
+            function = getattr(call, "function", None)
+            name = str(getattr(function, "name", "") or "").strip()
+            raw_arguments = getattr(function, "arguments", None) or "{}"
+            try:
+                arguments = (
+                    json.loads(raw_arguments) if isinstance(raw_arguments, str) else raw_arguments
+                )
+            except json.JSONDecodeError as exc:
+                raise RuntimeError(
+                    f"Harness model emitted invalid JSON arguments for tool {name!r}"
+                ) from exc
+            if not name or not isinstance(arguments, dict):
+                raise RuntimeError("Harness model emitted an invalid tool call")
+            calls.append(
+                HarnessToolCall(
+                    call_id=str(getattr(call, "id", "") or f"tool-call-{index}"),
+                    name=name,
+                    arguments=dict(arguments),
+                )
+            )
+        content = getattr(message, "content", None)
+        final_text = str(content) if content is not None else None
+        return HarnessReasoningTurn(final_text=final_text, tool_calls=tuple(calls))
+
+
+__all__ = [
+    "HarnessReasoner",
+    "HarnessReasoningTurn",
+    "HarnessToolCall",
+    "LiteLLMHarnessReasoner",
+]

ksadk/harness/runner.py

@@ -0,0 +1,211 @@
+"""Runner that composes model reasoning with real MCP and sandbox tools."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, AsyncIterator, Dict
+
+from ksadk.harness.config import HarnessConfig
+from ksadk.harness.reasoner import (
+    HarnessReasoner,
+    HarnessReasoningTurn,
+    HarnessToolCall,
+    LiteLLMHarnessReasoner,
+)
+from ksadk.harness.sandbox import HarnessSandboxExecutor
+from ksadk.harness.tools import HarnessTool, load_mcp_tools, sandbox_tools, tool_result_text
+from ksadk.runners.base_runner import BaseRunner
+
+_MAX_REASONING_TURNS = 8
+
+
+class YamlAgentRunner(BaseRunner):
+    """Execute one Harness config through the shared runner/runtime contract."""
+
+    def __init__(
+        self,
+        config: HarnessConfig,
+        *,
+        agent_name: str = "harness-agent",
+        reasoner: HarnessReasoner | None = None,
+        workspace_root: str | Path = ".",
+    ) -> None:
+        super().__init__(
+            detection_result=SimpleNamespace(
+                name=agent_name,
+                type=SimpleNamespace(value="harness"),
+            ),
+            project_dir=str(workspace_root),
+        )
+        self._config = config
+        self._reasoner = reasoner or LiteLLMHarnessReasoner()
+        self._sandbox = HarnessSandboxExecutor(
+            workspace_root=workspace_root,
+            read_only=config.sandbox.read_only,
+        )
+        self._loaded = False
+        self._load_lock = asyncio.Lock()
+        self._tools: tuple[HarnessTool, ...] | None = None
+        self._mcp_toolsets: list[Any] = []
+
+    @property
+    def harness_config(self) -> HarnessConfig:
+        return self._config
+
+    @property
+    def sandbox(self) -> HarnessSandboxExecutor:
+        return self._sandbox
+
+    @property
+    def workspace_root(self) -> Path:
+        return self._sandbox.workspace_root
+
+    def load_agent(self) -> None:
+        # MCP discovery is async and therefore happens lazily on first invocation.
+        self._loaded = True
+
+    def prepare_for_request(self, model: str | None) -> None:
+        # Request model is carried in input_data. Do not mutate process-wide model env.
+        del model
+
+    def _effective(self, input_data: Dict[str, Any]) -> tuple[str, str]:
+        metadata = input_data.get("metadata") or {}
+        if not isinstance(metadata, dict):
+            metadata = {}
+        model = str(
+            metadata.get("model_override") or input_data.get("model") or self._config.model
+        ).strip()
+        prompt = str(
+            metadata.get("prompt_override") or input_data.get("instructions") or self._config.prompt
+        ).strip()
+        return model, prompt
+
+    async def invoke(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        tools = await self._ensure_tools()
+        model, prompt = self._effective(input_data)
+        user_input = str(input_data.get("input") or "")
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": user_input},
+        ]
+        execution_log: list[dict[str, Any]] = []
+
+        for _turn_number in range(_MAX_REASONING_TURNS):
+            turn = await self._reasoner.complete(
+                model=model,
+                prompt=prompt,
+                messages=tuple(messages),
+                tools=tools,
+            )
+            if turn.tool_calls:
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": turn.final_text,
+                        "tool_calls": [
+                            {
+                                "id": call.call_id,
+                                "type": "function",
+                                "function": {
+                                    "name": call.name,
+                                    "arguments": json.dumps(call.arguments, ensure_ascii=False),
+                                },
+                            }
+                            for call in turn.tool_calls
+                        ],
+                    }
+                )
+                for call in turn.tool_calls:
+                    tool = next((item for item in tools if item.name == call.name), None)
+                    if tool is None:
+                        raise RuntimeError(
+                            f"Harness tool {call.name!r} is not available; it may be filtered "
+                            "or was not exposed by its MCP server"
+                        )
+                    result = await tool.call(call.arguments, call_id=call.call_id)
+                    content = tool_result_text(result)
+                    execution_log.append(
+                        {
+                            "call_id": call.call_id,
+                            "name": call.name,
+                            "source": tool.source,
+                            "result": result,
+                        }
+                    )
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": call.call_id,
+                            "name": call.name,
+                            "content": content,
+                        }
+                    )
+                continue
+            if turn.final_text is None:
+                raise RuntimeError(
+                    "Harness reasoner returned neither a final response nor a tool call"
+                )
+            return {
+                "output": turn.final_text,
+                "model": model,
+                "prompt": prompt,
+                "tool_calls": execution_log,
+                "sandbox_read_only": self._config.sandbox.read_only,
+            }
+        raise RuntimeError(f"Harness reasoning exceeded {_MAX_REASONING_TURNS} turns")
+
+    async def stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
+        result = await self.invoke(input_data)
+        yield {"delta": result["output"], "type": "text"}
+        yield {
+            "output": result["output"],
+            "type": "final",
+            "model": result["model"],
+            "tool_calls": result["tool_calls"],
+            "sandbox_read_only": result["sandbox_read_only"],
+        }
+
+    async def close(self) -> None:
+        toolsets, self._mcp_toolsets = self._mcp_toolsets, []
+        self._tools = None
+        if toolsets:
+            await asyncio.gather(*(toolset.close() for toolset in toolsets), return_exceptions=True)
+
+    async def _ensure_tools(self) -> tuple[HarnessTool, ...]:
+        if self._tools is not None:
+            return self._tools
+        async with self._load_lock:
+            if self._tools is not None:
+                return self._tools
+            tools = sandbox_tools(self._sandbox)
+            try:
+                for spec in self._config.mcp_tools:
+                    toolset, discovered = await load_mcp_tools(spec)
+                    self._mcp_toolsets.append(toolset)
+                    tools.extend(discovered)
+                duplicates = sorted(
+                    {
+                        tool.name
+                        for tool in tools
+                        if sum(item.name == tool.name for item in tools) > 1
+                    }
+                )
+                if duplicates:
+                    raise RuntimeError(f"Harness tool names are not unique: {duplicates}")
+            except Exception:
+                await self.close()
+                raise
+            self._tools = tuple(tools)
+            return self._tools
+
+
+__all__ = [
+    "HarnessReasoner",
+    "HarnessReasoningTurn",
+    "HarnessToolCall",
+    "LiteLLMHarnessReasoner",
+    "YamlAgentRunner",
+]

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"]