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

ksadk/server/routes/sessions.py

@@ -2,13 +2,27 @@
 
 from __future__ import annotations
 
+import os
 from collections.abc import Mapping
 from typing import Any
 
-from fastapi import HTTPException
+from fastapi import Depends, HTTPException
 
+from ksadk.conversations.runtime_persistence import (
+    ensure_conversation_session,
+    require_conversation_session,
+)
+from ksadk.runtime.executor import project_legacy_runtime_capabilities
+from ksadk.runtime_context import PlatformIdentityContext
 from ksadk.server.factory import get_runtime_execution, get_state
 from ksadk.sessions import SessionEvent
+from ksadk.sessions.base import CheckpointEventQuery, SessionEventQuery
+from ksadk.sessions.errors import CheckpointScanRestartRequired, SessionBackendUnavailable
+from ksadk.sessions.invocation_identity import (
+    bind_or_validate_session_identity,
+    identity_can_adopt_any_legacy_user,
+    session_identity_binding_matches,
+)
 from ksadk.tools.gateway import tool_approval_capability
 from ksadk.toolsets import describe_agentengine_tools
 from ksadk_runtime_common.workspace_files import (
@@ -16,6 +30,7 @@ from ksadk_runtime_common.workspace_files import (
     workspace_files_enabled,
 )
 
+from ..invocation_identity import resolve_trusted_invocation_identity
 from . import dependencies as deps
 from .common import (
     _action_response,
@@ -34,10 +49,10 @@ from .models import (
     ListToolReceiptsActionRequest,
     SessionIdRequest,
     UiBootstrapRequest,
-    _event_run_id,
     _runtime_agent_id,
 )
 from .projection import (
+    _apply_adk_only_latest_resumable,
     _apply_checkpoint_resume_audit,
     _apply_latest_checkpoint_policy,
     _checkpoint_event_to_action_payload,
@@ -45,10 +60,9 @@ from .projection import (
     _event_to_action_payload,
     _extend_invocation_after_window,
     _extend_invocation_before_window,
-    _iter_scoped_event_pages,
     _iter_session_event_pages,
-    _record_resume_audit,
     _require_action_session,
+    _resume_audit_by_checkpoint,
     _session_to_action_payload,
     _tool_receipt_event_to_action_payload,
 )
@@ -56,8 +70,91 @@ from .routers import sessions_router, tools_router, ui_bootstrap_router
 from .streaming import _cancel_detached_streams_for_session
 
 
+async def _require_identity_action_session(
+    service: Any,
+    *,
+    session_id: str,
+    agent_id: str | None,
+    user_id: str | None,
+    invocation_identity: PlatformIdentityContext,
+):
+    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,
+    )
+
+
+async def _list_identity_session_metadata(
+    service: Any,
+    *,
+    agent_id: str,
+    user_id: str | None,
+    invocation_identity: PlatformIdentityContext,
+) -> list[Any]:
+    """List bound sessions; only the verified IAM account may adopt legacy rows."""
+
+    if invocation_identity.is_empty:
+        return await service.list_session_metadata(agent_id, user_id)
+    from ksadk.sessions.invocation_identity import identity_native_user_id
+
+    candidate_users: set[str | None] = {identity_native_user_id(invocation_identity)}
+    if identity_can_adopt_any_legacy_user(invocation_identity):
+        candidate_users.add(None)
+    elif (
+        invocation_identity.identity_namespace == "kscloud-iam"
+        and invocation_identity.subject_type == "user"
+    ):
+        candidate_users.add(invocation_identity.subject_id)
+    sessions: list[Any] = []
+    seen: set[str] = set()
+    for candidate_user in candidate_users:
+        for session in await service.list_session_metadata(agent_id, candidate_user):
+            if session.id in seen:
+                continue
+            matches = await session_identity_binding_matches(
+                service=service,
+                session=session,
+                identity=invocation_identity,
+            )
+            if not matches:
+                try:
+                    await bind_or_validate_session_identity(
+                        service=service,
+                        session=session,
+                        identity=invocation_identity,
+                        requested_user_id=session.user_id,
+                    )
+                except HTTPException:
+                    matches = False
+                else:
+                    matches = True
+            if matches:
+                sessions.append(session)
+                seen.add(session.id)
+    sessions.sort(
+        key=lambda item: (item.updated_at, item.created_at, item.id),
+        reverse=True,
+    )
+    return sessions
+
+
 @ui_bootstrap_router.post("/agentengine/api/v1/GetAgentUiBootstrap")
-async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
+async def get_agent_ui_bootstrap(
+    request: UiBootstrapRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     state = get_state()
     executor, launch_context = get_runtime_execution()
     detection = launch_context.detection
@@ -66,12 +163,34 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
     framework = launch_context.runtime_type.strip().lower()
     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)
+    capability_subject = executor.capability_subject(launch_context)
+    if capability_subject is not None:
+        wait_timeout = max(0.1, float(os.getenv("KSADK_PERSISTENCE_PROBE_TIMEOUT") or "2"))
+        capability_snapshot = await state.persistence_capability.get_snapshot(
+            runner=capability_subject,
+            framework=framework,
+            status_provider=deps.get_persistence_status,
+            session_service_provider=deps.resolve_session_service,
+            wait_timeout=wait_timeout,
+        )
+        persistence = dict(capability_snapshot.session_persistence)
+        checkpoint_persistence = dict(capability_snapshot.checkpoint_persistence)
+        runtime_capabilities = dict(capability_snapshot.runtime_capabilities)
+        runtime_capability_matrix = executor.capability_matrix(launch_context)
+    else:
+        runtime_capability_matrix = executor.capability_matrix(launch_context)
+        persistence_status = dict(await deps.get_persistence_status(framework=framework))
+        if isinstance(persistence_status.get("Session"), Mapping):
+            persistence = dict(persistence_status["Session"])
+            checkpoint_persistence = dict(persistence_status.get("Checkpoint") or {})
+        else:
+            persistence = persistence_status
+            checkpoint_persistence = dict(persistence_status)
+        runtime_capabilities = project_legacy_runtime_capabilities(
+            executor.native_capabilities(launch_context), runtime_capability_matrix
+        )
     resume_capability = (
-        runtime_capabilities.get("ResumeRun")
-        if isinstance(runtime_capabilities, Mapping)
-        else None
+        runtime_capabilities.get("ResumeRun") if isinstance(runtime_capabilities, Mapping) else None
     )
     resume_capability = resume_capability if isinstance(resume_capability, Mapping) else {}
     checkpoint_capability = (
@@ -83,9 +202,7 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
         checkpoint_capability if isinstance(checkpoint_capability, Mapping) else {}
     )
     cancel_capability = (
-        runtime_capabilities.get("CancelRun")
-        if isinstance(runtime_capabilities, Mapping)
-        else None
+        runtime_capabilities.get("CancelRun") if isinstance(runtime_capabilities, Mapping) else None
     )
     cancel_capability = cancel_capability if isinstance(cancel_capability, Mapping) else {}
     checkpoint_resume_capability = {
@@ -148,6 +265,8 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
                 "Thinking": True,
                 "StopRun": cancel_run_supported,
                 "ResumeRun": checkpoint_resume_supported,
+                "Persistence": persistence,
+                "CheckpointPersistence": checkpoint_persistence,
                 "RuntimeCapabilities": runtime_capabilities,
                 "RuntimeCapabilityMatrix": runtime_capability_matrix,
                 "CheckpointResumeCapability": checkpoint_resume_capability,
@@ -161,7 +280,7 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
                 },
                 "MCP": False,
                 "HostedRuntime": False,
-                "NativeTerminal": _build_native_terminal_capability(framework),
+                "NativeTerminal": _build_native_terminal_capability(framework, invocation_identity),
                 "BuiltinTools": describe_agentengine_tools(),
             },
             "WorkspaceFiles": build_workspace_files_bootstrap(enabled=workspace_enabled),
@@ -193,22 +312,49 @@ async def get_agent_ui_bootstrap(request: UiBootstrapRequest):
 
 
 @sessions_router.post("/agentengine/api/v1/CreateSession")
-async def create_session_action(request: CreateSessionActionRequest):
-    session = await _ensure_session(request.AgentId, request.UserId or "user", request.SessionId)
+async def create_session_action(
+    request: CreateSessionActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    if invocation_identity.is_empty:
+        session = await _ensure_session(
+            request.AgentId, request.UserId or "user", request.SessionId
+        )
+    else:
+        session = await ensure_conversation_session(
+            agent_id=request.AgentId,
+            user_id=request.UserId or "user",
+            session_id=request.SessionId,
+            session_service_provider=deps.resolve_session_service,
+            invocation_identity=invocation_identity,
+        )
     return _action_response("CreateSession", {"Session": await _session_to_action_payload(session)})
 
 
 @sessions_router.post("/agentengine/api/v1/ListSessions")
-async def list_sessions_action(request: ListSessionsActionRequest):
+async def list_sessions_action(
+    request: ListSessionsActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     service = deps.resolve_session_service()
     offset = (request.Page - 1) * request.PageSize
-    sessions = await service.list_sessions(
-        request.AgentId,
-        request.UserId,
-        offset=offset,
-        limit=request.PageSize,
-    )
-    total = await service.count_sessions(request.AgentId, request.UserId)
+    if invocation_identity.is_empty:
+        sessions = await service.list_sessions(
+            request.AgentId,
+            request.UserId,
+            offset=offset,
+            limit=request.PageSize,
+        )
+        total = await service.count_sessions(request.AgentId, request.UserId)
+    else:
+        all_sessions = await _list_identity_session_metadata(
+            service,
+            agent_id=request.AgentId,
+            user_id=request.UserId,
+            invocation_identity=invocation_identity,
+        )
+        total = len(all_sessions)
+        sessions = all_sessions[offset : offset + request.PageSize]
     session_payloads = [await _session_to_action_payload(session) for session in sessions]
     return _action_response(
         "ListSessions",
@@ -225,13 +371,17 @@ async def list_sessions_action(request: ListSessionsActionRequest):
 
 
 @sessions_router.post("/agentengine/api/v1/GetSession")
-async def get_session_action(request: SessionIdRequest):
+async def get_session_action(
+    request: SessionIdRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     service = deps.resolve_session_service()
-    session = await _require_action_session(
+    session = await _require_identity_action_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
     hydrated = await _hydrate_session(session)
     if hydrated is None:
@@ -240,13 +390,17 @@ async def get_session_action(request: SessionIdRequest):
 
 
 @sessions_router.post("/agentengine/api/v1/DeleteSession")
-async def delete_session_action(request: SessionIdRequest):
+async def delete_session_action(
+    request: SessionIdRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_identity_action_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
     await _cancel_detached_streams_for_session(request.SessionId)
     deleted = await service.delete_session(request.SessionId)
@@ -256,21 +410,66 @@ async def delete_session_action(request: SessionIdRequest):
 
 
 @sessions_router.post("/agentengine/api/v1/ListSessionEvents")
-async def list_session_events_action(request: ListSessionEventsActionRequest):
+async def list_session_events_action(
+    request: ListSessionEventsActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     _executor, launch_context = get_runtime_execution()
     service = deps.resolve_session_service()
     session_id = str(request.SessionId or "").strip()
+    event_types = request.EventTypes or None
+    checkpoint_ids = request.CheckpointIds or None
     if not session_id:
         # 未传 SessionId：返回该 agent 全部会话的事件（存储层跨会话查询，真分页无截断；
         # seq 游标是会话内序号，跨会话模式下不适用，直接忽略）
         agent_id = str(request.AgentId or "").strip() or _runtime_agent_id(launch_context)
-        events = await service.get_events_for_agent(
-            agent_id,
-            user_id=request.UserId,
-            offset=request.Offset,
+        session_ids = None
+        if request.UserId is not None or not invocation_identity.is_empty:
+            session_ids = [
+                session.id
+                for session in await _list_identity_session_metadata(
+                    service,
+                    agent_id=agent_id,
+                    user_id=request.UserId,
+                    invocation_identity=invocation_identity,
+                )
+            ]
+        if not invocation_identity.is_empty and not session_ids:
+            return _action_response(
+                "ListSessionEvents",
+                {
+                    "Events": [],
+                    "Total": 0,
+                    "Offset": request.Offset or 0,
+                    "Limit": request.Limit or 0,
+                    "AfterSeqId": request.AfterSeqId,
+                    "BeforeSeqId": request.BeforeSeqId,
+                    "CheckpointIds": request.CheckpointIds,
+                    "EventTypes": request.EventTypes,
+                    "ScopedAllSessions": True,
+                },
+            )
+        query = SessionEventQuery(
+            session_ids=session_ids,
+            agent_id=agent_id,
+            offset=request.Offset or 0,
             limit=request.Limit,
+            event_types=event_types,
+            checkpoint_ids=checkpoint_ids,
+        )
+        events = await service.query_events(query)
+        total = await service.count_event_query(
+            SessionEventQuery(
+                session_ids=session_ids,
+                agent_id=agent_id,
+                event_types=event_types,
+                checkpoint_ids=checkpoint_ids,
+            )
+        )
+        events.sort(
+            key=lambda event: (event.timestamp, event.session_id, event.seq_id, event.id),
+            reverse=True,
         )
-        total = await service.count_events_for_agent(agent_id, user_id=request.UserId)
         return _action_response(
             "ListSessionEvents",
             {
@@ -280,26 +479,42 @@ async def list_session_events_action(request: ListSessionEventsActionRequest):
                 "Limit": request.Limit if request.Limit is not None else len(events),
                 "AfterSeqId": request.AfterSeqId,
                 "BeforeSeqId": request.BeforeSeqId,
+                "CheckpointIds": request.CheckpointIds,
+                "EventTypes": request.EventTypes,
                 "ScopedAllSessions": True,
             },
         )
-    await _require_action_session(
+    await _require_identity_action_session(
         service,
         session_id=session_id,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
-    events = await service.get_events(
-        session_id,
-        offset=request.Offset,
+    query = SessionEventQuery(
+        session_ids=[session_id],
+        agent_id=request.AgentId,
+        offset=request.Offset or 0,
         limit=request.Limit,
         after_seq_id=request.AfterSeqId,
         before_seq_id=request.BeforeSeqId,
+        event_types=event_types,
+        checkpoint_ids=checkpoint_ids,
     )
-    total = await service.count_events(
-        session_id,
-        after_seq_id=request.AfterSeqId,
-        before_seq_id=request.BeforeSeqId,
+    events = await service.query_events(query)
+    total = await service.count_event_query(
+        SessionEventQuery(
+            session_ids=[session_id],
+            agent_id=request.AgentId,
+            after_seq_id=request.AfterSeqId,
+            before_seq_id=request.BeforeSeqId,
+            event_types=event_types,
+            checkpoint_ids=checkpoint_ids,
+        )
+    )
+    events.sort(
+        key=lambda event: (event.timestamp, event.session_id, event.seq_id, event.id),
+        reverse=True,
     )
     return _action_response(
         "ListSessionEvents",
@@ -310,20 +525,26 @@ async def list_session_events_action(request: ListSessionEventsActionRequest):
             "Limit": request.Limit if request.Limit is not None else len(events),
             "AfterSeqId": request.AfterSeqId,
             "BeforeSeqId": request.BeforeSeqId,
+            "CheckpointIds": request.CheckpointIds,
+            "EventTypes": request.EventTypes,
         },
     )
 
 
 @sessions_router.post("/agentengine/api/v1/ListSessionMessages")
-async def list_session_messages_action(request: ListSessionMessagesActionRequest):
+async def list_session_messages_action(
+    request: ListSessionMessagesActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     from ksadk.conversations.message_projection import project_session_messages
 
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_identity_action_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
     total_events = await service.count_events(
         request.SessionId,
@@ -352,6 +573,7 @@ async def list_session_messages_action(request: ListSessionMessagesActionRequest
             include_reasoning=request.IncludeReasoning,
             include_tool_events=request.IncludeToolEvents,
             include_attachments=request.IncludeAttachments,
+            session_id=request.SessionId,
         )
 
     serialized_events, messages = project(events)
@@ -470,132 +692,263 @@ def _count_resumable_checkpoints(checkpoints: list[dict[str, Any]]) -> int:
     return resumable
 
 
-async def _list_checkpoints_payload(request: ListSessionCheckpointsActionRequest) -> dict[str, Any]:
-    service = deps.resolve_session_service()
-    run_id_filter = str(request.RunId or "").strip()
-    framework_filter = str(request.Framework or "").strip().lower()
+def _normalize_action_id_list(value: list[str] | str | None) -> list[str]:
+    values = [value] if isinstance(value, str) else list(value or [])
+    return list(dict.fromkeys(str(item).strip() for item in values if str(item).strip()))
 
-    session_id = str(request.SessionId or "").strip()
-    if session_id:
-        await _require_action_session(
-            service,
-            session_id=session_id,
-            agent_id=request.AgentId,
-            user_id=request.UserId,
-        )
 
-    audit_by_session: dict[str, dict[tuple[str, str], dict[str, Any]]] = {}
+def _is_checkpoint_resumable(checkpoint: Mapping[str, Any]) -> bool:
+    if checkpoint.get("IsResumable") is not True or checkpoint.get("IsTerminal") is True:
+        return False
+    if checkpoint.get("ReplayAllowed") is False:
+        return False
+    checkpoint_status = str(checkpoint.get("CheckpointStatus") or "").strip().lower()
+    resume_status = str(checkpoint.get("ResumeStatus") or "").strip().lower()
+    return (
+        checkpoint_status not in {"expired", "disabled", "terminal"} and resume_status != "disabled"
+    )
+
+
+async def _list_checkpoints_payload_legacy_filtered(
+    request: ListSessionCheckpointsActionRequest,
+    session_ids: list[str],
+    checkpoint_ids: list[str],
+) -> dict[str, Any]:
+    if len(session_ids) != 1:
+        raise HTTPException(
+            status_code=501, detail="Backend does not support multi-session checkpoints"
+        )
+    service = deps.resolve_session_service()
+    events = await service.get_events(session_ids[0])
+    audit = _resume_audit_by_checkpoint(events)
     latest_by_session_run: dict[tuple[str, str], int] = {}
-    run_seen = not run_id_filter
-    async for page in _iter_scoped_event_pages(
-        service,
-        session_id=session_id or None,
-        agent_id=request.AgentId,
-        user_id=request.UserId,
-    ):
-        for event in page:
-            if run_id_filter and _event_run_id(event) == run_id_filter:
-                run_seen = True
-            _record_resume_audit(audit_by_session, event)
-            checkpoint = _checkpoint_event_to_action_payload(event)
-            if checkpoint is None or not (checkpoint.get("Metadata") or {}).get(
-                "only_latest_resumable"
-            ):
-                continue
+    for event in events:
+        checkpoint = _checkpoint_event_to_action_payload(event)
+        if checkpoint is not None and (checkpoint.get("Metadata") or {}).get(
+            "only_latest_resumable"
+        ):
             key = (event.session_id, str(checkpoint.get("RunId") or ""))
             latest_by_session_run[key] = max(
-                latest_by_session_run.get(key, 0),
-                int(checkpoint.get("SeqId") or 0),
+                latest_by_session_run.get(key, 0), int(checkpoint.get("SeqId") or 0)
             )
-    if session_id and not run_seen:
-        raise HTTPException(status_code=409, detail="RunId does not belong to SessionId")
-
-    def project_checkpoint(event: SessionEvent) -> dict[str, Any] | None:
+    checkpoints: list[dict[str, Any]] = []
+    resume_status_filter = set(request.ResumeStatus)
+    resume_type_filter = set(request.ResumeTypes)
+    for event in events:
         checkpoint = _checkpoint_event_to_action_payload(event)
         if checkpoint is None:
-            return None
-        checkpoint = _apply_checkpoint_resume_audit(
-            checkpoint,
-            audit_by_session.get(event.session_id, {}),
-        )
+            continue
+        checkpoint = _apply_checkpoint_resume_audit(checkpoint, audit)
         checkpoint = _apply_latest_checkpoint_policy(
-            checkpoint,
-            latest_by_session_run,
-            session_id=event.session_id,
+            checkpoint, latest_by_session_run, session_id=event.session_id
         )
-        if run_id_filter and checkpoint["RunId"] != run_id_filter:
-            return None
-        if framework_filter and str(checkpoint["Framework"]).lower() != framework_filter:
-            return None
-        return checkpoint
+        if request.RunId and checkpoint["RunId"] != str(request.RunId):
+            continue
+        if checkpoint_ids and checkpoint["CheckpointId"] not in checkpoint_ids:
+            continue
+        if (
+            request.Framework
+            and str(checkpoint["Framework"]).lower() != str(request.Framework).lower()
+        ):
+            continue
+        if (
+            resume_status_filter
+            and str(checkpoint.get("ResumeStatus") or "").lower() not in resume_status_filter
+        ):
+            continue
+        if (
+            resume_type_filter
+            and str(checkpoint.get("Scope") or "unknown").lower() not in resume_type_filter
+        ):
+            continue
+        checkpoints.append(checkpoint)
+    checkpoints = _apply_adk_only_latest_resumable(checkpoints)
+    resumable_total = sum(_is_checkpoint_resumable(item) for item in checkpoints)
+    if request.OnlyResumable:
+        checkpoints = [item for item in checkpoints if _is_checkpoint_resumable(item)]
+    offset = int(request.Offset or 0)
+    checkpoints.sort(
+        key=lambda item: (item["Timestamp"], item["SessionId"], item["SeqId"]),
+        reverse=True,
+    )
+    checkpoints = checkpoints[offset : offset + request.Limit]
+    return {
+        "Checkpoints": checkpoints,
+        "Total": len(checkpoints),
+        "ResumableTotal": resumable_total,
+        "HasResumableCheckpoint": resumable_total > 0,
+        "SessionId": session_ids,
+        "CheckpointId": checkpoint_ids,
+        "ResumeStatus": request.ResumeStatus,
+        "ResumeTypes": request.ResumeTypes,
+        "Offset": offset,
+        "Limit": request.Limit,
+    }
 
-    total = 0
-    resumable_total = 0
-    async for page in _iter_scoped_event_pages(
-        service,
-        session_id=session_id or None,
-        agent_id=request.AgentId,
-        user_id=request.UserId,
-    ):
-        for event in page:
-            checkpoint = project_checkpoint(event)
-            if checkpoint is None:
-                continue
-            if checkpoint.get("IsResumable") is True:
-                resumable_total += 1
-            if request.OnlyResumable and checkpoint.get("IsResumable") is not True:
-                continue
-            total += 1
 
-    offset = int(request.Offset or 0)
-    limit = int(request.Limit)
-    window_end = max(total - offset, 0)
-    window_start = max(window_end - limit, 0)
-    checkpoints: list[dict[str, Any]] = []
-    filtered_index = 0
-    async for page in _iter_scoped_event_pages(
-        service,
-        session_id=session_id or None,
+async def _list_checkpoints_payload(
+    request: ListSessionCheckpointsActionRequest,
+    invocation_identity: PlatformIdentityContext,
+) -> dict[str, Any]:
+    service = deps.resolve_session_service()
+    session_ids = _normalize_action_id_list(request.SessionId)
+    checkpoint_ids = _normalize_action_id_list(request.CheckpointId)
+    if session_ids:
+        for session_id in session_ids:
+            await _require_identity_action_session(
+                service,
+                session_id=session_id,
+                agent_id=request.AgentId,
+                user_id=request.UserId,
+                invocation_identity=invocation_identity,
+            )
+    elif request.UserId is not None or not invocation_identity.is_empty:
+        session_ids = [
+            session.id
+            for session in await _list_identity_session_metadata(
+                service,
+                agent_id=request.AgentId,
+                user_id=request.UserId,
+                invocation_identity=invocation_identity,
+            )
+        ]
+    if not invocation_identity.is_empty and not session_ids:
+        return {
+            "Checkpoints": [],
+            "Total": 0,
+            "ResumableTotal": 0,
+            "HasResumableCheckpoint": False,
+            "SessionId": [],
+            "CheckpointId": checkpoint_ids,
+            "ResumeStatus": request.ResumeStatus,
+            "ResumeTypes": request.ResumeTypes,
+            "Offset": int(request.Offset or 0),
+            "Limit": request.Limit,
+        }
+    query = CheckpointEventQuery(
+        session_ids=session_ids or None,
         agent_id=request.AgentId,
-        user_id=request.UserId,
-    ):
-        for event in page:
-            checkpoint = project_checkpoint(event)
-            if checkpoint is None:
-                continue
-            if request.OnlyResumable and checkpoint.get("IsResumable") is not True:
+        checkpoint_ids=checkpoint_ids or None,
+        run_id=str(request.RunId or "").strip() or None,
+        framework=str(request.Framework or "").strip().lower() or None,
+        limit=50,
+    )
+    resume_status_filter = set(request.ResumeStatus)
+    resume_type_filter = set(request.ResumeTypes)
+    offset = int(request.Offset or 0)
+    for attempt in range(2):
+        total = 0
+        resumable_total = 0
+        checkpoints: list[dict[str, Any]] = []
+        batches = service.iter_checkpoint_event_chunks(query)
+        try:
+            async for batch in batches:
+                chunk = [
+                    checkpoint
+                    for event in batch
+                    if (checkpoint := _checkpoint_event_to_action_payload(event)) is not None
+                    and (
+                        not checkpoint_ids
+                        or str(checkpoint.get("CheckpointId") or "") in checkpoint_ids
+                    )
+                    and (query.run_id is None or str(checkpoint.get("RunId") or "") == query.run_id)
+                    and (
+                        query.framework is None
+                        or str(checkpoint.get("Framework") or "").lower() == query.framework
+                    )
+                ]
+                keys = [
+                    (
+                        str(checkpoint["SessionId"]),
+                        str(checkpoint["RunId"]),
+                        str(checkpoint["CheckpointId"]),
+                    )
+                    for checkpoint in chunk
+                ]
+                stats = await service.get_checkpoint_stats(keys)
+                for checkpoint in chunk:
+                    checkpoint = _apply_checkpoint_resume_audit(
+                        checkpoint, stats.get("audits") or {}
+                    )
+                    checkpoint = _apply_latest_checkpoint_policy(
+                        checkpoint,
+                        stats.get("latest_seq_ids") or {},
+                        session_id=str(checkpoint.get("SessionId") or ""),
+                    )
+                    if (
+                        resume_status_filter
+                        and str(checkpoint.get("ResumeStatus") or "").strip().lower()
+                        not in resume_status_filter
+                    ):
+                        continue
+                    if (
+                        resume_type_filter
+                        and str(checkpoint.get("Scope") or "unknown").strip().lower()
+                        not in resume_type_filter
+                    ):
+                        continue
+                    resumable_total += int(_is_checkpoint_resumable(checkpoint))
+                    if request.OnlyResumable and not _is_checkpoint_resumable(checkpoint):
+                        continue
+                    checkpoints.append(checkpoint)
+                    total += 1
+        except CheckpointScanRestartRequired as exc:
+            if attempt == 0:
                 continue
-            if window_start <= filtered_index < window_end:
-                checkpoints.append(checkpoint)
-            filtered_index += 1
-            if filtered_index >= window_end:
-                break
-        if filtered_index >= window_end:
-            break
-
+            raise SessionBackendUnavailable(
+                "Checkpoint backend changed repeatedly during one request"
+            ) from exc
+        except NotImplementedError:
+            return await _list_checkpoints_payload_legacy_filtered(
+                request, session_ids, checkpoint_ids
+            )
+        finally:
+            close = getattr(batches, "aclose", None)
+            if callable(close):
+                await close()
+        break
+    checkpoints.sort(
+        key=lambda item: (item["Timestamp"], item["SessionId"], item["SeqId"]),
+        reverse=True,
+    )
+    checkpoints = checkpoints[offset : offset + int(request.Limit)]
     return {
         "Checkpoints": checkpoints,
         "Total": total,
         "ResumableTotal": resumable_total,
         "HasResumableCheckpoint": resumable_total > 0,
+        "SessionId": session_ids,
+        "CheckpointId": checkpoint_ids,
+        "ResumeStatus": request.ResumeStatus,
+        "ResumeTypes": request.ResumeTypes,
         "Offset": offset,
-        "Limit": limit,
+        "Limit": request.Limit,
     }
 
 
 @sessions_router.post("/agentengine/api/v1/ListSessionCheckpoints")
-async def list_session_checkpoints_action(request: ListSessionCheckpointsActionRequest):
-    return _action_response("ListSessionCheckpoints", await _list_checkpoints_payload(request))
+async def list_session_checkpoints_action(
+    request: ListSessionCheckpointsActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    return _action_response(
+        "ListSessionCheckpoints",
+        await _list_checkpoints_payload(request, invocation_identity),
+    )
 
 
 @tools_router.post("/agentengine/api/v1/ListToolReceipts")
-async def list_tool_receipts_action(request: ListToolReceiptsActionRequest):
+async def list_tool_receipts_action(
+    request: ListToolReceiptsActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_identity_action_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
 
     run_id_filter = str(request.RunId or "").strip()