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

ksadk/server/routes/checkpoint_resolution.py

@@ -2,19 +2,27 @@
 
 from __future__ import annotations
 
+import asyncio
+import json
 import uuid
-from collections.abc import Mapping
+from collections.abc import AsyncIterator, Mapping
+from contextlib import aclosing
 from typing import Any
 
 from fastapi import HTTPException
 
-from ksadk.sessions import SessionEvent
+from ksadk.sessions import Session, SessionEvent
+from ksadk.sessions.errors import (
+    CheckpointLookupTimeout,
+    HistoryProjectionBudgetExceeded,
+    HistoryReloadRequired,
+)
+from ksadk.sessions.db_budget import session_db_budget
 
 from .projection import (
     _apply_checkpoint_resume_audit,
     _apply_latest_checkpoint_policy,
     _checkpoint_event_to_action_payload,
-    _iter_session_event_pages,
     _record_resume_audit,
 )
 
@@ -25,26 +33,67 @@ async def _find_session_checkpoint(
     session_id: str,
     run_id: str,
     checkpoint_id: str,
+    expected_session: Session | None = None,
 ) -> dict[str, Any] | None:
     audit_by_session: dict[str, dict[tuple[str, str], dict[str, Any]]] = {}
     latest_by_session_run: dict[tuple[str, str], int] = {}
     candidate_event: SessionEvent | None = None
-    async for page in _iter_session_event_pages(service, session_id):
-        for event in page:
-            _record_resume_audit(audit_by_session, event)
-            checkpoint = _checkpoint_event_to_action_payload(event)
-            if checkpoint is None:
-                continue
-            metadata = checkpoint.get("Metadata") or {}
-            checkpoint_run_id = str(checkpoint.get("RunId") or "")
-            if metadata.get("only_latest_resumable"):
-                key = (session_id, checkpoint_run_id)
-                latest_by_session_run[key] = max(
-                    latest_by_session_run.get(key, 0),
-                    int(checkpoint.get("SeqId") or 0),
-                )
-            if checkpoint_run_id == run_id and checkpoint.get("CheckpointId") == checkpoint_id:
-                candidate_event = event
+    scanned = 0
+    size = 0
+
+    async def custom_backend_pages() -> AsyncIterator[list[SessionEvent]]:
+        # Legacy duck-typed services may not inherit BaseSessionService.
+        if expected_session is not None:
+            candidate = await service.get_session_metadata(session_id)
+            if (candidate is None or candidate.agent_id != expected_session.agent_id
+                    or candidate.user_id != expected_session.user_id
+                    or candidate.created_at != expected_session.created_at):
+                raise HistoryReloadRequired("Checkpoint session changed during lookup")
+        events = await service.get_events(session_id)
+        related = sorted(
+            (event for event in events if event.event_type in
+             {"run_checkpoint", "run_resume", "runtime_resume", "continuation.created", "continuation.resumed"}),
+            key=lambda event: (event.seq_id, event.id),
+        )
+        for index in range(0, len(related), 256):
+            yield related[index : index + 256]
+
+    iterator = getattr(service, "iter_resume_related_event_pages", None)
+    pages = (
+        iterator(session_id, page_size=256, expected_session=expected_session)
+        if callable(iterator) else custom_backend_pages()
+    )
+    try:
+        async with asyncio.timeout(session_db_budget().write_operation_seconds):
+            async with aclosing(pages) as fixed_pages:
+                async for page in fixed_pages:
+                    scanned += len(page)
+                    size += sum(
+                        len(json.dumps(event.to_dict(), ensure_ascii=False).encode("utf-8"))
+                        for event in page
+                    )
+                    if scanned > 8192 or size > 16 * 1024 * 1024:
+                        raise HistoryProjectionBudgetExceeded(
+                            "Checkpoint lookup exceeds 8192 related events or 16 MiB"
+                        )
+                    for event in page:
+                        _record_resume_audit(audit_by_session, event)
+                        checkpoint = _checkpoint_event_to_action_payload(event)
+                        if checkpoint is None:
+                            continue
+                        metadata = checkpoint.get("Metadata") or {}
+                        checkpoint_run_id = str(checkpoint.get("RunId") or "")
+                        if metadata.get("only_latest_resumable"):
+                            key = (session_id, checkpoint_run_id)
+                            latest_by_session_run[key] = max(
+                                latest_by_session_run.get(key, 0),
+                                int(checkpoint.get("SeqId") or 0),
+                            )
+                        if (checkpoint_run_id == run_id
+                                and checkpoint.get("CheckpointId") == checkpoint_id):
+                            candidate_event = event
+    except TimeoutError as exc:
+        raise CheckpointLookupTimeout("Checkpoint lookup deadline exceeded") from exc
     if candidate_event is None:
         return None
     checkpoint = _checkpoint_event_to_action_payload(candidate_event)
@@ -76,7 +125,10 @@ async def _resolve_checkpoint_resume_input_from_session(
     if not normalized_session_id:
         raise HTTPException(status_code=400, detail="Checkpoint resume requires session_id")
 
-    session = await service.get_session(normalized_session_id)
+    header = getattr(service, "get_session_header", None)
+    if not callable(header):
+        header = service.get_session_metadata
+    session = await header(normalized_session_id)
     if not session or session.agent_id != agent_id:
         raise HTTPException(status_code=404, detail="Session not found")
 
@@ -92,6 +144,7 @@ async def _resolve_checkpoint_resume_input_from_session(
         session_id=normalized_session_id,
         run_id=run_id,
         checkpoint_id=checkpoint_id,
+        expected_session=session,
     )
     if checkpoint is None:
         raise HTTPException(status_code=404, detail="Checkpoint not found")

ksadk/server/routes/common.py

@@ -16,6 +16,7 @@ from fastapi.responses import FileResponse, Response
 
 from ksadk.conversations.attachments import compact_attachment_result_for_session
 from ksadk.conversations.model_context import normalize_model_metadata
+from ksadk.runtime_context import PlatformIdentityContext
 from ksadk.runtime_state import load_state as load_runtime_state
 from ksadk.server.factory import (
     RuntimeAppState,
@@ -28,6 +29,7 @@ from ksadk.server.terminal_sessions import (
     register_terminal_routes,
 )
 from ksadk.sessions import Session
+from ksadk.sessions.invocation_identity import identity_scope_ref
 from ksadk.sessions.local_service import resolve_local_session_dir
 from ksadk.ui_config import UI_PROFILE_CUSTOM, resolve_ui_config
 from ksadk_runtime_common.workspace_files import (
@@ -35,6 +37,10 @@ from ksadk_runtime_common.workspace_files import (
     workspace_files_enabled,
 )
 
+from ..invocation_identity import (
+    trusted_invocation_identity_from_headers,
+    trusted_invocation_identity_headers,
+)
 from . import dependencies as deps
 from .routers import health_meta_router
 
@@ -92,8 +98,17 @@ _MAX_REFERENCE_TEXT_BYTES = 3_000_000
 _UPLOAD_URI_SCHEME = "ksadk-upload://"
 
 
-def _workspace_root_dir() -> Path:
-    return Path(resolve_local_session_dir()) / "workspace"
+def _workspace_root_dir(
+    invocation_identity: PlatformIdentityContext | None = None,
+) -> Path:
+    root = Path(resolve_local_session_dir()) / "workspace"
+    if invocation_identity is not None and not invocation_identity.is_empty:
+        root = root / "identities" / identity_scope_ref(invocation_identity)
+    return root
+
+
+def _workspace_request_root(request: Request) -> Path:
+    return _workspace_root_dir(trusted_invocation_identity_from_headers(request.headers))
 
 
 _NATIVE_TUI_FRAMEWORKS = {"hermes", "openclaw"}
@@ -104,10 +119,18 @@ def _current_framework() -> str:
     return str(context.runtime_type if context is not None else "").strip().lower()
 
 
-def _build_native_terminal_capability(framework: str) -> dict[str, Any]:
+def _build_native_terminal_capability(
+    framework: str,
+    invocation_identity: PlatformIdentityContext | None = None,
+) -> dict[str, Any]:
+    isolated_identity = (
+        isinstance(invocation_identity, PlatformIdentityContext)
+        and not invocation_identity.is_empty
+    )
     enabled = (
         native_terminal_supported()
         and str(framework or "").strip().lower() in _NATIVE_TUI_FRAMEWORKS
+        and not isolated_identity
     )
     return {
         "Enabled": enabled,
@@ -127,6 +150,7 @@ def _register_integrated_routers(app: FastAPI, state: RuntimeAppState) -> None:
         create_workspace_files_router(
             root_getter=_workspace_root_dir,
             enabled_getter=lambda: workspace_files_enabled(default=True),
+            request_root_getter=_workspace_request_root,
         )
     )
     state.terminal_manager = TerminalSessionManager(
@@ -137,6 +161,9 @@ def _register_integrated_routers(app: FastAPI, state: RuntimeAppState) -> None:
         app,
         state.terminal_manager,
         bind_context=lambda: bind_runtime_state(state),
+        identity_access_allowed=lambda headers: (
+            trusted_invocation_identity_from_headers(headers).is_empty
+        ),
     )
 
 
@@ -631,6 +658,7 @@ async def _workspace_runtime_request(
     *,
     params: Optional[Dict[str, Any]] = None,
     files: Optional[Dict[str, Any]] = None,
+    invocation_identity: PlatformIdentityContext | None = None,
 ) -> httpx.Response:
     runtime_app = get_state().app
     if runtime_app is None:
@@ -640,6 +668,7 @@ async def _workspace_runtime_request(
         response = await client.request(
             method,
             runtime_path,
+            headers=trusted_invocation_identity_headers(invocation_identity),
             params=params,
             files=files,
         )

ksadk/server/routes/control.py

@@ -10,7 +10,7 @@ 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 (
@@ -19,10 +19,20 @@ 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 (
+    find_resume_attempt_event,
+    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.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
@@ -54,6 +64,33 @@ from .streaming import (
 )
 
 
+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."""
 
@@ -66,13 +103,18 @@ def _resolve_active_runner() -> Any:
 
 
 @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(
+    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(
@@ -80,6 +122,7 @@ async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePrevi
         session_id=request.SessionId,
         run_id=str(request.RunId),
         checkpoint_id=str(request.CheckpointId),
+        expected_session=session,
     )
     if checkpoint is None:
         raise HTTPException(status_code=404, detail="Checkpoint not found")
@@ -123,14 +166,19 @@ async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePrevi
 
 
 @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(
@@ -138,9 +186,48 @@ async def resume_run_action(request: ResumeRunActionRequest):
         session_id=request.SessionId,
         run_id=str(request.RunId),
         checkpoint_id=str(request.CheckpointId),
+        expected_session=session,
     )
     if checkpoint is None:
         raise HTTPException(status_code=404, detail="Checkpoint not found")
+
+    # Resolve an explicit attempt before resumability/lease gates. A network
+    # retry may arrive after the checkpoint has become non-resumable; returning
+    # the prior receipt is idempotent, while a new attempt still gets the
+    # normal 409 gate below. Requests that omit ResumeAttemptId intentionally
+    # retain the existing fresh-attempt behavior.
+    requested_resume_attempt_id = str(request.ResumeAttemptId or "").strip()
+    if requested_resume_attempt_id:
+        try:
+            existing_resume = await find_resume_attempt_event(
+                service,
+                request.SessionId,
+                resume_attempt_id=requested_resume_attempt_id,
+                run_id=str(request.RunId),
+                checkpoint_id=str(request.CheckpointId),
+            )
+        except ValueError as error:
+            raise HTTPException(
+                status_code=409,
+                detail={
+                    "code": "resume_attempt_conflict",
+                    "message": str(error),
+                    "resume_attempt_id": requested_resume_attempt_id,
+                },
+            ) from error
+        if existing_resume is not None:
+            return _action_response(
+                "ResumeRun",
+                {
+                    "SessionId": request.SessionId,
+                    "RunId": str(request.RunId),
+                    "CheckpointId": str(request.CheckpointId),
+                    "ResumeAttemptId": requested_resume_attempt_id,
+                    "InvocationId": existing_resume.invocation_id or requested_resume_attempt_id,
+                    "Status": "already_processed",
+                    "AlreadyProcessed": True,
+                },
+            )
     disabled_detail = _checkpoint_resume_disabled_detail(checkpoint)
     if disabled_detail is not None:
         if disabled_detail.get("IsTerminal"):
@@ -201,6 +288,10 @@ async def resume_run_action(request: ResumeRunActionRequest):
         **_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"])
@@ -374,9 +465,7 @@ async def _runtime_capability_snapshot(*, force: bool) -> Any:
 
     state = get_state()
     runner = _resolve_active_runner()
-    wait_timeout = max(
-        0.1, float(os.getenv("KSADK_PERSISTENCE_PROBE_TIMEOUT") or "2")
-    )
+    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),
@@ -430,17 +519,24 @@ 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(
+    # Subscription authorizes a read; it must not restore the full Agent
+    # context before opening a stream. Other control actions retain replay.
+    from .sessions import _require_identity_action_session
+    await _require_identity_action_session(
         service,
         session_id=session_id,
         agent_id=AgentId,
         user_id=UserId,
+        invocation_identity=invocation_identity,
+        history_only=True,
     )
     if not await _session_contains_invocation(service, session_id, invocation_id):
         raise HTTPException(
@@ -453,11 +549,18 @@ 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,
                 session_id,
                 after_seq_id=last_seq_id,
+                invocation_id=invocation_id,
             )
             for event in events:
                 last_seq_id = max(last_seq_id, event.seq_id)

ksadk/server/routes/dependencies.py

@@ -78,7 +78,8 @@ def describe_session_backend() -> dict[str, Any]:
 async def get_persistence_status(
     *, framework: str | None = None, use_cache: bool = True
 ) -> dict[str, Any]:
-    provider = current().get_persistence_status
+    # 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:

ksadk/server/routes/display_projection.py

@@ -0,0 +1,154 @@
+"""Pure display projection for persisted session events."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .models import _truncate_session_text
+
+
+def _first_text_part(parts: list[Any] | None) -> str:
+    """Return the text of the first part with content_type == 'text'."""
+    if not isinstance(parts, list):
+        return ""
+    for part in parts:
+        if isinstance(part, Mapping) and part.get("content_type") == "text":
+            return str(part.get("text") or "")
+    return ""
+
+
+def _first_tool_name(parts: list[Any] | None) -> str:
+    """Return the name from the first tool_call part."""
+    if not isinstance(parts, list) or not parts:
+        return ""
+    part = parts[0]
+    if isinstance(part, Mapping):
+        return str(part.get("name") or "")
+    return ""
+
+
+def _first_tool_result(parts: list[Any] | None) -> str:
+    """Return the result of the first tool_result part as a string."""
+    if not isinstance(parts, list) or not parts:
+        return ""
+    part = parts[0]
+    if not isinstance(part, Mapping):
+        return ""
+    result = part.get("result")
+    if result is None:
+        return ""
+    if isinstance(result, str):
+        return result
+    return json.dumps(result, ensure_ascii=False)
+
+
+def _derive_display_text(content: Mapping[str, Any]) -> str:
+    """Derive a display string for Content.parts[0].text from a canonical runtime event.
+
+    For canonical runtime events (family=runtime/v2) the Content dict carries a
+    ``runtime_event`` payload but no top-level ``parts``.  This helper extracts a
+    short human-readable string so that frontends reading ``Content.parts[0].text``
+    continue to display meaningful text without changes.
+    """
+    runtime_event = content.get("runtime_event")
+    if not isinstance(runtime_event, Mapping):
+        return str(content.get("text") or "")
+
+    event_type = str(runtime_event.get("event_type") or "")
+    item_kind = str(runtime_event.get("item_kind") or "")
+
+    if event_type == "item.updated":
+        update = runtime_event.get("update")
+        if not isinstance(update, Mapping):
+            return ""
+        if item_kind in ("message", "reasoning"):
+            return str(update.get("text") or "")
+        if item_kind == "tool_call":
+            name = str(update.get("name") or "")
+            return f"调用工具：{name}" if name else ""
+        return ""
+
+    if event_type == "item.started":
+        initial = runtime_event.get("initial")
+        parts = initial.get("parts") if isinstance(initial, Mapping) else None
+        if item_kind == "tool_call":
+            name = _first_tool_name(parts)
+            return f"调用工具：{name}" if name else ""
+        if item_kind in ("message", "reasoning"):
+            return _first_text_part(parts)
+        return ""
+
+    if event_type == "item.completed":
+        snapshot = runtime_event.get("snapshot")
+        parts = snapshot.get("parts") if isinstance(snapshot, Mapping) else None
+        if item_kind == "message":
+            return _first_text_part(parts)
+        if item_kind == "tool_result":
+            result = _first_tool_result(parts)
+            return _truncate_session_text(result) if result else ""
+        if item_kind == "tool_call":
+            name = _first_tool_name(parts)
+            return f"工具调用完成：{name}" if name else ""
+        return ""
+
+    if event_type == "item.snapshot_replaced":
+        snapshot = runtime_event.get("snapshot")
+        parts = snapshot.get("parts") if isinstance(snapshot, Mapping) else None
+        if item_kind in ("message", "reasoning"):
+            return _first_text_part(parts)
+        return ""
+
+    if event_type == "item.failed":
+        error = runtime_event.get("error")
+        if isinstance(error, Mapping):
+            return str(error.get("message") or "执行失败")
+        return "执行失败"
+
+    if event_type == "run.started":
+        return "运行开始"
+    if event_type == "run.progress":
+        return str(runtime_event.get("message") or "")
+    if event_type == "run.completed":
+        return "运行完成"
+    if event_type == "run.failed":
+        error = runtime_event.get("error")
+        if isinstance(error, Mapping):
+            return str(error.get("message") or "运行失败")
+        return "运行失败"
+    if event_type == "run.interrupted":
+        return str(runtime_event.get("reason") or "运行已中断")
+    if event_type == "run.canceled":
+        return str(runtime_event.get("reason") or "运行已取消")
+
+    if event_type == "interaction.requested":
+        request = runtime_event.get("request")
+        if isinstance(request, Mapping):
+            kind = str(request.get("kind") or "approval")
+            return f"请求审批：{kind}"
+        return "请求审批"
+
+    if event_type == "interaction.resolved":
+        response = runtime_event.get("response")
+        if isinstance(response, Mapping):
+            return str(response.get("decision") or "")
+        return ""
+
+    if event_type == "continuation.created":
+        return f"创建恢复点：{runtime_event.get('continuation_kind') or ''}"
+    if event_type == "continuation.resumed":
+        return f"恢复执行：{runtime_event.get('continuation_kind') or ''}"
+
+    if event_type == "context.compaction.started":
+        return "上下文压缩开始"
+    if event_type == "context.compaction.completed":
+        return "上下文压缩完成"
+
+    if event_type == "usage.reported":
+        total = runtime_event.get("total_tokens")
+        if total is not None:
+            return f"用量上报：{total} tokens"
+        return "用量上报"
+
+    return ""