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

ksadk/sandbox/backends/e2b.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+from ksadk.sandbox.base import (
+    SandboxCommandResult,
+    SandboxError,
+    SandboxInputFile,
+    SandboxSession,
+    SandboxSpec,
+)
+
+_TRANSIENT_STARTUP_ERROR_NAMES = {
+    "NotFoundException",
+    "FileNotFoundException",
+    "SandboxNotFoundException",
+}
+
+
+def _startup_retry_attempts() -> int:
+    raw = os.environ.get("KSADK_SANDBOX_STARTUP_RETRY_ATTEMPTS", "6")
+    try:
+        return max(1, int(raw))
+    except ValueError:
+        return 6
+
+
+def _startup_retry_delay() -> float:
+    raw = os.environ.get("KSADK_SANDBOX_STARTUP_RETRY_DELAY", "0.2")
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return 0.2
+
+
+def _is_transient_startup_error(exc: Exception) -> bool:
+    return type(exc).__name__ in _TRANSIENT_STARTUP_ERROR_NAMES
+
+
+def _with_startup_retry(operation):
+    attempts = _startup_retry_attempts()
+    delay = _startup_retry_delay()
+    last_exc: Exception | None = None
+    for attempt in range(attempts):
+        try:
+            return operation()
+        except Exception as exc:
+            if not _is_transient_startup_error(exc) or attempt >= attempts - 1:
+                raise
+            last_exc = exc
+            time.sleep(min(delay * (2**attempt), 1.0))
+    if last_exc is not None:
+        raise last_exc
+    raise SandboxError("E2B sandbox startup retry failed unexpectedly")
+
+
+class E2BSandboxSession:
+    def __init__(self, sandbox: Any):
+        self._sandbox = sandbox
+
+    @property
+    def sandbox_id(self) -> str:
+        return str(getattr(self._sandbox, "sandbox_id", "") or "")
+
+    def write_file(self, path: str, data: str | bytes) -> None:
+        self._sandbox.files.write(path, data)
+
+    def read_file(self, path: str) -> str:
+        return str(self._sandbox.files.read(path))
+
+    def run_command(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> SandboxCommandResult:
+        kwargs = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        if env is not None:
+            kwargs["envs"] = env
+        if cwd is not None:
+            kwargs["cwd"] = cwd
+        result = self._sandbox.commands.run(command, **kwargs)
+        return SandboxCommandResult(
+            stdout=str(getattr(result, "stdout", "") or ""),
+            stderr=str(getattr(result, "stderr", "") or ""),
+            exit_code=getattr(result, "exit_code", None),
+        )
+
+    def get_host(self, port: int) -> str:
+        return str(self._sandbox.get_host(port))
+
+    def kill(self) -> None:
+        self._sandbox.kill()
+
+
+class E2BSandboxBackend:
+    def __init__(
+        self,
+        *,
+        spec: SandboxSpec,
+        sandbox_cls: Any | None = None,
+    ):
+        if not spec.template_id:
+            raise SandboxError("E2B sandbox backend requires a template id")
+        self.spec = spec
+        self.sandbox_cls = sandbox_cls
+
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        env: dict[str, str] | None = None,
+        input_files: list[SandboxInputFile] | None = None,
+    ) -> SandboxSession:
+        sandbox_cls = self.sandbox_cls
+        if sandbox_cls is None:
+            try:
+                from e2b import Sandbox
+            except ImportError as exc:
+                raise SandboxError("e2b>=2.0.0 is required for KSADK_SANDBOX_BACKEND=e2b") from exc
+            sandbox_cls = Sandbox
+
+        metadata = {
+            "runtime": "ksadk",
+            "sandbox_type": self.spec.sandbox_type.value,
+            **self.spec.metadata,
+            "session_id": session_id,
+        }
+        runtime_env = {**self.spec.env, **(env or {})}
+        sandbox = sandbox_cls.create(
+            template=self.spec.template_id,
+            timeout=self.spec.timeout,
+            metadata=metadata,
+            envs=runtime_env,
+            allow_internet_access=self.spec.allow_internet_access,
+        )
+        session = self._wrap_sandbox(sandbox)
+        self._wait_until_ready(session)
+        for item in input_files or []:
+            session.write_file(item.target_path, item.source.read_bytes())
+        return session
+
+    def _wrap_sandbox(self, sandbox: Any) -> E2BSandboxSession:
+        return E2BSandboxSession(sandbox)
+
+    def _wait_until_ready(self, session: E2BSandboxSession) -> None:
+        _with_startup_retry(lambda: session.run_command("true"))
+        _with_startup_retry(lambda: session.write_file("/tmp/.ksadk-sandbox-ready", ""))

ksadk/sandbox/backends/local_process.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from pathlib import Path
+
+from ksadk.sandbox.base import SandboxCommandResult, SandboxInputFile, SandboxSession
+
+
+class LocalProcessSandboxSession:
+    def __init__(self, *, session_id: str, workspace_root: Path, backend_name: str = "local_process"):
+        self._session_id = session_id
+        self._workspace_root = workspace_root.expanduser().resolve()
+        self._workspace_root.mkdir(parents=True, exist_ok=True)
+        self._backend_name = backend_name
+
+    @property
+    def sandbox_id(self) -> str:
+        return f"{self._backend_name}:{self._session_id}"
+
+    def write_file(self, path: str, data: str | bytes) -> None:
+        target = self._resolve_workspace_path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(data, bytes):
+            target.write_bytes(data)
+        else:
+            target.write_text(data, encoding="utf-8")
+
+    def read_file(self, path: str) -> str:
+        return self._resolve_workspace_path(path).read_text(encoding="utf-8")
+
+    def run_command(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> SandboxCommandResult:
+        try:
+            resolved_cwd = self._resolve_cwd(cwd or (env or {}).get("KSADK_COMMAND_CWD"))
+        except ValueError as exc:
+            return SandboxCommandResult(stderr=str(exc), exit_code=126)
+        process_env = self._allowed_env(env or {})
+        try:
+            process = subprocess.Popen(
+                command,
+                shell=True,
+                cwd=resolved_cwd,
+                env=process_env,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                start_new_session=True,
+            )
+            stdout, stderr = process.communicate(timeout=timeout)
+            return SandboxCommandResult(
+                stdout=stdout,
+                stderr=stderr,
+                exit_code=process.returncode,
+            )
+        except subprocess.TimeoutExpired as exc:
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except Exception:
+                pass
+            stdout, stderr = process.communicate()
+            return SandboxCommandResult(
+                stdout=stdout or exc.stdout or "",
+                stderr=(stderr or exc.stderr or "") + "\ncommand timed out",
+                exit_code=124,
+            )
+
+    def get_host(self, port: int) -> str:
+        return f"http://127.0.0.1:{int(port)}"
+
+    def kill(self) -> None:
+        return None
+
+    def _resolve_cwd(self, cwd: str | None) -> Path:
+        if not cwd:
+            return self._workspace_root
+        candidate = Path(cwd)
+        if not candidate.is_absolute():
+            candidate = self._workspace_root / candidate
+        resolved = candidate.expanduser().resolve()
+        if resolved != self._workspace_root and self._workspace_root not in resolved.parents:
+            raise ValueError("cwd must stay inside the sandbox workspace")
+        return resolved
+
+    def _resolve_workspace_path(self, path: str) -> Path:
+        raw = str(path or "").strip().lstrip("/") or "."
+        target = (self._workspace_root / raw).resolve()
+        if target != self._workspace_root and self._workspace_root not in target.parents:
+            raise ValueError("path must stay inside the sandbox workspace")
+        return target
+
+    @staticmethod
+    def _allowed_env(env: dict[str, str]) -> dict[str, str]:
+        allowed = {"PATH": os.environ.get("PATH", ""), "HOME": os.environ.get("HOME", "")}
+        for key, value in env.items():
+            if key.startswith("KSADK_COMMAND_"):
+                continue
+            if key.startswith(("KSADK_SAFE_", "PYTHON", "NODE", "UV_")):
+                allowed[key] = str(value)
+        return allowed
+
+
+class LocalProcessSandboxBackend:
+    isolated = False
+
+    def __init__(self, *, workspace_root: Path, backend_name: str = "local_process"):
+        self.workspace_root = workspace_root
+        self.backend_name = backend_name
+
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        env: dict[str, str] | None = None,
+        input_files: list[SandboxInputFile] | None = None,
+    ) -> SandboxSession:
+        session = LocalProcessSandboxSession(
+            session_id=session_id,
+            workspace_root=self.workspace_root,
+            backend_name=self.backend_name,
+        )
+        for item in input_files or []:
+            session.write_file(item.target_path, item.source.read_bytes())
+        return session

ksadk/sandbox/base.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Protocol
+
+
+class SandboxError(RuntimeError):
+    pass
+
+
+class SandboxType(str, Enum):
+    AIO = "aio"
+    CODE = "code"
+    BROWSER = "browser"
+    PRIVATE = "private"
+
+    @classmethod
+    def from_value(cls, value: str | "SandboxType" | None) -> "SandboxType":
+        if isinstance(value, SandboxType):
+            return value
+        normalized = (value or "").strip().lower().replace("_", "").replace("-", "").replace(" ", "")
+        aliases = {
+            "": cls.AIO,
+            "aio": cls.AIO,
+            "allinone": cls.AIO,
+            "code": cls.CODE,
+            "codeinterpreter": cls.CODE,
+            "codesandbox": cls.CODE,
+            "browser": cls.BROWSER,
+            "browsersandbox": cls.BROWSER,
+            "private": cls.PRIVATE,
+            "custom": cls.PRIVATE,
+        }
+        try:
+            return aliases[normalized]
+        except KeyError as exc:
+            raise SandboxError(f"Unsupported sandbox type: {value}") from exc
+
+
+@dataclass(frozen=True)
+class SandboxInputFile:
+    source: Path
+    target_path: str
+
+
+@dataclass(frozen=True)
+class SandboxCommandResult:
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int | None = None
+
+
+@dataclass(frozen=True)
+class SandboxSpec:
+    template_id: str
+    sandbox_type: SandboxType = SandboxType.AIO
+    timeout: int = 900
+    allow_internet_access: bool = True
+    metadata: dict[str, str] = field(default_factory=dict)
+    env: dict[str, str] = field(default_factory=dict)
+
+
+class SandboxSession(Protocol):
+    @property
+    def sandbox_id(self) -> str:
+        ...
+
+    def write_file(self, path: str, data: str | bytes) -> None:
+        ...
+
+    def read_file(self, path: str) -> str:
+        ...
+
+    def run_command(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> SandboxCommandResult:
+        ...
+
+    def get_host(self, port: int) -> str:
+        ...
+
+    def kill(self) -> None:
+        ...
+
+
+class SandboxBackend(Protocol):
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        env: dict[str, str] | None = None,
+        input_files: list[SandboxInputFile] | None = None,
+    ) -> SandboxSession:
+        ...

ksadk/sandbox/factory.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ksadk.sandbox.backends.e2b import E2BSandboxBackend
+from ksadk.sandbox.backends.local_process import LocalProcessSandboxBackend
+from ksadk.sandbox.base import SandboxBackend, SandboxError, SandboxSpec, SandboxType
+from ksadk.sessions.local_service import resolve_local_session_dir
+
+
+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 create_sandbox_backend(
+    backend: str | None = None,
+    *,
+    sandbox_cls: Any | None = None,
+) -> SandboxBackend:
+    resolved = (backend or os.environ.get("KSADK_SANDBOX_BACKEND") or "e2b").strip().lower()
+    if resolved in {"local", "local_process"}:
+        return LocalProcessSandboxBackend(workspace_root=resolve_local_session_dir() / "workspace", backend_name="local_process")
+    if resolved in {"pod", "pod_process"}:
+        if not bool_env("KSADK_ALLOW_POD_PROCESS_TOOLS", False):
+            raise SandboxError("KSADK_ALLOW_POD_PROCESS_TOOLS=true is required for pod_process backend")
+        return LocalProcessSandboxBackend(workspace_root=resolve_local_session_dir() / "workspace", backend_name="pod_process")
+    if resolved != "e2b":
+        raise SandboxError(f"Unsupported sandbox backend: {resolved}")
+    return E2BSandboxBackend(spec=sandbox_spec_from_env(), sandbox_cls=sandbox_cls)
+
+
+def sandbox_spec_from_env() -> SandboxSpec:
+    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),
+    )
+    sandbox_type = SandboxType.from_value(os.environ.get("KSADK_SANDBOX_TYPE", "aio"))
+    return SandboxSpec(
+        template_id=template_id,
+        sandbox_type=sandbox_type,
+        timeout=timeout,
+        allow_internet_access=allow_internet_access,
+    )

ksadk/sandbox/registry.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import threading
+import time
+from dataclasses import dataclass
+
+from ksadk.sandbox.base import SandboxBackend, SandboxSession
+
+logger = logging.getLogger(__name__)
+
+# 后台 sweep 默认间隔(秒)。0 表示禁用后台 sweep,仅靠 get_or_create 时的惰性 sweep。
+_DEFAULT_SWEEP_INTERVAL_SECONDS = 60
+
+
+@dataclass
+class SandboxRegistryEntry:
+    key: str
+    backend: str
+    session: SandboxSession
+    created_at: float
+    last_used_at: float
+    expires_at: float
+    isolated: bool
+
+    @property
+    def sandbox_id(self) -> str:
+        return self.session.sandbox_id
+
+
+class SandboxRegistry:
+    def __init__(self):
+        self._entries: dict[str, SandboxRegistryEntry] = {}
+        # RLock 可重入:get_or_create 内部会调 sweep/kill/_enforce_quota。
+        self._lock = threading.RLock()
+        # idle_ttl 由 toolset 层在 get_or_create 时传入,后台 sweep 复用该值。
+        self._idle_ttl_seconds: int = 0
+        self._sweep_thread: threading.Thread | None = None
+        self._sweep_stop = threading.Event()
+        self._sweep_interval = self._resolve_sweep_interval()
+
+    @staticmethod
+    def _resolve_sweep_interval() -> int:
+        raw = os.environ.get("KSADK_SANDBOX_SWEEP_INTERVAL_SECONDS", str(_DEFAULT_SWEEP_INTERVAL_SECONDS))
+        try:
+            value = int(raw)
+        except (TypeError, ValueError):
+            return _DEFAULT_SWEEP_INTERVAL_SECONDS
+        return value if value > 0 else 0
+
+    def get_or_create(
+        self,
+        *,
+        key: str,
+        backend_name: str,
+        backend: SandboxBackend,
+        ttl_seconds: int,
+        isolated: bool,
+        idle_ttl_seconds: int | None = None,
+        max_sessions: int | None = None,
+        input_files: list | None = None,
+        now: float | None = None,
+    ) -> tuple[SandboxRegistryEntry, bool]:
+        current = time.time() if now is None else now
+        if idle_ttl_seconds is not None:
+            self._idle_ttl_seconds = int(idle_ttl_seconds or 0)
+        with self._lock:
+            self.sweep(now=current, idle_ttl_seconds=self._idle_ttl_seconds)
+            entry = self._entries.get(key)
+            if entry is not None and entry.expires_at > current:
+                entry.last_used_at = current
+                return entry, False
+            if entry is not None:
+                self.kill(key)
+            self._enforce_quota(max_sessions=max_sessions, keep_key=key)
+            session = backend.create_session(session_id=key, input_files=input_files or None)
+            entry = SandboxRegistryEntry(
+                key=key,
+                backend=backend_name,
+                session=session,
+                created_at=current,
+                last_used_at=current,
+                expires_at=current + max(1, int(ttl_seconds or 900)),
+                isolated=isolated,
+            )
+            self._entries[key] = entry
+        # 锁外启动后台线程,避免持锁创建线程。
+        self._start_sweep_thread()
+        return entry, True
+
+    def latest(self) -> SandboxRegistryEntry | None:
+        with self._lock:
+            if not self._entries:
+                return None
+            return max(self._entries.values(), key=lambda item: item.last_used_at)
+
+    def sweep(self, *, now: float | None = None, idle_ttl_seconds: int | None = None) -> int:
+        current = time.time() if now is None else now
+        idle_ttl = int(idle_ttl_seconds or 0)
+        with self._lock:
+            expired = [
+                key
+                for key, entry in self._entries.items()
+                if entry.expires_at <= current or (idle_ttl > 0 and current - entry.last_used_at > idle_ttl)
+            ]
+        for key in expired:
+            self.kill(key)
+        return len(expired)
+
+    def entries(self) -> list[SandboxRegistryEntry]:
+        with self._lock:
+            return list(self._entries.values())
+
+    def kill(self, key: str) -> bool:
+        with self._lock:
+            entry = self._entries.pop(key, None)
+        if entry is None:
+            return False
+        # session.kill() 是 E2B 网络 IO,放锁外避免持锁阻塞并发 get_or_create。
+        try:
+            entry.session.kill()
+        except Exception:
+            logger.exception("sandbox session kill failed for key=%s", key)
+        return True
+
+    def clear(self) -> None:
+        with self._lock:
+            keys = list(self._entries)
+        for key in keys:
+            self.kill(key)
+
+    def _enforce_quota(self, *, max_sessions: int | None, keep_key: str) -> None:
+        if not max_sessions or max_sessions < 1:
+            return
+        to_kill: list[str] = []
+        with self._lock:
+            while len(self._entries) - len(to_kill) >= max_sessions:
+                candidates = [
+                    entry for entry in self._entries.values()
+                    if entry.key != keep_key and entry.key not in to_kill
+                ]
+                if not candidates:
+                    break
+                oldest = min(candidates, key=lambda item: item.last_used_at)
+                to_kill.append(oldest.key)
+        for key in to_kill:
+            self.kill(key)
+
+    def _start_sweep_thread(self) -> None:
+        if self._sweep_interval <= 0:
+            return
+        with self._lock:
+            if self._sweep_thread is not None and self._sweep_thread.is_alive():
+                return
+            self._sweep_stop.clear()
+            self._sweep_thread = threading.Thread(
+                target=self._sweep_loop,
+                name="ksadk-sandbox-sweep",
+                daemon=True,
+            )
+            self._sweep_thread.start()
+
+    def _sweep_loop(self) -> None:
+        while not self._sweep_stop.wait(timeout=self._sweep_interval):
+            try:
+                self.sweep(idle_ttl_seconds=self._idle_ttl_seconds)
+            except Exception:
+                logger.exception("sandbox background sweep failed")
+
+    def reset_for_tests(self) -> None:
+        """停后台 sweep 线程并清空所有 entry,用于测试隔离。"""
+        self._sweep_stop.set()
+        thread = self._sweep_thread
+        if thread is not None and thread.is_alive():
+            thread.join(timeout=2.0)
+        self._sweep_thread = None
+        self.clear()
+        self._idle_ttl_seconds = 0
+        self._sweep_stop.clear()
+
+
+GLOBAL_SANDBOX_REGISTRY = SandboxRegistry()
+# 进程退出时清理 sandbox,避免 E2B sandbox 活到服务端 timeout 才销毁(按秒计费)。
+# clear() 幂等,与 server lifespan shutdown 重复调用安全。kill -9 不触发 atexit,只能靠 E2B 兜底。
+atexit.register(GLOBAL_SANDBOX_REGISTRY.clear)

ksadk/server/__init__.py

@@ -0,0 +1,7 @@
+"""
+KsADK Server - FastAPI 服务模块
+"""
+
+from ksadk.server.app import app, set_runner
+
+__all__ = ["app", "set_runner"]