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

ksadk/resource_runtime/build_artifacts.py

@@ -0,0 +1,165 @@
+"""Resource binding and pinned Skill files retained as one verifiable build input.
+
+The caller owns the enclosing Build and authorizes its resolved resource snapshot.
+This module writes into its staging directory; it creates no alternate registry,
+authorization store, or cloud upload path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+from pathlib import Path
+from typing import Literal, Mapping
+
+from pydantic import field_validator, model_validator
+
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.contracts import Digest, Identifier
+from ksadk.resource_runtime.snapshots import ResourceSnapshot
+from ksadk.skills.loader import load_local_skill
+from ksadk.skills.package_store import PackageStore, SkillPackage, SkillPackageError
+from ksadk.skills.runtime.pinned import PinnedSkillArchive, read_archive, stage_packages
+
+
+class LockedSkillPackage(PluginContractModel):
+    binding_id: Identifier
+    archive: PinnedSkillArchive
+
+
+class ResourceBuildManifest(PluginContractModel):
+    schema_version: Literal[1] = 1
+    snapshot: ResourceSnapshot
+    packages: tuple[LockedSkillPackage, ...] = ()
+
+    @field_validator("schema_version", mode="before")
+    @classmethod
+    def strict_version(cls, value: object) -> object:
+        if type(value) is not int:
+            raise ValueError("Resource Build schema version must be an integer")
+        return value
+
+    @model_validator(mode="after")
+    def exact_selected_packages(self) -> ResourceBuildManifest:
+        expected = set()
+        for binding in self.snapshot.bindings:
+            config = binding.config
+            if (
+                config.binding.resource.kind == "skill-space"
+                and config.selection_mode != "discovery"
+            ):
+                expected.update(
+                    (config.binding.id, skill.skill_id, skill.version_id, skill.content_hash)
+                    for skill in config.selected_skills
+                )
+        actual = [
+            (
+                item.binding_id,
+                item.archive.skill_id,
+                item.archive.version_id,
+                item.archive.content_hash,
+            )
+            for item in self.packages
+        ]
+        if len(actual) != len(set(actual)) or set(actual) != expected:
+            raise ValueError("Build packages must exactly match pinned resource selections")
+        return self
+
+    def canonical_bytes(self) -> bytes:
+        # ResourceSnapshot already normalizes config defaults for its digest.
+        payload = {
+            "schemaVersion": self.schema_version,
+            "snapshotDigest": self.snapshot.digest,
+            "packages": [
+                item.model_dump(by_alias=True, mode="json")
+                for item in sorted(
+                    self.packages, key=lambda item: (item.binding_id, item.archive.skill_id)
+                )
+            ],
+        }
+        return json.dumps(
+            payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+        ).encode()
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + hashlib.sha256(self.canonical_bytes()).hexdigest()
+
+
+class ResourceBuildReference(PluginContractModel):
+    """Persist this digest in the enclosing immutable Build record."""
+
+    digest: Digest
+    snapshot_digest: Digest
+
+
+def write_resource_build(
+    directory: Path,
+    snapshot: ResourceSnapshot,
+    packages: Mapping[str, list[SkillPackage]],
+) -> ResourceBuildReference:
+    """Populate a new caller-owned staging directory, retaining complete ZIPs."""
+    if directory.exists():
+        raise FileExistsError("Resource Build destination already exists")
+    # This private directory is not published until all references and bytes pass;
+    # the caller publishes its enclosing Build only on success.
+    directory.mkdir(parents=True, mode=0o700)
+    locked = []
+    try:
+        for binding_id, values in packages.items():
+            binding = snapshot.binding(binding_id)
+            if binding.config.binding.resource.kind != "skill-space":
+                raise ValueError("Skill packages require a Skill binding")
+            entries = stage_packages(values, directory)
+            locked.extend(
+                LockedSkillPackage(binding_id=binding_id, archive=entry) for entry in entries
+            )
+        manifest = ResourceBuildManifest(snapshot=snapshot, packages=tuple(locked))
+        (directory / "resource-build.json").write_text(
+            manifest.model_dump_json(by_alias=True), encoding="utf-8"
+        )
+        (directory / "resource-build.json").chmod(0o600)
+        reference = ResourceBuildReference(digest=manifest.digest, snapshot_digest=snapshot.digest)
+        # Build admission checks extraction as well as the archive hash. Keep the
+        # verified ZIPs as the portable artifact, not temporary absolute paths.
+        with tempfile.TemporaryDirectory(prefix=".resource-verify-", dir=directory.parent) as cache:
+            restore_resource_build(directory, reference, cache_directory=Path(cache))
+        return reference
+    except Exception:
+        import shutil
+
+        shutil.rmtree(directory)
+        raise
+
+
+def restore_resource_build(
+    directory: Path,
+    reference: ResourceBuildReference,
+    *,
+    cache_directory: Path,
+) -> tuple[ResourceBuildManifest, dict[str, list[SkillPackage]]]:
+    """Restore from saved bytes, without credentials, catalog queries, or env defaults."""
+    path = directory / "resource-build.json"
+    if directory.is_symlink() or path.is_symlink() or path.stat().st_size > 1024 * 1024:
+        raise SkillPackageError("Invalid Resource Build manifest file")
+    manifest = ResourceBuildManifest.model_validate_json(path.read_bytes())
+    if manifest.digest != reference.digest or manifest.snapshot.digest != reference.snapshot_digest:
+        raise SkillPackageError("Resource Build digest mismatch")
+    expected_files = {
+        "resource-build.json",
+        *(item.archive.archive_name for item in manifest.packages),
+    }
+    if {item.name for item in directory.iterdir()} != expected_files:
+        raise SkillPackageError("Resource Build file set mismatch")
+    # Namespace is derived from the frozen binding/identity snapshot, not runtime env.
+    store = PackageStore(cache_directory, namespace=manifest.snapshot.digest, require_hash=True)
+    result: dict[str, list[SkillPackage]] = {}
+    for item in manifest.packages:
+        package = store.store_archive(
+            item.archive.skill_ref(), read_archive(directory / item.archive.archive_name)
+        )
+        if load_local_skill(package.root_dir).name != item.archive.name:
+            raise SkillPackageError("Build Skill name does not match package metadata")
+        result.setdefault(item.binding_id, []).append(package)
+    return manifest, result

ksadk/resource_runtime/contracts.py

@@ -0,0 +1,138 @@
+"""Versioned resource declarations. Credentials are resolved outside these models."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Annotated, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from ksadk.plugins.contracts import PluginContractModel
+
+Identifier = Annotated[str, Field(strict=True, min_length=1, max_length=256, pattern=r"^\S+$")]
+Digest = Annotated[str, Field(pattern=r"^sha256:[0-9a-f]{64}$")]
+ResourceKind = Literal["knowledge-base", "memory-instance", "skill-space"]
+
+
+class ResourceRef(PluginContractModel):
+    kind: ResourceKind
+    id: Identifier
+    region: Identifier
+
+
+class ResourceBinding(PluginContractModel):
+    id: Identifier
+    connection_ref: Identifier
+    resource: ResourceRef
+    required: bool = Field(default=True, strict=True)
+
+
+class RetrievalPolicy(PluginContractModel):
+    mode: Literal["tool"] = "tool"
+    top_k: int = Field(default=5, ge=1, le=100, strict=True)
+    max_chars: int = Field(default=16000, ge=1, le=100000, strict=True)
+
+
+class SelectedSkill(PluginContractModel):
+    skill_id: Identifier
+    version_id: Identifier
+    content_hash: Digest
+
+
+class ResourceConfig(PluginContractModel):
+    schema_version: Literal[1] = 1
+    binding: ResourceBinding
+    retrieval: RetrievalPolicy | None = None
+    selection_mode: Literal["pinned", "discovery"] | None = None
+    selected_skills: tuple[SelectedSkill, ...] = ()
+    include_public: bool = Field(default=False, strict=True)
+    execution_mode: Literal["outer-agent", "isolated"] | None = None
+
+    @field_validator("schema_version", mode="before")
+    @classmethod
+    def strict_schema_version(cls, value: object) -> object:
+        if type(value) is not int:
+            raise ValueError("schemaVersion must be an integer")
+        return value
+
+    @model_validator(mode="after")
+    def validate_resource_policy(self) -> ResourceConfig:
+        kind = self.binding.resource.kind
+        if kind != "knowledge-base" and self.retrieval is not None:
+            raise ValueError("retrieval is only valid for knowledge-base bindings")
+        if kind != "skill-space":
+            if (
+                self.selection_mode is not None
+                or self.selected_skills
+                or self.include_public
+                or self.execution_mode is not None
+            ):
+                raise ValueError("Skill policies require a skill-space binding")
+        else:
+            identities = [skill.skill_id for skill in self.selected_skills]
+            if len(identities) != len(set(identities)):
+                raise ValueError("a Skill may only be selected once")
+            if self.selection_mode == "discovery" and self.selected_skills:
+                raise ValueError("discovery cannot declare pinned selectedSkills")
+        return self
+
+    def canonical_bytes(self) -> bytes:
+        """Normalize omitted defaults before hashing; lists are immutable tuples."""
+        data = self.model_dump(by_alias=True, mode="json", exclude_none=True)
+        if self.binding.resource.kind == "knowledge-base":
+            data["retrieval"] = (self.retrieval or RetrievalPolicy()).model_dump(by_alias=True)
+        if self.binding.resource.kind == "skill-space":
+            data["selectionMode"] = self.selection_mode or "pinned"
+            data["executionMode"] = self.execution_mode or "outer-agent"
+        return json.dumps(
+            data, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+        ).encode("utf-8")
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + hashlib.sha256(self.canonical_bytes()).hexdigest()
+
+
+def validate_resource_bindings(configs: tuple[ResourceConfig, ...]) -> None:
+    """First release supports one binding of each resource kind per Agent."""
+    ids = [config.binding.id for config in configs]
+    kinds = [config.binding.resource.kind for config in configs]
+    if len(ids) != len(set(ids)):
+        raise ValueError("resource binding IDs must be unique within an Agent")
+    if len(kinds) != len(set(kinds)):
+        raise ValueError("only one resource binding of each kind is supported")
+
+
+class InvocationIdentity(PluginContractModel):
+    """Resolved by the trusted host, never taken from model tool arguments.
+
+    Resource credentials and the human whose memories are accessed need not
+    represent the same principal. A worker activation belongs to one identity.
+    """
+
+    tenant_ref: Identifier
+    resource_principal_ref: Identifier
+    actor_ref: Identifier
+    memory_subject_ref: Identifier
+    agent_id: Identifier
+    session_ref: Identifier
+
+    def memory_partition(self, resource: ResourceRef) -> str:
+        """Stable across sessions/activations; account and resource remain isolated."""
+        if resource.kind != "memory-instance":
+            raise ValueError("memory partition requires a memory-instance")
+        parts = [
+            "memory-partition/v1",
+            self.tenant_ref,
+            self.resource_principal_ref,
+            resource.kind,
+            resource.id,
+            resource.region,
+            self.agent_id,
+            self.memory_subject_ref,
+        ]
+        encoded = json.dumps(parts, ensure_ascii=False, separators=(",", ":")).encode()
+        # AICP AgentUserId accepts at most 64 characters. Keep the versioned
+        # prefix and 240 bits of the partition digest inside that wire limit.
+        return "mp1-" + hashlib.sha256(encoded).hexdigest()[:60]

ksadk/resource_runtime/discovery_receipts.py

@@ -0,0 +1,100 @@
+"""Host-owned discovery selections in the existing operation ledger.
+
+Receipts pin identity and cache lookup fields, never grant permission or contain
+URLs. The runner supplies a stable logical run reference across recovery.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+
+from pydantic import Field
+
+from ksadk.resource_runtime.contracts import SelectedSkill
+from ksadk.resource_runtime.leases import ResourceScope
+from ksadk.resource_runtime.operation_ledger import OperationConflict, OperationLedger
+from ksadk.skills.models import ContentHash, SkillRef
+
+
+class DiscoverySkillReceipt(SelectedSkill):
+    name: str = Field(strict=True, min_length=1, max_length=256)
+    version: str = Field(default="", strict=True, max_length=256)
+
+    @classmethod
+    def from_ref(cls, ref: SkillRef):
+        return cls(
+            skill_id=ref.skill_id, version_id=ref.version_id,
+            content_hash=ref.content_hash.render() if ref.content_hash else "",
+            name=ref.name, version=ref.version,
+        )
+
+    def to_ref(self) -> SkillRef:
+        return SkillRef(
+            skill_id=self.skill_id, version_id=self.version_id,
+            name=self.name, version=self.version,
+            content_hash=ContentHash.parse(self.content_hash),
+        )
+
+
+def discovery_scope_key(scope: ResourceScope, run_ref: str) -> str:
+    if not isinstance(run_ref, str) or not 1 <= len(run_ref) <= 256:
+        raise ValueError("Discovery requires a stable host run reference")
+    return hashlib.sha256(json.dumps([
+        "discovery-selection-v1", run_ref,
+        scope.identity.model_dump(by_alias=True, mode="json"),
+        scope.build_digest, scope.binding_snapshot_digest, scope.binding_id,
+    ], sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+class DiscoverySelectionReceipts:
+    def __init__(self, ledger: OperationLedger):
+        self.ledger = ledger
+        with ledger._connect() as connection:
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS discovery_selections ("
+                "scope_key TEXT NOT NULL, skill_id TEXT NOT NULL, payload TEXT NOT NULL, "
+                "PRIMARY KEY(scope_key, skill_id))"
+            )
+
+    @staticmethod
+    def _key(value):
+        if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{64}", value):
+            raise ValueError("Invalid discovery scope")
+        return value
+
+    def read(self, scope_key: str) -> tuple[DiscoverySkillReceipt, ...]:
+        with self.ledger._connect() as connection:
+            rows = connection.execute(
+                "SELECT skill_id,payload FROM discovery_selections WHERE scope_key=? "
+                "ORDER BY skill_id LIMIT 33", (self._key(scope_key),),
+            ).fetchall()
+        if len(rows) > 32:
+            raise OperationConflict("Discovery selection limit exceeded")
+        results = tuple(DiscoverySkillReceipt.model_validate_json(row[1]) for row in rows)
+        if any(row[0] != result.skill_id for row, result in zip(rows, results)):
+            raise OperationConflict("Discovery selection identity mismatch")
+        return results
+
+    def record(self, scope_key: str, receipt: DiscoverySkillReceipt) -> None:
+        scope_key = self._key(scope_key)
+        receipt = DiscoverySkillReceipt.model_validate(receipt.model_dump())
+        with self.ledger._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            previous = connection.execute(
+                "SELECT payload FROM discovery_selections WHERE scope_key=? AND skill_id=?",
+                (scope_key, receipt.skill_id),
+            ).fetchone()
+            if previous:
+                if DiscoverySkillReceipt.model_validate_json(previous[0]) != receipt:
+                    raise OperationConflict("Discovery selection cannot change within a run")
+                return
+            count = connection.execute(
+                "SELECT COUNT(*) FROM discovery_selections WHERE scope_key=?", (scope_key,),
+            ).fetchone()[0]
+            if count >= 32:
+                raise OperationConflict("Discovery selection limit exceeded")
+            connection.execute(
+                "INSERT INTO discovery_selections VALUES (?,?,?)",
+                (scope_key, receipt.skill_id, receipt.model_dump_json(by_alias=True)),
+            )

ksadk/resource_runtime/discovery_skills.py

@@ -0,0 +1,172 @@
+"""Dynamic discovery with host-restored run selections in one admitted Skill space."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+from threading import RLock
+
+from ksadk.resource_runtime.contracts import ResourceConfig
+from ksadk.resource_runtime.discovery_receipts import DiscoverySkillReceipt
+from ksadk.resource_runtime.skills import (
+    PinnedSkillService,
+    SkillExecutionQuery,
+    SkillResourceQuery,
+    SkillSearchQuery,
+)
+from ksadk.resource_runtime.snapshots import SkillExecutionTarget
+from ksadk.skills.package_store import PackageStore, SkillPackageError
+from ksadk.skills.runtime.registry import match_skill_refs
+from ksadk.skills.service_client import SkillServiceClient
+
+
+class DiscoverySkillService(PinnedSkillService):
+    """Reuse the verified-package read contract while selecting from a live catalog.
+
+    A first load fixes a version; every subsequent read checks cached bytes. The
+    host commits a receipt before exposing content and supplies restored selections
+    when resuming a logical run. This does not claim native engine discovery.
+    """
+
+    def __init__(
+        self,
+        config: ResourceConfig,
+        client: SkillServiceClient,
+        *,
+        cache_directory: Path,
+        namespace: str,
+        restored_selections: tuple[DiscoverySkillReceipt, ...] = (),
+        execution_target: SkillExecutionTarget | None = None,
+    ):
+        self.config = ResourceConfig.model_validate(config.model_dump())
+        if (
+            self.config.binding.resource.kind != "skill-space"
+            or self.config.selection_mode != "discovery"
+            or self.config.include_public
+            or client.allow_env_fallback
+        ):
+            raise ValueError("Discovery requires one explicit non-public Skill space")
+        self.client = client
+        self.execution_target = (
+            SkillExecutionTarget.model_validate(execution_target.model_dump())
+            if execution_target is not None else None
+        )
+        if self.execution_target is not None and self.config.execution_mode != "isolated":
+            raise ValueError("Discovery execution target requires isolated mode")
+        self.store = PackageStore(cache_directory, namespace=namespace, require_hash=True)
+        receipts = tuple(
+            DiscoverySkillReceipt.model_validate(item.model_dump()) for item in restored_selections
+        )
+        if len(receipts) > 32 or len({item.skill_id for item in receipts}) != len(receipts):
+            raise ValueError("Invalid restored discovery selections")
+        self._selected = {item.skill_id: item.to_ref() for item in receipts}
+        self._lock = RLock()
+
+    def _catalog(self):
+        with self._lock:
+            listing = self.client.list_skills_by_space_id(self.config.binding.resource.id)
+            if listing.space_id != self.config.binding.resource.id:
+                raise SkillPackageError("Skill catalog does not match admitted space")
+            refs = {}
+            for ref in listing.active_skills(allow_partial=True):
+                DiscoverySkillReceipt.from_ref(ref)
+                if not ref.name or len(ref.name) > 256 or ref.skill_id in refs:
+                    raise SkillPackageError("Skill catalog contains invalid identities")
+                refs[ref.skill_id] = self._selected.get(ref.skill_id, ref)
+            return refs, listing.truncated
+
+    def list_skills(self, arguments: dict) -> dict:
+        if arguments:
+            raise ValueError("Skill catalog accepts no space override")
+        refs, partial = self._catalog()
+        ordered = sorted(refs.values(), key=lambda item: item.skill_id)
+        return {
+            "status": "ok",
+            "truncated": partial or len(ordered) > 128,
+            "items": [
+                {
+                    "skillId": ref.skill_id,
+                    "versionId": ref.version_id,
+                    "name": ref.name,
+                    "contentHash": ref.content_hash.render(),
+                }
+                for ref in ordered[:128]
+            ],
+        }
+
+    def search_skills(self, arguments: dict) -> dict:
+        query = SkillSearchQuery.model_validate(arguments)
+        if not query.query.strip():
+            raise ValueError("Skill query cannot be blank")
+        refs, partial = self._catalog()
+        matches = match_skill_refs(list(refs.values()), query.query)
+        return {
+            "status": "ok",
+            "truncated": partial or len(matches) > query.max_results,
+            "items": [
+                {
+                    "skillId": match.skill.skill_id,
+                    "versionId": match.skill.version_id,
+                    "name": match.skill.name,
+                    "contentHash": match.skill.content_hash.render(),
+                    "description": match.skill.description[:8192],
+                    "score": match.score,
+                    "reason": match.reason,
+                }
+                for match in matches[: query.max_results]
+            ],
+        }
+
+    def read_resource(self, arguments: dict) -> dict:
+        query = SkillResourceQuery.model_validate(arguments)
+        with self._lock:
+            if query.skill_id not in self._selected:
+                if len(self._selected) >= 32:
+                    raise SkillPackageError("Activation Skill selection limit exceeded")
+                refs, _ = self._catalog()
+                ref = refs.get(query.skill_id)
+                if ref is None:
+                    raise SkillPackageError("Skill is not in the admitted catalog")
+                # A download URL is obtained by the client and never retained in
+                # the chosen reference or returned to consumers.
+                ref = replace(ref, archive_uri="")
+                package = self.store.get_cached(ref)
+                if package is None:
+                    package = self.store.store_archive(ref, self.client.download_skill_archive(ref))
+                self._selected[query.skill_id] = ref
+            return super().read_resource(arguments)
+
+    def _packages(self):
+        with self._lock:
+            packages = {key: self.store.get_cached(ref) for key, ref in self._selected.items()}
+            if any(package is None for package in packages.values()):
+                raise SkillPackageError("Selected Skill cache integrity failed")
+            return packages
+
+    def _restore(self):
+        return self.config, self._packages(), self.execution_target
+
+    def execute(self, arguments, *, approved_selections=(), **kwargs):
+        if self.execution_target is None:
+            raise ValueError("Discovery execution has no admitted runtime adapter")
+        query = SkillExecutionQuery.model_validate(arguments)
+        approved = {
+            item.skill_id: item
+            for item in (
+                DiscoverySkillReceipt.model_validate(value.model_dump())
+                for value in approved_selections
+            )
+        }
+        if len(approved) != len(approved_selections) or set(approved) != set(query.skill_ids):
+            raise ValueError("Discovery execution requires exact committed selections")
+        with self._lock:
+            if any(
+                key not in self._selected
+                or DiscoverySkillReceipt.from_ref(self._selected[key]) != receipt
+                for key, receipt in approved.items()
+            ):
+                raise ValueError("Discovery execution selection mismatch")
+            return super().execute(arguments, **kwargs)
+
+    def close(self):
+        self.client.close()

ksadk/resource_runtime/errors.py

@@ -0,0 +1,6 @@
+"""Fixed diagnostics shared by trusted resource service adapters."""
+
+
+class ResourceUpstreamAuthorizationError(PermissionError):
+    def __init__(self):
+        super().__init__("RESOURCE_FORBIDDEN")