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

ksadk/server/routes/openai_compat.py

@@ -6,14 +6,33 @@ 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
 
+from ksadk.conversations.normalize import normalize_kop_messages, normalize_responses_input
 from ksadk.conversations.run_kinds import RUN_MODE_FOREGROUND, trigger_from_resume_input
+from ksadk.conversations.runtime_payloads import (
+    build_chat_completions_payload,
+    build_responses_payload,
+    extract_responses_resume_input,
+)
+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 .common import _prepare_runner_for_model, _resolve_active_runner
+from .kernel_ingress import (
+    _kernel_error_response,
+    _kernel_submit,
+    kernel_conversation_turn,
+    kernel_stream_response,
+)
 from .models import (
     ResponsesRequest,
     _clean_optional_string,
@@ -23,7 +42,10 @@ from .models import (
     _split_custom_metadata,
 )
 from .routers import openai_compat_router
-from .streaming import _detached_resume_key_from_input, _reject_if_detached_resume_active
+from .streaming import (
+    _detached_resume_key_from_input,
+    _reject_if_detached_resume_active,
+)
 from .workspace import _build_models_payload
 
 
@@ -46,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", []),
@@ -57,22 +99,20 @@ async def list_openai_models():
 @openai_compat_router.post("/v1/responses")
 async def responses(request: ResponsesRequest):
     """OpenAI Responses 兼容接口。"""
-    active_runner = _resolve_active_runner()
+    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(active_runner)
+    agent_id = _runtime_agent_id(launch_context)
 
-    resume_input = deps.conversation().extract_responses_resume_input(request.input)
+    resume_input = extract_responses_resume_input(request.input)
     resume_input = await _resolve_checkpoint_resume_input_from_session(
         service=deps.resolve_session_service(),
         agent_id=agent_id,
         session_id=resolved_session_id,
         resume_input=resume_input,
     )
-    messages = (
-        []
-        if resume_input is not None
-        else deps.conversation().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
@@ -90,11 +130,15 @@ async def responses(request: ResponsesRequest):
     invocation_id = _metadata_invocation_id(request_metadata)
 
     if request.stream:
+        runtime_preparation = (
+            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)
         return deps.detached_streaming_response(
-            deps.conversation().stream_responses_conversation_turn(
-                runner=active_runner,
+            stream_runtime_responses_conversation_turn(
+                executor=executor,
+                launch_context=launch_context,
                 agent_id=agent_id,
                 user_id=resolved_user_id,
                 messages=messages,
@@ -108,9 +152,9 @@ async def responses(request: ResponsesRequest):
                 resume_input=resume_input,
                 account_id=account_id,
                 invocation_id=invocation_id,
-                prepare_runner=_prepare_runner_for_model,
                 session_service_provider=deps.resolve_session_service,
                 run_mode=RUN_MODE_FOREGROUND,
+                runtime_preparation=runtime_preparation,
             ),
             invocation_id=invocation_id,
             resume_key=resume_key,
@@ -119,8 +163,9 @@ async def responses(request: ResponsesRequest):
         )
 
     response_id = f"resp_{uuid.uuid4().hex}"
-    resolved_session_id, result = await deps.conversation().invoke_conversation_once(
-        runner=active_runner,
+    resolved_session_id, result = await invoke_runtime_conversation_once(
+        executor=executor,
+        launch_context=launch_context,
         agent_id=agent_id,
         user_id=resolved_user_id,
         messages=messages,
@@ -135,11 +180,10 @@ async def responses(request: ResponsesRequest):
         response_id=response_id,
         account_id=account_id,
         invocation_id=invocation_id,
-        prepare_runner=_prepare_runner_for_model,
         session_service_provider=deps.resolve_session_service,
         run_mode=RUN_MODE_FOREGROUND,
     )
-    return deps.conversation().build_responses_payload(
+    return build_responses_payload(
         output_text=result["output_text"],
         model=request.model,
         session_id=resolved_session_id,
@@ -149,21 +193,79 @@ 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 兼容的聊天补全接口 (支持流式和非流式)"""
-    active_runner = _resolve_active_runner()
-    messages = deps.conversation().normalize_kop_messages(request.messages)
-    agent_id = _runtime_agent_id(active_runner)
+    executor, launch_context = get_runtime_execution()
+    messages = normalize_kop_messages(request.messages)
+    agent_id = _runtime_agent_id(launch_context)
     resolved_user_id = _clean_optional_string(request.user) or "user"
     account_id = _clean_optional_string(request.account_id)
     custom_metadata, request_metadata = _split_custom_metadata(request.metadata)
     invocation_id = _metadata_invocation_id(request_metadata)
 
     if request.stream:
+        runtime_preparation = await executor.prepare_start(launch_context)
         return StreamingResponse(
-            deps.conversation().stream_conversation_turn(
-                runner=active_runner,
+            stream_runtime_conversation_turn(
+                executor=executor,
+                launch_context=launch_context,
                 agent_id=agent_id,
                 user_id=resolved_user_id,
                 messages=messages,
@@ -175,15 +277,16 @@ async def chat_completions(request: ChatCompletionRequest):
                 custom_metadata=custom_metadata,
                 invocation_id=invocation_id,
                 account_id=account_id,
-                prepare_runner=_prepare_runner_for_model,
                 session_service_provider=deps.resolve_session_service,
                 run_mode=RUN_MODE_FOREGROUND,
+                runtime_preparation=runtime_preparation,
             ),
             media_type="text/event-stream",
         )
 
-    resolved_session_id, result = await deps.conversation().invoke_conversation_once(
-        runner=active_runner,
+    resolved_session_id, result = await invoke_runtime_conversation_once(
+        executor=executor,
+        launch_context=launch_context,
         agent_id=agent_id,
         user_id=resolved_user_id,
         messages=messages,
@@ -195,11 +298,10 @@ async def chat_completions(request: ChatCompletionRequest):
         custom_metadata=custom_metadata,
         invocation_id=invocation_id,
         account_id=account_id,
-        prepare_runner=_prepare_runner_for_model,
         session_service_provider=deps.resolve_session_service,
         run_mode=RUN_MODE_FOREGROUND,
     )
-    return deps.conversation().build_chat_completions_payload(
+    return build_chat_completions_payload(
         output_text=result["output_text"],
         model=request.model,
         session_id=resolved_session_id,

ksadk/server/routes/projection.py

@@ -15,8 +15,10 @@ from ksadk.conversations.session_title import (
     build_fallback_title,
     build_heuristic_title,
 )
-from ksadk.server.factory import get_state
-from ksadk.sessions import ConversationSessionCore, Session, SessionEvent
+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
 
 from . import dependencies as deps
 from .common import _sanitize_session_state_for_action
@@ -52,7 +54,6 @@ async def _require_action_session(
 
 
 async def _session_to_action_payload(session: Session) -> dict[str, Any]:
-    runner = get_state().runner
     events = list(session.events or [])
     if not events:
         try:
@@ -106,21 +107,56 @@ async def _session_to_action_payload(session: Session) -> dict[str, Any]:
         "CreatedAt": session.created_at,
         "UpdatedAt": session.updated_at,
         "Version": session.version,
+        "Continuity": _runtime_continuity_payload(),
     }
-    if runner is not None:
-        try:
-            continuity = await runner.get_session_adapter().describe_continuity(
-                runner=runner,
-                session=session,
-                core=ConversationSessionCore(deps.resolve_session_service()),
-            )
-            payload["Continuity"] = continuity.to_payload()
-        except Exception as exc:
-            logger.debug("Failed to describe continuity for session %s: %s", session.id, exc)
     return payload
 
 
+def _runtime_continuity_payload() -> dict[str, Any]:
+    """Describe continuity from the active RuntimeAdapter capability contract."""
+
+    state = get_state()
+    if state.executor is None or state.launch_context is None:
+        # Session storage is independently useful in route-manifest and
+        # control-plane-only apps. Do not make a metadata projection require a
+        # live runtime execution binding.
+        return {
+            "Level": "semantic",
+            "Path": "replay",
+            "Runtime": "unbound",
+            "Details": {
+                "CheckpointSupported": False,
+                "Reason": "RuntimeAdapter is not bound to this app",
+            },
+        }
+    executor, launch_context = get_runtime_execution()
+    capabilities = executor.native_capabilities(launch_context)
+    continuity = capabilities.get("SessionContinuity")
+    continuity = continuity if isinstance(continuity, Mapping) else {}
+    checkpoint = capabilities.get("Checkpoint")
+    checkpoint = checkpoint if isinstance(checkpoint, Mapping) else {}
+    level = str(continuity.get("Level") or "semantic").strip().lower()
+    if level not in {"ui_only", "semantic", "runtime", "exact"}:
+        level = "semantic"
+    return {
+        "Level": level,
+        "Path": "checkpoint" if checkpoint.get("Supported") else "replay",
+        "Runtime": launch_context.runtime_type,
+        "Details": {
+            "CheckpointSupported": bool(checkpoint.get("Supported")),
+            "Reason": str(continuity.get("Reason") or ""),
+        },
+    }
+
+
 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,
@@ -203,9 +239,41 @@ async def _iter_with_idle_heartbeat(source: AsyncIterator[Any]):
 
 
 def _checkpoint_event_to_action_payload(event: SessionEvent) -> dict[str, Any] | None:
-    if event.event_type != "run_checkpoint":
-        return None
-    metadata = event.metadata or {}
+    """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 {}
+    else:
+        canonical = session_event_to_runtime_event(event)
+        if not isinstance(canonical, ContinuationCreated):
+            return None
+        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 {}),
+            **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(capability.get("backend") or "unknown"),
+            "scope": str(capability.get("scope") or "unknown"),
+            "durable": bool(capability.get("durable", False)),
+            "is_resumable": canonical.resumable,
+        }
     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()