ya-agent-stream-protocol 0.86.0__tar.gz

ya_agent_stream_protocol-0.86.0/.gitignore

@@ -0,0 +1,171 @@
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!apps/
+!apps/ya-claw-web/
+!apps/ya-claw-web/src/
+!apps/ya-claw-web/src/lib/
+!apps/ya-claw-web/src/lib/**
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.bench/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.yaai/
+**/.yaai/
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.pyright/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Vscode config files
+# .vscode/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+TO-DO.json
+dev/
+ya_agent_sdk/sandbox/shell/templates/public
+
+# Sync automaticlly
+yaacli/yaacli/skills/building-agents
+
+# Frontend
+node_modules/
+apps/*/dist/
+!apps/ya-desktop/
+!apps/ya-desktop/src/
+!apps/ya-desktop/src/**
+!apps/ya-desktop/src-tauri/
+!apps/ya-desktop/src-tauri/resources/
+!apps/ya-desktop/src-tauri/resources/uv/
+!apps/ya-desktop/src-tauri/resources/uv/.gitkeep
+apps/ya-desktop/src-tauri/resources/uv/uv
+apps/ya-desktop/src-tauri/resources/uv/uv.exe
+apps/ya-desktop/src-tauri/gen/schemas/linux-schema.json
+*.tsbuildinfo

ya_agent_stream_protocol-0.86.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: ya-agent-stream-protocol
+Version: 0.86.0
+Summary: Shared stream protocol adapters between ya-agent-sdk and applications
+Project-URL: Repository, https://github.com/wh1isper/ya-mono
+Author-email: wh1isper <jizhongsheng957@gmail.com>
+Keywords: agent,agui,protocol,python,stream
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.11
+Requires-Dist: ag-ui-protocol>=0.1.18
+Requires-Dist: pydantic-ai<2,>=1.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: ya-agent-sdk==0.86.0
+Description-Content-Type: text/markdown
+
+# ya-agent-stream-protocol
+
+Shared stream protocol adapters between `ya-agent-sdk` and applications.
+
+The package provides AGUI event adaptation, compact replay buffers, message artifact validation, and SSE framing helpers used by YAACLI, YA Claw, and future applications.

ya_agent_stream_protocol-0.86.0/README.md

@@ -0,0 +1,5 @@
+# ya-agent-stream-protocol
+
+Shared stream protocol adapters between `ya-agent-sdk` and applications.
+
+The package provides AGUI event adaptation, compact replay buffers, message artifact validation, and SSE framing helpers used by YAACLI, YA Claw, and future applications.

ya_agent_stream_protocol-0.86.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "ya-agent-stream-protocol"
+dynamic = ["version", "dependencies"]
+description = "Shared stream protocol adapters between ya-agent-sdk and applications"
+authors = [{ name = "wh1isper", email = "jizhongsheng957@gmail.com" }]
+readme = "README.md"
+keywords = ["python", "agent", "stream", "protocol", "agui"]
+requires-python = ">=3.11,<3.14"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+[project.urls]
+Repository = "https://github.com/wh1isper/ya-mono"
+
+[dependency-groups]
+dev = [
+    "deptry>=0.22.0",
+    "pyright>=1.1.0",
+    "pytest>=7.2.0",
+    "ruff>=0.9.2",
+]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning]
+dependencies = [
+    "ag-ui-protocol>=0.1.18",
+    "pydantic>=2.0.0",
+    "pydantic-ai>=1.100.0,<2",
+    "ya-agent-sdk=={{ version }}",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ya_agent_stream_protocol"]
+
+[tool.uv.sources]
+ya-agent-sdk = { workspace = true }
+
+[tool.deptry]
+ignore = ["DEP001", "DEP002"]
+package_module_name_map = { "ag-ui-protocol" = "ag_ui", "pydantic" = "pydantic", "pydantic-ai" = "pydantic_ai", "ya-agent-sdk" = "ya_agent_sdk" }
+per_rule_ignores = { DEP003 = ["ag_ui", "pydantic", "pydantic_ai", "ya_agent_sdk"], DEP004 = ["pytest"] }

ya_agent_stream_protocol-0.86.0/tests/test_agui_adapter.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from pydantic_ai import PartDeltaEvent, PartEndEvent, PartStartEvent, TextPartDelta, ThinkingPartDelta
+from pydantic_ai.messages import TextPart, ThinkingPart
+from ya_agent_sdk.context.agent import StreamEvent
+from ya_agent_sdk.events import ModelRequestStartEvent
+from ya_agent_stream_protocol.agui import AguiReplayBuffer, AguiReplayConfig
+from ya_agent_stream_protocol.sdk import AguiAdapterConfig, AguiEventAdapter
+
+YAACLI_ADAPTER_CONFIG = AguiAdapterConfig(run_event_prefix="yaacli", stream_metadata_prefix="yaacli")
+CLAW_ADAPTER_CONFIG = AguiAdapterConfig(run_event_prefix="ya_claw")
+YAACLI_REPLAY_CONFIG = AguiReplayConfig(
+    agent_id_field="yaacliAgentId",
+    main_agent_id="main",
+    drop_subagent_detail_events=True,
+)
+
+
+def test_agui_event_adapter_maps_text_stream_events_and_compacts_replay() -> None:
+    adapter = AguiEventAdapter(session_id="session-1", run_id="run-1", config=YAACLI_ADAPTER_CONFIG)
+    replay = AguiReplayBuffer(config=YAACLI_REPLAY_CONFIG)
+
+    stream_events = [
+        StreamEvent(
+            agent_id="main",
+            agent_name="main",
+            event=ModelRequestStartEvent(event_id="run-1", loop_index=0, message_count=0),
+        ),
+        StreamEvent(agent_id="main", agent_name="main", event=PartStartEvent(index=0, part=TextPart(content=""))),
+        StreamEvent(
+            agent_id="main",
+            agent_name="main",
+            event=PartDeltaEvent(index=0, delta=TextPartDelta(content_delta="hello ")),
+        ),
+        StreamEvent(
+            agent_id="main",
+            agent_name="main",
+            event=PartDeltaEvent(index=0, delta=TextPartDelta(content_delta="world")),
+        ),
+        StreamEvent(
+            agent_id="main", agent_name="main", event=PartEndEvent(index=0, part=TextPart(content="hello world"))
+        ),
+    ]
+
+    live_events: list[dict[str, object]] = []
+    for stream_event in stream_events:
+        mapped = adapter.adapt_stream_event(stream_event)
+        live_events.extend(mapped)
+        for item in mapped:
+            replay.append(item)
+
+    assert live_events[0]["type"] == "CUSTOM"
+    assert live_events[0]["name"] == "ya_agent.model_request_start"
+    assert live_events[1]["yaacliAgentId"] == "main"
+    assert [event["type"] for event in live_events[1:]] == [
+        "TEXT_MESSAGE_START",
+        "TEXT_MESSAGE_CHUNK",
+        "TEXT_MESSAGE_CHUNK",
+        "TEXT_MESSAGE_END",
+    ]
+
+    replay.append(adapter.build_run_finished_event(result={"output_text": "hello world"}))
+
+    compacted = replay.snapshot()
+    assert [event["type"] for event in compacted] == ["CUSTOM", "TEXT_MESSAGE_CHUNK", "RUN_FINISHED"]
+    assert compacted[1]["delta"] == "hello world"
+    assert compacted[2]["result"] == {"output_text": "hello world"}
+
+
+def test_agui_event_adapter_run_started_excludes_input_parts() -> None:
+    adapter = AguiEventAdapter(session_id="session-1", run_id="run-1", config=CLAW_ADAPTER_CONFIG)
+
+    event = adapter.build_run_started_event(input_parts=[{"type": "text", "text": "hello"}])
+
+    assert event["type"] == "RUN_STARTED"
+    assert "input" not in event
+
+
+def test_agui_replay_buffer_keeps_runs_separate() -> None:
+    replay = AguiReplayBuffer()
+    replay.append({"type": "RUN_STARTED", "runId": "run-1"})
+    replay.append({"type": "TEXT_MESSAGE_CHUNK", "messageId": "m1", "delta": "first"})
+    replay.append({"type": "RUN_FINISHED", "runId": "run-1"})
+    replay.append({"type": "RUN_STARTED", "runId": "run-2"})
+    replay.append({"type": "TEXT_MESSAGE_CHUNK", "messageId": "m1", "delta": "second"})
+
+    compacted = replay.snapshot()
+    text_chunks = [event for event in compacted if event["type"] == "TEXT_MESSAGE_CHUNK"]
+    assert [event["delta"] for event in text_chunks] == ["first", "second"]
+
+
+def test_agui_replay_buffer_merges_tool_call_chunks() -> None:
+    replay = AguiReplayBuffer()
+    replay.append({
+        "type": "TOOL_CALL_CHUNK",
+        "toolCallId": "tool-1",
+        "toolCallName": "delegate",
+        "delta": '{"prompt":',
+    })
+    replay.append({"type": "TOOL_CALL_CHUNK", "toolCallId": "tool-1", "delta": '"hello"}'})
+    replay.append({
+        "type": "TOOL_CALL_RESULT",
+        "toolCallId": "tool-1",
+        "messageId": "tool-1:result",
+        "content": "done",
+        "role": "tool",
+    })
+
+    compacted = replay.snapshot()
+    assert compacted[0]["type"] == "TOOL_CALL_CHUNK"
+    assert compacted[0]["toolCallName"] == "delegate"
+    assert compacted[0]["delta"] == '{"prompt":"hello"}'
+    assert compacted[1]["type"] == "TOOL_CALL_RESULT"
+
+
+def test_agui_replay_buffer_drops_subagent_detail_events_when_configured() -> None:
+    adapter = AguiEventAdapter(session_id="session-1", run_id="run-1", config=YAACLI_ADAPTER_CONFIG)
+    replay = AguiReplayBuffer(config=YAACLI_REPLAY_CONFIG)
+
+    stream_events = [
+        StreamEvent(
+            agent_id="worker-1",
+            agent_name="worker",
+            event=PartStartEvent(index=0, part=ThinkingPart(content="")),
+        ),
+        StreamEvent(
+            agent_id="worker-1",
+            agent_name="worker",
+            event=PartDeltaEvent(index=0, delta=ThinkingPartDelta(content_delta="hidden thought")),
+        ),
+        StreamEvent(
+            agent_id="worker-1",
+            agent_name="worker",
+            event=PartEndEvent(index=0, part=ThinkingPart(content="hidden thought")),
+        ),
+        StreamEvent(agent_id="worker-1", agent_name="worker", event=PartStartEvent(index=1, part=TextPart(content=""))),
+        StreamEvent(
+            agent_id="worker-1",
+            agent_name="worker",
+            event=PartDeltaEvent(index=1, delta=TextPartDelta(content_delta="hidden text")),
+        ),
+        StreamEvent(
+            agent_id="worker-1", agent_name="worker", event=PartEndEvent(index=1, part=TextPart(content="hidden text"))
+        ),
+    ]
+
+    live_events: list[dict[str, object]] = []
+    for stream_event in stream_events:
+        mapped = adapter.adapt_stream_event(stream_event)
+        live_events.extend(mapped)
+        for item in mapped:
+            replay.append(item)
+
+    assert any(event["type"] == "TEXT_MESSAGE_CHUNK" for event in live_events)
+    assert any(event["type"] == "REASONING_MESSAGE_CHUNK" for event in live_events)
+    assert replay.snapshot() == []
+
+
+def test_agui_adapter_maps_run_custom_event_namespace() -> None:
+    adapter = AguiEventAdapter(session_id="session-1", run_id="run-1", config=CLAW_ADAPTER_CONFIG)
+
+    queued = adapter.build_run_custom_event("run_queued", {"status": "queued"})
+    finished = adapter.build_run_finished_event(result={"output_text": "done"})
+    errored = adapter.build_run_error_event(message="boom", code="error")
+
+    assert queued["type"] == "CUSTOM"
+    assert queued["name"] == "ya_claw.run_queued"
+    assert finished["type"] == "RUN_FINISHED"
+    assert finished["result"] == {"output_text": "done"}
+    assert errored["type"] == "RUN_ERROR"
+    assert errored["message"] == "boom"

ya_agent_stream_protocol-0.86.0/tests/test_agui_validation_sse.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from ya_agent_stream_protocol.agui import (
+    BufferedStreamEvent,
+    format_sse_event,
+    parse_message_events,
+    resolve_event_cursor,
+)
+
+
+def test_parse_message_events_accepts_top_level_event_array() -> None:
+    payload = [{"type": "TEXT_MESSAGE_CHUNK", "messageId": "m1", "delta": "hello"}]
+
+    assert parse_message_events(payload) == payload
+
+
+@pytest.mark.parametrize("payload", [{"events": []}, "[]", 123])
+def test_parse_message_events_rejects_non_array_payload(payload: object) -> None:
+    with pytest.raises(TypeError, match="top-level JSON array"):
+        parse_message_events(payload)  # type: ignore[arg-type]
+
+
+def test_parse_message_events_rejects_non_object_entries() -> None:
+    with pytest.raises(TypeError, match="AGUI event objects"):
+        parse_message_events([{"type": "message"}, "bad-entry"])
+
+
+def test_sse_formatting_uses_agui_type_as_event_name() -> None:
+    event = BufferedStreamEvent(id="2", payload={"type": "RUN_FINISHED", "result": {"output_text": "done"}})
+
+    framed = format_sse_event(event)
+
+    assert framed["id"] == "2"
+    assert framed["event"] == "RUN_FINISHED"
+    assert json.loads(framed["data"])["result"] == {"output_text": "done"}
+
+
+@pytest.mark.parametrize(("last_event_id", "cursor"), [(None, 0), ("0", 0), ("1", 1), ("bad", 0), ("-1", 0)])
+def test_resolve_event_cursor(last_event_id: str | None, cursor: int) -> None:
+    assert resolve_event_cursor(last_event_id) == cursor

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/__init__.py

@@ -0,0 +1,3 @@
+from ya_agent_stream_protocol.json_types import JsonArray, JsonObject, JsonValue
+
+__all__ = ["JsonArray", "JsonObject", "JsonValue"]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/agui/__init__.py

@@ -0,0 +1,37 @@
+from ya_agent_stream_protocol.agui.events import dump_agui_event
+from ya_agent_stream_protocol.agui.replay import (
+    AguiReplayBuffer,
+    AguiReplayConfig,
+    compact_agui_events,
+    is_subagent_detail_event,
+    is_subagent_event,
+)
+from ya_agent_stream_protocol.agui.sse import (
+    BufferedStreamEvent,
+    build_buffered_stream_event,
+    format_sse_event,
+    resolve_event_cursor,
+)
+from ya_agent_stream_protocol.agui.validation import (
+    parse_message_events,
+    parse_required_message_events,
+    validate_agui_events,
+    validate_display_events,
+)
+
+__all__ = [
+    "AguiReplayBuffer",
+    "AguiReplayConfig",
+    "BufferedStreamEvent",
+    "build_buffered_stream_event",
+    "compact_agui_events",
+    "dump_agui_event",
+    "format_sse_event",
+    "is_subagent_detail_event",
+    "is_subagent_event",
+    "parse_message_events",
+    "parse_required_message_events",
+    "resolve_event_cursor",
+    "validate_agui_events",
+    "validate_display_events",
+]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/agui/events.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+
+from ya_agent_stream_protocol.json_types import JsonObject
+
+
+def dump_agui_event(event: BaseModel) -> JsonObject:
+    payload = event.model_dump(mode="json", exclude_none=True, by_alias=True)
+    payload.setdefault("timestamp", int(datetime.now(UTC).timestamp() * 1000))
+    return payload  # type: ignore[return-value]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/agui/replay.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ya_agent_stream_protocol.json_types import JsonObject, JsonValue
+
+_REPLAY_DROP_EVENT_TYPES = frozenset({
+    "TEXT_MESSAGE_START",
+    "TEXT_MESSAGE_END",
+    "REASONING_MESSAGE_START",
+    "REASONING_MESSAGE_END",
+    "TOOL_CALL_START",
+    "TOOL_CALL_END",
+})
+_SUBAGENT_DETAIL_EVENT_TYPES = frozenset({
+    "TEXT_MESSAGE_START",
+    "TEXT_MESSAGE_CHUNK",
+    "TEXT_MESSAGE_END",
+    "REASONING_MESSAGE_START",
+    "REASONING_MESSAGE_CHUNK",
+    "REASONING_MESSAGE_END",
+    "TOOL_CALL_START",
+    "TOOL_CALL_CHUNK",
+    "TOOL_CALL_END",
+    "TOOL_CALL_RESULT",
+})
+
+
+@dataclass(slots=True)
+class AguiReplayConfig:
+    agent_id_field: str | None = None
+    main_agent_id: str = "main"
+    drop_subagent_detail_events: bool = False
+
+
+@dataclass(slots=True)
+class AguiReplayBuffer:
+    config: AguiReplayConfig = field(default_factory=AguiReplayConfig)
+    events: list[JsonObject] = field(default_factory=list)
+    _text_chunk_index: dict[str, int] = field(default_factory=dict)
+    _reasoning_chunk_index: dict[str, int] = field(default_factory=dict)
+    _tool_chunk_index: dict[str, int] = field(default_factory=dict)
+    _chunk_fragments: dict[int, list[str]] = field(default_factory=dict)
+
+    def append(self, event: dict[str, Any]) -> None:
+        event_type = str(event.get("type", "")).strip()
+        if event_type == "":
+            return
+        if self.is_subagent_detail_event(event):
+            return
+        if event_type in _REPLAY_DROP_EVENT_TYPES:
+            return
+        if event_type == "TEXT_MESSAGE_CHUNK":
+            self._merge_text_chunk(event)
+            return
+        if event_type == "REASONING_MESSAGE_CHUNK":
+            self._merge_reasoning_chunk(event)
+            return
+        if event_type == "TOOL_CALL_CHUNK":
+            self._merge_tool_call_chunk(event)
+            return
+        self._append_passthrough_event(event)
+
+    def extend_snapshot(self, events: list[dict[str, Any]]) -> None:
+        self.clear()
+        for event in events:
+            self.append(event)
+
+    def snapshot(self) -> list[JsonObject]:
+        snapshot: list[JsonObject] = []
+        for index, event in enumerate(self.events):
+            event_copy = dict(event)
+            fragments = self._chunk_fragments.get(index)
+            if fragments:
+                event_copy["delta"] = "".join(fragments)
+            snapshot.append(event_copy)
+        return snapshot
+
+    def clear(self) -> None:
+        self.events.clear()
+        self._text_chunk_index.clear()
+        self._reasoning_chunk_index.clear()
+        self._tool_chunk_index.clear()
+        self._chunk_fragments.clear()
+
+    def is_subagent_event(self, event: dict[str, Any]) -> bool:
+        agent_id_field = self.config.agent_id_field
+        if agent_id_field is None:
+            return False
+        agent_id = _normalized_identifier(_event_field(event, agent_id_field, _camel_to_snake(agent_id_field)))
+        return agent_id is not None and agent_id != self.config.main_agent_id
+
+    def is_subagent_detail_event(self, event: dict[str, Any]) -> bool:
+        if not self.config.drop_subagent_detail_events:
+            return False
+        event_type = str(event.get("type", "")).strip()
+        return event_type in _SUBAGENT_DETAIL_EVENT_TYPES and self.is_subagent_event(event)
+
+    def _merge_text_chunk(self, event: dict[str, Any]) -> None:
+        message_id = _normalized_identifier(_event_field(event, "messageId", "message_id"))
+        if message_id is None:
+            self._append_passthrough_event(event)
+            return
+        existing_index = self._text_chunk_index.get(message_id)
+        if existing_index is None:
+            self._text_chunk_index[message_id] = self._append_chunk_event(event)
+            return
+        self._append_delta_fragment(existing_index, event.get("delta"))
+        existing = self.events[existing_index]
+        if existing.get("role") is None and event.get("role") is not None:
+            existing["role"] = event.get("role")
+        if existing.get("name") is None and event.get("name") is not None:
+            existing["name"] = event.get("name")
+
+    def _merge_reasoning_chunk(self, event: dict[str, Any]) -> None:
+        message_id = _normalized_identifier(_event_field(event, "messageId", "message_id"))
+        if message_id is None:
+            self._append_passthrough_event(event)
+            return
+        existing_index = self._reasoning_chunk_index.get(message_id)
+        if existing_index is None:
+            self._reasoning_chunk_index[message_id] = self._append_chunk_event(event)
+            return
+        self._append_delta_fragment(existing_index, event.get("delta"))
+
+    def _merge_tool_call_chunk(self, event: dict[str, Any]) -> None:
+        tool_call_id = _normalized_identifier(_event_field(event, "toolCallId", "tool_call_id"))
+        if tool_call_id is None:
+            self._append_passthrough_event(event)
+            return
+        existing_index = self._tool_chunk_index.get(tool_call_id)
+        if existing_index is None:
+            self._tool_chunk_index[tool_call_id] = self._append_chunk_event(event)
+            return
+        self._append_delta_fragment(existing_index, event.get("delta"))
+        existing = self.events[existing_index]
+        tool_call_name = _event_field(event, "toolCallName", "tool_call_name")
+        if existing.get("toolCallName") is None and tool_call_name is not None:
+            existing["toolCallName"] = tool_call_name
+        parent_message_id = _event_field(event, "parentMessageId", "parent_message_id")
+        if existing.get("parentMessageId") is None and parent_message_id is not None:
+            existing["parentMessageId"] = parent_message_id
+
+    def _append_passthrough_event(self, event: dict[str, Any]) -> None:
+        self._forget_previous_run_state_if_needed(event)
+        self.events.append(_coerce_json_object(event))
+
+    def _append_chunk_event(self, event: dict[str, Any]) -> int:
+        self._forget_previous_run_state_if_needed(event)
+        event_copy = _coerce_json_object(event)
+        fragment = _delta_fragment(event_copy.get("delta"))
+        if fragment is not None:
+            event_copy["delta"] = ""
+        index = len(self.events)
+        self.events.append(event_copy)
+        if fragment is not None:
+            self._chunk_fragments[index] = [fragment]
+        return index
+
+    def _append_delta_fragment(self, index: int, value: object) -> None:
+        fragment = _delta_fragment(value)
+        if fragment is None:
+            return
+        self._chunk_fragments.setdefault(index, []).append(fragment)
+
+    def _forget_previous_run_state_if_needed(self, event: dict[str, Any]) -> None:
+        if event.get("type") != "RUN_STARTED":
+            return
+        self._text_chunk_index.clear()
+        self._reasoning_chunk_index.clear()
+        self._tool_chunk_index.clear()
+        self._chunk_fragments = {
+            index: fragments for index, fragments in self._chunk_fragments.items() if index < len(self.events)
+        }
+
+
+def compact_agui_events(events: list[dict[str, Any]], *, config: AguiReplayConfig | None = None) -> list[JsonObject]:
+    replay = AguiReplayBuffer(config=config or AguiReplayConfig())
+    for event in events:
+        replay.append(event)
+    return replay.snapshot()
+
+
+def is_subagent_detail_event(
+    event: dict[str, Any], *, agent_id_field: str = "yaacliAgentId", main_agent_id: str = "main"
+) -> bool:
+    replay = AguiReplayBuffer(
+        config=AguiReplayConfig(
+            agent_id_field=agent_id_field,
+            main_agent_id=main_agent_id,
+            drop_subagent_detail_events=True,
+        )
+    )
+    return replay.is_subagent_detail_event(event)
+
+
+def is_subagent_event(
+    event: dict[str, Any], *, agent_id_field: str = "yaacliAgentId", main_agent_id: str = "main"
+) -> bool:
+    replay = AguiReplayBuffer(config=AguiReplayConfig(agent_id_field=agent_id_field, main_agent_id=main_agent_id))
+    return replay.is_subagent_event(event)
+
+
+def _coerce_json_object(event: dict[str, Any]) -> JsonObject:
+    return dict(event)  # type: ignore[return-value]
+
+
+def _event_field(event: dict[str, Any], camel_name: str, snake_name: str) -> JsonValue:
+    if camel_name in event:
+        return event[camel_name]  # type: ignore[return-value]
+    return event.get(snake_name)  # type: ignore[return-value]
+
+
+def _normalized_identifier(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip()
+    return normalized or None
+
+
+def _delta_fragment(value: object) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def _camel_to_snake(value: str) -> str:
+    output: list[str] = []
+    for index, character in enumerate(value):
+        if character.isupper() and index > 0:
+            output.append("_")
+        output.append(character.lower())
+    return "".join(output)

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/agui/sse.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ya_agent_stream_protocol.json_types import JsonObject
+
+
+@dataclass(slots=True)
+class BufferedStreamEvent:
+    id: str
+    payload: JsonObject
+    terminal: bool = False
+
+
+def format_sse_event(event: BufferedStreamEvent) -> dict[str, str]:
+    return {
+        "id": event.id,
+        "event": str(event.payload.get("type", "message")),
+        "data": json.dumps(event.payload, ensure_ascii=False),
+    }
+
+
+def resolve_event_cursor(last_event_id: str | None) -> int:
+    if last_event_id is None:
+        return 0
+    try:
+        return max(int(last_event_id), 0)
+    except ValueError:
+        return 0
+
+
+def build_buffered_stream_event(
+    event_id: int | str, payload: dict[str, Any], *, terminal: bool = False
+) -> BufferedStreamEvent:
+    return BufferedStreamEvent(id=str(event_id), payload=dict(payload), terminal=terminal)  # type: ignore[arg-type]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/agui/validation.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ya_agent_stream_protocol.json_types import JsonObject, JsonValue
+
+
+def validate_agui_events(
+    raw_payload: object,
+    *,
+    payload_name: str = "AGUI events payload",
+    allow_none: bool = False,
+) -> list[JsonObject] | None:
+    if raw_payload is None and allow_none:
+        return None
+    if not isinstance(raw_payload, list):
+        raise TypeError(f"{payload_name} must be a top-level JSON array of AGUI event objects")
+    parsed_events: list[JsonObject] = [event for event in raw_payload if isinstance(event, dict)]
+    if len(parsed_events) != len(raw_payload):
+        raise TypeError(f"{payload_name} must contain only AGUI event objects")
+    return parsed_events
+
+
+def parse_message_events(raw_message_payload: JsonValue) -> list[JsonObject] | None:
+    return validate_agui_events(raw_message_payload, payload_name="message payload", allow_none=True)
+
+
+def parse_required_message_events(
+    raw_message_payload: JsonValue, *, payload_name: str = "message payload"
+) -> list[JsonObject]:
+    parsed = validate_agui_events(raw_message_payload, payload_name=payload_name, allow_none=False)
+    if parsed is None:
+        raise TypeError(f"{payload_name} must be a top-level JSON array of AGUI event objects")
+    return parsed
+
+
+def validate_display_events(raw_payload: object) -> list[JsonObject]:
+    parsed = validate_agui_events(raw_payload, payload_name="display_messages payload", allow_none=False)
+    if parsed is None:
+        raise TypeError("display_messages payload must be a top-level JSON array of event objects")
+    return parsed
+
+
+def coerce_json_object(value: dict[str, Any]) -> JsonObject:
+    return dict(value)  # type: ignore[return-value]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/json_types.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+JsonValue = None | bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"]
+JsonArray = list[JsonValue]
+JsonObject = dict[str, JsonValue]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/sdk/__init__.py

@@ -0,0 +1,3 @@
+from ya_agent_stream_protocol.sdk.agui_adapter import AguiAdapterConfig, AguiEventAdapter
+
+__all__ = ["AguiAdapterConfig", "AguiEventAdapter"]

ya_agent_stream_protocol-0.86.0/ya_agent_stream_protocol/sdk/agui_adapter.py

@@ -0,0 +1,450 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass, field, is_dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import cast
+
+from ag_ui.core.events import (
+    CustomEvent,
+    ReasoningMessageChunkEvent,
+    ReasoningMessageEndEvent,
+    ReasoningMessageStartEvent,
+    RunErrorEvent,
+    RunFinishedEvent,
+    RunStartedEvent,
+    TextMessageChunkEvent,
+    TextMessageEndEvent,
+    TextMessageStartEvent,
+    ToolCallChunkEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    ToolCallStartEvent,
+)
+from pydantic import BaseModel
+from pydantic_ai import (
+    FinalResultEvent,
+    FunctionToolResultEvent,
+    OutputToolResultEvent,
+    PartDeltaEvent,
+    PartEndEvent,
+    PartStartEvent,
+    TextPartDelta,
+    ThinkingPartDelta,
+    ToolCallPartDelta,
+)
+from pydantic_ai.messages import RetryPromptPart, TextPart, ThinkingPart, ToolCallPart, ToolReturnPart
+from ya_agent_sdk.context.agent import StreamEvent
+from ya_agent_sdk.events import MessageReceivedEvent, ModelRequestStartEvent, UsageSnapshotEvent
+
+from ya_agent_stream_protocol.agui.events import dump_agui_event
+from ya_agent_stream_protocol.json_types import JsonObject, JsonValue
+
+
+@dataclass(slots=True)
+class AguiAdapterConfig:
+    run_event_prefix: str
+    agent_event_prefix: str = "ya_agent"
+    stream_metadata_prefix: str | None = None
+
+
+@dataclass(slots=True)
+class PartCursor:
+    kind: str
+    part_id: str
+    role: str | None = None
+    tool_call_name: str | None = None
+    emitted_chunk: bool = False
+
+
+@dataclass(slots=True)
+class AgentCursor:
+    loop_index: int = 0
+    parts: dict[int, PartCursor] = field(default_factory=dict)
+
+
+class AguiEventAdapter:
+    def __init__(self, *, session_id: str, run_id: str, config: AguiAdapterConfig) -> None:
+        self._session_id = session_id
+        self._run_id = run_id
+        self._config = config
+        self._agents: dict[str, AgentCursor] = {}
+
+    def build_run_started_event(self, *, input_parts: list[JsonObject] | None = None) -> JsonObject:
+        _ = input_parts
+        return dump_agui_event(RunStartedEvent(thread_id=self._session_id, run_id=self._run_id))
+
+    def build_run_finished_event(self, result: JsonValue = None) -> JsonObject:
+        return dump_agui_event(RunFinishedEvent(thread_id=self._session_id, run_id=self._run_id, result=result))
+
+    def build_run_error_event(self, *, message: str, code: str | None = None) -> JsonObject:
+        return dump_agui_event(RunErrorEvent(message=message, code=code))
+
+    def build_run_custom_event(self, event_name: str, payload: object) -> JsonObject:
+        return dump_agui_event(
+            CustomEvent(
+                name=f"{self._config.run_event_prefix}.{event_name}",
+                value=_serialize_value(payload),
+            )
+        )
+
+    def adapt_stream_event(self, stream_event: StreamEvent) -> list[JsonObject]:
+        cursor = self._agents.setdefault(stream_event.agent_id, AgentCursor())
+        event = stream_event.event
+
+        if isinstance(event, ModelRequestStartEvent):
+            cursor.loop_index = event.loop_index
+
+        if isinstance(event, PartStartEvent):
+            return self._with_stream_metadata(stream_event, self._adapt_part_start(stream_event, cursor))
+        if isinstance(event, PartDeltaEvent):
+            return self._with_stream_metadata(stream_event, self._adapt_part_delta(stream_event, cursor))
+        if isinstance(event, PartEndEvent):
+            return self._with_stream_metadata(stream_event, self._adapt_part_end(stream_event, cursor))
+        if isinstance(event, FunctionToolResultEvent | OutputToolResultEvent):
+            return self._with_stream_metadata(stream_event, self._adapt_function_tool_result(stream_event))
+        if isinstance(event, FinalResultEvent):
+            return [
+                self._custom_agent_event(
+                    event_name="final_result",
+                    stream_event=stream_event,
+                    payload={"tool_name": event.tool_name, "tool_call_id": event.tool_call_id},
+                )
+            ]
+        if isinstance(event, UsageSnapshotEvent):
+            return [
+                self._custom_agent_event(
+                    event_name="usage_snapshot",
+                    stream_event=stream_event,
+                    payload=_serialize_value(event.snapshot) if event.snapshot is not None else None,
+                )
+            ]
+        if isinstance(event, MessageReceivedEvent):
+            return [
+                self._custom_agent_event(
+                    event_name="message_received",
+                    stream_event=stream_event,
+                    payload={"messages": _serialize_value(event.messages)},
+                )
+            ]
+        return [
+            self._custom_agent_event(
+                event_name=_camel_to_snake(type(event).__name__),
+                stream_event=stream_event,
+                payload=_serialize_value(event),
+            )
+        ]
+
+    def _adapt_part_start(self, stream_event: StreamEvent, cursor: AgentCursor) -> list[JsonObject]:
+        event = cast(PartStartEvent, stream_event.event)
+        part = event.part
+        if isinstance(part, TextPart):
+            message_id = part.id or self._part_id(stream_event.agent_id, cursor.loop_index, event.index, "text")
+            cursor.parts[event.index] = PartCursor(kind="text", part_id=message_id, role="assistant")
+            events = [
+                dump_agui_event(
+                    TextMessageStartEvent(message_id=message_id, role="assistant", name=stream_event.agent_name)
+                )
+            ]
+            if part.content:
+                events.append(
+                    dump_agui_event(
+                        TextMessageChunkEvent(
+                            message_id=message_id,
+                            role="assistant",
+                            name=stream_event.agent_name,
+                            delta=part.content,
+                        )
+                    )
+                )
+                cursor.parts[event.index].emitted_chunk = True
+            return events
+        if isinstance(part, ThinkingPart):
+            message_id = part.id or self._part_id(stream_event.agent_id, cursor.loop_index, event.index, "reasoning")
+            cursor.parts[event.index] = PartCursor(kind="reasoning", part_id=message_id, role="reasoning")
+            events = [dump_agui_event(ReasoningMessageStartEvent(message_id=message_id, role="reasoning"))]
+            if part.content:
+                events.append(dump_agui_event(ReasoningMessageChunkEvent(message_id=message_id, delta=part.content)))
+                cursor.parts[event.index].emitted_chunk = True
+            return events
+        if isinstance(part, ToolCallPart):
+            tool_call_id = part.tool_call_id
+            cursor.parts[event.index] = PartCursor(
+                kind="tool_call",
+                part_id=tool_call_id,
+                tool_call_name=part.tool_name,
+            )
+            events = [dump_agui_event(ToolCallStartEvent(tool_call_id=tool_call_id, tool_call_name=part.tool_name))]
+            chunk_delta = _stringify_tool_call_args(part.args)
+            if chunk_delta is not None or part.tool_name:
+                events.append(
+                    dump_agui_event(
+                        ToolCallChunkEvent(
+                            tool_call_id=tool_call_id,
+                            tool_call_name=part.tool_name,
+                            delta=chunk_delta,
+                        )
+                    )
+                )
+                cursor.parts[event.index].emitted_chunk = True
+            return events
+        if isinstance(part, ToolReturnPart):
+            return [self._tool_result_event(part)]
+        if isinstance(part, RetryPromptPart):
+            return [
+                self._custom_agent_event("retry_prompt_part", stream_event=stream_event, payload=_serialize_value(part))
+            ]
+        return [self._custom_agent_event("part_start", stream_event=stream_event, payload=_serialize_value(event))]
+
+    def _adapt_part_delta(self, stream_event: StreamEvent, cursor: AgentCursor) -> list[JsonObject]:
+        event = cast(PartDeltaEvent, stream_event.event)
+        delta = event.delta
+        if isinstance(delta, TextPartDelta):
+            part_cursor = self._ensure_text_cursor(stream_event.agent_id, cursor, event.index)
+            part_cursor.emitted_chunk = True
+            return [
+                dump_agui_event(
+                    TextMessageChunkEvent(
+                        message_id=part_cursor.part_id,
+                        role="assistant",
+                        name=stream_event.agent_name,
+                        delta=delta.content_delta,
+                    )
+                )
+            ]
+        if isinstance(delta, ThinkingPartDelta):
+            part_cursor = self._ensure_reasoning_cursor(stream_event.agent_id, cursor, event.index)
+            events: list[JsonObject] = []
+            if delta.content_delta:
+                part_cursor.emitted_chunk = True
+                events.append(
+                    dump_agui_event(
+                        ReasoningMessageChunkEvent(message_id=part_cursor.part_id, delta=delta.content_delta)
+                    )
+                )
+            if getattr(delta, "signature_delta", None):
+                events.append(
+                    self._custom_agent_event(
+                        "reasoning_signature_delta",
+                        stream_event=stream_event,
+                        payload={"message_id": part_cursor.part_id, "signature_delta": delta.signature_delta},
+                    )
+                )
+            return events
+        if isinstance(delta, ToolCallPartDelta):
+            part_cursor = self._ensure_tool_call_cursor(stream_event.agent_id, cursor, event.index, delta.tool_call_id)
+            if delta.tool_name_delta:
+                part_cursor.tool_call_name = f"{part_cursor.tool_call_name or ''}{delta.tool_name_delta}" or None
+            part_cursor.emitted_chunk = True
+            return [
+                dump_agui_event(
+                    ToolCallChunkEvent(
+                        tool_call_id=part_cursor.part_id,
+                        tool_call_name=part_cursor.tool_call_name,
+                        delta=_stringify_tool_call_args(delta.args_delta),
+                    )
+                )
+            ]
+        return [self._custom_agent_event("part_delta", stream_event=stream_event, payload=_serialize_value(event))]
+
+    def _adapt_part_end(self, stream_event: StreamEvent, cursor: AgentCursor) -> list[JsonObject]:
+        event = cast(PartEndEvent, stream_event.event)
+        part = event.part
+        part_cursor = cursor.parts.pop(event.index, None)
+        if isinstance(part, TextPart):
+            message_id = (
+                part_cursor.part_id
+                if part_cursor is not None
+                else part.id or self._part_id(stream_event.agent_id, cursor.loop_index, event.index, "text")
+            )
+            events: list[JsonObject] = []
+            emitted_chunk = part_cursor.emitted_chunk if part_cursor is not None else False
+            if part.content and not emitted_chunk:
+                events.append(
+                    dump_agui_event(
+                        TextMessageChunkEvent(
+                            message_id=message_id,
+                            role="assistant",
+                            name=stream_event.agent_name,
+                            delta=part.content,
+                        )
+                    )
+                )
+            events.append(dump_agui_event(TextMessageEndEvent(message_id=message_id)))
+            return events
+        if isinstance(part, ThinkingPart):
+            message_id = (
+                part_cursor.part_id
+                if part_cursor is not None
+                else part.id or self._part_id(stream_event.agent_id, cursor.loop_index, event.index, "reasoning")
+            )
+            events = []
+            emitted_chunk = part_cursor.emitted_chunk if part_cursor is not None else False
+            if part.content and not emitted_chunk:
+                events.append(dump_agui_event(ReasoningMessageChunkEvent(message_id=message_id, delta=part.content)))
+            events.append(dump_agui_event(ReasoningMessageEndEvent(message_id=message_id)))
+            return events
+        if isinstance(part, ToolCallPart):
+            tool_call_id = part.tool_call_id if part_cursor is None else part_cursor.part_id
+            events = []
+            emitted_chunk = part_cursor.emitted_chunk if part_cursor is not None else False
+            if not emitted_chunk:
+                events.append(
+                    dump_agui_event(
+                        ToolCallChunkEvent(
+                            tool_call_id=tool_call_id,
+                            tool_call_name=part.tool_name,
+                            delta=_stringify_tool_call_args(part.args),
+                        )
+                    )
+                )
+            events.append(dump_agui_event(ToolCallEndEvent(tool_call_id=tool_call_id)))
+            return events
+        if isinstance(part, ToolReturnPart):
+            return [self._tool_result_event(part)]
+        if isinstance(part, RetryPromptPart):
+            return [
+                self._custom_agent_event("retry_prompt_part", stream_event=stream_event, payload=_serialize_value(part))
+            ]
+        return [self._custom_agent_event("part_end", stream_event=stream_event, payload=_serialize_value(event))]
+
+    def _adapt_function_tool_result(self, stream_event: StreamEvent) -> list[JsonObject]:
+        event = cast(FunctionToolResultEvent | OutputToolResultEvent, stream_event.event)
+        part = event.part
+        content = event.content if isinstance(event, FunctionToolResultEvent) else None
+        if isinstance(part, ToolReturnPart):
+            return [self._tool_result_event(part, content=content)]
+        if isinstance(part, RetryPromptPart):
+            return [
+                self._custom_agent_event(
+                    "retry_prompt_part",
+                    stream_event=stream_event,
+                    payload={"part": _serialize_value(part), "content": _serialize_value(content)},
+                )
+            ]
+        return [
+            self._custom_agent_event("function_tool_result", stream_event=stream_event, payload=_serialize_value(event))
+        ]
+
+    def _tool_result_event(self, part: ToolReturnPart, *, content: object = None) -> JsonObject:
+        tool_call_id = part.tool_call_id
+        return dump_agui_event(
+            ToolCallResultEvent(
+                message_id=f"{tool_call_id}:result",
+                tool_call_id=tool_call_id,
+                content=_stringify_tool_result(content if content is not None else part.content),
+                role="tool",
+            )
+        )
+
+    def _ensure_text_cursor(self, agent_id: str, cursor: AgentCursor, index: int) -> PartCursor:
+        existing = cursor.parts.get(index)
+        if existing is not None:
+            return existing
+        part_cursor = PartCursor(
+            kind="text",
+            part_id=self._part_id(agent_id, cursor.loop_index, index, "text"),
+            role="assistant",
+        )
+        cursor.parts[index] = part_cursor
+        return part_cursor
+
+    def _ensure_reasoning_cursor(self, agent_id: str, cursor: AgentCursor, index: int) -> PartCursor:
+        existing = cursor.parts.get(index)
+        if existing is not None:
+            return existing
+        part_cursor = PartCursor(
+            kind="reasoning",
+            part_id=self._part_id(agent_id, cursor.loop_index, index, "reasoning"),
+            role="reasoning",
+        )
+        cursor.parts[index] = part_cursor
+        return part_cursor
+
+    def _ensure_tool_call_cursor(
+        self,
+        agent_id: str,
+        cursor: AgentCursor,
+        index: int,
+        tool_call_id: str | None,
+    ) -> PartCursor:
+        existing = cursor.parts.get(index)
+        if existing is not None:
+            if tool_call_id:
+                existing.part_id = tool_call_id
+            return existing
+        part_cursor = PartCursor(
+            kind="tool_call",
+            part_id=tool_call_id or self._part_id(agent_id, cursor.loop_index, index, "tool_call"),
+        )
+        cursor.parts[index] = part_cursor
+        return part_cursor
+
+    def _part_id(self, agent_id: str, loop_index: int, part_index: int, kind: str) -> str:
+        return f"{self._run_id}:{agent_id}:{loop_index}:{kind}:{part_index}"
+
+    def _with_stream_metadata(self, stream_event: StreamEvent, events: list[JsonObject]) -> list[JsonObject]:
+        prefix = self._config.stream_metadata_prefix
+        if prefix is None:
+            return events
+        agent_id_key = f"{prefix}AgentId"
+        agent_name_key = f"{prefix}AgentName"
+        for event in events:
+            event[agent_id_key] = stream_event.agent_id
+            event[agent_name_key] = stream_event.agent_name
+        return events
+
+    def _custom_agent_event(self, event_name: str, *, stream_event: StreamEvent, payload: object) -> JsonObject:
+        return dump_agui_event(
+            CustomEvent(
+                name=f"{self._config.agent_event_prefix}.{event_name}",
+                value={
+                    "run_id": self._run_id,
+                    "session_id": self._session_id,
+                    "agent_id": stream_event.agent_id,
+                    "agent_name": stream_event.agent_name,
+                    "payload": _serialize_value(payload),
+                },
+            )
+        )
+
+
+def _stringify_tool_call_args(value: object) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return json.dumps(_serialize_value(value), ensure_ascii=False, separators=(",", ":"))
+
+
+def _stringify_tool_result(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(_serialize_value(value), ensure_ascii=False)
+
+
+def _camel_to_snake(value: str) -> str:
+    snake = re.sub(r"(?<!^)(?=[A-Z])", "_", value).lower()
+    return snake.removesuffix("_event")
+
+
+def _serialize_value(value: object) -> JsonValue:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, datetime):
+        return value.astimezone(UTC).isoformat()
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")  # type: ignore[return-value]
+    if is_dataclass(value) and not isinstance(value, type):
+        return _serialize_value(asdict(value))
+    if isinstance(value, dict):
+        return {str(key): _serialize_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_serialize_value(item) for item in value]
+    return str(value)