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

ksadk/server/routes/common.py

@@ -16,12 +16,10 @@ from fastapi.responses import FileResponse, Response
 
 from ksadk.conversations.attachments import compact_attachment_result_for_session
 from ksadk.conversations.model_context import normalize_model_metadata
-from ksadk.runners.base_runner import BaseRunner
 from ksadk.runtime_state import load_state as load_runtime_state
 from ksadk.server.factory import (
     RuntimeAppState,
     bind_runtime_state,
-    get_runner,
     get_state,
 )
 from ksadk.server.terminal_sessions import (
@@ -102,11 +100,8 @@ _NATIVE_TUI_FRAMEWORKS = {"hermes", "openclaw"}
 
 
 def _current_framework() -> str:
-    runner = get_state().runner
-    if not runner:
-        return ""
-    detection_type = getattr(getattr(runner, "detection_result", None), "type", None)
-    return str(getattr(detection_type, "value", detection_type) or "").strip().lower()
+    context = get_state().launch_context
+    return str(context.runtime_type if context is not None else "").strip().lower()
 
 
 def _build_native_terminal_capability(framework: str) -> dict[str, Any]:
@@ -145,32 +140,6 @@ def _register_integrated_routers(app: FastAPI, state: RuntimeAppState) -> None:
     )
 
 
-def set_runner(r: BaseRunner, *, loaded: bool = False):
-    """Bind a runner and record whether its agent has already been loaded."""
-    state = get_state()
-    state.runner = r
-    state.runner_loaded = loaded
-    from ksadk.server.factory import wire_default_agui_for_runner
-
-    wire_default_agui_for_runner(state, r)
-
-
-def _ensure_runner_loaded() -> BaseRunner:
-    return get_runner()
-
-
-def _resolve_active_runner() -> BaseRunner:
-    return get_runner()
-
-
-def _prepare_runner_for_model(active_runner: BaseRunner, model: Optional[str]) -> None:
-    try:
-        active_runner.prepare_for_request(model)
-    except Exception as exc:
-        logger.warning("Runner 模型切换失败: %s", exc)
-        raise HTTPException(status_code=500, detail=str(exc) or "Runner 模型切换失败") from exc
-
-
 def _resolve_current_model() -> tuple[Optional[str], Optional[str]]:
     candidates = (
         ("OPENAI_MODEL_NAME", os.getenv("OPENAI_MODEL_NAME")),
@@ -194,11 +163,11 @@ def _build_bootstrap_model_payload() -> Optional[dict[str, Any]]:
     return payload
 
 
-def _runner_project_dir() -> Path:
-    runner = get_state().runner
-    if runner and getattr(runner, "project_dir", None):
+def _runtime_project_dir() -> Path:
+    context = get_state().launch_context
+    if context is not None:
         try:
-            return Path(str(runner.project_dir)).resolve()
+            return Path(str(context.project_dir)).resolve()
         except Exception:
             pass
     return Path(".").resolve()
@@ -223,7 +192,7 @@ def _ui_state_with_env_fallback(state: dict[str, Any]) -> dict[str, Any]:
 
 
 def _resolve_agent_ui_spec() -> dict[str, Any]:
-    project_dir = _runner_project_dir()
+    project_dir = _runtime_project_dir()
     state = _ui_state_with_env_fallback(load_runtime_state(project_dir))
     framework = _current_framework()
     auto_custom_bundle_dir = _default_custom_ui_bundle_dir(project_dir)
@@ -696,18 +665,18 @@ async def _workspace_runtime_request(
 
 @health_meta_router.get("/health")
 async def health_check():
-    runner = get_state().runner
-    framework = "unknown"
-    agent_name = "unknown"
-    if runner and hasattr(runner, "detection_result"):
-        framework = runner.detection_result.type.value  # langgraph, langchain, adk
-        agent_name = runner.detection_result.name
+    context = get_state().launch_context
+    framework = context.runtime_type if context is not None else "unknown"
+    detection = context.detection if context is not None else None
+    agent_name = str(getattr(detection, "name", "") or "unknown")
     return {"status": "ok", "framework": framework, "agent": agent_name}
 
 
 @health_meta_router.get("/list-apps")
 async def list_apps(relative_path: str = "./"):
     """Return available apps. For KsADK single-agent mode, returns the current agent."""
-    runner = get_state().runner
-    name = runner.detection_result.name if runner else "default_agent"
+    del relative_path
+    context = get_state().launch_context
+    detection = context.detection if context is not None else None
+    name = str(getattr(detection, "name", "") or "default_agent")
     return [name]

ksadk/server/routes/control.py

@@ -17,10 +17,14 @@ from ksadk.conversations.run_kinds import (
     RUN_MODE_FOREGROUND,
     RUN_TRIGGER_CHECKPOINT_RESUME,
 )
+from ksadk.conversations.runtime_payloads import build_responses_payload
+from ksadk.conversations.runtime_streaming import stream_runtime_responses_conversation_turn
+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 _find_session_checkpoint
-from .common import _action_response, _prepare_runner_for_model, _resolve_active_runner
+from .common import _action_response
 from .models import (
     _MAX_PREVIEW_TOOL_RECEIPTS,
     _RUN_TERMINAL_STATUSES,
@@ -108,6 +112,7 @@ async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePrevi
 
 @control_router.post("/agentengine/api/v1/ResumeRun")
 async def resume_run_action(request: ResumeRunActionRequest):
+    executor, launch_context = get_runtime_execution()
     service = deps.resolve_session_service()
     session = await _require_action_session(
         service,
@@ -174,7 +179,6 @@ async def resume_run_action(request: ResumeRunActionRequest):
         "resume_instruction_enabled": bool(getattr(request, "ResumeInstructionEnabled", False)),
         "resume_instruction": str(getattr(request, "ResumeInstruction", "") or "").strip(),
     }
-    active_runner = _resolve_active_runner()
     user_id = session.user_id or "user"
     custom_metadata, _metadata_runtime_controls = _split_custom_metadata(request.Metadata)
     resume_request_metadata = {
@@ -201,8 +205,9 @@ async def resume_run_action(request: ResumeRunActionRequest):
             run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
         )
         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=request.AgentId,
                 user_id=user_id,
                 messages=[],
@@ -215,7 +220,6 @@ async def resume_run_action(request: ResumeRunActionRequest):
                 include_agentengine_metadata=True,
                 resume_input=resume_input,
                 invocation_id=resume_invocation_id,
-                prepare_runner=_prepare_runner_for_model,
                 session_service_provider=deps.resolve_session_service,
                 run_mode=RUN_MODE_BACKGROUND,
             ),
@@ -226,8 +230,9 @@ async def resume_run_action(request: ResumeRunActionRequest):
         )
 
     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=request.AgentId,
         user_id=user_id,
         messages=[],
@@ -240,11 +245,10 @@ async def resume_run_action(request: ResumeRunActionRequest):
         resume_input=resume_input,
         response_id=response_id,
         invocation_id=str(resume_input["resume_attempt_id"]),
-        prepare_runner=_prepare_runner_for_model,
         session_service_provider=deps.resolve_session_service,
         run_mode=RUN_MODE_FOREGROUND,
     )
-    payload = deps.conversation().build_responses_payload(
+    payload = build_responses_payload(
         output_text=result["output_text"],
         model=request.Model,
         session_id=resolved_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/misc.py

@@ -16,7 +16,6 @@ from ksadk.tracing import get_memory_exporter
 from . import dependencies as deps
 from .common import (
     _action_response,
-    _ensure_runner_loaded,
     _ensure_session,
     _hydrate_session,
     _resolve_ui_static_response,
@@ -393,40 +392,18 @@ async def delete_session(app_name: str, user_id: str, session_id: str):
     "/apps/{app_name}/users/{user_id}/sessions/{session_id}/save_memory"
 )
 async def save_session_to_memory(app_name: str, user_id: str, session_id: str):
-    """将指定 session 保存到长期记忆
-
-    当配置了 KSADK_LTM_BACKEND 时，将 session 中的用户消息
-    持久化到长期记忆后端，供后续 session 通过 load_memory 工具检索。
-    """
-    active_runner = _ensure_runner_loaded()
-
-    # 检查 runner 是否支持长期记忆
-    from ksadk.runners.adk_runner import ADKRunner as _ADKRunner
-
-    if not isinstance(active_runner, _ADKRunner):
-        raise HTTPException(
-            status_code=400, detail="Long-term memory is only supported with ADK runner"
-        )
-
-    if not active_runner._long_term_memory:
-        raise HTTPException(
-            status_code=400,
-            detail="Long-term memory not configured. Set KSADK_LTM_BACKEND environment variable.",
-        )
-
-    # 查找 ADK 内部 session ID
-    internal_session_id = active_runner._session_map.get(session_id, session_id)
-
-    success = await active_runner.save_session_to_long_term_memory(
-        session_id=internal_session_id,
-        user_id=user_id,
+    """Fail closed until long-term memory is exposed as a Runtime capability."""
+
+    del app_name, user_id, session_id
+    raise HTTPException(
+        status_code=501,
+        detail={
+            "code": "RUNTIME_NOT_SUPPORTED",
+            "message": "当前 RuntimeAdapter 未声明长期记忆写入能力",
+            "hint": "请通过 Runtime Catalog 检查长期记忆能力后重试",
+        },
     )
 
-    if success:
-        return {"status": "saved", "session_id": session_id}
-    else:
-        raise HTTPException(status_code=500, detail="Failed to save session to long-term memory")
-
 
 @sessions_adk_compat_router.get(
     "/apps/{app_name}/users/{user_id}/sessions/{session_id}/events/{event_id}/graph"

ksadk/server/routes/models.py

@@ -11,7 +11,7 @@ from pydantic import BaseModel, Field, field_validator
 
 from ksadk.conversations.run_kinds import RUN_MODE_UNKNOWN, RUN_TRIGGER_UNKNOWN
 from ksadk.conversations.run_status import RUN_STATUS_ACTIVE, RUN_STATUS_TERMINAL
-from ksadk.runners.base_runner import BaseRunner
+from ksadk.runtime.launch import RuntimeLaunchContext
 from ksadk.sessions import SessionEvent
 
 _RUN_TERMINAL_STATUSES = RUN_STATUS_TERMINAL
@@ -258,11 +258,11 @@ def _resolve_responses_session_and_user(request: ResponsesRequest) -> tuple[str
     return resolved_session_id, resolved_user_id
 
 
-def _runtime_agent_id(active_runner: BaseRunner) -> str:
+def _runtime_agent_id(launch_context: RuntimeLaunchContext) -> str:
     runtime_id = _clean_optional_string(os.getenv("AGENT_RUNTIME_ID"))
     if runtime_id:
         return runtime_id
-    return str(getattr(active_runner.detection_result, "name", "") or "agent")
+    return str(getattr(launch_context.detection, "name", "") or "agent")
 
 
 def _metadata_invocation_id(metadata: Mapping[str, Any] | None) -> str | None:
@@ -425,9 +425,17 @@ def _latest_session_run_metadata(
             if not _is_run_lifecycle_event(event) or _event_run_id(event) != invocation_id:
                 continue
             metadata = event.metadata or {}
-            run_mode = str(metadata.get("run_mode") or RUN_MODE_UNKNOWN)
-            run_trigger = str(metadata.get("run_trigger") or RUN_TRIGGER_UNKNOWN)
-            break
+            candidate_mode = str(metadata.get("run_mode") or RUN_MODE_UNKNOWN)
+            candidate_trigger = str(metadata.get("run_trigger") or RUN_TRIGGER_UNKNOWN)
+            # Canonical RuntimeEvents and their legacy ``run_status`` projection
+            # coexist in the session log. RuntimeEvents intentionally carry only
+            # the transport-neutral marker, while the projection owns run kind
+            # metadata. Keep scanning past an unclassified RuntimeEvent so the UI
+            # does not downgrade a known background/foreground run to ``unknown``.
+            if candidate_mode != RUN_MODE_UNKNOWN or candidate_trigger != RUN_TRIGGER_UNKNOWN:
+                run_mode = candidate_mode
+                run_trigger = candidate_trigger
+                break
     return invocation_id, status, run_mode, run_trigger