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

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
@@ -19,7 +20,14 @@ from ksadk.conversations.runtime_constants import (
     EVENT_SCAN_PAGE_SIZE,
 )
 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,
+    require_complete_platform_identity,
+)
 
 
 async def ensure_conversation_session(
@@ -28,20 +36,110 @@ async def ensure_conversation_session(
     user_id: str,
     session_id: Optional[str],
     session_service_provider: Callable[[], Any] | None = None,
+    invocation_identity: Any = None,
+    allow_agent_alias: bool = False,
 ) -> Session:
-    """确保会话存在，并在显式 session_id 冲突时做 owner 校验。"""
+    """确保会话存在，并在读取历史前校验可信业务 owner。"""
     service = (session_service_provider or resolve_session_service)()
+    identity = require_complete_platform_identity(invocation_identity)
     if session_id:
-        existing = await service.get_session(session_id)
+        # Ownership is decided from metadata/state before any transcript read.
+        existing = await service.get_session_metadata(session_id)
         if existing:
-            if existing.agent_id != agent_id or existing.user_id != user_id:
-                raise HTTPException(
-                    status_code=409,
-                    detail="Session id belongs to a different agent or user",
+            if existing.agent_id != agent_id:
+                if allow_agent_alias and not identity.is_empty:
+                    # Hosted workers receive an internal instance alias while
+                    # the control plane persists the public AgentId. The
+                    # worker is already scoped to this session store; adopt
+                    # the persisted owner before validating business identity.
+                    agent_id = existing.agent_id
+                elif not identity.is_empty:
+                    raise HTTPException(status_code=404, detail="Session not found")
+                else:
+                    raise HTTPException(
+                        status_code=409,
+                        detail="Session id belongs to a different agent or user",
+                    )
+            if existing.agent_id == agent_id:
+                return await bind_or_validate_session_identity(
+                    service=service,
+                    session=existing,
+                    identity=identity,
+                    requested_user_id=user_id,
                 )
-            return existing
-        return await service.create_session(agent_id, user_id, session_id=session_id)
-    return await service.create_session(agent_id, user_id)
+        native_user_id = identity_native_user_id(identity) or user_id
+        created = await service.create_session(agent_id, native_user_id, session_id=session_id)
+        if created.agent_id != agent_id:
+            raise HTTPException(status_code=404, detail="Session not found")
+        return await bind_or_validate_session_identity(
+            service=service,
+            session=created,
+            identity=identity,
+            requested_user_id=user_id,
+        )
+    native_user_id = identity_native_user_id(identity) or user_id
+    created = await service.create_session(agent_id, native_user_id)
+    return await bind_or_validate_session_identity(
+        service=service,
+        session=created,
+        identity=identity,
+        requested_user_id=user_id,
+    )
+
+
+async def require_conversation_session(
+    *,
+    agent_id: str,
+    user_id: str,
+    session_id: str,
+    session_service_provider: Callable[[], Any] | None = None,
+    invocation_identity: Any = None,
+) -> Session:
+    """Authorize an existing session without creating state on a read/control path."""
+
+    service = (session_service_provider or resolve_session_service)()
+    identity = require_complete_platform_identity(invocation_identity)
+    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 not in session_agent_ids(agent_id):
+        if not identity.is_empty:
+            raise HTTPException(status_code=404, detail="Session not found")
+        raise HTTPException(
+            status_code=409,
+            detail="Session id belongs to a different agent or user",
+        )
+    return await bind_or_validate_session_identity(
+        service=service,
+        session=existing,
+        identity=identity,
+        requested_user_id=user_id,
+    )
+
+
+async def prepare_stream_identity_session(
+    *,
+    agent_id: str,
+    user_id: str,
+    session_id: str | None,
+    request_metadata: Mapping[str, Any] | None,
+    session_service_provider: Callable[[], Any] | None = None,
+) -> tuple[str, str | None, PlatformIdentityContext, dict[str, Any]]:
+    """Authorize a stream before preview reads and hide its private identity carrier."""
+
+    public_metadata = dict(request_metadata or {})
+    identity_payload = public_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
+    identity = PlatformIdentityContext.from_payload(identity_payload)
+    if not identity_payload:
+        return user_id, session_id, identity, public_metadata
+    session = await ensure_conversation_session(
+        agent_id=agent_id,
+        user_id=user_id,
+        session_id=session_id,
+        session_service_provider=session_service_provider,
+        invocation_identity=identity_payload,
+    )
+    return session.user_id, session.id, identity, public_metadata
 
 
 async def append_conversation_event(
@@ -55,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 追加入口。
@@ -68,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,
@@ -331,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,
@@ -344,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(

ksadk/conversations/runtime_preparation.py

@@ -49,7 +49,6 @@ from ksadk.conversations.runtime_metadata import (
 )
 from ksadk.conversations.runtime_observability import _latest_deferred_tool_names
 from ksadk.conversations.runtime_payloads import PreparedConversationTurn
-from ksadk.session_context import split_session_context
 from ksadk.conversations.runtime_persistence import (
     append_conversation_event,
     append_run_resume_event,
@@ -57,22 +56,28 @@ from ksadk.conversations.runtime_persistence import (
     ensure_conversation_session,
 )
 from ksadk.conversations.runtime_resume import (
+    ToolReceiptUncertainError,
     _agentengine_resume_metadata,
     _approval_decision_from_resume,
     _approval_resume_run_mode,
+    _claim_approved_builtin_tool_resume,
     _consecutive_approval_denials_from_events,
     _execute_approved_builtin_tool_resume,
     _find_tool_receipt_event_by_key,
     _format_resume_response_text,
-    _has_pending_approval,
     _is_approval_resume_input,
     _is_checkpoint_resume_input,
     _normalize_approval_resume_input,
     _normalize_checkpoint_resume_input,
+    _raise_if_legacy_tool_receipt_checkpoint_ambiguous,
     _tool_receipt_idempotency_key_for_resume,
+    _validate_tool_receipt_event,
 )
+from ksadk.conversations.tool_receipt_resume import _has_pending_approval_for_resume
 from ksadk.ids import new_run_id
 from ksadk.model_policy import model_policy_options_for_model
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, PlatformIdentityContext
+from ksadk.session_context import split_session_context
 from ksadk.sessions import SessionEvent, resolve_session_service
 
 logger = logging.getLogger(__name__)
@@ -122,25 +127,25 @@ async def build_run_input(
     caller_run_trigger = trigger_from_resume_input(resume_input)
     provider = session_service_provider or resolve_session_service
     service = provider()
-    resolved_user_id = user_id
-    if session_id:
-        existing_session = await service.get_session(session_id)
-        if existing_session and existing_session.user_id:
-            resolved_user_id = existing_session.user_id
+    private_request_metadata = dict(request_metadata or {})
+    identity_payload = private_request_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
+    invocation_identity = PlatformIdentityContext.from_payload(identity_payload)
 
     session = await ensure_conversation_session(
         agent_id=agent_id,
-        user_id=resolved_user_id,
+        user_id=user_id,
         session_id=session_id,
         session_service_provider=provider,
+        invocation_identity=invocation_identity,
     )
+    resolved_user_id = session.user_id
     resolved_session_id = session.id
     resolved_invocation_id = str(invocation_id or new_run_id(resolved_session_id))
     resolved_model_metadata = await _resolve_runtime_model_metadata(
         model,
         model_metadata=model_metadata,
     )
-    session_context, normalized_request_metadata = split_session_context(request_metadata)
+    session_context, normalized_request_metadata = split_session_context(private_request_metadata)
     normalized_custom_metadata = dict(custom_metadata or {})
     policy_model = model or os.getenv("OPENAI_MODEL_NAME") or os.getenv("MODEL_NAME")
     normalized_model_options = {
@@ -205,6 +210,8 @@ async def build_run_input(
                 session_context=session_context.to_payload(),
                 session_id=resolved_session_id,
                 invocation_id=resolved_invocation_id,
+                user_id=resolved_user_id,
+                agent_id=agent_id,
                 user_input="",
                 user_display_input="",
                 history=history,
@@ -241,13 +248,41 @@ async def build_run_input(
 
         existing_events = await service.get_events(resolved_session_id)
         is_approval_resume = _is_approval_resume_input(normalized_resume_input)
-        existing_tool_receipt_event = None
-        if is_approval_resume and not _has_pending_approval(existing_events):
+        has_pending_approval = _has_pending_approval_for_resume(
+            existing_events, normalized_resume_input
+        )
+        preclaimed_receipt = None
+        replay_candidate = normalized_resume_input
+        if is_approval_resume:
             replay_candidate = _normalize_approval_resume_input(
                 normalized_resume_input,
                 existing_events,
-                include_resolved=True,
+                include_resolved=not has_pending_approval,
             )
+            decision = replay_candidate.get("approval")
+            if not isinstance(decision, Mapping):
+                decision = _approval_decision_from_resume(replay_candidate)
+            if bool(decision.get("approved") or decision.get("approve")):
+                # Do this before persisting approval_response. An unscoped
+                # legacy receipt cannot safely be attributed to an explicit
+                # checkpoint and must never reach replay or builtin execution.
+                receipt_key = _tool_receipt_idempotency_key_for_resume(
+                    session_id=resolved_session_id,
+                    resume_input=replay_candidate,
+                )
+                scoped_receipt_event = (
+                    _find_tool_receipt_event_by_key(existing_events, receipt_key)
+                    if receipt_key
+                    else None
+                )
+                if scoped_receipt_event is None:
+                    _raise_if_legacy_tool_receipt_checkpoint_ambiguous(
+                        session_id=resolved_session_id,
+                        resume_input=replay_candidate,
+                        events=existing_events,
+                    )
+        existing_tool_receipt_event = None
+        if is_approval_resume and not has_pending_approval:
             receipt_key = _tool_receipt_idempotency_key_for_resume(
                 session_id=resolved_session_id,
                 resume_input=replay_candidate,
@@ -257,10 +292,27 @@ async def build_run_input(
                     existing_events,
                     receipt_key,
                 )
+            replay_decision = replay_candidate.get("approval")
+            if not isinstance(replay_decision, Mapping):
+                replay_decision = _approval_decision_from_resume(replay_candidate)
+            replay_is_approved = bool(
+                replay_decision.get("approved") or replay_decision.get("approve")
+            )
             if existing_tool_receipt_event is not None:
+                if replay_is_approved:
+                    # Validate before appending the approval response.  A
+                    # malformed newest receipt must fail closed and must not
+                    # create another approval/tool-result pair.
+                    _validate_tool_receipt_event(existing_tool_receipt_event)
                 normalized_resume_input = replay_candidate
-            else:
+            elif not replay_is_approved:
                 raise ValueError("Responses resume input requires a pending approval_request")
+            else:
+                # A prior request may have consumed approval_response before a
+                # crash left only the durable unknown claim. Discover that
+                # claim before appending another response; unknown never runs
+                # the builtin again and remains available for reconciliation.
+                normalized_resume_input = replay_candidate
         if is_approval_resume:
             normalized_resume_input = _normalize_approval_resume_input(
                 normalized_resume_input,
@@ -276,6 +328,36 @@ async def build_run_input(
                     _consecutive_approval_denials_from_events(existing_events)
                 )
 
+            # A pending approval can still race with a persisted receipt (for
+            # example, after a retry that restored the approval request but
+            # retained its tool-result ledger entry).  Resolve and validate
+            # the newest matching receipt before appending approval_response.
+            # Rejections remain a harmless no-op even if an unrelated old
+            # receipt is malformed, so only approved decisions are replayed.
+            approval_decision = normalized_resume_input.get("approval")
+            if not isinstance(approval_decision, Mapping):
+                approval_decision = _approval_decision_from_resume(normalized_resume_input)
+            approval_is_approved = bool(
+                approval_decision.get("approved") or approval_decision.get("approve")
+            )
+            if approval_is_approved and existing_tool_receipt_event is None:
+                _preclaimed_receipt, preclaimed_claim = (
+                    await _claim_approved_builtin_tool_resume(
+                        session_id=resolved_session_id,
+                        invocation_id=resolved_invocation_id,
+                        resume_input=normalized_resume_input,
+                        session_service_provider=provider,
+                        existing_events=existing_events,
+                        require_existing=not has_pending_approval,
+                    )
+                )
+                if not has_pending_approval and preclaimed_claim is None:
+                    raise ValueError("Responses resume input requires a pending approval_request")
+                if preclaimed_claim is not None and _preclaimed_receipt is not None:
+                    if not preclaimed_claim.acquired and preclaimed_claim.state == "unknown":
+                        raise ToolReceiptUncertainError(preclaimed_claim.idempotency_key)
+                    preclaimed_receipt = (_preclaimed_receipt, preclaimed_claim)
+
         resume_text = _format_resume_response_text(normalized_resume_input)
         resume_event_metadata: dict[str, Any] = {"resume_input": normalized_resume_input}
         if normalized_resume_input.get("call_id"):
@@ -305,6 +387,7 @@ async def build_run_input(
                 resume_input=normalized_resume_input,
                 session_service_provider=provider,
                 existing_events=existing_events,
+                preclaimed_receipt=preclaimed_receipt,
             )
         effective_resume_input = tool_resume_input or normalized_resume_input
         if tool_resume_input is not None:
@@ -323,6 +406,8 @@ async def build_run_input(
             session_context=session_context.to_payload(),
             session_id=resolved_session_id,
             invocation_id=resolved_invocation_id,
+            user_id=resolved_user_id,
+            agent_id=agent_id,
             user_input=resume_text,
             user_display_input=resume_text,
             history=history,