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

ksadk/server/routes/control.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import time
 import uuid
 from collections.abc import AsyncIterator, Mapping
@@ -20,7 +21,7 @@ from ksadk.conversations.run_kinds import (
 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 ksadk.server.factory import get_runtime_execution, get_state
 
 from . import dependencies as deps
 from .checkpoint_resolution import _find_session_checkpoint
@@ -47,11 +48,23 @@ 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,
 )
 
 
+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):
     service = deps.resolve_session_service()
@@ -96,17 +109,16 @@ 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},
     )
 
 
@@ -131,7 +143,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 +170,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 +198,141 @@ 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,
     }
 
+    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 +364,65 @@ 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(...),

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,20 @@ 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]:
+    provider = current().get_persistence_status
+    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/models.py

@@ -7,7 +7,7 @@ from datetime import datetime, timezone
 from typing import Any, Dict, List, Mapping, Optional
 
 from fastapi import HTTPException
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_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
@@ -58,7 +58,7 @@ class ListSessionsActionRequest(BaseModel):
     AgentId: str
     UserId: Optional[str] = None
     Page: int = Field(1, ge=1)
-    PageSize: int = Field(20, ge=1, le=200)
+    PageSize: int = Field(20, ge=1, le=1000)
 
 
 class SessionIdRequest(BaseModel):
@@ -71,11 +71,30 @@ class ListSessionEventsActionRequest(BaseModel):
     AgentId: Optional[str] = None
     SessionId: Optional[str] = None
     UserId: Optional[str] = None
+    CheckpointIds: list[str] = Field(default_factory=list)
+    EventTypes: list[str] = Field(default_factory=list)
     Offset: Optional[int] = Field(None, ge=0)
     Limit: int = Field(200, ge=1, le=2000)
     AfterSeqId: Optional[int] = Field(None, ge=0)
     BeforeSeqId: Optional[int] = Field(None, ge=1)
 
+    @field_validator("CheckpointIds", "EventTypes", mode="before")
+    @classmethod
+    def normalize_event_filters(cls, value: Any) -> list[str]:
+        if value is None:
+            return []
+        values = value if isinstance(value, list) else [value]
+        normalized = [str(item).strip() for item in values if str(item).strip()]
+        return list(dict.fromkeys(normalized))
+
+    @model_validator(mode="after")
+    def validate_cursor_scope(self):
+        if self.SessionId is None and (
+            self.AfterSeqId is not None or self.BeforeSeqId is not None
+        ):
+            raise ValueError("Seq cursors require SessionId")
+        return self
+
 
 class ListSessionMessagesActionRequest(BaseModel):
     AgentId: Optional[str] = None
@@ -91,13 +110,36 @@ class ListSessionMessagesActionRequest(BaseModel):
 
 class ListSessionCheckpointsActionRequest(BaseModel):
     AgentId: str
-    SessionId: Optional[str] = None
+    SessionId: list[str] | str | None = None
     UserId: Optional[str] = None
+    CheckpointId: list[str] | str | None = None
     RunId: Optional[str] = None
     OnlyResumable: bool = False
     Framework: Optional[str] = None
+    ResumeStatus: list[str] = Field(default_factory=list)
+    ResumeTypes: list[str] = Field(default_factory=list)
     Offset: Optional[int] = Field(None, ge=0)
-    Limit: int = Field(100, ge=1, le=500)
+    Limit: int = Field(100, ge=1, le=1000)
+
+    @field_validator("SessionId", "CheckpointId", mode="before")
+    @classmethod
+    def normalize_id_filters(cls, value: Any) -> list[str] | str | None:
+        if value is None:
+            return None
+        values = value if isinstance(value, list) else [value]
+        normalized = [str(item).strip() for item in values if str(item).strip()]
+        if not normalized:
+            return None
+        return normalized if isinstance(value, list) else normalized[0]
+
+    @field_validator("ResumeStatus", "ResumeTypes", mode="before")
+    @classmethod
+    def normalize_resume_filters(cls, value: Any) -> list[str]:
+        if value is None:
+            return []
+        values = value if isinstance(value, list) else [value]
+        normalized = [str(item).strip().lower() for item in values if str(item).strip()]
+        return list(dict.fromkeys(normalized))
 
 
 class ListToolReceiptsActionRequest(BaseModel):
@@ -119,6 +161,7 @@ class ResumeRunActionRequest(BaseModel):
     ResumeAttemptId: Optional[str] = None
     InvocationId: Optional[str] = None
     Stream: bool = False
+    Background: bool = False
     Model: Optional[str] = None
     ModelMetadata: Optional[Dict[str, Any]] = None
     ModelOptions: Optional[Dict[str, Any]] = None