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

ksadk/evaluation/local_adapter.py

@@ -18,6 +18,7 @@ from ksadk.evaluation.adapters import TargetAdapterError
 from ksadk.evaluation.contracts import (
     EvalCase,
     EvalRunSpec,
+    FileCheckEvidence,
     TargetKind,
     TargetRef,
     TargetRun,
@@ -27,7 +28,12 @@ from ksadk.evaluation.contracts import (
     TraceRef,
     UsageSnapshot,
 )
-from ksadk.evaluation.evidence import EvidenceStore, project_tool_calls
+from ksadk.evaluation.evidence import (
+    EvidenceStore,
+    project_file_checks,
+    project_runtime_facts,
+    project_tool_calls,
+)
 from ksadk.events.store import RuntimeEventStore
 from ksadk.runtime import RuntimeExecutor, RuntimeLaunchContext
 from ksadk.runtime.conversation_execution import invoke_runtime_conversation_once
@@ -240,6 +246,17 @@ class LocalSourceTargetAdapter:
         trace_ref: TraceRef | None = None
         trace_refs: list[TraceRef] = []
         tool_calls: list[ToolCallEvidence] = []
+        runtime_facts = {
+            "maxTerminalEventsPerScope": 0,
+            "retryCount": 0,
+            "compactionCount": 0,
+            "subagentCount": 0,
+            "toolCallCount": 0,
+            "memoryRecallCount": 0,
+            "memoryWriteCount": 0,
+            "skillDisclosureCount": 0,
+            "mcpDisclosureCount": 0,
+        }
         try:
             for turn_index, turn in enumerate(case.turns, start=1):
                 invocation_id = _scoped_id(
@@ -270,20 +287,44 @@ class LocalSourceTargetAdapter:
                         invocation_id=invocation_id,
                     )
                 )
-                if self._evidence_store is not None:
-                    events = await RuntimeEventStore(self._session_service).list(
-                        session_id,
-                        run_id=invocation_id,
+                events = await RuntimeEventStore(self._session_service).list(
+                    session_id,
+                    run_id=invocation_id,
+                )
+                if events:
+                    trace_ref = TraceRef(
+                        run_id=spec.id,
+                        session_id=session_id,
+                        invocation_id=invocation_id,
+                        seq_start=events[0].seq,
+                        seq_end=events[-1].seq,
                     )
-                    if events:
+                    if self._evidence_store is not None:
                         trace_ref = self._evidence_store.write_trace(
                             spec.id,
                             events,
                             session_id=session_id,
                             policy=spec.config.data_policy,
                         )
-                        trace_refs.append(trace_ref)
-                        tool_calls.extend(project_tool_calls(events))
+                    trace_refs.append(trace_ref)
+                    turn_tool_calls = project_tool_calls(events)
+                    tool_calls.extend(turn_tool_calls)
+                    runtime_facts["toolCallCount"] += len(turn_tool_calls)
+                    turn_facts = project_runtime_facts(events)
+                    runtime_facts["maxTerminalEventsPerScope"] = max(
+                        runtime_facts["maxTerminalEventsPerScope"],
+                        turn_facts["maxTerminalEventsPerScope"],
+                    )
+                    for key in (
+                        "retryCount",
+                        "compactionCount",
+                        "subagentCount",
+                        "memoryRecallCount",
+                        "memoryWriteCount",
+                        "skillDisclosureCount",
+                        "mcpDisclosureCount",
+                    ):
+                        runtime_facts[key] += turn_facts[key]
         except asyncio.CancelledError:
             raise
         except TimeoutError:
@@ -297,7 +338,12 @@ class LocalSourceTargetAdapter:
                 trace_refs=tuple(trace_refs),
                 tool_calls=tuple(tool_calls),
             )
-            return _to_target_run(result, runtime=resolved.snapshot.runtime)
+            return _to_target_run(
+                result,
+                runtime=resolved.snapshot.runtime,
+                runtime_facts=runtime_facts,
+                file_checks=project_file_checks(case, Path(resolved.workspace.name)),
+            )
         except Exception:
             result = _LocalCaseResult(
                 status=TargetRunStatus.ERROR,
@@ -309,7 +355,12 @@ class LocalSourceTargetAdapter:
                 trace_refs=tuple(trace_refs),
                 tool_calls=tuple(tool_calls),
             )
-            return _to_target_run(result, runtime=resolved.snapshot.runtime)
+            return _to_target_run(
+                result,
+                runtime=resolved.snapshot.runtime,
+                runtime_facts=runtime_facts,
+                file_checks=project_file_checks(case, Path(resolved.workspace.name)),
+            )
         finally:
             await asyncio.shield(self._session_service.delete_session(session_id))
 
@@ -330,7 +381,12 @@ class LocalSourceTargetAdapter:
             trace_refs=tuple(trace_refs),
             tool_calls=tuple(tool_calls),
         )
-        return _to_target_run(result, runtime=resolved.snapshot.runtime)
+        return _to_target_run(
+            result,
+            runtime=resolved.snapshot.runtime,
+            runtime_facts=runtime_facts,
+            file_checks=project_file_checks(case, Path(resolved.workspace.name)),
+        )
 
 
 def _resolve_project_dir(locator: str) -> Path:
@@ -463,7 +519,13 @@ def _sum_usage(turns: tuple[_LocalTurnResult, ...]) -> UsageSnapshot:
     )
 
 
-def _to_target_run(result: _LocalCaseResult, *, runtime: str) -> TargetRun:
+def _to_target_run(
+    result: _LocalCaseResult,
+    *,
+    runtime: str,
+    runtime_facts: dict[str, int],
+    file_checks: list[FileCheckEvidence],
+) -> TargetRun:
     final_turn = result.turns[-1] if result.turns else None
     return TargetRun(
         status=result.status,
@@ -479,9 +541,11 @@ def _to_target_run(result: _LocalCaseResult, *, runtime: str) -> TargetRun:
         trace_ref=result.trace_ref,
         trace_refs=list(result.trace_refs),
         tool_calls=list(result.tool_calls),
+        file_checks=file_checks,
         metadata={
             "runtime": runtime,
             "turnCount": len(result.turns),
+            **runtime_facts,
         },
     )
 

ksadk/evaluation/studio_build_adapter.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+import asyncio
 import hashlib
 from collections.abc import Callable
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any, Protocol
 
 from ksadk.events.canonical import RuntimeEvent, parse_runtime_event
@@ -22,7 +24,12 @@ from .contracts import (
     TraceRef,
     UsageSnapshot,
 )
-from .evidence import EvidenceStore, project_tool_calls
+from .evidence import (
+    EvidenceStore,
+    project_file_checks,
+    project_runtime_facts,
+    project_tool_calls,
+)
 
 
 class _StudioRunService(Protocol):
@@ -51,6 +58,7 @@ class StudioBuildResolution:
     model: str | None
     run_spec: Any
     metadata: dict[str, Any]
+    verification_root: Path | None = None
 
 
 class StudioBuildTargetError(TargetAdapterError):
@@ -145,15 +153,65 @@ class StudioBuildTargetAdapter:
         trace_ref: TraceRef | None = None
         trace_refs: list[TraceRef] = []
         tool_calls: list[ToolCallEvidence] = []
+        runtime_facts = {
+            "maxTerminalEventsPerScope": 0,
+            "retryCount": 0,
+            "compactionCount": 0,
+            "subagentCount": 0,
+            "toolCallCount": 0,
+            "memoryRecallCount": 0,
+            "memoryWriteCount": 0,
+            "skillDisclosureCount": 0,
+            "mcpDisclosureCount": 0,
+        }
+        attempted_turns = 0
         for turn in case.turns:
-            record = await self._run_service.run(
-                resolved.run_spec,
-                turn.input,
-                session_id=session_id,
-            )
+            attempted_turns += 1
+            try:
+                record = await asyncio.wait_for(
+                    self._run_service.run(
+                        resolved.run_spec,
+                        turn.input,
+                        session_id=session_id,
+                    ),
+                    timeout=self._timeout_seconds,
+                )
+            except TimeoutError:
+                return TargetRun(
+                    status=TargetRunStatus.ERROR,
+                    duration_ms=self._timeout_seconds * 1000,
+                    usage=usage,
+                    error_code="EVALUATION_CASE_TIMEOUT",
+                    error_message="Studio Build evaluation case exceeded its timeout",
+                    trace_refs=trace_refs,
+                    tool_calls=tool_calls,
+                    file_checks=project_file_checks(case, resolved.verification_root),
+                    metadata={
+                        "runtime": resolved.runtime,
+                        "turnCount": attempted_turns,
+                        **runtime_facts,
+                    },
+                )
             events = _runtime_events(await self._run_service.events(record.id))
             if events:
-                tool_calls.extend(project_tool_calls(events))
+                turn_tool_calls = project_tool_calls(events)
+                tool_calls.extend(turn_tool_calls)
+                runtime_facts["toolCallCount"] += len(turn_tool_calls)
+                turn_facts = project_runtime_facts(events)
+                runtime_facts["maxTerminalEventsPerScope"] = max(
+                    runtime_facts["maxTerminalEventsPerScope"],
+                    turn_facts["maxTerminalEventsPerScope"],
+                )
+                for key in (
+                    "retryCount",
+                    "compactionCount",
+                    "subagentCount",
+                    "memoryRecallCount",
+                    "memoryWriteCount",
+                    "skillDisclosureCount",
+                    "mcpDisclosureCount",
+                ):
+                    runtime_facts[key] += turn_facts[key]
             trace_ref = _trace_ref(spec.id, record, events)
             if self._evidence_store is not None and events:
                 persisted_ref = self._evidence_store.write_trace(
@@ -184,7 +242,12 @@ class StudioBuildTargetAdapter:
                     trace_ref=trace_ref,
                     trace_refs=trace_refs,
                     tool_calls=tool_calls,
-                    metadata={"runtime": resolved.runtime, "turnCount": len(tool_calls)},
+                    file_checks=project_file_checks(case, resolved.verification_root),
+                    metadata={
+                        "runtime": resolved.runtime,
+                        "turnCount": attempted_turns,
+                        **runtime_facts,
+                    },
                 )
             output = str(getattr(record, "output", "") or "")
 
@@ -198,7 +261,8 @@ class StudioBuildTargetAdapter:
             trace_ref=trace_ref,
             trace_refs=trace_refs,
             tool_calls=tool_calls,
-            metadata={"runtime": resolved.runtime, "turnCount": len(case.turns)},
+            file_checks=project_file_checks(case, resolved.verification_root),
+            metadata={"runtime": resolved.runtime, "turnCount": attempted_turns, **runtime_facts},
         )
 
 

ksadk/events/adapters/_a2a_checkpoint.py

@@ -0,0 +1,151 @@
+"""Typed private checkpoint codec; no pickles, transport objects or raw protobufs."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ksadk.events.adapters._a2a_support import A2AAdapterContext, _ArtifactState, _MessageState
+from ksadk.events.content import ContentSnapshot
+from ksadk.events.identity import stable_item_id
+
+
+class _Contract(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, hide_input_in_errors=True)
+
+
+class _Artifact(_Contract):
+    artifact_id: str
+    item_id: str
+    snapshot: ContentSnapshot
+    closed: bool
+    present: bool
+
+    @model_validator(mode="after")
+    def unique_parts(self):
+        ids = [part.part_id for part in self.snapshot.parts]
+        if len(ids) != len(set(ids)):
+            raise ValueError("A2A_CHECKPOINT_DUPLICATE_PART")
+        return self
+
+
+class _Context(_Contract):
+    run_id: str
+    context_id: str
+    task_id: str | None
+    next_seq: int = Field(ge=0)
+    fixed_scope_id: str | None
+    parent_scope_id: str | None
+    direct_message_id: str | None
+
+
+class AdapterCheckpoint(_Contract):
+    version: Literal[1]
+    context: _Context
+    artifacts: dict[str, _Artifact]
+    messages: dict[str, str]
+    tool_activities: dict[str, tuple[str, bool]]
+    tool_activity_bytes: int = Field(ge=0)
+    seen_occurrences: list[tuple[str, str]]
+    provisional_ordinals: dict[str, int]
+    interaction_payloads: list[tuple[int, str, str]]
+    run_started: bool
+    run_interrupted: bool
+    active_interaction: tuple[str, str] | None
+    active_interaction_kind: Literal["structured_input", "approval"] = "structured_input"
+    terminal_snapshot_fingerprint: str | None
+
+
+def export_checkpoint(adapter, context):
+    checkpoint = AdapterCheckpoint(
+        version=1,
+        context=_Context(
+            run_id=context.run_id,
+            context_id=context.context_id,
+            task_id=context.task_id,
+            next_seq=context.peek_placeholder_seq(),
+            fixed_scope_id=context.fixed_scope_id,
+            parent_scope_id=context.parent_scope_id,
+            direct_message_id=context._direct_message_id,
+        ),
+        artifacts={
+            key: _Artifact(
+                artifact_id=value.artifact_id,
+                item_id=value.item_id,
+                snapshot=value.snapshot(),
+                closed=value.closed,
+                present=value.present,
+            )
+            for key, value in adapter._artifacts.items()
+        },
+        messages={key: value.signature for key, value in adapter._messages.items()},
+        tool_activities=adapter._tool_activities,
+        tool_activity_bytes=adapter._tool_activity_bytes,
+        seen_occurrences=list(adapter._seen_occurrences.items()),
+        provisional_ordinals=adapter._provisional_ordinals,
+        interaction_payloads=[
+            (key[0], key[1], value) for key, value in adapter._interaction_payloads.items()
+        ],
+        run_started=adapter._run_started,
+        run_interrupted=adapter._run_interrupted,
+        active_interaction=adapter._active_interaction,
+        active_interaction_kind=adapter._active_interaction_kind,
+        terminal_snapshot_fingerprint=adapter._terminal_snapshot_fingerprint,
+    )
+    payload = checkpoint.model_dump(mode="json")
+    # Keep the established checkpoint wire shape for legacy input flows.
+    # Approval checkpoints require a reader that understands their semantics.
+    if adapter._active_interaction_kind == "structured_input":
+        payload.pop("active_interaction_kind")
+    return payload
+
+
+def restore_checkpoint(adapter_type, payload):
+    import json
+
+    # JSON validation allows the wire representation of tuples while retaining
+    # strict checks for scalars and discriminated canonical content.
+    checkpoint = AdapterCheckpoint.model_validate_json(json.dumps(payload, allow_nan=False))
+    value = checkpoint.context
+    context = A2AAdapterContext(
+        run_id=value.run_id,
+        context_id=value.context_id,
+        task_id=value.task_id,
+        initial_seq=value.next_seq,
+        fixed_scope_id=value.fixed_scope_id,
+        parent_scope_id=value.parent_scope_id,
+    )
+    if value.direct_message_id is not None:
+        context.bind_direct_message(value.direct_message_id)
+    adapter = adapter_type()
+    for key, artifact in checkpoint.artifacts.items():
+        if key != artifact.artifact_id or artifact.item_id != stable_item_id(
+            "a2a", *context.item_identity, "artifact", artifact.artifact_id
+        ):
+            raise ValueError("A2A_CHECKPOINT_ARTIFACT_IDENTITY_CONFLICT")
+        adapter._artifacts[key] = _ArtifactState(
+            artifact_id=artifact.artifact_id,
+            item_id=artifact.item_id,
+            parts={p.part_id: p for p in artifact.snapshot.parts},
+            part_order=[p.part_id for p in artifact.snapshot.parts],
+            closed=artifact.closed,
+            present=artifact.present,
+        )
+    adapter._messages = {
+        key: _MessageState(signature=value) for key, value in checkpoint.messages.items()
+    }
+    adapter._tool_activities = checkpoint.tool_activities
+    adapter._tool_activity_bytes = checkpoint.tool_activity_bytes
+    adapter._seen_occurrences = OrderedDict(checkpoint.seen_occurrences)
+    adapter._provisional_ordinals = checkpoint.provisional_ordinals
+    adapter._interaction_payloads = {
+        (state, key): value for state, key, value in checkpoint.interaction_payloads
+    }
+    adapter._run_started = checkpoint.run_started
+    adapter._run_interrupted = checkpoint.run_interrupted
+    adapter._active_interaction = checkpoint.active_interaction
+    adapter._active_interaction_kind = checkpoint.active_interaction_kind
+    adapter._terminal_snapshot_fingerprint = checkpoint.terminal_snapshot_fingerprint
+    return adapter, context

ksadk/events/adapters/_a2a_snapshot.py

@@ -94,8 +94,7 @@ class _A2ATaskSnapshotMixin:
             native_event_id=None,
             native_cursor=None,
             identity=(
-                f"get-task:{reason}:{attempt_id}:"
-                f"{TaskState.Name(state)}:{_proto_fingerprint(task)}"
+                f"get-task:{reason}:{attempt_id}:{TaskState.Name(state)}:{_proto_fingerprint(task)}"
             ),
             provisional=False,
         )
@@ -157,11 +156,15 @@ class _A2ATaskSnapshotMixin:
         snapshot_artifact_ids: set[str] = set()
 
         for artifact in task.artifacts:
+            from ksadk.events.adapters._a2a_tool_activity import map_tool_artifact
+
+            public = map_tool_artifact(self, artifact, context, scope.timestamp)
+            if public is not None:
+                scope.events.extend(public)
+                continue
             artifact_id = _required_string(artifact.artifact_id, "task.artifacts.artifact_id")
             snapshot_artifact_ids.add(artifact_id)
-            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)
             parts = self._convert_parts(artifact, item_id, start_index=0)
             if not parts:
                 _fail(
@@ -329,14 +332,15 @@ class _A2ATaskSnapshotMixin:
 
         if state in _TERMINAL_STATES and self._active_interaction is not None:
             interaction_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)}),
+            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)}),
+                    )
                 )
-            )
             self._active_interaction = None
 
         def status_text() -> str | None:
@@ -365,7 +369,7 @@ class _A2ATaskSnapshotMixin:
                             if state == TaskState.TASK_STATE_REJECTED
                             else "a2a_task_failed"
                         ),
-                        message=status_text(),
+                        message=status_text() or "Remote A2A task failed",
                         source="a2a",
                         scope_id=context.scope_id,
                         source_ref=terminal_source,
@@ -421,7 +425,7 @@ class _A2ATaskSnapshotMixin:
                 identity=occurrence_identity or message_id,
                 provisional=False,
             )
-        signature = message.SerializeToString(deterministic=True)
+        signature = _proto_fingerprint(message)
         existing = self._messages.get(message_id)
         if existing is not None:
             if existing.signature != signature:

ksadk/events/adapters/_a2a_support.py

@@ -68,6 +68,8 @@ class A2AAdapterContext:
     context_id: str
     task_id: str | None
     initial_seq: int = 0
+    fixed_scope_id: str | None = None
+    parent_scope_id: str | None = None
     _next_seq: int = field(init=False, repr=False)
     _direct_message_id: str | None = field(default=None, init=False, repr=False)
 
@@ -82,6 +84,8 @@ class A2AAdapterContext:
 
     @property
     def scope_id(self) -> str:
+        if self.fixed_scope_id is not None:
+            return self.fixed_scope_id
         if self.task_id is not None:
             return stable_scope_id("a2a", self.context_id, self.task_id)
         if self._direct_message_id is not None:
@@ -92,13 +96,21 @@ class A2AAdapterContext:
             "A2A scope requires a task_id or direct message_id",
         )
 
+    @property
+    def item_identity(self) -> tuple[str, ...]:
+        if self.fixed_scope_id is not None:
+            return (self.fixed_scope_id,)
+        return (self.context_id, self.task_id) if self.task_id else (self.context_id,)
+
     @property
     def native_run_id(self) -> str:
-        return _required_string(self.task_id or self._direct_message_id, "task_id/message_id")
+        return _required_string(
+            self.task_id or self._direct_message_id or self.fixed_scope_id, "task_id/message_id"
+        )
 
     def bind_direct_message(self, message_id: str) -> None:
         native_message_id = _required_string(message_id, "message.message_id")
-        if self.task_id is not None:
+        if self.task_id is not None or self.fixed_scope_id is not None:
             return
         if self._direct_message_id not in {None, native_message_id}:
             _fail(
@@ -153,7 +165,7 @@ class _ArtifactState:
 
 @dataclass(frozen=True)
 class _MessageState:
-    signature: bytes
+    signature: str
 
 
 @dataclass(frozen=True)

ksadk/events/adapters/_a2a_tool_activity.py

@@ -0,0 +1,123 @@
+"""Decode declared public observations without executing any remote tool."""
+
+import json
+
+from google.protobuf.json_format import MessageToDict
+
+from ksadk.a2a.presentation import (
+    A2A_TOOL_ACTIVITY_EXTENSION_URI,
+    A2A_TOOL_ACTIVITY_MAX_INVOCATION_BYTES,
+    ToolActivity,
+)
+from ksadk.events.canonical import ItemCompleted, ItemStarted, ItemUpdated, SourceRef
+from ksadk.events.content import ContentSnapshot, DataContent, ToolCallContent, ToolResultContent
+from ksadk.events.identity import stable_event_id, stable_item_id, stable_part_id
+
+
+def map_tool_artifact(adapter, artifact, context, timestamp):
+    """Return None for ordinary artifacts, safe diagnostic data for damaged extensions."""
+    metadata = MessageToDict(artifact.metadata)
+    declared = metadata.get("extension_uri")
+    if not declared:
+        return None
+    state = adapter._tool_activities
+    events = []
+    for index, part in enumerate(artifact.parts):
+        identity = stable_item_id("a2a-tool", context.scope_id, artifact.artifact_id, index)
+        native = MessageToDict(part.data) if part.WhichOneof("content") == "data" else {}
+        try:
+            if declared != A2A_TOOL_ACTIVITY_EXTENSION_URI:
+                raise ValueError("unknown extension")
+            activity = ToolActivity.model_validate(native)
+            # Struct map iteration order may differ between SSE and GetTask.
+            fingerprint = json.dumps(
+                activity.model_dump(mode="json"), sort_keys=True, separators=(",", ":")
+            )
+            previous = state.get(identity)
+            if previous is not None and previous[0] == fingerprint:
+                continue
+            if previous is not None and previous[1]:
+                from ksadk.events.adapters._a2a_support import _fail
+
+                _fail(
+                    "A2A_TOOL_CLOSED_CONFLICT", "artifact", "closed public tool observation changed"
+                )
+            size = len(fingerprint.encode())
+            if adapter._tool_activity_bytes + size > A2A_TOOL_ACTIVITY_MAX_INVOCATION_BYTES:
+                raise ValueError("extension budget")
+            adapter._tool_activity_bytes += size
+            call_id = stable_item_id("a2a-tool", context.scope_id, activity.call_id)
+            part_id = stable_part_id("a2a", identity, "public-tool")
+            content = (
+                ToolCallContent(
+                    part_id=part_id,
+                    call_id=call_id,
+                    name=activity.name,
+                    arguments=activity.arguments,
+                )
+                if activity.item_kind == "tool_call"
+                else ToolResultContent(
+                    part_id=part_id,
+                    call_id=call_id,
+                    result=activity.result,
+                    is_error=activity.is_error,
+                )
+            )
+            kind = activity.item_kind
+            terminal = activity.operation in {"completed", "failed"}
+            occurrence = activity.event_id
+            state[identity] = (fingerprint, terminal)
+        except ValueError as exc:
+            if getattr(exc, "code", None) == "A2A_TOOL_CLOSED_CONFLICT":
+                raise
+            # Never expose malformed/raw extension data in diagnostics.
+            occurrence = "extension-degraded"
+            if identity in state:
+                continue
+            content = DataContent(
+                part_id=stable_part_id("a2a", identity, "diagnostic"),
+                data={"code": "A2A_TOOL_ACTIVITY_UNAVAILABLE"},
+            )
+            kind, terminal, previous = "status", True, None
+            state[identity] = (occurrence, True)
+        common = dict(
+            schema_version=2,
+            timestamp=timestamp,
+            run_id=context.run_id,
+            scope_id=context.scope_id,
+            parent_scope_id=context.parent_scope_id,
+            source=SourceRef(
+                framework="a2a",
+                native_run_id=context.native_run_id,
+                native_item_id=artifact.artifact_id,
+                metadata={"remote_observation": True},
+            ),
+        )
+
+        def env(phase):
+            return dict(
+                common,
+                seq=context.allocate_placeholder_seq(),
+                event_id=stable_event_id(
+                    "a2a", context.scope_id, identity, phase, "public-tool", occurrence, 0
+                ),
+            )
+
+        if previous is None:
+            events.append(ItemStarted(**env("start"), item_id=identity, item_kind=kind))
+        if terminal:
+            events.append(
+                ItemCompleted(
+                    **env("complete"),
+                    item_id=identity,
+                    item_kind=kind,
+                    snapshot=ContentSnapshot(parts=(content,)),
+                )
+            )
+        else:
+            events.append(
+                ItemUpdated(
+                    **env("update"), item_id=identity, item_kind=kind, op="replace", update=content
+                )
+            )
+    return tuple(events)