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

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

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