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

ksadk/harness/capabilities.py

@@ -0,0 +1,115 @@
+"""统一 Capability Registry 描述符（plan §10.1）。
+
+Contract 只落描述符与注册表数据结构；发现/加载/降级在 admission boundary 落地。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ksadk.harness.resource_ref import validate_resource_ref
+
+
+class CapabilityKind(str, Enum):
+    MCP = "mcp"
+    SKILL = "skill"
+    BUILTIN = "builtin"
+    SANDBOX = "sandbox"
+
+
+class LoadPolicy(str, Enum):
+    ALWAYS = "always"
+    ON_DEMAND = "on_demand"
+    EXPLICIT = "explicit"
+
+
+class RiskLevel(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class CapabilityDescriptor(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: str = Field(min_length=1, max_length=512)
+    kind: CapabilityKind
+    name: str = Field(min_length=1, max_length=256)
+    description: str = Field(default="", max_length=8192)
+    version: str = Field(min_length=1, max_length=64)
+    risk_level: RiskLevel = RiskLevel.MEDIUM
+    load_policy: LoadPolicy = LoadPolicy.ALWAYS
+    dependencies: tuple[str, ...] = Field(default=(), max_length=32)
+
+    @model_validator(mode="after")
+    def validate_refs(self) -> "CapabilityDescriptor":
+        validate_resource_ref(self.id)
+        for dep in self.dependencies:
+            validate_resource_ref(dep)
+        return self
+
+
+class CapabilityRegistryError(ValueError):
+    """注册/解析冲突（重复 id、悬空依赖）。"""
+
+
+class CapabilityRegistry:
+    """进程内注册表：id 唯一，依赖必须已注册（拓扑可解析）。"""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, CapabilityDescriptor] = {}
+
+    def register(self, descriptor: CapabilityDescriptor) -> None:
+        if descriptor.id in self._entries:
+            raise CapabilityRegistryError(f"capability 重复注册: {descriptor.id}")
+        missing = [d for d in descriptor.dependencies if d not in self._entries]
+        if missing:
+            raise CapabilityRegistryError(
+                f"capability {descriptor.id} 依赖未注册: {sorted(missing)}"
+            )
+        self._entries[descriptor.id] = descriptor
+
+    def get(self, capability_id: str) -> CapabilityDescriptor:
+        try:
+            return self._entries[capability_id]
+        except KeyError:
+            raise CapabilityRegistryError(f"unknown capability: {capability_id}") from None
+
+    def resolve_order(self, capability_ids: list[str]) -> list[CapabilityDescriptor]:
+        """按依赖拓扑排序（稳定：同层保持声明顺序）。"""
+        resolved: list[CapabilityDescriptor] = []
+        seen: set[str] = set()
+        visiting: set[str] = set()
+
+        def visit(cid: str) -> None:
+            if cid in seen:
+                return
+            if cid in visiting:
+                raise CapabilityRegistryError(f"capability 依赖成环: {cid}")
+            visiting.add(cid)
+            for dep in self.get(cid).dependencies:
+                visit(dep)
+            visiting.discard(cid)
+            seen.add(cid)
+            resolved.append(self.get(cid))
+
+        for capability_id in capability_ids:
+            visit(capability_id)
+        return resolved
+
+    def describe(self) -> list[dict[str, Any]]:
+        return [d.model_dump(mode="json") for d in self._entries.values()]
+
+
+__all__ = [
+    "CapabilityDescriptor",
+    "CapabilityKind",
+    "CapabilityRegistry",
+    "CapabilityRegistryError",
+    "LoadPolicy",
+    "RiskLevel",
+]

ksadk/harness/capability_runtime.py

@@ -0,0 +1,237 @@
+"""统一 CapabilityRuntime（plan §10/§11 收口 2）。
+
+把 ToolPolicy、ToolReceipt、Approval、Sandbox 装配到同一个执行节点入口：
+tool_calls 节点对每次调用统一走「幂等检查 → 策略决策 → 审批 → 执行 → Receipt
+落账」，MCP/Skill 工具经 ToolExecutor 注入（宿主负责装配数据面），Sandbox
+Backend 作为能力面由宿主声明并可在 ToolExecutor 内使用。
+
+职责边界：
+- 本模块只做决策与幂等（纯逻辑 + 可选 SQLite Receipt 存储），不做 IO 副作用；
+- 「如何挂起等审批」仍由引擎的 ApprovalResolver 承担（LangGraph interrupt）；
+- Receipt 以 (invocation_id, call_id) 为幂等键：审批恢复重放节点时直接回放
+  既有结果，不重复触发外部副作用（plan §11.2）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ksadk.harness.capabilities import RiskLevel
+from ksadk.harness.tool_policy import ToolCallContext, ToolDecision, ToolPolicy
+from ksadk.harness.tool_receipts import ToolReceipt, ToolReceiptStore
+from ksadk.harness.tool_reliability import ToolReliability, classify_tool_reliability
+
+#: side_effect（Studio ToolContract）→ 是否存在外部副作用。
+_SIDE_EFFECT_EXTERNAL = frozenset({"write", "external"})
+
+
+def arguments_digest(arguments: dict[str, Any]) -> str:
+    payload = json.dumps(arguments or {}, ensure_ascii=False, sort_keys=True)
+    return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _risk_from_side_effect(side_effect: str) -> RiskLevel:
+    if side_effect == "external":
+        return RiskLevel.HIGH
+    if side_effect == "write":
+        return RiskLevel.MEDIUM
+    return RiskLevel.LOW
+
+
+@dataclass
+class ToolProfile:
+    """宿主注册的工具画像（来自 ToolContract / MCP 声明）。"""
+
+    name: str
+    version: str = "1.0.0"
+    risk_level: RiskLevel = RiskLevel.LOW
+    side_effect: str = "none"
+    data_sensitivity: str = "internal"
+    network_destination: str = ""
+
+
+class CapabilityRuntime:
+    """tool_calls 节点的统一决策/幂等入口。
+
+    - ``decide``：ToolPolicy 确定性决策（allow / deny / require_approval）；
+    - ``check_receipt`` / ``record_receipt``：审批恢复重放的幂等锚点；
+    - 宿主未注入 Policy/Receipt 时自动退化为「全部放行」（调试语义）。
+    """
+
+    def __init__(
+        self,
+        *,
+        policy: ToolPolicy | None = None,
+        receipts: ToolReceiptStore | None = None,
+        profiles: dict[str, ToolProfile] | None = None,
+        environment: str = "draft",
+        approval_mode: str = "policy",
+    ) -> None:
+        self._policy = policy or ToolPolicy()
+        self._receipts = receipts
+        self._profiles = dict(profiles or {})
+        self._environment = environment
+        self._approval_mode = approval_mode
+
+    # -------------------------------------------------------------- policy
+
+    def register_profile(self, profile: ToolProfile) -> None:
+        self._profiles[profile.name] = profile
+
+    @property
+    def receipt_enabled(self) -> bool:
+        """当前执行入口是否装配 Receipt Store。"""
+        return self._receipts is not None
+
+    def reliability(
+        self,
+        tool_name: str,
+        *,
+        side_effect: str | None = None,
+        transport_idempotent: bool = False,
+    ) -> ToolReliability:
+        """返回 Tool 的诚实可靠性声明。
+
+        ``side_effect`` 允许 MCP/子 Agent 等动态工具按实际目标覆盖静态画像；
+        未注册工具保持 ``unknown``，不会被误标为无副作用。
+        """
+        profile = self._profiles.get(tool_name)
+        resolved_side_effect = side_effect or (profile.side_effect if profile else "unknown")
+        return classify_tool_reliability(
+            side_effect=resolved_side_effect,
+            receipt_enabled=self.receipt_enabled,
+            transport_idempotent=transport_idempotent,
+        )
+
+    def decide(
+        self,
+        *,
+        tenant_id: str,
+        user_id: str,
+        agent_id: str,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> ToolDecision:
+        profile = self._profiles.get(tool_name)
+        if self._approval_mode == "never":
+            return ToolDecision(
+                action="allow",
+                reason="approval_policy.mode=never",
+                policy_ref=self._policy.policy_ref,
+                risk_level=profile.risk_level if profile else RiskLevel.LOW,
+            )
+        prior = self.check_receipt_idempotency_only(tenant_id, tool_name)
+        return self._policy.decide(
+            ToolCallContext(
+                tenant_id=tenant_id,
+                user_id=user_id,
+                agent_id=agent_id,
+                tool_name=tool_name,
+                tool_version=profile.version if profile else "1.0.0",
+                risk_level=profile.risk_level if profile else RiskLevel.LOW,
+                has_external_side_effects=(
+                    profile.side_effect in _SIDE_EFFECT_EXTERNAL if profile else False
+                ),
+                data_sensitivity=profile.data_sensitivity if profile else "internal",
+                network_destination=profile.network_destination if profile else "",
+                environment=self._environment,
+                prior_receipt_id=prior or "",
+            )
+        )
+
+    # ------------------------------------------------------------- receipts
+
+    def check_receipt(self, invocation_id: str, call_id: str) -> ToolReceipt | None:
+        if self._receipts is None:
+            return None
+        return self._receipts.get(invocation_id, call_id)
+
+    def check_receipt_idempotency_only(self, tenant_id: str, tool_name: str) -> str:
+        """策略决策用的历史 Receipt 存在性（键退化：tenant+tool）。"""
+        del tenant_id, tool_name
+        return ""
+
+    def record_receipt(
+        self,
+        *,
+        invocation_id: str,
+        call_id: str,
+        tool_name: str,
+        arguments: dict[str, Any],
+        decision: str,
+        status: str,
+        result_digest: str = "",
+    ) -> ToolReceipt | None:
+        if self._receipts is None:
+            return None
+        return self._receipts.record(
+            ToolReceipt(
+                invocation_id=invocation_id,
+                call_id=call_id,
+                tool_name=tool_name,
+                arguments_digest=arguments_digest(arguments or {}),
+                decision=decision,
+                status=status,
+                result_digest=result_digest,
+            )
+        )
+
+    # ------------------------------------------------------------ factories
+
+    @staticmethod
+    def from_tool_contracts(
+        contracts: list[dict[str, Any]] | None,
+        *,
+        approval_mode: str = "policy",
+        policy: ToolPolicy | None = None,
+        receipts: ToolReceiptStore | None = None,
+        environment: str = "draft",
+    ) -> CapabilityRuntime:
+        """从 Studio ToolContract 列表装配（risk 来自 side_effect/approval 声明）。
+
+        approval_mode 为 never 时不强制任何审批；always 时全部进审批
+        （经 approval_required_prefixes 全前缀匹配实现）。
+        """
+        profiles: dict[str, ToolProfile] = {}
+        approval_prefixes: list[str] = []
+        for contract in contracts or []:
+            if not isinstance(contract, dict) or not contract.get("name"):
+                continue
+            name = str(contract["name"])
+            side_effect = str(contract.get("sideEffect") or contract.get("side_effect") or "none")
+            approval = str(contract.get("approval") or "never")
+            risk = _risk_from_side_effect(side_effect)
+            if approval == "always":
+                risk = RiskLevel.HIGH
+            profiles[name] = ToolProfile(
+                name=name,
+                version=str(contract.get("version") or "1.0.0"),
+                risk_level=risk,
+                side_effect=side_effect,
+            )
+            if approval == "always" or (approval == "policy" and risk is RiskLevel.HIGH):
+                approval_prefixes.append(name)
+        resolved_policy = policy or ToolPolicy(
+            approval_required_prefixes=tuple(approval_prefixes),
+        )
+        if approval_mode == "always":
+            resolved_policy = ToolPolicy(approval_required_prefixes=("",))
+        elif approval_mode == "never":
+            resolved_policy = ToolPolicy()
+        return CapabilityRuntime(
+            policy=resolved_policy,
+            receipts=receipts,
+            profiles=profiles,
+            environment=environment,
+            approval_mode=approval_mode,
+        )
+
+
+__all__ = [
+    "CapabilityRuntime",
+    "ToolProfile",
+    "arguments_digest",
+]

ksadk/harness/closure_contract.py

@@ -0,0 +1,92 @@
+"""Stable contracts used to close and verify Harness runtime capabilities.
+
+The models intentionally carry metadata only.  Raw provider errors, tool results,
+credentials, and other sensitive payloads do not belong in closure reports.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class RunTerminalStatus(str, Enum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    AWAITING_APPROVAL = "awaiting_approval"
+    INTERRUPTED = "interrupted"
+
+    @classmethod
+    def normalize(cls, value: str | "RunTerminalStatus") -> "RunTerminalStatus":
+        if isinstance(value, cls):
+            return value
+        if value == "canceled":
+            value = cls.CANCELLED.value
+        return cls(value)
+
+
+class ReadinessStatus(str, Enum):
+    READY = "ready"
+    WARNING = "warning"
+    BLOCKED = "blocked"
+    NOT_CONFIGURED = "not_configured"
+
+
+class FailureCategory(BaseModel):
+    """Policy-safe failure identity; human error text remains in a redacted cause."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    domain: str = Field(min_length=1, max_length=64, pattern=r"^[a-z][a-z0-9_-]*$")
+    code: str = Field(min_length=1, max_length=128, pattern=r"^[a-z][a-z0-9_-]*$")
+    retryable: bool = False
+
+
+class ReadinessCheck(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True, populate_by_name=True)
+
+    check_id: str = Field(alias="id", min_length=1, max_length=256)
+    category: str = Field(min_length=1, max_length=64)
+    status: ReadinessStatus
+    required: bool = True
+    reason_code: str = Field(min_length=1, max_length=128)
+
+
+class HarnessClosureReport(BaseModel):
+    """Versioned machine-readable closure result shared by SDK and CI.
+
+    ``extra='ignore'`` is the additive compatibility rule: readers of schema v1
+    accept metadata appended by a newer v1 writer without treating it as proof.
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True, populate_by_name=True)
+
+    schema_version: int = Field(default=1, alias="schemaVersion", ge=1)
+    target: str = Field(min_length=1, max_length=256)
+    status: ReadinessStatus
+    checks: tuple[ReadinessCheck, ...] = ()
+    counts: dict[str, int] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def populate_counts(cls, value: Any) -> Any:
+        if not isinstance(value, dict) or value.get("counts") is not None:
+            return value
+        checks = value.get("checks") or ()
+        counts = {status.value: 0 for status in ReadinessStatus}
+        for check in checks:
+            raw = check.status if isinstance(check, ReadinessCheck) else check.get("status")
+            counts[ReadinessStatus(raw).value] += 1
+        return {**value, "counts": counts}
+
+
+__all__ = [
+    "FailureCategory",
+    "HarnessClosureReport",
+    "ReadinessCheck",
+    "ReadinessStatus",
+    "RunTerminalStatus",
+]

ksadk/harness/compaction_record.py

@@ -0,0 +1,122 @@
+"""CompactionRecord（长任务 Context 与 Memory 增强方案 §6.4）。
+
+压缩的**投影变化记录**，不是新的聊天事实源（完整 Transcript 不删除）。
+相比 ``ContextCheckpoint``（引擎内部的压缩检查点），CompactionRecord 面向
+平台观测：补齐压缩前后 Token、事件范围、摘要模型引用和质量校验字段。
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _compaction_id(material: str) -> str:
+    return f"cmp_{hashlib.sha256(material.encode('utf-8')).hexdigest()[:12]}"
+
+
+@dataclass(frozen=True)
+class CompactionRecord:
+    """一次上下文压缩的完整记录（可持久化、可审计）。"""
+
+    compaction_id: str
+    run_id: str
+    trigger: str
+    before_tokens: int
+    after_tokens: int
+    #: 被压缩的 seq 区间（闭开）。
+    compacted_event_range: tuple[int, int]
+    preserved_event_ids: tuple[str, ...] = field(default=())
+    summary: str = ""
+    #: 摘要正文作为 Artifact 保存后的引用（artifact://...）。
+    summary_artifact_ref: str = ""
+    #: 压缩前受控 Memory Flush 提交的候选引用（mem://...）。
+    memory_candidate_refs: tuple[str, ...] = field(default=())
+    #: 生成摘要的模型引用（本地截断降级时为空）。
+    summary_model_ref: str = ""
+    retained_critical_facts: tuple[str, ...] = field(default=())
+    dropped_critical_facts: tuple[str, ...] = field(default=())
+    #: 摘要缺失但经重注入保留在模型输入中的关键事实（§8.4.1）。
+    reinjected_critical_facts: tuple[str, ...] = field(default=())
+
+    # ---- 质量校验（§6.4 quality_checks） ----
+    tool_pairs_complete: bool = True
+    approvals_preserved: bool = True
+    goal_preserved: bool = True
+    critical_facts_preserved: bool = True
+
+    def quality_checks(self) -> dict[str, bool]:
+        return {
+            "tool_pairs_complete": self.tool_pairs_complete,
+            "approvals_preserved": self.approvals_preserved,
+            "goal_preserved": self.goal_preserved,
+            "critical_facts_preserved": self.critical_facts_preserved,
+        }
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "compaction_id": self.compaction_id,
+            "run_id": self.run_id,
+            "trigger": self.trigger,
+            "before_tokens": self.before_tokens,
+            "after_tokens": self.after_tokens,
+            "compacted_event_range": list(self.compacted_event_range),
+            "preserved_event_ids": list(self.preserved_event_ids),
+            "summary_artifact_ref": self.summary_artifact_ref,
+            "memory_candidate_refs": list(self.memory_candidate_refs),
+            "summary_model_ref": self.summary_model_ref,
+            "retained_critical_facts": list(self.retained_critical_facts),
+            "dropped_critical_facts": list(self.dropped_critical_facts),
+            "reinjected_critical_facts": list(self.reinjected_critical_facts),
+            "quality_checks": self.quality_checks(),
+        }
+
+
+def build_compaction_record(
+    *,
+    run_id: str,
+    trigger: str,
+    before_tokens: int,
+    after_tokens: int,
+    compacted_event_range: tuple[int, int],
+    summary: str,
+    retained_critical_facts: tuple[str, ...],
+    dropped_critical_facts: tuple[str, ...],
+    reinjected_critical_facts: tuple[str, ...] = (),
+    summary_model_ref: str = "",
+    memory_candidate_refs: tuple[str, ...] = (),
+    tool_pairs_complete: bool = True,
+    approvals_preserved: bool = True,
+    goal_preserved: bool = True,
+) -> CompactionRecord:
+    """从压缩结果构建完整记录。
+
+    ``critical_facts_preserved`` 按「重注入后仍丢弃」判定（方案 §6.4
+    "不静默丢弃"）：摘要缺失的事实经重注入（§8.4.1）保留在模型输入中，
+    不算最终丢弃——真实模型评测曾因此误报 constraint_retention<1.0。
+    """
+    still_dropped = set(dropped_critical_facts) - set(reinjected_critical_facts)
+    critical_ok = not still_dropped
+    material = f"{run_id}:{trigger}:{before_tokens}:{compacted_event_range}:{summary[:64]}"
+    return CompactionRecord(
+        compaction_id=_compaction_id(material),
+        run_id=run_id,
+        trigger=trigger,
+        before_tokens=before_tokens,
+        after_tokens=after_tokens,
+        compacted_event_range=compacted_event_range,
+        summary=summary,
+        summary_model_ref=summary_model_ref,
+        memory_candidate_refs=memory_candidate_refs,
+        retained_critical_facts=retained_critical_facts,
+        dropped_critical_facts=dropped_critical_facts,
+        reinjected_critical_facts=reinjected_critical_facts,
+        tool_pairs_complete=tool_pairs_complete,
+        approvals_preserved=approvals_preserved,
+        goal_preserved=goal_preserved,
+        critical_facts_preserved=critical_ok,
+    )
+
+
+__all__ = ["CompactionRecord", "build_compaction_record"]