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

ksadk/harness/artifact_store.py

@@ -0,0 +1,213 @@
+"""Harness Artifact Store（缺口 5 / plan §6.2 大结果外置）。
+
+工具产出的大结果（报表、文件、生成物）落工作区磁盘，State/事件流只带
+引用（``artifact.created`` payload 的 ``uri``）。同一 ``(run, name)`` 重复
+保存递增 ``version``，历史版本保留可下载。
+
+存储形态：内容文件 ``{root}/{run_id}/{name}.v{version}`` + SQLite 索引
+（run_id / name / version / mime / content_hash / bytes / created_at）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ArtifactRecord:
+    run_id: str
+    name: str
+    version: int
+    mime: str
+    content_hash: str
+    bytes: int
+    uri: str
+    created_at: str
+
+
+class ArtifactStore:
+    """Run 作用域 Artifact 持久化（线程安全由 SQLite 连接锁保证）。"""
+
+    def __init__(self, root: str | Path, db_path: str | Path | None = None) -> None:
+        self._root = Path(root)
+        self._root.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(str(db_path or self._root / "artifacts.sqlite3"))
+        self._db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS artifacts (
+                run_id TEXT NOT NULL,
+                name TEXT NOT NULL,
+                version INTEGER NOT NULL,
+                mime TEXT NOT NULL DEFAULT "text/plain",
+                content_hash TEXT NOT NULL,
+                bytes INTEGER NOT NULL,
+                uri TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                PRIMARY KEY (run_id, name, version)
+            )
+            """
+        )
+        self._db.commit()
+
+    # ------------------------------------------------------------- 写入
+
+    def save(
+        self, *, run_id: str, name: str, content: bytes, mime: str = "text/plain"
+    ) -> ArtifactRecord:
+        name = _safe_name(name)
+        if not name:
+            raise ValueError("artifact name 不能为空")
+        run_id = _safe_name(run_id)
+        if not run_id:
+            raise ValueError("run_id 不能为空")
+        version = self._next_version(run_id, name)
+        digest = "sha256:" + hashlib.sha256(content).hexdigest()
+        directory = self._root / run_id
+        directory.mkdir(parents=True, exist_ok=True)
+        file_path = directory / f"{name}.v{version}"
+        # 目录穿越防线：规范化后必须仍在 Store 根目录内（run_id/name 已各
+        # 自过 _safe_name，此处校验最终落点，防御纵深）。
+        _assert_within_root(self._root, file_path)
+        file_path.write_bytes(content)
+        uri = f"artifact://{run_id}/{name}@v{version}"
+        record = ArtifactRecord(
+            run_id=run_id,
+            name=name,
+            version=version,
+            mime=mime,
+            content_hash=digest,
+            bytes=len(content),
+            uri=uri,
+            created_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        )
+        self._db.execute(
+            "INSERT INTO artifacts VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                record.run_id,
+                record.name,
+                record.version,
+                record.mime,
+                record.content_hash,
+                record.bytes,
+                record.uri,
+                record.created_at,
+            ),
+        )
+        self._db.commit()
+        return record
+
+    # ------------------------------------------------------------- 读取
+
+    def list(self, run_id: str, *, name: str | None = None) -> list[ArtifactRecord]:
+        run_id = _safe_name(run_id)
+        query = "SELECT * FROM artifacts WHERE run_id = ?"
+        params: list[Any] = [run_id]
+        if name is not None:
+            query += " AND name = ?"
+            params.append(_safe_name(name))
+        query += " ORDER BY name, version"
+        rows = self._db.execute(query, params).fetchall()
+        return [_record(row) for row in rows]
+
+    def latest(self, run_id: str, name: str) -> ArtifactRecord | None:
+        records = self.list(run_id, name=name)
+        return records[-1] if records else None
+
+    def read(self, record: ArtifactRecord) -> bytes:
+        return self._read_uri(record.uri)
+
+    def read_latest(self, run_id: str, name: str) -> bytes | None:
+        record = self.latest(run_id, name)
+        return None if record is None else self.read(record)
+
+    def _read_uri(self, uri: str) -> bytes:
+        # uri: artifact://{run_id}/{name}@v{version}
+        try:
+            body = uri[len("artifact://") :]
+            run_id, rest = body.split("/", 1)
+            name, version = rest.rsplit("@v", 1)
+            file_path = self._root / _safe_name(run_id) / f"{_safe_name(name)}.v{int(version)}"
+        except ValueError as exc:
+            raise ValueError(f"非法 artifact uri: {uri!r}") from exc
+        _assert_within_root(self._root, file_path)
+        if not file_path.is_file():
+            raise FileNotFoundError(f"artifact 内容缺失: {uri}")
+        return file_path.read_bytes()
+
+    # ------------------------------------------------------------- 内部
+
+    def _next_version(self, run_id: str, name: str) -> int:
+        row = self._db.execute(
+            "SELECT MAX(version) FROM artifacts WHERE run_id = ? AND name = ?",
+            (run_id, name),
+        ).fetchone()
+        return (row[0] or 0) + 1
+
+    def close(self) -> None:
+        self._db.close()
+
+
+class BudgetedArtifactStore:
+    """Run 级写入守卫；在委托真实 Store 前原子检查数量预算。"""
+
+    def __init__(self, store: ArtifactStore, *, run_id: str, max_artifacts: int) -> None:
+        self._store = store
+        self._run_id = run_id
+        self._max_artifacts = max_artifacts
+
+    def save(self, *, run_id: str, name: str, content: bytes, mime: str = "text/plain"):
+        if run_id != self._run_id:
+            raise ValueError("budgeted artifact store run_id mismatch")
+        if len(self._store.list(run_id)) >= self._max_artifacts:
+            raise ArtifactBudgetExceeded(
+                f"artifact budget {self._max_artifacts} exhausted before write"
+            )
+        return self._store.save(run_id=run_id, name=name, content=content, mime=mime)
+
+    def list(self, run_id: str, *, name: str | None = None):
+        return self._store.list(run_id, name=name)
+
+    def __getattr__(self, name: str):
+        return getattr(self._store, name)
+
+
+class ArtifactBudgetExceeded(ValueError):
+    """Artifact 写入在产生文件或索引副作用前被预算拒绝。"""
+
+
+def _safe_name(name: str) -> str:
+    keep = [c if (c.isalnum() or c in "-_.") else "_" for c in str(name or "").strip()]
+    return "".join(keep)[:128]
+
+
+def _assert_within_root(root: Path, path: Path) -> None:
+    root_resolved = root.resolve()
+    path_resolved = path.resolve()
+    if root_resolved != path_resolved and root_resolved not in path_resolved.parents:
+        raise ValueError(f"artifact 路径越界: {path}")
+
+
+def _record(row: tuple) -> ArtifactRecord:
+    return ArtifactRecord(
+        run_id=row[0],
+        name=row[1],
+        version=int(row[2]),
+        mime=row[3],
+        content_hash=row[4],
+        bytes=int(row[5]),
+        uri=row[6],
+        created_at=row[7],
+    )
+
+
+__all__ = [
+    "ArtifactBudgetExceeded",
+    "ArtifactRecord",
+    "ArtifactStore",
+    "BudgetedArtifactStore",
+]

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