agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/plugins/providers/harness_contributions.py

@@ -0,0 +1,241 @@
+"""DSH-locked Skill and MCP contributions shared by Harness engine adapters.
+
+PluginHost owns their activation and disposal. This module has no dependency
+on LangGraph or the Native Kernel and does not select a runtime engine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import re
+from collections.abc import Sequence
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from ksadk.harness.capabilities import (
+    CapabilityDescriptor,
+    CapabilityKind,
+    LoadPolicy,
+    RiskLevel,
+)
+from ksadk.harness.config import McpToolSpec
+from ksadk.harness.mcp_runtime import McpCapabilityRuntime, McpServerBinding
+from ksadk.harness.skill_runtime import SkillManifest
+from ksadk.harness.spec import CapabilityBinding
+from ksadk.harness.tools import HarnessTool, load_mcp_tools
+from ksadk.plugins.providers.mcp_projection import MCPRuntimeCredential, _finish_owned_task
+from ksadk.skills.loader import _parse_frontmatter
+
+
+def resource_id(value: str, *, fallback: str) -> str:
+    normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-._")
+    return normalized or fallback
+
+
+class ProviderSkillSource:
+    """Expose only locked DSH Skill contributions through L0–L3 reads."""
+
+    def __init__(self, contributions: Sequence[Any]) -> None:
+        self._skills: dict[str, Any] = {}
+        for contribution in contributions:
+            name = str(getattr(contribution, "name", "")).strip()
+            instructions = str(getattr(contribution, "instructions", "")).strip()
+            if not name or not instructions:
+                continue
+            ref = f"skill://{resource_id(name, fallback='provider-skill')}@1.0.0"
+            if ref in self._skills:
+                raise ValueError(f"duplicate DSH Skill contribution: {ref}")
+            self._skills[ref] = contribution
+
+    @property
+    def refs(self) -> tuple[str, ...]:
+        return tuple(self._skills)
+
+    def manifest(self, skill_id: str) -> SkillManifest:
+        contribution = self._require(skill_id)
+        instructions = str(contribution.instructions).strip()
+        metadata, body = _parse_frontmatter(instructions)
+        summary = str(metadata.get("description") or "").strip()
+        if not summary:
+            summary = next(
+                (
+                    line.strip().lstrip("#").strip()
+                    for line in body.splitlines()
+                    if line.strip() and line.strip() != "---"
+                ),
+                str(contribution.name),
+            )
+        return SkillManifest(name=str(contribution.name), summary=summary[:512])
+
+    def full_text(self, skill_id: str) -> str:
+        return str(self._require(skill_id).instructions)
+
+    def resource(self, skill_id: str, resource_ref: str) -> bytes:
+        contribution = self._require(skill_id)
+        root = getattr(contribution, "resource_root", None)
+        if root is None:
+            raise FileNotFoundError(
+                f"DSH inline Skill {skill_id} has no packaged resource {resource_ref!r}"
+            )
+        root = Path(root).resolve()
+        candidate = (root / resource_ref).resolve()
+        if Path(resource_ref).is_absolute() or not candidate.is_relative_to(root):
+            raise ValueError("Skill resource path escapes locked Bundle directory")
+        if not candidate.is_file():
+            raise FileNotFoundError(resource_ref)
+        return candidate.read_bytes()
+
+    def _require(self, skill_id: str) -> Any:
+        try:
+            return self._skills[skill_id]
+        except KeyError:
+            raise KeyError(f"DSH Skill {skill_id!r} is not bound") from None
+
+
+class McpToolSpecTransport:
+    """Adapt one locked DSH MCP contribution to the Harness MCP transport."""
+
+    def __init__(
+        self,
+        spec: McpToolSpec,
+        *,
+        credential: MCPRuntimeCredential | None = None,
+    ) -> None:
+        self._spec = spec
+        self._credential = credential
+        self._active_token: str | None = None
+        self._schema_digest: str | None = None
+        self._lock = asyncio.Lock()
+        self._closed = False
+        self._toolset: Any | None = None
+        self._tools: dict[str, HarnessTool] = {}
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        async with self._lock:
+            await self._ensure_loaded()
+            return [
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "inputSchema": tool.parameters,
+                }
+                for tool in self._tools.values()
+            ]
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        async with self._lock:
+            await self._ensure_loaded()
+            try:
+                tool = self._tools[name]
+            except KeyError:
+                raise RuntimeError(
+                    f"MCP tool {name!r} is not exposed by {self._spec.name!r}"
+                ) from None
+            # Auth renewal happens before execution, never by replaying a call.
+            return await tool.call(arguments)
+
+    async def close(self) -> None:
+        self._closed = True
+        async with self._lock:
+            await self._close_current()
+
+    async def _close_current(self) -> None:
+        if self._toolset is not None:
+            await _finish_owned_task(asyncio.create_task(self._toolset.close()))
+        self._toolset = None
+        self._tools.clear()
+
+    async def _ensure_loaded(self) -> None:
+        if self._closed:
+            raise RuntimeError("MCP transport is closed")
+        token = await self._credential.token() if self._credential else self._spec.api_key
+        if self._credential is not None and (not isinstance(token, str) or not token.strip()):
+            raise RuntimeError("MCP runtime credential is unavailable")
+        if self._closed:
+            raise RuntimeError("MCP transport is closed")
+        if self._toolset is not None and token == self._active_token:
+            return
+        await self._close_current()
+        selected = replace(self._spec, api_key=token) if self._credential else self._spec
+        toolset, tools = await load_mcp_tools(selected)
+        try:
+            schema_digest = hashlib.sha256(
+                json.dumps(
+                    sorted((tool.name, tool.description, tool.parameters) for tool in tools),
+                    sort_keys=True,
+                    ensure_ascii=False,
+                    allow_nan=False,
+                ).encode()
+            ).hexdigest()
+            if self._closed or (
+                self._schema_digest is not None and schema_digest != self._schema_digest
+            ):
+                raise RuntimeError("MCP transport closed or locked tool schema changed")
+        except BaseException:
+            await _finish_owned_task(asyncio.create_task(toolset.close()))
+            raise
+        self._schema_digest = schema_digest
+        self._active_token = token
+        self._toolset = toolset
+        self._tools = {tool.name: tool for tool in tools}
+
+
+def mcp_runtime(
+    specs: Sequence[McpToolSpec],
+    *,
+    runtime_credentials: Sequence[MCPRuntimeCredential] = (),
+) -> tuple[
+    McpCapabilityRuntime | None,
+    tuple[McpToolSpecTransport, ...],
+    tuple[CapabilityBinding, ...],
+]:
+    credentials = {item.name: item for item in runtime_credentials}
+    if len(credentials) != len(runtime_credentials) or not set(credentials).issubset(
+        {spec.name for spec in specs}
+    ):
+        raise ValueError("invalid MCP runtime credential binding")
+    if not specs:
+        return None, (), ()
+    runtime = McpCapabilityRuntime()
+    transports: list[McpToolSpecTransport] = []
+    bindings: list[CapabilityBinding] = []
+    seen: set[str] = set()
+    for spec in specs:
+        ref = f"mcp://{resource_id(spec.name, fallback='provider-mcp')}@1.0.0"
+        if ref in seen:
+            raise ValueError(f"duplicate DSH MCP contribution: {ref}")
+        seen.add(ref)
+        transport = McpToolSpecTransport(spec, credential=credentials.get(spec.name))
+        runtime.bind(
+            McpServerBinding(
+                descriptor=CapabilityDescriptor(
+                    id=ref,
+                    kind=CapabilityKind.MCP,
+                    name=spec.name,
+                    description=(spec.description or "").strip()
+                    or f"DSH-provided MCP server {spec.name}",
+                    version="1.0.0",
+                    risk_level=RiskLevel.MEDIUM,
+                    load_policy=LoadPolicy.ON_DEMAND,
+                ),
+                transport=transport,
+                required=True,
+                tool_prefix=spec.tool_name_prefix or "",
+                static_tool_names=tuple(spec.tool_filter),
+            )
+        )
+        transports.append(transport)
+        bindings.append(
+            CapabilityBinding(
+                capability_ref=ref,
+                required=True,
+                load_policy="on_demand",
+            )
+        )
+    return runtime, tuple(transports), tuple(bindings)
+
+
+__all__ = ["ProviderSkillSource", "McpToolSpecTransport", "mcp_runtime", "resource_id"]

ksadk/plugins/providers/harness_delegation.py

@@ -54,12 +54,34 @@ _NEGATED_CODING_SIGNALS = re.compile(
     re.IGNORECASE,
 )
 _DIRECT_FILE_DELIVERY_SIGNALS = re.compile(
-    r"(?:创建|生成|保存|写入|输出)(?:一个|一份|为)?[^。；\n]{0,80}"
-    r"(?:\.(?:md|txt|json|csv|html?)\b|(?:Markdown|MD|文本|JSON|CSV|HTML)\s*文档|文件)|"
+    r"(?:创建|生成|保存|写入|落盘)(?:一个|一份|为)?[^。；\n]{0,80}"
+    r"(?:\.(?:md|txt|json|csv|html?)\b|(?:Markdown|MD|文本|JSON|CSV|HTML)\s*文档|文件|产物)|"
     r"\b(?:create|generate|save|write)\b[^.\n]{0,80}"
     r"(?:\.(?:md|txt|json|csv|html?)\b|\b(?:markdown|text|json|csv|html)\s+file\b)",
     re.IGNORECASE,
 )
+_BOUND_CAPABILITY_ACTION = re.compile(
+    r"(?:(?:调用|读取|查询|检索|搜索|浏览|使用)[^。；\n]{0,24}"
+    r"(?:知识库|技能|Skill|MCP|网页|官方资料)|"
+    r"\b(?:call|read|query|search|browse|use)\b[^.\n]{0,40}"
+    r"\b(?:knowledge\s*base|skill|mcp|web|official\s+sources?)\b)",
+    re.IGNORECASE,
+)
+_DESIGN_ONLY_SIGNALS = re.compile(
+    r"(?:设计|方案|草案|接口|状态机|机制|关卡|可访问性|测试策略|"
+    r"\b(?:design|proposal|spec(?:ification)?|interface|state\s+machine|"
+    r"test\s+strategy)\b)",
+    re.IGNORECASE,
+)
+_DELIVERY_LEAD = re.compile(
+    r"^\s*(?:请\s*|please\s+)?(?:(?:创建|生成|保存|写入)|"
+    r"(?:create|generate|save|write)\b)",
+    re.IGNORECASE,
+)
+_READ_ONLY_TOOL_NAME = re.compile(
+    r"(?:^|_)(?:read|search|list|status|inspect|lint|fetch|view)(?:_|$)",
+    re.IGNORECASE,
+)
 _RESEARCH_SIGNALS = re.compile(
     r"(?:调研|研究|检索|搜索|查找|核对|资料|证据|比较|对比|"
     r"\b(?:research|investigate|search|compare|verify)\b)",
@@ -73,11 +95,30 @@ _RESEARCH_LEAD = re.compile(
 _MUTATING_TASK_SIGNALS = re.compile(
     r"^\s*(?:请\s*|please\s+)?(?:将|把)?[^。；\n]{0,40}"
     r"(?:保存|写入|编辑|修改|上传|发布|删除|"
-    r"\b(?:save|write|edit|modify|upload|publish|delete)\b)",
+    r"实现|开发|编写|构建|编码|落地|落盘|产出|交付|重构|修复|"
+    r"\b(?:save|write|edit|modify|upload|publish|delete|"
+    r"implement|develop|build|code|refactor|fix)\b)",
     re.IGNORECASE,
 )
 
 
+def _is_direct_file_delivery(task: str) -> bool:
+    """Distinguish a durable file request from a design that names files.
+
+    Child design briefs often mention the future ``game-core.mjs`` contract or
+    say "生成设计方案".  Those are text conclusions for the parent, not a
+    request for the child to persist the final artifact.
+    """
+
+    if not _DIRECT_FILE_DELIVERY_SIGNALS.search(task):
+        return False
+    if _NEGATED_CODING_SIGNALS.search(task):
+        return False
+    if _DESIGN_ONLY_SIGNALS.search(task) and not _DELIVERY_LEAD.search(task):
+        return False
+    return True
+
+
 @dataclass(frozen=True)
 class DelegationDecision:
     task_kind: Literal["coding", "general"]
@@ -196,6 +237,18 @@ class AdaptiveDelegationRuntime:
         interrupts while allowing independent product research to run in
         parallel.  Other general tasks retain the existing sequential,
         approval-capable behaviour.
+
+        ⚠️ 判定的唯一依据必须是"任务本身要不要写"，不能只看关键词表够不够全
+        （2026-09-18 实测事故）：父 Agent 并行委派"实现核心规则/开发界面交互/
+        编写自动化测试"三个实现型子任务，而 ``_MUTATING_TASK_SIGNALS`` 当时只认
+        「保存/写入/编辑/修改…」，**不认「实现/开发/编写」**，于是把实现型任务误判
+        成"并行安全的调研"→ 子 Agent 只拿到只读工具 → 一个文件都写不出来 →
+        父 Agent 以 COMPLETED + 0 产物收场。
+
+        这与 Claude Code 的形态一致：**默认可写，只读是显式声明的例外**
+        （``GENERAL_PURPOSE_AGENT.tools = ['*']``；只有 Explore/Plan 用
+        ``disallowedTools`` 禁写）。所以任何"可能产出交付物"的任务都必须走
+        串行、可审批、可写的路径。
         """
         task = str(arguments.get("task") or "").strip()
         if (
@@ -204,18 +257,25 @@ class AdaptiveDelegationRuntime:
             != "general"
         ):
             return False
-        if not _RESEARCH_SIGNALS.search(task):
-            return False
         mutating = (
-            bool(_DIRECT_FILE_DELIVERY_SIGNALS.search(task))
+            _is_direct_file_delivery(task)
             if _RESEARCH_LEAD.search(task)
             else bool(_MUTATING_TASK_SIGNALS.search(task))
         )
+        if _DESIGN_ONLY_SIGNALS.search(task) and not _DELIVERY_LEAD.search(task):
+            mutating = False
         if mutating:
             return False
+        # Bound Skill/MCP catalogs should not serialize every otherwise pure
+        # design/analysis child. Only tasks that explicitly need those shared
+        # external capabilities stay sequential. Parallel children receive a
+        # read-only tool subset and do not inherit the shared runtimes below.
         return not (
-            bool(getattr(parent_run, "skill_catalog", ()))
-            or bool(getattr(parent_run, "mcp_catalog", ()))
+            _BOUND_CAPABILITY_ACTION.search(task)
+            and (
+                bool(getattr(parent_run, "skill_catalog", ()))
+                or bool(getattr(parent_run, "mcp_catalog", ()))
+            )
         )
 
     def preview_route(self, arguments: dict[str, Any], *, call_id: str) -> dict[str, Any]:
@@ -248,7 +308,12 @@ class AdaptiveDelegationRuntime:
         # write lets a text-only child claim success without any durable write
         # receipt. Fail before spawning so the next parent turn can call the
         # bound workspace tool itself.
-        if _DIRECT_FILE_DELIVERY_SIGNALS.search(task):
+        # A model may phrase the same forbidden delegation as "落盘产物"
+        # without spelling out a filename.  Keep this guard intentionally
+        # narrower than the general mutation classifier: coding children are
+        # allowed to implement patches, while final durable delivery remains
+        # parent-owned.
+        if _is_direct_file_delivery(task):
             raise SubagentProviderError(
                 "delegation_requires_parent_tool",
                 "final file delivery must use the parent workspace write tool",
@@ -430,9 +495,21 @@ class AdaptiveDelegationRuntime:
     ) -> tuple[Any, list[RuntimeEvent]]:
         child_name = self._child_name("harness", call_id)
         child_tools = tuple(name for name in parent_run.tools if name != self.name)
-        if self.parallel_safe({"task": task, "task_kind": "general"}, parent_run=parent_run):
-            approval_required = set(getattr(parent_run, "approval_required", ()))
-            child_tools = tuple(name for name in child_tools if name not in approval_required)
+        parallel_safe = self.parallel_safe(
+            {"task": task, "task_kind": "general"}, parent_run=parent_run
+        )
+        if parallel_safe:
+            # ⚠️ 2026-09-18 实测结论（勿轻易放开）：
+            #
+            # 直接去掉这个只读过滤会让子 Agent 立刻撞上**审批门控**——实测
+            # `tests/plugins/test_harness_adaptive_delegation.py` 三个用例同时挂
+            # （子 Agent 不再产出 usage），即写工具带来的并发审批会把子 Agent 卡住。
+            # 所以"让实现型子 Agent 能写"不能只改这一行，必须先有并发写的处置手段
+            # （参照 pi 的 `file-mutation-queue`：同文件串行、不同文件并行）。
+            #
+            # 现状的代价也要记住：并行委派的子 Agent 在架构上**不可能产出交付物**，
+            # 交付必须由父 Agent 落盘（见 run_service 的 EMPTY_DELIVERY 判定）。
+            child_tools = tuple(name for name in child_tools if _READ_ONLY_TOOL_NAME.search(name))
         sub = SubAgentSpec(
             name=child_name,
             description=label,
@@ -448,8 +525,8 @@ class AdaptiveDelegationRuntime:
             timeout_seconds=float(self._child_timeout_seconds),
             max_turns=self._child_max_turns,
             max_total_tokens=self._child_max_total_tokens,
-            inherit_skills=True,
-            inherit_mcp=True,
+            inherit_skills=not parallel_safe,
+            inherit_mcp=not parallel_safe,
             failure_policy="return_error",
         )
         result, _ = await run_subagent(

ksadk/plugins/providers/harness_hooks.py

@@ -0,0 +1,121 @@
+"""Locked PluginHost Hook sources; configuration proposes no execution grant.
+
+This is the Python capability boundary for the DSH-backed Harness provider.
+It does not interpret Cordis/MCP exports as Hooks or execute shell/HTTP config.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+from pydantic import Field, JsonValue
+
+from ksadk.harness.native.hook_runtime_contract import (
+    HookDefinition,
+    HookInvocationRequest,
+    HookOutput,
+    hook_execution_policy_digest,
+)
+from ksadk.harness.native.state import Contract
+from ksadk.plugins.bundle import ResolvedPluginBundle
+from ksadk.plugins.host import PluginExecutionContext, PluginHostError
+
+HARNESS_HOOK_DEFINITION = "harness.hook/v1"
+
+
+class HarnessHookConfiguration(Contract):
+    schema_version: Literal["ksadk.harness-hook-binding/v1"]
+    hooks: tuple[dict[str, JsonValue], ...] = Field(min_length=1, max_length=16)
+    cleanup_timeout_seconds: float = Field(strict=True, gt=0, allow_inf_nan=False)
+    stop_continuation_limit: int | None = Field(default=None, strict=True, ge=0)
+
+    def definitions(self, *, source_ref: str, binding_digest: str) -> tuple[HookDefinition, ...]:
+        policy = hook_execution_policy_digest(
+            cleanup_timeout_seconds=self.cleanup_timeout_seconds,
+        )
+        definitions = []
+        for declaration in self.hooks:
+            # Resource identity is derived from the locked host graph. Neither
+            # editable config nor a callback may replace it.
+            if {"source_ref", "binding_digest", "execution_policy_digest"} & declaration.keys():
+                raise ValueError("Hook config cannot supply binding authority")
+            definitions.append(HookDefinition(
+                **declaration, source_ref=source_ref, binding_digest=binding_digest,
+                execution_policy_digest=policy,
+            ))
+        if len({item.hook_id for item in definitions}) != len(definitions):
+            raise ValueError("duplicate Hook declarations")
+        has_stop = any("Stop" in item.events for item in definitions)
+        if has_stop != (self.stop_continuation_limit is not None):
+            raise ValueError("Stop Hook requires its own explicit continuation policy")
+        return tuple(definitions)
+
+
+@runtime_checkable
+class HarnessHookSource(Protocol):
+    async def harness_hook(
+        self, bundle: ResolvedPluginBundle, request: HookInvocationRequest,
+    ) -> HookOutput: ...
+
+
+@dataclass(frozen=True)
+class HarnessHookBinding:
+    plugin_id: str
+    plugin_version: str
+    slot: str
+    runtime: HarnessHookSource
+
+
+def hook_configuration(
+    bundle: ResolvedPluginBundle, binding: HarnessHookBinding,
+) -> HarnessHookConfiguration:
+    ref = f"plugin://{binding.plugin_id}@{binding.plugin_version}"
+    selected = [item for item in bundle.composition.profile.capabilities if item.ref == ref]
+    locked = [item for item in bundle.composition.plugin_lock.plugins
+              if (item.id, item.version) == (binding.plugin_id, binding.plugin_version)]
+    if len(selected) != 1 or len(locked) != 1 or not any(
+        (item.definition, item.slot, item.owner)
+        == (HARNESS_HOOK_DEFINITION, binding.slot, binding.plugin_id)
+        for item in locked[0].provides
+    ):
+        raise ValueError("native_hook_source_unbound")
+    config = HarnessHookConfiguration.model_validate_json(
+        HarnessHookConfiguration.model_validate(selected[0].config).model_dump_json(),
+    )
+    config.definitions(source_ref=ref, binding_digest=locked[0].digest)
+    return config
+
+
+def project_harness_hooks(
+    bundle: ResolvedPluginBundle, capabilities: PluginExecutionContext,
+) -> tuple[HarnessHookBinding, ...]:
+    selected = capabilities.all(HARNESS_HOOK_DEFINITION)
+    if not selected:
+        return ()
+    if (capabilities.profile_digest, capabilities.plugin_lock_digest) != (
+        bundle.composition.profile_digest, bundle.composition.plugin_lock_digest,
+    ):
+        raise PluginHostError("harness_hook_binding_invalid", "Hook graph pins differ from Bundle")
+    bindings = []
+    owners = set()
+    for item in selected:
+        if not isinstance(item.runtime, HarnessHookSource) or not inspect.iscoroutinefunction(
+            item.runtime.harness_hook,
+        ):
+            raise PluginHostError(
+                "harness_hook_incompatible", "Hook source requires an async producer",
+            )
+        if item.plugin_id in owners:
+            raise PluginHostError("harness_hook_binding_invalid", "duplicate Hook owner")
+        owners.add(item.plugin_id)
+        binding = HarnessHookBinding(item.plugin_id, item.plugin_version, item.slot, item.runtime)
+        try:
+            hook_configuration(bundle, binding)
+        except (ValueError, TypeError) as error:
+            raise PluginHostError(
+                "harness_hook_binding_invalid", "Hook source or policy is not locked",
+            ) from error
+        bindings.append(binding)
+    return tuple(bindings)