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

ksadk/events/adapters/_codex_errors.py

@@ -0,0 +1,49 @@
+"""Public Codex retry diagnostics without persisting provider response bodies."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from ._codex_validators import _safe_codex_error_info_kind
+
+
+def codex_http_status(error: Mapping[str, Any]) -> int | None:
+    info = error.get("codexErrorInfo")
+    kind = _safe_codex_error_info_kind(info)
+    detail = info.get(kind) if isinstance(info, Mapping) and kind else None
+    value = detail.get("httpStatusCode") if isinstance(detail, Mapping) else None
+    if isinstance(value, int) and not isinstance(value, bool) and 400 <= value <= 599:
+        return value
+    # Older App Servers put the HTTP status only in the diagnostic string.
+    # Extract the bounded numeric field; never copy that free text into progress.
+    for key in ("message", "additionalDetails"):
+        text = error.get(key)
+        match = (
+            re.search(r"\b(?:HTTP(?: status)?|status code)[:\s]+([45]\d{2})\b", text, re.I)
+            if isinstance(text, str)
+            else None
+        )
+        if match:
+            return int(match.group(1))
+    return None
+
+
+def codex_retry_numbers(message: str, observed: int) -> tuple[int, int | None]:
+    # This exact counter is emitted by Codex itself. It counts retries, not
+    # initial requests, and may reset for the next sampling step in a turn.
+    match = re.fullmatch(r"Reconnecting\.\.\. (\d+)/(\d+)", message)
+    if match:
+        count, maximum = (int(value) for value in match.groups())
+        if 0 < count <= maximum <= 100:
+            return count, maximum
+    return observed, None
+
+
+def codex_error_label(status: int | None) -> str:
+    if status == 429:
+        return "模型限流（HTTP 429）"
+    if status is not None:
+        return f"模型请求失败（HTTP {status}）"
+    return "模型连接中断"

ksadk/events/adapters/_codex_items.py

@@ -42,6 +42,7 @@ from ksadk.events.identity import stable_event_id, stable_item_id, stable_part_i
 
 _CODEX_0_147_0_NOTIFICATION_METHODS = frozenset("""
     account/login/completed account/rateLimits/updated account/updated app/list/updated
+    autoApprovalReview/strictReviewRequired
     command/exec/outputDelta configWarning deprecationNotice error
     externalAgentConfig/import/completed externalAgentConfig/import/progress fs/changed
     fuzzyFileSearch/sessionCompleted fuzzyFileSearch/sessionUpdated guardianWarning
@@ -50,16 +51,23 @@ _CODEX_0_147_0_NOTIFICATION_METHODS = frozenset("""
     item/commandExecution/terminalInteraction item/completed item/fileChange/outputDelta
     item/fileChange/patchUpdated item/mcpToolCall/progress item/plan/delta
     item/reasoning/summaryPartAdded item/reasoning/summaryTextDelta item/reasoning/textDelta
-    item/started mcpServer/oauthLogin/completed mcpServer/startupStatus/updated
-    model/rerouted model/safetyBuffering/updated model/verification process/exited
-    process/outputDelta remoteControl/status/changed serverRequest/resolved skills/changed
-    thread/archived thread/closed thread/compacted thread/deleted thread/goal/cleared
-    thread/environment/connected thread/environment/disconnected
-    thread/goal/updated thread/name/updated thread/realtime/closed thread/realtime/error
+    item/started mcpServer/event/stream/notification mcpServer/oauthLogin/completed
+    mcpServer/startupStatus/updated
+    model/rerouted model/safetyBuffering/updated model/verification
+    modelProvider/authRecoveryCompleted modelProvider/authRecoveryStarted
+    process/exited process/outputDelta project/changed
+    remoteControl/status/changed serverRequest/resolved skills/changed
+    thread/archived thread/attachment/updated thread/closed thread/compacted thread/deleted
+    thread/goal/cleared thread/environment/connected thread/environment/disconnected
+    thread/goal/updated thread/name/updated thread/project/updated thread/queue/changed
+    thread/realtime/closed thread/realtime/error
+    thread/realtime/item/completed thread/realtime/item/started
+    thread/realtime/item/transcript/delta
     thread/realtime/itemAdded thread/realtime/outputAudio/delta thread/realtime/sdp
     thread/realtime/started thread/realtime/transcript/delta thread/realtime/transcript/done
-    thread/settings/updated thread/started thread/status/changed thread/tokenUsage/updated
-    thread/unarchived turn/completed turn/diff/updated turn/moderationMetadata
+    thread/reverted thread/settings/updated thread/started thread/status/changed
+    thread/tokenUsage/updated thread/unarchived turn/completed turn/diff/updated
+    turn/moderationMetadata
     turn/plan/updated turn/started warning windows/worldWritableWarning
     windowsSandbox/setupCompleted
     """.split())

ksadk/events/adapters/_langgraph_support.py

@@ -17,6 +17,7 @@ from ksadk.events.canonical import (
     ItemUpdated,
     RuntimeEvent,
     SourceRef,
+    UsageReported,
 )
 from ksadk.events.content import (
     ContentSnapshot,
@@ -32,6 +33,7 @@ from ksadk.events.identity import (
     stable_part_id,
     stable_scope_id,
 )
+from ksadk.runners.base_runner import BaseRunner
 
 # Native content-block types that carry a tool call identity.
 _TOOL_CALL_BLOCKS = frozenset(
@@ -73,6 +75,7 @@ class LangGraphAdapterContext:
     graph_run_id: str
     initial_seq: int = 0
     checkpoint_ref: Mapping[str, str] | None = None
+    publication_epoch: str | None = None
     _next_seq: int = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
@@ -151,7 +154,10 @@ def _map_data_channel(
     value: Any,
 ) -> tuple[RuntimeEvent, ...]:
     env = _envelope(context, frame.occurrence_key, frame.timestamp)
-    item_id = stable_item_id("langgraph", frame.scope_id, "channel", method, frame.source_seq)
+    item_id = stable_item_id(
+        "langgraph", frame.scope_id, "channel", method, frame.source_seq,
+        *([context.publication_epoch] if context.publication_epoch else []),
+    )
     part_id = _part_id(item_id, "channel", method)
     content = DataContent(part_id=part_id, data=_json_value(value))
     envelope = lambda event_type: env(  # noqa: E731
@@ -423,14 +429,49 @@ def _map_whole_message(
                 ),
             )
         )
+    usage = BaseRunner._message_usage(payload)
+    if usage:
+        usage_item_id = stable_item_id("langgraph", state.scope_id, "$run")
+        emitted.append(
+            UsageReported(
+                **env(
+                    state.scope_id,
+                    state.parent_scope_id,
+                    usage_item_id,
+                    "usage.reported",
+                    "usage",
+                    source,
+                ),
+                input_tokens=usage["input_tokens"],
+                output_tokens=usage["output_tokens"],
+                total_tokens=usage["total_tokens"],
+                cached_tokens=_usage_detail(usage.get("input_token_details"), "cached"),
+                reasoning_tokens=_usage_detail(usage.get("output_token_details"), "reasoning"),
+            )
+        )
     return tuple(emitted)
 
 
+def _usage_detail(details: Any, key: str) -> int:
+    if not isinstance(details, Mapping):
+        return 0
+    value = details.get(key)
+    if value is None and key == "cached":
+        value = details.get("cache_read") or details.get("cached_tokens")
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
 def _envelope(
     context: LangGraphAdapterContext,
     occurrence_key: str,
     timestamp: float,
 ) -> Callable[..., dict[str, Any]]:
+    if context.publication_epoch:
+        occurrence_key = f"{context.publication_epoch}:{occurrence_key}"
+
     def env(
         scope_id: str,
         parent_scope_id: str | None,
@@ -440,6 +481,10 @@ def _envelope(
         source: SourceRef,
         ordinal: int = 0,
     ) -> dict[str, Any]:
+        if context.publication_epoch:
+            source = source.model_copy(update={"metadata": {
+                **source.metadata, "publication_epoch": context.publication_epoch,
+            }})
         return {
             "schema_version": 2,
             "event_id": stable_event_id(

ksadk/events/adapters/a2a.py

@@ -89,6 +89,8 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
     OCCURRENCE_CACHE_LIMIT = 1024
 
     def __init__(self) -> None:
+        self._tool_activities = {}
+        self._tool_activity_bytes = 0
         self._artifacts: dict[str, _ArtifactState] = {}
         self._messages: dict[str, _MessageState] = {}
         self._seen_occurrences: OrderedDict[str, str] = OrderedDict()
@@ -97,8 +99,20 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
         self._run_started = False
         self._run_interrupted = False
         self._active_interaction: tuple[str, str] | None = None
+        self._active_interaction_kind = "structured_input"
         self._terminal_snapshot_fingerprint: str | None = None
 
+    def checkpoint(self, context: A2AAdapterContext):
+        from ksadk.events.adapters._a2a_checkpoint import export_checkpoint
+
+        return export_checkpoint(self, context)
+
+    @classmethod
+    def restore_checkpoint(cls, payload):
+        from ksadk.events.adapters._a2a_checkpoint import restore_checkpoint
+
+        return restore_checkpoint(cls, payload)
+
     def map_event(
         self,
         native_event: object,
@@ -134,6 +148,12 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
                 getattr(native_event, payload_name), context, timestamp=timestamp
             )
         if isinstance(native_event, TaskArtifactUpdateEvent):
+            from ksadk.events.adapters._a2a_tool_activity import map_tool_artifact
+
+            self._validate_identity(native_event.context_id, native_event.task_id, context)
+            public = map_tool_artifact(self, native_event.artifact, context, timestamp)
+            if public is not None:
+                return public
             return self._map_artifact_update(native_event, context, timestamp)
         if isinstance(native_event, TaskStatusUpdateEvent):
             return self._map_status_update(native_event, context, timestamp)
@@ -317,9 +337,7 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
                 "artifact.artifact_id",
                 f"A2A artifact {artifact_id!r} is already closed",
             )
-        item_id = stable_item_id(
-            "a2a", context.context_id, context.task_id, "artifact", artifact_id
-        )
+        item_id = stable_item_id("a2a", *context.item_identity, "artifact", artifact_id)
         source = self._source(
             context,
             occurrence,
@@ -460,14 +478,17 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
         events: list[RuntimeEvent] = []
         if self._active_interaction is not None:
             interaction_id, continuation_id = self._active_interaction
-            events.append(
-                InteractionResolved(
-                    **env(interaction_id, "interaction.resolved", "interaction", len(events)),
-                    interaction_id=interaction_id,
-                    interaction_kind="structured_input",
-                    response=StructuredInputResponse(data={"state": TaskState.Name(state)}),
+            # Remote progress is not evidence of a user's approval decision.
+            # The caller's durable interaction ledger owns that resolution.
+            if self._active_interaction_kind == "structured_input":
+                events.append(
+                    InteractionResolved(
+                        **env(interaction_id, "interaction.resolved", "interaction", len(events)),
+                        interaction_id=interaction_id,
+                        interaction_kind="structured_input",
+                        response=StructuredInputResponse(data={"state": TaskState.Name(state)}),
+                    )
                 )
-            )
             events.append(
                 ContinuationResumed(
                     **env(continuation_id, "continuation.resumed", "continuation", len(events)),
@@ -528,18 +549,19 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
         events: list[RuntimeEvent] = []
         if self._active_interaction is not None:
             previous_interaction_id, _ = self._active_interaction
-            events.append(
-                InteractionResolved(
-                    **env(
-                        previous_interaction_id, "interaction.resolved", "interaction", len(events)
-                    ),
-                    interaction_id=previous_interaction_id,
-                    interaction_kind="structured_input",
-                    response=StructuredInputResponse(
-                        data={"state": "SUPERSEDED_BY_NEW_A2A_INTERACTION"}
-                    ),
+            if self._active_interaction_kind == "structured_input":
+                events.append(
+                    InteractionResolved(
+                        **env(
+                            previous_interaction_id, "interaction.resolved", "interaction", len(events)
+                        ),
+                        interaction_id=previous_interaction_id,
+                        interaction_kind="structured_input",
+                        response=StructuredInputResponse(
+                            data={"state": "SUPERSEDED_BY_NEW_A2A_INTERACTION"}
+                        ),
+                    )
                 )
-            )
             self._active_interaction = None
         self._ensure_run_started(events, context, source, timestamp, occurrence)
         interaction_id = stable_item_id(
@@ -553,12 +575,18 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
         schema = message_metadata.get("input_schema")
         if not isinstance(schema, dict):
             schema = {"type": "object" if state == TaskState.TASK_STATE_AUTH_REQUIRED else "string"}
+        from ksadk.a2a.interaction_wire import parse_approval_metadata
+
+        approval = parse_approval_metadata(message_metadata, call_id=interaction_id)
+        if approval is not None and state != TaskState.TASK_STATE_INPUT_REQUIRED:
+            raise ValueError("A2A_INTERACTION_DECLARATION_INVALID")
+        kind = "approval" if approval is not None else "structured_input"
         events.append(
             InteractionRequested(
                 **env(interaction_id, "interaction.requested", "interaction", len(events)),
                 interaction_id=interaction_id,
-                interaction_kind="structured_input",
-                request=StructuredInputRequest(prompt=prompt, schema=schema),
+                interaction_kind=kind,
+                request=approval or StructuredInputRequest(prompt=prompt, schema=schema),
             )
         )
         events.append(
@@ -582,6 +610,7 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
             )
             self._run_interrupted = True
         self._active_interaction = (interaction_id, continuation_id)
+        self._active_interaction_kind = kind
         return tuple(events)
 
     def _map_awaiting_terminal_status(
@@ -684,9 +713,7 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
 
     @staticmethod
     def _message_item_id(context: A2AAdapterContext, message_id: str) -> str:
-        if context.task_id is not None:
-            return stable_item_id("a2a", context.context_id, context.task_id, "message", message_id)
-        return stable_item_id("a2a", context.context_id, "message", message_id)
+        return stable_item_id("a2a", *context.item_identity, "message", message_id)
 
     @staticmethod
     def _require_task_status(task: Task) -> None:
@@ -752,6 +779,7 @@ class A2AEventAdapter(_A2ATaskSnapshotMixin):
             "timestamp": timestamp,
             "run_id": context.run_id,
             "scope_id": context.scope_id,
+            "parent_scope_id": context.parent_scope_id,
             "source": source,
         }
 

ksadk/events/adapters/adk.py

@@ -1,9 +1,10 @@
-"""Google ADK 2.6.3+ events to canonical RuntimeEvent schema v2."""
+"""Google ADK events to canonical RuntimeEvent schema v2."""
 
 from __future__ import annotations
 
 from collections import defaultdict
 from dataclasses import dataclass, field
+from importlib.metadata import version
 from typing import Any, TypeAlias, cast
 
 from google.adk.events import Event
@@ -37,6 +38,7 @@ class ADKAdapterContext:
 
     run_id: str
     initial_seq: int = 1
+    max_native_events: int = 32768
     _next_seq: int = field(init=False, repr=False)
     _ordinals: dict[_OrdinalKey, int] = field(
         default_factory=lambda: defaultdict(int), init=False, repr=False
@@ -44,14 +46,29 @@ class ADKAdapterContext:
     _open_items: set[_ItemKey] = field(default_factory=set, init=False, repr=False)
     _open_item_kinds: dict[_ItemKey, ItemKind] = field(default_factory=dict, init=False, repr=False)
     _completed_items: set[_ItemKey] = field(default_factory=set, init=False, repr=False)
+    _remote_completed_text: dict[_ItemKey, str] = field(
+        default_factory=dict, init=False, repr=False
+    )
     _output_refs: list[OutputRef] = field(default_factory=list, init=False, repr=False)
     _output_replacement_items: set[_ItemKey] = field(default_factory=set, init=False, repr=False)
+    _active_text_items: dict[tuple[str, str], str] = field(
+        default_factory=dict, init=False, repr=False
+    )
+    _pending_text: dict[_ItemKey, tuple[dict[str, Any], str]] = field(
+        default_factory=dict, init=False, repr=False
+    )
+    _partial_deliveries: int = field(default=0, init=False, repr=False)
+    _seen_native_events: set[tuple[str, str, str]] = field(
+        default_factory=set, init=False, repr=False
+    )
 
     def __post_init__(self) -> None:
         if not self.run_id.strip():
             raise ValueError("ADK adapter run_id must not be empty")
         if self.initial_seq < 0:
             raise ValueError("ADK adapter initial_seq must be non-negative")
+        if self.max_native_events <= 0:
+            raise ValueError("ADK adapter max_native_events must be positive")
         self._next_seq = self.initial_seq
 
     def allocate_seq(self) -> int:
@@ -96,6 +113,7 @@ class ADKAdapterContext:
     def mark_completed(self, key: _ItemKey, *, output: bool) -> None:
         self._open_items.discard(key)
         self._open_item_kinds.pop(key, None)
+        self._pending_text.pop(key, None)
         self._completed_items.add(key)
         if output:
             if key in self._output_replacement_items:
@@ -106,21 +124,88 @@ class ADKAdapterContext:
     def mark_output_replacement(self, key: _ItemKey) -> None:
         self._output_replacement_items.add(key)
 
+    def accept_native_event(
+        self, native_run_id: str, path_key: str, native_event_id: str, *, deduplicate: bool = True
+    ) -> bool:
+        key = (native_run_id, path_key, native_event_id)
+        if deduplicate and key in self._seen_native_events:
+            return False
+        if len(self._seen_native_events) + self._partial_deliveries >= self.max_native_events:
+            raise ValueError("ADK native event budget exceeded")
+        if deduplicate:
+            self._seen_native_events.add(key)
+        else:
+            self._partial_deliveries += 1
+        return True
+
+    def resolve_text_item(self, scope_id: str, lane: str, candidate_item_id: str) -> str:
+        """Reuse the open ADK response lane across per-chunk native Event IDs."""
+
+        return self._active_text_items.get((scope_id, lane), candidate_item_id)
+
+    def mark_text_started(self, key: _ItemKey, lane: str, item_kind: ItemKind) -> None:
+        self.mark_started(key, item_kind)
+        self._active_text_items[(key[0], lane)] = key[1]
+
+    def mark_text_completed(self, key: _ItemKey, lane: str, *, output: bool) -> None:
+        active_key = (key[0], lane)
+        if self._active_text_items.get(active_key) == key[1]:
+            self._active_text_items.pop(active_key, None)
+        self.mark_completed(key, output=output)
+
     def mark_failed(self, key: _ItemKey) -> None:
         self._open_items.discard(key)
         self._open_item_kinds.pop(key, None)
+        self._pending_text.pop(key, None)
         self._output_replacement_items.discard(key)
+        for active_key, active_item_id in tuple(self._active_text_items.items()):
+            if active_key[0] == key[0] and active_item_id == key[1]:
+                self._active_text_items.pop(active_key, None)
 
 
 class ADKEventAdapter:
     """Map ADK native response identities without author/text inference."""
 
+    def __init__(self, *, partial_ids_identify_response: bool | None = None):
+        if partial_ids_identify_response is None:
+            release = tuple(int(part) for part in version("google-adk").split(".")[:2])
+            partial_ids_identify_response = release >= (2, 6)
+        self._partial_ids_identify_response = partial_ids_identify_response
+
     def map(self, event: Event, context: ADKAdapterContext) -> tuple[RuntimeEvent, ...]:
+        if getattr(event, "_canonical", None) is not None:
+            # Only our in-process event type can carry an already persisted
+            # fact. Public custom_metadata cannot opt into this bypass.
+            from ksadk.a2a.adk import canonical_event_from_adk
+
+            canonical = canonical_event_from_adk(event)
+            if canonical is not None:
+                if canonical.run_id != context.run_id or canonical.event_type.startswith("run."):
+                    raise ValueError("A2A_CANONICAL_REFERENCE_CONFLICT")
+                if not context.accept_native_event(
+                    canonical.run_id, canonical.scope_id, canonical.event_id
+                ):
+                    return ()
+                context._next_seq = max(context.next_seq, canonical.seq + 1)
+                return (canonical,)
         native_event_id = _required_string(getattr(event, "id", None), "event id")
         native_run_id = _required_string(getattr(event, "invocation_id", None), "invocation id")
         path = str(getattr(getattr(event, "node_info", None), "path", "") or "")
         branch = str(getattr(event, "branch", "") or "")
         path_key = path or branch or "$root"
+        # ADK >= 2.6 reuses one response ID for every transient partial and
+        # its aggregate. These partials are not persisted by native sessions;
+        # their ordered deliveries, including equal text, must remain distinct.
+        # Canonical references and A2A artifact observations keep their own IDs.
+        shared_partial = (
+            self._partial_ids_identify_response
+            and bool(getattr(event, "partial", False))
+            and not (getattr(event, "custom_metadata", None) or {}).get("ksadk_a2a_stream")
+        )
+        if not context.accept_native_event(
+            native_run_id, path_key, native_event_id, deduplicate=not shared_partial
+        ):
+            return ()
         scope_id = stable_scope_id("adk", native_run_id, path_key)
         source_metadata: dict[str, JsonValue] = {"path": path, "path_key": path_key}
         author = str(getattr(event, "author", "") or "")
@@ -144,30 +229,49 @@ class ADKEventAdapter:
             ),
         }
         is_partial = bool(getattr(event, "partial", False))
-        for lane in ("reasoning", "message"):
-            text = text_by_lane[lane]
-            if not text:
-                continue
-            mapped.extend(
-                self._map_text_lane(
-                    event=event,
-                    context=context,
-                    native_event_id=native_event_id,
-                    native_run_id=native_run_id,
-                    path_key=path_key,
-                    scope_id=scope_id,
-                    source_metadata=source_metadata,
-                    lane=cast("_TextLane", lane),
-                    text=text,
-                    partial=is_partial,
-                    replace=any(
-                        getattr(part, "text", None)
-                        and bool(getattr(part, "thought", False)) == (lane == "reasoning")
-                        and _metadata_flag(part, "ksadk_output_snapshot")
-                        for part in parts
+        observations = (getattr(event, "custom_metadata", None) or {}).get("ksadk_a2a_stream") or [
+            None
+        ]
+        for remote in observations:
+            remote_item_id = None
+            if remote is not None:
+                remote_item_id = stable_item_id(
+                    "a2a", str(remote["task_id"]), str(remote["artifact_id"])
+                )
+            for lane in ("reasoning", "message"):
+                text = remote["text"][lane] if remote else text_by_lane[lane]
+                candidate_key = (
+                    scope_id,
+                    stable_item_id(
+                        "adk", native_run_id, path_key, remote_item_id or native_event_id, lane
                     ),
                 )
-            )
+                if not text and not (remote and context.is_open(candidate_key)):
+                    continue
+                mapped.extend(
+                    self._map_text_lane(
+                        event=event,
+                        context=context,
+                        native_event_id=native_event_id,
+                        native_run_id=native_run_id,
+                        path_key=path_key,
+                        scope_id=scope_id,
+                        source_metadata=source_metadata,
+                        lane=cast("_TextLane", lane),
+                        text=text,
+                        partial=(not remote["snapshot"]) if remote else is_partial,
+                        native_item_id=remote_item_id,
+                        close_at_end=bool(remote["last_chunk"]) if remote else False,
+                        replace=(not remote["append"])
+                        if remote
+                        else any(
+                            getattr(part, "text", None)
+                            and bool(getattr(part, "thought", False)) == (lane == "reasoning")
+                            and _metadata_flag(part, "ksadk_output_snapshot")
+                            for part in parts
+                        ),
+                    )
+                )
 
         if not is_partial:
             for part in parts:
@@ -207,6 +311,24 @@ class ADKEventAdapter:
                     )
         return tuple(mapped)
 
+    def finish(self, context: ADKAdapterContext) -> tuple[RuntimeEvent, ...]:
+        """Close a partial reasoning lane omitted from the terminal response."""
+
+        mapped: list[RuntimeEvent] = []
+        for _key, (kwargs, text) in list(context._pending_text.items()):
+            if (kwargs["lane"] == "reasoning" and not kwargs.get("native_item_id")) or kwargs.get(
+                "close_at_end", False
+            ):
+                mapped.extend(
+                    self._map_text_lane(
+                        **kwargs,
+                        text=text,
+                        partial=False,
+                        replace=False,
+                    )
+                )
+        return tuple(mapped)
+
     def _map_text_lane(
         self,
         *,
@@ -221,10 +343,21 @@ class ADKEventAdapter:
         text: str,
         partial: bool,
         replace: bool,
+        native_item_id: str | None = None,
+        close_at_end: bool = False,
     ) -> list[RuntimeEvent]:
-        item_id = stable_item_id("adk", native_run_id, path_key, native_event_id, lane)
+        candidate_item_id = stable_item_id(
+            "adk", native_run_id, path_key, native_item_id or native_event_id, lane
+        )
+        item_id = (
+            candidate_item_id
+            if native_item_id
+            else context.resolve_text_item(scope_id, lane, candidate_item_id)
+        )
         key = (scope_id, item_id)
         if context.is_completed(key):
+            if native_item_id and context._remote_completed_text.get(key) != text:
+                raise ValueError("A2A_TERMINAL_CONTENT_CONFLICT")
             return []
         part_id = f"{lane}.text"
         item_kind: ItemKind = "reasoning" if lane == "reasoning" else "message"
@@ -232,8 +365,11 @@ class ADKEventAdapter:
         source = _source(
             native_event_id=native_event_id,
             native_run_id=native_run_id,
-            native_item_id=native_event_id,
-            metadata=source_metadata,
+            native_item_id=native_item_id or native_event_id,
+            metadata={
+                **source_metadata,
+                **({"ksadk_output_snapshot": True} if replace and not native_item_id else {}),
+            },
         )
         mapped: list[RuntimeEvent] = []
         if not context.is_open(key):
@@ -254,11 +390,30 @@ class ADKEventAdapter:
                     phase=phase,
                 )
             )
-            context.mark_started(key, item_kind)
+            if native_item_id:
+                context.mark_started(key, item_kind)
+            else:
+                context.mark_text_started(key, lane, item_kind)
         content = TextContent(part_id=part_id, text=text)
-        if replace and lane == "message":
+        if replace and lane == "message" and not native_item_id:
             context.mark_output_replacement(key)
         if partial:
+            previous = context._pending_text.get(key, ({}, ""))[1]
+            context._pending_text[key] = (
+                {
+                    "event": event,
+                    "context": context,
+                    "native_event_id": native_event_id,
+                    "native_run_id": native_run_id,
+                    "path_key": path_key,
+                    "scope_id": scope_id,
+                    "source_metadata": source_metadata,
+                    "lane": lane,
+                    "native_item_id": native_item_id,
+                    "close_at_end": close_at_end,
+                },
+                ("" if replace else previous) + text,
+            )
             mapped.append(
                 ItemUpdated(
                     **_envelope(
@@ -295,9 +450,12 @@ class ADKEventAdapter:
                     snapshot=ContentSnapshot(parts=(content,)),
                 )
             )
-            context.mark_completed(
+            if native_item_id:
+                context._remote_completed_text[key] = text
+            context.mark_text_completed(
                 key,
-                output=lane == "message" and event.is_final_response(),
+                lane,
+                output=lane == "message" and (bool(native_item_id) or event.is_final_response()),
             )
         return mapped