a2aproject / a2aproject/a2a-js

Push notification body shape change between 0.3.14 and 1.0 with legacyCompat: { enabled: true }

Offen
#624 0 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen
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

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.