docs(spec): Fix whats-new-v1.md

[ishymko]

Changes below as they appear in the file.

• blocking flag existed in 0.3: source
• SendMessage: remove "MAY return Message"/"MUST return Task" which are not in the spec, remove service parameters mention as they are covered above
• streaming was specified for gRPC in proto definition as returns (stream StreamResponse)
• SubscribeToTask is not a new operation
• blocking has no effect for streaming operations: source
• TaskNotCancelableError was mentioned in 0.3: source
• RFC 7515 was mentioned for Agent Card signatures in 0.3: source, kept only RFC 8785 for canonicalization which wasn't
• agentId field does not exist and never did
• extension declarations (AgentExtension object) did not change between 0.3 and 1.0
• Mutual TLS existed in 0.3: source
• subscribing to tasks not originally created via streaming is not a behavior change and is not explicitly mentioned in 1.0
• token is not removed from PushNotificationConfig: source
• configId does not exist in PushNotificationConfig (source) and id was there in 0.3 (source)
• PushNotificationNotSupportedError existed in 0.3: source
• SendMessageRequest example fixed to match the spec
• createdAt and lastModified do not exist in Task: source
• changes to nested Task objects removed as they are covered in respective sections (TaskStatus, Message, Artifact)
• timestamp was not added to Message: source
• there is no "stricter typing" for metadata
• "retained" should not be in the changelog
• createdAt was not added to Artifact: source
• signatures field was there in 0.3: source

Re #1436.

[gemini-code-assist]

Summary of Changes

Hello @ishymko, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on enhancing the accuracy and clarity of the whats-new-v1.md documentation. It addresses and corrects several discrepancies between the documented changes from v0.3 to v1.0 of the specification and the actual protocol definitions. The primary goal is to provide a precise and reliable reference for developers and implementers, ensuring a consistent understanding of the specification's evolution without introducing any functional code changes.

Highlights

• Documentation Accuracy: Corrected numerous inaccuracies in the whats-new-v1.md document, ensuring the specification's evolution from v0.3 to v1.0 is accurately represented.
• SendMessage Operation Details: Rectified details regarding the blocking flag, return types, and service parameters for the SendMessage operation, aligning documentation with actual v0.3 behavior and v1.0 changes.
• Streaming Operations Clarification: Updated descriptions for SendStreamingMessage and SubscribeToTask to correctly reflect gRPC streaming specifications, confirm SubscribeToTask is not a new operation, and clarify the irrelevance of blocking for streaming.
• Error Handling and Agent Card Corrections: Clarified the historical presence of TaskNotCancelableError and refined Agent Card signature details, including the removal of incorrect agentId field mentions and specific RFC references.
• Configuration Object Adjustments: Corrected information for PushNotificationConfig, addressing the token field, configId existence, and PushNotificationNotSupportedError status.
• Object Field Removals: Removed erroneous additions of createdAt and lastModified fields from Task and Artifact objects, timestamp from Message, and eliminated incorrect statements about metadata typing and retention.
• Outdated Section Pruning: Fixed the SendMessageRequest example and removed entire sections (e.g., AgentExtension Object, SecurityScheme Objects) that contained outdated or incorrect information.

Changelog

• docs/whats-new-v1.md
  • Corrected SendMessage operation documentation by removing inaccurate statements about blocking flag novelty, specific return type semantics, and new service parameters.
  • Updated SendStreamingMessage details, removing mentions of unspecified gRPC streaming and the applicability of blocking parameters.
  • Rectified CancelTask documentation, removing the incorrect assertion that TaskNotCancelableError was a new explicit error.
  • Refined Agent Card changes, specifically clarifying canonicalization (RFC 8785) and removing agentId, extension declarations, and Mutual TLS support as new additions.
  • Adjusted SubscribeToTask to correctly identify it as a renamed operation, not a new one, and removed an erroneous behavior change regarding task subscriptions.
  • Corrected PushNotificationConfig details by removing false claims about token field removal, configId addition, and PushNotificationNotSupportedError novelty.
  • Fixed the SendMessageRequest protobuf example to accurately reflect the specification.
  • Removed createdAt and lastModified from the 'Added Fields' list for the Task object, and other related behavior changes.
  • Removed timestamp from the 'Added Fields' list for the Message object and corrected statements about metadata typing.
  • Eliminated the 'RETAINED: metadata optional map' entry from the Part object section.
  • Removed createdAt from the 'Added Fields' list for the Artifact object and related behavior changes.
  • Removed agentId and signatures[] from the 'Added Fields' list for the AgentCard object, along with other modified fields related to extensions and security schemes.
  • Removed the entire 'AgentExtension Object' section, as its structure did not change between v0.3 and v1.0.
  • Updated AgentCapabilities by removing incorrect statements about pushNotifications and streaming enhancements.
  • Removed the entire 'SecurityScheme Objects' section, as its described features were not new to v1.0.
  • Removed incorrect behavior changes and removed fields from PushNotificationConfig related to token and configId identification.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request makes numerous corrections to the whats-new-v1.md documentation, improving its accuracy by aligning it with the protocol specification. The changes are well-justified and enhance the quality of the documentation. However, I've identified one area where the removal of content appears to be based on an incorrect premise regarding the AgentExtension object, and I've provided a comment to address this.

I am having trouble creating individual review comments. Click here to see my feedback.

docs/whats-new-v1.md (508-541)

The removal of this section, along with related changes in the AgentCard Object section, appears to be based on the incorrect premise that the AgentExtension object did not change between v0.3.0 and v1.0. As detailed in the content being removed, the object was significantly redesigned (e.g., id, name, and version were replaced by uri and required). This is a significant breaking change, and the detailed comparison is valuable for developers migrating to v1.0. Please consider restoring this section and the related documentation on AgentCard modifications to accurately reflect the changes in the protocol.

[darrelmiller]

These are excellent updates. Thank you for catching all these mistakes/

[holtskinner]

While we're at it, should we add an entry in mkdocs.yml to add this page to the TOC?

[ishymko]

Apologize @holtskinner auto-merge merged the PR with your comment. I see you covered it in #1489, thank you!