a2aproject / a2aproject/a2a-js

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

オープン
#624 コメント 0 件 リアクション 1 件 担当者 0 名 GitHub で見る
主要言語
TypeScript
スター
613
フォーク
169
平均マージ
1日 6時間
マージ済み PR(30日)
21

説明

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.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Look at the push notification serialization logic in src/server/request_handler/default_request_handler.ts around line 1006 for v1.0.1 and line 628 for v0.3.14. Understand the V03PushNotificationSerializer and how it maps StreamResponse cases to v0.3 wire bodies. The fix likely involves modifying the compat layer to consolidate delta events into a full-task push when legacyCompat is enabled, matching the old behavior. Test by simulating status-update and artifact-update events and checking the emitted notification shape.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
javascript, typescript
領域
api, backend
issue の種類
バグ
難易度
4/5
見積もり時間
3〜5日
活発さ
静か
明瞭さ
明確に書かれている
初心者へのやさしさ
40/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。