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

ksadk/runtime_context.py

@@ -7,6 +7,79 @@ from typing import Any, Iterator, Mapping
 
 from ksadk.session_context import SessionContext
 
+TRUSTED_IDENTITY_METADATA_KEY = "_agentengine_verified_identity"
+
+
+def _identity_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+@dataclass(frozen=True)
+class PlatformIdentityContext:
+    """Verified application identity carried through one runtime invocation.
+
+    Authentication adapters create this value after validating credentials and
+    tenant membership.  It is deliberately separate from caller metadata and
+    from the cloud ``account_id``/``user_id`` compatibility fields.
+    """
+
+    identity_namespace: str = ""
+    tenant_id: str = ""
+    subject_type: str = ""
+    subject_id: str = ""
+    actor_type: str = ""
+    actor_id: str = ""
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any] | None) -> "PlatformIdentityContext":
+        if not isinstance(payload, Mapping):
+            return cls()
+        return cls(
+            identity_namespace=_identity_value(payload.get("identity_namespace")),
+            tenant_id=_identity_value(payload.get("tenant_id")),
+            subject_type=_identity_value(payload.get("subject_type")),
+            subject_id=_identity_value(payload.get("subject_id")),
+            actor_type=_identity_value(payload.get("actor_type")),
+            actor_id=_identity_value(payload.get("actor_id")),
+        )
+
+    @property
+    def is_empty(self) -> bool:
+        return not any(self.to_payload().values())
+
+    @property
+    def is_complete(self) -> bool:
+        """Whether the four authorization-scoping fields are all present."""
+
+        return all(self.user_scope)
+
+    @property
+    def tenant_scope(self) -> tuple[str, str]:
+        return self.identity_namespace, self.tenant_id
+
+    @property
+    def user_scope(self) -> tuple[str, str, str, str]:
+        return (
+            self.identity_namespace,
+            self.tenant_id,
+            self.subject_type,
+            self.subject_id,
+        )
+
+    def to_payload(self) -> dict[str, str]:
+        return {
+            key: value
+            for key, value in {
+                "identity_namespace": self.identity_namespace,
+                "tenant_id": self.tenant_id,
+                "subject_type": self.subject_type,
+                "subject_id": self.subject_id,
+                "actor_type": self.actor_type,
+                "actor_id": self.actor_id,
+            }.items()
+            if value
+        }
+
 
 @dataclass
 class PlatformInvocationContext:
@@ -24,6 +97,7 @@ class PlatformInvocationContext:
     has_current_files: bool
     runner_type: str
     account_id: str = ""
+    identity: PlatformIdentityContext = field(default_factory=PlatformIdentityContext)
     metadata: dict[str, Any] = field(default_factory=dict)
     model: str | None = None
     model_options: dict[str, Any] | None = None
@@ -57,6 +131,8 @@ class PlatformInvocationContext:
 
         if self.session.tags or self.session.revision:
             payload["session"] = self.session.to_payload()
+        if not self.identity.is_empty:
+            payload["identity"] = self.identity.to_payload()
         return payload
 
 
@@ -125,6 +201,19 @@ def get_current_account_id(default: str = "") -> str:
     return str(context.account_id or default)
 
 
+def get_current_identity_context() -> PlatformIdentityContext:
+    context = get_current_invocation_context()
+    return context.identity if context is not None else PlatformIdentityContext()
+
+
+def get_current_tenant_id(default: str = "") -> str:
+    return str(get_current_identity_context().tenant_id or default)
+
+
+def get_current_subject_id(default: str = "") -> str:
+    return str(get_current_identity_context().subject_id or default)
+
+
 def set_current_invocation_context(
     context: PlatformInvocationContext | None,
 ) -> Token[PlatformInvocationContext | None]:
@@ -199,7 +288,15 @@ def get_current_session_tags() -> Mapping[str, str]:
     return get_current_session_context().tags
 
 
-def session_invocation_context(snapshot, *, agent_id="", user_id="", session_id="", runner_type=""):
+def session_invocation_context(
+    snapshot,
+    *,
+    agent_id="",
+    user_id="",
+    session_id="",
+    runner_type="",
+    identity: PlatformIdentityContext | Mapping[str, Any] | None = None,
+):
     """Build the narrow context for kernel starts without conversation preprocessing."""
     return PlatformInvocationContext(
         agent_id=agent_id,
@@ -216,4 +313,9 @@ def session_invocation_context(snapshot, *, agent_id="", user_id="", session_id=
         current_attachment_results=[],
         has_current_files=False,
         session=SessionContext.from_payload(snapshot),
+        identity=(
+            identity
+            if isinstance(identity, PlatformIdentityContext)
+            else PlatformIdentityContext.from_payload(identity)
+        ),
     )

ksadk/sandbox/backends/e2b.py

@@ -2,16 +2,19 @@ from __future__ import annotations
 
 import logging
 import os
+import posixpath
 import time
 from typing import Any
 
 from ksadk.sandbox.base import (
+    ReconnectableSandboxCommandHandle,
     SandboxCommandResult,
     SandboxError,
     SandboxInputFile,
     SandboxSession,
     SandboxSpec,
 )
+from ksadk.sandbox.diagnostics import e2b_diagnostic_step
 from ksadk.sandbox.e2b_connection import ExplicitE2BConnection
 
 logger = logging.getLogger(__name__)
@@ -26,6 +29,28 @@ _TRANSIENT_STARTUP_ERROR_NAMES = {
 }
 
 
+class E2BSandboxSessionError(SandboxError):
+    """Carry sandbox lifecycle facts when session initialization fails."""
+
+    def __init__(
+        self,
+        cause: Exception,
+        *,
+        instance_status: str,
+        failure_stage: str,
+        runtime_id: str = "",
+        cleanup_status: str = "not_started",
+        cleanup_error: str | None = None,
+    ) -> None:
+        super().__init__(str(cause))
+        self.cause = cause
+        self.instance_status = instance_status
+        self.failure_stage = failure_stage
+        self.runtime_id = runtime_id
+        self.cleanup_status = cleanup_status
+        self.cleanup_error = cleanup_error
+
+
 def _startup_retry_attempts() -> int:
     raw = os.environ.get("KSADK_SANDBOX_STARTUP_RETRY_ATTEMPTS", "6")
     try:
@@ -46,7 +71,7 @@ def _is_transient_startup_error(exc: Exception) -> bool:
     return type(exc).__name__ in _TRANSIENT_STARTUP_ERROR_NAMES
 
 
-def _with_startup_retry(operation):
+def _with_startup_retry(operation, *, step: str = "startup", runtime_id: str = ""):
     attempts = _startup_retry_attempts()
     delay = _startup_retry_delay()
     last_exc: Exception | None = None
@@ -54,7 +79,18 @@ def _with_startup_retry(operation):
         try:
             return operation()
         except Exception as exc:
-            if not _is_transient_startup_error(exc) or attempt >= attempts - 1:
+            retry = _is_transient_startup_error(exc) and attempt < attempts - 1
+            logger.warning(
+                "E2B_DIAGNOSTIC step=%s runtime_id=%s attempt=%d max_attempts=%d "
+                "error_type=%s retry=%s",
+                step,
+                runtime_id,
+                attempt + 1,
+                attempts,
+                type(exc).__name__,
+                retry,
+            )
+            if not retry:
                 raise
             last_exc = exc
             time.sleep(min(delay * (2**attempt), 1.0))
@@ -63,6 +99,43 @@ def _with_startup_retry(operation):
     raise SandboxError("E2B sandbox startup retry failed unexpectedly")
 
 
+class E2BCommandHandle:
+    """Normalize an E2B background command to the SDK optional contract."""
+
+    def __init__(self, handle: Any):
+        self._handle = handle
+
+    @property
+    def process_id(self) -> int:
+        process_id = int(getattr(self._handle, "pid", 0) or 0)
+        if process_id <= 0:
+            raise SandboxError("E2B command handle did not expose a valid process ID")
+        return process_id
+
+    def wait(self) -> SandboxCommandResult:
+        try:
+            result = self._handle.wait()
+        except Exception as exc:
+            # E2B raises CommandExitException for an ordinary non-zero exit.
+            # Preserve the result contract instead of erasing stdout/stderr.
+            exit_code = getattr(exc, "exit_code", None)
+            if exit_code is None:
+                raise
+            return SandboxCommandResult(
+                stdout=str(getattr(exc, "stdout", "") or ""),
+                stderr=str(getattr(exc, "stderr", "") or ""),
+                exit_code=int(exit_code),
+            )
+        return SandboxCommandResult(
+            stdout=str(getattr(result, "stdout", "") or ""),
+            stderr=str(getattr(result, "stderr", "") or ""),
+            exit_code=getattr(result, "exit_code", None),
+        )
+
+    def kill(self) -> bool:
+        return bool(self._handle.kill())
+
+
 class E2BSandboxSession:
     def __init__(self, sandbox: Any):
         self._sandbox = sandbox
@@ -120,6 +193,65 @@ class E2BSandboxSession:
             exit_code=getattr(result, "exit_code", None),
         )
 
+    def start_command(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> ReconnectableSandboxCommandHandle:
+        kwargs: dict[str, Any] = {"background": True}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        if env is not None:
+            kwargs["envs"] = env
+        if cwd is not None:
+            kwargs["cwd"] = cwd
+        return E2BCommandHandle(self._sandbox.commands.run(command, **kwargs))
+
+    def connect_command(
+        self,
+        process_id: int,
+        *,
+        timeout: int | None = None,
+    ) -> ReconnectableSandboxCommandHandle:
+        if process_id <= 0:
+            raise SandboxError("E2B command reconnect requires a positive process ID")
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return E2BCommandHandle(self._sandbox.commands.connect(process_id, **kwargs))
+
+    def list_files(self, root: str, *, recursive: bool = True) -> list[str]:
+        """List file paths below ``root`` without exposing sibling paths."""
+
+        normalized_root = posixpath.normpath(root)
+        if not normalized_root.startswith("/"):
+            raise SandboxError("E2B artifact root must be an absolute path")
+        entries = self._sandbox.files.list(
+            normalized_root,
+            depth=None if recursive else 1,
+        )
+        files: list[str] = []
+        for entry in entries:
+            entry_path = posixpath.normpath(str(getattr(entry, "path", "") or ""))
+            if not entry_path.startswith("/"):
+                entry_path = posixpath.normpath(posixpath.join(normalized_root, entry_path))
+            entry_type = getattr(getattr(entry, "type", None), "value", "")
+            if getattr(entry, "symlink_target", None) is not None:
+                continue
+            try:
+                in_root = posixpath.commonpath((normalized_root, entry_path)) == normalized_root
+            except ValueError:
+                in_root = False
+            if not in_root or entry_type != "file":
+                continue
+            relative = posixpath.relpath(entry_path, normalized_root)
+            if relative != "." and not relative.startswith("../"):
+                files.append(relative)
+        return sorted(set(files))
+
     def get_host(self, port: int) -> str:
         return str(self._sandbox.get_host(port))
 
@@ -128,6 +260,17 @@ class E2BSandboxSession:
 
 
 class E2BSandboxBackend:
+    def _diagnostic_step(self, step: str, *, runtime_id: str = "", env=None):
+        credentials = (
+            (self.connection.api_key.get_secret_value(),) if self.connection is not None else ()
+        )
+        return e2b_diagnostic_step(
+            step,
+            runtime_id=runtime_id,
+            sensitive_values=credentials,
+            env={**self.spec.env, **(env or {})},
+        )
+
     def __init__(
         self,
         *,
@@ -141,9 +284,22 @@ class E2BSandboxBackend:
         self.sandbox_cls = sandbox_cls
         self.connection = (
             ExplicitE2BConnection.model_validate(connection.model_dump())
-            if connection is not None else None
+            if connection is not None
+            else None
         )
 
+    def _get_sandbox_cls(self) -> Any:
+        sandbox_cls = self.sandbox_cls
+        if sandbox_cls is not None:
+            return sandbox_cls
+        try:
+            from e2b import Sandbox  # type: ignore[import-not-found, import-untyped]
+        except ImportError as exc:
+            raise SandboxError(
+                "e2b>=2.15.3,<2.25.0 is required for KSADK_SANDBOX_BACKEND=e2b"
+            ) from exc
+        return Sandbox
+
     def check_available(self) -> None:
         """Validate local SDK/connection configuration without creating a sandbox."""
         if self.connection is not None:
@@ -179,26 +335,82 @@ class E2BSandboxBackend:
             "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,
-            **connection_options,
-        )
+        try:
+            with self._diagnostic_step("create", env=runtime_env):
+                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,
+                    **connection_options,
+                )
+        except Exception as exc:
+            # The transport can fail after the service accepted the request but before
+            # returning an instance id, so creation cannot be reported as not_created.
+            raise E2BSandboxSessionError(
+                exc,
+                instance_status="unknown",
+                failure_stage="create",
+            ) from exc
         session = self._wrap_sandbox(sandbox)
         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:
+            with self._diagnostic_step(
+                "initialize", runtime_id=session.sandbox_id, env=runtime_env
+            ):
+                self._wait_until_ready(session, runtime_env)
+                with self._diagnostic_step(
+                    "input_files.write", runtime_id=session.sandbox_id, env=runtime_env
+                ):
+                    session.write_files(
+                        [(item.target_path, item.source.read_bytes()) for item in input_files or []]
+                    )
+        except BaseException as exc:
+            cleanup_status = "not_started"
+            cleanup_error = None
             try:
-                session.kill()
+                with self._diagnostic_step(
+                    "initialize.cleanup", runtime_id=session.sandbox_id, env=runtime_env
+                ):
+                    session.kill()
+                cleanup_status = "completed"
             except Exception:
+                cleanup_status = "failed"
+                cleanup_error = "cleanup_failed"
                 logger.warning("E2B sandbox cleanup failed after initialization failure")
-            raise
+            if not isinstance(exc, Exception):
+                raise
+            raise E2BSandboxSessionError(
+                exc,
+                instance_status="created",
+                failure_stage="initialize",
+                runtime_id=session.sandbox_id,
+                cleanup_status=cleanup_status,
+                cleanup_error=cleanup_error,
+            ) from exc
+        return session
+
+    def reconnect_session(self, *, session_locator: str) -> SandboxSession:
+        """Reconnect to an existing E2B sandbox without recreating it."""
+
+        locator = session_locator.strip()
+        if not locator:
+            raise SandboxError("E2B reconnect requires a sandbox ID")
+        # Reconnection does not transfer ownership: failure must not kill an
+        # existing instance that may still be running another process's work.
+        with self._diagnostic_step("reconnect", runtime_id=locator):
+            sandbox_cls = self._get_sandbox_cls()
+            connection_options = (
+                self.connection.sdk_options() if self.connection is not None else {}
+            )
+            sandbox = sandbox_cls.connect(locator, timeout=self.spec.timeout, **connection_options)
+            session = self._wrap_sandbox(sandbox)
+            with self._diagnostic_step("reconnect.ready.command", runtime_id=session.sandbox_id):
+                _with_startup_retry(
+                    lambda: session.run_command("true"),
+                    step="reconnect.ready.command",
+                    runtime_id=session.sandbox_id,
+                )
         return session
 
     def _wrap_sandbox(self, sandbox: Any) -> E2BSandboxSession:
@@ -207,9 +419,20 @@ class E2BSandboxBackend:
     def _wait_until_ready(
         self, session: E2BSandboxSession, env: dict[str, str] | None = None
     ) -> None:
-        _with_startup_retry(lambda: session.run_command("true"))
-        _with_startup_retry(lambda: session.write_file("/tmp/.ksadk-sandbox-ready", ""))
-        self._wait_env_applied(session, env or {})
+        with self._diagnostic_step("ready.command", runtime_id=session.sandbox_id, env=env):
+            _with_startup_retry(
+                lambda: session.run_command("true"),
+                step="ready.command",
+                runtime_id=session.sandbox_id,
+            )
+        with self._diagnostic_step("ready.file", runtime_id=session.sandbox_id, env=env):
+            _with_startup_retry(
+                lambda: session.write_file("/tmp/.ksadk-sandbox-ready", ""),
+                step="ready.file",
+                runtime_id=session.sandbox_id,
+            )
+        with self._diagnostic_step("ready.env", runtime_id=session.sandbox_id, env=env):
+            self._wait_env_applied(session, env or {})
 
     def _wait_env_applied(self, session: E2BSandboxSession, env: dict[str, str]) -> None:
         # create 返回后 envd 异步应用 envVars, 实测存在秒级延迟;
@@ -228,9 +451,8 @@ class E2BSandboxBackend:
         # 不 raise: 模板可能预置同名空值覆盖 create 注入 (envd 合并优先级问题),
         # 此时调用方仍可通过 run_command(env=...) 的 per-command 注入拿到正确值。
         logger.warning(
-            "E2B sandbox env %s not applied after %d attempts (expected %r); "
+            "E2B sandbox env %s not applied after %d attempts; "
             "template may predefine an empty override",
             key,
             attempts,
-            expected,
         )

ksadk/sandbox/backends/local_process.py

@@ -1,17 +1,16 @@
 from __future__ import annotations
 
 import os
-import signal
-import subprocess
 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 ""
+from ksadk.sandbox.local_controls import (
+    LocalControlSettings,
+    build_script_environment,
+    check_command,
+    resource_limit_reason,
+    run_bounded_process,
+)
 
 
 class LocalProcessSandboxSession:
@@ -22,6 +21,7 @@ class LocalProcessSandboxSession:
         self._workspace_root = workspace_root.expanduser().resolve()
         self._workspace_root.mkdir(parents=True, exist_ok=True)
         self._backend_name = backend_name
+        self._controls = LocalControlSettings.from_trusted_host_env()
 
     @property
     def sandbox_id(self) -> str:
@@ -59,35 +59,56 @@ class LocalProcessSandboxSession:
             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 {})
+        finding = check_command(
+            command,
+            cwd=resolved_cwd,
+            allowed_roots=(self._workspace_root,),
+        )
+        if finding is not None:
+            return SandboxCommandResult(
+                stderr=f"blocked by local-process policy: {finding.reason()}", exit_code=126
+            )
+        source_env = dict(os.environ)
+        source_env.update(env or {})
+        process_env = build_script_environment(source_env, settings=self._controls)
         try:
-            process = subprocess.Popen(
-                command,
-                shell=True,
+            effective_timeout = self._controls.wall_seconds
+            if timeout is not None:
+                effective_timeout = min(timeout, effective_timeout)
+            executed = run_bounded_process(
+                ["/bin/sh", "-c", command],
                 cwd=resolved_cwd,
                 env=process_env,
-                text=True,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
+                timeout=effective_timeout,
+                settings=self._controls,
                 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()
+        except (OSError, ValueError) as exc:
             return SandboxCommandResult(
-                stdout=_coerce_output(stdout or exc.stdout),
-                stderr=_coerce_output(stderr or exc.stderr) + "\ncommand timed out",
-                exit_code=124,
+                stderr=f"local-process controls failed: {exc}", exit_code=125
             )
+        diagnostics: list[str] = []
+        if executed.controls.get("status") == "failed":
+            diagnostics.append("resource limits were not applied")
+        if executed.output_limit_exceeded:
+            diagnostics.append("command output limit exceeded")
+        if executed.timed_out:
+            diagnostics.append("command timed out")
+        if limit := resource_limit_reason(executed.exit_code):
+            diagnostics.append(f"command exceeded {limit} resource limit")
+        if executed.cleanup_error:
+            diagnostics.append("command process-group cleanup failed")
+        stderr = executed.stderr
+        if diagnostics:
+            stderr = (stderr.rstrip() + "\n" if stderr else "") + "; ".join(diagnostics)
+        exit_code = executed.exit_code
+        if executed.timed_out:
+            exit_code = 124
+        elif executed.output_limit_exceeded:
+            exit_code = 122
+        elif executed.controls.get("status") == "failed" or executed.cleanup_error:
+            exit_code = 125
+        return SandboxCommandResult(stdout=executed.stdout, stderr=stderr, exit_code=exit_code)
 
     def get_host(self, port: int) -> str:
         return f"http://127.0.0.1:{int(port)}"
@@ -104,24 +125,27 @@ class LocalProcessSandboxSession:
         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")
+        self._reject_symlink_components(candidate)
         return resolved
 
     def _resolve_workspace_path(self, path: str) -> Path:
         raw = str(path or "").strip().lstrip("/") or "."
+        self._reject_symlink_components(self._workspace_root / raw)
         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
+    def _reject_symlink_components(self, path: Path) -> None:
+        try:
+            relative = path.absolute().relative_to(self._workspace_root)
+        except ValueError:
+            raise ValueError("path must stay inside the sandbox workspace") from None
+        current = self._workspace_root
+        for part in relative.parts:
+            current = current / part
+            if current.is_symlink():
+                raise ValueError("sandbox file API does not follow symbolic links")
 
 
 class LocalProcessSandboxBackend: