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

ksadk/runtime_context.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Iterator
 
 
@@ -22,10 +22,14 @@ class PlatformInvocationContext:
     has_current_files: bool
     runner_type: str
     account_id: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
     model: str | None = None
     model_options: dict[str, Any] | None = None
     kb_context: dict[str, Any] | None = None
     memory_context: dict[str, Any] | None = None
+    # Request-scoped runtime control. It is intentionally separate from
+    # public caller metadata so built-in tools can enforce it consistently.
+    tool_approval_mode: str = ""
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -43,6 +47,7 @@ class PlatformInvocationContext:
             "current_attachment_results": list(self.current_attachment_results or []),
             "has_current_files": self.has_current_files,
             "runner_type": self.runner_type,
+            "metadata": dict(self.metadata or {}),
             "model": self.model,
             "model_options": dict(self.model_options or {}),
         }
@@ -122,7 +127,14 @@ def set_current_invocation_context(
 def reset_current_invocation_context(
     token: Token[PlatformInvocationContext | None],
 ) -> None:
-    _CURRENT_PLATFORM_INVOCATION_CONTEXT.reset(token)
+    try:
+        _CURRENT_PLATFORM_INVOCATION_CONTEXT.reset(token)
+    except ValueError:
+        # ASGI streaming may resume an async generator in a descendant
+        # Context after it yielded an interrupt. Tokens cannot be reset from
+        # that different Context; clearing the active descendant avoids
+        # converting a successfully persisted approval pause into a failed run.
+        _CURRENT_PLATFORM_INVOCATION_CONTEXT.set(None)
 
 
 def set_current_tool_execution_context(
@@ -134,7 +146,10 @@ def set_current_tool_execution_context(
 def reset_current_tool_execution_context(
     token: Token[ToolExecutionContext | None],
 ) -> None:
-    _CURRENT_TOOL_EXECUTION_CONTEXT.reset(token)
+    try:
+        _CURRENT_TOOL_EXECUTION_CONTEXT.reset(token)
+    except ValueError:
+        _CURRENT_TOOL_EXECUTION_CONTEXT.set(None)
 
 
 @contextmanager

ksadk/runtime_state.py

@@ -7,7 +7,6 @@ from typing import Any
 
 import yaml
 
-
 STATE_FILE_NAME = ".agentengine.state"
 
 

ksadk/sandbox/__init__.py

@@ -1,5 +1,8 @@
 from ksadk.sandbox.backends.e2b import E2BSandboxBackend, E2BSandboxSession
-from ksadk.sandbox.backends.local_process import LocalProcessSandboxBackend, LocalProcessSandboxSession
+from ksadk.sandbox.backends.local_process import (
+    LocalProcessSandboxBackend,
+    LocalProcessSandboxSession,
+)
 from ksadk.sandbox.base import (
     SandboxBackend,
     SandboxCommandResult,

ksadk/sandbox/backends/__init__.py

@@ -1,5 +1,8 @@
 from ksadk.sandbox.backends.e2b import E2BSandboxBackend, E2BSandboxSession
-from ksadk.sandbox.backends.local_process import LocalProcessSandboxBackend, LocalProcessSandboxSession
+from ksadk.sandbox.backends.local_process import (
+    LocalProcessSandboxBackend,
+    LocalProcessSandboxSession,
+)
 
 __all__ = [
     "E2BSandboxBackend",

ksadk/sandbox/backends/e2b.py

@@ -67,6 +67,11 @@ class E2BSandboxSession:
     def write_file(self, path: str, data: str | bytes) -> None:
         self._sandbox.files.write(path, data)
 
+    def write_files(self, files: list[tuple[str, str | bytes]]) -> None:
+        if not files:
+            return
+        self._sandbox.files.write_files([{"path": path, "data": data} for path, data in files])
+
     def read_file(self, path: str) -> str:
         return str(self._sandbox.files.read(path))
 
@@ -78,7 +83,7 @@ class E2BSandboxSession:
         env: dict[str, str] | None = None,
         cwd: str | None = None,
     ) -> SandboxCommandResult:
-        kwargs = {}
+        kwargs: dict[str, Any] = {}
         if timeout is not None:
             kwargs["timeout"] = timeout
         if env is not None:
@@ -121,9 +126,11 @@ class E2BSandboxBackend:
         sandbox_cls = self.sandbox_cls
         if sandbox_cls is None:
             try:
-                from e2b import Sandbox
+                from e2b import Sandbox  # type: ignore[import-untyped]
             except ImportError as exc:
-                raise SandboxError("e2b>=2.0.0 is required for KSADK_SANDBOX_BACKEND=e2b") from exc
+                raise SandboxError(
+                    "e2b>=2.15.3,<2.25.0 is required for KSADK_SANDBOX_BACKEND=e2b"
+                ) from exc
             sandbox_cls = Sandbox
 
         metadata = {
@@ -142,8 +149,9 @@ class E2BSandboxBackend:
         )
         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())
+        session.write_files(
+            [(item.target_path, item.source.read_bytes()) for item in input_files or []]
+        )
         return session
 
     def _wrap_sandbox(self, sandbox: Any) -> E2BSandboxSession:

ksadk/sandbox/backends/local_process.py

@@ -8,8 +8,16 @@ from pathlib import Path
 from ksadk.sandbox.base import SandboxCommandResult, SandboxInputFile, SandboxSession
 
 
+def _coerce_output(value: str | bytes | None) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return value or ""
+
+
 class LocalProcessSandboxSession:
-    def __init__(self, *, session_id: str, workspace_root: Path, backend_name: str = "local_process"):
+    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)
@@ -67,8 +75,8 @@ class LocalProcessSandboxSession:
                 pass
             stdout, stderr = process.communicate()
             return SandboxCommandResult(
-                stdout=stdout or exc.stdout or "",
-                stderr=(stderr or exc.stderr or "") + "\ncommand timed out",
+                stdout=_coerce_output(stdout or exc.stdout),
+                stderr=_coerce_output(stderr or exc.stderr) + "\ncommand timed out",
                 exit_code=124,
             )
 

ksadk/sandbox/base.py

@@ -20,7 +20,9 @@ class SandboxType(str, Enum):
     def from_value(cls, value: str | "SandboxType" | None) -> "SandboxType":
         if isinstance(value, SandboxType):
             return value
-        normalized = (value or "").strip().lower().replace("_", "").replace("-", "").replace(" ", "")
+        normalized = (
+            (value or "").strip().lower().replace("_", "").replace("-", "").replace(" ", "")
+        )
         aliases = {
             "": cls.AIO,
             "aio": cls.AIO,
@@ -64,14 +66,11 @@ class SandboxSpec:
 
 class SandboxSession(Protocol):
     @property
-    def sandbox_id(self) -> str:
-        ...
+    def sandbox_id(self) -> str: ...
 
-    def write_file(self, path: str, data: str | bytes) -> None:
-        ...
+    def write_file(self, path: str, data: str | bytes) -> None: ...
 
-    def read_file(self, path: str) -> str:
-        ...
+    def read_file(self, path: str) -> str: ...
 
     def run_command(
         self,
@@ -80,14 +79,11 @@ class SandboxSession(Protocol):
         timeout: int | None = None,
         env: dict[str, str] | None = None,
         cwd: str | None = None,
-    ) -> SandboxCommandResult:
-        ...
+    ) -> SandboxCommandResult: ...
 
-    def get_host(self, port: int) -> str:
-        ...
+    def get_host(self, port: int) -> str: ...
 
-    def kill(self) -> None:
-        ...
+    def kill(self) -> None: ...
 
 
 class SandboxBackend(Protocol):
@@ -97,5 +93,4 @@ class SandboxBackend(Protocol):
         session_id: str,
         env: dict[str, str] | None = None,
         input_files: list[SandboxInputFile] | None = None,
-    ) -> SandboxSession:
-        ...
+    ) -> SandboxSession: ...

ksadk/sandbox/factory.py

@@ -23,11 +23,17 @@ def create_sandbox_backend(
 ) -> 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")
+        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")
+            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)
@@ -39,7 +45,11 @@ def sandbox_spec_from_env() -> SandboxSpec:
         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")
+    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),

ksadk/sandbox/registry.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import atexit
+import contextvars
 import logging
 import os
 import threading
 import time
+from contextlib import contextmanager
 from dataclasses import dataclass
+from typing import Any, Iterator
 
 from ksadk.sandbox.base import SandboxBackend, SandboxSession
 
@@ -43,7 +46,9 @@ class SandboxRegistry:
 
     @staticmethod
     def _resolve_sweep_interval() -> int:
-        raw = os.environ.get("KSADK_SANDBOX_SWEEP_INTERVAL_SECONDS", str(_DEFAULT_SWEEP_INTERVAL_SECONDS))
+        raw = os.environ.get(
+            "KSADK_SANDBOX_SWEEP_INTERVAL_SECONDS", str(_DEFAULT_SWEEP_INTERVAL_SECONDS)
+        )
         try:
             value = int(raw)
         except (TypeError, ValueError):
@@ -103,7 +108,8 @@ class SandboxRegistry:
             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)
+                if entry.expires_at <= current
+                or (idle_ttl > 0 and current - entry.last_used_at > idle_ttl)
             ]
         for key in expired:
             self.kill(key)
@@ -138,7 +144,8 @@ class SandboxRegistry:
         with self._lock:
             while len(self._entries) - len(to_kill) >= max_sessions:
                 candidates = [
-                    entry for entry in self._entries.values()
+                    entry
+                    for entry in self._entries.values()
                     if entry.key != keep_key and entry.key not in to_kill
                 ]
                 if not candidates:
@@ -171,17 +178,61 @@ class SandboxRegistry:
 
     def reset_for_tests(self) -> None:
         """停后台 sweep 线程并清空所有 entry,用于测试隔离。"""
+        self.close()
+        self._idle_ttl_seconds = 0
+        self._sweep_stop.clear()
+
+    def close(self) -> None:
+        """Stop the owned sweep thread and kill every sandbox session."""
         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()
+_current_sandbox_registry: contextvars.ContextVar[SandboxRegistry | None] = contextvars.ContextVar(
+    "ksadk_sandbox_registry", default=None
+)
+_fallback_sandbox_registry = SandboxRegistry()
+
+
+def set_fallback_sandbox_registry(registry: SandboxRegistry) -> None:
+    """Set the registry used by legacy calls outside a bound app context."""
+    global _fallback_sandbox_registry
+    _fallback_sandbox_registry = registry
+
+
+@contextmanager
+def bind_sandbox_registry(registry: SandboxRegistry) -> Iterator[None]:
+    token = _current_sandbox_registry.set(registry)
+    try:
+        yield
+    finally:
+        _current_sandbox_registry.reset(token)
+
+
+def get_sandbox_registry() -> SandboxRegistry:
+    return _current_sandbox_registry.get() or _fallback_sandbox_registry
+
+
+class _ContextualSandboxRegistry:
+    """Compatibility proxy resolving the registry owned by the current app."""
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(get_sandbox_registry(), name)
+
+    def clear(self) -> None:
+        # Keep atexit dynamic: resolve the default app registry when invoked,
+        # not when the callback is registered.
+        get_sandbox_registry().clear()
+
+    def close(self) -> None:
+        get_sandbox_registry().close()
+
+
+GLOBAL_SANDBOX_REGISTRY = _ContextualSandboxRegistry()
 # 进程退出时清理 sandbox,避免 E2B sandbox 活到服务端 timeout 才销毁(按秒计费)。
 # clear() 幂等,与 server lifespan shutdown 重复调用安全。kill -9 不触发 atexit,只能靠 E2B 兜底。
 atexit.register(GLOBAL_SANDBOX_REGISTRY.clear)

ksadk/server/api_models.py

@@ -1,13 +1,16 @@
-from typing import List, Optional, Dict, Any, Union
-from pydantic import BaseModel, Field
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel
 
 # --- Consolidating Part Types ---
 
+
 class FunctionCall(BaseModel):
     id: Optional[str] = None
     name: str
     args: Dict[str, Any]
 
+
 class FunctionResponse(BaseModel):
     id: Optional[str] = None
     name: str
@@ -32,19 +35,22 @@ class Part(BaseModel):
     functionResponse: Optional[FunctionResponse] = None
     inlineData: Optional[InlineData] = None
     fileData: Optional[FileData] = None
-    
-    # Simple alias for JSON field mapping if needed, 
+
+    # Simple alias for JSON field mapping if needed,
     # but Pydantic usually handles this with field aliases if inputs differ.
     # For now we stick to the TS interface names.
 
+
 class GenAiContent(BaseModel):
     role: str = "user"
     parts: List[Part]
 
+
 class NewMessage(BaseModel):
     parts: List[Part]
     role: str = "user"
 
+
 class AgentRunRequest(BaseModel):
     appName: str
     userId: str
@@ -56,18 +62,22 @@ class AgentRunRequest(BaseModel):
     functionCallEventId: Optional[str] = None
     model: Optional[str] = None
 
+
 # --- Response Types ---
 
+
 class LlmResponse(BaseModel):
     content: Optional[GenAiContent] = None
     error: Optional[str] = None
 
+
 class Session(BaseModel):
     id: str
     userId: str
     appName: str
     createdTime: Optional[float] = None
     updatedTime: Optional[float] = None
-    
+
+
 class AppListResponse(BaseModel):
     apps: List[str]