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

ksadk/server/routes/kernel_ingress.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""RunAgent / Responses 入口的 kernel 路径（Phase 1 Task 8 Step 3-5）。
+"""RunAgent / Responses 入口的 kernel 路径（Kernel Task 8 Step 3-5）。
 
 只在 ``kernel_route_active()`` 时启用（灰度 opt-in）；旧 HTTP 行为保持兼容：
 - accepted -> 202、duplicate -> 200、rejected -> 400、unsupported -> 409、
@@ -18,6 +18,8 @@ from fastapi.responses import JSONResponse, StreamingResponse
 
 from ksadk.kernel import ingress
 from ksadk.kernel.contracts import AgentControlReceipt
+from ksadk.runtime_context import PlatformIdentityContext
+from ksadk.sessions.invocation_identity import identity_owner_payload
 
 logger = logging.getLogger(__name__)
 
@@ -35,6 +37,7 @@ async def _kernel_submit(
     correlation_ref: str | None,
     source_kind: str,
     runtime_options: dict[str, Any] | None = None,
+    invocation_identity: PlatformIdentityContext | None = None,
 ) -> tuple[AgentControlReceipt, ingress.TrustedRuntimeContext]:
     trusted = ingress.trusted_context(
         source_kind=source_kind,
@@ -60,6 +63,11 @@ async def _kernel_submit(
         **({correlation_kwarg: correlation_ref} if correlation_ref else {}),
         **({"runtime_options": runtime_options} if runtime_options else {}),
     )
+    owner = identity_owner_payload(invocation_identity)
+    if owner:
+        command = command.model_copy(
+            update={"payload": {**dict(command.payload), "invocation_identity": owner}}
+        )
     receipt = await ingress.submit_command(command, permit=trusted.permit)
     return receipt, trusted
 
@@ -100,8 +108,9 @@ def kernel_stream_response(
                 continue
             kind, payload = projected
             yield _sse_chunk(payload, event=kind, seq=seq)
-            if kind == "response.output_item.done" and (
-                (payload.get("item") or {}).get("type") == "mcp_approval_request"
+            if kind == "interaction.requested" or (
+                kind == "response.output_item.done"
+                and (payload.get("item") or {}).get("type") == "mcp_approval_request"
             ):
                 yield _sse_chunk(
                     {"type": "response.incomplete"},
@@ -125,7 +134,21 @@ def _responses_projector(envelope: Any) -> tuple[str, dict[str, Any]] | None:
     payload = envelope.payload or {}
     event_type = envelope.event_type
     if event_type == "interaction.requested":
+        # Runtime facts precede the authoritative Kernel interaction record.
+        # Projecting them as approvals closes the foreground stream before
+        # the durable request schema and submission identity become available.
+        if getattr(envelope, "family", None) == "runtime":
+            return None
         request = payload.get("request") or {}
+        if (payload.get("kind") or request.get("kind")) == "structured_input":
+            return "interaction.requested", {
+                "event_type": "interaction.requested",
+                "family": "interaction",
+                "session_id": str(getattr(envelope, "session_id", "") or payload.get("session_id") or ""),
+                "run_id": str(getattr(envelope, "run_id", "") or payload.get("run_id") or ""),
+                "seq": getattr(envelope, "seq", 0),
+                "payload": payload,
+            }
         presentation = request.get("presentation") or {}
         description = presentation.get("description") or ""
         try:

ksadk/server/routes/misc.py

@@ -2,22 +2,33 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import time
 import uuid
 from collections.abc import Mapping
 from typing import Any, Dict, List, Optional, cast
 
-from fastapi import HTTPException, Request
+from fastapi import Depends, HTTPException, Request
 
+from ksadk.conversations.runtime_persistence import (
+    ensure_conversation_session,
+    require_conversation_session,
+)
+from ksadk.runtime_context import PlatformIdentityContext
 from ksadk.sessions import SessionEvent
+from ksadk.sessions.invocation_identity import (
+    bind_or_validate_session_identity,
+    identity_can_adopt_any_legacy_user,
+    identity_native_user_id,
+    session_identity_binding_matches,
+)
 from ksadk.tracing import get_memory_exporter
 
+from ..invocation_identity import resolve_trusted_invocation_identity
 from . import dependencies as deps
 from .common import (
     _action_response,
-    _ensure_session,
-    _hydrate_session,
     _resolve_ui_static_response,
 )
 from .models import ResponseFeedbackRefActionRequest, UpsertResponseFeedbackActionRequest
@@ -32,6 +43,49 @@ from .routers import (
 from .workspace import ListAgentModelsRequest, _build_models_payload
 
 
+async def _require_misc_session(
+    *,
+    session_id: str,
+    agent_id: str,
+    invocation_identity: PlatformIdentityContext,
+):
+    service = deps.resolve_session_service()
+    if invocation_identity.is_empty:
+        session = await service.get_session(session_id)
+        if not session or session.agent_id != agent_id:
+            raise HTTPException(status_code=404, detail="Session not found")
+        return session
+    return await require_conversation_session(
+        agent_id=agent_id,
+        user_id="",
+        session_id=session_id,
+        session_service_provider=lambda: service,
+        invocation_identity=invocation_identity,
+    )
+
+
+async def _adk_session_with_events(service, session_id: str, session=None):
+    """Return a complete legacy session with ownership bound to its transcript."""
+    snapshot = getattr(service, "get_adk_session_snapshot", None)
+    if callable(snapshot):
+        return await snapshot(session_id, session)
+    # Older custom services keep the metadata/events protocol. Recheck their
+    # incarnation after reading; they cannot guarantee a database snapshot.
+    session = session or await service.get_session_metadata(session_id)
+    if session is None:
+        return None
+    events = await service.get_events(session_id)
+    current = await service.get_session_metadata(session_id)
+    if (current is None or current.agent_id != session.agent_id
+            or current.user_id != session.user_id
+            or current.created_at != session.created_at):
+        from ksadk.sessions.errors import HistoryReloadRequired
+
+        raise HistoryReloadRequired("Session changed during legacy read")
+    current.events = events
+    return current
+
+
 @health_meta_router.get("/{requested_path:path}", include_in_schema=False)
 async def serve_agent_ui_static(requested_path: str):
     response = _resolve_ui_static_response(requested_path)
@@ -54,7 +108,7 @@ async def get_agent_builder(
     """Get agent builder config - stub for ADK-Web"""
     # Return minimal YAML config for non-ADK projects
     return f"""name: {app_name}
-model: glm-5.1
+model: deepseek-v4.1-flash
 description: {app_name} agent
 instruction: You are a helpful assistant.
 """
@@ -86,8 +140,21 @@ async def list_agent_models_action(_request: ListAgentModelsRequest):
 
 
 @debug_router.get("/debug/trace/session/{session_id}")
-async def get_session_trace(session_id: str):
+async def get_session_trace(
+    session_id: str,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """Get traces for a session - returns array of Span objects"""
+    service = deps.resolve_session_service()
+    if not invocation_identity.is_empty:
+        candidate = await service.get_session_metadata(session_id)
+        if candidate is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        await _require_misc_session(
+            session_id=session_id,
+            agent_id=candidate.agent_id,
+            invocation_identity=invocation_identity,
+        )
     exporter = get_memory_exporter()
     if not exporter:
         return []  # Return empty array, not object
@@ -96,7 +163,6 @@ async def get_session_trace(session_id: str):
     raw_spans = exporter.get_finished_spans()
 
     # Get session events for invocation mapping
-    service = deps.resolve_session_service()
     events = await service.get_events(session_id)
 
     # Build invocation ID mapping from session events
@@ -161,8 +227,13 @@ async def get_session_trace(session_id: str):
 
 
 @debug_router.get("/debug/trace/{event_id}")
-async def get_event_trace(event_id: str):
+async def get_event_trace(
+    event_id: str,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """Get trace for a specific event - returns array of Span objects"""
+    if not invocation_identity.is_empty:
+        raise HTTPException(status_code=404, detail="Trace not found")
     exporter = get_memory_exporter()
     if not exporter:
         return []
@@ -174,8 +245,13 @@ async def get_event_trace(event_id: str):
 
 
 @debug_router.get("/traces")
-async def get_traces(limit: int = 50):
+async def get_traces(
+    limit: int = 50,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """Get recent traces (OpenTelemetry)"""
+    if not invocation_identity.is_empty:
+        raise HTTPException(status_code=404, detail="Trace not found")
     exporter = get_memory_exporter()
     if not exporter:
         return {"traces": []}
@@ -251,10 +327,20 @@ async def _find_feedback_assistant_event(
 
 
 @feedback_router.post("/agentengine/api/v1/GetResponseFeedback")
-async def get_response_feedback_action(request: ResponseFeedbackRefActionRequest):
-    session = await deps.resolve_session_service().get_session(request.SessionId)
-    if not session or session.agent_id != request.AgentId:
-        return _action_response("GetResponseFeedback", {"Feedback": None})
+async def get_response_feedback_action(
+    request: ResponseFeedbackRefActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    try:
+        session = await _require_misc_session(
+            session_id=request.SessionId,
+            agent_id=request.AgentId,
+            invocation_identity=invocation_identity,
+        )
+    except HTTPException:
+        if invocation_identity.is_empty:
+            return _action_response("GetResponseFeedback", {"Feedback": None})
+        raise
     feedbacks = session.state.get("__ksadk_response_feedback__")
     feedback = None
     if isinstance(feedbacks, Mapping):
@@ -265,15 +351,20 @@ async def get_response_feedback_action(request: ResponseFeedbackRefActionRequest
 
 
 @feedback_router.post("/agentengine/api/v1/UpsertResponseFeedback")
-async def upsert_response_feedback_action(request: UpsertResponseFeedbackActionRequest):
+async def upsert_response_feedback_action(
+    request: UpsertResponseFeedbackActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     rating = str(request.Rating or "").strip().lower()
     if rating not in {"up", "down"}:
         raise HTTPException(status_code=400, detail="Feedback rating must be up or down")
 
     service = deps.resolve_session_service()
-    session = await service.get_session(request.SessionId)
-    if not session or session.agent_id != request.AgentId:
-        raise HTTPException(status_code=404, detail="Session not found")
+    session = await _require_misc_session(
+        session_id=request.SessionId,
+        agent_id=request.AgentId,
+        invocation_identity=invocation_identity,
+    )
 
     assistant_event = await _find_feedback_assistant_event(
         session_id=request.SessionId,
@@ -314,11 +405,21 @@ async def upsert_response_feedback_action(request: UpsertResponseFeedbackActionR
 
 
 @feedback_router.post("/agentengine/api/v1/DeleteResponseFeedback")
-async def delete_response_feedback_action(request: ResponseFeedbackRefActionRequest):
+async def delete_response_feedback_action(
+    request: ResponseFeedbackRefActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     service = deps.resolve_session_service()
-    session = await service.get_session(request.SessionId)
-    if not session or session.agent_id != request.AgentId:
-        return _action_response("DeleteResponseFeedback", {"Deleted": False})
+    try:
+        session = await _require_misc_session(
+            session_id=request.SessionId,
+            agent_id=request.AgentId,
+            invocation_identity=invocation_identity,
+        )
+    except HTTPException:
+        if invocation_identity.is_empty:
+            return _action_response("DeleteResponseFeedback", {"Deleted": False})
+        raise
     existing_feedbacks = session.state.get("__ksadk_response_feedback__")
     feedbacks = dict(existing_feedbacks) if isinstance(existing_feedbacks, Mapping) else {}
     deleted = feedbacks.pop(_feedback_state_key(request.ResponseId), None) is not None
@@ -337,7 +438,12 @@ async def delete_response_feedback_action(request: ResponseFeedbackRefActionRequ
 
 
 @sessions_adk_compat_router.post("/apps/{app_name}/users/{user_id}/sessions")
-async def create_session(app_name: str, user_id: str, request: Request):
+async def create_session(
+    app_name: str,
+    user_id: str,
+    request: Request,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """Create a new session"""
     # Check if importing existing events
     body = {}
@@ -347,42 +453,234 @@ async def create_session(app_name: str, user_id: str, request: Request):
         pass
 
     service = deps.resolve_session_service()
-    session = await _ensure_session(app_name, user_id, body.get("sessionId") or body.get("id"))
+    requested_session_id = body.get("sessionId") or body.get("id")
+    existing = (
+        await service.get_session_metadata(str(requested_session_id))
+        if requested_session_id
+        else None
+    )
+    if not invocation_identity.is_empty and existing is not None:
+        session = existing
+        matches = existing.agent_id == app_name and await session_identity_binding_matches(
+            service=service, session=existing, identity=invocation_identity
+        )
+        if not matches and existing.agent_id == app_name:
+            session = await ensure_conversation_session(
+                agent_id=app_name,
+                user_id=existing.user_id,
+                session_id=existing.id,
+                session_service_provider=lambda: service,
+                invocation_identity=invocation_identity,
+            )
+            matches = True
+        if not matches:
+            raise HTTPException(status_code=404, detail="Session not found")
+    elif invocation_identity.is_empty:
+        if existing is not None:
+            if existing.agent_id != app_name or existing.user_id != user_id:
+                raise HTTPException(
+                    status_code=409,
+                    detail="Session id belongs to a different agent or user",
+                )
+            session = existing
+        else:
+            session = await service.create_session(
+                app_name, user_id, session_id=requested_session_id
+            )
+            if session.agent_id != app_name or session.user_id != user_id:
+                raise HTTPException(
+                    status_code=409,
+                    detail="Session id belongs to a different agent or user",
+                )
+    else:
+        session = await ensure_conversation_session(
+            agent_id=app_name,
+            user_id=user_id,
+            session_id=requested_session_id,
+            session_service_provider=lambda: service,
+            invocation_identity=invocation_identity,
+        )
 
     for raw_event in body.get("events", []):
         session_event = SessionEvent.from_dict(raw_event, session_id=session.id)
-        await service.append_event(session.id, session_event)
+        guarded_append = getattr(service, "append_event_if_session_matches", None)
+        if callable(guarded_append):
+            await guarded_append(session.id, session_event, session)
+        else:
+            current = await service.get_session_metadata(session.id)
+            if (current is None or current.agent_id != session.agent_id
+                    or current.user_id != session.user_id
+                    or current.created_at != session.created_at):
+                from ksadk.sessions.errors import HistoryReloadRequired
+
+                raise HistoryReloadRequired("Session changed during legacy import")
+            await service.append_event(session.id, session_event)
+
+    hydrated = await _adk_session_with_events(
+        service, session.id, session
+    )
+    if hydrated is not None and not invocation_identity.is_empty:
+        matches = await session_identity_binding_matches(
+            service=service, session=hydrated, identity=invocation_identity,
+        )
+        if not matches:
+            from ksadk.sessions.errors import HistoryReloadRequired
 
-    hydrated = await _hydrate_session(await service.get_session(session.id))
-    return hydrated.to_legacy_dict() if hydrated else session.to_legacy_dict()
+            raise HistoryReloadRequired("Session identity changed during legacy read")
+    if hydrated is None:
+        from ksadk.sessions.errors import HistoryReloadRequired
+
+        raise HistoryReloadRequired("Session disappeared during legacy read")
+    return hydrated.to_legacy_dict()
 
 
 @sessions_adk_compat_router.get("/apps/{app_name}/users/{user_id}/sessions")
-async def list_sessions(app_name: str, user_id: str):
+async def list_sessions(
+    app_name: str,
+    user_id: str,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """List all sessions for a user"""
     service = deps.resolve_session_service()
-    sessions = await service.list_sessions(app_name, user_id)
+    if invocation_identity.is_empty:
+        sessions = await service.list_session_metadata(app_name, user_id)
+    else:
+        sessions = []
+        seen: set[str] = set()
+        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)
+        for candidate_user in candidate_users:
+            for candidate in await service.list_session_metadata(app_name, candidate_user):
+                if candidate.id in seen:
+                    continue
+                matches = await session_identity_binding_matches(
+                    service=service,
+                    session=candidate,
+                    identity=invocation_identity,
+                )
+                if not matches:
+                    try:
+                        await bind_or_validate_session_identity(
+                            service=service,
+                            session=candidate,
+                            identity=invocation_identity,
+                            requested_user_id=candidate.user_id,
+                        )
+                    except HTTPException:
+                        matches = False
+                    else:
+                        matches = True
+                if matches:
+                    sessions.append(candidate)
+                    seen.add(candidate.id)
+    async def load_one(session) -> Dict[str, Any]:
+        complete = await _adk_session_with_events(service, session.id, session)
+        if complete is None or complete.agent_id != app_name:
+            from ksadk.sessions.errors import HistoryReloadRequired
+
+            raise HistoryReloadRequired("Session changed during legacy read")
+        if not invocation_identity.is_empty:
+            matches = await session_identity_binding_matches(
+                service=service, session=complete, identity=invocation_identity,
+            )
+            if not matches:
+                from ksadk.sessions.errors import HistoryReloadRequired
+
+                raise HistoryReloadRequired("Session identity changed during legacy read")
+        return complete.to_legacy_dict()
+
     hydrated: List[Dict[str, Any]] = []
-    for session in sessions:
-        session.events = await service.get_events(session.id)
-        hydrated.append(session.to_legacy_dict())
+    for index in range(0, len(sessions), 2):
+        tasks = [asyncio.create_task(load_one(session))
+                 for session in sessions[index : index + 2]]
+        try:
+            hydrated.extend(await asyncio.gather(*tasks))
+        except BaseException:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            raise
     return hydrated
 
 
 @sessions_adk_compat_router.get("/apps/{app_name}/users/{user_id}/sessions/{session_id}")
-async def get_session(app_name: str, user_id: str, session_id: str):
+async def get_session(
+    app_name: str,
+    user_id: str,
+    session_id: str,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """Get a specific session with its events"""
     service = deps.resolve_session_service()
-    session = await _hydrate_session(await service.get_session(session_id))
+    if invocation_identity.is_empty:
+        session = await _adk_session_with_events(service, session_id)
+    else:
+        existing = await service.get_session_metadata(session_id)
+        if existing is None or existing.agent_id != app_name:
+            raise HTTPException(status_code=404, detail="Session not found")
+        matches = await session_identity_binding_matches(
+            service=service,
+            session=existing,
+            identity=invocation_identity,
+        )
+        if not matches:
+            existing = await ensure_conversation_session(
+                agent_id=app_name,
+                user_id=existing.user_id,
+                session_id=session_id,
+                session_service_provider=lambda: service,
+                invocation_identity=invocation_identity,
+            )
+            matches = True
+        if not matches:
+            raise HTTPException(status_code=404, detail="Session not found")
+        session = await _adk_session_with_events(service, existing.id, existing)
+        if session is not None and not await session_identity_binding_matches(
+            service=service, session=session, identity=invocation_identity,
+        ):
+            from ksadk.sessions.errors import HistoryReloadRequired
+
+            raise HistoryReloadRequired("Session identity changed during legacy read")
     if not session:
         raise HTTPException(status_code=404, detail="Session not found")
     return session.to_legacy_dict()
 
 
 @sessions_adk_compat_router.delete("/apps/{app_name}/users/{user_id}/sessions/{session_id}")
-async def delete_session(app_name: str, user_id: str, session_id: str):
+async def delete_session(
+    app_name: str,
+    user_id: str,
+    session_id: str,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
     """Delete a session"""
     service = deps.resolve_session_service()
+    if not invocation_identity.is_empty:
+        existing = await service.get_session_metadata(session_id)
+        if existing is None or existing.agent_id != app_name:
+            raise HTTPException(status_code=404, detail="Session not found")
+        matches = await session_identity_binding_matches(
+            service=service,
+            session=existing,
+            identity=invocation_identity,
+        )
+        if not matches:
+            await ensure_conversation_session(
+                agent_id=app_name,
+                user_id=existing.user_id,
+                session_id=session_id,
+                session_service_provider=lambda: service,
+                invocation_identity=invocation_identity,
+            )
+            matches = True
+        if not matches:
+            raise HTTPException(status_code=404, detail="Session not found")
     if await service.delete_session(session_id):
         return {"status": "deleted"}
     raise HTTPException(status_code=404, detail="Session not found")

ksadk/server/routes/models.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 from datetime import datetime, timezone
-from typing import Any, Dict, List, Mapping, Optional
+from typing import Any, Dict, List, Literal, Mapping, Optional
 
 from fastapi import HTTPException
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -12,6 +12,7 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 from ksadk.conversations.run_kinds import RUN_MODE_UNKNOWN, RUN_TRIGGER_UNKNOWN
 from ksadk.conversations.run_status import RUN_STATUS_ACTIVE, RUN_STATUS_TERMINAL
 from ksadk.runtime.launch import RuntimeLaunchContext
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY
 from ksadk.sessions import SessionEvent
 
 _RUN_TERMINAL_STATUSES = RUN_STATUS_TERMINAL
@@ -77,6 +78,10 @@ class ListSessionEventsActionRequest(BaseModel):
     Limit: int = Field(200, ge=1, le=2000)
     AfterSeqId: Optional[int] = Field(None, ge=0)
     BeforeSeqId: Optional[int] = Field(None, ge=1)
+    EventOrder: Optional[Literal["session_seq"]] = None
+    CursorSource: Optional[Literal["runtime", "control"]] = None
+    HistoryEpoch: Optional[str] = None
+    SnapshotSeqId: Optional[int] = Field(None, ge=0)
 
     @field_validator("CheckpointIds", "EventTypes", mode="before")
     @classmethod
@@ -89,10 +94,13 @@ class ListSessionEventsActionRequest(BaseModel):
 
     @model_validator(mode="after")
     def validate_cursor_scope(self):
-        if self.SessionId is None and (
-            self.AfterSeqId is not None or self.BeforeSeqId is not None
-        ):
+        if self.SessionId is None and (self.AfterSeqId is not None or self.BeforeSeqId is not None):
             raise ValueError("Seq cursors require SessionId")
+        if self.EventOrder == "session_seq":
+            if not str(self.SessionId or "").strip() or self.Offset not in (None, 0):
+                raise ValueError("EventOrder=session_seq requires SessionId and no Offset")
+            if self.CursorSource == "control":
+                raise ValueError("Runtime cannot continue a control cursor")
         return self
 
 
@@ -106,6 +114,9 @@ class ListSessionMessagesActionRequest(BaseModel):
     IncludeReasoning: bool = False
     IncludeToolEvents: bool = False
     IncludeAttachments: bool = True
+    HistoryEpoch: Optional[str] = None
+    CursorSource: Optional[Literal["runtime", "control"]] = None
+    SnapshotSeqId: Optional[int] = Field(None, ge=0)
 
 
 class ListSessionCheckpointsActionRequest(BaseModel):
@@ -152,6 +163,18 @@ class ListToolReceiptsActionRequest(BaseModel):
     Limit: int = Field(200, ge=1, le=500)
 
 
+class GetToolReceiptClaimActionRequest(BaseModel):
+    AgentId: str
+    UserId: Optional[str] = None
+    SessionId: str
+    IdempotencyKey: str
+
+
+class ReconcileToolReceiptClaimActionRequest(GetToolReceiptClaimActionRequest):
+    ClaimId: str
+    Reason: str = Field(..., min_length=1, max_length=1000)
+
+
 class ResumeRunActionRequest(BaseModel):
     AgentId: str
     UserId: Optional[str] = None
@@ -321,6 +344,7 @@ def _split_custom_metadata(
     metadata: Mapping[str, Any] | None,
 ) -> tuple[dict[str, Any], dict[str, Any]]:
     public_metadata = dict(metadata or {})
+    public_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
     runtime_metadata: dict[str, Any] = {}
     agentengine_metadata = public_metadata.get("agentengine")
     public_metadata.pop("agentengine", None)