a2aproject / a2aproject/a2a-js
Push notification body shape change between 0.3.14 and 1.0 with legacyCompat: { enabled: true }
- Vorherrschende Sprache
- TypeScript
- Sterne
- 613
- Forks
- 169
- Ø Merge
- 1 T. 6 Std.
- Gemergte PRs (30 T.)
- 21
Beschreibung
Hi, thanks a lot for the ongoing work on the SDK and for the legacyCompat layer.
We're currently migrating from 0.3.14 to 1.0 and found a behaviour change (with `legacyCompat: { enabled: true }`) that we think breaks the compat contract for v0.3 clients. Neither the migration guide nor the compatibility guide mentions it explictily.
Given an AgentExecutor that publishes a `status-update` event (or an `artifact-update` event) to the event bus, the shape of the outgoing push notification diverges between the two SDK versions:
- `0.3.14`: the SDK loads the full Task from the TaskStore and pushes `JSON.stringify(task)`, a single consistent shape (kind: "task") for every event kind. Delta events are recognised by the SDK but consolidated into a full-task push. e.g.: https://github.com/a2aproject/a2a-js/blob/v0.3.14/src/server/request_handler/default_request_handler.ts#L628
- `1.0 with legacyCompat: { enabled: true } and V03PushNotificationSerializer`: the SDK maps each executor event to a StreamResponse with a matching `$case` (task, statusUpdate, artifactUpdate, message), and the compat serializer emits a matching v0.3 wire body (kind: "task", kind: "status-update", kind: "artifact-update"). Delta events are pushed as deltas, not consolidated. e.g. https://github.com/a2aproject/a2a-js/blob/v1.0.1/src/server/request_handler/default_request_handler.ts#L1006
For downstream receivers built against the 0.3.14-actual shape (in our case both internal test doubles and business-application callbacks), this is an unannounced breaking change on the wire.
The [migration guide](https://github.com/a2aproject/a2a-js/blob/main/docs/migration-guide.md) documents the interface change from `send(task: Task)` to `send(streamResponse: StreamResponse, context)`. The [compat guide](https://github.com/a2aproject/a2a-js/blob/main/docs/compatibility-v0_3.md#push-notifications-routed-per-webhook) describes the compat push body as "the bare event object (v0.3 Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent)". Neither points out that this is a deviation from what `0.3.14` actually emitted, so a `0.3.14`-upgrader has no way to anticipate the wire-shape change.
We have a few questions:
1. Is this intentional, or an oversight in the compat layer? For a v0.3 client, a push body of `kind: "status-update"` is a valid wire shape, but it isn't what `0.3.14` ever emitted, so any existing v0.3 receiver deployed against a `0.3.14` server is likely to break. That reads to us as a compat regression rather than a design choice.
2. If it stays as-is, the compatibility guide should call it out. At the moment nothing in either the migration guide or the compat guide leads a `0.3.14`-upgrader to expect a wire-shape change.
3. If it's considered a regression, would a fix that restores `0.3.14` behaviour under `legacyCompat: { enabled: true }` be acceptable, so that every event is consolidated into a `kind: "task"` push before dispatch when the receiver was registered as v0.3?
Thanks again for the great work on the SDK.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.