agentengine-sdk-python 0.8.5__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/_langgraph_support.py

@@ -75,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:
@@ -153,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
@@ -465,6 +469,9 @@ def _envelope(
     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,
@@ -474,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
 

ksadk/events/adapters/codex.py

@@ -9,6 +9,11 @@ from collections import OrderedDict
 from collections.abc import Iterable, Mapping, Sequence
 from typing import Any, Callable
 
+from ksadk.events.adapters._codex_errors import (
+    codex_error_label,
+    codex_http_status,
+    codex_retry_numbers,
+)
 from ksadk.events.adapters._codex_interactions import _CodexInteractionMixin
 from ksadk.events.adapters._codex_items import (
     _CODEX_0_147_0_NOTIFICATION_METHODS,
@@ -80,6 +85,7 @@ class CodexEventAdapter(_CodexInteractionMixin):
     def __init__(self, *, known_thread_ids: Iterable[str] = ()) -> None:
         self._items: dict[tuple[str, str], _ItemState] = {}
         self._active_turns: set[str] = set()
+        self._retry_counts: dict[str, int] = {}
         self._completed_items: dict[str, list[OutputRef]] = {}
         self._interactions: dict[str, _InteractionState] = {}
         self._thread_continuations: dict[str, str] = {
@@ -632,11 +638,19 @@ class CodexEventAdapter(_CodexInteractionMixin):
         elif status == "failed":
             error = _mapping(turn.get("error"), "params.turn.error")
             message = _required_text(error.get("message"), "params.turn.error.message")
+            http_status = codex_http_status(error)
+            retry_count = self._retry_counts.get(scope_id, 0)
+            if http_status is not None:
+                outcome = f"自动重试 {retry_count} 次后仍失败" if retry_count else "本次请求失败"
+                message = f"{codex_error_label(http_status)}，{outcome}，请稍后重试。"
+                source = source.model_copy(update={"metadata": {
+                    **source.metadata, "status_code": http_status, "retry_count": retry_count,
+                }})
             terminal = RunFailed(
                 **env(scope_id, turn_id, "run.failed", "run", source),
                 status="failed",
                 error=ErrorInfo(
-                    code="codex_turn_failed",
+                    code="MODEL_RATE_LIMITED" if http_status == 429 else "codex_turn_failed",
                     message=message,
                     source="codex",
                     scope_id=scope_id,
@@ -656,6 +670,7 @@ class CodexEventAdapter(_CodexInteractionMixin):
                 f"Unsupported terminal Codex turn status: {status}",
             )
         self._active_turns.remove(scope_id)
+        self._retry_counts.pop(scope_id, None)
         self._completed_items.pop(scope_id, None)
         return (terminal,)
 
@@ -735,7 +750,7 @@ class CodexEventAdapter(_CodexInteractionMixin):
         cursor: str,
     ) -> tuple[RuntimeEvent, ...]:
         error = _mapping(params.get("error"), "params.error")
-        _required_text(error.get("message"), "params.error.message")
+        native_message = _required_text(error.get("message"), "params.error.message")
         will_retry = params.get("willRetry")
         if not isinstance(will_retry, bool):
             _fail(
@@ -750,11 +765,26 @@ class CodexEventAdapter(_CodexInteractionMixin):
             turn_id=turn_id,
             native_item_id=None,
         )
+        http_status = codex_http_status(error)
+        observed = self._retry_counts.get(scope_id, 0)
+        if will_retry:
+            observed += 1
+            self._retry_counts[scope_id] = observed
+        count, maximum = codex_retry_numbers(native_message, observed)
+        counter = f"{count}/{maximum}" if maximum else str(count)
+        public_message = (
+            f"{codex_error_label(http_status)}，正在自动重试（第 {counter} 次）"
+            if will_retry
+            else f"{codex_error_label(http_status)}，自动重试已停止"
+        )
         source = base.model_copy(
             update={
                 "metadata": {
                     **base.metadata,
                     "will_retry": will_retry,
+                    "status_code": http_status,
+                    "retry_count": count,
+                    "max_retries": maximum,
                     "error_message_present": True,
                     "additional_details_present": error.get("additionalDetails") is not None,
                     "codex_error_info_present": error.get("codexErrorInfo") is not None,
@@ -774,11 +804,7 @@ class CodexEventAdapter(_CodexInteractionMixin):
                     source,
                 ),
                 status="running",
-                message=(
-                    "Codex reported a retryable turn error"
-                    if will_retry
-                    else "Codex reported a non-retryable turn error"
-                ),
+                message=public_message,
             ),
         )