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

ksadk/sandbox/base.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Protocol
+from typing import Protocol, runtime_checkable
 
 
 class SandboxError(RuntimeError):
@@ -88,6 +88,56 @@ class SandboxSession(Protocol):
     def kill(self) -> None: ...
 
 
+@runtime_checkable
+class SandboxCommandHandle(Protocol):
+    """Optional handle for a command that can be stopped explicitly."""
+
+    def wait(self) -> SandboxCommandResult: ...
+
+    def kill(self) -> bool: ...
+
+
+@runtime_checkable
+class BackgroundCommandSandboxSession(Protocol):
+    """Optional session extension used for truthful cooperative cancellation."""
+
+    def start_command(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> SandboxCommandHandle: ...
+
+
+@runtime_checkable
+class ReconnectableSandboxCommandHandle(SandboxCommandHandle, Protocol):
+    """Optional command handle with a credential-free vendor process ID."""
+
+    @property
+    def process_id(self) -> int: ...
+
+
+@runtime_checkable
+class ReconnectableCommandSandboxSession(BackgroundCommandSandboxSession, Protocol):
+    """Optional session extension for reconnecting an in-flight command."""
+
+    def connect_command(
+        self,
+        process_id: int,
+        *,
+        timeout: int | None = None,
+    ) -> ReconnectableSandboxCommandHandle: ...
+
+
+@runtime_checkable
+class ArtifactListingSandboxSession(Protocol):
+    """Optional session extension for bounded artifact enumeration."""
+
+    def list_files(self, root: str, *, recursive: bool = True) -> list[str]: ...
+
+
 class SandboxBackend(Protocol):
     def create_session(
         self,
@@ -96,3 +146,14 @@ class SandboxBackend(Protocol):
         env: dict[str, str] | None = None,
         input_files: list[SandboxInputFile] | None = None,
     ) -> SandboxSession: ...
+
+
+@runtime_checkable
+class ReconnectableSandboxBackend(Protocol):
+    """Optional SDK backend extension for reconnecting an existing session.
+
+    ``session_locator`` is an opaque vendor locator (for example an E2B
+    sandbox ID).  It must not contain credentials or environment values.
+    """
+
+    def reconnect_session(self, *, session_locator: str) -> SandboxSession: ...

ksadk/sandbox/diagnostics.py

@@ -0,0 +1,82 @@
+"""Step-level E2B diagnostics without credential-bearing request dumps."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import time
+import traceback
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_detail(value: str, secrets: tuple[str, ...]) -> str:
+    for secret in sorted(set(secrets), key=len, reverse=True):
+        if secret:
+            value = value.replace(secret, "[REDACTED]")
+    # Exception text can contain signed URLs, headers or SDK-generated tokens.
+    value = re.sub(r"https?://[^\s\"'<>]+", "[REDACTED_URL]", value)
+    value = re.sub(
+        r"(?i)(authorization|api[_-]?key|token|secret|password)\s*[:=]\s*[^\n]+",
+        r"\1=[REDACTED]",
+        value,
+    )
+    return value
+
+
+@contextmanager
+def e2b_diagnostic_step(
+    step: str,
+    *,
+    runtime_id: str = "",
+    sensitive_values: tuple[str, ...] = (),
+    env: Mapping[str, str] | None = None,
+) -> Iterator[None]:
+    """Log progress and sanitized exception chains; preserve operation semantics."""
+    started = time.monotonic()
+    logger.info("E2B_DIAGNOSTIC step=%s status=started runtime_id=%s", step, runtime_id)
+    try:
+        yield
+    except Exception as exc:
+        secrets = (
+            sensitive_values
+            + tuple((env or {}).values())
+            + tuple(
+                value
+                for key, value in os.environ.items()
+                if any(part in key.upper() for part in ("KEY", "TOKEN", "SECRET", "PASSWORD"))
+            )
+        )
+        # No locals or source lines: either can contain literal credentials.
+        trace = traceback.TracebackException.from_exception(exc, capture_locals=False)
+        pending = [trace]
+        while pending:
+            current = pending.pop()
+            current.stack = traceback.StackSummary.from_list(
+                traceback.FrameSummary(frame.filename, frame.lineno, frame.name, line="")
+                for frame in current.stack
+            )
+            pending.extend(
+                item for item in (current.__cause__, current.__context__) if item is not None
+            )
+            pending.extend(getattr(current, "exceptions", None) or [])
+        detail = _safe_detail("".join(trace.format(chain=True)), secrets)
+        logger.error(
+            "E2B_DIAGNOSTIC step=%s status=failed runtime_id=%s duration_ms=%d error_type=%s\n%s",
+            step,
+            runtime_id,
+            int((time.monotonic() - started) * 1000),
+            type(exc).__name__,
+            detail,
+        )
+        raise
+    else:
+        logger.info(
+            "E2B_DIAGNOSTIC step=%s status=completed runtime_id=%s duration_ms=%d",
+            step,
+            runtime_id,
+            int((time.monotonic() - started) * 1000),
+        )