agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/sessions/sqlite_service.py

@@ -0,0 +1,13 @@
+"""Compatibility wrapper for the legacy sqlite-backed local session service path."""
+
+from ksadk.sessions.local_service import (
+    LocalSessionService,
+    create_local_session_service,
+    resolve_local_session_dir,
+)
+
+__all__ = [
+    "LocalSessionService",
+    "create_local_session_service",
+    "resolve_local_session_dir",
+]

ksadk/skills/__init__.py

@@ -0,0 +1,9 @@
+"""Skill Center runtime consumption helpers."""
+
+from ksadk.skills.models import ContentHash, SkillListResponse, SkillRef
+
+__all__ = [
+    "ContentHash",
+    "SkillListResponse",
+    "SkillRef",
+]

ksadk/skills/loader.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class LocalSkill:
+    name: str
+    description: str
+    root_dir: Path
+    skill_md: Path
+    body: str
+
+
+def load_local_skill(root_dir: str | Path) -> LocalSkill:
+    root = Path(root_dir)
+    skill_md = root / "SKILL.md"
+    if not skill_md.exists():
+        raise FileNotFoundError(f"SKILL.md not found: {skill_md}")
+    content = skill_md.read_text(encoding="utf-8")
+    metadata, body = _parse_frontmatter(content)
+    return LocalSkill(
+        name=metadata.get("name") or root.name,
+        description=metadata.get("description") or "",
+        root_dir=root,
+        skill_md=skill_md,
+        body=body,
+    )
+
+
+def _parse_frontmatter(content: str) -> tuple[dict[str, str], str]:
+    if not content.startswith("---\n"):
+        return {}, content
+    end = content.find("\n---\n", 4)
+    if end == -1:
+        return {}, content
+    raw_meta = content[4:end]
+    body = content[end + 5 :]
+    metadata: dict[str, str] = {}
+    for line in raw_meta.splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        metadata[key.strip()] = value.strip().strip("\"'")
+    return metadata, body

ksadk/skills/models.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ContentHash:
+    algorithm: str
+    value: str
+
+    @classmethod
+    def parse(cls, raw: str | None) -> "ContentHash | None":
+        normalized = str(raw or "").strip()
+        if not normalized:
+            return None
+        if ":" not in normalized:
+            return cls("sha256", normalized.lower())
+        algorithm, value = normalized.split(":", 1)
+        return cls(algorithm.strip().lower(), value.strip().lower())
+
+    def render(self) -> str:
+        return f"{self.algorithm}:{self.value}"
+
+
+@dataclass(frozen=True)
+class SkillRef:
+    skill_id: str
+    version_id: str
+    version: str
+    name: str
+    description: str = ""
+    status: str = ""
+    content_hash: ContentHash | None = None
+    archive_uri: str = ""
+    aliases: tuple[str, ...] = ()
+    tags: tuple[str, ...] = ()
+    examples: tuple[str, ...] = ()
+    input_schema: dict[str, Any] | None = None
+    runtime_requirements: dict[str, Any] | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "SkillRef":
+        return cls(
+            skill_id=str(payload.get("SkillId") or payload.get("skill_id") or ""),
+            version_id=str(payload.get("VersionId") or payload.get("version_id") or ""),
+            version=str(payload.get("Version") or payload.get("version") or ""),
+            name=str(payload.get("Name") or payload.get("name") or ""),
+            description=str(payload.get("Description") or payload.get("description") or ""),
+            status=str(payload.get("Status") or payload.get("status") or ""),
+            content_hash=ContentHash.parse(payload.get("ContentHash") or payload.get("content_hash")),
+            archive_uri=str(payload.get("ArchiveUri") or payload.get("archive_uri") or ""),
+            aliases=_string_tuple(payload.get("Aliases") or payload.get("aliases")),
+            tags=_string_tuple(payload.get("Tags") or payload.get("tags")),
+            examples=_string_tuple(payload.get("Examples") or payload.get("examples")),
+            input_schema=_dict_or_none(payload.get("InputSchema") or payload.get("input_schema")),
+            runtime_requirements=_dict_or_none(
+                payload.get("RuntimeRequirements") or payload.get("runtime_requirements")
+            ),
+        )
+
+    @property
+    def cache_key(self) -> str:
+        identity = self.skill_id or self.name
+        version_key = self.version_id or self.version
+        if not version_key and self.content_hash:
+            version_key = self.content_hash.value
+        return "__".join(part.replace("/", "_").replace(":", "_") for part in (identity, version_key) if part)
+
+    @property
+    def is_active(self) -> bool:
+        return not self.status or self.status.lower() in {"active", "available", "enabled"}
+
+
+@dataclass(frozen=True)
+class SkillListResponse:
+    request_id: str
+    space_id: str
+    space_name: str
+    skills: list[SkillRef]
+    code: int = 0
+    message: str = ""
+
+    @classmethod
+    def from_payload(
+        cls,
+        payload: dict[str, Any],
+        *,
+        space_id: str = "",
+        space_name: str = "",
+    ) -> "SkillListResponse":
+        data = payload.get("Data") or payload.get("data") or {}
+        skills_payload = data.get("Skills") or data.get("skills") or data.get("Items") or data.get("items") or []
+        return cls(
+            code=int(payload.get("Code") or payload.get("code") or 0),
+            message=str(payload.get("Message") or payload.get("message") or ""),
+            request_id=str(payload.get("RequestId") or payload.get("request_id") or ""),
+            space_id=str(data.get("SkillSpaceId") or data.get("skill_space_id") or space_id),
+            space_name=str(data.get("SkillSpaceName") or data.get("skill_space_name") or space_name),
+            skills=[SkillRef.from_payload(item) for item in skills_payload if isinstance(item, dict)],
+        )
+
+    def active_skills(self) -> list[SkillRef]:
+        return [skill for skill in self.skills if skill.is_active]
+
+
+def _string_tuple(raw: Any) -> tuple[str, ...]:
+    if raw is None:
+        return ()
+    if isinstance(raw, str):
+        values = raw.split(",")
+    elif isinstance(raw, (list, tuple, set)):
+        values = raw
+    else:
+        return ()
+    return tuple(value for value in (str(item).strip() for item in values) if value)
+
+
+def _dict_or_none(raw: Any) -> dict[str, Any] | None:
+    return dict(raw) if isinstance(raw, dict) else None

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")