feat(a2a): Introduce restore command for a2a server

[cocosheng-g]

This pull request introduces a new restore command for the a2a (agent-to-agent) server, which allows for restoring the application state from a checkpoint.

Here's a detailed breakdown of the changes:

New restore command

A new restore command has been added to both the a2a-server and the CLI. This command provides the ability to manage and restore checkpoints.

The command has the following subcommands:

• restore <checkpoint-name>: This command restores the application to a previously saved checkpoint. It reads the checkpoint file, and if it's a valid checkpoint, it restores the state.

• restore list: This command lists all the available checkpoints that can be used for restoration.

• checkpoint field: The checkpoint field is added to the ToolCallRequestInfo interface in packages/core/src/core/turn.ts. This field holds the name of the checkpoint file associated with a tool call. The scheduleToolCalls function in packages/a2a-server/src/agent/task.ts populates this field after a checkpoint is created. The actual checkpoint data, including the application state, is stored in the JSON file on disk, not in the checkpoint field itself.

Core Logic Refactoring

The core logic for handling checkpoints has been moved to a new, separate file, packages/core/src/utils/checkpointUtils.ts. This change centralizes checkpoint management and allows for the logic to be shared between the server and the command-line interface.

The new checkpointUtils.ts file includes several utility functions:

• getToolCallDataSchema: This function provides a Zod schema for validating the structure of tool call data in a checkpoint.
• generateCheckpointFileName: This function creates a standardized name for a checkpoint file based on the timestamp, filename, and the tool name that triggered the checkpoint.
• processRestorableToolCalls: This is a key function that processes tool calls that are deemed "restorable" (e.g., file modifications). It creates a git snapshot of the current state and saves the relevant data to a checkpoint file.
• getCheckpointInfoList: This function reads the available checkpoint files and returns a list of their metadata.

Server-side Implementation (a2a-server)

On the server side, the new RestoreCommand is registered in the command-registry.ts file. The server now has a /executeCommand endpoint that can handle the restore command.

When a restorable tool call is executed, the server now creates a checkpoint by calling processRestorableToolCalls before executing the tool call. This ensures that the state can be restored if something goes wrong.

Client-side Implementation (cli)

The client-side restoreCommand.ts has been updated to use the new performRestore function from @google/gemini-cli-core. The command also includes a completion feature that suggests available checkpoint names when a user is typing the restore command.

The logic for creating checkpoints was moved out of useGeminiStream.ts and into a new, shared function called processRestorableToolCalls. This hook now calls that new function instead of handling checkpoint creation itself, which makes the code here much simpler.

[kschaab]

/gemini review