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

ksadk/runtime/runner_adapter.py

@@ -54,6 +54,7 @@ from ksadk.runtime.adapter import (
 )
 from ksadk.runtime.preprocessing import PreparedRuntimeStart, prepare_runtime_start
 from ksadk.runtime.runner_loading import ensure_runner_loaded
+from ksadk.runtime_context import session_invocation_context
 
 logger = logging.getLogger(__name__)
 
@@ -138,6 +139,10 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
 
     # ---- 框架钩子(子类按需 override) ----
 
+    def _requires_stable_stream_context(self) -> bool:
+        """Whether one Task must own the runner generator for its lifetime."""
+        return self._runtime_type == "adk"
+
     def capabilities(self) -> RuntimeCapabilityMatrix:
         """诚实矩阵:cancel 经 asyncio 任务打断(emulated,过 conformance);
         resume/checkpoint 依赖 runner 声明的原生 checkpoint;attach/durable_restore
@@ -170,8 +175,12 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             submit_interaction=_unavailable("runtime_no_live_interaction_channel"),
             attach=(
                 RuntimeCapability(supported=True, mode="native")
-                if attach_seam
-                else _unavailable("runner_no_durable_attach_seam")
+                if durable_supported
+                else _unavailable(
+                    "runner_no_durable_attach_seam"
+                    if not attach_seam
+                    else "attach_requires_cross_process_checkpoint"
+                )
             ),
             steer=_unavailable("runtime_no_native_steer"),
             inject=_unavailable("runtime_no_native_inject"),
@@ -185,6 +194,11 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 if durable_supported
                 else _unavailable("durable_restore_requires_cross_process_checkpoint")
             ),
+            # A generic Runner cannot claim interaction delivery merely from a
+            # checkpoint capability.  ADK is forward-only and only the
+            # LangGraph specialization below binds a checkpoint to the
+            # original interrupt identity.
+            interaction_mode="unavailable",
         )
 
     async def durable_restore(self, handle: RunHandle) -> RunHandle:
@@ -267,6 +281,15 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         self._active_runs[run_id] = _ActiveRun(invocation_id=run_id, session_id=request.session_id)
         # 暂存 start 输入,供 stream() 使用。
         self._active_runs[run_id].__dict__["_start_request"] = request
+        snapshot = request.metadata.get("session_context")
+        if snapshot is not None:
+            self._active_runs[run_id].__dict__["_tag_context"] = session_invocation_context(
+                snapshot,
+                agent_id=request.agent_id or "",
+                user_id=request.user_id,
+                session_id=request.session_id,
+                runner_type=self._runtime_type,
+            )
         if prepared_start is not None:
             self._active_runs[run_id].__dict__["_prepared_start"] = prepared_start
         return handle
@@ -302,6 +325,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 f"runner for {self._runtime_type!r} has no durable "
                 "attach_runtime_handle capability"
             )
+        ensure_runner_loaded(self._runner, runtime_type=self._runtime_type)
         restored = attach(handle)
         if inspect.isawaitable(restored):
             restored = await restored
@@ -360,11 +384,14 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         self._require_native_checkpoint_capability()
         self._known_runs.add(handle.run_id)
         prepared_start: PreparedRuntimeStart | None = None
+        resume_invocation_id = handle.run_id
         raw_start_request = handle.native_ref.pop(RESUME_START_REQUEST_NATIVE_KEY, None)
         if isinstance(raw_start_request, Mapping):
-            prepared_start = await prepare_runtime_start(
-                StartRequest.model_validate(raw_start_request), self._runner
+            resume_request = StartRequest.model_validate(raw_start_request)
+            resume_invocation_id = str(
+                resume_request.metadata.get("invocation_id") or handle.run_id
             )
+            prepared_start = await prepare_runtime_start(resume_request, self._runner)
         # _resume_native 返回的 runner_input 覆盖存到 run 上,下一次 stream() 经
         # _build_runner_input 消费,以框架原生方式真驱动恢复。
         override = await self._resume_native(handle, target, payload)
@@ -387,7 +414,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 return handle
             if resume_key in self._consumed_resumes:
                 self._active_runs[handle.run_id] = _ActiveRun(
-                    invocation_id=handle.run_id,
+                    invocation_id=resume_invocation_id,
                     session_id=handle.session_id,
                     resume_key=resume_key,
                     resume_fingerprint=resume_fingerprint,
@@ -404,11 +431,19 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             raise ValueError(f"run {handle.run_id!r} already has an active or pending resume")
 
         run = _ActiveRun(
-            invocation_id=handle.run_id,
+            invocation_id=resume_invocation_id,
             session_id=handle.session_id,
             resume_key=resume_key,
             resume_fingerprint=resume_fingerprint,
         )
+        if payload is not None and payload.session_context is not None:
+            run.__dict__["_tag_context"] = session_invocation_context(
+                payload.session_context,
+                agent_id=str(handle.native_ref.get("agent_id") or ""),
+                user_id=str(handle.native_ref.get("user_id") or ""),
+                session_id=handle.session_id,
+                runner_type=self._runtime_type,
+            )
         if prepared_start is not None:
             run.__dict__["_prepared_start"] = prepared_start
         if override:
@@ -504,23 +539,30 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         if run is None:
             run = _ActiveRun(invocation_id=handle.run_id, session_id=handle.session_id)
             self._active_runs[handle.run_id] = run
+        event_handle = (
+            handle
+            if run.invocation_id == handle.run_id
+            else handle.model_copy(update={"run_id": run.invocation_id})
+        )
 
         # 消费 pending cancel:start 时若已记 pending,立即中断该 turn。
         if handle.run_id in self._pending_cancels:
             self._pending_cancels.discard(handle.run_id)
-            yield self._make_run_canceled(handle, reason=CancelResult.PENDING_CANCEL_RECORDED.value)
+            yield self._make_run_canceled(
+                event_handle, reason=CancelResult.PENDING_CANCEL_RECORDED.value
+            )
             return
 
         if run.skip_runner:
             run.done = True
             self._active_runs.pop(handle.run_id, None)
-            yield self._make_run_completed(handle)
+            yield self._make_run_completed(event_handle)
             return
 
         if run.resume_key is not None:
             self._consumed_resumes.add(run.resume_key)
 
-        yield self._make_run_started(handle)
+        yield self._make_run_started(event_handle)
 
         request = run.__dict__.get("_start_request")
         runner_input = self._build_runner_input(handle, request)
@@ -528,7 +570,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         terminal_event_seen = False
         approval_interrupted = False
         try:
-            gen = self._map_runner_stream(handle, runner_input)
+            gen = self._map_runner_stream(event_handle, runner_input, active_run=run)
             run.stream = gen
             async for event in gen:
                 yield event
@@ -555,18 +597,38 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
 
             if run.interrupt_event.is_set() and not terminal_event_seen:
                 yield self._make_run_canceled(
-                    handle, reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value
+                    event_handle, reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value
                 )
             elif approval_interrupted and not terminal_event_seen:
-                yield self._make_run_interrupted(handle, reason="input_required")
+                yield self._make_run_interrupted(event_handle, reason="input_required")
             elif not terminal_event_seen:
-                yield self._make_run_completed(handle, run=run, metrics=run.completion_metrics)
+                yield self._make_run_completed(
+                    event_handle, run=run, metrics=run.completion_metrics
+                )
         finally:
             run.stream = None
             run.done = True
             self._active_runs.pop(handle.run_id, None)
 
     def _build_runner_input(self, handle: RunHandle, request: Optional[StartRequest]) -> dict:
+        result = self._build_base_runner_input(handle, request)
+        run = self._active_runs.get(handle.run_id)
+        context = run.__dict__.get("_tag_context") if run is not None else None
+        if context is not None:
+            existing_context = result.get("platform_context")
+            result["platform_context"] = (
+                {**existing_context, "session": context.session.to_payload()}
+                if isinstance(existing_context, dict)
+                else context.to_payload()
+            )
+            result["metadata"] = {
+                key: value
+                for key, value in dict(result.get("metadata") or {}).items()
+                if key != "session_context"
+            }
+        return result
+
+    def _build_base_runner_input(self, handle: RunHandle, request: Optional[StartRequest]) -> dict:
         # resume 覆盖优先:_resume_native 注入的 checkpoint_resume + framework_ref
         # 直接作为 runner 输入,驱动框架原生恢复。
         run = self._active_runs.get(handle.run_id)
@@ -583,7 +645,9 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 {
                     "input": override.get("input"),
                     "session_id": handle.session_id,
-                    "invocation_id": handle.run_id,
+                    "invocation_id": str(
+                        merged.get("invocation_id") or handle.run_id
+                    ),
                     "metadata": {
                         **(dict(base_metadata) if isinstance(base_metadata, Mapping) else {}),
                         **dict(override.get("metadata") or {}),

ksadk/runtime_context.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass, field
-from typing import Any, Iterator
+from typing import Any, Iterator, Mapping
+
+from ksadk.session_context import SessionContext
 
 
 @dataclass
@@ -30,9 +32,10 @@ class PlatformInvocationContext:
     # Request-scoped runtime control. It is intentionally separate from
     # public caller metadata so built-in tools can enforce it consistently.
     tool_approval_mode: str = ""
+    session: SessionContext = field(default_factory=SessionContext)
 
     def to_payload(self) -> dict[str, Any]:
-        return {
+        payload = {
             "agent_id": self.agent_id,
             "user_id": self.user_id,
             "account_id": self.account_id,
@@ -52,6 +55,10 @@ class PlatformInvocationContext:
             "model_options": dict(self.model_options or {}),
         }
 
+        if self.session.tags or self.session.revision:
+            payload["session"] = self.session.to_payload()
+        return payload
+
 
 @dataclass
 class ToolExecutionContext:
@@ -179,3 +186,34 @@ def tool_execution_scope(
         yield context
     finally:
         reset_current_tool_execution_context(token)
+
+
+def get_current_session_context() -> SessionContext:
+    """Read the current immutable snapshot in LangChain, LangGraph or ADK code."""
+    context = get_current_invocation_context()
+    return context.session if context is not None else SessionContext()
+
+
+def get_current_session_tags() -> Mapping[str, str]:
+    """Return read-only business labels; these are not authorization claims."""
+    return get_current_session_context().tags
+
+
+def session_invocation_context(snapshot, *, agent_id="", user_id="", session_id="", runner_type=""):
+    """Build the narrow context for kernel starts without conversation preprocessing."""
+    return PlatformInvocationContext(
+        agent_id=agent_id,
+        user_id=user_id,
+        session_id=session_id,
+        runner_type=runner_type,
+        history=[],
+        input_content=[],
+        input_messages=[],
+        input_parts=[],
+        attachments=[],
+        attachment_results=[],
+        current_attachments=[],
+        current_attachment_results=[],
+        has_current_files=False,
+        session=SessionContext.from_payload(snapshot),
+    )

ksadk/sandbox/__init__.py

@@ -12,7 +12,7 @@ from ksadk.sandbox.base import (
     SandboxSpec,
     SandboxType,
 )
-from ksadk.sandbox.factory import create_sandbox_backend, sandbox_spec_from_env
+from ksadk.sandbox.factory import create_sandbox_backend, sandbox_spec_from_env, setup_sandbox_api_url_if_needed
 
 __all__ = [
     "E2BSandboxBackend",
@@ -28,4 +28,5 @@ __all__ = [
     "SandboxType",
     "create_sandbox_backend",
     "sandbox_spec_from_env",
+    "setup_sandbox_api_url_if_needed",
 ]

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/sandbox/factory.py

@@ -16,11 +16,83 @@ def bool_env(name: str, default: bool = True) -> bool:
     return raw.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def _resolve_sandbox_api_url() -> str:
+    """Probe sandbox control-plane URL at runtime (in-Pod).
+
+    agentengine-server injects public E2B_API_URL on the management cluster.
+    public_only compute pods can reach the public address directly; private_only
+    pods have no public egress. Strategy: try the original (public) URL first;
+    if reachable keep it, otherwise fall back to the 198 public-service-net
+    internal address. Mirrors KSPMAS get_kspmas_api_base(): probe runs in-Pod.
+    """
+    raw = (os.environ.get("E2B_API_URL") or "").strip()
+    if not raw:
+        return raw
+
+    from urllib.parse import urlsplit, urlunsplit
+
+    parsed = urlsplit(raw)
+    host = (parsed.hostname or "").lower()
+    if host.endswith(".sdns.ksyun.com"):
+        return raw
+    if not host.endswith(".sandbox.ksyun.com"):
+        return raw
+
+    parts = host.split(".")
+    region = ""
+    if len(parts) >= 4 and parts[0] == "mgr":
+        region = parts[1]
+    elif len(parts) >= 4:
+        region = parts[1] if parts[1] != "sandbox" else ""
+    if not region:
+        return raw
+
+    import socket
+
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+
+    # 1) Try the original (public) URL first; reachable => keep it.
+    try:
+        s = socket.socket()
+        s.settimeout(1.5)
+        s.connect((host, port))
+        s.close()
+        return raw
+    except OSError:
+        pass
+
+    # 2) Public unreachable (e.g. private_only node) => fall back to internal.
+    internal_host = f"sandbox.{region}.sandbox.sdns.ksyun.com"
+    try:
+        s = socket.socket()
+        s.settimeout(1.5)
+        s.connect((internal_host, port))
+        s.close()
+    except OSError:
+        return raw
+
+    internal_url = urlunsplit((parsed.scheme or "https", internal_host, parsed.path, parsed.query, ""))
+    return internal_url
+
+
+def setup_sandbox_api_url_if_needed() -> None:
+    """Override E2B_API_URL to internal address before creating E2B backend.
+
+    Only runs in managed runtime (AGENT_RUNTIME_ID / K8S); local dev unaffected.
+    """
+    if not os.environ.get("AGENT_RUNTIME_ID") and not os.environ.get("KUBERNETES_SERVICE_HOST"):
+        return
+    resolved = _resolve_sandbox_api_url()
+    if resolved != (os.environ.get("E2B_API_URL") or ""):
+        os.environ["E2B_API_URL"] = resolved
+
+
 def create_sandbox_backend(
     backend: str | None = None,
     *,
     sandbox_cls: Any | None = None,
 ) -> SandboxBackend:
+    setup_sandbox_api_url_if_needed()
     resolved = (backend or os.environ.get("KSADK_SANDBOX_BACKEND") or "e2b").strip().lower()
     if resolved in {"local", "local_process"}:
         return LocalProcessSandboxBackend(

ksadk/scheduler/__init__.py

@@ -0,0 +1,18 @@
+"""Local Scheduler Lite contracts and deterministic calendar calculations."""
+
+from ksadk.scheduler.calendar import next_schedule_time
+from ksadk.scheduler.contracts import ScheduledTask, ScheduleOccurrence, ScheduleSpec
+from ksadk.scheduler.dispatcher import AgentControlSchedulerDispatcher
+from ksadk.scheduler.engine import SchedulerDispatchError, SchedulerEngine
+from ksadk.scheduler.sqlite_store import SchedulerSQLiteStore
+
+__all__ = [
+    "ScheduleOccurrence",
+    "ScheduledTask",
+    "ScheduleSpec",
+    "AgentControlSchedulerDispatcher",
+    "SchedulerDispatchError",
+    "SchedulerEngine",
+    "SchedulerSQLiteStore",
+    "next_schedule_time",
+]