agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__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``(HarnessRuntimeAdapter)| ``codex``(CodexRuntimeAdapter)。"""
+
+    @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/runtime.py

@@ -0,0 +1,364 @@
+"""Native RuntimeAdapter for YAML Harness agents."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ksadk.events import EventPhase, EventType, RuntimeEvent
+from ksadk.harness.config import HarnessConfig
+from ksadk.harness.reasoner import HarnessReasoner, LiteLLMHarnessReasoner
+from ksadk.harness.sandbox import HarnessSandboxExecutor
+from ksadk.harness.tools import HarnessTool, load_mcp_tools, sandbox_tools, tool_result_text
+from ksadk.runtime import (
+    BaseRuntime,
+    CancelResult,
+    CheckpointCapability,
+    CheckpointDescriptor,
+    ResumePayload,
+    ResumeTarget,
+    RunHandle,
+    RuntimeAdapter,
+    StartRequest,
+)
+
+_MAX_REASONING_TURNS = 8
+
+
+class HarnessRuntime(BaseRuntime):
+    runtime_type = "harness"
+
+    def native_capabilities(self) -> dict[str, Any]:
+        return {
+            "cancel": {"supported": True},
+            "resume": {"supported": False},
+            "checkpoint": {"supported": False, "granularity": "none"},
+            "session_continuity": {"durable": False, "scope": "process"},
+        }
+
+
+@dataclass
+class _HarnessRun:
+    request: StartRequest
+    task: asyncio.Task[dict[str, Any]] | None = None
+    pending_cancel: bool = False
+    done: bool = False
+
+
+class HarnessRuntimeAdapter(RuntimeAdapter):
+    """Execute a YAML Harness config directly as RuntimeEvent streams."""
+
+    def __init__(
+        self,
+        config: HarnessConfig,
+        *,
+        agent_name: str = "harness-agent",
+        reasoner: HarnessReasoner | None = None,
+        workspace_root: str | Path = ".",
+    ) -> None:
+        super().__init__(HarnessRuntime())
+        self._config = config
+        self._agent_name = agent_name
+        self._reasoner = reasoner or LiteLLMHarnessReasoner()
+        self._sandbox = HarnessSandboxExecutor(
+            workspace_root=workspace_root,
+            read_only=config.sandbox.read_only,
+        )
+        self._runs: dict[str, _HarnessRun] = {}
+        self._tools: tuple[HarnessTool, ...] | None = None
+        self._tool_lock = asyncio.Lock()
+        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
+
+    async def start(self, request: StartRequest) -> RunHandle:
+        run_id = str(request.metadata.get("invocation_id") or f"harness_{uuid.uuid4().hex}")
+        if run_id in self._runs:
+            raise ValueError(f"duplicate Harness invocation: {run_id}")
+        self._runs[run_id] = _HarnessRun(request=request)
+        return RunHandle(
+            run_id=run_id,
+            session_id=request.session_id,
+            runtime_type="harness",
+            native_ref={"user_id": request.user_id, "agent_id": request.agent_id},
+        )
+
+    def stream(self, handle: RunHandle):
+        return self._stream(handle)
+
+    async def cancel(self, handle: RunHandle) -> CancelResult:
+        run = self._runs.get(handle.run_id)
+        if run is None or run.done:
+            return CancelResult.NOT_RUNNING
+        if run.task is None:
+            run.pending_cancel = True
+            return CancelResult.PENDING_CANCEL_RECORDED
+        if run.task.done():
+            return CancelResult.NOT_RUNNING
+        run.task.cancel()
+        return CancelResult.INTERRUPTED_ACTIVE_TURN
+
+    async def resume(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: ResumePayload | None,
+    ) -> RunHandle:
+        del handle, target, payload
+        raise RuntimeError("Harness runtime does not support resume")
+
+    async def checkpoint(self, handle: RunHandle) -> CheckpointDescriptor:
+        return CheckpointDescriptor(
+            checkpoint_id=f"unsupported:{handle.run_id}",
+            invocation_id=handle.run_id,
+            capability=CheckpointCapability(
+                supported=False,
+                granularity="none",
+                rollback_scope="none",
+                fork_supported=False,
+                durable=False,
+                shared_across_pods=False,
+                reason="Harness runtime has no checkpoint backend",
+            ),
+        )
+
+    async def close(self, handle: RunHandle) -> None:
+        run = self._runs.pop(handle.run_id, None)
+        if run is not None and run.task is not None and not run.task.done():
+            run.task.cancel()
+            await asyncio.gather(run.task, return_exceptions=True)
+        if not self._runs:
+            await self._close_tools()
+
+    def is_handle_attached(self, handle: RunHandle) -> bool:
+        return handle.run_id in self._runs
+
+    async def execute_request(self, request: StartRequest) -> dict[str, Any]:
+        tools = await self._ensure_tools()
+        model, prompt = self._effective(request)
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": str(request.input or "")},
+        ]
+        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,
+                            "arguments": dict(call.arguments),
+                            "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")
+
+    def _effective(self, request: StartRequest) -> tuple[str, str]:
+        metadata = request.metadata or {}
+        model = str(
+            metadata.get("model_override") or request.model or self._config.model
+        ).strip()
+        prompt = str(
+            metadata.get("prompt_override")
+            or request.config.get("base_instructions")
+            or request.config.get("instructions")
+            or request.config.get("prompt")
+            or self._config.prompt
+        ).strip()
+        return model, prompt
+
+    async def _stream(self, handle: RunHandle):
+        run = self._require_run(handle)
+        seq = 0
+
+        def event(
+            event_type: str,
+            payload: dict[str, Any],
+            *,
+            phase: str | None = None,
+        ) -> RuntimeEvent:
+            nonlocal seq
+            seq += 1
+            request = run.request
+            return RuntimeEvent.create(
+                event_type,
+                agent_id=str(request.agent_id or self._agent_name),
+                user_id=request.user_id,
+                session_id=request.session_id,
+                invocation_id=handle.run_id,
+                seq_id=seq,
+                payload=payload,
+                phase=phase,
+            )
+
+        if run.pending_cancel:
+            run.done = True
+            yield event(
+                EventType.RUN_CANCELED,
+                {
+                    "status": "cancelled",
+                    "cancel_result": CancelResult.PENDING_CANCEL_RECORDED.value,
+                },
+            )
+            return
+        yield event(EventType.RUN_STARTED, {"status": "in_progress"})
+        run.task = asyncio.create_task(self.execute_request(run.request))
+        try:
+            result = await run.task
+            for call in result["tool_calls"]:
+                yield event(
+                    EventType.TOOL_CALL_BEGIN,
+                    {
+                        "call_id": call["call_id"],
+                        "name": call["name"],
+                        "args": call["arguments"],
+                    },
+                )
+                yield event(
+                    EventType.TOOL_CALL_END,
+                    {
+                        "call_id": call["call_id"],
+                        "name": call["name"],
+                        "result": call["result"],
+                    },
+                )
+            text = str(result["output"])
+            yield event(
+                EventType.TEXT_DELTA,
+                {"text": text},
+                phase=EventPhase.FINAL_ANSWER.value,
+            )
+            yield event(
+                EventType.TEXT_COMPLETED,
+                {"text": text},
+                phase=EventPhase.FINAL_ANSWER.value,
+            )
+            run.done = True
+            yield event(EventType.RUN_COMPLETED, {"status": "completed"})
+        except asyncio.CancelledError:
+            run.done = True
+            yield event(
+                EventType.RUN_CANCELED,
+                {
+                    "status": "cancelled",
+                    "cancel_result": CancelResult.INTERRUPTED_ACTIVE_TURN.value,
+                },
+            )
+        except Exception as exc:  # noqa: BLE001
+            run.done = True
+            yield event(
+                EventType.RUN_FAILED,
+                {"status": "failed", "error": str(exc)},
+            )
+
+    def _require_run(self, handle: RunHandle) -> _HarnessRun:
+        if handle.runtime_type != "harness":
+            raise ValueError(f"Harness adapter cannot stream {handle.runtime_type!r}")
+        try:
+            return self._runs[handle.run_id]
+        except KeyError:
+            raise KeyError(f"unknown Harness run: {handle.run_id}") from None
+
+    async def _ensure_tools(self) -> tuple[HarnessTool, ...]:
+        if self._tools is not None:
+            return self._tools
+        async with self._tool_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_tools()
+                raise
+            self._tools = tuple(tools)
+            return self._tools
+
+    async def _close_tools(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)
+
+
+__all__ = ["HarnessRuntime", "HarnessRuntimeAdapter"]