agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/sandbox/backends/e2b.py

@@ -12,6 +12,7 @@ from ksadk.sandbox.base import (
     SandboxSession,
     SandboxSpec,
 )
+from ksadk.sandbox.e2b_connection import ExplicitE2BConnection
 
 logger = logging.getLogger(__name__)
 
@@ -81,6 +82,22 @@ class E2BSandboxSession:
     def read_file(self, path: str) -> str:
         return str(self._sandbox.files.read(path))
 
+    def read_file_bytes(self, path: str, *, max_bytes: int) -> bytes:
+        if type(max_bytes) is not int or max_bytes < 1:
+            raise ValueError("File download limit must be positive")
+        stream = self._sandbox.files.read(path, format="stream", request_timeout=30)
+        content = bytearray()
+        try:
+            for chunk in stream:
+                if len(content) + len(chunk) > max_bytes:
+                    raise ValueError("Sandbox file exceeds download limit")
+                content.extend(chunk)
+        finally:
+            close = getattr(stream, "close", None)
+            if close is not None:
+                close()
+        return bytes(content)
+
     def run_command(
         self,
         command: str,
@@ -116,19 +133,24 @@ class E2BSandboxBackend:
         *,
         spec: SandboxSpec,
         sandbox_cls: Any | None = None,
+        connection: ExplicitE2BConnection | None = None,
     ):
         if not spec.template_id:
             raise SandboxError("E2B sandbox backend requires a template id")
         self.spec = spec
         self.sandbox_cls = sandbox_cls
+        self.connection = (
+            ExplicitE2BConnection.model_validate(connection.model_dump())
+            if connection is not None else None
+        )
 
-    def create_session(
-        self,
-        *,
-        session_id: str,
-        env: dict[str, str] | None = None,
-        input_files: list[SandboxInputFile] | None = None,
-    ) -> SandboxSession:
+    def check_available(self) -> None:
+        """Validate local SDK/connection configuration without creating a sandbox."""
+        if self.connection is not None:
+            self.connection.sdk_options()
+        self._sandbox_class()
+
+    def _sandbox_class(self):
         sandbox_cls = self.sandbox_cls
         if sandbox_cls is None:
             try:
@@ -138,6 +160,17 @@ class E2BSandboxBackend:
                     "e2b>=2.15.3,<2.25.0 is required for KSADK_SANDBOX_BACKEND=e2b"
                 ) from exc
             sandbox_cls = Sandbox
+        return sandbox_cls
+
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        env: dict[str, str] | None = None,
+        input_files: list[SandboxInputFile] | None = None,
+    ) -> SandboxSession:
+        connection_options = self.connection.sdk_options() if self.connection is not None else {}
+        sandbox_cls = self._sandbox_class()
 
         metadata = {
             "runtime": "ksadk",
@@ -152,12 +185,20 @@ class E2BSandboxBackend:
             metadata=metadata,
             envs=runtime_env,
             allow_internet_access=self.spec.allow_internet_access,
+            **connection_options,
         )
         session = self._wrap_sandbox(sandbox)
-        self._wait_until_ready(session, runtime_env)
-        session.write_files(
-            [(item.target_path, item.source.read_bytes()) for item in input_files or []]
-        )
+        try:
+            self._wait_until_ready(session, runtime_env)
+            session.write_files(
+                [(item.target_path, item.source.read_bytes()) for item in input_files or []]
+            )
+        except BaseException:
+            try:
+                session.kill()
+            except Exception:
+                logger.warning("E2B sandbox cleanup failed after initialization failure")
+            raise
         return session
 
     def _wrap_sandbox(self, sandbox: Any) -> E2BSandboxSession:

ksadk/sandbox/backends/local_process.py

@@ -38,6 +38,15 @@ class LocalProcessSandboxSession:
     def read_file(self, path: str) -> str:
         return self._resolve_workspace_path(path).read_text(encoding="utf-8")
 
+    def read_file_bytes(self, path: str, *, max_bytes: int) -> bytes:
+        if type(max_bytes) is not int or max_bytes < 1:
+            raise ValueError("File download limit must be positive")
+        with self._resolve_workspace_path(path).open("rb") as source:
+            content = source.read(max_bytes + 1)
+        if len(content) > max_bytes:
+            raise ValueError("Sandbox file exceeds download limit")
+        return content
+
     def run_command(
         self,
         command: str,

ksadk/sandbox/base.py

@@ -72,6 +72,8 @@ class SandboxSession(Protocol):
 
     def read_file(self, path: str) -> str: ...
 
+    def read_file_bytes(self, path: str, *, max_bytes: int) -> bytes: ...
+
     def run_command(
         self,
         command: str,

ksadk/sandbox/e2b_connection.py

@@ -0,0 +1,66 @@
+"""Explicit E2B connection for dedicated, environment-isolated resource workers."""
+
+from __future__ import annotations
+
+import os
+import re
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+from ksadk.sandbox.base import SandboxError
+
+
+class ExplicitE2BConnection(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
+
+    api_url: str = Field(strict=True)
+    domain: str = Field(strict=True)
+    api_key: SecretStr = Field(min_length=1, repr=False)
+
+    @model_validator(mode="after")
+    def validate_target(self):
+        url = urlsplit(self.api_url)
+        if (
+            url.scheme != "https"
+            or not url.hostname
+            or url.username is not None
+            or url.password is not None
+            or url.query
+            or url.fragment
+            or url.path not in {"", "/"}
+            or any(c.isspace() for c in self.api_url)
+        ):
+            raise ValueError("E2B API target must be an explicit HTTPS origin")
+        if not re.fullmatch(r"[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9-]+)*", self.domain):
+            raise ValueError("E2B domain must be an explicit hostname")
+        return self
+
+    def sdk_options(self) -> dict:
+        """Credential-bearing arguments for SDK creation only, never for logs/archives.
+
+        E2B 2.15.3 uses boolean-or defaults for debug and sandbox URL. Passing
+        False/None cannot disable their env fallback; dedicated workers omit them.
+        """
+        contaminated = (
+            "E2B_DEBUG",
+            "E2B_SANDBOX_URL",
+            "E2B_ACCESS_TOKEN",
+            "HTTP_PROXY",
+            "HTTPS_PROXY",
+            "ALL_PROXY",
+            "http_proxy",
+            "https_proxy",
+            "all_proxy",
+            "SSL_CERT_FILE",
+            "SSL_CERT_DIR",
+        )
+        if any(os.environ.get(name) for name in contaminated):
+            raise SandboxError("E2B explicit connections require an isolated worker environment")
+        return {
+            "api_key": self.api_key.get_secret_value(),
+            "api_url": self.api_url,
+            "domain": self.domain,
+            "debug": False,
+            "request_timeout": 30,
+        }

ksadk/scheduler/sqlite_store.py

@@ -223,6 +223,24 @@ class SchedulerSQLiteStore:
             ).fetchall()
         return [ScheduleOccurrence.model_validate_json(row["body_json"]) for row in rows]
 
+    def list_task_occurrence_summaries(self) -> list[ScheduleOccurrence]:
+        """One current state per live task, independent of the history page.
+
+        An active run takes precedence over a newer skipped overlap. Otherwise
+        the most recent occurrence owns the task's board state.
+        """
+        with self._connect() as connection:
+            rows = connection.execute(
+                """SELECT o.body_json FROM scheduler_tasks t
+                JOIN scheduler_occurrences o ON o.occurrence_id = (
+                    SELECT occurrence_id FROM scheduler_occurrences
+                    WHERE task_id = t.task_id
+                    ORDER BY (state IN ('claimed','accepted','running')) DESC,
+                             scheduled_for DESC, occurrence_id DESC LIMIT 1
+                )"""
+            ).fetchall()
+        return [ScheduleOccurrence.model_validate_json(row["body_json"]) for row in rows]
+
     def list_active_occurrences(self, *, limit: int = 200) -> list[ScheduleOccurrence]:
         """Return only non-terminal occurrences for event reconciliation.
 

ksadk/server/composition.py

@@ -40,11 +40,13 @@ def _configure_route_dependencies() -> None:
         _DetachedSSEStream,
         detached_streaming_response,
     )
+    from ksadk.sessions.persistence import get_persistence_status
 
     dependencies.configure(
         dependencies.ServerRouteDependencies(
             resolve_session_service=lambda: get_state().resolve_session_service(),
             describe_session_backend=lambda: get_state().describe_session_backend(),
+            get_persistence_status=get_persistence_status,
             resolve_agent_ui_spec=_resolve_agent_ui_spec,
             conversation=lambda: conversation,
             detached_streaming_response=detached_streaming_response,

ksadk/server/factory.py

@@ -37,6 +37,7 @@ from ksadk.sandbox.registry import (
     bind_sandbox_registry,
     set_fallback_sandbox_registry,
 )
+from ksadk.server.persistence_capability import PersistenceCapabilityCoordinator
 
 logger = logging.getLogger(__name__)
 
@@ -91,6 +92,7 @@ class StreamRegistry:
         self.streams_by_invocation: dict[str, Any] = {}
         self.resume_keys_by_invocation: dict[str, tuple[str, str]] = {}
         self.active_resume_invocation_by_key: dict[tuple[str, str], str] = {}
+        self.resume_key_lock = asyncio.Lock()
 
     def clear(self) -> None:
         self.streams.clear()
@@ -130,6 +132,7 @@ class RuntimeAppState:
         # AG-UI endpoint 及其 app-owned RuntimeAdapter handle registry。
         self.agui_agent: Any = None
         self.agui_config: Any = None
+        self.persistence_capability = PersistenceCapabilityCoordinator()
 
     def resolve_session_service(self) -> Any:
         """Return this app's session service for the current execution loop."""
@@ -289,6 +292,8 @@ async def shutdown_runtime_resources(state: RuntimeAppState) -> None:
         await asyncio.gather(*pending_streams, return_exceptions=True)
     registry.clear()
 
+    await state.persistence_capability.aclose()
+
     if state.executor is not None:
         try:
             await state.executor.close_all()