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

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 兼容的聊天补全接口 (支持流式和非流式)"""

ksadk/server/routes/projection.py

@@ -15,7 +15,8 @@ from ksadk.conversations.session_title import (
     build_fallback_title,
     build_heuristic_title,
 )
-from ksadk.events.runtime_event import EventType
+from ksadk.events.canonical import ContinuationCreated
+from ksadk.events.canonical_store import session_event_to_runtime_event
 from ksadk.server.factory import get_runtime_execution, get_state
 from ksadk.sessions import Session, SessionEvent
 
@@ -149,6 +150,13 @@ def _runtime_continuity_payload() -> dict[str, Any]:
 
 
 def _event_to_action_payload(event: SessionEvent) -> dict[str, Any]:
+    """Serialize a stored SessionEvent for the REST action wire.
+
+    公开承诺字段（契约声明见 ``ksadk/events/projections.py``）：
+    ``EventId``/``SessionId``/``Author``/``EventType``/``Content``/``Timestamp``/
+    ``SeqId``（有值时附 ``InvocationId``）。这是存储事件形态本身的透传，
+    ``Content``/``Metadata`` 的内部结构不在承诺范围。
+    """
     payload = {
         "EventId": event.id,
         "SessionId": event.session_id,
@@ -231,34 +239,41 @@ async def _iter_with_idle_heartbeat(source: AsyncIterator[Any]):
 
 
 def _checkpoint_event_to_action_payload(event: SessionEvent) -> dict[str, Any] | None:
+    """Project a checkpoint-bearing event into the REST checkpoint action payload.
+
+    公开承诺字段（契约声明见 ``ksadk/events/projections.py``）：``EventId``/
+    ``SessionId``/``InvocationId``/``SeqId``/``Timestamp``/``RunId``/
+    ``CheckpointId``/``Framework``/``FrameworkRef``/``IsResumable``/
+    ``ResumeStatus``/``IsTerminal``/``NextNode``。来源为显式 ``run_checkpoint``
+    事件元数据，或 ``continuation.created`` canonical 事件的投影。
+    非 checkpoint 事件（或不可识别的 continuation_kind）返回 ``None``。
+    内部不保证字段：其余元数据透传键（``Metadata`` 内容随存储演进可变）。
+    """
     if event.event_type == "run_checkpoint":
         metadata = event.metadata or {}
-    elif event.event_type == EventType.CHECKPOINT_CREATED:
-        content = event.content or {}
-        payload = content.get("payload") if isinstance(content, Mapping) else {}
-        if not isinstance(payload, Mapping):
+    else:
+        canonical = session_event_to_runtime_event(event)
+        if not isinstance(canonical, ContinuationCreated):
             return None
-        framework_ref = payload.get("framework_ref") or payload.get("resume_target") or {}
-        if not isinstance(framework_ref, Mapping):
-            framework_ref = {}
-        framework = str(payload.get("framework") or "").strip()
-        if not framework and len(framework_ref) == 1:
-            framework = str(next(iter(framework_ref)))
-        capability = payload.get("capability")
+        if canonical.continuation_kind != "graph_checkpoint":
+            return None
+        framework = canonical.source.framework
+        framework_ref = {framework: dict(canonical.ref)}
+        capability = canonical.source.metadata.get("capability")
         capability = capability if isinstance(capability, Mapping) else {}
         metadata = {
             **dict(event.metadata or {}),
-            "run_id": str(payload.get("run_id") or event.invocation_id or ""),
-            "checkpoint_id": str(payload.get("checkpoint_id") or ""),
+            **dict(canonical.source.metadata),
+            "continuation_kind": canonical.continuation_kind,
+            "run_id": canonical.run_id,
+            "checkpoint_id": canonical.continuation_id,
             "framework": framework,
             "framework_ref": dict(framework_ref),
-            "backend": str(payload.get("backend") or capability.get("backend") or "unknown"),
-            "scope": str(payload.get("scope") or capability.get("scope") or "unknown"),
-            "durable": bool(payload.get("durable", capability.get("durable", False))),
-            "is_resumable": bool(payload.get("is_resumable", True)),
+            "backend": str(capability.get("backend") or "unknown"),
+            "scope": str(capability.get("scope") or "unknown"),
+            "durable": bool(capability.get("durable", False)),
+            "is_resumable": canonical.resumable,
         }
-    else:
-        return None
     run_id = str(metadata.get("run_id") or "").strip()
     checkpoint_id = str(metadata.get("checkpoint_id") or "").strip()
     framework = str(metadata.get("framework") or "").strip()