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

ksadk/a2a/build_validation.py

@@ -0,0 +1,147 @@
+"""Static, side-effect-free validation for code-first A2A exposure plans."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+_SKIP_DIRS = frozenset({".agentengine", ".git", ".venv", "venv", "__pycache__"})
+
+
+def _call_name(node: ast.AST) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""
+
+
+def _string_value(node: ast.AST, constants: dict[str, str]) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    if isinstance(node, ast.Name):
+        return constants.get(node.id)
+    return None
+
+
+def _assignment(statement: ast.stmt) -> tuple[str, ast.AST] | None:
+    if isinstance(statement, ast.Assign) and len(statement.targets) == 1:
+        target = statement.targets[0]
+        if isinstance(target, ast.Name):
+            return target.id, statement.value
+    if isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name):
+        if statement.value is not None:
+            return statement.target.id, statement.value
+    return None
+
+
+def _spec_from_call(call: ast.Call, constants: dict[str, str]) -> dict[str, str] | None:
+    if _call_name(call.func) != "RemoteAgentSpec":
+        return None
+    values: dict[str, str] = {}
+    for keyword in call.keywords:
+        if keyword.arg in {"local_name", "binding_id", "target_agent_id", "exposure"}:
+            value = _string_value(keyword.value, constants)
+            if value is not None:
+                values[keyword.arg] = value
+    if "target_agent_id" not in values:
+        return None
+    values.setdefault("local_name", "<unknown>")
+    values.setdefault("binding_id", "<unknown>")
+    values.setdefault("exposure", "auto")
+    return values
+
+
+def _resolve_plan_entries(
+    expression: ast.AST,
+    *,
+    constants: dict[str, str],
+    specs: dict[str, dict[str, str]],
+) -> list[dict[str, str]] | None:
+    if not isinstance(expression, (ast.List, ast.Tuple)):
+        return None
+    resolved: list[dict[str, str]] = []
+    for element in expression.elts:
+        if isinstance(element, ast.Name) and element.id in specs:
+            resolved.append(specs[element.id])
+            continue
+        if isinstance(element, ast.Call):
+            spec = _spec_from_call(element, constants)
+            if spec is not None:
+                resolved.append(spec)
+                continue
+        return None
+    return resolved
+
+
+def _top_level_calls(statement: ast.stmt) -> tuple[ast.Call, ...]:
+    value: ast.AST | None = None
+    if isinstance(statement, ast.Expr):
+        value = statement.value
+    else:
+        assignment = _assignment(statement)
+        if assignment is not None:
+            value = assignment[1]
+    return (value,) if isinstance(value, ast.Call) else ()
+
+
+def _validate_file(path: Path, project_dir: Path) -> None:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
+    except (OSError, SyntaxError, UnicodeDecodeError):
+        return
+
+    constants: dict[str, str] = {}
+    for statement in tree.body:
+        assignment = _assignment(statement)
+        if assignment is None:
+            continue
+        name, value = assignment
+        resolved = _string_value(value, constants)
+        if resolved is not None:
+            constants[name] = resolved
+
+    specs: dict[str, dict[str, str]] = {}
+    for statement in tree.body:
+        assignment = _assignment(statement)
+        if assignment is None:
+            continue
+        name, value = assignment
+        if isinstance(value, ast.Call):
+            spec = _spec_from_call(value, constants)
+            if spec is not None:
+                specs[name] = spec
+
+    for statement in tree.body:
+        for call in _top_level_calls(statement):
+            if _call_name(call.func) != "compile_exposure_plan" or not call.args:
+                continue
+            entries = _resolve_plan_entries(call.args[0], constants=constants, specs=specs)
+            if entries is None:
+                continue
+            by_target: dict[str, dict[str, str]] = {}
+            for entry in entries:
+                target = entry["target_agent_id"]
+                previous = by_target.get(target)
+                if previous is None:
+                    by_target[target] = entry
+                    continue
+                relative = path.relative_to(project_dir).as_posix()
+                raise ValueError(
+                    "A2A_EXPOSURE_CONFLICT: "
+                    f"{relative}:{call.lineno} target {target!r} is declared by "
+                    f"{previous['local_name']!r}/{previous['exposure']!r} and "
+                    f"{entry['local_name']!r}/{entry['exposure']!r}"
+                )
+
+
+def validate_a2a_exposure_sources(project_dir: Path) -> None:
+    """Reject statically resolvable duplicate targets without importing agent code."""
+    project_dir = Path(project_dir).resolve()
+    for path in sorted(project_dir.rglob("*.py")):
+        if any(part in _SKIP_DIRS for part in path.relative_to(project_dir).parts):
+            continue
+        _validate_file(path, project_dir)
+
+
+__all__ = ["validate_a2a_exposure_sources"]

ksadk/a2a/card.py

@@ -1,15 +1,23 @@
-"""Compatibility exports for the lightweight shared AgentCard builder."""
-
-from ksadk.a2a_card import (
-    A2A_PROTOCOL_VERSION,
-    JSONRPC_PATH,
-    REST_PATH_PREFIX,
-    build_agent_card,
-)
-
-__all__ = [
-    "A2A_PROTOCOL_VERSION",
-    "JSONRPC_PATH",
-    "REST_PATH_PREFIX",
-    "build_agent_card",
-]
+"""AgentCard builder with opt-in public tool producer advertisement."""
+
+from ksadk.a2a.presentation import A2A_TOOL_ACTIVITY_EXTENSION_URI
+from ksadk.a2a_card import A2A_PROTOCOL_VERSION, JSONRPC_PATH, REST_PATH_PREFIX
+from ksadk.a2a_card import build_agent_card as _build_agent_card
+
+
+def build_agent_card(*, public_tool_policy=None, **kwargs):
+    card = _build_agent_card(**kwargs)
+    if public_tool_policy is not None and public_tool_policy.tools:
+        from a2a.types import AgentExtension
+
+        card.capabilities.extensions.append(
+            AgentExtension(
+                uri=A2A_TOOL_ACTIVITY_EXTENSION_URI,
+                description="Explicitly allowlisted public tool observations",
+                required=False,
+            )
+        )
+    return card
+
+
+__all__ = ["A2A_PROTOCOL_VERSION", "JSONRPC_PATH", "REST_PATH_PREFIX", "build_agent_card"]

ksadk/a2a/codex.py

@@ -0,0 +1,160 @@
+"""Fixed Codex experts using native tool identities and the shared A2A service."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import time
+from contextlib import aclosing
+from dataclasses import dataclass
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.a2a.exposure import compile_exposure_plan
+from ksadk.a2a.invocation_types import (
+    A2AInvocationContext, A2AInvocationHandle, A2AInvocationMessage,
+    A2AInvocationRequest, RemoteAgentSpec,
+)
+from ksadk.a2a.presentation import ScopeTriggerRef
+from ksadk.a2a.result_text import select_terminal_reply
+from ksadk.a2a.runtime_input import invoke_with_input
+from ksadk.events.content import TextContent, ToolCallContent
+from ksadk.events.identity import stable_item_id
+
+
+class CodexToolCall(BaseModel):
+    """The app-server item/tool/call request, never model-selected identity."""
+    model_config = ConfigDict(frozen=True, extra="forbid", populate_by_name=True)
+    thread_id: str = Field(alias="threadId", min_length=1)
+    turn_id: str = Field(alias="turnId", min_length=1)
+    call_id: str = Field(alias="callId", min_length=1)
+    tool: str = Field(min_length=1)
+    namespace: None = None
+    arguments: dict
+
+
+@dataclass(frozen=True)
+class CodexExpertInvocation:
+    request: A2AInvocationRequest
+    trigger: ScopeTriggerRef
+    service: object
+
+
+class CodexInvocationContextProvider:
+    def __init__(self, *, authority, service_for_space, caller_agent_id, clock=time.time, require_durable=False):
+        self.authority, self.services = authority, service_for_space
+        self.caller, self.clock = caller_agent_id, clock
+        self.require_durable = require_durable
+
+    async def resolve(self, spec, call):
+        authority = self.authority
+        authority.require_session(authority.session_id)
+        triggers = set()
+        for event in await authority.list(authority.session_id):
+            source = event.source
+            if (source.framework != "codex" or source.native_run_id != call.turn_id
+                    or source.native_item_id != call.call_id
+                    or source.metadata.get("thread_id") != call.thread_id
+                    or source.metadata.get("turn_id") != call.turn_id):
+                continue
+            snapshot = getattr(event, "initial", None) or getattr(event, "snapshot", None)
+            if snapshot is None or getattr(event, "item_kind", None) != "tool_call":
+                continue
+            for part in snapshot.parts:
+                if (isinstance(part, ToolCallContent) and part.call_id == call.call_id
+                        and part.name == spec.local_name
+                        and part.arguments == {"arguments": call.arguments, "namespace": None}):
+                    triggers.add((event.scope_id, event.item_id, part.call_id))
+        if len(triggers) != 1:
+            raise ValueError("A2A_CODEX_NATIVE_TRIGGER_NOT_PERSISTED")
+        scope, item, native_call = next(iter(triggers))
+        trigger = ScopeTriggerRef(scope_id=scope, item_id=item, call_id=native_call)
+        handle = A2AInvocationHandle(
+            run_id=authority.run_id, session_id=authority.session_id,
+            parent_scope_id=scope, call_id=native_call, binding_id=spec.binding_id,
+            target_agent_id=spec.target_agent_id,
+            attempt_id=stable_item_id("a2a", scope, item, "attempt-1"),
+        )
+        service = self.services(spec.space_id)
+        if inspect.isawaitable(service):
+            service = await service
+        if self.require_durable and not service.durable_recovery_available:
+            raise ValueError("A2A_CODEX_DURABLE_SERVICE_REQUIRED")
+        original = await service.original_request(handle)
+        message = call.arguments["message"]
+        if original is not None:
+            if (original.spec != spec or original.context.caller_agent_id != self.caller
+                    or original.message.text_parts != (message,)):
+                raise ValueError("A2A_RECOVERED_BINDING_CONFLICT")
+            return CodexExpertInvocation(original, trigger, service)
+        request = A2AInvocationRequest(
+            spec=spec, handle=handle,
+            message=A2AInvocationMessage(message_id=stable_item_id("a2a", handle.scope_id, "initial-message"), text_parts=(message,)),
+            context=A2AInvocationContext(caller_agent_id=self.caller, audit_id=stable_item_id("a2a", handle.scope_id, "audit")),
+            deadline_unix_seconds=float(self.clock()) + (spec.timeout_seconds or 300.0),
+            idempotency_token=stable_item_id("a2a", handle.scope_id, "initial-send"),
+        )
+        return CodexExpertInvocation(request, trigger, service)
+
+
+@dataclass(frozen=True)
+class CodexExpert:
+    spec: RemoteAgentSpec
+
+    def __post_init__(self):
+        spec = RemoteAgentSpec.model_validate(self.spec.model_dump())
+        compile_exposure_plan([spec], framework="codex", consumer_id=spec.local_name)
+        object.__setattr__(self, "spec", spec)
+
+    def tool_spec(self):
+        """Pinned app-server experimental dynamicTools function declaration."""
+        return {"type": "function", "name": self.spec.local_name,
+                "description": self.spec.description or "Ask this fixed remote expert and receive its result.",
+                "inputSchema": {"type": "object", "properties": {"message": {"type": "string", "minLength": 1}},
+                                "required": ["message"], "additionalProperties": False}}
+
+    async def invoke(self, call, *, provider: CodexInvocationContextProvider, emit,
+                     before_invoke=None):
+        call = CodexToolCall.model_validate(call.model_dump() if isinstance(call, CodexToolCall) else call)
+        if call.tool != self.spec.local_name or set(call.arguments) != {"message"}:
+            raise ValueError("A2A_FIXED_TARGET_ARGUMENT_INVALID")
+        if not isinstance(call.arguments["message"], str) or not call.arguments["message"].strip():
+            raise ValueError("A2A_MESSAGE_REQUIRED")
+        invocation = await provider.resolve(self.spec, call)
+        if before_invoke is not None:
+            await before_invoke(call)
+        service, request, trigger = invocation.service, invocation.request, invocation.trigger
+        texts, kinds = {}, {}
+        try:
+            async with aclosing(invoke_with_input(service, request, trigger_ref=trigger)) as events:
+                async for event in events:
+                    published = emit(event)
+                    if inspect.isawaitable(published):
+                        await published
+                    if event.event_type == "item.completed" and event.item_kind in {"message", "artifact"}:
+                        key = (event.scope_id, event.item_id)
+                        kinds[key] = event.item_kind
+                        texts[key] = {part.part_id: part.text for part in event.snapshot.parts if isinstance(part, TextContent)}
+        except (asyncio.CancelledError, TimeoutError):
+            try:
+                handle = service.handle(request.scope_id)
+            except KeyError:
+                pass
+            else:
+                await asyncio.shield(service.cancel(handle))
+            raise
+        snapshot = service.snapshot(service.handle(request.scope_id))
+        if snapshot is None:
+            raise RuntimeError("A2A_INVOCATION_NOT_COMPLETED")
+        result = {"ok": snapshot.status == "completed", "state": snapshot.status,
+                  "reply": select_terminal_reply(snapshot.output_refs, texts, kinds)}
+        return {"success": result["ok"], "contentItems": [{"type": "inputText", "text": json.dumps(result, ensure_ascii=False)}]}
+
+
+def codex_expert(spec: RemoteAgentSpec) -> CodexExpert:
+    return CodexExpert(spec)
+
+
+def compile_codex_experts(specs):
+    plan = compile_exposure_plan(specs, framework="codex", consumer_id="codex")
+    return tuple(codex_expert(entry.spec) for entry in plan.entries)

ksadk/a2a/codex_checkpoint.py

@@ -0,0 +1,111 @@
+"""Save native expert recovery inputs before allowing an outbound invocation."""
+
+import asyncio
+
+from ksadk.a2a.codex import CodexToolCall
+
+
+class CodexCheckpointUnavailable(RuntimeError):
+    def __init__(self, thread_id):
+        super().__init__("A2A_CODEX_CHECKPOINT_UNAVAILABLE")
+        self.thread_id = thread_id
+
+
+class CodexCheckpointWriter:
+    def __init__(self, *, client, authority, request, experts, recovery=None):
+        if request.session_id != authority.session_id:
+            raise ValueError("A2A_CODEX_CHECKPOINT_SESSION_CONFLICT")
+        self.client, self.authority = client, authority
+        self.start_request = request.model_dump(mode="json")
+        self.bindings = {
+            name: expert.spec.model_dump(mode="json") for name, expert in experts.items()
+        }
+        self.calls = {
+            (call.thread_id, call.turn_id, call.call_id): call
+            for call in (recovery.calls if recovery is not None else ())
+        }
+        self.lock = asyncio.Lock()
+
+    async def before_invoke(self, call):
+        try:
+            await self.save(call)
+        except Exception:
+            raise CodexCheckpointUnavailable(call.thread_id) from None
+
+    async def mark_continuation_started(self):
+        if not self.calls:
+            raise ValueError("A2A_CODEX_RECOVERY_CALL_REQUIRED")
+        call = next(iter(self.calls.values()))
+        try:
+            await self.save(call, continuation_started=True)
+        except Exception:
+            raise CodexCheckpointUnavailable(call.thread_id) from None
+
+    async def completed_turn(self, event):
+        """Commit terminal history before Kernel may publish run.completed."""
+        from ksadk.a2a.codex_session_checkpoint import CodexSessionCheckpoint
+
+        thread_id, turn_id = event.source.metadata.get("thread_id"), event.source.native_run_id
+        try:
+            async with self.lock:
+                rollout = await self.client.capture_completed_a2a_rollout(thread_id, turn_id)
+                checkpoint = CodexSessionCheckpoint.model_validate({
+                    "schema": "codex.a2a.session/v1",
+                    **self.authority.runtime_checkpoint_identity(),
+                    "run_id": self.authority.run_id,
+                    "session_id": self.authority.session_id,
+                    "thread_id": thread_id,
+                    "turn_id": turn_id,
+                    "start_request": self.start_request,
+                    "bindings": self.bindings,
+                    "rollout": rollout.model_dump(mode="json"),
+                    "terminal_event": event.model_dump(mode="json"),
+                })
+                await self.authority.save_runtime_checkpoint(
+                    checkpoint.model_dump(mode="json", by_alias=True)
+                )
+        except Exception:
+            raise CodexCheckpointUnavailable(thread_id) from None
+
+    async def save(self, call, *, continuation_started=False):
+        call = CodexToolCall.model_validate(call)
+        if call.tool not in self.bindings:
+            raise ValueError("A2A_CODEX_CHECKPOINT_BINDING_UNKNOWN")
+        async with self.lock:
+            key = (call.thread_id, call.turn_id, call.call_id)
+            previous = self.calls.get(key)
+            if previous is not None and previous != call:
+                raise ValueError("A2A_CODEX_CHECKPOINT_CALL_CONFLICT")
+            calls = dict(self.calls)
+            calls[key] = call
+            rollout = await self.client.capture_a2a_rollout(call)
+            for known in calls.values():
+                if known.thread_id != rollout.thread_id:
+                    raise ValueError("A2A_CODEX_CHECKPOINT_THREAD_CONFLICT")
+                rollout.require_call(
+                    turn_id=known.turn_id,
+                    call_id=known.call_id,
+                    tool=known.tool,
+                    arguments=known.arguments,
+                )
+            if continuation_started and any(
+                rollout.function_output(known.call_id) is None for known in calls.values()
+            ):
+                raise ValueError("A2A_CODEX_RECOVERY_OUTPUT_REQUIRED")
+            await self.authority.save_runtime_checkpoint(
+                {
+                    "schema": "codex.a2a.native/v1",
+                    **({"continuation_started": True} if continuation_started else {}),
+                    **self.authority.runtime_checkpoint_identity(),
+                    "run_id": self.authority.run_id,
+                    "session_id": self.authority.session_id,
+                    "thread_id": call.thread_id,
+                    "start_request": self.start_request,
+                    "bindings": self.bindings,
+                    "calls": [
+                        calls[key].model_dump(mode="json", by_alias=True) for key in sorted(calls)
+                    ],
+                    "rollout": rollout.model_dump(mode="json"),
+                }
+            )
+            self.calls = calls

ksadk/a2a/codex_recovery.py

@@ -0,0 +1,96 @@
+"""Validate private recovery state before native restore or remote access."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ksadk.a2a.codex import CodexToolCall
+from ksadk.a2a.invocation_types import RemoteAgentSpec
+from ksadk.codex.rollout_checkpoint import NativeRolloutCheckpoint
+from ksadk.kernel.state import RunState
+from ksadk.runtime.adapter import RunHandle, StartRequest
+from ksadk.runtime.executor import handle_digest
+
+
+class CodexRecoveryCheckpoint(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
+
+    schema_version: Literal["codex.a2a.native/v1"] = Field(alias="schema")
+    run_id: str = Field(min_length=1)
+    session_id: str = Field(min_length=1)
+    tenant_id: str = Field(min_length=1)
+    agent_instance_id: str = Field(min_length=1)
+    thread_id: str = Field(min_length=1)
+    start_request: StartRequest
+    bindings: dict[str, RemoteAgentSpec]
+    calls: tuple[CodexToolCall, ...] = Field(min_length=1)
+    rollout: NativeRolloutCheckpoint
+    continuation_started: bool = Field(default=False, strict=True)
+
+    @model_validator(mode="after")
+    def validate_native_scope(self):
+        if (
+            self.rollout.thread_id != self.thread_id
+            or self.start_request.session_id != self.session_id
+        ):
+            raise ValueError("A2A_CODEX_RECOVERY_SCOPE_CONFLICT")
+        identities = set()
+        for name, spec in self.bindings.items():
+            if name != spec.local_name:
+                raise ValueError("A2A_CODEX_RECOVERY_BINDING_CONFLICT")
+        for call in self.calls:
+            key = (call.thread_id, call.turn_id, call.call_id)
+            if key in identities:
+                raise ValueError("A2A_CODEX_RECOVERY_DUPLICATE_CALL")
+            identities.add(key)
+            if (
+                call.thread_id != self.thread_id
+                or call.tool not in self.bindings
+                or set(call.arguments) != {"message"}
+                or not isinstance(call.arguments["message"], str)
+                or not call.arguments["message"].strip()
+            ):
+                raise ValueError("A2A_CODEX_RECOVERY_CALL_CONFLICT")
+            self.rollout.require_call(
+                turn_id=call.turn_id, call_id=call.call_id, tool=call.tool, arguments=call.arguments
+            )
+        return self
+
+
+def validated_recovery_checkpoint(run, handle: RunHandle, *, experts):
+    """No I/O. A valid digest alone is not enough to authorize another scope."""
+    try:
+        saved_handle = RunHandle.model_validate(run.metadata.get("handle"))
+        checkpoint = CodexRecoveryCheckpoint.model_validate(run.metadata.get("runtime_checkpoint"))
+        if (
+            saved_handle != handle
+            or handle_digest(saved_handle) != run.metadata.get("handle_digest")
+            or handle.runtime_type != "codex"
+            or handle.run_id != checkpoint.thread_id
+            or handle.native_ref.get("thread_id") != checkpoint.thread_id
+            or handle.session_id != run.session_id
+            or handle.native_ref.get("user_id") != checkpoint.start_request.user_id
+            or run.run_id != checkpoint.run_id
+            or run.session_id != checkpoint.session_id
+            or run.agent_instance_id != checkpoint.agent_instance_id
+            or run.metadata.get("tenant_id") != checkpoint.tenant_id
+            or run.state not in {RunState.RUNNING, RunState.WAITING, RunState.PAUSED}
+        ):
+            raise ValueError("scope mismatch")
+        metadata = checkpoint.start_request.metadata
+        if (
+            metadata.get("run_id") != run.run_id
+            or not isinstance(metadata.get("command_id"), str)
+            or not metadata["command_id"]
+            or metadata.get("command_id") != run.metadata.get("command_id")
+            or (metadata.get("invocation_id") and metadata["invocation_id"] != run.run_id)
+        ):
+            raise ValueError("start identity mismatch")
+        expected = {name: expert.spec for name, expert in experts.items()}
+        if checkpoint.bindings != expected:
+            raise ValueError("frozen bindings changed")
+        return checkpoint
+    except (ValueError, TypeError, AttributeError):
+        # Never expose serialized native instructions or private metadata through
+        # a public run failure. Callers cannot restore on this error.
+        raise ValueError("A2A_CODEX_RECOVERY_CHECKPOINT_INVALID") from None

ksadk/a2a/codex_recovery_events.py

@@ -0,0 +1,123 @@
+"""Close the original expert item from verified rollout output, never a fake RPC."""
+
+import hashlib
+import time
+
+from ksadk.events.canonical import ErrorInfo, ItemCompleted, ItemFailed
+from ksadk.events.content import ContentSnapshot, ToolCallContent, ToolResultContent
+from ksadk.events.identity import stable_event_id, stable_part_id
+
+
+async def recovered_expert_terminal(authority, call, rollout, response):
+    rollout.require_call(
+        turn_id=call.turn_id, call_id=call.call_id, tool=call.tool, arguments=call.arguments
+    )
+    items = response.get("contentItems", [])
+    if (
+        len(items) != 1
+        or items[0].get("type") != "inputText"
+        or not isinstance(items[0].get("text"), str)
+        or not isinstance(response.get("success"), bool)
+        or rollout.function_output(call.call_id) != items[0]["text"]
+    ):
+        raise ValueError("A2A_CODEX_RECOVERY_OUTPUT_CONFLICT")
+    events = await authority.list(authority.session_id)
+    triggers = {}
+    for event in events:
+        source = event.source
+        if (
+            source.framework != "codex"
+            or source.native_run_id != call.turn_id
+            or source.native_item_id != call.call_id
+            or source.metadata.get("thread_id") != call.thread_id
+        ):
+            continue
+        snapshot = getattr(event, "initial", None) or getattr(event, "snapshot", None)
+        if getattr(event, "item_kind", None) != "tool_call" or snapshot is None:
+            continue
+        if any(
+            isinstance(part, ToolCallContent)
+            and part.call_id == call.call_id
+            and part.name == call.tool
+            and part.arguments == {"arguments": call.arguments, "namespace": None}
+            for part in snapshot.parts
+        ):
+            triggers.setdefault((event.scope_id, event.item_id), event)
+    if len(triggers) != 1:
+        raise ValueError("A2A_CODEX_NATIVE_TRIGGER_NOT_PERSISTED")
+    (scope, item), original = next(iter(triggers.items()))
+    for event in events:
+        if event.scope_id != scope or getattr(event, "item_id", None) != item:
+            continue
+        if isinstance(event, ItemFailed):
+            if response["success"]:
+                raise ValueError("A2A_CODEX_RECOVERY_TOOL_TERMINAL_CONFLICT")
+            return None
+        if isinstance(event, ItemCompleted):
+            results = [part for part in event.snapshot.parts if isinstance(part, ToolResultContent)]
+            if (
+                len(results) != 1
+                or results[0].call_id != call.call_id
+                or not isinstance(results[0].result, dict)
+                or results[0].result.get("contentItems") != items
+                or results[0].result.get("success") != response["success"]
+            ):
+                raise ValueError("A2A_CODEX_RECOVERY_TOOL_TERMINAL_CONFLICT")
+            return None
+    source = original.source.model_copy(
+        update={
+            "native_event_id": None,
+            "native_cursor": "rollout-output:" + rollout.sha256,
+            "metadata": {
+                **original.source.metadata,
+                "recovery_method": "native_rollout_output",
+                "native_callback_replayed": False,
+            },
+        }
+    )
+    event_type = "item.completed" if response["success"] else "item.failed"
+    values = dict(
+        schema_version=2,
+        run_id=authority.run_id,
+        scope_id=scope,
+        parent_scope_id=original.parent_scope_id,
+        item_id=item,
+        item_kind="tool_call",
+        seq=0,
+        timestamp=time.time(),
+        source=source,
+        event_id=stable_event_id(
+            "codex",
+            scope,
+            item,
+            event_type,
+            "recovered-output",
+            hashlib.sha256(items[0]["text"].encode()).hexdigest(),
+            0,
+        ),
+    )
+    if not response["success"]:
+        return ItemFailed(
+            **values,
+            error=ErrorInfo(
+                code="A2A_CODEX_RECOVERED_EXPERT_FAILED",
+                message="Recovered expert invocation failed",
+                source="codex",
+                scope_id=scope,
+                item_id=item,
+                source_ref=source,
+            ),
+        )
+    snapshot = getattr(original, "initial", None) or original.snapshot
+    result = ToolResultContent(
+        part_id=stable_part_id("codex", item, "tool_result", "primary"),
+        call_id=call.call_id,
+        result={"status": "completed", "success": True, "contentItems": items, "durationMs": None},
+    )
+    return ItemCompleted(
+        **values,
+        snapshot=ContentSnapshot(
+            parts=tuple(part for part in snapshot.parts if not isinstance(part, ToolResultContent))
+            + (result,),
+        ),
+    )