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

ksadk/server/routes/control.py

@@ -4,12 +4,13 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import time
 import uuid
 from collections.abc import AsyncIterator, Mapping
 from typing import Any, Optional
 
-from fastapi import HTTPException, Query
+from fastapi import Depends, HTTPException, Query
 from fastapi.responses import StreamingResponse
 
 from ksadk.conversations.run_kinds import (
@@ -18,10 +19,17 @@ from ksadk.conversations.run_kinds import (
     RUN_TRIGGER_CHECKPOINT_RESUME,
 )
 from ksadk.conversations.runtime_payloads import build_responses_payload
+from ksadk.conversations.runtime_persistence import require_conversation_session
 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 ksadk.runtime_context import PlatformIdentityContext
+from ksadk.server.factory import get_runtime_execution, get_state
 
+from ..invocation_identity import (
+    coerce_trusted_invocation_identity,
+    inject_trusted_invocation_identity,
+    resolve_trusted_invocation_identity,
+)
 from . import dependencies as deps
 from .checkpoint_resolution import _find_session_checkpoint
 from .common import _action_response
@@ -47,19 +55,63 @@ from .projection import (
 )
 from .routers import control_router, run_router
 from .streaming import (
+    _claim_detached_resume_key,
+    _clear_detached_resume_key,
     _detached_resume_key_from_input,
-    _reject_if_detached_resume_active,
 )
 
 
+async def _require_control_session(
+    service: Any,
+    *,
+    session_id: str,
+    agent_id: str | None,
+    user_id: str | None,
+    invocation_identity: PlatformIdentityContext,
+):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
+    if invocation_identity.is_empty:
+        return await _require_action_session(
+            service,
+            session_id=session_id,
+            agent_id=agent_id,
+            user_id=user_id,
+        )
+    if not agent_id:
+        raise HTTPException(status_code=400, detail="AgentId is required")
+    return await require_conversation_session(
+        agent_id=agent_id,
+        user_id=str(user_id or ""),
+        session_id=session_id,
+        session_service_provider=lambda: service,
+        invocation_identity=invocation_identity,
+    )
+
+
+def _resolve_active_runner() -> Any:
+    """Expose the adapter-owned runner for persistence capability probing."""
+
+    executor, launch_context = get_runtime_execution()
+    adapter = executor.create_adapter(launch_context)
+    runner = getattr(adapter, "_runner", None)
+    if runner is None:
+        raise HTTPException(status_code=500, detail="Runtime runner is unavailable")
+    return runner
+
+
 @control_router.post("/agentengine/api/v1/GetCheckpointResumePreview")
-async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePreviewActionRequest):
+async def get_checkpoint_resume_preview_action(
+    request: GetCheckpointResumePreviewActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_control_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
 
     checkpoint = await _find_session_checkpoint(
@@ -96,29 +148,33 @@ async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePrevi
             if len(receipts) < _MAX_PREVIEW_TOOL_RECEIPTS:
                 receipts.append(receipt)
 
+    preview = _build_checkpoint_resume_preview(
+        checkpoint=checkpoint,
+        receipts=receipts,
+        receipt_total=receipt_total,
+        side_effect_receipt_count=side_effect_receipt_count,
+        failed_receipt_count=failed_receipt_count,
+    )
     return _action_response(
         "GetCheckpointResumePreview",
-        {
-            "Preview": _build_checkpoint_resume_preview(
-                checkpoint=checkpoint,
-                receipts=receipts,
-                receipt_total=receipt_total,
-                side_effect_receipt_count=side_effect_receipt_count,
-                failed_receipt_count=failed_receipt_count,
-            )
-        },
+        {"Preview": preview},
     )
 
 
 @control_router.post("/agentengine/api/v1/ResumeRun")
-async def resume_run_action(request: ResumeRunActionRequest):
+async def resume_run_action(
+    request: ResumeRunActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
     executor, launch_context = get_runtime_execution()
     service = deps.resolve_session_service()
-    session = await _require_action_session(
+    session = await _require_control_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
 
     checkpoint = await _find_session_checkpoint(
@@ -131,7 +187,7 @@ async def resume_run_action(request: ResumeRunActionRequest):
         raise HTTPException(status_code=404, detail="Checkpoint not found")
     disabled_detail = _checkpoint_resume_disabled_detail(checkpoint)
     if disabled_detail is not None:
-        if disabled_detail.get("is_terminal"):
+        if disabled_detail.get("IsTerminal"):
             resume_attempt_id = str(request.ResumeAttemptId or f"resume_{uuid.uuid4().hex}")
             invocation_id = str(request.InvocationId or resume_attempt_id)
             await deps.conversation().append_run_resume_event(
@@ -158,10 +214,14 @@ async def resume_run_action(request: ResumeRunActionRequest):
             return _action_response(
                 "ResumeRun",
                 {
+                    "Status": "noop",
                     "status": "noop",
-                    "Reason": disabled_detail["reason"],
-                    "CheckpointId": disabled_detail["checkpoint_id"],
-                    "RunId": disabled_detail["run_id"],
+                    "Reason": disabled_detail["Reason"],
+                    "reason": disabled_detail["Reason"],
+                    "CheckpointId": disabled_detail["CheckpointId"],
+                    "checkpoint_id": disabled_detail["CheckpointId"],
+                    "RunId": disabled_detail["RunId"],
+                    "run_id": disabled_detail["RunId"],
                     "ResumeAttemptId": resume_attempt_id,
                 },
             )
@@ -182,52 +242,145 @@ async def resume_run_action(request: ResumeRunActionRequest):
     user_id = session.user_id or "user"
     custom_metadata, _metadata_runtime_controls = _split_custom_metadata(request.Metadata)
     resume_request_metadata = {
+        **_metadata_runtime_controls,
         "responses_conversation": True,
     }
+    resume_request_metadata = inject_trusted_invocation_identity(
+        resume_request_metadata,
+        invocation_identity,
+    )
+
+    if request.Background:
+        resume_invocation_id = str(request.InvocationId or resume_input["resume_attempt_id"])
+        resume_key = _detached_resume_key_from_input(request.SessionId, resume_input)
+        await _claim_detached_resume_key(resume_key, resume_invocation_id, pascal_case_detail=True)
+        try:
+            await deps.conversation().append_run_resume_event(
+                session_id=request.SessionId,
+                author=request.AgentId,
+                run_id=str(request.RunId),
+                checkpoint_id=str(request.CheckpointId),
+                resume_attempt_id=str(resume_input["resume_attempt_id"]),
+                framework=checkpoint["Framework"],
+                framework_ref=checkpoint["FrameworkRef"],
+                invocation_id=resume_invocation_id,
+                session_service_provider=deps.resolve_session_service,
+            )
+            await deps.conversation().append_run_status_event(
+                session_id=request.SessionId,
+                author=request.AgentId,
+                status="resuming",
+                invocation_id=resume_invocation_id,
+                detail="checkpoint_resume",
+                session_service_provider=deps.resolve_session_service,
+                run_mode=RUN_MODE_BACKGROUND,
+                run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+            )
+            detached = deps.detached_stream_class()(
+                stream_runtime_responses_conversation_turn(
+                    executor=executor,
+                    launch_context=launch_context,
+                    agent_id=request.AgentId,
+                    user_id=user_id,
+                    messages=[],
+                    session_id=request.SessionId,
+                    model=request.Model,
+                    model_metadata=request.ModelMetadata,
+                    model_options=request.ModelOptions,
+                    request_metadata=resume_request_metadata,
+                    custom_metadata=custom_metadata,
+                    include_agentengine_metadata=True,
+                    resume_input=resume_input,
+                    invocation_id=resume_invocation_id,
+                    session_service_provider=deps.resolve_session_service,
+                    run_mode=RUN_MODE_BACKGROUND,
+                ),
+                invocation_id=resume_invocation_id,
+                session_id=request.SessionId,
+                run_mode=RUN_MODE_BACKGROUND,
+                run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+            )
+        except Exception:
+            if resume_key:
+                _clear_detached_resume_key(
+                    get_state().stream_registry, resume_invocation_id, resume_key
+                )
+            raise
+        if resume_key:
+            registry = detached._registry
+            registry.resume_keys_by_invocation[resume_invocation_id] = resume_key
+            registry.active_resume_invocation_by_key[resume_key] = resume_invocation_id
+            detached._task.add_done_callback(
+                lambda _task: _clear_detached_resume_key(registry, resume_invocation_id, resume_key)
+            )
+        return _action_response(
+            "ResumeRun",
+            {
+                "SessionId": request.SessionId,
+                "RunId": str(request.RunId),
+                "CheckpointId": str(request.CheckpointId),
+                "ResumeAttemptId": str(resume_input["resume_attempt_id"]),
+                "InvocationId": resume_invocation_id,
+                "Status": "resuming",
+                "Background": True,
+                "SubscribeUrl": (
+                    "/agentengine/api/v1/SubscribeRunEvents"
+                    f"?SessionId={request.SessionId}&InvocationId={resume_invocation_id}"
+                ),
+            },
+        )
 
     if request.Stream:
         resume_invocation_id = str(request.InvocationId or resume_input["resume_attempt_id"])
         resume_key = _detached_resume_key_from_input(request.SessionId, resume_input)
-        _reject_if_detached_resume_active(resume_key)
+        await _claim_detached_resume_key(resume_key, resume_invocation_id, pascal_case_detail=True)
         # 与 RunAgent Background 同款：返回 SSE 前同步落 resuming 起始事件。
         # detached turn 的首个事件要等流被消费才写；UI 拿到响应头会立刻调
         # SubscribeRunEvents，其 _session_contains_invocation 校验若抢在首次写入前
         # 会误判 409 "InvocationId does not belong to SessionId"。
         # append_run_status_event 按 (invocation_id, status) 幂等，turn 内的补写会去重。
-        await deps.conversation().append_run_status_event(
-            session_id=request.SessionId,
-            author=request.AgentId,
-            status="resuming",
-            invocation_id=resume_invocation_id,
-            detail="checkpoint_resume",
-            session_service_provider=deps.resolve_session_service,
-            run_mode=RUN_MODE_BACKGROUND,
-            run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
-        )
-        return deps.detached_streaming_response(
-            stream_runtime_responses_conversation_turn(
-                executor=executor,
-                launch_context=launch_context,
-                agent_id=request.AgentId,
-                user_id=user_id,
-                messages=[],
+        try:
+            await deps.conversation().append_run_status_event(
                 session_id=request.SessionId,
-                model=request.Model,
-                model_metadata=request.ModelMetadata,
-                model_options=request.ModelOptions,
-                request_metadata=resume_request_metadata,
-                custom_metadata=custom_metadata,
-                include_agentengine_metadata=True,
-                resume_input=resume_input,
+                author=request.AgentId,
+                status="resuming",
                 invocation_id=resume_invocation_id,
+                detail="checkpoint_resume",
                 session_service_provider=deps.resolve_session_service,
                 run_mode=RUN_MODE_BACKGROUND,
-            ),
-            invocation_id=resume_invocation_id,
-            resume_key=resume_key,
-            run_mode=RUN_MODE_BACKGROUND,
-            run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
-        )
+                run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+            )
+            return deps.detached_streaming_response(
+                stream_runtime_responses_conversation_turn(
+                    executor=executor,
+                    launch_context=launch_context,
+                    agent_id=request.AgentId,
+                    user_id=user_id,
+                    messages=[],
+                    session_id=request.SessionId,
+                    model=request.Model,
+                    model_metadata=request.ModelMetadata,
+                    model_options=request.ModelOptions,
+                    request_metadata=resume_request_metadata,
+                    custom_metadata=custom_metadata,
+                    include_agentengine_metadata=True,
+                    resume_input=resume_input,
+                    invocation_id=resume_invocation_id,
+                    session_service_provider=deps.resolve_session_service,
+                    run_mode=RUN_MODE_BACKGROUND,
+                ),
+                invocation_id=resume_invocation_id,
+                session_id=request.SessionId,
+                resume_key=resume_key,
+                run_mode=RUN_MODE_BACKGROUND,
+                run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+            )
+        except Exception:
+            if resume_key:
+                _clear_detached_resume_key(
+                    get_state().stream_registry, resume_invocation_id, resume_key
+                )
+            raise
 
     response_id = f"resp_{uuid.uuid4().hex}"
     resolved_session_id, result = await invoke_runtime_conversation_once(
@@ -259,6 +412,63 @@ async def resume_run_action(request: ResumeRunActionRequest):
     return _action_response("ResumeRun", payload)
 
 
+def _runner_framework(runner: Any) -> str:
+    detection_type = getattr(getattr(runner, "detection_result", None), "type", None)
+    return str(getattr(detection_type, "value", detection_type) or "").strip().lower()
+
+
+async def _runtime_capability_snapshot(*, force: bool) -> Any:
+    from ksadk.server.factory import get_state
+
+    state = get_state()
+    runner = _resolve_active_runner()
+    wait_timeout = max(0.1, float(os.getenv("KSADK_PERSISTENCE_PROBE_TIMEOUT") or "2"))
+    return await state.persistence_capability.get_snapshot(
+        runner=runner,
+        framework=_runner_framework(runner),
+        status_provider=deps.get_persistence_status,
+        session_service_provider=deps.resolve_session_service,
+        force=force,
+        wait_timeout=wait_timeout,
+    )
+
+
+async def _require_runtime_checkpoint_persistence() -> None:
+    snapshot = await _runtime_capability_snapshot(force=True)
+    if snapshot.resume_supported:
+        return
+    gate = dict(snapshot.persistence_gate)
+    checkpoint = snapshot.runtime_capabilities.get("Checkpoint") or {}
+    reason_code = str(
+        gate.get("ReasonCode")
+        or (checkpoint.get("ReasonCode") if isinstance(checkpoint, Mapping) else "")
+        or "RUNTIME_CAPABILITY_UNAVAILABLE"
+    )
+    reason = str(
+        gate.get("Reason")
+        or (checkpoint.get("Reason") if isinstance(checkpoint, Mapping) else "")
+        or "Runtime checkpoint persistence is unavailable"
+    )
+    blocked_store = str(gate.get("BlockedStore") or "checkpoint")
+    retryable = reason_code not in {
+        "AUTH_FAILED",
+        "DEPENDENCY_MISSING",
+        "SCHEMA_PERMISSION_DENIED",
+        "LANGGRAPH_FACTORY_REQUIRED",
+        "CHECKPOINTER_NOT_DURABLE",
+    }
+    raise HTTPException(
+        status_code=503,
+        detail={
+            "Code": "runtime_persistence_unavailable",
+            "ReasonCode": reason_code,
+            "Reason": reason,
+            "BlockedStore": blocked_store,
+            "Retryable": retryable,
+        },
+    )
+
+
 @run_router.get("/agentengine/api/v1/SubscribeRunEvents", include_in_schema=False)
 async def subscribe_run_events_action(
     SessionId: str = Query(...),
@@ -266,17 +476,20 @@ async def subscribe_run_events_action(
     AfterSeqId: int = Query(0),
     AgentId: Optional[str] = Query(None),
     UserId: Optional[str] = Query(None),
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
 ):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
     session_id = str(SessionId or "").strip()
     invocation_id = str(InvocationId or "").strip()
     if not session_id or not invocation_id:
         raise HTTPException(status_code=400, detail="SessionId and InvocationId are required")
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_control_session(
         service,
         session_id=session_id,
         agent_id=AgentId,
         user_id=UserId,
+        invocation_identity=invocation_identity,
     )
     if not await _session_contains_invocation(service, session_id, invocation_id):
         raise HTTPException(
@@ -289,6 +502,12 @@ async def subscribe_run_events_action(
         deadline = time.monotonic() + 5 * 60
         last_heartbeat_at = time.monotonic()
         last_terminal_check_at = 0.0
+        if deps.heartbeat_interval() <= 0:
+            # A zero interval explicitly requests an immediate keepalive. Do
+            # this before the first storage poll so a concurrently completed
+            # run cannot make the reconnect response timing-dependent.
+            yield ": heartbeat\n\n"
+            last_heartbeat_at = time.monotonic()
         while True:
             events = await _oldest_unconsumed_session_events(
                 service,

ksadk/server/routes/dependencies.py

@@ -23,6 +23,7 @@ class ServerRouteDependencies:
     detached_stream_class: Callable[[], type[Any]]
     heartbeat_interval: Callable[[], float]
     runtime_app: Callable[[], Any]
+    get_persistence_status: Callable[..., Any] | None = None
 
 
 _dependencies: ServerRouteDependencies | None = None
@@ -74,6 +75,21 @@ def describe_session_backend() -> dict[str, Any]:
     return current().describe_session_backend()
 
 
+async def get_persistence_status(
+    *, framework: str | None = None, use_cache: bool = True
+) -> dict[str, Any]:
+    # App-scoped session routes also run without the legacy global app.
+    provider = _dependencies.get_persistence_status if _dependencies is not None else None
+    if provider is None:
+        from ksadk.sessions.persistence import get_persistence_status as provider
+    try:
+        return dict(await provider(framework=framework, use_cache=use_cache))
+    except TypeError as exc:
+        if "use_cache" not in str(exc):
+            raise
+        return dict(await provider(framework=framework))
+
+
 def resolve_agent_ui_spec() -> dict[str, Any]:
     return current().resolve_agent_ui_spec()
 

ksadk/server/routes/kernel_ingress.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""RunAgent / Responses 入口的 kernel 路径（Phase 1 Task 8 Step 3-5）。
+"""RunAgent / Responses 入口的 kernel 路径（Kernel Task 8 Step 3-5）。
 
 只在 ``kernel_route_active()`` 时启用（灰度 opt-in）；旧 HTTP 行为保持兼容：
 - accepted -> 202、duplicate -> 200、rejected -> 400、unsupported -> 409、
@@ -18,6 +18,8 @@ from fastapi.responses import JSONResponse, StreamingResponse
 
 from ksadk.kernel import ingress
 from ksadk.kernel.contracts import AgentControlReceipt
+from ksadk.runtime_context import PlatformIdentityContext
+from ksadk.sessions.invocation_identity import identity_owner_payload
 
 logger = logging.getLogger(__name__)
 
@@ -35,6 +37,7 @@ async def _kernel_submit(
     correlation_ref: str | None,
     source_kind: str,
     runtime_options: dict[str, Any] | None = None,
+    invocation_identity: PlatformIdentityContext | None = None,
 ) -> tuple[AgentControlReceipt, ingress.TrustedRuntimeContext]:
     trusted = ingress.trusted_context(
         source_kind=source_kind,
@@ -60,6 +63,11 @@ async def _kernel_submit(
         **({correlation_kwarg: correlation_ref} if correlation_ref else {}),
         **({"runtime_options": runtime_options} if runtime_options else {}),
     )
+    owner = identity_owner_payload(invocation_identity)
+    if owner:
+        command = command.model_copy(
+            update={"payload": {**dict(command.payload), "invocation_identity": owner}}
+        )
     receipt = await ingress.submit_command(command, permit=trusted.permit)
     return receipt, trusted