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

ksadk/runtime/usage.py

@@ -0,0 +1,33 @@
+"""Canonical runtime usage projection helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+def canonical_usage_payload(
+    usage: Mapping[str, Any], *, runtime_type: str
+) -> dict[str, Any]:
+    """Normalize provider usage, including nested cache/reasoning details."""
+    input_details = usage.get("input_token_details")
+    output_details = usage.get("output_token_details")
+    cached = (
+        input_details.get("cached")
+        if isinstance(input_details, Mapping)
+        else usage.get("cached_tokens")
+    )
+    reasoning = (
+        output_details.get("reasoning")
+        if isinstance(output_details, Mapping)
+        else usage.get("reasoning_tokens")
+    )
+    input_tokens = int(usage.get("input_tokens") or 0)
+    output_tokens = int(usage.get("output_tokens") or 0)
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "total_tokens": int(usage.get("total_tokens") or input_tokens + output_tokens),
+        "cached_tokens": int(cached or 0),
+        "reasoning_tokens": int(reasoning or 0),
+        "source": str(usage.get("source") or runtime_type),
+    }

ksadk/sandbox/backends/e2b.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import os
 import time
 from typing import Any
@@ -12,10 +13,15 @@ from ksadk.sandbox.base import (
     SandboxSpec,
 )
 
+logger = logging.getLogger(__name__)
+
 _TRANSIENT_STARTUP_ERROR_NAMES = {
     "NotFoundException",
     "FileNotFoundException",
     "SandboxNotFoundException",
+    # create 快速返回后 envd RPC 通道可能尚未就绪 (connection refused / unavailable),
+    # SDK 将其包装为 TimeoutException 抛出, 需按瞬时启动错误重试。
+    "TimeoutException",
 }
 
 
@@ -148,7 +154,7 @@ class E2BSandboxBackend:
             allow_internet_access=self.spec.allow_internet_access,
         )
         session = self._wrap_sandbox(sandbox)
-        self._wait_until_ready(session)
+        self._wait_until_ready(session, runtime_env)
         session.write_files(
             [(item.target_path, item.source.read_bytes()) for item in input_files or []]
         )
@@ -157,6 +163,33 @@ class E2BSandboxBackend:
     def _wrap_sandbox(self, sandbox: Any) -> E2BSandboxSession:
         return E2BSandboxSession(sandbox)
 
-    def _wait_until_ready(self, session: E2BSandboxSession) -> None:
+    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 {})
+
+    def _wait_env_applied(self, session: E2BSandboxSession, env: dict[str, str]) -> None:
+        # create 返回后 envd 异步应用 envVars, 实测存在秒级延迟;
+        # 轮询一个非空变量直到值就位, 避免紧随其后的 agent 进程读到缺失的环境。
+        probe = next(((k, v) for k, v in env.items() if v), None)
+        if probe is None:
+            return
+        key, expected = probe
+        attempts = _startup_retry_attempts()
+        delay = _startup_retry_delay()
+        for attempt in range(attempts):
+            result = session.run_command(f"printenv {key} || true")
+            if result.stdout.strip() == expected:
+                return
+            time.sleep(min(delay * (2**attempt), 1.0))
+        # 不 raise: 模板可能预置同名空值覆盖 create 注入 (envd 合并优先级问题),
+        # 此时调用方仍可通过 run_command(env=...) 的 per-command 注入拿到正确值。
+        logger.warning(
+            "E2B sandbox env %s not applied after %d attempts (expected %r); "
+            "template may predefine an empty override",
+            key,
+            attempts,
+            expected,
+        )

ksadk/server/composition.py

@@ -13,6 +13,14 @@ def configure_runtime_app(app: FastAPI, state: RuntimeAppState, groups: set[str]
     _configure_route_dependencies()
     _register_integrated_routers(app, state)
 
+    # Agent Kernel canonical ingress（/agent-kernel/v1/*）必须先于 route group
+    # 注册：group 内的静态 UI catch-all(GET /{path}) 会吞掉所有未匹配 GET，
+    # 后注册的 kernel GET 路由（health / SubscribeSessionEvents）将被遮蔽 404。
+    # 灰度开关关闭时 bootstrap 返回 None、路由统一回 503，不影响旧路径。
+    from ksadk.kernel import ingress as _kernel_ingress
+
+    app.include_router(_kernel_ingress.agent_kernel_router())
+
     ordered = sorted(group for group in groups if group != "health_meta")
     if "health_meta" in groups:
         ordered.append("health_meta")

ksadk/server/factory.py

@@ -194,6 +194,7 @@ class RuntimeAppConfig:
         agui: Optional[Any] = None,
         runtime_executor: RuntimeExecutor | None = None,
         launch_context: RuntimeLaunchContext | None = None,
+        kernel_adapter_provider: Callable[[], RuntimeAdapter] | None = None,
         session_service_provider: Callable[[], Any] | None = None,
         session_backend_provider: Callable[[], dict[str, Any]] | None = None,
     ) -> None:
@@ -208,6 +209,9 @@ class RuntimeAppConfig:
         self.agui = agui
         self.runtime_executor = runtime_executor
         self.launch_context = launch_context
+        # 特殊 runtime 可显式提供 worker/recovery 的 adapter；常规部署从
+        # runtime_executor 的同一 registry 派生，见 _kernel_adapter_provider。
+        self.kernel_adapter_provider = kernel_adapter_provider
         self.session_service_provider = session_service_provider
         self.session_backend_provider = session_backend_provider
 
@@ -353,6 +357,40 @@ def create_runtime_app(
 
     @asynccontextmanager
     async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+        # 生产 kernel 的 composition root 必须启动 worker/lease/recovery，
+        # 不能只注册一个可接收命令、却永远不会消费的 ingress kernel。
+        from ksadk.kernel import ingress as _kernel_ingress
+        from ksadk.kernel.bootstrap import (
+            bootstrap_agent_kernel_runtime_from_env,
+            clear_agent_kernel_runtime,
+        )
+        from ksadk.runtime.factory import kernel_start_request_defaults
+
+        adapter_provider = _kernel_adapter_provider(config)
+        request_defaults = (
+            kernel_start_request_defaults(config.launch_context)
+            if config.launch_context is not None
+            else {}
+        )
+        kernel_runtime = await bootstrap_agent_kernel_runtime_from_env(
+            adapter_provider=adapter_provider,
+            runtime_executor=config.runtime_executor,
+            launch_context=config.launch_context,
+            start_request_defaults=request_defaults,
+            session_service=state.resolve_session_service(),
+        )
+        app.state.agent_kernel_runtime = kernel_runtime
+        if kernel_runtime is not None:
+            # Kernel canonical events are the replay authority for the normal
+            # Session APIs as well.  In memory/ephemeral mode bootstrap reuses
+            # the app-owned service above; in PostgreSQL mode it owns the
+            # durable service and the HTTP routes must adopt that exact one.
+            # Keeping two services made foreground SSE look correct while a
+            # later ListSessionEvents call returned an empty history forever.
+            kernel_session_service = kernel_runtime.config.session_service
+            if kernel_session_service is None:  # pragma: no cover - defensive
+                raise RuntimeError("agent kernel runtime has no Session service")
+            state.session_service = kernel_session_service
         try:
             if state.a2a_bootstrap is not None:
                 await state.a2a_bootstrap.start()
@@ -360,6 +398,10 @@ def create_runtime_app(
         finally:
             if state.a2a_bootstrap is not None:
                 await state.a2a_bootstrap.stop()
+            if kernel_runtime is not None:
+                await kernel_runtime.close()
+            clear_agent_kernel_runtime()
+            _kernel_ingress.clear_agent_kernel()
             await shutdown_runtime_resources(state)
 
     app = FastAPI(
@@ -488,6 +530,25 @@ def create_runtime_app(
     return app
 
 
+def _kernel_adapter_provider(
+    config: RuntimeAppConfig,
+) -> Callable[[], RuntimeAdapter] | None:
+    """Return the adapter source used by the durable kernel runtime.
+
+    Hosted startup deliberately fails when neither a provider nor a Runtime
+    launch context is available. It must never construct an unrelated local
+    adapter merely to make the ingress look healthy.
+    """
+
+    if config.kernel_adapter_provider is not None:
+        return config.kernel_adapter_provider
+    if config.a2a_runtime_adapter is not None:
+        return lambda: config.a2a_runtime_adapter
+    if config.runtime_executor is not None and config.launch_context is not None:
+        return lambda: config.runtime_executor.create_adapter(config.launch_context)
+    return None
+
+
 def _wire_a2a_if_enabled(app: FastAPI, state: RuntimeAppState, config: RuntimeAppConfig) -> None:
     """Mount A2A with an explicitly injected RuntimeAdapter.
 
@@ -569,15 +630,17 @@ def _wire_agui_if_enabled(app: FastAPI, state: RuntimeAppState, config: RuntimeA
             self._service = service
             self._store = RuntimeEventStore(service)
 
-        async def append_one(self, event: Any) -> Any:
-            existing = await self._service.get_session(event.session_id)
+        async def append_one(self, session_id: str, event: Any) -> Any:
+            existing = await self._service.get_session(session_id)
             if existing is None:
+                metadata = getattr(event, "source", None)
+                meta = metadata.metadata if metadata is not None else {}
                 await self._service.create_session(
-                    event.agent_id,
-                    event.user_id,
-                    event.session_id,
+                    str(meta.get("agent_id") or "agent"),
+                    str(meta.get("user_id") or "user"),
+                    session_id,
                 )
-            return await self._store.append_one(event)
+            return await self._store.append_one(session_id, event)
 
         async def reserve_once(self, event: Any) -> Any:
             existing = await self._service.get_session(event.session_id)

ksadk/server/routes/kernel_ingress.py

@@ -0,0 +1,258 @@
+# -*- coding: utf-8 -*-
+"""RunAgent / Responses 入口的 kernel 路径（Phase 1 Task 8 Step 3-5）。
+
+只在 ``kernel_route_active()`` 时启用（灰度 opt-in）；旧 HTTP 行为保持兼容：
+- accepted -> 202、duplicate -> 200、rejected -> 400、unsupported -> 409、
+  queue_full -> 429、persistence_uncertain -> 503（RECEIPT_HTTP_STATUS）。
+- 旧响应 shape 不变；非流式在 receipt accepted 后才开始消费 stream。
+- SSE 的 reconnect cursor 源自同一 Session seq（SessionEventSubscription）。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from ksadk.kernel import ingress
+from ksadk.kernel.contracts import AgentControlReceipt
+
+logger = logging.getLogger(__name__)
+
+
+def _envelope_text(payload: dict[str, Any]) -> str:
+    return str(payload.get("delta") or payload.get("text") or "")
+
+
+async def _kernel_submit(
+    *,
+    mapper: str,
+    session_id: str,
+    idempotency_key: str,
+    content: Any,
+    correlation_ref: str | None,
+    source_kind: str,
+    runtime_options: dict[str, Any] | None = None,
+) -> tuple[AgentControlReceipt, ingress.TrustedRuntimeContext]:
+    trusted = ingress.trusted_context(
+        source_kind=source_kind,
+        source_ref=idempotency_key,
+        session_id=session_id,
+        # A foreground compatibility request admits a mutation and then reads
+        # the same session's canonical stream.  It remains session-bound, but
+        # needs explicit authority for both operations.
+        operations=("enqueue", "subscribe_events"),
+    )
+    correlation_kwarg = {
+        "map_run_request": "invocation_id",
+        "map_responses_request": "response_id",
+        "map_agui_request": "run_id",
+        "map_a2a_task": "task_id",
+        "map_studio_request": "run_id",
+    }[mapper]
+    command = getattr(ingress, mapper)(
+        trusted=trusted,
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        content=content,
+        **({correlation_kwarg: correlation_ref} if correlation_ref else {}),
+        **({"runtime_options": runtime_options} if runtime_options else {}),
+    )
+    receipt = await ingress.submit_command(command, permit=trusted.permit)
+    return receipt, trusted
+
+
+def _kernel_error_response(receipt: AgentControlReceipt) -> JSONResponse:
+    return JSONResponse(
+        status_code=ingress.receipt_http_status(receipt),
+        content={
+            "error": ingress.receipt_error_payload(receipt),
+        },
+        headers=ingress.receipt_response_headers(receipt),
+    )
+
+
+def _sse_chunk(payload: dict[str, Any], *, event: str | None, seq: int) -> str:
+    prefix = f"event: {event}\n" if event else ""
+    return f"id: {seq}\n{prefix}data: {json.dumps(payload, ensure_ascii=False)}\n\n"
+
+
+def kernel_stream_response(
+    *,
+    receipt: AgentControlReceipt,
+    trusted: ingress.TrustedRuntimeContext,
+    session_id: str,
+) -> StreamingResponse:
+    """统一 cursor：从 receipt.accepted_seq 之后读 Session 事件。"""
+
+    after_seq = int(receipt.accepted_seq or 0)
+
+    async def generator():
+        async for seq, projected in ingress.subscribe_projected(
+            session_id,
+            trusted=trusted,
+            after_seq=after_seq,
+            projector=_new_responses_projector(),
+        ):
+            if projected is None:
+                continue
+            kind, payload = projected
+            yield _sse_chunk(payload, event=kind, seq=seq)
+            if kind == "response.output_item.done" and (
+                (payload.get("item") or {}).get("type") == "mcp_approval_request"
+            ):
+                yield _sse_chunk(
+                    {"type": "response.incomplete"},
+                    event="response.incomplete",
+                    seq=seq,
+                )
+                return
+            # A foreground response stream is scoped to one admitted run.
+            # SessionEventStore subscriptions are deliberately long-lived for
+            # replay/SSE clients, so do not leave this HTTP response open after
+            # the terminal fact has been projected.
+            if kind in {"response.completed", "response.failed", "response.canceled"}:
+                return
+
+    return StreamingResponse(generator(), media_type="text/event-stream")
+
+
+def _responses_projector(envelope: Any) -> tuple[str, dict[str, Any]] | None:
+    """Session envelope -> 旧 Responses SSE shape（cursor 仍用 envelope.seq）。"""
+
+    payload = envelope.payload or {}
+    event_type = envelope.event_type
+    if event_type == "interaction.requested":
+        request = payload.get("request") or {}
+        presentation = request.get("presentation") or {}
+        description = presentation.get("description") or ""
+        try:
+            visible = json.loads(description) if description else {}
+        except (TypeError, json.JSONDecodeError):
+            visible = {}
+        arguments = visible.get("arguments") if isinstance(visible, dict) else {}
+        return "response.output_item.done", {
+            "type": "response.output_item.done",
+            "item": {
+                "id": str(payload.get("interaction_id") or ""),
+                "type": "mcp_approval_request",
+                "name": str(presentation.get("title") or payload.get("kind") or "approval"),
+                "arguments": json.dumps(arguments or {}, ensure_ascii=False),
+            },
+        }
+    if event_type == "run.completed":
+        text = str(payload.get("output_text") or "")
+        return "response.completed", {
+            "type": "response.completed",
+            "output_text": text,
+            "delta": text,
+        }
+    if event_type == "run.failed":
+        return "response.failed", {
+            "type": "response.failed",
+            "error": payload.get("error") or {"code": "runtime_failed"},
+        }
+    if event_type in {"run.canceled", "run.interrupted"}:
+        return "response.canceled", {
+            "type": "response.canceled",
+            "reason": payload.get("reason") or event_type,
+        }
+    text = _envelope_text(payload)
+    if text:
+        return "response.output_text.delta", {
+            "type": "response.output_text.delta",
+            "delta": text,
+        }
+    return None
+
+
+def _new_responses_projector():
+    """Create a session-scoped canonical RuntimeEvent -> Responses projector.
+
+    ``run.completed.output_refs`` deliberately point at canonical items instead
+    of duplicating answer text.  A projector therefore keeps only the small
+    item snapshot needed for this one HTTP/SSE response and resolves those
+    refs when the terminal fact arrives.
+    """
+
+    item_text: dict[str, str] = {}
+
+    def project(envelope: Any) -> tuple[str, dict[str, Any]] | None:
+        payload = envelope.payload or {}
+        event_type = envelope.event_type
+        if event_type == "item.updated":
+            item_id = str(payload.get("item_id") or "")
+            update = payload.get("update") or {}
+            text = str(update.get("text") or "")
+            if item_id and text:
+                item_text[item_id] = (
+                    text if payload.get("op") == "replace" else item_text.get(item_id, "") + text
+                )
+            return None
+        if event_type == "item.completed":
+            item_id = str(payload.get("item_id") or "")
+            parts = (payload.get("snapshot") or {}).get("parts") or []
+            if item_id and isinstance(parts, list):
+                item_text[item_id] = "".join(
+                    str(part.get("text") or "") for part in parts if isinstance(part, dict)
+                )
+            return None
+        if event_type == "run.completed":
+            refs = payload.get("output_refs") or []
+            output = "".join(
+                item_text.get(str(ref.get("item_id") or ""), "")
+                for ref in refs
+                if isinstance(ref, dict)
+            )
+            projected_payload = dict(payload)
+            projected_payload["output_text"] = output or str(payload.get("output_text") or "")
+            return _responses_projector(
+                type("Envelope", (), {"event_type": event_type, "payload": projected_payload})()
+            )
+        return _responses_projector(envelope)
+
+    return project
+
+
+async def kernel_conversation_turn(
+    *,
+    receipt: AgentControlReceipt,
+    trusted: ingress.TrustedRuntimeContext,
+    session_id: str,
+    build_payload,
+):
+    """非流式 kernel 路径：receipt accepted 后订阅聚合 output_text。"""
+
+    if receipt.status not in ("accepted", "duplicate"):
+        return _kernel_error_response(receipt)
+    output_text = ""
+    async for _seq, projected in ingress.subscribe_projected(
+        session_id,
+        trusted=trusted,
+        after_seq=int(receipt.accepted_seq or 0),
+        projector=_new_responses_projector(),
+    ):
+        if projected and projected[0] == "response.completed":
+            output_text = str(projected[1].get("output_text") or output_text)
+            break
+        if projected and projected[0] in {"response.failed", "response.canceled"}:
+            return JSONResponse(
+                status_code=502,
+                content={"error": projected[1]},
+            )
+        elif projected:
+            output_text += str(projected[1].get("delta") or "")
+    payload = build_payload(output_text)
+    return JSONResponse(
+        status_code=ingress.receipt_http_status(receipt),
+        content=payload,
+        headers=ingress.receipt_response_headers(receipt),
+    )
+
+
+__all__ = [
+    "kernel_conversation_turn",
+    "kernel_stream_response",
+]

ksadk/server/routes/openai_compat.py

@@ -6,6 +6,7 @@ import uuid
 from collections.abc import Mapping
 from typing import Any, Dict, List, Optional
 
+from fastapi import HTTPException
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 
@@ -20,11 +21,18 @@ from ksadk.conversations.runtime_streaming import (
     stream_runtime_conversation_turn,
     stream_runtime_responses_conversation_turn,
 )
+from ksadk.kernel.ingress import kernel_route_active
 from ksadk.runtime.conversation_execution import invoke_runtime_conversation_once
 from ksadk.server.factory import get_runtime_execution
 
 from . import dependencies as deps
 from .checkpoint_resolution import _resolve_checkpoint_resume_input_from_session
+from .kernel_ingress import (
+    _kernel_error_response,
+    _kernel_submit,
+    kernel_conversation_turn,
+    kernel_stream_response,
+)
 from .models import (
     ResponsesRequest,
     _clean_optional_string,
@@ -60,6 +68,26 @@ async def list_openai_models():
     """Expose the current model catalog through the OpenAI-compatible path."""
 
     payload = await _build_models_payload()
+    try:
+        _executor, launch_context = get_runtime_execution()
+    except HTTPException:
+        launch_context = None
+    if launch_context is not None:
+        config = dict(launch_context.config)
+        raw_allowed = (
+            config.get("models") or config.get("allowed_models") or config.get("allowedModels")
+        )
+        if isinstance(raw_allowed, (list, tuple, set)):
+            allowed = {str(item).strip() for item in raw_allowed if str(item).strip()}
+            default_model = str(config.get("model") or "").strip()
+            if default_model:
+                allowed.add(default_model)
+            payload = dict(payload)
+            payload["data"] = [
+                item
+                for item in payload.get("data", [])
+                if str(item.get("id") or "").strip() in allowed
+            ]
     return {
         "object": "list",
         "data": payload.get("data", []),
@@ -72,6 +100,8 @@ async def list_openai_models():
 async def responses(request: ResponsesRequest):
     """OpenAI Responses 兼容接口。"""
     executor, launch_context = get_runtime_execution()
+    if kernel_route_active():
+        return await _kernel_responses(request, launch_context)
     resolved_session_id, resolved_user_id = _resolve_responses_session_and_user(request)
     agent_id = _runtime_agent_id(launch_context)
 
@@ -82,11 +112,7 @@ async def responses(request: ResponsesRequest):
         session_id=resolved_session_id,
         resume_input=resume_input,
     )
-    messages = (
-        []
-        if resume_input is not None
-        else normalize_responses_input(request.input)
-    )
+    messages = [] if resume_input is not None else normalize_responses_input(request.input)
     custom_metadata, request_metadata = _split_custom_metadata(request.metadata)
     if request.previous_response_id:
         request_metadata["previous_response_id"] = request.previous_response_id
@@ -105,9 +131,7 @@ async def responses(request: ResponsesRequest):
 
     if request.stream:
         runtime_preparation = (
-            None
-            if resume_input is not None
-            else await executor.prepare_start(launch_context)
+            None if resume_input is not None else await executor.prepare_start(launch_context)
         )
         resume_key = _detached_resume_key_from_input(resolved_session_id, resume_input)
         _reject_if_detached_resume_active(resume_key)
@@ -169,6 +193,62 @@ async def responses(request: ResponsesRequest):
     )
 
 
+async def _kernel_responses(request: ResponsesRequest, launch_context):
+    """kernel 路径（灰度 opt-in）：Responses -> AgentControlCommand -> receipt。"""
+
+    from ksadk.conversations.runtime_persistence import ensure_conversation_session
+
+    resolved_session_id, resolved_user_id = _resolve_responses_session_and_user(request)
+    session = await ensure_conversation_session(
+        agent_id=_runtime_agent_id(launch_context),
+        user_id=resolved_user_id,
+        session_id=resolved_session_id,
+        session_service_provider=deps.resolve_session_service,
+    )
+    session_id = session.id
+    metadata = request.metadata if isinstance(request.metadata, dict) else {}
+    idempotency_key = (
+        _clean_optional_string(metadata.get("idempotency_key"))
+        or _metadata_invocation_id(metadata)
+        or f"resp_{uuid.uuid4().hex}"
+    )
+    messages = normalize_responses_input(request.input)
+    response_id = f"resp_{uuid.uuid4().hex}"
+    receipt, trusted = await _kernel_submit(
+        mapper="map_responses_request",
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        content=messages,
+        correlation_ref=response_id,
+        source_kind="responses",
+    )
+    if receipt.status not in ("accepted", "duplicate"):
+        return _kernel_error_response(receipt)
+
+    def build_payload(output_text: str):
+        return build_responses_payload(
+            output_text=output_text,
+            model=request.model,
+            session_id=session_id,
+            response_id=response_id,
+            metadata=None,
+            usage=None,
+        )
+
+    if request.stream:
+        return kernel_stream_response(
+            receipt=receipt,
+            trusted=trusted,
+            session_id=session_id,
+        )
+    return await kernel_conversation_turn(
+        receipt=receipt,
+        trusted=trusted,
+        session_id=session_id,
+        build_payload=build_payload,
+    )
+
+
 @openai_compat_router.post("/v1/chat/completions")
 async def chat_completions(request: ChatCompletionRequest):
     """OpenAI 兼容的聊天补全接口 (支持流式和非流式)"""