agentengine-sdk-python 0.6.4__py3-none-any.whl → 0.7.0__py3-none-any.whl

ksadk/skills/package_store.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import hashlib
+import shutil
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from ksadk.skills.models import SkillRef
+
+
+class SkillPackageError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class SkillPackage:
+    ref: SkillRef
+    archive_path: Path
+    extract_dir: Path
+    root_dir: Path
+    cache_hit: bool = False
+
+
+class PackageStore:
+    def __init__(self, cache_dir: str | Path):
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    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)
+            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,
+        )
+
+    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():
+            return None
+        content = archive_path.read_bytes()
+        try:
+            self._verify_hash(ref, content)
+        except SkillPackageError:
+            return None
+        return SkillPackage(
+            ref=ref,
+            archive_path=archive_path,
+            extract_dir=extract_dir,
+            root_dir=self._find_skill_root(extract_dir),
+            cache_hit=True,
+        )
+
+    def _skill_dir(self, ref: SkillRef) -> Path:
+        return self.cache_dir / (ref.cache_key or ref.name or "skill")
+
+    def _verify_hash(self, ref: SkillRef, content: bytes) -> None:
+        if not ref.content_hash:
+            return
+        if ref.content_hash.algorithm != "sha256":
+            raise SkillPackageError(f"Unsupported ContentHash algorithm: {ref.content_hash.algorithm}")
+        actual = hashlib.sha256(content).hexdigest()
+        if actual.lower() != ref.content_hash.value.lower():
+            raise SkillPackageError(
+                f"ContentHash mismatch for {ref.name}: expected {ref.content_hash.render()}, got sha256:{actual}"
+            )
+
+    def _safe_extract(self, archive_path: Path, extract_dir: Path) -> None:
+        base = extract_dir.resolve()
+        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)
+
+    def _find_skill_root(self, extract_dir: Path) -> Path:
+        if (extract_dir / "SKILL.md").exists():
+            return extract_dir
+        candidates = sorted(path.parent for path in extract_dir.rglob("SKILL.md"))
+        if not candidates:
+            raise SkillPackageError(f"SKILL.md not found under {extract_dir}")
+        return candidates[0]

ksadk/skills/runtime/__init__.py

@@ -0,0 +1,17 @@
+from ksadk.skills.runtime.base import (
+    SandboxInputFile,
+    SkillRuntimeBackend,
+    SkillRuntimeError,
+    SkillRuntimeResult,
+)
+from ksadk.skills.runtime.factory import create_skill_runtime_backend
+from ksadk.skills.runtime.request import SkillWorkflowRequest
+
+__all__ = [
+    "SandboxInputFile",
+    "SkillRuntimeBackend",
+    "SkillRuntimeError",
+    "SkillRuntimeResult",
+    "SkillWorkflowRequest",
+    "create_skill_runtime_backend",
+]

ksadk/skills/runtime/agent.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+import httpx
+
+from ksadk.skills.loader import LocalSkill
+from ksadk.skills.models import SkillRef
+from ksadk.skills.package_store import PackageStore
+from ksadk.skills.runtime.base import normalize_skill_names
+from ksadk.skills.runtime.executor import (
+    WorkflowExecution,
+    execute_workflow,
+    _can_run_web_artifacts_builder as _executor_can_run_web_artifacts_builder,
+    _run_command as _executor_run_command,
+    _run_web_artifacts_builder as _executor_run_web_artifacts_builder,
+    _runtime_timeout as _executor_runtime_timeout,
+    _safe_project_name as _executor_safe_project_name,
+    _tail as _executor_tail,
+)
+from ksadk.skills.runtime.request import (
+    SkillWorkflowRequest,
+    SkillWorkflowRequestError,
+    parse_workflow_request,
+)
+from ksadk.skills.runtime import loader as runtime_loader
+from ksadk.skills.runtime import registry as runtime_registry
+
+
+def _skill_space_ids() -> list[str]:
+    return runtime_registry.skill_space_ids()
+
+
+def _user_skill_space_ids() -> list[str]:
+    return runtime_registry.user_skill_space_ids()
+
+
+def _public_skill_space_ids() -> list[str]:
+    return runtime_registry.public_skill_space_ids()
+
+
+def _parse_space_ids(*raw_values: str) -> list[str]:
+    return runtime_registry.parse_space_ids(*raw_values)
+
+
+_SKILL_LOAD_WARNINGS: list[str] = []
+
+
+def _load_skills(
+    *,
+    prompt: str = "",
+    skill_names: list[str] | None = None,
+    service_transport: httpx.BaseTransport | None = None,
+) -> list[LocalSkill]:
+    result = runtime_loader.load_skills(
+        prompt=prompt,
+        skill_names=skill_names,
+        service_transport=service_transport,
+    )
+    _SKILL_LOAD_WARNINGS.extend(result.warnings)
+    return result.skills
+
+
+def _dedupe_skill_refs(skill_refs: list[SkillRef], *, seen_names: set[str]) -> list[SkillRef]:
+    return runtime_registry.dedupe_skill_refs(skill_refs, seen_names=seen_names)
+
+
+def _select_public_skill_refs(skill_refs: list[SkillRef]) -> list[SkillRef]:
+    return runtime_registry.select_public_skill_refs(skill_refs)
+
+
+def _allow_hash_mismatch() -> bool:
+    return runtime_loader._allow_hash_mismatch()
+
+
+def _store_unverified_archive(store: PackageStore, skill: SkillRef, archive: bytes):
+    return runtime_loader._store_unverified_archive(store, skill, archive)
+
+
+def _select_remote_skill_refs(
+    skill_refs: list[SkillRef],
+    prompt: str,
+    *,
+    skill_names: list[str] | None = None,
+) -> list[SkillRef]:
+    return runtime_registry.select_remote_skill_refs(skill_refs, prompt, skill_names=skill_names)
+
+
+def _load_local_skills() -> list[LocalSkill]:
+    return runtime_loader.load_local_skills()
+
+
+def run_agent(
+    argv: list[str] | None = None,
+    *,
+    service_transport: httpx.BaseTransport | None = None,
+) -> int:
+    _SKILL_LOAD_WARNINGS.clear()
+    args = list(argv if argv is not None else sys.argv[1:])
+    try:
+        request = _resolve_request(args)
+    except SkillWorkflowRequestError as exc:
+        execution = WorkflowExecution(status="failed", error=str(exc))
+        print("workflow=")
+        print(f"skill_spaces={','.join(_skill_space_ids())}")
+        print("loaded_skills=")
+        print(f"workflow_result={json.dumps(asdict(execution), ensure_ascii=False, sort_keys=True)}")
+        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,
+    )
+    execution = _execute_workflow(prompt, loaded_skills, selected_skill_names=selected_skill_names)
+    print(f"workflow={prompt}")
+    print(f"skill_spaces={','.join(_skill_space_ids())}")
+    print(f"loaded_skills={','.join(skill.name for skill in loaded_skills)}")
+    print(f"selected_skills={json.dumps(selected_skill_names, ensure_ascii=False, sort_keys=True)}")
+    if _SKILL_LOAD_WARNINGS:
+        print(f"skill_warnings={json.dumps(_SKILL_LOAD_WARNINGS, ensure_ascii=False, sort_keys=True)}")
+    print(f"workflow_result={json.dumps(asdict(execution), ensure_ascii=False, sort_keys=True)}")
+    return 0 if execution.status != "failed" else 1
+
+
+def _resolve_request(args: list[str]) -> SkillWorkflowRequest:
+    return parse_workflow_request(args)
+
+
+def _selected_skill_names() -> list[str]:
+    return normalize_skill_names(os.environ.get("KSADK_SELECTED_SKILL_NAMES", ""))
+
+
+def _execute_workflow(
+    prompt: str,
+    skills: list[LocalSkill],
+    *,
+    selected_skill_names: list[str] | None = None,
+) -> WorkflowExecution:
+    return execute_workflow(prompt, skills, selected_skill_names=selected_skill_names)
+
+
+def _can_run_web_artifacts_builder(skill: LocalSkill, prompt: str) -> bool:
+    return _executor_can_run_web_artifacts_builder(skill, prompt)
+
+
+def _run_web_artifacts_builder(skill: LocalSkill) -> WorkflowExecution:
+    return _executor_run_web_artifacts_builder(skill)
+
+
+def _run_command(args: list[str], *, cwd: Path, timeout: int) -> dict[str, object]:
+    return _executor_run_command(args, cwd=cwd, timeout=timeout)
+
+
+def _runtime_timeout() -> int:
+    return _executor_runtime_timeout()
+
+
+def _safe_project_name(raw: str) -> str:
+    return _executor_safe_project_name(raw)
+
+
+def _tail(value: str | bytes, limit: int = 4000) -> str:
+    return _executor_tail(value, limit=limit)
+
+
+def _resolve_prompt(args: list[str]) -> str:
+    return _resolve_request(args).workflow_prompt
+
+
+def main(argv: list[str] | None = None) -> int:
+    return run_agent(argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ksadk/skills/runtime/artifacts.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def parse_artifact_lines(stdout: str) -> list[str]:
+    artifacts: list[str] = []
+    seen: set[str] = set()
+    for line in stdout.splitlines():
+        if not line.startswith("artifact="):
+            continue
+        value = line.split("=", 1)[1].strip()
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        artifacts.append(value)
+    return artifacts
+
+
+def collect_output_dir_artifacts(output_dir: Path) -> list[str]:
+    if not output_dir.is_dir():
+        return []
+    return [
+        str(path)
+        for path in sorted(output_dir.rglob("*"))
+        if path.is_file()
+    ]
+
+
+def merge_artifacts(*groups: list[str]) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for group in groups:
+        for item in group:
+            if item in seen:
+                continue
+            seen.add(item)
+            merged.append(item)
+    return merged

ksadk/skills/runtime/backends/__init__.py

@@ -0,0 +1 @@
+"""Skill Runtime backend implementations."""

ksadk/skills/runtime/backends/disabled.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from ksadk.skills.runtime.base import SkillRuntimeError, SkillRuntimeResult
+
+
+class DisabledSkillRuntimeBackend:
+    def run_workflow(self, *args, **kwargs) -> SkillRuntimeResult:
+        raise SkillRuntimeError("Skill Runtime is disabled")

ksadk/skills/runtime/backends/e2b.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any
+
+from ksadk.sandbox import (
+    E2BSandboxBackend,
+    SandboxInputFile as RuntimeSandboxInputFile,
+    SandboxSpec,
+)
+from ksadk.skills.runtime.base import (
+    SandboxInputFile,
+    SkillRuntimeError,
+    SkillRuntimeResult,
+    format_skill_names_env,
+    normalize_skill_names,
+    parse_output_files,
+)
+
+
+def _bool_env(name: str, default: bool = True) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _redact(value: str) -> str:
+    redacted = value
+    for key_name in (
+        "E2B_API_KEY",
+        "KSADK_SKILL_SERVICE_TOKEN",
+        "KSADK_SKILL_SERVICE_ACCESS_KEY",
+        "KSADK_SKILL_SERVICE_SECRET_KEY",
+        "KSYUN_ACCESS_KEY",
+        "KSYUN_SECRET_KEY",
+        "KS3_ACCESS_KEY",
+        "KS3_SECRET_KEY",
+    ):
+        secret = os.environ.get(key_name)
+        if secret:
+            redacted = redacted.replace(secret, "[REDACTED]")
+    return redacted
+
+
+class E2BSkillRuntimeBackend:
+    def __init__(
+        self,
+        *,
+        sandbox_cls: Any | None = None,
+        template_id: str,
+        timeout: int = 900,
+        allow_internet_access: bool = True,
+    ):
+        if not template_id:
+            raise SkillRuntimeError(
+                "KSADK_SANDBOX_TEMPLATE_ID is required for E2B backend "
+                "(KSADK_SKILL_RUNTIME_TEMPLATE_ID is a compatibility alias)"
+            )
+        self.template_id = template_id
+        self.timeout = timeout
+        self.allow_internet_access = allow_internet_access
+        self.sandbox_backend = E2BSandboxBackend(
+            spec=SandboxSpec(
+                template_id=template_id,
+                timeout=timeout,
+                allow_internet_access=allow_internet_access,
+                metadata={"component": "skill-runtime"},
+            ),
+            sandbox_cls=sandbox_cls,
+        )
+
+    @classmethod
+    def from_env(cls) -> "E2BSkillRuntimeBackend":
+        try:
+            from e2b import Sandbox
+        except ImportError as exc:
+            raise SkillRuntimeError(
+                "e2b>=2.0.0 is required for KSADK_SKILL_RUNTIME_BACKEND=e2b"
+            ) from exc
+        return cls(
+            sandbox_cls=Sandbox,
+            template_id=(
+                os.environ.get("KSADK_SANDBOX_TEMPLATE_ID")
+                or os.environ.get("KSADK_SKILL_RUNTIME_TEMPLATE_ID")
+                or ""
+            ),
+            timeout=int(os.environ.get("KSADK_SANDBOX_TIMEOUT") or os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT") or "900"),
+            allow_internet_access=_bool_env(
+                "KSADK_SANDBOX_ALLOW_INTERNET_ACCESS",
+                _bool_env("KSADK_SKILL_RUNTIME_ALLOW_INTERNET_ACCESS", True),
+            ),
+        )
+
+    def run_workflow(
+        self,
+        workflow_prompt: str,
+        *,
+        skill_space_ids: list[str],
+        session_id: str,
+        skill_names: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        input_files: list[SandboxInputFile] | None = None,
+        timeout: int = 900,
+    ) -> SkillRuntimeResult:
+        session = None
+        started = time.monotonic()
+        effective_timeout = timeout or self.timeout
+        try:
+            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"):
+                sandbox_env["KSADK_PUBLIC_SKILL_SPACE_IDS"] = public_spaces
+            selected_skill_names = format_skill_names_env(skill_names)
+            if selected_skill_names:
+                sandbox_env["KSADK_SELECTED_SKILL_NAMES"] = selected_skill_names
+            sandbox_env.update(env or {})
+            session = self.sandbox_backend.create_session(
+                session_id=session_id,
+                env=sandbox_env,
+                input_files=[
+                    RuntimeSandboxInputFile(source=item.source, target_path=item.target_path)
+                    for item in input_files or []
+                ],
+            )
+
+            request_path = "/tmp/ksadk-workflow-request.json"
+            session.write_file(
+                request_path,
+                json.dumps(
+                    {
+                        "workflow_prompt": workflow_prompt,
+                        "skill_names": normalize_skill_names(skill_names),
+                    },
+                    ensure_ascii=False,
+                ).encode("utf-8"),
+            )
+            command = f"python -u /home/ksadk/agent.py --request-file {request_path}"
+            result = session.run_command(command, timeout=effective_timeout, env=sandbox_env)
+            stdout = result.stdout
+            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),
+            )
+        except Exception as exc:
+            error_type = type(exc).__name__
+            return SkillRuntimeResult(
+                runtime_id=session.sandbox_id if session is not None else "",
+                exit_code=None,
+                duration_ms=int((time.monotonic() - started) * 1000),
+                timed_out="timeout" in error_type.lower(),
+                error_type=error_type,
+                error_message=_redact(str(exc)),
+            )
+        finally:
+            if session is not None:
+                try:
+                    session.kill()
+                except Exception:
+                    pass

ksadk/skills/runtime/backends/local.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+from ksadk.skills.runtime.base import (
+    SandboxInputFile,
+    SkillRuntimeResult,
+    format_skill_names_env,
+    normalize_skill_names,
+    parse_output_files,
+)
+
+
+class LocalProcessSkillRuntimeBackend:
+    def __init__(self, agent_path: str | Path, timeout: int = 900):
+        self.agent_path = Path(agent_path)
+        self.timeout = timeout
+
+    @classmethod
+    def from_env(cls) -> "LocalProcessSkillRuntimeBackend":
+        agent_path = os.environ.get("KSADK_SKILL_RUNTIME_AGENT_PATH") or str(
+            Path(__file__).resolve().parents[1] / "agent.py"
+        )
+        timeout = int(os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT", "900"))
+        return cls(agent_path=agent_path, timeout=timeout)
+
+    def run_workflow(
+        self,
+        workflow_prompt: str,
+        *,
+        skill_space_ids: list[str],
+        session_id: str,
+        skill_names: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        input_files: list[SandboxInputFile] | None = None,
+        timeout: int = 900,
+    ) -> SkillRuntimeResult:
+        started = time.monotonic()
+        runtime_env = 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"):
+            runtime_env["KSADK_PUBLIC_SKILL_SPACE_IDS"] = public_spaces
+        selected_skill_names = format_skill_names_env(skill_names)
+        if selected_skill_names:
+            runtime_env["KSADK_SELECTED_SKILL_NAMES"] = selected_skill_names
+        else:
+            runtime_env.pop("KSADK_SELECTED_SKILL_NAMES", None)
+        try:
+            with tempfile.TemporaryDirectory(prefix="ksadk-skill-runtime-") as tmp_dir:
+                request_path = Path(tmp_dir) / "workflow-request.json"
+                request_path.write_text(
+                    json.dumps(
+                        {
+                            "workflow_prompt": workflow_prompt,
+                            "skill_names": normalize_skill_names(skill_names),
+                        },
+                        ensure_ascii=False,
+                    ),
+                    encoding="utf-8",
+                )
+                completed = subprocess.run(
+                    [sys.executable, "-u", str(self.agent_path), "--request-file", str(request_path)],
+                    text=True,
+                    capture_output=True,
+                    timeout=timeout or self.timeout,
+                    env=runtime_env,
+                    check=False,
+                )
+            return SkillRuntimeResult(
+                runtime_id=f"local:{session_id}",
+                exit_code=completed.returncode,
+                stdout=completed.stdout,
+                stderr=completed.stderr,
+                duration_ms=int((time.monotonic() - started) * 1000),
+                output_files=parse_output_files(completed.stdout),
+            )
+        except subprocess.TimeoutExpired as exc:
+            return SkillRuntimeResult(
+                runtime_id=f"local:{session_id}",
+                exit_code=None,
+                stdout=exc.stdout or "",
+                stderr=exc.stderr or "",
+                duration_ms=int((time.monotonic() - started) * 1000),
+                timed_out=True,
+                error_type="TimeoutExpired",
+                error_message=f"Skill workflow timed out after {timeout or self.timeout}s",
+            )