cleveragents/cleveragents-core

Fork 3

UAT: `entity/updated` SSE event type missing from EventBusBridge — spec requires push-based entity sync via SSE #2141

New issue

Open

opened 2026-04-03 04:23:58 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:23:58 +00:00

Owner

Metadata

Branch: fix/a2a-entity-updated-sse-event
Commit Message: fix(a2a): add entity/updated SSE event type to EventBusBridge and SseEventFormatter
Milestone: v3.7.0
Parent Epic: #933

Background

Code-level analysis of the SSE event system in src/cleveragents/a2a/events.py, specifically the EventBusBridge class and SseEventFormatter class, against the spec's push-based entity synchronization model, revealed that the entity/updated SSE event type is entirely absent from the implementation.

What Was Tested

Expected Behavior (from spec)

The specification states:

The server sends entity/updated events to the client over an SSE connection. Each event contains the updated entity and its new version. The client is responsible for updating its local cache with the new entity data. This push-based approach ensures that clients are always in sync with the server without the need for constant polling.

The EventBusBridge must:

Translate domain events for entity changes (resource modified, actor invoked, tool registered, etc.) into entity/updated SSE events
Include the full entity payload in the event data so clients can update their local caches
Broadcast these events to all connected clients (not just a single subscriber)

The SseEventFormatter must:

Support the entity/updated event type in its _EVENT_TYPE_TO_METHOD mapping
Format entity update events with the correct JSON-RPC 2.0 method name

Actual Behavior

entity/updated event type is completely absent from EventBusBridge._STATUS_EVENT_TYPES and EventBusBridge._ARTIFACT_EVENT_TYPES in src/cleveragents/a2a/events.py (lines 237-253). The bridge only handles plan lifecycle events (PLAN_CREATED, PLAN_PHASE_CHANGED, etc.) and checkpoint events (CHECKPOINT_RESTORED).
SseEventFormatter._EVENT_TYPE_TO_METHOD (lines 155-160) only maps TaskStatusUpdateEvent and TaskArtifactUpdateEvent. There is no mapping for entity/updated or any entity-related event type.
EventType.ENTITY_UPDATED is missing from src/cleveragents/infrastructure/events/types.py. Only ENTITY_DELETED exists (line 69). The spec requires entity.updated events to be emitted when entities are modified.
No broadcast mechanism exists. The A2aEventQueue only supports single-subscriber local callbacks (subscribe_local). There is no mechanism to broadcast entity update events to multiple connected clients simultaneously, which is required for server mode.

Code Locations

src/cleveragents/a2a/events.py lines 237-253: EventBusBridge event type sets
src/cleveragents/a2a/events.py lines 155-160: SseEventFormatter._EVENT_TYPE_TO_METHOD
src/cleveragents/infrastructure/events/types.py line 69: Only ENTITY_DELETED, no ENTITY_UPDATED
src/cleveragents/a2a/events.py lines 45-130: A2aEventQueue — no broadcast support

Steps to Reproduce

from cleveragents.infrastructure.events.types import EventType
# FAILS — ENTITY_UPDATED does not exist
assert hasattr(EventType, 'ENTITY_UPDATED')

from cleveragents.a2a.events import EventBusBridge
# FAILS — entity events not in any event type set
assert "ENTITY_UPDATED" in EventBusBridge._STATUS_EVENT_TYPES or \
       "ENTITY_UPDATED" in EventBusBridge._ARTIFACT_EVENT_TYPES

from cleveragents.a2a.events import SseEventFormatter
# FAILS — no entity/updated mapping
assert "entity/updated" in SseEventFormatter._EVENT_TYPE_TO_METHOD.values()

Severity

High — The push-based entity synchronization model is the core mechanism for keeping clients in sync with the server. Without entity/updated SSE events, clients cannot receive real-time entity updates after the initial sync.

Subtasks

Add ENTITY_UPDATED to EventType enum in src/cleveragents/infrastructure/events/types.py
Add entity/updated event type handling to EventBusBridge (new event type set or extend existing) in src/cleveragents/a2a/events.py
Add entity/updated → JSON-RPC 2.0 method mapping to SseEventFormatter._EVENT_TYPE_TO_METHOD
Implement broadcast mechanism in A2aEventQueue to support multiple simultaneous SSE subscribers
Emit ENTITY_UPDATED domain events from all entity-mutating operations (resource modified, actor invoked, tool registered, etc.)
Write Behave scenarios covering entity/updated SSE event emission for each entity type
Write Behave scenarios covering broadcast delivery to multiple connected clients
Run nox -e typecheck and fix any type errors
Run nox -e unit_tests and ensure all scenarios pass
Run nox -e coverage_report and confirm coverage ≥ 97%
Run full nox suite and fix any remaining failures

Definition of Done

EventType.ENTITY_UPDATED exists in src/cleveragents/infrastructure/events/types.py
EventBusBridge routes entity mutation domain events to entity/updated SSE events
SseEventFormatter._EVENT_TYPE_TO_METHOD includes a mapping for the entity/updated event type
A2aEventQueue supports broadcasting entity update events to all connected SSE clients
All entity-mutating operations emit ENTITY_UPDATED domain events
Behave scenarios cover all new event paths and broadcast behaviour
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/a2a-entity-updated-sse-event` - **Commit Message**: `fix(a2a): add entity/updated SSE event type to EventBusBridge and SseEventFormatter` - **Milestone**: v3.7.0 - **Parent Epic**: #933 ## Background Code-level analysis of the SSE event system in `src/cleveragents/a2a/events.py`, specifically the `EventBusBridge` class and `SseEventFormatter` class, against the spec's push-based entity synchronization model, revealed that the `entity/updated` SSE event type is entirely absent from the implementation. ## What Was Tested Code-level analysis of the SSE event system in `src/cleveragents/a2a/events.py`, specifically the `EventBusBridge` class and `SseEventFormatter` class, against the spec's push-based entity synchronization model. ## Expected Behavior (from spec) The specification states: > The server sends `entity/updated` events to the client over an SSE connection. Each event contains the updated entity and its new version. The client is responsible for updating its local cache with the new entity data. This push-based approach ensures that clients are always in sync with the server without the need for constant polling. The `EventBusBridge` must: 1. Translate domain events for entity changes (resource modified, actor invoked, tool registered, etc.) into `entity/updated` SSE events 2. Include the full entity payload in the event data so clients can update their local caches 3. Broadcast these events to all connected clients (not just a single subscriber) The `SseEventFormatter` must: 1. Support the `entity/updated` event type in its `_EVENT_TYPE_TO_METHOD` mapping 2. Format entity update events with the correct JSON-RPC 2.0 method name ## Actual Behavior 1. **`entity/updated` event type is completely absent** from `EventBusBridge._STATUS_EVENT_TYPES` and `EventBusBridge._ARTIFACT_EVENT_TYPES` in `src/cleveragents/a2a/events.py` (lines 237-253). The bridge only handles plan lifecycle events (`PLAN_CREATED`, `PLAN_PHASE_CHANGED`, etc.) and checkpoint events (`CHECKPOINT_RESTORED`). 2. **`SseEventFormatter._EVENT_TYPE_TO_METHOD`** (lines 155-160) only maps `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`. There is no mapping for `entity/updated` or any entity-related event type. 3. **`EventType.ENTITY_UPDATED` is missing** from `src/cleveragents/infrastructure/events/types.py`. Only `ENTITY_DELETED` exists (line 69). The spec requires `entity.updated` events to be emitted when entities are modified. 4. **No broadcast mechanism** exists. The `A2aEventQueue` only supports single-subscriber local callbacks (`subscribe_local`). There is no mechanism to broadcast entity update events to multiple connected clients simultaneously, which is required for server mode. ## Code Locations - `src/cleveragents/a2a/events.py` lines 237-253: `EventBusBridge` event type sets - `src/cleveragents/a2a/events.py` lines 155-160: `SseEventFormatter._EVENT_TYPE_TO_METHOD` - `src/cleveragents/infrastructure/events/types.py` line 69: Only `ENTITY_DELETED`, no `ENTITY_UPDATED` - `src/cleveragents/a2a/events.py` lines 45-130: `A2aEventQueue` — no broadcast support ## Steps to Reproduce ```python from cleveragents.infrastructure.events.types import EventType # FAILS — ENTITY_UPDATED does not exist assert hasattr(EventType, 'ENTITY_UPDATED') from cleveragents.a2a.events import EventBusBridge # FAILS — entity events not in any event type set assert "ENTITY_UPDATED" in EventBusBridge._STATUS_EVENT_TYPES or \ "ENTITY_UPDATED" in EventBusBridge._ARTIFACT_EVENT_TYPES from cleveragents.a2a.events import SseEventFormatter # FAILS — no entity/updated mapping assert "entity/updated" in SseEventFormatter._EVENT_TYPE_TO_METHOD.values() ``` ## Severity **High** — The push-based entity synchronization model is the core mechanism for keeping clients in sync with the server. Without `entity/updated` SSE events, clients cannot receive real-time entity updates after the initial sync. ## Subtasks - [ ] Add `ENTITY_UPDATED` to `EventType` enum in `src/cleveragents/infrastructure/events/types.py` - [ ] Add `entity/updated` event type handling to `EventBusBridge` (new event type set or extend existing) in `src/cleveragents/a2a/events.py` - [ ] Add `entity/updated` → JSON-RPC 2.0 method mapping to `SseEventFormatter._EVENT_TYPE_TO_METHOD` - [ ] Implement broadcast mechanism in `A2aEventQueue` to support multiple simultaneous SSE subscribers - [ ] Emit `ENTITY_UPDATED` domain events from all entity-mutating operations (resource modified, actor invoked, tool registered, etc.) - [ ] Write Behave scenarios covering `entity/updated` SSE event emission for each entity type - [ ] Write Behave scenarios covering broadcast delivery to multiple connected clients - [ ] Run `nox -e typecheck` and fix any type errors - [ ] Run `nox -e unit_tests` and ensure all scenarios pass - [ ] Run `nox -e coverage_report` and confirm coverage ≥ 97% - [ ] Run full `nox` suite and fix any remaining failures ## Definition of Done - [ ] `EventType.ENTITY_UPDATED` exists in `src/cleveragents/infrastructure/events/types.py` - [ ] `EventBusBridge` routes entity mutation domain events to `entity/updated` SSE events - [ ] `SseEventFormatter._EVENT_TYPE_TO_METHOD` includes a mapping for the `entity/updated` event type - [ ] `A2aEventQueue` supports broadcasting entity update events to all connected SSE clients - [ ] All entity-mutating operations emit `ENTITY_UPDATED` domain events - [ ] Behave scenarios cover all new event paths and broadcast behaviour - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 04:24:02 +00:00

freemo added a new dependency

2026-04-03 04:25:39 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo referenced this issue

2026-04-03 04:31:47 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 731 — v3.7.0 #2157

freemo referenced this issue

2026-04-03 04:32:08 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:40:28 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo self-assigned this

2026-04-03 16:58:02 +00:00

freemo added the

MoSCoW

Must have

label

2026-04-03 18:27:17 +00:00

freemo commented

2026-04-03 18:27:29 +00:00

Author

Owner

MoSCoW classification: Must Have

Rationale: This issue addresses a core spec requirement or blocks critical functionality. The project cannot ship without this fix.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Must Have** Rationale: This issue addresses a core spec requirement or blocks critical functionality. The project cannot ship without this fix. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner