refactor(spec): rename SendMessageConfiguration.blocking to SendMessageConfiguration.return_immediately

[ishymko]

As mentioned in the linked issue, defaulting to non-blocking behavior is counterintuitive and is implemented the opposite way in the SDKs.

Renaming it to return_immediately makes default behavior simpler while advanced scenario requires an extra flag.

---

Previos proposals:

1. polling has inaccurate meaning in this context as pointed out in the comments.
2. non_blocking is a negative boolean which leads to confusing conditional expressions (not non_blocking).

Fixes #1453

[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 refactors the task execution control mechanism by renaming the blocking parameter to polling and inverting its boolean logic. This change aims to make the default behavior more intuitive and consistent with SDK implementations, where waiting for task completion is the common expectation. The update ensures that the specification and examples accurately reflect this new, clearer approach to managing task execution flow.

Highlights

• Parameter Renaming: The blocking parameter has been renamed to polling across the specification and documentation to better reflect its behavior.
• Inverted Logic and Default Behavior: The logic of the parameter has been inverted: polling: false now signifies blocking behavior (wait for task completion), which is the new default. Conversely, polling: true now signifies non-blocking behavior (return immediately).
• Documentation and Example Updates: All relevant documentation, including the main specification and 'What's New' guide, along with code examples, have been updated to reflect the new polling parameter name, its inverted logic, and the new default.

Changelog

• docs/specification.md
  • Renamed the 'Blocking vs Non-Blocking Execution' section to 'Execution Mode'.
  • Updated the description of the blocking field to refer to polling and inverted its logic.
  • Clarified that polling: false is now the default blocking behavior.
  • Adjusted language from 'blocking mode' to 'execution mode'.
• docs/whats-new-v1.md
  • Renamed the 'Blocking Parameter Control' section to 'Execution Mode Control'.
  • Modified TypeScript code snippets to use polling instead of blocking and updated the boolean values to reflect the new logic.
  • Updated a roadmap item from 'blocking parameter support' to 'polling parameter support'.
• specification/a2a.proto
  • Renamed the blocking field to polling within the SendMessageConfiguration message.
  • Updated the comment for the polling field to describe its new inverted logic and default value.

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

The pull request effectively renames 'blocking' to 'polling' across the documentation and protocol definition, aligning with the intent to clarify execution modes. The changes are consistent and improve the readability and understanding of the protocol's behavior regarding task completion. The updates in specification/a2a.proto and docs/specification.md accurately reflect the new terminology and default behavior. The docs/whats-new-v1.md file is also updated to reflect these changes, providing clear migration guidance for developers. Overall, the changes are well-executed and contribute positively to the protocol's clarity.

[Tehsmash]

Hey @ishymko, Thanks for the PR, I'm not sure about the wording of "polling" when its a server side flag. i.e. Now it sounds like your asking the server to poll when in fact you're asking it to block/not-block. Polling is a client side operation and is just one reason to send blocking=False for example if you register a webhook callback you aren't doing polling but you still want non-blocking.

Even if blocking=True you may still need to "poll" the Task to get it to completion if it goes through an interrupted state, so blocking=True is really an implementation of long polling which returns when the state changes. Perhaps we should lean further into that design.

[ishymko]

Hey @Tehsmash, thank you for your input, makes sense, what's your proposal for something which is going to be false by default?

Options mentioned in #1453: polling, nonblocking or async.

[Tehsmash]

Out of the proposed options I prefer async.
Other options could be: nowait or return_immediately.

Another option that we make blocking an optional boolean in the proto, this would allow us to have three values: unset, true and false. Then we can decide what the "unset" behaviour is separately.

[darrelmiller]

I added a comment on the issue, but adding here too. I agree with @Tehsmash that "polling" is not the right term. I'd rather not use "async" because it means something different in programming languages. I'm ok with "nonBlocking", or "noWait" or "returnImmediately". I think the last suggestion is probably the most explicit description of the desired behavior.

[ishymko]

@Tehsmash @darrelmiller thank you for your input. Renamed to non_blocking as it's close to original. I believe that return_immediately still doesn't eliminate the need of reading the description.

On a side note: CI is failing due to some unrelated (I hope) issue. Fixed via #1509

[ishymko]

CI is going to be fixed via #1509.

[holtskinner]

I understand changing the default on this; however, this rename to non_blocking makes this field a negative boolean, which can be confusing to handle. I think it makes more sense to leave as a positive boolean to avoid double negatives.

https://testing.googleblog.com/2023/10/improve-readability-with-positive.html

[ishymko]

@holtskinner so how about return_immediately?

Changing it to proto optional and treating unset as true is also confusing IMO.

[ishymko]

@holtskinner @darrelmiller renamed to return_immediately