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

ksadk/skills/runtime/base.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, Sequence
+
+
+class SkillRuntimeError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class SandboxInputFile:
+    source: Path
+    target_path: str
+
+
+@dataclass(frozen=True)
+class SkillRuntimeResult:
+    runtime_id: str = ""
+    exit_code: int | None = None
+    stdout: str = ""
+    stderr: str = ""
+    duration_ms: int = 0
+    timed_out: bool = False
+    error_type: str | None = None
+    error_message: str | None = None
+    output_files: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0 and not self.error_type and not self.timed_out
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "runtime_id": self.runtime_id,
+            "exit_code": self.exit_code,
+            "stdout": self.stdout,
+            "stderr": self.stderr,
+            "duration_ms": self.duration_ms,
+            "timed_out": self.timed_out,
+            "error_type": self.error_type,
+            "error_message": self.error_message,
+            "output_files": list(self.output_files),
+        }
+
+
+class SkillRuntimeBackend(Protocol):
+    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:
+        ...
+
+
+def parse_output_files(stdout: str) -> list[str]:
+    for line in stdout.splitlines():
+        if not line.startswith("workflow_result="):
+            continue
+        raw = line.split("=", 1)[1]
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            return []
+        output_files = payload.get("output_files") if isinstance(payload, dict) else None
+        if isinstance(output_files, list):
+            return [str(item) for item in output_files]
+    return []
+
+
+def normalize_skill_names(skill_names: Sequence[str] | str | None) -> list[str]:
+    if skill_names is None:
+        return []
+
+    raw_values: list[str]
+    if isinstance(skill_names, str):
+        raw_values = [skill_names]
+    else:
+        raw_values = [str(item) for item in skill_names]
+
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for raw in raw_values:
+        for part in raw.split(","):
+            name = part.strip()
+            key = name.lower()
+            if not name or key in seen:
+                continue
+            seen.add(key)
+            normalized.append(name)
+    return normalized
+
+
+def format_skill_names_env(skill_names: Sequence[str] | str | None) -> str:
+    return ",".join(normalize_skill_names(skill_names))

ksadk/skills/runtime/executor.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ksadk.skills.loader import LocalSkill
+from ksadk.skills.runtime.artifacts import (
+    collect_output_dir_artifacts,
+    merge_artifacts,
+    parse_artifact_lines,
+)
+from ksadk.skills.runtime.base import normalize_skill_names
+
+
+@dataclass
+class WorkflowExecution:
+    status: str
+    executed_skill: str = ""
+    output_files: list[str] = field(default_factory=list)
+    commands: list[dict[str, object]] = field(default_factory=list)
+    selected_skills: list[str] = field(default_factory=list)
+    loaded_skills: list[str] = field(default_factory=list)
+    artifacts: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    error: str = ""
+
+
+def execute_workflow(
+    prompt: str,
+    skills: list[LocalSkill],
+    *,
+    selected_skill_names: list[str] | None = None,
+) -> WorkflowExecution:
+    selected = normalize_skill_names(selected_skill_names)
+    loaded = [skill.name for skill in skills]
+    if not skills:
+        return WorkflowExecution(status="no_skills", selected_skills=selected, loaded_skills=loaded)
+
+    for skill in _candidate_skills(skills, selected):
+        if _can_run_web_artifacts_builder(skill, prompt):
+            result = _run_web_artifacts_builder(skill)
+            _attach_context(result, selected=selected, loaded=loaded)
+            return result
+
+    for skill in _candidate_skills(skills, selected):
+        if _can_run_generic_workflow(skill):
+            result = _run_generic_workflow(skill, prompt)
+            _attach_context(result, selected=selected, loaded=loaded)
+            return result
+
+    return WorkflowExecution(
+        status="skipped",
+        selected_skills=selected,
+        loaded_skills=loaded,
+        warnings=["No loaded skill exposes an executable workflow entrypoint."],
+    )
+
+
+def _candidate_skills(skills: list[LocalSkill], selected: list[str]) -> list[LocalSkill]:
+    if not selected:
+        return skills
+    selected_keys = {name.lower() for name in selected}
+    return [skill for skill in skills if skill.name.lower() in selected_keys]
+
+
+def _attach_context(result: WorkflowExecution, *, selected: list[str], loaded: list[str]) -> None:
+    result.selected_skills = selected
+    result.loaded_skills = loaded
+    if not result.artifacts:
+        result.artifacts = list(result.output_files)
+
+
+def _can_run_web_artifacts_builder(skill: LocalSkill, prompt: str) -> bool:
+    if skill.name != "web-artifacts-builder":
+        return False
+    init_script = skill.root_dir / "scripts" / "init-artifact.sh"
+    bundle_script = skill.root_dir / "scripts" / "bundle-artifact.sh"
+    if not init_script.exists() or not bundle_script.exists():
+        return False
+    normalized = prompt.lower()
+    return any(marker in normalized for marker in ("web-artifacts-builder", "artifact", "bundle", "html", "react"))
+
+
+def _can_run_generic_workflow(skill: LocalSkill) -> bool:
+    return (skill.root_dir / "scripts" / "run-workflow.sh").exists()
+
+
+def _run_web_artifacts_builder(skill: LocalSkill) -> WorkflowExecution:
+    workdir = _skill_workdir()
+    project_name = _safe_project_name(os.environ.get("KSADK_SKILL_ARTIFACT_PROJECT") or "ksadk-artifact")
+    project_dir = workdir / project_name
+    workdir.mkdir(parents=True, exist_ok=True)
+    if project_dir.exists():
+        shutil.rmtree(project_dir)
+
+    timeout = _runtime_timeout()
+    commands: list[dict[str, object]] = []
+    init_result = _run_command(
+        ["bash", str(skill.root_dir / "scripts" / "init-artifact.sh"), project_name],
+        cwd=workdir,
+        timeout=timeout,
+    )
+    commands.append(init_result)
+    if init_result["exit_code"] != 0:
+        return WorkflowExecution(status="failed", executed_skill=skill.name, commands=commands)
+
+    bundle_result = _run_command(
+        ["bash", str(skill.root_dir / "scripts" / "bundle-artifact.sh")],
+        cwd=project_dir,
+        timeout=timeout,
+    )
+    commands.append(bundle_result)
+    output_files = [str(project_dir / "bundle.html")] if (project_dir / "bundle.html").exists() else []
+    status = "ok" if bundle_result["exit_code"] == 0 and output_files else "failed"
+    return WorkflowExecution(
+        status=status,
+        executed_skill=skill.name,
+        output_files=output_files,
+        artifacts=list(output_files),
+        commands=commands,
+    )
+
+
+def _run_generic_workflow(skill: LocalSkill, prompt: str) -> WorkflowExecution:
+    workdir = _skill_workdir()
+    workdir.mkdir(parents=True, exist_ok=True)
+    output_dir = workdir / "artifacts"
+    timeout = _runtime_timeout()
+    command = _run_command(
+        ["bash", str(skill.root_dir / "scripts" / "run-workflow.sh")],
+        cwd=workdir,
+        timeout=timeout,
+        extra_env={
+            "KSADK_WORKFLOW_PROMPT": prompt,
+            "KSADK_SKILL_WORKDIR": str(workdir),
+            "KSADK_SKILL_OUTPUT_DIR": str(output_dir),
+            "KSADK_SKILL_ROOT_DIR": str(skill.root_dir),
+        },
+    )
+    artifacts = merge_artifacts(
+        parse_artifact_lines(str(command.get("stdout") or "")),
+        collect_output_dir_artifacts(output_dir),
+    )
+    status = "ok" if command["exit_code"] == 0 else "failed"
+    return WorkflowExecution(
+        status=status,
+        executed_skill=skill.name,
+        output_files=list(artifacts),
+        artifacts=list(artifacts),
+        commands=[command],
+    )
+
+
+def _skill_workdir() -> Path:
+    return Path(
+        os.environ.get("KSADK_SKILL_WORKDIR")
+        or Path(tempfile.gettempdir()) / "ksadk-skill-workflow"
+    )
+
+
+def _run_command(
+    args: list[str],
+    *,
+    cwd: Path,
+    timeout: int,
+    extra_env: dict[str, str] | None = None,
+) -> dict[str, object]:
+    env = os.environ.copy()
+    env.setdefault("CI", "1")
+    env.update(extra_env or {})
+    try:
+        completed = subprocess.run(
+            args,
+            cwd=str(cwd),
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+            env=env,
+        )
+        return {
+            "command": " ".join(args),
+            "cwd": str(cwd),
+            "exit_code": completed.returncode,
+            "stdout": _tail(completed.stdout),
+            "stderr": _tail(completed.stderr),
+        }
+    except subprocess.TimeoutExpired as exc:
+        return {
+            "command": " ".join(args),
+            "cwd": str(cwd),
+            "exit_code": None,
+            "timed_out": True,
+            "stdout": _tail(exc.stdout or ""),
+            "stderr": _tail(exc.stderr or ""),
+        }
+
+
+def _runtime_timeout() -> int:
+    try:
+        return int(os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT", "900"))
+    except ValueError:
+        return 900
+
+
+def _safe_project_name(raw: str) -> str:
+    sanitized = "".join(ch if ch.isalnum() or ch in {"-", "_"} else "-" for ch in raw).strip("-_")
+    return sanitized[:80] or "ksadk-artifact"
+
+
+def _tail(value: str | bytes, limit: int = 4000) -> str:
+    text = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else value
+    if len(text) <= limit:
+        return text
+    return text[-limit:]

ksadk/skills/runtime/factory.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+
+from ksadk.skills.runtime.base import SkillRuntimeBackend
+from ksadk.skills.runtime.backends.disabled import DisabledSkillRuntimeBackend
+from ksadk.skills.runtime.backends.e2b import E2BSkillRuntimeBackend
+from ksadk.skills.runtime.backends.local import LocalProcessSkillRuntimeBackend
+
+
+def _resolve_backend(backend: str | None = None) -> str:
+    if backend is not None:
+        return backend.strip().lower()
+
+    explicit = os.environ.get("KSADK_SKILL_RUNTIME_BACKEND")
+    if explicit is not None:
+        return explicit.strip().lower()
+
+    sandbox_backend = os.environ.get("KSADK_SANDBOX_BACKEND", "").strip().lower()
+    if sandbox_backend and sandbox_backend not in {"disabled", "none", "off"}:
+        return sandbox_backend
+
+    if os.environ.get("KSADK_SANDBOX_TEMPLATE_ID") or os.environ.get("KSADK_SKILL_RUNTIME_TEMPLATE_ID"):
+        return "e2b"
+
+    return "disabled"
+
+
+def create_skill_runtime_backend(backend: str | None = None) -> SkillRuntimeBackend:
+    resolved = _resolve_backend(backend)
+    if resolved in {"", "disabled", "none", "off"}:
+        return DisabledSkillRuntimeBackend()
+    if resolved == "local_process":
+        return LocalProcessSkillRuntimeBackend.from_env()
+    if resolved == "e2b":
+        return E2BSkillRuntimeBackend.from_env()
+    raise ValueError(f"Unsupported skill runtime backend: {resolved}")

ksadk/skills/runtime/loader.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+from ksadk.skills.loader import LocalSkill, load_local_skill
+from ksadk.skills.models import SkillRef
+from ksadk.skills.package_store import PackageStore, SkillPackageError
+from ksadk.skills.runtime import registry
+from ksadk.skills.service_client import SkillServiceClient
+from ksadk.skills.service_env import resolve_skill_service_url
+
+
+@dataclass
+class SkillLoadResult:
+    skills: list[LocalSkill] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def load_skills(
+    *,
+    prompt: str = "",
+    skill_names: list[str] | None = None,
+    service_transport: httpx.BaseTransport | None = None,
+) -> SkillLoadResult:
+    warnings: list[str] = []
+    skills: list[LocalSkill] = []
+    skills.extend(load_local_skills())
+
+    service_url = resolve_skill_service_url(require_spaces=True)
+    if not service_url:
+        return SkillLoadResult(skills=skills, warnings=warnings)
+
+    cache_dir = Path(
+        os.environ.get("KSADK_SKILL_CACHE_DIR")
+        or Path(tempfile.gettempdir()) / "ksadk-skill-cache"
+    )
+    client = SkillServiceClient(
+        base_url=service_url,
+        token=os.environ.get("KSADK_SKILL_SERVICE_TOKEN", ""),
+        transport=service_transport,
+    )
+    store = PackageStore(cache_dir=cache_dir)
+    selected_refs: list[SkillRef] = []
+    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)
+        selected_refs.extend(
+            registry.dedupe_skill_refs(
+                registry.select_remote_skill_refs(
+                    listing.active_skills(),
+                    prompt,
+                    skill_names=skill_names,
+                ),
+                seen_names=seen_names,
+            )
+        )
+
+    if registry.public_skill_space_ids():
+        listing = client.list_available_premade_skills()
+        selected_refs.extend(
+            registry.dedupe_skill_refs(
+                registry.select_public_skill_refs(listing.active_skills()),
+                seen_names=seen_names,
+            )
+        )
+
+    for skill in selected_refs:
+        package = store.get_cached(skill)
+        if package is None:
+            archive = client.download_skill_archive(skill)
+            try:
+                package = store.store_archive(skill, archive)
+            except SkillPackageError as exc:
+                if not _allow_hash_mismatch():
+                    raise
+                package = _store_unverified_archive(store, skill, archive)
+                warnings.append(str(exc))
+        skills.append(load_local_skill(package.root_dir))
+    return SkillLoadResult(skills=skills, warnings=warnings)
+
+
+def load_local_skills() -> list[LocalSkill]:
+    skills_dir = os.environ.get("KSADK_LOCAL_SKILLS_DIR", "").strip()
+    if not skills_dir:
+        return []
+    root = Path(skills_dir)
+    if not root.exists():
+        return []
+    return [
+        load_local_skill(path)
+        for path in sorted(root.iterdir())
+        if path.is_dir() and (path / "SKILL.md").exists()
+    ]
+
+
+def _allow_hash_mismatch() -> bool:
+    return os.environ.get("KSADK_SKILL_ALLOW_HASH_MISMATCH", "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }
+
+
+def _store_unverified_archive(store: PackageStore, skill: SkillRef, archive: bytes):
+    skill_dir = store.cache_dir / f"unverified-{skill.cache_key or skill.name or 'skill'}"
+    if skill_dir.exists():
+        shutil.rmtree(skill_dir)
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    archive_path = skill_dir / "archive.zip"
+    extract_dir = skill_dir / "extracted"
+    archive_path.write_bytes(archive)
+    extract_dir.mkdir(parents=True, exist_ok=True)
+    store._safe_extract(archive_path, extract_dir)
+    return type(
+        "UnverifiedSkillPackage",
+        (),
+        {
+            "ref": skill,
+            "archive_path": archive_path,
+            "extract_dir": extract_dir,
+            "root_dir": store._find_skill_root(extract_dir),
+            "cache_hit": False,
+        },
+    )()

ksadk/skills/runtime/registry.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import os
+import re
+
+from ksadk.skills.models import SkillRef
+from ksadk.skills.runtime.base import normalize_skill_names
+from ksadk.skills.service_env import (
+    parse_skill_space_ids,
+    public_skill_space_ids as configured_public_skill_space_ids,
+    skill_space_ids as configured_skill_space_ids,
+    user_skill_space_ids as configured_user_skill_space_ids,
+)
+
+
+def skill_space_ids() -> list[str]:
+    return configured_skill_space_ids()
+
+
+def user_skill_space_ids() -> list[str]:
+    return configured_user_skill_space_ids()
+
+
+def public_skill_space_ids() -> list[str]:
+    return configured_public_skill_space_ids()
+
+
+def parse_space_ids(*raw_values: str) -> list[str]:
+    return parse_skill_space_ids(*raw_values)
+
+
+def dedupe_skill_refs(skill_refs: list[SkillRef], *, seen_names: set[str]) -> list[SkillRef]:
+    selected: list[SkillRef] = []
+    seen_keys: set[str] = set()
+    for skill in skill_refs:
+        name_key = skill.name.lower() if skill.name else ""
+        key = skill.cache_key or skill.skill_id or skill.name
+        if not name_key or name_key in seen_names or key in seen_keys:
+            continue
+        seen_names.add(name_key)
+        seen_keys.add(key)
+        selected.append(skill)
+    return selected
+
+
+def select_public_skill_refs(skill_refs: list[SkillRef]) -> list[SkillRef]:
+    allowlist = {name.lower() for name in normalize_skill_names(os.environ.get("KSADK_PUBLIC_SKILL_ALLOWLIST", ""))}
+    if not allowlist:
+        return [skill for skill in skill_refs if skill.name]
+    return [
+        skill
+        for skill in skill_refs
+        if skill.name and skill.name.lower() in allowlist
+    ]
+
+
+def select_remote_skill_refs(
+    skill_refs: list[SkillRef],
+    prompt: str,
+    *,
+    skill_names: list[str] | None = None,
+) -> list[SkillRef]:
+    if not prompt and not normalize_skill_names(skill_names):
+        return []
+    return [match.skill for match in match_skill_refs(skill_refs, prompt, skill_names=skill_names)]
+
+
+class SkillMatch:
+    def __init__(self, skill: SkillRef, score: int, reason: str):
+        self.skill = skill
+        self.score = score
+        self.reason = reason
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.skill.name,
+            "description": self.skill.description,
+            "version": self.skill.version,
+            "score": self.score,
+            "reason": self.reason,
+            "aliases": list(self.skill.aliases),
+            "tags": list(self.skill.tags),
+        }
+
+
+def match_skill_refs(
+    skill_refs: list[SkillRef],
+    prompt: str,
+    *,
+    skill_names: list[str] | None = None,
+    limit: int | None = None,
+) -> list[SkillMatch]:
+    requested_names = {name.lower() for name in normalize_skill_names(skill_names)}
+    normalized_prompt = prompt.lower()
+    prompt_tokens = _tokens(normalized_prompt)
+    matches: list[SkillMatch] = []
+    seen: set[str] = set()
+    for skill in skill_refs:
+        if not skill.name:
+            continue
+        skill_name = skill.name.lower()
+        if requested_names:
+            if skill_name not in requested_names:
+                continue
+            score, reason = 100, "exact_name"
+        else:
+            score, reason = _metadata_score(skill, normalized_prompt, prompt_tokens)
+            if score <= 0:
+                continue
+        key = skill.cache_key or skill.skill_id or skill.name
+        if key in seen:
+            continue
+        seen.add(key)
+        matches.append(SkillMatch(skill=skill, score=score, reason=reason))
+    matches.sort(key=lambda item: (-item.score, item.skill.name.lower()))
+    if limit is not None:
+        return matches[: max(0, limit)]
+    return matches
+
+
+def _metadata_score(skill: SkillRef, normalized_prompt: str, prompt_tokens: set[str]) -> tuple[int, str]:
+    if skill.name and skill.name.lower() in normalized_prompt:
+        return 90, "name"
+    for alias in skill.aliases:
+        if alias.lower() in normalized_prompt:
+            return 80, "alias"
+    for tag in skill.tags:
+        tag_key = tag.lower()
+        if tag_key and (tag_key in normalized_prompt or tag_key in prompt_tokens):
+            return 65, "tag"
+
+    text = " ".join(
+        [
+            skill.description or "",
+            " ".join(skill.examples),
+        ]
+    ).lower()
+    skill_tokens = _tokens(text)
+    overlap = prompt_tokens & skill_tokens
+    if overlap:
+        return min(55, 20 + len(overlap) * 10), "metadata"
+    return 0, ""
+
+
+def _tokens(value: str) -> set[str]:
+    return {
+        token
+        for token in re.split(r"[^0-9a-zA-Z\u4e00-\u9fff]+", value.lower())
+        if len(token) >= 2
+    }