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

ksadk/resource_runtime/process.py

@@ -0,0 +1,110 @@
+"""Async owner of one resource worker subprocess and its private pipes."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import struct
+import sys
+import time
+
+from ksadk.resource_runtime.ipc import MAX_FRAME_BYTES, ResourceRequest, decode_body, encode_frame
+from ksadk.resource_runtime.leases import ResourceScope
+from ksadk.resource_runtime.worker import WorkerInitialization
+
+
+class ResourceWorkerError(RuntimeError):
+    def __init__(self):
+        super().__init__("RESOURCE_WORKER_UNAVAILABLE")
+
+
+class ResourceWorkerProcess:
+    def __init__(self, process: asyncio.subprocess.Process):
+        self._process = process
+        self._lock = asyncio.Lock()
+
+    @classmethod
+    async def start(cls, initialization: WorkerInitialization) -> ResourceWorkerProcess:
+        if os.name != "posix":
+            raise RuntimeError("RESOURCE_IPC_UNSUPPORTED")
+        # No inherited credential, proxy, Python path or runtime selection vars.
+        env = {
+            key: os.environ[key]
+            for key in ("PATH", "LANG", "LC_ALL", "SYSTEMROOT")
+            if key in os.environ
+        }
+        process = await asyncio.create_subprocess_exec(
+            sys.executable,
+            "-I",
+            "-m",
+            "ksadk.resource_runtime.worker",
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+            env=env,
+        )
+        worker = cls(process)
+        try:
+            response = await asyncio.wait_for(worker._exchange(initialization.pipe_payload()), 30)
+            if response != {"status": "ready"}:
+                raise ResourceWorkerError()
+            return worker
+        except BaseException:
+            await worker.aclose()
+            raise
+
+    async def invoke(self, request: ResourceRequest, scope: ResourceScope) -> dict:
+        async with self._lock:
+            remaining = request.deadline / 1000 - time.time()
+            if remaining <= 0:
+                raise ResourceWorkerError()
+            try:
+                response = await asyncio.wait_for(
+                    self._exchange(
+                        {
+                            "request": request.model_dump(by_alias=True, mode="json"),
+                            "scope": scope.model_dump(by_alias=True, mode="json"),
+                        }
+                    ),
+                    remaining,
+                )
+                if response.get("requestId") != request.request_id or "result" not in response:
+                    raise ResourceWorkerError()
+                return response["result"]
+            except BaseException:
+                # A lost response cannot be correlated with a subsequent request.
+                # Terminate instead of reusing or silently restarting the worker.
+                await self.aclose()
+                raise
+
+    async def _exchange(self, payload: dict) -> dict:
+        if self._process.returncode is not None:
+            raise ResourceWorkerError()
+        source, target = self._process.stdout, self._process.stdin
+        assert source is not None and target is not None
+        target.write(encode_frame(payload))
+        await target.drain()
+        prefix = await source.readexactly(4)
+        (size,) = struct.unpack("!I", prefix)
+        if not 0 < size <= MAX_FRAME_BYTES:
+            raise ResourceWorkerError()
+        return decode_body(await source.readexactly(size))
+
+    async def aclose(self) -> None:
+        if self._process.returncode is None:
+            try:
+                self._process.kill()
+            except ProcessLookupError:
+                pass
+        await self._process.wait()
+
+    @property
+    def pid(self) -> int:
+        return self._process.pid
+
+    @property
+    def is_running(self) -> bool:
+        return self._process.returncode is None
+
+    async def wait_stopped(self) -> int:
+        return await self._process.wait()

ksadk/resource_runtime/skill_artifacts.py

@@ -0,0 +1,153 @@
+"""Host-owned Skill result publication in the existing durable operation ledger.
+
+This is local runtime storage, not a new upload service. Callers must admit the
+current resource lease before every read; opaque IDs do not confer authority.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import tempfile
+import zipfile
+from pathlib import Path
+
+from pydantic import Field
+
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.operation_ledger import OperationConflict, OperationLedger
+from ksadk.skills.runtime.artifact_delivery import export_artifacts
+
+
+class SkillArtifactQuery(PluginContractModel):
+    operation_id: str = Field(strict=True, pattern=r"^[0-9a-f]{64}$")
+    artifact_id: str = Field(strict=True, pattern=r"^[0-9a-f]{64}$")
+    offset: int = Field(default=0, strict=True, ge=0, le=20 * 1024 * 1024)
+    max_bytes: int = Field(default=32768, strict=True, ge=1, le=32768)
+
+
+class SkillArtifactReceipts:
+    def __init__(self, ledger: OperationLedger):
+        self.ledger = ledger
+        with ledger._connect() as connection:
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS skill_results ("
+                "operation_id TEXT PRIMARY KEY, payload TEXT NOT NULL)"
+            )
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS skill_artifacts ("
+                "operation_id TEXT NOT NULL, id TEXT NOT NULL, data BLOB NOT NULL, "
+                "PRIMARY KEY(operation_id, id))"
+            )
+
+    def _owned(self, operation_id: str, authority_digest: str):
+        receipt = self.ledger.lookup(
+            operation_id, authority_digest=authority_digest, operation="execute_skills"
+        )
+        if receipt is None:
+            raise OperationConflict("RESOURCE_OPERATION_NOT_FOUND")
+        return receipt
+
+    def result(self, operation_id: str, *, authority_digest: str) -> dict | None:
+        self._owned(operation_id, authority_digest)
+        with self.ledger._connect() as connection:
+            row = connection.execute(
+                "SELECT payload FROM skill_results WHERE operation_id=?", (operation_id,)
+            ).fetchone()
+        return None if row is None else json.loads(row[0])
+
+    def publish(
+        self,
+        operation_id: str,
+        *,
+        authority_digest: str,
+        root: Path,
+        paths: list[str],
+        status: str,
+    ) -> dict:
+        """Atomically retain validated bytes and a terminal receipt; never execute.
+
+        root is supplied by the trusted activation owner, not by the Worker result.
+        A repeated publication returns the original receipt and does not read paths.
+        """
+        self._owned(operation_id, authority_digest)
+        if status not in {"succeeded", "failed"}:
+            raise ValueError("Only confirmed execution outcomes may be published")
+        existing = self.result(operation_id, authority_digest=authority_digest)
+        if existing is not None:
+            return existing
+        with tempfile.TemporaryDirectory(prefix="ksadk-artifact-publication-") as temporary:
+            archive_path = Path(temporary) / "artifacts.zip"
+            export_artifacts(paths, root, archive_path)
+            with zipfile.ZipFile(archive_path) as archive, self.ledger._connect() as connection:
+                connection.execute("BEGIN IMMEDIATE")
+                # Another host publisher may have committed while files were validated.
+                previous = connection.execute(
+                    "SELECT payload FROM skill_results WHERE operation_id=?", (operation_id,)
+                ).fetchone()
+                if previous is not None:
+                    return json.loads(previous[0])
+                state = connection.execute(
+                    "SELECT state FROM operations WHERE id=?", (operation_id,)
+                ).fetchone()
+                if state is None or state[0] not in {"unknown", "accepted_pending"}:
+                    raise OperationConflict("RESOURCE_OPERATION_STATE_CONFLICT")
+                artifacts = []
+                for entry in archive.infolist():
+                    data = archive.read(entry)
+                    digest = hashlib.sha256(data).hexdigest()
+                    artifact_id = hashlib.sha256(
+                        (operation_id + "\0" + entry.filename + "\0" + digest).encode()
+                    ).hexdigest()
+                    artifacts.append(
+                        {
+                            "artifactId": artifact_id,
+                            "name": entry.filename,
+                            "size": len(data),
+                            "sha256": digest,
+                        }
+                    )
+                    connection.execute(
+                        "INSERT INTO skill_artifacts VALUES (?, ?, ?)",
+                        (operation_id, artifact_id, data),
+                    )
+                result = {"status": status, "operationId": operation_id, "artifacts": artifacts}
+                connection.execute(
+                    "INSERT INTO skill_results VALUES (?, ?)",
+                    (operation_id, json.dumps(result, separators=(",", ":"))),
+                )
+                connection.execute(
+                    "UPDATE operations SET state=? WHERE id=?", (status, operation_id)
+                )
+                return result
+
+    def read(self, arguments: dict, *, authority_digest: str) -> dict:
+        query = SkillArtifactQuery.model_validate(arguments)
+        result = self.result(query.operation_id, authority_digest=authority_digest)
+        artifact = next(
+            (
+                item
+                for item in (result or {}).get("artifacts", [])
+                if item["artifactId"] == query.artifact_id
+            ),
+            None,
+        )
+        if artifact is None or query.offset > artifact["size"]:
+            raise OperationConflict("RESOURCE_ARTIFACT_NOT_FOUND")
+        with self.ledger._connect() as connection:
+            row = connection.execute(
+                "SELECT substr(data, ?, ?) FROM skill_artifacts WHERE operation_id=? AND id=?",
+                (query.offset + 1, query.max_bytes, query.operation_id, query.artifact_id),
+            ).fetchone()
+        if row is None:
+            raise OperationConflict("RESOURCE_ARTIFACT_NOT_FOUND")
+        following = query.offset + len(row[0])
+        return {
+            **artifact,
+            "operationId": query.operation_id,
+            "encoding": "base64",
+            "content": base64.b64encode(row[0]).decode("ascii"),
+            "offset": query.offset,
+            "nextOffset": following if following < artifact["size"] else None,
+        }

ksadk/resource_runtime/skill_runtime.py

@@ -0,0 +1,42 @@
+"""Instantiate the sandbox target frozen in a resource Build after host admission."""
+
+from pathlib import Path
+
+from pydantic import SecretStr
+
+from ksadk.resource_runtime.snapshots import ConnectionTarget, ResourceSnapshot
+from ksadk.sandbox.e2b_connection import ExplicitE2BConnection
+from ksadk.skills.runtime.backends.e2b import E2BSkillRuntimeBackend
+
+
+def create_bound_skill_runtime(
+    snapshot: ResourceSnapshot,
+    binding_id: str,
+    *,
+    current_connection: ConnectionTarget,
+    api_key: SecretStr,
+    artifact_directory: Path | None = None,
+) -> E2BSkillRuntimeBackend:
+    """Host revalidates account/grant first; only secret values may rotate here.
+
+    This factory does not read process env, create a sandbox, or authorize tool
+    execution. The target and network policy are immutable Build inputs.
+    """
+    snapshot = ResourceSnapshot.model_validate(snapshot.model_dump())
+    target = snapshot.binding(binding_id).skill_execution
+    if target is None:
+        raise ValueError("SKILL_EXECUTION_TARGET_REQUIRED")
+    if target.connection != current_connection:
+        raise ValueError("RESOURCE_CONNECTION_CHANGED")
+    connection = ExplicitE2BConnection(
+        api_url=target.connection.endpoint,
+        domain=target.domain,
+        api_key=api_key,
+    )
+    return E2BSkillRuntimeBackend(
+        template_id=target.template_id,
+        timeout=target.timeout,
+        allow_internet_access=target.allow_internet_access,
+        connection=connection,
+        artifact_directory=artifact_directory,
+    )

ksadk/resource_runtime/skill_workspace.py

@@ -0,0 +1,118 @@
+"""Owned, activation-visible pinned Skill files for an outer-agent consumer.
+
+This prepares files, not native discovery or sandbox isolation. The executor must
+own the workspace lifetime and verify its runtime's discovery and context rules.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import tempfile
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+from ksadk.resource_runtime.build_artifacts import ResourceBuildReference, restore_resource_build
+from ksadk.skills.package_store import SkillPackageError
+
+
+@dataclass(frozen=True)
+class PreparedSkill:
+    skill_id: str
+    version_id: str
+    content_hash: str
+    relative_directory: str
+
+
+@dataclass(frozen=True)
+class SkillWorkspace:
+    directory: Path
+    skills: tuple[PreparedSkill, ...]
+
+
+def _identity(path: Path) -> tuple[int, int]:
+    info = path.lstat()
+    if path.is_symlink() or not path.is_dir():
+        raise SkillPackageError("Skill workspace must remain an owned directory")
+    return info.st_dev, info.st_ino
+
+
+@contextmanager
+def prepare_pinned_skill_workspace(
+    build_directory: Path,
+    reference: ResourceBuildReference,
+    *,
+    binding_id: str,
+    workspace_directory: Path,
+) -> Iterator[SkillWorkspace]:
+    """Restore a Build into a new private workspace; clean only that owned root.
+
+    The trusted executor must admit the current activation and binding first;
+    possession of Build bytes is not a grant to consume a platform resource.
+    Never merges into an existing project or a global Skill directory. Existing
+    user files require an executor-owned workspace composition step. The returned
+    paths are relative to the actual consumer cwd, not Worker cache locations.
+    """
+    requested = Path(workspace_directory)
+    if not requested.is_absolute():
+        raise ValueError("Skill consumer workspace must be absolute")
+    # Normalize platform aliases such as macOS /var while retaining exclusive
+    # creation of the final path. A pre-existing symlink or directory is rejected.
+    directory = requested.parent.resolve(strict=True) / requested.name
+    with tempfile.TemporaryDirectory(prefix=".skill-consumer-", dir=directory.parent) as temporary:
+        manifest, packages = restore_resource_build(
+            build_directory,
+            reference,
+            cache_directory=Path(temporary),
+        )
+        config = manifest.snapshot.binding(binding_id).config
+        if (
+            config.binding.resource.kind != "skill-space"
+            or config.selection_mode == "discovery"
+            or config.execution_mode == "isolated"
+        ):
+            raise SkillPackageError(
+                "Native file preparation requires an outer-agent pinned binding"
+            )
+        selected = packages.get(binding_id, [])
+        names = [package.ref.name for package in selected]
+        for package in selected:
+            for path in package.extract_dir.rglob("*"):
+                if path.is_file() and not path.is_relative_to(package.root_dir):
+                    raise SkillPackageError(
+                        "Archive contains files outside its selected Skill root"
+                    )
+        if len(set(name.casefold() for name in names)) != len(names) or any(
+            not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", name) for name in names
+        ):
+            raise SkillPackageError(
+                "Pinned Skill names cannot form unique safe consumer directories"
+            )
+        directory.mkdir(mode=0o700)
+        owned_identity = _identity(directory)
+        try:
+            skills_root = directory / ".agents" / "skills"
+            skills_root.mkdir(parents=True, mode=0o700)
+            prepared = []
+            for package in selected:
+                destination = skills_root / package.ref.name
+                # The verified extraction belongs exclusively to this preparation.
+                # Moving it retains complete resources and executable bits without
+                # copying from any mutable profile or user Skill directory.
+                package.root_dir.rename(destination)
+                prepared.append(
+                    PreparedSkill(
+                        package.ref.skill_id,
+                        package.ref.version_id,
+                        package.ref.content_hash.render(),
+                        destination.relative_to(directory).as_posix(),
+                    )
+                )
+            yield SkillWorkspace(directory, tuple(prepared))
+        finally:
+            if directory.exists() or directory.is_symlink():
+                if _identity(directory) != owned_identity:
+                    raise SkillPackageError("Skill workspace ownership changed; cleanup refused")
+                shutil.rmtree(directory)

ksadk/resource_runtime/skills.py

@@ -0,0 +1,215 @@
+"""Offline, Build-bound Skill directory and text resources for plugin consumers."""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import replace
+from pathlib import Path, PurePosixPath
+
+from pydantic import Field, field_validator
+
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.build_artifacts import ResourceBuildReference, restore_resource_build
+from ksadk.skills.loader import load_local_skill
+from ksadk.skills.package_store import SkillPackageError
+from ksadk.skills.runtime.base import SkillRuntimeBackend, SkillRuntimeResult
+from ksadk.skills.runtime.registry import match_skill_refs
+
+
+class SkillSelector(PluginContractModel):
+    skill_id: str = Field(strict=True, min_length=1, max_length=256)
+
+
+class SkillSearchQuery(PluginContractModel):
+    query: str = Field(strict=True, min_length=1, max_length=16000)
+    max_results: int = Field(default=10, strict=True, ge=1, le=32)
+
+
+class SkillExecutionQuery(PluginContractModel):
+    workflow_prompt: str = Field(strict=True, min_length=1, max_length=16000)
+    skill_ids: tuple[str, ...] = Field(min_length=1, max_length=32)
+
+    @field_validator("skill_ids")
+    @classmethod
+    def unique_ids(cls, values):
+        if len(set(values)) != len(values) or any(not item or len(item) > 256 for item in values):
+            raise ValueError("Execution requires unique Skill IDs")
+        return values
+
+
+class SkillResourceQuery(SkillSelector):
+    path: str = Field(strict=True, min_length=1, max_length=1024)
+    offset: int = Field(default=0, strict=True, ge=0, le=1024 * 1024)
+    max_chars: int = Field(default=16000, strict=True, ge=1, le=64000)
+
+    @field_validator("path")
+    @classmethod
+    def relative_path(cls, value: str) -> str:
+        path = PurePosixPath(value)
+        if (
+            path.is_absolute()
+            or "\\" in value
+            or "\x00" in value
+            or any(part in {"", ".", ".."} for part in value.split("/"))
+        ):
+            raise ValueError("Skill resource must use a canonical relative path")
+        return value
+
+
+class PinnedSkillService:
+    """The host supplies an admitted Build and binding; no remote catalog fallback.
+
+    Every operation revalidates saved Build bytes and the extraction cache. This
+    protects reproducibility, not hostile same-user processes during a read.
+    Paths returned in tool results are package-relative, never host locations.
+    """
+
+    def __init__(
+        self,
+        directory: Path,
+        reference: ResourceBuildReference,
+        *,
+        binding_id: str,
+        cache_directory: Path,
+    ):
+        self.directory = directory
+        self.reference = ResourceBuildReference.model_validate(reference.model_dump())
+        self.binding_id = binding_id
+        self.cache_directory = cache_directory
+        self._packages()
+
+    def _restore(self):
+        manifest, packages = restore_resource_build(
+            self.directory,
+            self.reference,
+            cache_directory=self.cache_directory,
+        )
+        binding = manifest.snapshot.binding(self.binding_id)
+        config = binding.config
+        if config.binding.resource.kind != "skill-space" or config.selection_mode == "discovery":
+            raise SkillPackageError("Pinned Skill service requires a pinned Skill binding")
+        return (
+            config,
+            {package.ref.skill_id: package for package in packages.get(self.binding_id, [])},
+            binding.skill_execution,
+        )
+
+    def _packages(self):
+        return self._restore()[1]
+
+    def execute(
+        self,
+        arguments: dict,
+        *,
+        backend: SkillRuntimeBackend,
+        operation_id: str,
+        timeout: int,
+    ) -> SkillRuntimeResult:
+        """Host-only post-approval adapter to an explicitly admitted Runtime.
+
+        The host selects the backend and owns artifact publication. The internal
+        result may contain host paths; it must not be sent directly as tool text.
+        This adapter grants no approval and does not select a backend from env.
+        """
+        query = SkillExecutionQuery.model_validate(arguments)
+        if not query.workflow_prompt.strip() or type(timeout) is not int or not 1 <= timeout <= 900:
+            raise ValueError("Invalid Skill execution budget or prompt")
+        if len(operation_id) != 64 or any(char not in "0123456789abcdef" for char in operation_id):
+            raise ValueError("Execution requires a durable operation ID")
+        config, packages, target = self._restore()
+        if config.execution_mode != "isolated":
+            raise ValueError("SKILL_EXECUTION_MODE_UNSUPPORTED")
+        if any(skill_id not in packages for skill_id in query.skill_ids):
+            raise ValueError("SKILL_NOT_BOUND")
+        selected = [packages[skill_id] for skill_id in query.skill_ids]
+        return backend.run_workflow(
+            query.workflow_prompt,
+            skill_space_ids=[],
+            session_id=operation_id,
+            skill_names=[package.ref.name for package in selected],
+            pinned_packages=selected,
+            timeout=min(timeout, target.timeout) if target is not None else timeout,
+        )
+
+    def list_skills(self, arguments: dict) -> dict:
+        if arguments:
+            raise ValueError("Pinned directory accepts no resource or space parameters")
+        packages = self._packages()
+        return {
+            "status": "ok",
+            "items": [
+                {
+                    "skillId": package.ref.skill_id,
+                    "versionId": package.ref.version_id,
+                    "name": package.ref.name,
+                    "contentHash": package.ref.content_hash.render(),
+                }
+                for package in sorted(packages.values(), key=lambda item: item.ref.skill_id)
+            ],
+            "truncated": False,
+        }
+
+    def read_resource(self, arguments: dict) -> dict:
+        query = SkillResourceQuery.model_validate(arguments)
+        package = self._packages().get(query.skill_id)
+        if package is None:
+            raise ValueError("SKILL_NOT_BOUND")
+        path = package.root_dir
+        for part in PurePosixPath(query.path).parts:
+            path = path / part
+            if path.is_symlink():
+                raise SkillPackageError("Skill resource cannot be a symbolic link")
+        descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        with os.fdopen(descriptor, "rb") as stream:
+            info = os.fstat(stream.fileno())
+            if not stat.S_ISREG(info.st_mode) or info.st_size > 1024 * 1024:
+                raise SkillPackageError("Skill text resource exceeds limit or is not a file")
+            raw = stream.read(1024 * 1024 + 1)
+        if len(raw) > 1024 * 1024:
+            raise SkillPackageError("Skill text resource exceeds limit")
+        content = raw.decode("utf-8")
+        end = min(len(content), query.offset + query.max_chars)
+        truncated = end < len(content)
+        return {
+            "status": "ok",
+            "skillId": query.skill_id,
+            "versionId": package.ref.version_id,
+            "contentHash": package.ref.content_hash.render(),
+            "path": query.path,
+            "content": content[query.offset : end],
+            "truncated": truncated,
+            "nextOffset": end if truncated else None,
+        }
+
+    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 = []
+        for package in self._packages().values():
+            if (package.root_dir / "SKILL.md").stat().st_size > 1024 * 1024:
+                raise SkillPackageError("Skill document exceeds text limit")
+            document = load_local_skill(package.root_dir)
+            refs.append(replace(package.ref, description=document.description[:8192]))
+        matches = match_skill_refs(refs, query.query)
+        return {
+            "status": "ok",
+            "truncated": len(matches) > query.max_results,
+            "items": [
+                {
+                    "skillId": match.skill.skill_id,
+                    "name": match.skill.name,
+                    "versionId": match.skill.version_id,
+                    "contentHash": match.skill.content_hash.render(),
+                    "description": match.skill.description,
+                    "score": match.score,
+                    "reason": match.reason,
+                }
+                for match in matches[: query.max_results]
+            ],
+        }
+
+    def load_skill(self, arguments: dict) -> dict:
+        selector = SkillSelector.model_validate(arguments)
+        return self.read_resource({"skillId": selector.skill_id, "path": "SKILL.md"})