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

ksadk/conversations/message_projection_blocks.py

@@ -0,0 +1,137 @@
+"""历史消息载荷解析与有序正文块投影。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def _event_metadata(event: Mapping[str, Any]) -> Mapping[str, Any]:
+    metadata = event.get("Metadata")
+    return metadata if isinstance(metadata, Mapping) else {}
+
+
+def _event_text(event: Mapping[str, Any]) -> str:
+    content = event.get("Content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, Mapping):
+        return ""
+    if content.get("text") is not None:
+        return str(content.get("text") or "")
+    return "".join(
+        str(part.get("text") or "")
+        for part in content.get("parts") or []
+        if isinstance(part, Mapping)
+    )
+
+
+def _project_interleaved_blocks(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    tool_events: Sequence[Mapping[str, Any]],
+    expected_text: str | None = None,
+) -> list[dict[str, Any]]:
+    """Reconstruct ordered chat blocks from persisted streaming events.
+
+    ``assistant_stream_snapshot`` carries a cumulative text value.  The delta
+    relative to the prior snapshot is the text emitted at that point in the
+    event sequence.  Reasoning events written before that snapshot can
+    therefore be replayed as ``thinking → text → thinking → text`` instead of
+    being flattened into the legacy ``Reasoning`` and ``Content`` fields.
+
+    Older transcripts wrote all reasoning only at terminal time.  Their first
+    reasoning event appears after streamed text, so their original boundaries
+    are unknowable.  Return no blocks for those transcripts and let clients
+    use the existing best-effort compatibility projection.
+    """
+
+    blocks: list[dict[str, Any]] = []
+    latest_snapshot_text = ""
+    saw_stream_text = False
+    saw_reasoning_after_stream_text = False
+    tools_by_seq_id = {
+        int(tool.get("SeqId") or 0): tool for tool in tool_events if int(tool.get("SeqId") or 0) > 0
+    }
+
+    def append_text(text: str, seq_id: Any) -> None:
+        if not text:
+            return
+        if blocks and blocks[-1].get("Type") == "text":
+            blocks[-1]["Content"] = f"{blocks[-1].get('Content') or ''}{text}"
+            return
+        blocks.append({"Type": "text", "Content": text, "SeqId": seq_id})
+
+    def append_thinking(text: str, seq_id: Any) -> None:
+        if not text:
+            return
+        if blocks and blocks[-1].get("Type") == "thinking":
+            blocks[-1]["Content"] = f"{blocks[-1].get('Content') or ''}{text}"
+            return
+        blocks.append({"Type": "thinking", "Content": text, "SeqId": seq_id})
+
+    def append_tool(event: Mapping[str, Any]) -> None:
+        tool = tools_by_seq_id.get(int(event.get("SeqId") or 0))
+        if not tool:
+            return
+        blocks.append(
+            {
+                "Type": "tool",
+                "SeqId": tool.get("SeqId"),
+                "Name": tool.get("Name") or "tool",
+                "Args": tool.get("Args"),
+                "Result": tool.get("Result"),
+                "Status": tool.get("Status") or "completed",
+                "ToolCallId": tool.get("ToolCallId"),
+            }
+        )
+
+    for event in events:
+        event_type = str(event.get("EventType") or "")
+        text = _event_text(event)
+        seq_id = event.get("SeqId")
+
+        if event_type == "reasoning":
+            metadata = _event_metadata(event)
+            if saw_stream_text and metadata.get("stream_boundary") != "before_text":
+                saw_reasoning_after_stream_text = True
+            append_thinking(text, seq_id)
+            continue
+        if event_type == "tool_call":
+            append_tool(event)
+            continue
+        if event_type == "assistant_stream_delta":
+            append_text(text, seq_id)
+            latest_snapshot_text += text
+            saw_stream_text = saw_stream_text or bool(text)
+            continue
+        if event_type == "assistant_stream_snapshot":
+            if text.startswith(latest_snapshot_text):
+                append_text(text[len(latest_snapshot_text) :], seq_id)
+            elif text != latest_snapshot_text:
+                # A replacement snapshot has no safe incremental boundary.
+                # Keep the latest content as a standalone text block instead
+                # of duplicating already-replayed output.
+                append_text(text, seq_id)
+            latest_snapshot_text = text
+            saw_stream_text = saw_stream_text or bool(text)
+            continue
+        if event_type == "assistant_message":
+            if latest_snapshot_text and text.startswith(latest_snapshot_text):
+                append_text(text[len(latest_snapshot_text) :], seq_id)
+            elif not latest_snapshot_text:
+                append_text(text, seq_id)
+
+    if saw_reasoning_after_stream_text:
+        return []
+    # A run can contain multiple message items, and a terminal snapshot can
+    # replace streamed text. Without reliable boundaries, use the existing
+    # Content/Reasoning/ToolEvents projection instead of displaying stale or
+    # whole-run text for one message.
+    if (
+        expected_text is not None
+        and "".join(block["Content"] for block in blocks if block["Type"] == "text")
+        != expected_text
+    ):
+        return []
+    return blocks

ksadk/conversations/model_context.py

@@ -132,7 +132,7 @@ def _extract_input_modalities(raw_model: Mapping[str, Any]) -> list[str]:
     if not isinstance(architecture, Mapping):
         return []
     modalities = architecture.get("input_modalities")
-    if not isinstance(modalities, list):
+    if not isinstance(modalities, (list, tuple)):
         return []
 
     normalized: list[str] = []
@@ -144,11 +144,19 @@ def _extract_input_modalities(raw_model: Mapping[str, Any]) -> list[str]:
 
 
 def supports_native_image_input(model_metadata: Mapping[str, Any] | None) -> bool:
+    """Resolve the locked declaration once; explicit flags precede modalities.
+
+    Canonical capabilities take precedence over the legacy Studio spelling.
+    Unknown names or truthy non-booleans never grant image input. Frozen Build
+    tuples have the same meaning as the discovery payload's JSON arrays.
+    """
     if not isinstance(model_metadata, Mapping):
         return False
     capabilities = model_metadata.get("capabilities")
     if isinstance(capabilities, Mapping) and capabilities.get("multimodal_input_image") is not None:
-        return bool(capabilities.get("multimodal_input_image"))
+        return capabilities.get("multimodal_input_image") is True
+    if model_metadata.get("supports_image_input") is not None:
+        return model_metadata.get("supports_image_input") is True
     return "image" in _extract_input_modalities(model_metadata)
 
 
@@ -387,9 +395,9 @@ def normalize_model_metadata(raw_model: Mapping[str, Any] | str | None) -> dict[
         **dict(base.get("capabilities") or {}),
     }
     if input_modalities:
-        capabilities["multimodal_input_image"] = "image" in input_modalities
         capabilities["multimodal_input_video"] = "video" in input_modalities
         capabilities["multimodal_input_file"] = "file" in input_modalities
+    capabilities["multimodal_input_image"] = supports_native_image_input(base)
     limits = {
         **DEFAULT_MODEL_LIMITS,
         **dict(base.get("limits") or {}),

ksadk/conversations/projector.py

@@ -93,6 +93,12 @@ def project_conversation_item(
         schema = "conversation.item.tool-call/v1"
         payload = _tool_payload(event.initial)
         capability_ref = "tool.inspect"
+    elif isinstance(event, ItemSnapshotReplaced) and event.item_kind == "tool_call":
+        kind = "tool_call"
+        operation = "replace"
+        schema = "conversation.item.tool-call/v1"
+        payload = _tool_payload(event.snapshot)
+        capability_ref = "tool.inspect"
     elif isinstance(event, ItemCompleted) and event.item_kind == "tool_call":
         kind = "tool_call"
         operation = "completed"
@@ -100,6 +106,12 @@ def project_conversation_item(
         schema = "conversation.item.tool-call/v1"
         payload = _tool_payload(event.snapshot)
         capability_ref = "tool.inspect"
+    elif isinstance(event, (ItemUpdated, ItemSnapshotReplaced)) and event.item_kind == "tool_call":
+        kind = "tool_call"
+        operation = event.op if isinstance(event, ItemUpdated) else "replace"
+        schema = "conversation.item.tool-call/v1"
+        payload = _tool_payload(_item_snapshot(event))
+        capability_ref = "tool.inspect"
     elif (
         isinstance(event, (ItemStarted, ItemUpdated, ItemSnapshotReplaced, ItemCompleted))
         and event.item_kind == "tool_result"
@@ -253,6 +265,8 @@ def project_conversation_item(
             "status": "failed" if isinstance(event, RunFailed) else "canceled",
             "error": event.error.message if isinstance(event, RunFailed) else event.reason or "",
         }
+        if isinstance(event, RunFailed):
+            payload["errorCode"] = event.error.code
     elif isinstance(event, (ContinuationCreated, ContinuationResumed)):
         kind = "progress"
         schema = "conversation.item.checkpoint/v1"
@@ -310,6 +324,16 @@ def project_conversation_item(
                 "eventType": event.event_type,
                 "summary": "This content requires a newer renderer.",
             }
+    if isinstance(event, (RunCompleted, RunFailed, RunCanceled, RunInterrupted)):
+        payload.update(_run_outcome_payload(event.source.metadata))
+    if kind == "tool_call" and event.source.metadata.get("engine_kind") == "native":
+        # Native public results contain a sealed execution status, not arbitrary
+        # business output. An approval receipt is nonterminal even in old logs
+        # which incorrectly wrapped it in ItemCompleted. Never rewrite the log.
+        output = payload.get("output")
+        if isinstance(output, dict) and output.get("status") == "approval_required":
+            operation, lifecycle = "replace", "pending"
+            payload["executionStatus"] = "approval_required"
     return ConversationItem(
         item_id=item_id,
         source_event_ids=(event.event_id,),
@@ -330,6 +354,44 @@ def project_conversation_item(
     )
 
 
+def _run_outcome_payload(metadata: Mapping[str, Any]) -> dict[str, Any]:
+    """Project explicit acceptance facts; completion alone does not prove them.
+
+    Provider metadata is not a public payload. Only the terminal outcome contract
+    is admitted here; arbitrary diagnostics, reasoning and report contents stay
+    outside the conversation. Keep legacy terminal events without this contract.
+    """
+    outcome = metadata.get("outcome")
+    if not isinstance(outcome, str) or outcome not in {
+        "verified",
+        "unverified",
+        "partial",
+        "blocked",
+    }:
+        return {}
+    payload: dict[str, Any] = {"outcome": outcome}
+    for source, target in (
+        ("reason", "reason"),
+        ("contract_revision", "contractRevision"),
+        ("verification_report_ref", "verificationReportRef"),
+    ):
+        value = metadata.get(source)
+        if isinstance(value, str) and value:
+            payload[target] = value
+    items = metadata.get("verification_items")
+    if isinstance(items, list):
+        payload["verificationItems"] = [
+            {"acceptanceId": row["acceptance_id"], "status": row["status"]}
+            for row in items
+            if isinstance(row, dict)
+            and isinstance(row.get("acceptance_id"), str)
+            and row["acceptance_id"]
+            and isinstance(row.get("status"), str)
+            and row.get("status") in {"passed", "failed", "not_run", "blocked"}
+        ]
+    return payload
+
+
 def project_interaction_conversation_item(
     envelope: SessionEventEnvelope,
 ) -> ConversationItem | None:
@@ -604,6 +666,7 @@ def _native_ref(event: RuntimeEvent) -> dict[str, Any]:
             "protocol": source.protocol,
             "eventId": source.native_event_id,
             "cursor": source.native_cursor,
+            "timestamp": event.timestamp,
             "runId": source.native_run_id,
             "itemId": source.native_item_id,
         }.items()

ksadk/conversations/runtime_compaction.py

@@ -231,7 +231,10 @@ async def preview_auto_compaction(
 
     provider = session_service_provider or resolve_session_service
     service = provider()
-    existing_session = await service.get_session(session_id)
+    # Attachment context lives in state; authorization/preview do not need a
+    # second complete transcript before the explicit get_events below.
+    read_metadata = getattr(service, "get_session_metadata", None) or service.get_session
+    existing_session = await read_metadata(session_id)
     if not existing_session:
         return CompactionPlan(
             should_compact=False,
@@ -378,7 +381,9 @@ async def compact_conversation_history(
     provider = session_service_provider or resolve_session_service
     service = provider()
     events = await service.get_events(session_id)
-    session = await service.get_session(session_id)
+    header_reader = getattr(service, "get_session_header", None) or getattr(
+        service, "get_session_metadata", None) or service.get_session
+    session = await header_reader(session_id)
     memory_user_id = str(getattr(session, "user_id", "") or "")
     plan = _plan_compaction(
         events,

ksadk/conversations/runtime_input.py

@@ -750,10 +750,22 @@ async def _auto_save_ltm_turn(
 ) -> None:
     if prepared.resume_input is not None:
         return
-    memory_rollout = str(prepared.memory_write_rollout or "").strip().lower()
-    if memory_rollout in {"off", "shadow"}:
-        return
-    if not memory_rollout and not _ltm_auto_save_enabled():
+    from ksadk.memory.resolved_policy import resolve_memory_policy
+
+    memory_rollout = prepared.memory_write_rollout
+    if not str(memory_rollout or "").strip():
+        memory_rollout = "enabled" if _ltm_auto_save_enabled() else "off"
+    # Old callers have no MemorySpec and retain the SDK auto-save fallback.
+    # Explicit Build switches always govern before opening a memory service.
+    policy = resolve_memory_policy(
+        memory_enabled=True if prepared.memory_enabled is None else prepared.memory_enabled,
+        recall_enabled=prepared.memory_recall_enabled,
+        write_rollout=memory_rollout,
+        write_mode=prepared.memory_write_mode,
+        flush_before_compaction=prepared.flush_before_compaction,
+        provider_ref=prepared.provider_ref,
+    )
+    if not policy.should_flush:
         return
 
     metadata: dict[str, Any] = {

ksadk/conversations/runtime_payloads.py

@@ -217,6 +217,8 @@ def extract_responses_resume_input(input_payload: Any) -> dict[str, Any] | None:
             approval_resume: dict[str, Any] = {"type": "mcp_approval_response"}
             if item.get("id"):
                 approval_resume["id"] = str(item.get("id"))
+            if item.get("checkpoint_id"):
+                approval_resume["checkpoint_id"] = str(item.get("checkpoint_id"))
             approval_request_id = item.get("approval_request_id")
             if approval_request_id:
                 approval_resume["approval_request_id"] = str(approval_request_id)
@@ -243,6 +245,8 @@ def extract_responses_resume_input(input_payload: Any) -> dict[str, Any] | None:
 
         if item_type in {"ksadk_resume", "ksadk.approval_response"}:
             ksadk_resume: dict[str, Any] = {"type": "ksadk_resume"}
+            if item.get("checkpoint_id"):
+                ksadk_resume["checkpoint_id"] = str(item.get("checkpoint_id"))
             interrupt_id = (
                 item.get("interrupt_id") or item.get("approval_request_id") or item.get("id")
             )

ksadk/conversations/runtime_persistence.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import time
 import uuid
 from typing import Any, Callable, Mapping, Optional, Sequence, cast
@@ -21,6 +22,7 @@ from ksadk.conversations.runtime_constants import (
 from ksadk.conversations.runtime_observability import _extract_deferred_tool_names
 from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, PlatformIdentityContext
 from ksadk.sessions import Session, SessionEvent, resolve_session_service
+from ksadk.sessions.agent_identity import session_agent_ids
 from ksadk.sessions.invocation_identity import (
     bind_or_validate_session_identity,
     identity_native_user_id,
@@ -100,7 +102,7 @@ async def require_conversation_session(
     existing = await service.get_session_metadata(session_id)
     if existing is None:
         raise HTTPException(status_code=404, detail="Session not found")
-    if existing.agent_id != agent_id:
+    if existing.agent_id not in session_agent_ids(agent_id):
         if not identity.is_empty:
             raise HTTPException(status_code=404, detail="Session not found")
         raise HTTPException(
@@ -151,6 +153,7 @@ async def append_conversation_event(
     metadata: Optional[dict[str, Any]] = None,
     event_type: Optional[str] = None,
     content: Optional[dict[str, Any]] = None,
+    event_id: Optional[str] = None,
     session_service_provider: Callable[[], Any] | None = None,
 ) -> SessionEvent:
     """统一的 canonical event 追加入口。
@@ -164,7 +167,7 @@ async def append_conversation_event(
         session_id,
         SessionEvent.from_dict(
             {
-                "id": str(uuid.uuid4()),
+                "id": str(event_id or uuid.uuid4()),
                 "author": author,
                 "event_type": event_type or canonical_event_type(None, author=author, role=role),
                 "invocationId": invocation_id,
@@ -427,6 +430,115 @@ async def append_run_checkpoint_event(
     )
 
 
+def _resume_event_id(
+    session_id: str, resume_attempt_id: str
+) -> str:
+    """Return the stable physical id for one session-scoped resume attempt."""
+
+    # The attempt id is the semantic idempotency key. Keep the physical key
+    # independent of checkpoint details so a concurrent reuse of an attempt
+    # cannot create two rows before the collision validator runs.
+    identity = "\x1f".join((session_id, resume_attempt_id))
+    return "resume_" + hashlib.sha256(identity.encode("utf-8")).hexdigest()
+
+
+def _resume_identity_matches(
+    event: SessionEvent,
+    *,
+    run_id: str,
+    checkpoint_id: str,
+    resume_attempt_id: str,
+    framework: str,
+    framework_ref: Mapping[str, Any],
+) -> None:
+    identity = _resume_event_identity(event)
+    expected = (run_id, checkpoint_id, resume_attempt_id)
+    if identity is None or identity[:3] != expected:
+        raise ValueError(
+            f"resume_attempt_id {resume_attempt_id!r} is already bound to a different checkpoint"
+        )
+    actual_framework, actual_framework_ref = identity[3:]
+    if actual_framework is not None and actual_framework != framework:
+        raise ValueError(
+            f"resume_attempt_id {resume_attempt_id!r} is already bound to a different framework"
+        )
+    if actual_framework_ref is not None and actual_framework_ref != dict(framework_ref):
+        raise ValueError(
+            f"resume_attempt_id {resume_attempt_id!r} is already bound to a different checkpoint"
+        )
+
+
+def _resume_event_identity(
+    event: SessionEvent,
+) -> tuple[str, str, str, str | None, dict[str, Any] | None] | None:
+    """Extract resume identity from legacy or canonical checkpoint carriers."""
+
+    if canonical_event_type(event.event_type) == "run_resume":
+        metadata = event.metadata or {}
+        run_id = str(metadata.get("run_id") or "").strip()
+        checkpoint_id = str(metadata.get("checkpoint_id") or "").strip()
+        resume_attempt_id = str(metadata.get("resume_attempt_id") or "").strip()
+        if not (run_id and checkpoint_id and resume_attempt_id):
+            return None
+        framework = str(metadata.get("framework") or "").strip() or None
+        framework_ref = metadata.get("framework_ref")
+        return (
+            run_id,
+            checkpoint_id,
+            resume_attempt_id,
+            framework,
+            dict(framework_ref) if isinstance(framework_ref, Mapping) else None,
+        )
+
+    if event.event_type != "continuation.resumed":
+        return None
+    payload = (event.content or {}).get("runtime_event")
+    if not isinstance(payload, Mapping):
+        envelope = (event.content or {}).get("session_event")
+        payload = envelope.get("payload") if isinstance(envelope, Mapping) else None
+    if not isinstance(payload, Mapping) or payload.get("continuation_kind") != "graph_checkpoint":
+        return None
+    run_id = str(payload.get("run_id") or "").strip()
+    checkpoint_id = str(payload.get("continuation_id") or "").strip()
+    resume_attempt_id = str(payload.get("resume_attempt_id") or "").strip()
+    if not (run_id and checkpoint_id and resume_attempt_id):
+        return None
+    source = payload.get("source")
+    framework = str(source.get("framework") or "").strip() if isinstance(source, Mapping) else ""
+    return run_id, checkpoint_id, resume_attempt_id, framework or None, None
+
+
+async def find_resume_attempt_event(
+    service: Any,
+    session_id: str,
+    *,
+    resume_attempt_id: str,
+    run_id: str | None = None,
+    checkpoint_id: str | None = None,
+) -> SessionEvent | None:
+    """Find a prior legacy or canonical resume fact for idempotent API retries."""
+
+    attempt_id = str(resume_attempt_id).strip()
+    if not attempt_id:
+        return None
+
+    def predicate(event: SessionEvent) -> bool:
+        identity = _resume_event_identity(event)
+        if identity is None or identity[2] != attempt_id:
+            return False
+        if run_id is not None and identity[0] != str(run_id).strip():
+            raise ValueError(
+                f"resume_attempt_id {attempt_id!r} is already bound to a different run"
+            )
+        if checkpoint_id is not None and identity[1] != str(checkpoint_id).strip():
+            raise ValueError(
+                f"resume_attempt_id {attempt_id!r} is already bound to a different checkpoint"
+            )
+        return True
+
+    return await _find_latest_session_event(service, session_id, predicate)
+
+
 async def append_run_resume_event(
     *,
     session_id: str,
@@ -440,33 +552,89 @@ async def append_run_resume_event(
     metadata: Optional[dict[str, Any]] = None,
     session_service_provider: Callable[[], Any] | None = None,
 ) -> SessionEvent:
+    service = (session_service_provider or resolve_session_service)()
+    run_id = str(run_id).strip()
+    checkpoint_id = str(checkpoint_id).strip()
+    resume_attempt_id = str(resume_attempt_id).strip()
+    framework = str(framework).strip()
+    if not all((session_id.strip(), run_id, checkpoint_id, resume_attempt_id, framework)):
+        raise ValueError(
+            "session_id, run_id, checkpoint_id, resume_attempt_id, and framework are required"
+        )
+    framework_ref_dict = dict(framework_ref)
+
+    # ``resume_attempt_id`` is the caller's idempotency key. Invocation ids
+    # identify a transport execution and may legitimately change on retry.
+    existing = await find_resume_attempt_event(
+        service,
+        session_id,
+        resume_attempt_id=resume_attempt_id,
+        run_id=run_id,
+        checkpoint_id=checkpoint_id,
+    )
+    if existing is not None:
+        _resume_identity_matches(
+            existing,
+            run_id=run_id,
+            checkpoint_id=checkpoint_id,
+            resume_attempt_id=resume_attempt_id,
+            framework=framework,
+            framework_ref=framework_ref_dict,
+        )
+        return existing
+
     event_metadata = dict(metadata or {})
     event_metadata.update(
         {
-            "run_id": str(run_id),
-            "checkpoint_id": str(checkpoint_id),
-            "resume_attempt_id": str(resume_attempt_id),
-            "framework": str(framework),
-            "framework_ref": dict(framework_ref),
+            "run_id": run_id,
+            "checkpoint_id": checkpoint_id,
+            "resume_attempt_id": resume_attempt_id,
+            "framework": framework,
+            "framework_ref": framework_ref_dict,
         }
     )
-    return await append_conversation_event(
-        session_id=session_id,
-        author=author,
-        role="model",
-        text="checkpoint resume requested",
-        invocation_id=invocation_id,
-        event_type="run_resume",
-        content={
-            "status": "resuming",
-            "run_id": str(run_id),
-            "checkpoint_id": str(checkpoint_id),
-            "resume_attempt_id": str(resume_attempt_id),
-            "framework": str(framework),
-        },
-        metadata=event_metadata,
-        session_service_provider=session_service_provider,
-    )
+    event_id = _resume_event_id(session_id, resume_attempt_id)
+    try:
+        return await append_conversation_event(
+            session_id=session_id,
+            author=author,
+            role="model",
+            text="checkpoint resume requested",
+            invocation_id=invocation_id,
+            event_type="run_resume",
+            event_id=event_id,
+            content={
+                "status": "resuming",
+                "run_id": run_id,
+                "checkpoint_id": checkpoint_id,
+                "resume_attempt_id": resume_attempt_id,
+                "framework": framework,
+            },
+            metadata=event_metadata,
+            session_service_provider=lambda: service,
+        )
+    except Exception:
+        # A concurrent retry can win the deterministic insert. Re-read the
+        # winner and absorb only an identical attempt; unrelated failures stay
+        # visible to the caller.
+        existing = await find_resume_attempt_event(
+            service,
+            session_id,
+            resume_attempt_id=resume_attempt_id,
+            run_id=run_id,
+            checkpoint_id=checkpoint_id,
+        )
+        if existing is None:
+            raise
+        _resume_identity_matches(
+            existing,
+            run_id=run_id,
+            checkpoint_id=checkpoint_id,
+            resume_attempt_id=resume_attempt_id,
+            framework=framework,
+            framework_ref=framework_ref_dict,
+        )
+        return existing
 
 
 async def append_reasoning_event(