docs: align v1 migration guide with proto

[hxaxd]

Description

The v1.0 migration guide still described stream wrappers and timestamp fields that do not exist in the normative a2a.proto. A client copied from the guide would check taskStatusUpdate / taskArtifactUpdate, while strict ProtoJSON emits statusUpdate / artifactUpdate, so conforming stream updates could be silently ignored. The guide also recommended Task.createdAt, Task.lastModified, and push-notification configuration fields that the proto cannot serialize.

This change aligns the v1.0 JSON and TypeScript examples with the canonical ProtoJSON member names, removes the nonexistent timestamp and configId claims, preserves the valid TaskStatus.timestamp guidance, and leaves the intentional v0.3 kind examples unchanged.

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title follow the Conventional Commits specification and repository rules
• Ensure the tests and linter pass
• Appropriate docs were updated (if necessary)

Fixes #2045 🦕

[gemini-code-assist]

Code Review

This pull request updates the docs/whats-new-v1.md documentation to remove references to the createdAt and lastModified timestamp fields across Task and PushNotificationConfig objects. Additionally, it renames the event types taskStatusUpdate and taskArtifactUpdate to statusUpdate and artifactUpdate respectively in JSON examples, patterns, and TypeScript code snippets. There are no review comments to evaluate, so no further feedback is provided.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chopmob-cloud]

Verified this against the normative sources. The PR is correct on everything it changes and worth landing. There is one thing it leaves behind that belongs in the same fix, because it fails in exactly the same way.

The changes here are right

Against specification/a2a.proto on current main:

• StreamResponse names its oneof members status_update and artifact_update, so ProtoJSON emits statusUpdate and artifactUpdate. The renames in this PR match.
• message Task carries id, context_id, status, artifacts, history, metadata. No timestamps, so removing createdAt and lastModified is correct.
• TaskPushNotificationConfig carries tenant, id, task_id, url, token, authentication. No timestamp there either, so removing that createdAt is correct.
• TaskStatus.timestamp does exist (google.protobuf.Timestamp timestamp = 3), so re-pointing the ISO 8601 line at it rather than deleting the line outright is the right call.

The PR is also right to leave the kind snippets in place, which is worth saying plainly since the issue raises them:

(The same passages also show a "kind" discriminator at L447 and L480, inside snippets whose surrounding prose says kind was removed in v1.0.)

Those two blocks are labelled v0.3.0:, and the Changes: list noting the removed kind discriminator sits below both of them, describing the move to v1.0. So a kind field is correct there, and removing it would have been the wrong fix.

What it leaves behind: those v0.3 examples carry the wrong kind values

The v0.3 side of the examples is wrong on its own terms, and this PR keeps it wrong.

v0.3.0 never used taskStatusUpdate or taskArtifactUpdate as kind values. From types/src/types.ts at tag v0.3.0, which is the source specification/json/a2a.json is generated from (specification/json/README.md: "DO NOT EDIT a2a.json directly. Make all edits in types/src/types.ts"). Excerpted, with the intervening fields elided:

export interface TaskStatusUpdateEvent {          // L519
  ...
  /** The type of this event, used as a discriminator. Always 'status-update'. */
  readonly kind: "status-update";                 // L525
  ...
}

export interface TaskArtifactUpdateEvent {        // L542
  ...
  /** The type of this event, used as a discriminator. Always 'artifact-update'. */
  readonly kind: "artifact-update";               // L548
  ...
}

The generated schema at the same tag carries those through as "const": "status-update" and "const": "artifact-update".

Worth adding that this is not a value that went stale. It was never correct. I checked every released tag rather than sampling: the constants are status-update and artifact-update in each of v0.2.0 through v0.3.0, and the string taskStatusUpdate occurs zero times in the published schema of any released version, v0.1.0 included.

The guide uses the wrong values in four places, all still present at this PR's head:

• L440, "kind": "taskStatusUpdate" in the v0.3.0 JSON example
• L473, "kind": "taskArtifactUpdate" in the v0.3.0 JSON example
• L651 and L653, event.kind === "taskStatusUpdate" and event.kind === "taskArtifactUpdate" in the Before (v0.3.0) TypeScript snippet

The correct values are status-update and artifact-update.

I checked every kind value in the document against the v0.3.0 schema rather than only these, to be sure the fix is scoped correctly. The Part discriminators (text, file, data) are all correct as written. These four are the only wrong ones.

This matters for the same reason the v1.0 half did, and it fails the same way. Any v0.3 branch written or kept from that snippet tests event.kind against a string no conformant v0.3 server has ever sent, so the branch never fires and the events are silently dropped. No error, just a stream that appears to produce nothing.

The sharpest case is the one a migration guide reliably produces: a client that has to speak both versions during the transition. That code is written straight from this document, with the Before snippet as the v0.3 arm and the After snippet as the v1.0 arm. Before this PR, both arms were wrong. After it, the v1.0 arm is right and the v0.3 arm still is not.

One smaller residual

L187 still gives the compound-ID example tasks/{taskId}/pushNotificationConfigs/{configId} and says it maps to separate task_id and config_id fields.

There is no config_id in the proto. TaskPushNotificationConfig names it id (field 2), alongside task_id (field 3). That is the same configId claim this PR already removes from the PushNotificationConfig field list, so it is worth taking out in the same pass for consistency.

With those four kind values corrected and that line adjusted, the guide reads clean against both the v0.3.0 schema and the v1.0 proto.

[hxaxd]

Hi @darrelmiller - this is a small update aligning the v1 migration guide with the current proto, all checks are green, and I'd greatly appreciate your review when you have a moment. Thank you!