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

ksadk/skills/package_store.py

@@ -1,10 +1,21 @@
 from __future__ import annotations
 
 import hashlib
+import json
+import os
 import shutil
+import stat
+import tempfile
+import threading
 import zipfile
+from contextlib import contextmanager
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path, PurePosixPath
+
+try:
+    import fcntl
+except ImportError:  # Windows legacy callers retain in-process synchronization.
+    fcntl = None
 
 from ksadk.skills.models import SkillRef
 
@@ -23,60 +34,128 @@ class SkillPackage:
 
 
 class PackageStore:
-    def __init__(self, cache_dir: str | Path):
+    def __init__(
+        self,
+        cache_dir: str | Path,
+        *,
+        namespace: str = "",
+        require_hash: bool = False,
+        max_archive_bytes: int = 20 * 1024 * 1024,
+        max_extracted_bytes: int = 100 * 1024 * 1024,
+        max_files: int = 2000,
+    ):
+        if any(
+            type(value) is not int or value < 1
+            for value in (max_archive_bytes, max_extracted_bytes, max_files)
+        ):
+            raise ValueError("Skill package limits must be positive integers")
+        if require_hash and (not namespace or fcntl is None):
+            raise ValueError("Verified package stores require a namespace and process locking")
         self.cache_dir = Path(cache_dir)
-        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.cache_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.namespace = namespace
+        self.require_hash = require_hash
+        self.max_archive_bytes = max_archive_bytes
+        self.max_extracted_bytes = max_extracted_bytes
+        self.max_files = max_files
+        self._thread_lock = threading.RLock()
 
     def store_archive(self, ref: SkillRef, content: bytes) -> SkillPackage:
         self._verify_hash(ref, content)
-        skill_dir = self._skill_dir(ref)
-        archive_path = skill_dir / "archive.zip"
-        extract_dir = skill_dir / "extracted"
-
-        if archive_path.exists() and extract_dir.exists():
-            cached = self.get_cached(ref)
+        with self._locked(ref):
+            cached = self._get_cached(ref)
             if cached is not None:
                 return cached
-
-        if skill_dir.exists():
-            shutil.rmtree(skill_dir)
-        skill_dir.mkdir(parents=True, exist_ok=True)
-        archive_path.write_bytes(content)
-        extract_dir.mkdir(parents=True, exist_ok=True)
-        self._safe_extract(archive_path, extract_dir)
-
-        return SkillPackage(
-            ref=ref,
-            archive_path=archive_path,
-            extract_dir=extract_dir,
-            root_dir=self._find_skill_root(extract_dir),
-            cache_hit=False,
-        )
+            skill_dir = self._skill_dir(ref)
+            stage = Path(tempfile.mkdtemp(prefix=".stage-", dir=self.cache_dir))
+            try:
+                (stage / "archive.zip").write_bytes(content)
+                os.chmod(stage / "archive.zip", 0o600)
+                extracted = stage / "extracted"
+                extracted.mkdir(mode=0o700)
+                self._safe_extract(stage / "archive.zip", extracted)
+                self._find_skill_root(extracted)
+                # Publish only a complete validated tree, under the per-key lock.
+                if skill_dir.is_symlink() or skill_dir.is_file():
+                    skill_dir.unlink()
+                elif skill_dir.exists():
+                    shutil.rmtree(skill_dir)
+                os.replace(stage, skill_dir)
+            except (OSError, zipfile.BadZipFile, RuntimeError, ValueError) as error:
+                raise SkillPackageError("Skill archive could not be safely materialized") from error
+            finally:
+                if stage.exists():
+                    shutil.rmtree(stage)
+            return self._package(ref, skill_dir, cache_hit=False)
 
     def get_cached(self, ref: SkillRef) -> SkillPackage | None:
+        with self._locked(ref):
+            return self._get_cached(ref)
+
+    def _get_cached(self, ref: SkillRef) -> SkillPackage | None:
         skill_dir = self._skill_dir(ref)
         archive_path = skill_dir / "archive.zip"
         extract_dir = skill_dir / "extracted"
-        if not archive_path.exists() or not extract_dir.exists():
+        if (
+            skill_dir.is_symlink()
+            or archive_path.is_symlink()
+            or extract_dir.is_symlink()
+            or not archive_path.is_file()
+            or not extract_dir.is_dir()
+        ):
             return None
-        content = archive_path.read_bytes()
         try:
+            if archive_path.stat().st_size > self.max_archive_bytes:
+                return None
+            content = archive_path.read_bytes()
             self._verify_hash(ref, content)
-        except SkillPackageError:
+            self._verify_tree(archive_path, extract_dir)
+            return self._package(ref, skill_dir, cache_hit=True)
+        except (RuntimeError, OSError, zipfile.BadZipFile, ValueError):
             return None
+
+    def _package(self, ref: SkillRef, skill_dir: Path, *, cache_hit: bool) -> SkillPackage:
         return SkillPackage(
             ref=ref,
-            archive_path=archive_path,
-            extract_dir=extract_dir,
-            root_dir=self._find_skill_root(extract_dir),
-            cache_hit=True,
+            archive_path=skill_dir / "archive.zip",
+            extract_dir=skill_dir / "extracted",
+            root_dir=self._find_skill_root(skill_dir / "extracted"),
+            cache_hit=cache_hit,
         )
 
     def _skill_dir(self, ref: SkillRef) -> Path:
-        return self.cache_dir / (ref.cache_key or ref.name or "skill")
+        identity = [
+            self.namespace,
+            ref.skill_id,
+            ref.version_id,
+            ref.version,
+            ref.name,
+            ref.content_hash.render() if ref.content_hash else "",
+        ]
+        key = hashlib.sha256(json.dumps(identity, ensure_ascii=False).encode()).hexdigest()
+        return self.cache_dir / key
+
+    @contextmanager
+    def _locked(self, ref: SkillRef):
+        with self._thread_lock:
+            if fcntl is None:
+                yield
+                return
+            path = self._skill_dir(ref).with_suffix(".lock")
+            fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+            with os.fdopen(fd, "rb") as lock:
+                fcntl.flock(lock, fcntl.LOCK_EX)
+                try:
+                    yield
+                finally:
+                    fcntl.flock(lock, fcntl.LOCK_UN)
 
     def _verify_hash(self, ref: SkillRef, content: bytes) -> None:
+        if len(content) > self.max_archive_bytes:
+            raise SkillPackageError("Skill archive exceeds size limit")
         if not ref.content_hash:
+            if self.require_hash:
+                raise SkillPackageError("Verified Skill packages require ContentHash")
             return
         if ref.content_hash.algorithm != "sha256":
             raise SkillPackageError(
@@ -90,13 +169,82 @@ class PackageStore:
             )
 
     def _safe_extract(self, archive_path: Path, extract_dir: Path) -> None:
-        base = extract_dir.resolve()
+        expanded = 0
+        with zipfile.ZipFile(archive_path) as archive:
+            for member, relative in self._members(archive):
+                target = extract_dir / relative
+                target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+                if member.is_dir():
+                    target.mkdir(exist_ok=True, mode=0o700)
+                    continue
+                with archive.open(member) as source, target.open("xb") as destination:
+                    written = 0
+                    while chunk := source.read(64 * 1024):
+                        written += len(chunk)
+                        expanded += len(chunk)
+                        if written > member.file_size or expanded > self.max_extracted_bytes:
+                            raise SkillPackageError("Expanded Skill package exceeds limits")
+                        destination.write(chunk)
+                os.chmod(target, 0o700 if (member.external_attr >> 16) & 0o111 else 0o600)
+
+    def _members(self, archive: zipfile.ZipFile):
+        members = archive.infolist()
+        if (
+            len(members) > self.max_files
+            or sum(item.file_size for item in members) > self.max_extracted_bytes
+        ):
+            raise SkillPackageError("Expanded Skill package exceeds limits")
+        seen = set()
+        result = []
+        for member in members:
+            relative = PurePosixPath(member.filename)
+            kind = stat.S_IFMT(member.external_attr >> 16)
+            if (
+                not relative.parts
+                or relative.is_absolute()
+                or ".." in relative.parts
+                or "\\" in member.filename
+                or ":" in member.filename
+                or "\x00" in member.orig_filename
+                or kind not in (0, stat.S_IFREG, stat.S_IFDIR)
+                or relative in seen
+                or member.flag_bits & 1
+            ):
+                raise SkillPackageError("Unsafe Skill archive member")
+            seen.add(relative)
+            result.append((member, relative))
+        return result
+
+    def _verify_tree(self, archive_path: Path, extract_dir: Path) -> None:
+        expected = set()
         with zipfile.ZipFile(archive_path) as archive:
-            for member in archive.infolist():
-                target = (extract_dir / member.filename).resolve()
-                if not str(target).startswith(str(base) + "/") and target != base:
-                    raise SkillPackageError(f"unsafe zip member: {member.filename}")
-            archive.extractall(extract_dir)
+            for member, relative in self._members(archive):
+                expected.update(
+                    parent for parent in relative.parents if parent != PurePosixPath(".")
+                )
+                expected.add(relative)
+                target = extract_dir / relative
+                if any((extract_dir / parent).is_symlink() for parent in relative.parents):
+                    raise SkillPackageError("Skill cache contains a linked parent")
+                if target.is_symlink():
+                    raise SkillPackageError("Skill cache contains a link")
+                if member.is_dir():
+                    if not target.is_dir():
+                        raise SkillPackageError("Skill cache directory missing")
+                    continue
+                if not target.is_file() or target.stat().st_size != member.file_size:
+                    raise SkillPackageError("Skill cache file changed")
+                with archive.open(member) as source, target.open("rb") as current:
+                    while chunk := source.read(64 * 1024):
+                        if chunk != current.read(len(chunk)):
+                            raise SkillPackageError("Skill cache content changed")
+        actual = set()
+        for path in extract_dir.rglob("*"):
+            if path.is_symlink():
+                raise SkillPackageError("Skill cache contains a link")
+            actual.add(PurePosixPath(path.relative_to(extract_dir).as_posix()))
+        if actual != expected:
+            raise SkillPackageError("Skill cache file set changed")
 
     def _find_skill_root(self, extract_dir: Path) -> Path:
         if (extract_dir / "SKILL.md").exists():

ksadk/skills/runtime/agent.py

@@ -13,6 +13,7 @@ from ksadk.skills.models import SkillRef
 from ksadk.skills.package_store import PackageStore
 from ksadk.skills.runtime import loader as runtime_loader
 from ksadk.skills.runtime import registry as runtime_registry
+from ksadk.skills.runtime.artifact_delivery import export_artifacts
 from ksadk.skills.runtime.base import normalize_skill_names
 from ksadk.skills.runtime.executor import (
     WorkflowExecution,
@@ -36,12 +37,18 @@ from ksadk.skills.runtime.executor import (
 from ksadk.skills.runtime.executor import (
     _tail as _executor_tail,
 )
+from ksadk.skills.runtime.pinned import (
+    PINNED_PACKAGE_PROTOCOL_VERSION as PINNED_PACKAGE_PROTOCOL_VERSION,
+)
+from ksadk.skills.runtime.pinned import load_pinned_packages
 from ksadk.skills.runtime.request import (
     SkillWorkflowRequest,
     SkillWorkflowRequestError,
     parse_workflow_request,
 )
 
+ARTIFACT_DELIVERY_PROTOCOL_VERSION = 1
+
 
 def _skill_space_ids() -> list[str]:
     return runtime_registry.skill_space_ids()
@@ -126,13 +133,31 @@ def run_agent(
         return 1
 
     prompt = request.workflow_prompt
-    selected_skill_names = request.skill_names or _selected_skill_names()
-    loaded_skills = _load_skills(
-        prompt=prompt,
-        skill_names=selected_skill_names,
-        service_transport=service_transport,
-    )
+    selected_skill_names = request.skill_names
+    if request.pinned_packages is not None:
+        if request.package_directory is None:
+            raise SkillWorkflowRequestError("Pinned Skill delivery directory is missing")
+        loaded_skills = load_pinned_packages(request.pinned_packages, request.package_directory)
+    else:
+        selected_skill_names = selected_skill_names or _selected_skill_names()
+        loaded_skills = _load_skills(
+            prompt=prompt,
+            skill_names=selected_skill_names,
+            service_transport=service_transport,
+        )
     execution = _execute_workflow(prompt, loaded_skills, selected_skill_names=selected_skill_names)
+    if request.collect_artifacts and request.package_directory is not None:
+        try:
+            root = Path(os.environ.get("KSADK_SKILL_WORKDIR") or "/tmp/ksadk-skill-workflow")
+            receipt = export_artifacts(
+                execution.output_files, root, request.package_directory / "artifacts.zip"
+            )
+            execution.artifact_bundle = receipt.model_dump()
+        except Exception:
+            execution.status = "failed"
+            execution.error = "Skill artifact delivery failed"
+            execution.output_files = []
+            execution.artifacts = []
     print(f"workflow={prompt}")
     print(f"skill_spaces={','.join(_skill_space_ids())}")
     print(f"loaded_skills={','.join(skill.name for skill in loaded_skills)}")

ksadk/skills/runtime/artifact_delivery.py

@@ -0,0 +1,139 @@
+"""Bounded, verified artifact delivery before a Skill sandbox is destroyed."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import shutil
+import stat
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+
+from pydantic import BaseModel, ConfigDict, Field
+
+MAX_FILES = 100
+MAX_FILE_BYTES = 20 * 1024 * 1024
+MAX_TOTAL_BYTES = 100 * 1024 * 1024
+MAX_BUNDLE_BYTES = MAX_TOTAL_BYTES + 1024 * 1024
+
+
+class ArtifactDeliveryError(ValueError):
+    pass
+
+
+class ArtifactBundle(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
+
+    sha256: str = Field(pattern=r"^[0-9a-f]{64}$", strict=True)
+    size: int = Field(ge=0, le=MAX_BUNDLE_BYTES, strict=True)
+    file_count: int = Field(ge=0, le=MAX_FILES, strict=True)
+
+
+def _name(raw: str) -> str:
+    path = PurePosixPath(raw)
+    if (
+        not raw
+        or len(raw) > 512
+        or path.is_absolute()
+        or ".." in path.parts
+        or "\\" in raw
+        or ":" in raw
+        or "\x00" in raw
+        or str(path) != raw
+        or raw == "."
+    ):
+        raise ArtifactDeliveryError("Invalid artifact relative path")
+    return raw
+
+
+def export_artifacts(paths: list[str], root: Path, destination: Path) -> ArtifactBundle:
+    """Only export regular files under the execution workspace, never symlinks."""
+    if len(paths) > MAX_FILES:
+        raise ArtifactDeliveryError("Too many artifacts")
+    root = root.resolve()
+    total = 0
+    names = set()
+    opened = zipfile.ZipFile(destination, "x", compression=zipfile.ZIP_STORED)
+    try:
+        with opened as archive:
+            for raw in paths:
+                path = Path(raw)
+                if not path.is_absolute():
+                    path = root / path
+                try:
+                    relative = path.relative_to(root)
+                    name = _name(relative.as_posix())
+                except ValueError:
+                    raise ArtifactDeliveryError(
+                        "Artifact is outside the execution workspace"
+                    ) from None
+                if name in names:
+                    raise ArtifactDeliveryError("Duplicate artifact path")
+                names.add(name)
+                current = root
+                for part in relative.parts:
+                    current = current / part
+                    if current.is_symlink():
+                        raise ArtifactDeliveryError("Artifact links are not allowed")
+                descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+                with os.fdopen(descriptor, "rb") as source:
+                    info = os.fstat(source.fileno())
+                    if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_FILE_BYTES:
+                        raise ArtifactDeliveryError("Artifact is not a bounded regular file")
+                    content = source.read(MAX_FILE_BYTES + 1)
+                total += len(content)
+                if len(content) > MAX_FILE_BYTES or total > MAX_TOTAL_BYTES:
+                    raise ArtifactDeliveryError("Artifact size limit exceeded")
+                archive.writestr(name, content)
+        os.chmod(destination, 0o600)
+        content = destination.read_bytes()
+        return ArtifactBundle(
+            sha256=hashlib.sha256(content).hexdigest(), size=len(content), file_count=len(names)
+        )
+    except Exception:
+        destination.unlink(missing_ok=True)
+        raise
+
+
+def import_artifacts(
+    content: bytes, receipt: ArtifactBundle, *, parent: Path | None = None
+) -> list[str]:
+    """Verify the full bundle before publishing any consumer-visible paths."""
+    if len(content) != receipt.size or hashlib.sha256(content).hexdigest() != receipt.sha256:
+        raise ArtifactDeliveryError("Artifact bundle integrity mismatch")
+    directory = Path(tempfile.mkdtemp(prefix="ksadk-skill-artifacts-", dir=parent))
+    try:
+        with zipfile.ZipFile(io.BytesIO(content)) as archive:
+            entries = archive.infolist()
+            if len(entries) != receipt.file_count:
+                raise ArtifactDeliveryError("Artifact file count mismatch")
+            total = 0
+            names = set()
+            outputs = []
+            for entry in entries:
+                name = _name(entry.filename)
+                mode = entry.external_attr >> 16
+                if name in names or entry.is_dir() or stat.S_IFMT(mode) not in {0, stat.S_IFREG}:
+                    raise ArtifactDeliveryError("Artifact bundle contains invalid file entries")
+                names.add(name)
+                total += entry.file_size
+                if entry.file_size > MAX_FILE_BYTES or total > MAX_TOTAL_BYTES:
+                    raise ArtifactDeliveryError("Artifact size limit exceeded")
+                with archive.open(entry) as source:
+                    data = source.read(MAX_FILE_BYTES + 1)
+                if len(data) != entry.file_size or len(data) > MAX_FILE_BYTES:
+                    raise ArtifactDeliveryError("Artifact size mismatch")
+                target = directory / name
+                target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+                with target.open("xb") as output:
+                    os.chmod(target, 0o600)
+                    output.write(data)
+                outputs.append(str(target))
+        if not outputs:
+            directory.rmdir()
+        return outputs
+    except Exception:
+        shutil.rmtree(directory)
+        raise

ksadk/skills/runtime/backends/e2b.py

@@ -2,7 +2,10 @@ from __future__ import annotations
 
 import json
 import os
+import secrets
+import tempfile
 import time
+from pathlib import Path, PurePosixPath
 from typing import Any
 
 from ksadk.sandbox import (
@@ -12,6 +15,9 @@ from ksadk.sandbox import (
 from ksadk.sandbox import (
     SandboxInputFile as RuntimeSandboxInputFile,
 )
+from ksadk.sandbox.e2b_connection import ExplicitE2BConnection
+from ksadk.skills.package_store import SkillPackage
+from ksadk.skills.runtime.artifact_delivery import ArtifactBundle, import_artifacts
 from ksadk.skills.runtime.base import (
     SandboxInputFile,
     SkillRuntimeError,
@@ -20,6 +26,7 @@ from ksadk.skills.runtime.base import (
     normalize_skill_names,
     parse_output_files,
 )
+from ksadk.skills.runtime.pinned import read_archive, stage_packages
 
 
 def _bool_env(name: str, default: bool = True) -> bool:
@@ -48,6 +55,10 @@ def _redact(value: str) -> str:
 
 
 class E2BSkillRuntimeBackend:
+    def preflight(self) -> None:
+        """Read-only local dependency check; does not prove upstream authorization."""
+        self.sandbox_backend.check_available()
+
     def __init__(
         self,
         *,
@@ -55,6 +66,8 @@ class E2BSkillRuntimeBackend:
         template_id: str,
         timeout: int = 900,
         allow_internet_access: bool = True,
+        connection: ExplicitE2BConnection | None = None,
+        artifact_directory: Path | None = None,
     ):
         if not template_id:
             raise SkillRuntimeError(
@@ -64,6 +77,7 @@ class E2BSkillRuntimeBackend:
         self.template_id = template_id
         self.timeout = timeout
         self.allow_internet_access = allow_internet_access
+        self.artifact_directory = artifact_directory
         self.sandbox_backend = E2BSandboxBackend(
             spec=SandboxSpec(
                 template_id=template_id,
@@ -72,6 +86,7 @@ class E2BSkillRuntimeBackend:
                 metadata={"component": "skill-runtime"},
             ),
             sandbox_cls=sandbox_cls,
+            connection=connection,
         )
 
     @classmethod
@@ -109,17 +124,31 @@ class E2BSkillRuntimeBackend:
         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:
         session = None
         started = time.monotonic()
         effective_timeout = timeout or self.timeout
         try:
+            if pinned_packages is not None:
+                for item in input_files or []:
+                    target = PurePosixPath(item.target_path)
+                    if (
+                        not target.is_relative_to("/workspace/inputs")
+                        or ".." in target.parts
+                        or "\\" in item.target_path
+                    ):
+                        raise SkillRuntimeError(
+                            "Pinned Skill inputs must be under /workspace/inputs"
+                        )
             sandbox_env = {
                 "KSADK_SKILL_SPACE_IDS": ",".join(skill_space_ids),
                 "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")
+            ):
                 sandbox_env["KSADK_PUBLIC_SKILL_SPACE_IDS"] = public_spaces
             selected_skill_names = format_skill_names_env(skill_names)
             if selected_skill_names:
@@ -135,26 +164,89 @@ class E2BSkillRuntimeBackend:
             )
 
             request_path = "/tmp/ksadk-workflow-request.json"
+            request = {
+                "workflow_prompt": workflow_prompt,
+                "skill_names": normalize_skill_names(skill_names),
+            }
+            if pinned_packages is not None:
+                probe = session.run_command(
+                    "python -I -c 'from ksadk.skills.runtime.agent import "
+                    "PINNED_PACKAGE_PROTOCOL_VERSION, ARTIFACT_DELIVERY_PROTOCOL_VERSION; "
+                    'print(f"{PINNED_PACKAGE_PROTOCOL_VERSION}:{ARTIFACT_DELIVERY_PROTOCOL_VERSION}")\'',
+                    timeout=min(effective_timeout, 10),
+                    env=sandbox_env,
+                )
+                if probe.exit_code != 0 or probe.stdout.strip() != "1:1":
+                    raise SkillRuntimeError(
+                        "Sandbox runtime does not support pinned Skill protocol v1"
+                    )
+                delivery = "/tmp/ksadk-pinned-" + secrets.token_hex(16)
+                prepared = session.run_command(
+                    f"mkdir -m 700 {delivery}", timeout=min(effective_timeout, 10), env=sandbox_env
+                )
+                if prepared.exit_code != 0:
+                    raise SkillRuntimeError("Could not prepare pinned Skill delivery directory")
+                with tempfile.TemporaryDirectory(prefix="ksadk-skill-transfer-") as directory:
+                    entries = stage_packages(pinned_packages, Path(directory))
+                    for entry in entries:
+                        session.write_file(
+                            f"{delivery}/{entry.archive_name}",
+                            read_archive(Path(directory) / entry.archive_name),
+                        )
+                request["pinned_packages"] = [entry.model_dump() for entry in entries]
+                request["pinned_protocol_version"] = 1
+                request["collect_artifacts"] = True
+                sandbox_env["KSADK_SKILL_WORKDIR"] = f"{delivery}/work"
+                request_path = f"{delivery}/workflow-request.json"
             session.write_file(
                 request_path,
                 json.dumps(
-                    {
-                        "workflow_prompt": workflow_prompt,
-                        "skill_names": normalize_skill_names(skill_names),
-                    },
+                    request,
                     ensure_ascii=False,
                 ).encode("utf-8"),
             )
             command = f"python -u /home/ksadk/agent.py --request-file {request_path}"
+            if pinned_packages is not None:
+                command = (
+                    f"python -I -u -m ksadk.skills.runtime.agent --request-file {request_path}"
+                )
             result = session.run_command(command, timeout=effective_timeout, env=sandbox_env)
             stdout = result.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("Sandbox did not return a unique workflow result")
+                payload = payloads[0]
+                if payload.get("artifact_bundle") is None:
+                    raise SkillRuntimeError("Sandbox did not return an artifact delivery receipt")
+                receipt = ArtifactBundle.model_validate(payload["artifact_bundle"])
+                content = session.read_file_bytes(
+                    f"{delivery}/artifacts.zip", max_bytes=receipt.size
+                )
+                output_files = import_artifacts(content, receipt, parent=self.artifact_directory)
+                payload["output_files"] = output_files
+                payload["artifacts"] = output_files
+                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=session.sandbox_id,
                 exit_code=result.exit_code,
                 stdout=stdout,
                 stderr=result.stderr,
                 duration_ms=int((time.monotonic() - started) * 1000),
-                output_files=parse_output_files(stdout),
+                output_files=output_files,
             )
         except Exception as exc:
             error_type = type(exc).__name__