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

ksadk/skills/runtime/backends/local.py

@@ -8,13 +8,17 @@ import tempfile
 import time
 from pathlib import Path
 
+from ksadk.skills.package_store import SkillPackage
+from ksadk.skills.runtime.artifact_delivery import export_artifacts, import_artifacts
 from ksadk.skills.runtime.base import (
     SandboxInputFile,
+    SkillRuntimeError,
     SkillRuntimeResult,
     format_skill_names_env,
     normalize_skill_names,
     parse_output_files,
 )
+from ksadk.skills.runtime.pinned import stage_packages
 
 
 def _coerce_output(value: str | bytes | None) -> str:
@@ -45,14 +49,29 @@ class LocalProcessSkillRuntimeBackend:
         skill_names: list[str] | None = None,
         env: dict[str, str] | None = None,
         input_files: list[SandboxInputFile] | None = None,
+        pinned_packages: list[SkillPackage] | None = None,
         timeout: int = 900,
     ) -> SkillRuntimeResult:
         started = time.monotonic()
-        runtime_env = os.environ.copy()
+        if pinned_packages is not None and self.agent_path.resolve() != (
+            Path(__file__).resolve().parents[1] / "agent.py"
+        ):
+            raise ValueError("Pinned Skill execution requires the bundled runtime agent")
+        runtime_env = (
+            {
+                key: value
+                for key, value in os.environ.items()
+                if key in {"PATH", "LANG", "LC_ALL", "TMPDIR", "SYSTEMROOT"}
+            }
+            if pinned_packages is not None
+            else os.environ.copy()
+        )
         runtime_env.update(env or {})
         runtime_env["KSADK_SKILL_SPACE_IDS"] = ",".join(skill_space_ids)
         runtime_env["SKILL_SPACE_ID"] = skill_space_ids[0] if skill_space_ids else ""
-        if public_spaces := os.environ.get("KSADK_PUBLIC_SKILL_SPACE_IDS"):
+        if pinned_packages is None and (
+            public_spaces := os.environ.get("KSADK_PUBLIC_SKILL_SPACE_IDS")
+        ):
             runtime_env["KSADK_PUBLIC_SKILL_SPACE_IDS"] = public_spaces
         selected_skill_names = format_skill_names_env(skill_names)
         if selected_skill_names:
@@ -62,12 +81,27 @@ class LocalProcessSkillRuntimeBackend:
         try:
             with tempfile.TemporaryDirectory(prefix="ksadk-skill-runtime-") as tmp_dir:
                 request_path = Path(tmp_dir) / "workflow-request.json"
+                request = {
+                    "workflow_prompt": workflow_prompt,
+                    "skill_names": normalize_skill_names(skill_names),
+                }
+                if pinned_packages is not None:
+                    entries = stage_packages(pinned_packages, Path(tmp_dir))
+                    request["pinned_packages"] = [entry.model_dump() for entry in entries]
+                    request["pinned_protocol_version"] = 1
+                    if not runtime_env.get("KSADK_SKILL_WORKDIR"):
+                        # Artifacts outlive the temporary archive delivery directory.
+                        runtime_env["KSADK_SKILL_WORKDIR"] = tempfile.mkdtemp(
+                            prefix="ksadk-pinned-artifacts-"
+                        )
+                    # Use the same canonical root in the child and host validator
+                    # (macOS temporary directories may be reached through /var).
+                    runtime_env["KSADK_SKILL_WORKDIR"] = str(
+                        Path(runtime_env["KSADK_SKILL_WORKDIR"]).resolve()
+                    )
                 request_path.write_text(
                     json.dumps(
-                        {
-                            "workflow_prompt": workflow_prompt,
-                            "skill_names": normalize_skill_names(skill_names),
-                        },
+                        request,
                         ensure_ascii=False,
                     ),
                     encoding="utf-8",
@@ -75,6 +109,7 @@ class LocalProcessSkillRuntimeBackend:
                 completed = subprocess.run(
                     [
                         sys.executable,
+                        *(["-I"] if pinned_packages is not None else []),
                         "-u",
                         str(self.agent_path),
                         "--request-file",
@@ -86,13 +121,43 @@ class LocalProcessSkillRuntimeBackend:
                     env=runtime_env,
                     check=False,
                 )
+                stdout = completed.stdout
+                output_files = parse_output_files(stdout)
+                if pinned_packages is not None:
+                    payloads = [
+                        json.loads(line.split("=", 1)[1])
+                        for line in stdout.splitlines()
+                        if line.startswith("workflow_result=")
+                    ]
+                    if len(payloads) != 1 or not isinstance(payloads[0], dict):
+                        raise SkillRuntimeError("Runtime did not return a unique workflow result")
+                    payload = payloads[0]
+                    paths = payload.get("output_files")
+                    if not isinstance(paths, list) or any(not isinstance(p, str) for p in paths):
+                        raise SkillRuntimeError("Runtime returned invalid artifact paths")
+                    # Snapshot only bounded regular files from the admitted workspace.
+                    # A workflow's stdout is not authority to read arbitrary host files.
+                    bundle_path = Path(tmp_dir) / "artifacts.zip"
+                    receipt = export_artifacts(
+                        paths, Path(runtime_env["KSADK_SKILL_WORKDIR"]), bundle_path
+                    )
+                    output_files = import_artifacts(bundle_path.read_bytes(), receipt)
+                    payload["output_files"] = output_files
+                    payload["artifacts"] = output_files
+                    payload["artifact_bundle"] = receipt.model_dump()
+                    stdout = "\n".join(
+                        "workflow_result=" + json.dumps(payload, ensure_ascii=False, sort_keys=True)
+                        if line.startswith("workflow_result=")
+                        else line
+                        for line in stdout.splitlines()
+                    ) + "\n"
             return SkillRuntimeResult(
                 runtime_id=f"local:{session_id}",
                 exit_code=completed.returncode,
-                stdout=completed.stdout,
+                stdout=stdout,
                 stderr=completed.stderr,
                 duration_ms=int((time.monotonic() - started) * 1000),
-                output_files=parse_output_files(completed.stdout),
+                output_files=output_files,
             )
         except subprocess.TimeoutExpired as exc:
             return SkillRuntimeResult(

ksadk/skills/runtime/base.py

@@ -5,6 +5,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Protocol, Sequence
 
+from ksadk.skills.package_store import SkillPackage
+
 
 class SkillRuntimeError(RuntimeError):
     pass
@@ -56,6 +58,7 @@ class SkillRuntimeBackend(Protocol):
         skill_names: list[str] | None = None,
         env: dict[str, str] | None = None,
         input_files: list[SandboxInputFile] | None = None,
+        pinned_packages: list[SkillPackage] | None = None,
         timeout: int = 900,
     ) -> SkillRuntimeResult: ...
 

ksadk/skills/runtime/executor.py

@@ -27,6 +27,7 @@ class WorkflowExecution:
     artifacts: list[str] = field(default_factory=list)
     warnings: list[str] = field(default_factory=list)
     error: str = ""
+    artifact_bundle: dict[str, object] | None = None
 
 
 def execute_workflow(
@@ -136,6 +137,7 @@ def _run_generic_workflow(skill: LocalSkill, prompt: str) -> WorkflowExecution:
     workdir = _skill_workdir()
     workdir.mkdir(parents=True, exist_ok=True)
     output_dir = workdir / "artifacts"
+    output_dir.mkdir(parents=True, exist_ok=True)
     timeout = _runtime_timeout()
     command = _run_command(
         ["bash", str(skill.root_dir / "scripts" / "run-workflow.sh")],

ksadk/skills/runtime/loader.py

@@ -49,10 +49,14 @@ def load_skills(
     seen_names: set[str] = {skill.name.lower() for skill in skills if skill.name}
     for space_id in registry.user_skill_space_ids():
         listing = client.list_skills_by_space_id(space_id)
+        if listing.truncated:
+            warnings.append(
+                "Skill directory is incomplete; selection covers only retrieved entries"
+            )
         selected_refs.extend(
             registry.dedupe_skill_refs(
                 registry.select_remote_skill_refs(
-                    listing.active_skills(),
+                    listing.active_skills(allow_partial=True),
                     prompt,
                     skill_names=skill_names,
                 ),
@@ -62,9 +66,13 @@ def load_skills(
 
     if registry.public_skill_space_ids():
         listing = client.list_available_premade_skills()
+        if listing.truncated:
+            warnings.append(
+                "Public Skill directory is incomplete; selection covers only retrieved entries"
+            )
         selected_refs.extend(
             registry.dedupe_skill_refs(
-                registry.select_public_skill_refs(listing.active_skills()),
+                registry.select_public_skill_refs(listing.active_skills(allow_partial=True)),
                 seen_names=seen_names,
             )
         )

ksadk/skills/runtime/pinned.py

@@ -0,0 +1,114 @@
+"""Transport and consume exact Skill archives without directory discovery.
+
+The trusted caller authorizes the package set before staging. This contract
+verifies bytes at the consumer; it is not an authorization or sandbox boundary.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.skills.loader import LocalSkill, load_local_skill
+from ksadk.skills.models import ContentHash, SkillRef
+from ksadk.skills.package_store import PackageStore, SkillPackage, SkillPackageError
+
+MAX_ARCHIVE_BYTES = 20 * 1024 * 1024
+MAX_PACKAGES = 32
+PINNED_PACKAGE_PROTOCOL_VERSION = 1
+
+
+class PinnedSkillArchive(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
+
+    skill_id: str = Field(min_length=1, max_length=256, strict=True)
+    version_id: str = Field(min_length=1, max_length=256, strict=True)
+    name: str = Field(min_length=1, max_length=256, strict=True)
+    content_hash: str = Field(pattern=r"^sha256:[0-9a-f]{64}$", strict=True)
+    archive_name: str = Field(pattern=r"^[0-9a-f]{64}\.zip$", strict=True)
+
+    def skill_ref(self) -> SkillRef:
+        return SkillRef(
+            skill_id=self.skill_id,
+            version_id=self.version_id,
+            version="",
+            name=self.name,
+            content_hash=ContentHash.parse(self.content_hash),
+        )
+
+
+def read_archive(path: Path) -> bytes:
+    """Read a bounded regular archive, rejecting a symlink at the final component."""
+    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 > MAX_ARCHIVE_BYTES:
+            raise SkillPackageError("Pinned Skill archive is not a bounded regular file")
+        content = stream.read(MAX_ARCHIVE_BYTES + 1)
+    if len(content) > MAX_ARCHIVE_BYTES:
+        raise SkillPackageError("Pinned Skill archive exceeds size limit")
+    return content
+
+
+def validate_package_set(entries: tuple[PinnedSkillArchive, ...]) -> None:
+    if len(entries) > MAX_PACKAGES:
+        raise SkillPackageError("Too many pinned Skill packages")
+    if len({entry.skill_id for entry in entries}) != len(entries) or len(
+        {entry.name.casefold() for entry in entries}
+    ) != len(entries):
+        raise SkillPackageError("Pinned Skill identities and names must be unique")
+
+
+def stage_packages(packages: list[SkillPackage], directory: Path) -> tuple[PinnedSkillArchive, ...]:
+    """Copy verified archives into a private request delivery directory."""
+    if len(packages) > MAX_PACKAGES:
+        raise SkillPackageError("Too many pinned Skill packages")
+    entries = tuple(
+        PinnedSkillArchive(
+            skill_id=package.ref.skill_id,
+            version_id=package.ref.version_id,
+            name=package.ref.name,
+            content_hash=package.ref.content_hash.render() if package.ref.content_hash else "",
+            archive_name=(package.ref.content_hash.value if package.ref.content_hash else "")
+            + ".zip",
+        )
+        for package in packages
+    )
+    validate_package_set(entries)
+    for package, entry in zip(packages, entries, strict=True):
+        content = read_archive(package.archive_path)
+        if "sha256:" + hashlib.sha256(content).hexdigest() != entry.content_hash:
+            raise SkillPackageError("Pinned Skill archive digest mismatch")
+        target = directory / entry.archive_name
+        if target.exists():
+            if read_archive(target) != content:
+                raise SkillPackageError("Pinned Skill archive destination conflict")
+            continue
+        with target.open("xb") as output:
+            os.chmod(target, 0o600)
+            output.write(content)
+    return entries
+
+
+def load_pinned_packages(
+    entries: tuple[PinnedSkillArchive, ...], directory: Path
+) -> list[LocalSkill]:
+    """Use only supplied archives; never read environment Skill directories or APIs."""
+    validate_package_set(entries)
+    store = PackageStore(
+        directory / "extracted-packages", namespace="pinned-request", require_hash=True
+    )
+    skills = []
+    for entry in entries:
+        package = store.store_archive(
+            entry.skill_ref(), read_archive(directory / entry.archive_name)
+        )
+        skill = load_local_skill(package.root_dir)
+        if skill.name != entry.name:
+            raise SkillPackageError("Pinned Skill name does not match its manifest")
+        skills.append(skill)
+    return skills

ksadk/skills/runtime/request.py

@@ -5,7 +5,11 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from pydantic import ValidationError
+
+from ksadk.skills.package_store import SkillPackageError
 from ksadk.skills.runtime.base import normalize_skill_names
+from ksadk.skills.runtime.pinned import PinnedSkillArchive, validate_package_set
 
 
 class SkillWorkflowRequestError(ValueError):
@@ -16,6 +20,9 @@ class SkillWorkflowRequestError(ValueError):
 class SkillWorkflowRequest:
     workflow_prompt: str = ""
     skill_names: list[str] = field(default_factory=list)
+    pinned_packages: tuple[PinnedSkillArchive, ...] | None = None
+    package_directory: Path | None = None
+    collect_artifacts: bool = False
 
 
 def parse_workflow_request(argv: list[str]) -> SkillWorkflowRequest:
@@ -56,9 +63,33 @@ def _request_from_json_file(path: str) -> SkillWorkflowRequest:
         raise SkillWorkflowRequestError("request file must contain a JSON object")
     prompt = payload.get("workflow_prompt", payload.get("prompt", ""))
     skill_names = _skill_names_from_payload(payload)
+    pinned_packages = None
+    if "pinned_protocol_version" in payload and "pinned_packages" not in payload:
+        raise SkillWorkflowRequestError("Pinned Skill manifest is missing")
+    if "pinned_packages" in payload:
+        version = payload.get("pinned_protocol_version")
+        if type(version) is not int or version != 1:
+            raise SkillWorkflowRequestError("Unsupported pinned Skill protocol version")
+        raw = payload["pinned_packages"]
+        if not isinstance(raw, list):
+            raise SkillWorkflowRequestError("pinned_packages must be an array")
+        try:
+            pinned_packages = tuple(PinnedSkillArchive.model_validate(item) for item in raw)
+            validate_package_set(pinned_packages)
+        except (ValidationError, SkillPackageError):
+            raise SkillWorkflowRequestError("Invalid pinned Skill manifest") from None
+        allowed = {entry.name.casefold() for entry in pinned_packages}
+        if any(name.casefold() not in allowed for name in skill_names):
+            raise SkillWorkflowRequestError("Selected Skill is not in the pinned manifest")
+    collect_artifacts = payload.get("collect_artifacts", False)
+    if type(collect_artifacts) is not bool or (collect_artifacts and pinned_packages is None):
+        raise SkillWorkflowRequestError("Artifact collection requires a pinned request")
     return SkillWorkflowRequest(
         workflow_prompt=str(prompt or ""),
         skill_names=skill_names,
+        pinned_packages=pinned_packages,
+        package_directory=Path(path).resolve().parent if pinned_packages is not None else None,
+        collect_artifacts=collect_artifacts,
     )