a2aproject / a2aproject/a2a-js

[Bug]: unknown enum values become the string "UNRECOGNIZED", which a2a-python rejects

Đang mở
#640 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
TypeScript
Star
613
Fork
169
Merge trung bình
1 ngày 6 giờ
Pull request đã merge (30 ngày)
21

Mô tả

### What happened?

`ts-proto` maps any enum value it doesn't recognise to the sentinel `UNRECOGNIZED`, and
`toJSON` emits that as a literal string. proto3 JSON keeps an unknown enum value as its
integer instead, so that a peer running an older version can still pass a newer value
through untouched.

Right now the value isn't just degraded, it's gone. `"UNRECOGNIZED"` carries nothing about
what the original was, so nothing downstream can recover it.

```js
import { TaskStatus } from '@a2a-js/sdk';

TaskStatus.toJSON(TaskStatus.fromJSON({ state: 99 }));
// { state: 'UNRECOGNIZED' }
```

`a2a-python` on the same input:

```python
from a2a.types import TaskStatus
from google.protobuf.json_format import MessageToDict, ParseDict

m = TaskStatus(); ParseDict({"state": 99}, m)
MessageToDict(m) # {'state': 99}

ParseDict({"state": "UNRECOGNIZED"}, TaskStatus())
# ParseError: Invalid enum value UNRECOGNIZED for enum type lf.a2a.v1.TaskState
```

So the round trip through a JS hop is lossy in a way the other end can't parse:

```
python emits {"state": 99}
js re-emits {"state": "UNRECOGNIZED"}
python rejects ParseError
```

### Why it matters

`TaskState` currently defines 0 through 8, so 9 is the next value the spec would add. On
that day, any 1.0 JS SDK sitting between two newer peers as a proxy, relay or gateway
turns a forward-compatible number into a string that a conformant parser refuses. The
same applies to `Role`.

It's latent today and guaranteed to bite on the next enum addition, which is the awkward
kind: nothing is visibly wrong until a version bump makes it wrong everywhere at once.

### What I'd expect

Unrecognised enum members keep their numeric value through `fromJSON` and `toJSON` rather
than collapsing to a sentinel.

### How this was found

Round-tripping a shared corpus of protocol objects through this SDK and `a2a-python` and
diffing the JSON. Both generate from the same `.proto`, so a disagreement is an interop
divergence rather than a matter of preference.

Reproduced on `@a2a-js/sdk` 1.0.1 from npm and on `main` at `1c6eb32`, against
`a2a-python` at `cff6727`.

I'm happy to send a fix, but this one lives in `src/types/pb/a2a.ts`, which is generated
and marked `DO NOT EDIT`, and I don't see a regeneration path in the repo. Let me know
where you'd want it: patched in the generated output, handled in a normalization layer at
the transport boundary, or pushed upstream to `ts-proto`.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

The issue is in the generated file src/types/pb/a2a.ts, which comes from ts-proto. First, understand how ts-proto handles unknown enum values in its JSON mapping. Look for ts-proto's generation configuration in the project. The fix likely requires updating the ts-proto plugin or adding a post-processing step. Test by modifying the generation to preserve numeric values for unknown enums and verify round-trip compatibility with a2a-python using the provided examples.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
typescript
Lĩnh vực
backend-api-design, data
Loại issue
Lỗi
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
40/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.