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

ksadk/harness/subagent_adapters/prepared_recovery.py

@@ -0,0 +1,120 @@
+"""Lease takeover for a committed, undispatched child effect.
+
+Verify-only recovery remains separate from ordinary Kernel continuation.
+Both grants retain the original configuration, origin and lease policy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from ksadk.harness.native.engine import NativeKernel
+from ksadk.harness.native.state import RunPhase, RunSnapshot
+from ksadk.harness.stores.native_contract import LeaseBusy
+
+
+def _prepared(
+    kernel: NativeKernel, snapshot: RunSnapshot, original: RunSnapshot, *,
+    allow_execution: bool = False, allow_compaction: bool = False,
+) -> bool:
+    intent = kernel.store.get_intent(kernel.scope, snapshot.run_id, snapshot.pending_intent)
+    phases = {"verify": RunPhase.VERIFYING}
+    if allow_execution:
+        phases.update(model=RunPhase.REQUESTING_MODEL, tool=RunPhase.EXECUTING_TOOLS)
+    phase_allowed = intent is not None and snapshot.phase == phases.get(intent.kind)
+    if (
+        allow_execution and allow_compaction and intent is not None
+        and intent.kind == "model" and snapshot.phase == RunPhase.COMPACTING
+    ):
+        # This permission belongs only to the checkpoint grant. Verify-only
+        # and the older prepared-execution grant retain their original scope.
+        phase_allowed = (
+            intent.payload == {"purpose": "compaction"}
+            and snapshot.compaction_request is not None
+            and kernel.context.planner is not None
+            and snapshot.context_binding == kernel.context.binding
+        )
+    return (
+        phase_allowed
+        and snapshot.goal_revision == original.goal_revision == 0
+        and snapshot.goal == original.goal
+        and snapshot.origin == original.origin
+        and snapshot.session_id == original.session_id
+        and snapshot.pending_intent == original.pending_intent
+        and intent.status == "prepared"
+        and (intent.kind != "tool" or isinstance(intent.payload.get("call"), dict))
+        and kernel.store.get_receipt(kernel.scope, snapshot.run_id, intent.operation_key) is None
+        and not kernel.store.commands(kernel.scope, snapshot.run_id)
+    )
+
+
+async def _claim_prepared(
+    kernel: NativeKernel, original: RunSnapshot, *, ttl: float | None, timeout: float,
+    allow_execution: bool,
+) -> tuple[RunSnapshot, bool]:
+    if (
+        ttl is None or original.origin.get("lease_policy") != "native.owner_lease/v1"
+        or type(original.origin.get("lease_ttl_seconds")) not in {int, float}
+        or original.origin["lease_ttl_seconds"] != ttl
+        or not _prepared(kernel, original, original, allow_execution=allow_execution)
+    ):
+        raise ValueError("child_prepared_recovery_rejected")
+    deadline = asyncio.get_running_loop().time() + min(timeout, ttl + 1)
+    while True:
+        current = kernel.snapshot(original.run_id)
+        if current.phase.terminal:
+            return current, False
+        if not _prepared(kernel, current, original, allow_execution=allow_execution):
+            raise ValueError("child_prepared_recovery_rejected")
+        try:
+            kernel.attach(original.run_id)
+        except LeaseBusy:
+            remaining = deadline - asyncio.get_running_loop().time()
+            if remaining <= 0:
+                raise ValueError("child_owner_still_active") from None
+            await asyncio.sleep(min(0.05, remaining))
+        else:
+            # The old owner could commit between our read and lease acquisition.
+            # Return ownership before any await so the caller always releases it.
+            try:
+                return kernel.snapshot(original.run_id), True
+            except BaseException:
+                kernel.release(original.run_id)
+                raise
+
+
+async def claim_prepared_verification(
+    kernel: NativeKernel, original: RunSnapshot, *, ttl: float | None, timeout: float
+) -> tuple[RunSnapshot, bool]:
+    return await _claim_prepared(kernel, original, ttl=ttl, timeout=timeout,
+                                 allow_execution=False)
+
+
+async def claim_prepared_execution(
+    kernel: NativeKernel, original: RunSnapshot, *, ttl: float | None, timeout: float
+) -> tuple[RunSnapshot, bool]:
+    return await _claim_prepared(kernel, original, ttl=ttl, timeout=timeout,
+                                 allow_execution=True)
+
+
+async def continue_prepared_execution(
+    kernel: NativeKernel, snapshot: RunSnapshot, original: RunSnapshot
+) -> RunSnapshot:
+    if not _prepared(kernel, snapshot, original, allow_execution=True):
+        return snapshot
+    # The ordinary Kernel still owns admission, remaining budgets, commands,
+    # receipts and verification. No host executor restarts unknown effects.
+    return await kernel.run_until_idle(snapshot.run_id)
+
+
+async def finish_prepared_verification(
+    kernel: NativeKernel, snapshot: RunSnapshot, original: RunSnapshot
+) -> RunSnapshot:
+    if not _prepared(kernel, snapshot, original):
+        return snapshot
+    snapshot = await kernel.advance(snapshot.run_id)
+    # A failed verifier can schedule repair. That is outside this recovery grant.
+    # Finalization is a local commit; a new model/tool/verification is forbidden.
+    if snapshot.phase == RunPhase.FINALIZING and not snapshot.pending_intent:
+        snapshot = await kernel.advance(snapshot.run_id)
+    return snapshot

ksadk/harness/tool_display.py

@@ -0,0 +1,75 @@
+"""Host tool output disclosure and pure display contract compatibility exports."""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePosixPath
+from typing import Any
+
+from .tool_display_contract import (
+    ToolDisplay as ToolDisplay,
+)
+from .tool_display_contract import (
+    display_text,
+    safe_tool_display,
+    tool_display_start,
+)
+
+
+def tool_display_output(
+    start: dict[str, Any], *, output: Any = None, diff: Any = None, exit_code: Any = None
+) -> dict[str, Any]:
+    """For trusted host adapters only, after their disclosure/policy decision."""
+    value = dict(start)
+    total = max(
+        len(output) if isinstance(output, str) else 0, len(diff) if isinstance(diff, str) else 0
+    )
+    for key, raw in (("output", output), ("diff", diff)):
+        if isinstance(raw, str):
+            value[key] = display_text(raw)
+    value.update(truncated=total > 16384, total_chars=total)
+    if type(exit_code) is int:
+        value["exit_code"] = exit_code
+    return safe_tool_display(value) or {}
+
+
+def builtin_tool_display(name: str, args: Any, result: Any) -> dict[str, Any]:
+    """Explicit SDK host disclosure allowlist. Never call for custom/MCP tools."""
+    start = tool_display_start(name, args)
+    if not isinstance(result, dict):
+        return start
+    category = start["category"]
+    output = diff = None
+    if category == "terminal":
+        output = "\n".join(
+            result[key] for key in ("stdout", "stderr") if isinstance(result.get(key), str)
+        )
+    elif category == "read" and start.get("path"):
+        output = result.get("content")
+    elif category == "edit" and start.get("path") and result.get("ok") is True:
+        diff = result.get("diff")
+    elif category == "search" and isinstance(result.get("results"), list):
+        # Only file location/line text, never arbitrary search result objects.
+        lines = []
+        for item in result["results"][:100]:
+            if isinstance(item, dict):
+                path = PurePosixPath(str(item.get("path") or "")).name
+                if not re.search(r"(?i)(?:\.env|credential|secret|token|password)", path):
+                    lines.append(f"{path}:{item.get('line', '')} {item.get('text', '')}")
+        output = "\n".join(lines)
+    display = tool_display_output(
+        start, output=output, diff=diff, exit_code=result.get("exit_code")
+    )
+    if result.get("truncated") is True or result.get("diff_truncated") is True:
+        display["truncated"] = True
+    retained = diff if isinstance(diff, str) else output
+    if isinstance(retained, str) and len(retained) > 16384:
+        from .public_output import retain_public_output
+
+        identity = retain_public_output(
+            retained, incomplete=(result.get("truncated") is True
+                                  or result.get("diff_truncated") is True),
+        )
+        if identity:
+            display["artifact_id"] = identity
+    return display

ksadk/harness/tool_display_contract.py

@@ -0,0 +1,134 @@
+"""Versioned, bounded public tool presentation, independent of raw receipts.
+
+Arguments and results remain redacted in canonical tool items. Hosts explicitly
+opt into publishing output; a tool-returned JSON key cannot grant disclosure.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import PurePosixPath
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .public_activity import public_commentary_text, tool_public_action
+
+
+class ToolDisplay(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    version: Literal["tool-display/v1"] = "tool-display/v1"
+    category: Literal["terminal", "read", "search", "edit", "todo", "tool"] = "tool"
+    summary: str = Field(default="", max_length=280)
+    path: str | None = Field(default=None, max_length=180)
+    output: str | None = Field(default=None, max_length=16384)
+    diff: str | None = Field(default=None, max_length=16384)
+    truncated: bool = False
+    total_chars: int | None = Field(default=None, ge=0)
+    exit_code: int | None = None
+    # Opaque host-owned identity, resolved only through a run-scoped API.
+    artifact_id: str | None = Field(default=None, max_length=180)
+    todos: list[dict[str, str]] | None = Field(default=None, max_length=64)
+
+
+_CATEGORIES = {
+    **dict.fromkeys(
+        (
+            "exec_command",
+            "run_command",
+            "execute_command",
+            "run_workspace_command",
+            "sandbox_run_command",
+            "codex.command",
+        ),
+        "terminal",
+    ),
+    **dict.fromkeys(
+        ("read_file", "read_workspace_file", "list_workspace_files", "sandbox_read_file"), "read"
+    ),
+    **dict.fromkeys(
+        ("web_search", "search_workspace_files", "search_knowledge", "knowledge_search"), "search"
+    ),
+    **dict.fromkeys(
+        ("write_workspace_file", "edit_workspace_file", "multi_edit_workspace_file", "apply_patch"),
+        "edit",
+    ),
+    "TodoWrite": "todo",
+}
+_SECRET = re.compile(
+    r"(?i)(?:\b(?:api[_ -]?key|secret|password|passwd|authorization|access[_ -]?token|"
+    r"refresh[_ -]?token|token|private[_ -]?key)\b\s*[:=]\s*[^\n]+|"
+    r"\bbearer\s+\S+|\bsk-[a-z0-9_-]{12,})"
+)
+_ANSI = re.compile(r"\x1b(?:\][^\x07]*(?:\x07|\x1b\\)|\[[0-?]*[ -/]*[@-~])")
+
+
+def display_text(value: Any, limit: int = 16384) -> str:
+    if not isinstance(value, str):
+        return ""
+    value = _ANSI.sub("", value)
+    value = _SECRET.sub("[redacted]", value)
+    value = re.sub(r"https?://[^\s/]*@[^\s]+", "[redacted URL]", value)
+    value = re.sub(
+        r"-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|\Z)",
+        "[redacted key]",
+        value,
+    )
+    # Keep tabs/newlines, never terminal control sequences or bidi overrides.
+    value = re.sub(r"[\x00-\x08\x0b-\x1f\x7f\u202a-\u202e\u2066-\u2069]", "", value)
+    return value[:limit]
+
+
+def safe_tool_display(value: Any) -> dict[str, Any] | None:
+    """Revalidate at every public boundary; unknown versions fail closed."""
+    try:
+        display = ToolDisplay.model_validate(value)
+    except (ValueError, TypeError):
+        return None
+    result = display.model_dump(exclude_none=True)
+    for key in ("summary", "path", "output", "diff", "artifact_id"):
+        if key in result:
+            result[key] = display_text(result[key])
+    if display.todos is not None:
+        result["todos"] = []
+        seen = set()
+        for item in display.todos:
+            content = public_commentary_text(item.get("content"), limit=500)
+            state = item.get("status")
+            if not content or state not in {"pending", "in_progress", "completed"}:
+                continue
+            # Legacy model plans lack IDs. The public identity survives reorder
+            # and status updates; edited text intentionally becomes a new item.
+            identity = (
+                item.get("id") or hashlib.sha256(content.casefold().encode()).hexdigest()[:20]
+            )
+            if identity in seen:
+                continue
+            seen.add(identity)
+            result["todos"].append(
+                {
+                    "id": display_text(identity, 180),
+                    "content": content,
+                    "status": state,
+                    "priority": item.get("priority", "medium"),
+                }
+            )
+    return result
+
+
+def tool_display_start(name: str, args: Any) -> dict[str, Any]:
+    args = args if isinstance(args, dict) else {}
+    action = tool_public_action({"name": name, "args": args}) or {}
+    display = ToolDisplay(category=_CATEGORIES.get(name, "tool"), summary=action.get("text", ""))
+    if display.category in {"read", "edit"}:
+        raw_path = str(args.get("path") or "").replace("\\", "/")
+        target = PurePosixPath(raw_path).name
+        if target and not re.search(
+            r"(?i)(?:\.env|credential|secret|token|password|id_rsa|\.ssh|\.aws|kubeconfig|\.pypirc)",
+            raw_path,
+        ):
+            display.path = display_text(target, 180)
+    if name == "TodoWrite" and isinstance(args.get("todos"), (list, tuple)):
+        display.todos = [item for item in args["todos"][:64] if isinstance(item, dict)]
+    return safe_tool_display(display.model_dump()) or ToolDisplay().model_dump(exclude_none=True)

ksadk/harness/tool_output.py

@@ -0,0 +1,141 @@
+"""Optional host output observation, separate from tool execution authority.
+
+All ToolPort.execute wrappers inherit the observation context. A host may
+publish stdout/stderr after its existing admission checks; observers cannot
+approve, retry, complete or cancel tools. Raw chunks never enter UI events.
+"""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from threading import RLock
+from time import monotonic
+from typing import Literal
+
+from .tool_display import display_text, tool_display_output, tool_display_start
+
+OutputObserver = Callable[[str, str], None]
+_OBSERVER: ContextVar[OutputObserver | None] = ContextVar("ksadk_public_tool_output", default=None)
+
+
+@contextmanager
+def tool_output_scope(observer: OutputObserver) -> Iterator[None]:
+    token = _OBSERVER.set(observer)
+    try:
+        yield
+    finally:
+        _OBSERVER.reset(token)
+
+
+def current_tool_output_observer() -> OutputObserver | None:
+    return _OBSERVER.get()
+
+
+def publish_tool_output(channel: str, text: str) -> None:
+    observer = _OBSERVER.get()
+    if observer is not None and channel in {"stdout", "stderr"} and isinstance(text, str):
+        try:
+            observer(channel, text)
+        except Exception:
+            # Presentation must never change execution/receipt outcomes.
+            pass
+
+
+@dataclass(frozen=True)
+class ToolOutputObservation:
+    kind: Literal["tool_output"]
+    operation_key: str
+    call_id: str
+    display: dict
+
+
+class PublicOutputBuffer:
+    """Publish bounded complete lines so secrets split across chunks stay private."""
+
+    def __init__(self, name: str, args: dict, emit: Callable[[dict], None]):
+        self.start = tool_display_start(name, args)
+        self.emit = emit
+        self.pending = {"stdout": "", "stderr": ""}
+        self.visible = ""
+        self.total_chars = 0
+        self.truncated = False
+        self.lock = RLock()
+        self.last_publish = 0.0
+        self.published_chars = 0
+        self.publications = 0
+        self.closed = False
+        self.private_key = {"stdout": False, "stderr": False}
+
+    def observe(self, channel: str, text: str) -> None:
+        with self.lock:
+            self._observe(channel, text)
+
+    def _observe(self, channel: str, text: str) -> None:
+        if self.closed or channel not in self.pending or not isinstance(text, str):
+            return
+        self.total_chars += len(text)
+        if self.total_chars > 32768:
+            self.truncated = True
+        # Buffer each unfinished line separately; a credential may span chunks.
+        self.pending[channel] = (self.pending[channel] + text)[:32768]
+        lines = self.pending[channel].splitlines(keepends=True)
+        self.pending[channel] = ""
+        for line in lines:
+            if line.endswith(("\n", "\r")):
+                self._line(channel, line)
+            else:
+                self.pending[channel] = line
+        self._publish()
+
+    def _line(self, channel: str, line: str) -> None:
+        if "-----BEGIN " in line and "PRIVATE KEY-----" in line:
+            self.private_key[channel] = True
+            line = "[redacted key]\n"
+        elif self.private_key[channel]:
+            if "-----END " in line and "PRIVATE KEY-----" in line:
+                self.private_key[channel] = False
+            return
+        if len(self.visible) >= 16384:
+            self.truncated = True
+            return
+        clean = display_text(line, 32768)
+        remaining = 16384 - len(self.visible)
+        if len(clean) > remaining:
+            self.truncated = True
+        self.visible += clean[:remaining]
+
+    def _publish(self, *, final: bool = False) -> None:
+        now = monotonic()
+        if not self.visible and not self.truncated:
+            return
+        if not final and (
+            self.publications >= 63
+            or (
+                self.publications
+                and now - self.last_publish < 0.2
+                and len(self.visible) - self.published_chars < 1024
+            )
+        ):
+            return
+        display = tool_display_output(self.start, output=self.visible)
+        display.update(truncated=self.truncated, total_chars=self.total_chars)
+        self.last_publish = now
+        self.published_chars = len(self.visible)
+        self.publications += 1
+        try:
+            self.emit(display)
+        except Exception:
+            # Observation failure cannot replace a tool result or cancellation.
+            pass
+
+    def finish(self) -> None:
+        with self.lock:
+            if self.closed:
+                return
+            self.closed = True
+            for channel in self.pending:
+                if self.pending[channel]:
+                    self._line(channel, self.pending[channel])
+                    self.pending[channel] = ""
+            self._publish(final=True)

ksadk/harness/tool_policy.py

@@ -0,0 +1,134 @@
+"""Harness Tool Policy 决策（plan §11.1）。
+
+确定性决策表（无模型调用）：
+
+- CRITICAL 风险或外部副作用 + 高敏数据 → require_approval；
+- 策略显式 deny（如目的地不在允许清单）→ deny；
+- 其余 → allow。
+
+决策输入覆盖 plan 要求的最小集：tenant/user/agent、tool+版本、参数摘要、
+敏感等级、外部副作用、网络目的地、环境、Revision Policy、历史 Receipt。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ksadk.harness.capabilities import RiskLevel
+
+#: 风险等级序（str-Enum 不可比较，用显式序号）。
+_RISK_ORDER = {
+    RiskLevel.LOW: 0,
+    RiskLevel.MEDIUM: 1,
+    RiskLevel.HIGH: 2,
+    RiskLevel.CRITICAL: 3,
+}
+#: 审批阈值（含）：该风险等级及以上需要审批。
+_APPROVAL_RISK = 2  # HIGH
+#: 拒绝阈值（含）：该风险等级及以上在正式环境需审批。
+_DENY_RISK = 3  # CRITICAL
+
+
+@dataclass(frozen=True)
+class ToolCallContext:
+    """一次 Tool 调用的决策输入。"""
+
+    tenant_id: str
+    user_id: str
+    agent_id: str
+    tool_name: str
+    tool_version: str = "1.0.0"
+    risk_level: RiskLevel = RiskLevel.LOW
+    has_external_side_effects: bool = False
+    data_sensitivity: str = "internal"  # public/internal/confidential/restricted
+    network_destination: str = ""
+    environment: str = "draft"  # draft / revision
+    #: Revision Policy 侧白名单：为空表示不限制目的地。
+    allowed_destinations: tuple[str, ...] = ()
+    #: 历史 Receipt：此前是否已成功执行同一 call（幂等去重）。
+    prior_receipt_id: str = ""
+
+
+@dataclass(frozen=True)
+class ToolDecision:
+    action: str  # allow / deny / require_approval
+    reason: str
+    policy_ref: str
+    risk_level: RiskLevel
+    disclosure: str = ""
+    # G23 审批治理：审计维度（§9 开放问题 7：合同先落，UI 后置）。
+    # user_permanent/user_temporary/user_reject/user_abort/hook/classifier/config/policy/immune
+    decided_by: str = "classifier"
+
+
+@dataclass
+class ToolPolicy:
+    """Revision 级工具策略（宿主从 HarnessSpec.tool_policy 投影）。"""
+
+    policy_ref: str = "tool-policy://default@1"
+    #: 强制审批的工具名前缀（如高危财务工具）。
+    approval_required_prefixes: tuple[str, ...] = field(default=())
+    #: 明确拒绝的工具名前缀。
+    denied_prefixes: tuple[str, ...] = field(default=())
+    #: 允许的网络目的地（空 = 不限制）。
+    allowed_destinations: tuple[str, ...] = field(default=())
+    #: 环境限制：正式环境默认更严。
+    strict_in_revision: bool = True
+
+    def decide(self, context: ToolCallContext) -> ToolDecision:
+        if any(context.tool_name.startswith(p) for p in self.denied_prefixes):
+            return ToolDecision(
+                action="deny",
+                reason=f"tool {context.tool_name} is denied by revision policy",
+                policy_ref=self.policy_ref,
+                risk_level=context.risk_level,
+                disclosure="Revision Policy 明确拒绝该工具",
+            )
+        if self.allowed_destinations and context.network_destination:
+            if context.network_destination not in self.allowed_destinations:
+                return ToolDecision(
+                    action="deny",
+                    reason=(
+                        f"network destination {context.network_destination!r} "
+                        f"not in allowlist {list(self.allowed_destinations)}"
+                    ),
+                    policy_ref=self.policy_ref,
+                    risk_level=context.risk_level,
+                    disclosure="网络目的地不在允许清单",
+                )
+        if _RISK_ORDER[context.risk_level] >= _DENY_RISK and context.environment == "revision":
+            if not context.prior_receipt_id:
+                return ToolDecision(
+                    action="require_approval",
+                    reason="critical risk in revision environment requires approval",
+                    policy_ref=self.policy_ref,
+                    risk_level=context.risk_level,
+                    disclosure="Critical 风险工具在正式环境需审批",
+                )
+        needs_approval = (
+            _RISK_ORDER[context.risk_level] >= _APPROVAL_RISK
+            or context.has_external_side_effects
+            or context.data_sensitivity in {"confidential", "restricted"}
+            or any(context.tool_name.startswith(p) for p in self.approval_required_prefixes)
+        )
+        if needs_approval and not context.prior_receipt_id:
+            return ToolDecision(
+                action="require_approval",
+                reason=(
+                    f"risk={context.risk_level.value}, "
+                    f"side_effects={context.has_external_side_effects}, "
+                    f"sensitivity={context.data_sensitivity}"
+                ),
+                policy_ref=self.policy_ref,
+                risk_level=context.risk_level,
+                disclosure="高风险/外部副作用/敏感数据工具需审批",
+            )
+        return ToolDecision(
+            action="allow",
+            reason="within policy",
+            policy_ref=self.policy_ref,
+            risk_level=context.risk_level,
+        )
+
+
+__all__ = ["ToolCallContext", "ToolDecision", "ToolPolicy"]