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

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()

ksadk/server/routes/run.py

@@ -39,6 +39,7 @@ from ksadk.conversations.runtime_streaming import (
 if TYPE_CHECKING:
     pass
 from ksadk.ids import new_run_id
+from ksadk.kernel.ingress import kernel_route_active
 from ksadk.runtime.conversation_execution import (
     invoke_runtime_conversation_once,
     iter_runtime_conversation_semantic_events,
@@ -51,6 +52,11 @@ from .checkpoint_resolution import _resolve_checkpoint_resume_input_from_session
 from .common import (
     _action_response,
 )
+from .kernel_ingress import (
+    _kernel_error_response,
+    kernel_conversation_turn,
+    kernel_stream_response,
+)
 from .models import (
     RunAgentActionRequest,
     _clean_optional_string,
@@ -72,6 +78,8 @@ logger = logging.getLogger(__name__)
 @run_router.post("/agentengine/api/v1/RunAgent")
 async def run_agent_action(request: RunAgentActionRequest):
     executor, launch_context = get_runtime_execution()
+    if kernel_route_active():
+        return await _kernel_run_agent_action(request, launch_context)
     api_format = (request.ApiFormat or "responses").strip().lower()
     run_user_id = _clean_optional_string(request.UserId) or "user"
     account_id = _clean_optional_string(request.AccountId)
@@ -283,6 +291,92 @@ async def run_agent_action(request: RunAgentActionRequest):
     return _action_response("RunAgent", payload)
 
 
+async def _kernel_run_agent_action(request: RunAgentActionRequest, launch_context):
+    """kernel 路径（灰度 opt-in）：RunAgent -> AgentControlCommand -> receipt。
+
+    旧响应 shape 不变；receipt 状态走 RECEIPT_HTTP_STATUS 映射；
+    stream 从 SessionEventSubscription 统一 cursor 读取。
+    """
+    from .kernel_ingress import _kernel_submit
+
+    run_user_id = _clean_optional_string(request.UserId) or "user"
+    session = await ensure_conversation_session(
+        agent_id=request.AgentId,
+        user_id=run_user_id,
+        session_id=request.SessionId,
+        session_service_provider=deps.resolve_session_service,
+    )
+    session_id = session.id
+    idempotency_key = (
+        _clean_optional_string(request.InvocationId)
+        or _clean_optional_string(
+            (request.Metadata or {}).get("IdempotencyKey")
+            if isinstance(request.Metadata, dict)
+            else None
+        )
+        or new_run_id(session_id)
+    )
+    messages = (
+        normalize_responses_input(request.ResponsesInput)
+        if request.ResponsesInput is not None
+        and (request.ApiFormat or "responses").strip().lower() == "responses"
+        else normalize_kop_messages(request.Messages)
+    )
+    # RunAgent 的 Model 覆盖走 runtime_options.model:与 agentengine-server 的
+    # _kernel_runtime_options 投影同构;worker 侧按部署 defaults/白名单校验。
+    runtime_options: dict[str, Any] = {}
+    requested_model = _clean_optional_string(request.Model)
+    if requested_model:
+        runtime_options["model"] = requested_model
+    receipt, trusted = await _kernel_submit(
+        mapper="map_run_request",
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        content=messages,
+        correlation_ref=request.InvocationId,
+        source_kind="system",
+        runtime_options=runtime_options or None,
+    )
+    if receipt.status not in ("accepted", "duplicate"):
+        return _kernel_error_response(receipt)
+
+    def build_payload(output_text: str):
+        if (request.ApiFormat or "responses").strip().lower() == "chat_completions":
+            return _action_response(
+                "RunAgent",
+                build_chat_completions_payload(
+                    output_text=output_text,
+                    model=request.Model,
+                    session_id=session_id,
+                    metadata=None,
+                ),
+            )
+        return _action_response(
+            "RunAgent",
+            build_responses_payload(
+                output_text=output_text,
+                model=request.Model,
+                session_id=session_id,
+                response_id=f"resp_{uuid.uuid4().hex}",
+                metadata=None,
+                usage=None,
+            ),
+        )
+
+    if request.Stream or request.Background:
+        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,
+    )
+
+
 # ============================================================
 # Session Management API (ADK Web Compatible)
 # ============================================================

ksadk/server/routes/sessions.py

@@ -67,6 +67,7 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
     workspace_enabled = workspace_files_enabled(default=True)
     ui_spec = _resolve_agent_ui_spec()
     runtime_capabilities = executor.native_capabilities(launch_context)
+    runtime_capability_matrix = executor.capability_matrix(launch_context)
     resume_capability = (
         runtime_capabilities.get("ResumeRun")
         if isinstance(runtime_capabilities, Mapping)
@@ -148,6 +149,7 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
                 "StopRun": cancel_run_supported,
                 "ResumeRun": checkpoint_resume_supported,
                 "RuntimeCapabilities": runtime_capabilities,
+                "RuntimeCapabilityMatrix": runtime_capability_matrix,
                 "CheckpointResumeCapability": checkpoint_resume_capability,
                 "RunLifecycle": {
                     "Enabled": True,

ksadk/server/routes/streaming.py

@@ -92,6 +92,7 @@ class _DetachedSSEStream:
 
     async def _consume(self) -> None:
         terminal_fallback_status: str | None = None
+        terminal_fallback_detail: str | None = None
         try:
             async for chunk in self._source:
                 self._backlog.append(chunk)
@@ -107,8 +108,9 @@ class _DetachedSSEStream:
         except asyncio.CancelledError:
             terminal_fallback_status = "cancelled"
             raise
-        except Exception:
+        except Exception as exc:
             terminal_fallback_status = "failed"
+            terminal_fallback_detail = f"{type(exc).__name__}: {exc}"[:2048]
             logger.exception("Detached SSE stream failed")
             raise
         finally:
@@ -128,7 +130,8 @@ class _DetachedSSEStream:
                             status=terminal_fallback_status,
                             invocation_id=self.invocation_id or "",
                             detail=(
-                                f"background_{terminal_fallback_status}:{self.invocation_id or ''}"
+                                terminal_fallback_detail
+                                or f"background_{terminal_fallback_status}:{self.invocation_id or ''}"
                             ),
                             session_service_provider=get_state().resolve_session_service,
                             run_mode=self._run_mode,

ksadk/server/static/assets/{ArtifactsPanel-CakCqxEN.js → ArtifactsPanel-DSU1sWD_.js}

@@ -1 +1 @@
-import{bt as e,ht as t,lt as n,n as r,t as i,ut as a,wt as o,xt as s,yt as c}from"./index-R52pJJvg.js";var l=o(s(),1),u=c();function d(){let o=e(e=>e.visible),s=e(e=>e.content),c=e(e=>e.type),d=e(e=>e.hide),f=(0,l.useRef)(null);if(r(f),!o||!s)return null;let p=i(s);return(0,u.jsxs)(`aside`,{className:n(`flex h-full flex-shrink-0 flex-col border-l border-slate-200/30 bg-white dark:border-slate-800/40 dark:bg-slate-950`,`w-[min(42rem,50vw)]`),children:[(0,u.jsxs)(`div`,{className:`flex h-14 flex-shrink-0 items-center justify-between border-b border-slate-200/30 px-4 dark:border-slate-800/40`,children:[(0,u.jsxs)(`div`,{className:`flex min-w-0 items-center gap-2`,children:[(0,u.jsx)(`span`,{className:`text-sm font-semibold text-slate-900 dark:text-slate-100`,children:`Artifact`}),(0,u.jsx)(`span`,{className:`rounded-md bg-slate-100 px-1.5 py-0.5 font-mono text-[11px] text-slate-500 dark:bg-slate-900 dark:text-slate-400`,children:c})]}),(0,u.jsxs)(`div`,{className:`flex items-center gap-1.5`,children:[(0,u.jsxs)(`button`,{type:`button`,onClick:()=>{let e=new Blob([s],{type:`text/html;charset=utf-8`}),t=URL.createObjectURL(e),n=document.createElement(`a`);n.href=t,n.download=`artifact.${c===`svg`?`svg`:`html`}`,document.body.appendChild(n),n.click(),document.body.removeChild(n),URL.revokeObjectURL(t)},className:`inline-flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs font-medium text-slate-600 transition hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-900`,title:`Download`,children:[(0,u.jsx)(t,{className:`h-3.5 w-3.5`}),`Download`]}),(0,u.jsx)(`button`,{type:`button`,onClick:d,className:`rounded-lg p-1.5 text-slate-500 transition hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-900 dark:hover:text-slate-100`,"aria-label":`Close Artifact`,title:`Close`,children:(0,u.jsx)(a,{className:`h-4 w-4`})})]})]}),(0,u.jsx)(`div`,{className:`min-h-0 flex-1`,children:(0,u.jsx)(`iframe`,{ref:f,srcDoc:p,sandbox:`allow-scripts allow-downloads`,title:`Artifact Preview`,className:`h-full w-full border-0 bg-white`})})]})}export{d as ArtifactsPanel};
+import{St as e,Tt as t,bt as n,gt as r,lt as i,n as a,t as o,ut as s,xt as c}from"./index-8ipRcQ-M.js";var l=t(e(),1),u=n();function d(){let e=c(e=>e.visible),t=c(e=>e.content),n=c(e=>e.type),d=c(e=>e.hide),f=(0,l.useRef)(null);if(a(f),!e||!t)return null;let p=o(t);return(0,u.jsxs)(`aside`,{className:i(`flex h-full flex-shrink-0 flex-col border-l border-slate-200/30 bg-white dark:border-slate-800/40 dark:bg-slate-950`,`w-[min(42rem,50vw)]`),children:[(0,u.jsxs)(`div`,{className:`flex h-14 flex-shrink-0 items-center justify-between border-b border-slate-200/30 px-4 dark:border-slate-800/40`,children:[(0,u.jsxs)(`div`,{className:`flex min-w-0 items-center gap-2`,children:[(0,u.jsx)(`span`,{className:`text-sm font-semibold text-slate-900 dark:text-slate-100`,children:`Artifact`}),(0,u.jsx)(`span`,{className:`rounded-md bg-slate-100 px-1.5 py-0.5 font-mono text-[11px] text-slate-500 dark:bg-slate-900 dark:text-slate-400`,children:n})]}),(0,u.jsxs)(`div`,{className:`flex items-center gap-1.5`,children:[(0,u.jsxs)(`button`,{type:`button`,onClick:()=>{let e=new Blob([t],{type:`text/html;charset=utf-8`}),r=URL.createObjectURL(e),i=document.createElement(`a`);i.href=r,i.download=`artifact.${n===`svg`?`svg`:`html`}`,document.body.appendChild(i),i.click(),document.body.removeChild(i),URL.revokeObjectURL(r)},className:`inline-flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs font-medium text-slate-600 transition hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-900`,title:`Download`,children:[(0,u.jsx)(r,{className:`h-3.5 w-3.5`}),`Download`]}),(0,u.jsx)(`button`,{type:`button`,onClick:d,className:`rounded-lg p-1.5 text-slate-500 transition hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-900 dark:hover:text-slate-100`,"aria-label":`Close Artifact`,title:`Close`,children:(0,u.jsx)(s,{className:`h-4 w-4`})})]})]}),(0,u.jsx)(`div`,{className:`min-h-0 flex-1`,children:(0,u.jsx)(`iframe`,{ref:f,srcDoc:p,sandbox:`allow-scripts allow-downloads`,title:`Artifact Preview`,className:`h-full w-full border-0 bg-white`})})]})}export{d as ArtifactsPanel};