chore: import upstream snapshot with attribution

packages/a2a-server/GEMINI.md

@@ -0,0 +1,22 @@
+# Gemini CLI A2A Server (`@google/gemini-cli-a2a-server`)
+
+Experimental Agent-to-Agent (A2A) server that exposes Gemini CLI capabilities
+over HTTP for inter-agent communication.
+
+## Architecture
+
+- `src/agent/`: Agent session management for A2A interactions.
+- `src/commands/`: CLI command definitions for the A2A server binary.
+- `src/config/`: Server configuration.
+- `src/http/`: HTTP server and route handlers.
+- `src/persistence/`: Session and state persistence.
+- `src/utils/`: Shared utility functions.
+- `src/types.ts`: Shared type definitions.
+
+## Running
+
+- Binary entry point: `gemini-cli-a2a-server`
+
+## Testing
+
+- Run tests: `npm test -w @google/gemini-cli-a2a-server`

packages/a2a-server/README.md

@@ -0,0 +1,5 @@
+# Gemini CLI A2A Server
+
+## All code in this package is experimental and under active development
+
+This package contains the A2A server implementation for the Gemini CLI.

packages/a2a-server/development-extension-rfc.md

@@ -0,0 +1,509 @@
+# RFC: Gemini CLI A2A Development-Tool Extension
+
+## 1. Introduction
+
+### 1.1 Overview
+
+To standardize client integrations with the Gemini CLI agent, this document
+proposes the `development-tool` extension for the A2A protocol.
+
+Rather than creating a new protocol, this specification builds upon the existing
+A2A protocol. As an open-source standard recently adopted by the Linux
+Foundation, A2A provides a robust foundation for core concepts like tasks,
+messages, and streaming events. This extension-based approach allows us to
+leverage A2A's proven architecture while defining the specific capabilities
+required for rich, interactive workflows with the Gemini CLI agent.
+
+### 1.2 Motivation
+
+Recent work integrating Gemini CLI with clients like Zed and Gemini Code
+Assist’s agent mode has highlighted the need for a robust, standard
+communication protocol. Standardizing on A2A provides several key advantages:
+
+- **Solid Foundation**: Provides a robust, open standard that ensures a stable,
+  predictable, and consistent integration experience across different IDEs and
+  client surfaces.
+- **Extensibility**: Creates a flexible foundation to support new tools and
+  workflows as they emerge.
+- **Ecosystem Alignment**: Aligns Gemini CLI with a growing industry standard,
+  fostering broader interoperability.
+
+## 2. Communication Flow
+
+The interaction follows A2A’s task-based, streaming pattern. The client sends a
+`message/stream` request and the agent responds with a `contextId` / `taskId`
+and a stream of events. `TaskStatusUpdateEvent` events are used to convey the
+overall state of the task. The task is complete when the agent sends a final
+`TaskStatusUpdateEvent` with `final: true` and a terminal status like
+`completed` or `failed`.
+
+### 2.1 Asynchronous Responses and Notifications
+
+Clients that may disconnect from the agent should supply a
+`PushNotificationConfig` to the agent with the initial `message/stream` method
+or subsequently with the `tasks/pushNotificationConfig/set` method so that the
+agent can call back when updates are ready.
+
+## 3. The `development-tool` extension
+
+### 3.1 Overview
+
+The `development-tool` extension establishes a communication contract for
+workflows between a client and the Gemini CLI agent. It consists of a
+specialized set of schemas, embedded within core A2A data structures, that
+enable the agent to stream real-time updates on its state and thought process.
+These schemas also provide the mechanism for the agent to request user
+permission before executing tools.
+
+**Sample Agent Card**
+
+```json
+{
+  "name": "Gemini CLI Agent",
+  "description": "An agent that generates code based on natural language instructions.",
+  "capabilities": {
+    "streaming": true,
+    "extensions": [
+      {
+        "uri": "https://github.com/google-gemini/gemini-cli/blob/main/docs/a2a/developer-profile/v0/spec.md",
+        "description": "An extension for interactive development tasks, enabling features like code generation, tool usage, and real-time status updates.",
+        "required": true
+      }
+    ]
+  }
+}
+```
+
+**Versioning**
+
+The agent card `uri` field contains an embedded semantic version. The client
+must extract this version to determine compatibility with the agent extension
+using the compatibility logic defined in Semantic Versioning 2.0.0 spec.
+
+### 3.2 Schema Definitions
+
+This section defines the schemas for the `development-tool` A2A extension,
+organized by their function within the communication flow. Note that all custom
+objects included in the `metadata` field (e.g. `Message.metadata`) must be keyed
+by the unique URI that points to that extension’s spec to prevent naming
+collisions with other extensions.
+
+**Initialization & Configuration**
+
+The first message in a session must contain an `AgentSettings` object in its
+metadata. This object provides the agent with the necessary configuration
+information for proper initialization. Additional configuration settings (ex.
+MCP servers, allowed tools, etc.) can be added to this message.
+
+**Schema**
+
+```proto
+syntax = "proto3";
+
+// Configuration settings for the Gemini CLI agent.
+message AgentSettings {
+  // The absolute path to the workspace directory where the agent will execute.
+  string workspace_path = 1;
+}
+```
+
+**Agent-to-Client Messages**
+
+All real-time updates from the agent (including its thoughts, tool calls, and
+simple text replies) are streamed to the client as `TaskStatusUpdateEvents`.
+
+Each Event contains a `Message` object, which holds the content in one of two
+formats:
+
+- **TextPart**: Used for standard text messages. This part requires no custom
+  schema.
+- **DataPart**: Used for complex, structured objects. Tool Calls and Thoughts
+  are sent this way, each using their respective schemas defined below.
+
+**Tool Calls**
+
+The `ToolCall` schema is designed to provide a structured representation of a
+tool’s execution lifecycle. This protocol defines a clear state machine and
+provides detailed schemas for common development tasks (file edits, shell
+commands, MCP Tool), ensuring clients can build reliable UIs without being tied
+to a specific agent implementation.
+
+The core principle is that the agent sends a `ToolCall` object on every update.
+This makes client-side logic stateless and simple.
+
+**Tool Call Lifecycle**
+
+1.  **Creation**: The agent sends a `ToolCall` object with `status: PENDING`. If
+    user permission is required, the `confirmation_request` field will be
+    populated.
+2.  **Confirmation**: If the client needs to confirm the message, the client
+    will send a `ToolCallConfirmation`. If the client responds with a
+    cancellation, execution will be skipped.
+3.  **Execution**: Once approved (or if no approval is required), the agent
+    sends an update with `status: EXECUTING`. It can stream real-time progress
+    by updating the `live_content` field.
+4.  **Completion**: The agent sends a final update with the status set to
+    `SUCCEEDED`, `FAILED`, or `CANCELLED` and populates the appropriate result
+    field.
+
+**Schema**
+
+```proto
+syntax = "proto3";
+
+import "google/protobuf/struct.proto";
+
+// ToolCall is the central message representing a tool's execution lifecycle.
+// The entire object is sent from the agent to client on every update.
+message ToolCall {
+  // A unique identifier, assigned by the agent
+  string tool_call_id = 1;
+
+  // The current state of the tool call in its lifecycle
+  ToolCallStatus status = 2;
+
+  // Name of the tool being called (e.g. 'Edit', 'ShellTool')
+  string tool_name = 3;
+
+  // An optional description of the tool call's purpose to show the user
+  optional string description = 4;
+
+  // The structured input params provided by the LLM for tool invocation.
+  google.protobuf.Struct input_parameters = 5;
+
+  // String containing the real-time output from the tool as it executes (primarily designed for shell output).
+  // During streaming the entire string is replaced on each update
+  optional string live_content = 6;
+
+  // The final result of the tool (used to replace live_content when applicable)
+  oneof result {
+    // The output on tool success
+    ToolOutput output = 7;
+    // The error details if the tool failed
+    ErrorDetails error = 8;
+  }
+
+  // If the tool requires user confirmation, this field will be populated while status is PENDING
+  optional ConfirmationRequest confirmation_request = 9;
+}
+
+// Possible execution status of a ToolCall
+enum ToolCallStatus {
+  STATUS_UNSPECIFIED = 0;
+  PENDING = 1;
+  EXECUTING = 2;
+  SUCCEEDED = 3;
+  FAILED = 4;
+  CANCELLED = 5;
+}
+
+// ToolOutput represents the final, successful, output of a tool
+message ToolOutput {
+  oneof result {
+    string text = 1;
+    // For ToolCalls which resulted in a file modification
+    FileDiff diff = 2;
+    // A generic fallback for any other structured JSON data
+    google.protobuf.Struct structured_data = 3;
+  }
+}
+
+// A structured representation of an error
+message ErrorDetails {
+  // User facing error message
+  string message = 1;
+  // Optional agent-specific error type or category (e.g. read_content_failure, grep_execution_error, mcp_tool_error)
+  optional string type = 2;
+  // Optional status code
+  optional int32 status_code = 3;
+}
+
+// ConfirmationRequest is sent from the agent to client to request user permission for a ToolCall
+message ConfirmationRequest {
+  // A list of choices for the user to select from
+  repeated ConfirmationOption options = 1;
+  // Specific details of the action requiring user confirmation
+  oneof details {
+    ExecuteDetails execute_details = 2;
+    FileDiff file_edit_details = 3;
+    McpDetails mcp_details = 4;
+    GenericDetails generic_details = 5;
+  }
+}
+
+// A single choice presented to the user during a confirmation request
+message ConfirmationOption {
+  // Unique ID for the choice (e.g. proceed_once, cancel)
+  string id = 1;
+  // Human-readable choice (e.g. Allow Once, Reject).
+  string name = 2;
+  // An optional longer description for a tooltip
+  optional string description = 3;
+}
+
+// Details for a request to execute a shell command
+message ExecuteDetails {
+  // The shell command to be executed
+  string command = 1;
+  // An optional directory in which the command will be run
+  optional string working_directory = 2;
+}
+
+
+message FileDiff {
+  string file_name = 1;
+  // The absolute path to the file to modify
+  string file_path = 2;
+  // The original content, if the file exists
+  optional string old_content = 3;
+  string new_content = 4;
+  // Pre-formatted diff string for display
+  optional string formatted_diff = 5;
+}
+
+// Details for an MCP (Model Context Protocol) tool confirmation
+message McpDetails {
+  // The name of the MCP server that provides the tool
+  string server_name = 1;
+  // THe name of the tool being called from the MCP Server
+  string tool_name = 2;
+}
+
+// Generic catch-all for ToolCall requests that don't fit other types
+message GenericDetails {
+  // Description of the action requiring confirmation
+  string description = 1;
+}
+```
+
+**Agent Thoughts**
+
+**Schema**
+
+```proto
+syntax = "proto3";
+
+// Represents a thought with a subject and a detailed description.
+message AgentThought {
+  // A concise subject line or title for the thought.
+  string subject = 1;
+
+  // The description or elaboration of the thought itself.
+  string description = 2;
+}
+```
+
+**Event Metadata**
+
+The `metadata` object in `TaskStatusUpdateEvent` is used by the A2A client to
+deserialize the `TaskStatusUpdateEvents` into their appropriate objects.
+
+**Schema**
+
+```proto
+syntax = "proto3";
+
+// A DevelopmentToolEvent event.
+message DevelopmentToolEvent {
+  // Enum representing the specific type of development tool event.
+  enum DevelopmentToolEventKind {
+    // The default, unspecified value.
+    DEVELOPMENT_TOOL_EVENT_KIND_UNSPECIFIED = 0;
+    TOOL_CALL_CONFIRMATION = 1;
+    TOOL_CALL_UPDATE = 2;
+    TEXT_CONTENT = 3;
+    STATE_CHANGE = 4;
+    THOUGHT = 5;
+  }
+
+  // The specific kind of event that occurred.
+  DevelopmentToolEventKind kind = 1;
+
+  // The model used for this event.
+  string model = 2;
+
+  // The tier of the user (optional).
+  string user_tier = 3;
+
+  // An unexpected error occurred in the agent execution (optional).
+  string error = 4;
+}
+```
+
+**Client-to-Agent Messages**
+
+When the agent sends a `TaskStatusUpdateEvent` with `status.state` set to
+`input-required` and its message contains a `ConfirmationRequest`, the client
+must respond by sending a new `message/stream` request.
+
+This new request must include the `contextId` and the `taskId` from the ongoing
+task and contain a `ToolCallConfirmation` object. This object conveys the user's
+decision regarding the tool call that was awaiting approval.
+
+**Schema**
+
+```proto
+syntax = "proto3";
+
+// The client's response to a ConfirmationRequest.
+message ToolCallConfirmation {
+  // A unique identifier, assigned by the agent
+  string tool_call_id = 1;
+  // The 'id' of the ConfirmationOption chosen by the user.
+  string selected_option_id = 2;
+  // Included if the user modifies the proposed change.
+  // The type should correspond to the original ConfirmationRequest details.
+  oneof modified_details {
+    // Corresponds to a FileDiff confirmation
+    ModifiedFileDetails file_details = 3;
+  }
+}
+
+message ModifiedFileDetails {
+  // The new content after user edits.
+  string new_content = 1;
+}
+```
+
+### 3.3 Method Definitions
+
+This section defines the new methods introduced by the `development-tool`
+extension.
+
+**Method: `commands/get`**
+
+This method allows the client to discover slash commands supported by Gemini
+CLI. The client should call this method during startup to dynamically populate
+its command list.
+
+```proto
+// Response message containing the list of all top-level slash commands.
+message GetAllSlashCommandsResponse {
+  // A list of the top-level slash commands.
+  repeated SlashCommand commands = 1;
+}
+
+// Represents a single slash command, which can contain subcommands.
+message SlashCommand {
+  // The primary name of the command.
+  string name = 1;
+  // A detailed description of what the command does.
+  string description = 2;
+  // A list of arguments that the command accepts.
+  repeated SlashCommandArgument arguments = 3;
+  // A list of nested subcommands.
+  repeated SlashCommand sub_commands = 4;
+}
+
+// Defines the structure for a single slash command argument.
+message SlashCommandArgument {
+  // The name of the argument.
+  string name = 1;
+  // A brief description of what the argument is for.
+  string description = 2;
+  // Whether the argument is required or optional.
+  bool is_required = 3;
+}
+```
+
+**Method: `command/execute`**
+
+This method allows the client to execute a slash command. Following the initial
+`ExecuteSlashCommandResponse`, the agent will use the standard streaming
+mechanism to communicate the command's progress and output. All subsequent
+updates, including textual output, agent thoughts, and any required user
+confirmations for tool calls (like executing a shell command), will be sent as
+`TaskStatusUpdateEvent` messages, re-using the schemas defined above.
+
+```proto
+// Request to execute a specific slash command.
+message ExecuteSlashCommandRequest {
+  // The path to the command, e.g., ["memory", "list"] for /memory list
+  repeated string command_path = 1;
+  // The arguments for the command as a single string.
+  string args = 2;
+}
+
+// Enum for the initial status of a command execution request.
+enum CommandExecutionStatus {
+  // Default unspecified status.
+  COMMAND_EXECUTION_STATUS_UNSPECIFIED = 0;
+  // The command was successfully received and its execution has started.
+  STARTED = 1;
+  // The command failed to start (e.g., command not found, invalid format).
+  FAILED_TO_START = 2;
+  // The command has been paused and is waiting for the user to confirm
+  // a set of shell commands.
+  AWAITING_SHELL_CONFIRMATION = 3;
+  // The command has been paused and is waiting for the user to confirm
+  // a specific action.
+  AWAITING_ACTION_CONFIRMATION = 4;
+}
+
+// The immediate, async response after requesting a command execution.
+message ExecuteSlashCommandResponse {
+  // A unique taskID for this specific command execution.
+  string execution_id = 1;
+  // The initial status of the command execution.
+  CommandExecutionStatus status = 2;
+  // An optional message, particularly useful for explaining why a command
+  // failed to start.
+  string message = 3;
+}
+```
+
+## 4. Separation of Concerns
+
+We believe that all client-side context (ex., workspace state) and client-side
+tool execution (ex. read active buffers) should be routed through MCP.
+
+This approach enforces a strict separation of concerns: the A2A
+`development-tool` extension standardizes communication to the agent, while MCP
+serves as the single, authoritative interface for client-side capabilities.
+
+## Appendix
+
+### A. Example Interaction Flow
+
+1.  **Client -> Server**: The client sends a `message/stream` request containing
+    the initial prompt and configuration in an `AgentSettings` object.
+2.  **Server -> Client**: SSE stream begins.
+    - **Event 1**: The server sends a `Task` object with
+      `status.state: 'submitted'` and the new `taskId`.
+    - **Event 2**: The server sends a `TaskStatusUpdateEvent` with the metadata
+      `kind` set to `'STATE_CHANGE'` and `status.state` set to `'working'`.
+3.  **Agent Logic**: The agent processes the prompt and decides to call the
+    `write_file` tool, which requires user confirmation.
+4.  **Server -> Client**:
+    - **Event 3**: The server sends a `TaskStatusUpdateEvent`. The metadata
+      `kind` is `'TOOL_CALL_UPDATE'`, and the `DataPart` contains a `ToolCall`
+      object with its `status` as `'PENDING'` and a populated
+      `confirmation_request`.
+    - **Event 4**: The server sends a final `TaskStatusUpdateEvent` for this
+      exchange. The metadata `kind` is `'STATE_CHANGE'`, the `status.state` is
+      `'input-required'`, and `final` is `true`. The stream for this request
+      ends.
+5.  **Client**: The client UI renders the confirmation prompt based on the
+    `ToolCall` object from Event 3. The user clicks "Approve."
+6.  **Client -> Server**: The client sends a new `message/stream` request. It
+    includes the `taskId` from the ongoing task and a `DataPart` containing a
+    `ToolCallConfirmation` object (e.g.,
+    `{"tool_call_id": "...", "selected_option_id": "proceed_once"}`).
+7.  **Server -> Client**: A new SSE stream begins for the second request.
+    - **Event 1**: The server sends a `TaskStatusUpdateEvent` with
+      `kind: 'TOOL_CALL_UPDATE'`, containing the `ToolCall` object with its
+      `status` now set to `'EXECUTING'`.
+    - **Event 2**: After the tool runs, the server sends another
+      `TaskStatusUpdateEvent` with `kind: 'TOOL_CALL_UPDATE'`, containing the
+      `ToolCall` with its `status` as `'SUCCEEDED'`.
+8.  **Agent Logic**: The agent receives the successful tool result and generates
+    a final textual response.
+9.  **Server -> Client**:
+    - **Event 3**: The server sends a `TaskStatusUpdateEvent` with
+      `kind: 'TEXT_CONTENT'` and a `TextPart` containing the agent's final
+      answer.
+    - **Event 4**: The server sends the final `TaskStatusUpdateEvent`. The
+      `kind` is `'STATE_CHANGE'`, the `status.state` is `'completed'`, and
+      `final` is `true`. The stream ends.
+10. **Client**: The client displays the final answer. The task is now complete
+    but can be continued by sending another message with the same `taskId`.

packages/a2a-server/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './src/index.js';

packages/a2a-server/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@google/gemini-cli-a2a-server",
+  "version": "0.52.0-nightly.20260707.g27a3da3e8",
+  "description": "Gemini CLI A2A Server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/google-gemini/gemini-cli.git",
+    "directory": "packages/a2a-server"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "gemini-cli-a2a-server": "dist/a2a-server.mjs"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build_package.js",
+    "start": "node dist/src/http/server.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@a2a-js/sdk": "0.3.11",
+    "@google-cloud/storage": "7.19.0",
+    "@google/gemini-cli-core": "file:../core",
+    "express": "5.1.0",
+    "fs-extra": "11.3.0",
+    "strip-json-comments": "3.1.1",
+    "tar": "7.5.8",
+    "uuid": "13.0.0",
+    "winston": "3.17.0"
+  },
+  "devDependencies": {
+    "@google/genai": "1.30.0",
+    "@types/express": "5.0.3",
+    "@types/fs-extra": "11.0.4",
+    "@types/supertest": "6.0.3",
+    "@types/tar": "6.1.13",
+    "dotenv": "16.4.5",
+    "supertest": "7.1.4",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

packages/a2a-server/src/agent/executor.test.ts

@@ -0,0 +1,303 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { CoderAgentExecutor } from './executor.js';
+import type {
+  ExecutionEventBus,
+  RequestContext,
+  TaskStore,
+} from '@a2a-js/sdk/server';
+import { EventEmitter } from 'node:events';
+import { requestStorage } from '../http/requestStorage.js';
+
+// Mocks for constructor dependencies
+vi.mock('../config/config.js', () => ({
+  loadConfig: vi.fn().mockReturnValue({
+    getSessionId: () => 'test-session',
+    getTargetDir: () => '/tmp',
+    getCheckpointingEnabled: () => false,
+  }),
+  loadEnvironment: vi.fn(),
+  setIsTrusted: vi.fn().mockReturnValue(false),
+  setTargetDir: vi.fn().mockReturnValue('/tmp'),
+}));
+
+vi.mock('../config/settings.js', () => ({
+  loadSettings: vi.fn().mockReturnValue({}),
+}));
+
+vi.mock('../config/extension.js', () => ({
+  loadExtensions: vi.fn().mockReturnValue([]),
+}));
+
+vi.mock('../http/requestStorage.js', () => ({
+  requestStorage: {
+    getStore: vi.fn(),
+  },
+}));
+
+vi.mock('./task.js', () => {
+  const mockTaskInstance = (taskId: string, contextId: string) => ({
+    id: taskId,
+    contextId,
+    taskState: 'working',
+    acceptUserMessage: vi
+      .fn()
+      .mockImplementation(async function* (context, aborted) {
+        const isConfirmation = (
+          context.userMessage.parts as Array<{ kind: string }>
+        ).some((p) => p.kind === 'confirmation');
+        // Hang only for main user messages (text), allow confirmations to finish quickly
+        if (!isConfirmation && aborted) {
+          await new Promise((resolve) => {
+            aborted.addEventListener('abort', resolve, { once: true });
+          });
+        }
+        yield { type: 'content', value: 'hello' };
+      }),
+    acceptAgentMessage: vi.fn().mockResolvedValue(undefined),
+    scheduleToolCalls: vi.fn().mockResolvedValue(undefined),
+    waitForPendingTools: vi.fn().mockResolvedValue(undefined),
+    getAndClearCompletedTools: vi.fn().mockReturnValue([]),
+    get hasPendingTools() {
+      return false;
+    },
+    get pendingToolsCount() {
+      return 0;
+    },
+    addToolResponsesToHistory: vi.fn(),
+    sendCompletedToolsToLlm: vi.fn().mockImplementation(async function* () {}),
+    cancelPendingTools: vi.fn(),
+    setTaskStateAndPublishUpdate: vi.fn(),
+    dispose: vi.fn(),
+    getMetadata: vi.fn().mockResolvedValue({}),
+    geminiClient: {
+      initialize: vi.fn().mockResolvedValue(undefined),
+    },
+    toSDKTask: () => ({
+      id: taskId,
+      contextId,
+      kind: 'task',
+      status: { state: 'working', timestamp: new Date().toISOString() },
+      metadata: {},
+      history: [],
+      artifacts: [],
+    }),
+  });
+
+  const MockTask = vi.fn().mockImplementation(mockTaskInstance);
+  (MockTask as unknown as { create: Mock }).create = vi
+    .fn()
+    .mockImplementation(async (taskId: string, contextId: string) =>
+      mockTaskInstance(taskId, contextId),
+    );
+
+  return { Task: MockTask };
+});
+
+describe('CoderAgentExecutor', () => {
+  let executor: CoderAgentExecutor;
+  let mockTaskStore: TaskStore;
+  let mockEventBus: ExecutionEventBus;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockTaskStore = {
+      save: vi.fn().mockResolvedValue(undefined),
+      load: vi.fn().mockResolvedValue(undefined),
+      delete: vi.fn().mockResolvedValue(undefined),
+      list: vi.fn().mockResolvedValue([]),
+    } as unknown as TaskStore;
+
+    mockEventBus = new EventEmitter() as unknown as ExecutionEventBus;
+    mockEventBus.publish = vi.fn();
+    mockEventBus.finished = vi.fn();
+
+    executor = new CoderAgentExecutor(mockTaskStore);
+  });
+
+  it('should distinguish between primary and secondary execution', async () => {
+    const taskId = 'test-task';
+    const contextId = 'test-context';
+
+    const mockSocket = new EventEmitter();
+    const requestContext = {
+      userMessage: {
+        messageId: 'msg-1',
+        taskId,
+        contextId,
+        parts: [{ kind: 'text', text: 'hi' }],
+        metadata: {
+          coderAgent: { kind: 'agent-settings', workspacePath: '/tmp' },
+        },
+      },
+    } as unknown as RequestContext;
+
+    // Mock requestStorage for primary
+    (requestStorage.getStore as Mock).mockReturnValue({
+      req: { socket: mockSocket },
+    });
+
+    // First execution (Primary)
+    const primaryPromise = executor.execute(requestContext, mockEventBus);
+
+    // Give it enough time to reach line 490 in executor.ts
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(
+      (
+        executor as unknown as { executingTasks: Set<string> }
+      ).executingTasks.has(taskId),
+    ).toBe(true);
+    const wrapper = executor.getTask(taskId);
+    expect(wrapper).toBeDefined();
+
+    // Mock requestStorage for secondary
+    const secondarySocket = new EventEmitter();
+    (requestStorage.getStore as Mock).mockReturnValue({
+      req: { socket: secondarySocket },
+    });
+
+    const secondaryRequestContext = {
+      userMessage: {
+        messageId: 'msg-2',
+        taskId,
+        contextId,
+        parts: [{ kind: 'confirmation', callId: '1', outcome: 'proceed' }],
+        metadata: {
+          coderAgent: { kind: 'agent-settings', workspacePath: '/tmp' },
+        },
+      },
+    } as unknown as RequestContext;
+
+    const secondaryPromise = executor.execute(
+      secondaryRequestContext,
+      mockEventBus,
+    );
+
+    // Secondary execution should NOT add to executingTasks (already there)
+    // and should return early after its loop
+    await secondaryPromise;
+
+    // Task should still be in executingTasks and NOT disposed
+    expect(
+      (
+        executor as unknown as { executingTasks: Set<string> }
+      ).executingTasks.has(taskId),
+    ).toBe(true);
+    expect(wrapper?.task.dispose).not.toHaveBeenCalled();
+
+    // Now simulate secondary socket closure - it should NOT affect primary
+    secondarySocket.emit('end');
+    expect(
+      (
+        executor as unknown as { executingTasks: Set<string> }
+      ).executingTasks.has(taskId),
+    ).toBe(true);
+    expect(wrapper?.task.dispose).not.toHaveBeenCalled();
+
+    // Set to terminal state to verify disposal on finish
+    wrapper!.task.taskState = 'completed';
+
+    // Now close primary socket
+    mockSocket.emit('end');
+
+    await primaryPromise;
+
+    expect(
+      (
+        executor as unknown as { executingTasks: Set<string> }
+      ).executingTasks.has(taskId),
+    ).toBe(false);
+    expect(wrapper?.task.dispose).toHaveBeenCalled();
+  });
+
+  it('should evict task from cache when it reaches terminal state', async () => {
+    const taskId = 'test-task-terminal';
+    const contextId = 'test-context';
+
+    const mockSocket = new EventEmitter();
+    (requestStorage.getStore as Mock).mockReturnValue({
+      req: { socket: mockSocket },
+    });
+
+    const requestContext = {
+      userMessage: {
+        messageId: 'msg-1',
+        taskId,
+        contextId,
+        parts: [{ kind: 'text', text: 'hi' }],
+        metadata: {
+          coderAgent: { kind: 'agent-settings', workspacePath: '/tmp' },
+        },
+      },
+    } as unknown as RequestContext;
+
+    const primaryPromise = executor.execute(requestContext, mockEventBus);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const wrapper = executor.getTask(taskId)!;
+    expect(wrapper).toBeDefined();
+    // Simulate terminal state
+    wrapper.task.taskState = 'completed';
+
+    // Finish primary execution
+    mockSocket.emit('end');
+    await primaryPromise;
+
+    expect(executor.getTask(taskId)).toBeUndefined();
+    expect(wrapper.task.dispose).toHaveBeenCalled();
+  });
+
+  it('should yield the turn and transition to input-required if tools are pending', async () => {
+    const taskId = 'test-task-pending-tools';
+    const contextId = 'test-context';
+
+    const mockSocket = new EventEmitter();
+    (requestStorage.getStore as Mock).mockReturnValue({
+      req: { socket: mockSocket },
+    });
+
+    // Pre-create the task to safely modify its mocked methods before execution
+    const wrapper = await executor.createTask(
+      taskId,
+      contextId,
+      undefined,
+      mockEventBus,
+    );
+    const hasPendingToolsSpy = vi
+      .spyOn(wrapper.task, 'hasPendingTools', 'get')
+      .mockReturnValue(true);
+    vi.spyOn(wrapper.task, 'pendingToolsCount', 'get').mockReturnValue(1);
+
+    const requestContext = {
+      userMessage: {
+        messageId: 'msg-1',
+        taskId,
+        contextId,
+        parts: [{ kind: 'confirmation', callId: '1', outcome: 'proceed' }],
+        metadata: {
+          coderAgent: { kind: 'agent-settings', workspacePath: '/tmp' },
+        },
+      },
+    } as unknown as RequestContext;
+
+    await executor.execute(requestContext, mockEventBus);
+
+    // Assert that the executor yielded the turn correctly without further progression
+    expect(hasPendingToolsSpy).toHaveBeenCalled();
+    expect(wrapper.task.getAndClearCompletedTools).not.toHaveBeenCalled();
+    expect(wrapper.task.sendCompletedToolsToLlm).not.toHaveBeenCalled();
+    expect(wrapper.task.setTaskStateAndPublishUpdate).toHaveBeenCalledWith(
+      'input-required',
+      expect.any(Object),
+      undefined,
+      undefined,
+      true,
+    );
+  });
+});

packages/a2a-server/src/agent/executor.ts

@@ -0,0 +1,673 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Message, Task as SDKTask } from '@a2a-js/sdk';
+import type {
+  TaskStore,
+  AgentExecutor,
+  AgentExecutionEvent,
+  RequestContext,
+  ExecutionEventBus,
+} from '@a2a-js/sdk/server';
+import {
+  GeminiEventType,
+  SimpleExtensionLoader,
+  type ToolCallRequestInfo,
+  type Config,
+} from '@google/gemini-cli-core';
+import { v4 as uuidv4 } from 'uuid';
+
+import { logger } from '../utils/logger.js';
+import {
+  CoderAgentEvent,
+  getPersistedState,
+  setPersistedState,
+  type StateChange,
+  type AgentSettings,
+  type PersistedStateMetadata,
+  getContextIdFromMetadata,
+  getAgentSettingsFromMetadata,
+} from '../types.js';
+import {
+  loadConfig,
+  loadEnvironment,
+  setIsTrusted,
+  setTargetDir,
+} from '../config/config.js';
+import { loadSettings } from '../config/settings.js';
+import { loadExtensions } from '../config/extension.js';
+import { Task } from './task.js';
+import { requestStorage } from '../http/requestStorage.js';
+import { pushTaskStateFailed } from '../utils/executor_utils.js';
+
+/**
+ * Provides a wrapper for Task. Passes data from Task to SDKTask.
+ * The idea is to use this class inside CoderAgentExecutor to replace Task.
+ */
+class TaskWrapper {
+  task: Task;
+  agentSettings: AgentSettings;
+
+  constructor(task: Task, agentSettings: AgentSettings) {
+    this.task = task;
+    this.agentSettings = agentSettings;
+  }
+
+  get id() {
+    return this.task.id;
+  }
+
+  toSDKTask(): SDKTask {
+    const persistedState: PersistedStateMetadata = {
+      _agentSettings: this.agentSettings,
+      _taskState: this.task.taskState,
+    };
+
+    const sdkTask: SDKTask = {
+      id: this.task.id,
+      contextId: this.task.contextId,
+      kind: 'task',
+      status: {
+        state: this.task.taskState,
+        timestamp: new Date().toISOString(),
+      },
+      metadata: setPersistedState({}, persistedState),
+      history: [],
+      artifacts: [],
+    };
+    sdkTask.metadata!['_contextId'] = this.task.contextId;
+    return sdkTask;
+  }
+}
+
+/**
+ * CoderAgentExecutor implements the agent's core logic for code generation.
+ */
+export class CoderAgentExecutor implements AgentExecutor {
+  private tasks: Map<string, TaskWrapper> = new Map();
+  // Track tasks with an active execution loop.
+  private executingTasks = new Set<string>();
+
+  constructor(private taskStore?: TaskStore) {}
+
+  private async getConfig(
+    agentSettings: AgentSettings,
+    taskId: string,
+  ): Promise<Config> {
+    const workspaceRoot = setTargetDir(agentSettings);
+    loadEnvironment(); // Will override any global env with workspace envs
+    const isTrusted = setIsTrusted(agentSettings);
+    const settings = loadSettings(workspaceRoot, isTrusted);
+    const extensions = loadExtensions(workspaceRoot);
+    return loadConfig(
+      settings,
+      new SimpleExtensionLoader(extensions),
+      taskId,
+      isTrusted,
+    );
+  }
+
+  /**
+   * Reconstructs TaskWrapper from SDKTask.
+   */
+  async reconstruct(
+    sdkTask: SDKTask,
+    eventBus?: ExecutionEventBus,
+  ): Promise<TaskWrapper> {
+    const metadata = sdkTask.metadata || {};
+    const persistedState = getPersistedState(metadata);
+
+    if (!persistedState) {
+      throw new Error(
+        `Cannot reconstruct task ${sdkTask.id}: missing persisted state in metadata.`,
+      );
+    }
+
+    const agentSettings = persistedState._agentSettings;
+    const config = await this.getConfig(agentSettings, sdkTask.id);
+    const contextId: string =
+      getContextIdFromMetadata(metadata) || sdkTask.contextId;
+    const runtimeTask = await Task.create(
+      sdkTask.id,
+      contextId,
+      config,
+      eventBus,
+      agentSettings.autoExecute,
+    );
+    runtimeTask.taskState = persistedState._taskState;
+    await runtimeTask.geminiClient.initialize();
+
+    const wrapper = new TaskWrapper(runtimeTask, agentSettings);
+    this.tasks.set(sdkTask.id, wrapper);
+    logger.info(`Task ${sdkTask.id} reconstructed from store.`);
+    return wrapper;
+  }
+
+  async createTask(
+    taskId: string,
+    contextId: string,
+    agentSettingsInput?: AgentSettings,
+    eventBus?: ExecutionEventBus,
+  ): Promise<TaskWrapper> {
+    const agentSettings: AgentSettings = agentSettingsInput || {
+      kind: CoderAgentEvent.StateAgentSettingsEvent,
+      workspacePath: process.cwd(),
+    };
+    const config = await this.getConfig(agentSettings, taskId);
+    const runtimeTask = await Task.create(
+      taskId,
+      contextId,
+      config,
+      eventBus,
+      agentSettings.autoExecute,
+    );
+    await runtimeTask.geminiClient.initialize();
+
+    const wrapper = new TaskWrapper(runtimeTask, agentSettings);
+    this.tasks.set(taskId, wrapper);
+    logger.info(`New task ${taskId} created.`);
+    return wrapper;
+  }
+
+  getTask(taskId: string): TaskWrapper | undefined {
+    return this.tasks.get(taskId);
+  }
+
+  getAllTasks(): TaskWrapper[] {
+    return Array.from(this.tasks.values());
+  }
+
+  cancelTask = async (
+    taskId: string,
+    eventBus: ExecutionEventBus,
+  ): Promise<void> => {
+    logger.info(
+      `[CoderAgentExecutor] Received cancel request for task ${taskId}`,
+    );
+    const wrapper = this.tasks.get(taskId);
+
+    if (!wrapper) {
+      logger.warn(
+        `[CoderAgentExecutor] Task ${taskId} not found for cancellation.`,
+      );
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        contextId: uuidv4(),
+        status: {
+          state: 'failed',
+          message: {
+            kind: 'message',
+            role: 'agent',
+            parts: [{ kind: 'text', text: `Task ${taskId} not found.` }],
+            messageId: uuidv4(),
+            taskId,
+          },
+        },
+        final: true,
+      });
+      return;
+    }
+
+    const { task } = wrapper;
+
+    if (task.taskState === 'canceled' || task.taskState === 'failed') {
+      logger.info(
+        `[CoderAgentExecutor] Task ${taskId} is already in a final state: ${task.taskState}. No action needed for cancellation.`,
+      );
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        contextId: task.contextId,
+        status: {
+          state: task.taskState,
+          message: {
+            kind: 'message',
+            role: 'agent',
+            parts: [
+              {
+                kind: 'text',
+                text: `Task ${taskId} is already ${task.taskState}.`,
+              },
+            ],
+            messageId: uuidv4(),
+            taskId,
+          },
+        },
+        final: true,
+      });
+      return;
+    }
+
+    try {
+      logger.info(
+        `[CoderAgentExecutor] Initiating cancellation for task ${taskId}.`,
+      );
+      task.cancelPendingTools('Task canceled by user request.');
+
+      const stateChange: StateChange = {
+        kind: CoderAgentEvent.StateChangeEvent,
+      };
+      task.setTaskStateAndPublishUpdate(
+        'canceled',
+        stateChange,
+        'Task canceled by user request.',
+        undefined,
+        true,
+      );
+      logger.info(
+        `[CoderAgentExecutor] Task ${taskId} cancellation processed. Saving state.`,
+      );
+      await this.taskStore?.save(wrapper.toSDKTask());
+      logger.info(`[CoderAgentExecutor] Task ${taskId} state CANCELED saved.`);
+
+      // Cleanup listener subscriptions to avoid memory leaks.
+      wrapper.task.dispose();
+      this.tasks.delete(taskId);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown error';
+      logger.error(
+        `[CoderAgentExecutor] Error during task cancellation for ${taskId}: ${errorMessage}`,
+        error,
+      );
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        contextId: task.contextId,
+        status: {
+          state: 'failed',
+          message: {
+            kind: 'message',
+            role: 'agent',
+            parts: [
+              {
+                kind: 'text',
+                text: `Failed to process cancellation for task ${taskId}: ${errorMessage}`,
+              },
+            ],
+            messageId: uuidv4(),
+            taskId,
+          },
+        },
+        final: true,
+      });
+    }
+  };
+
+  async execute(
+    requestContext: RequestContext,
+    eventBus: ExecutionEventBus,
+  ): Promise<void> {
+    const userMessage = requestContext.userMessage;
+    const sdkTask = requestContext.task;
+
+    const taskId = sdkTask?.id || userMessage.taskId || uuidv4();
+    const contextId: string =
+      userMessage.contextId ||
+      sdkTask?.contextId ||
+      getContextIdFromMetadata(sdkTask?.metadata) ||
+      uuidv4();
+
+    logger.info(
+      `[CoderAgentExecutor] Executing for taskId: ${taskId}, contextId: ${contextId}`,
+    );
+    logger.info(
+      `[CoderAgentExecutor] userMessage: ${JSON.stringify(userMessage)}`,
+    );
+    eventBus.on('event', (event: AgentExecutionEvent) =>
+      logger.info('[EventBus event]: ', event),
+    );
+
+    const store = requestStorage.getStore();
+    if (!store) {
+      logger.error(
+        '[CoderAgentExecutor] Could not get request from async local storage. Cancellation on socket close will not be handled for this request.',
+      );
+    }
+
+    const abortController = new AbortController();
+    const abortSignal = abortController.signal;
+
+    if (store) {
+      // Grab the raw socket from the request object
+      const socket = store.req.socket;
+      const onSocketEnd = () => {
+        logger.info(
+          `[CoderAgentExecutor] Socket ended for message ${userMessage.messageId} (task ${taskId}). Aborting execution loop.`,
+        );
+        if (!abortController.signal.aborted) {
+          abortController.abort();
+        }
+        // Clean up the listener to prevent memory leaks
+        socket.removeListener('end', onSocketEnd);
+      };
+
+      // Listen on the socket's 'end' event (remote closed the connection)
+      socket.on('end', onSocketEnd);
+      socket.once('close', () => {
+        socket.removeListener('end', onSocketEnd);
+      });
+
+      // It's also good practice to remove the listener if the task completes successfully
+      abortSignal.addEventListener('abort', () => {
+        socket.removeListener('end', onSocketEnd);
+      });
+      logger.info(
+        `[CoderAgentExecutor] Socket close handler set up for task ${taskId}.`,
+      );
+    }
+
+    let wrapper: TaskWrapper | undefined = this.tasks.get(taskId);
+
+    if (wrapper) {
+      wrapper.task.eventBus = eventBus;
+      logger.info(`[CoderAgentExecutor] Task ${taskId} found in memory cache.`);
+    } else if (sdkTask) {
+      logger.info(
+        `[CoderAgentExecutor] Task ${taskId} found in TaskStore. Reconstructing...`,
+      );
+      try {
+        wrapper = await this.reconstruct(sdkTask, eventBus);
+      } catch (e) {
+        logger.error(
+          `[CoderAgentExecutor] Failed to hydrate task ${taskId}:`,
+          e,
+        );
+        const stateChange: StateChange = {
+          kind: CoderAgentEvent.StateChangeEvent,
+        };
+        eventBus.publish({
+          kind: 'status-update',
+          taskId,
+          contextId: sdkTask.contextId,
+          status: {
+            state: 'failed',
+            message: {
+              kind: 'message',
+              role: 'agent',
+              parts: [
+                {
+                  kind: 'text',
+                  text: 'Internal error: Task state lost or corrupted.',
+                },
+              ],
+              messageId: uuidv4(),
+              taskId,
+              contextId: sdkTask.contextId,
+            } as Message,
+          },
+          final: true,
+          metadata: { coderAgent: stateChange },
+        });
+        return;
+      }
+    } else {
+      logger.info(`[CoderAgentExecutor] Creating new task ${taskId}.`);
+      const agentSettings = getAgentSettingsFromMetadata(userMessage.metadata);
+      try {
+        wrapper = await this.createTask(
+          taskId,
+          contextId,
+          agentSettings,
+          eventBus,
+        );
+      } catch (error) {
+        logger.error(
+          `[CoderAgentExecutor] Error creating task ${taskId}:`,
+          error,
+        );
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        pushTaskStateFailed(error, eventBus, taskId, contextId);
+        return;
+      }
+      const newTaskSDK = wrapper.toSDKTask();
+      eventBus.publish({
+        ...newTaskSDK,
+        kind: 'task',
+        status: { state: 'submitted', timestamp: new Date().toISOString() },
+        history: [userMessage],
+      });
+      try {
+        await this.taskStore?.save(newTaskSDK);
+        logger.info(`[CoderAgentExecutor] New task ${taskId} saved to store.`);
+      } catch (saveError) {
+        logger.error(
+          `[CoderAgentExecutor] Failed to save new task ${taskId} to store:`,
+          saveError,
+        );
+      }
+    }
+
+    if (!wrapper) {
+      logger.error(
+        `[CoderAgentExecutor] Task ${taskId} is unexpectedly undefined after load/create.`,
+      );
+      return;
+    }
+
+    const currentTask = wrapper.task;
+
+    if (['canceled', 'failed', 'completed'].includes(currentTask.taskState)) {
+      logger.warn(
+        `[CoderAgentExecutor] Attempted to execute task ${taskId} which is already in state ${currentTask.taskState}. Ignoring.`,
+      );
+      return;
+    }
+
+    if (this.executingTasks.has(taskId)) {
+      logger.info(
+        `[CoderAgentExecutor] Task ${taskId} has a pending execution. Processing message and yielding.`,
+      );
+      currentTask.eventBus = eventBus;
+      for await (const _ of currentTask.acceptUserMessage(
+        requestContext,
+        abortController.signal,
+      )) {
+        logger.info(
+          `[CoderAgentExecutor] Processing user message ${userMessage.messageId} in secondary execution loop for task ${taskId}.`,
+        );
+      }
+      // End this execution-- the original/source will be resumed.
+      return;
+    }
+
+    // Check if this is the primary/initial execution for this task
+    const isPrimaryExecution = !this.executingTasks.has(taskId);
+
+    if (!isPrimaryExecution) {
+      logger.info(
+        `[CoderAgentExecutor] Primary execution already active for task ${taskId}. Starting secondary loop for message ${userMessage.messageId}.`,
+      );
+      currentTask.eventBus = eventBus;
+      for await (const _ of currentTask.acceptUserMessage(
+        requestContext,
+        abortController.signal,
+      )) {
+        logger.info(
+          `[CoderAgentExecutor] Processing user message ${userMessage.messageId} in secondary execution loop for task ${taskId}.`,
+        );
+      }
+      // End this execution-- the original/source will be resumed.
+      return;
+    }
+
+    logger.info(
+      `[CoderAgentExecutor] Starting main execution for message ${userMessage.messageId} for task ${taskId}.`,
+    );
+    this.executingTasks.add(taskId);
+
+    try {
+      let agentTurnActive = true;
+      logger.info(`[CoderAgentExecutor] Task ${taskId}: Processing user turn.`);
+      let agentEvents = currentTask.acceptUserMessage(
+        requestContext,
+        abortSignal,
+      );
+
+      while (agentTurnActive) {
+        logger.info(
+          `[CoderAgentExecutor] Task ${taskId}: Processing agent turn (LLM stream).`,
+        );
+        const toolCallRequests: ToolCallRequestInfo[] = [];
+        for await (const event of agentEvents) {
+          if (abortSignal.aborted) {
+            logger.warn(
+              `[CoderAgentExecutor] Task ${taskId}: Abort signal received during agent event processing.`,
+            );
+            throw new Error('Execution aborted');
+          }
+          if (event.type === GeminiEventType.ToolCallRequest) {
+            toolCallRequests.push(event.value);
+            continue;
+          }
+          await currentTask.acceptAgentMessage(event);
+        }
+
+        if (abortSignal.aborted) throw new Error('Execution aborted');
+
+        if (toolCallRequests.length > 0) {
+          logger.info(
+            `[CoderAgentExecutor] Task ${taskId}: Found ${toolCallRequests.length} tool call requests. Scheduling as a batch.`,
+          );
+          await currentTask.scheduleToolCalls(toolCallRequests, abortSignal);
+        }
+
+        logger.info(
+          `[CoderAgentExecutor] Task ${taskId}: Waiting for pending tools if any.`,
+        );
+        await currentTask.waitForPendingTools();
+        logger.info(
+          `[CoderAgentExecutor] Task ${taskId}: All pending tools completed or none were pending.`,
+        );
+
+        if (abortSignal.aborted) throw new Error('Execution aborted');
+
+        if (currentTask.hasPendingTools) {
+          logger.info(
+            `[CoderAgentExecutor] Task ${taskId}: There are still ${currentTask.pendingToolsCount} pending tools waiting for approval. Yielding to user.`,
+          );
+          agentTurnActive = false;
+        } else {
+          const completedTools = currentTask.getAndClearCompletedTools();
+
+          if (completedTools.length > 0) {
+            // If all completed tool calls were canceled, manually add them to history and set state to input-required, final:true
+            if (completedTools.every((tool) => tool.status === 'cancelled')) {
+              logger.info(
+                `[CoderAgentExecutor] Task ${taskId}: All tool calls were cancelled. Updating history and ending agent turn.`,
+              );
+              currentTask.addToolResponsesToHistory(completedTools);
+              agentTurnActive = false;
+              const stateChange: StateChange = {
+                kind: CoderAgentEvent.StateChangeEvent,
+              };
+              currentTask.setTaskStateAndPublishUpdate(
+                'input-required',
+                stateChange,
+                undefined,
+                undefined,
+                true,
+              );
+            } else {
+              logger.info(
+                `[CoderAgentExecutor] Task ${taskId}: Found ${completedTools.length} completed tool calls. Sending results back to LLM.`,
+              );
+
+              agentEvents = currentTask.sendCompletedToolsToLlm(
+                completedTools,
+                abortSignal,
+              );
+              // Continue the loop to process the LLM response to the tool results.
+            }
+          } else {
+            logger.info(
+              `[CoderAgentExecutor] Task ${taskId}: No more tool calls to process. Ending agent turn.`,
+            );
+            agentTurnActive = false;
+          }
+        }
+      }
+
+      logger.info(
+        `[CoderAgentExecutor] Task ${taskId}: Agent turn finished, setting to input-required.`,
+      );
+      const stateChange: StateChange = {
+        kind: CoderAgentEvent.StateChangeEvent,
+      };
+      currentTask.setTaskStateAndPublishUpdate(
+        'input-required',
+        stateChange,
+        undefined,
+        undefined,
+        true,
+      );
+    } catch (error) {
+      if (abortSignal.aborted) {
+        logger.warn(`[CoderAgentExecutor] Task ${taskId} execution aborted.`);
+        currentTask.cancelPendingTools('Execution aborted');
+        if (
+          currentTask.taskState !== 'canceled' &&
+          currentTask.taskState !== 'failed'
+        ) {
+          currentTask.setTaskStateAndPublishUpdate(
+            'input-required',
+            { kind: CoderAgentEvent.StateChangeEvent },
+            'Execution aborted by client.',
+            undefined,
+            true,
+          );
+        }
+      } else {
+        const errorMessage =
+          error instanceof Error ? error.message : 'Agent execution error';
+        logger.error(
+          `[CoderAgentExecutor] Error executing agent for task ${taskId}:`,
+          error,
+        );
+        currentTask.cancelPendingTools(errorMessage);
+        if (currentTask.taskState !== 'failed') {
+          const stateChange: StateChange = {
+            kind: CoderAgentEvent.StateChangeEvent,
+          };
+          currentTask.setTaskStateAndPublishUpdate(
+            'failed',
+            stateChange,
+            errorMessage,
+            undefined,
+            true,
+          );
+        }
+      }
+    } finally {
+      if (isPrimaryExecution) {
+        this.executingTasks.delete(taskId);
+        logger.info(
+          `[CoderAgentExecutor] Saving final state for task ${taskId}.`,
+        );
+        try {
+          await this.taskStore?.save(wrapper.toSDKTask());
+          logger.info(`[CoderAgentExecutor] Task ${taskId} state saved.`);
+        } catch (saveError) {
+          logger.error(
+            `[CoderAgentExecutor] Failed to save task ${taskId} state in finally block:`,
+            saveError,
+          );
+        }
+
+        if (
+          ['canceled', 'failed', 'completed'].includes(currentTask.taskState)
+        ) {
+          logger.info(
+            `[CoderAgentExecutor] Task ${taskId} reached terminal state ${currentTask.taskState}. Evicting and disposing.`,
+          );
+          wrapper.task.dispose();
+          this.tasks.delete(taskId);
+        }
+      }
+    }
+  }
+}

packages/a2a-server/src/agent/race-condition.test.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { Task } from './task.js';
+import {
+  MessageBusType,
+  CoreToolCallStatus,
+  type Config,
+  type MessageBus,
+} from '@google/gemini-cli-core';
+import { createMockConfig } from '../utils/testing_utils.js';
+import type { RequestContext } from '@a2a-js/sdk/server';
+
+describe('Task Race Condition', () => {
+  let mockConfig: Config;
+  let messageBus: MessageBus;
+
+  beforeEach(() => {
+    messageBus = {
+      subscribe: vi.fn(),
+      unsubscribe: vi.fn(),
+      publish: vi.fn(),
+    } as unknown as MessageBus;
+    mockConfig = createMockConfig({
+      messageBus,
+    }) as Config;
+  });
+
+  it('should not hang when multiple tool confirmations are processed while waiting', async () => {
+    // @ts-expect-error - private constructor
+    const task = new Task('task-id', 'context-id', mockConfig);
+
+    // 1. Register two tools as scheduled
+    task['_registerToolCall']('tool-1', 'scheduled');
+    task['_registerToolCall']('tool-2', 'scheduled');
+
+    // 2. Both transition to awaiting_approval
+    const updateHandler = (messageBus.subscribe as Mock).mock.calls.find(
+      (c: unknown[]) => c[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    updateHandler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      schedulerId: 'task-id',
+      toolCalls: [
+        {
+          request: { callId: 'tool-1', name: 't1' },
+          status: CoreToolCallStatus.AwaitingApproval,
+          correlationId: 'corr-1',
+          confirmationDetails: { type: 'info' },
+        },
+        {
+          request: { callId: 'tool-2', name: 't2' },
+          status: CoreToolCallStatus.AwaitingApproval,
+          correlationId: 'corr-2',
+          confirmationDetails: { type: 'info' },
+        },
+      ],
+    });
+
+    // 3. Confirm Tool 1. This makes isAwaitingApprovalOnly() return false.
+    for await (const _ of task.acceptUserMessage(
+      {
+        userMessage: {
+          parts: [
+            {
+              kind: 'data',
+              data: { callId: 'tool-1', outcome: 'proceed_once' },
+            },
+          ],
+        },
+      } as unknown as RequestContext,
+      new AbortController().signal,
+    )) {
+      // consume generator
+    }
+
+    // 4. Start waiting. This should now block because Tool 1 is confirmed (so we are waiting for its execution).
+    const waitPromise = task.waitForPendingTools();
+
+    // 5. Confirm Tool 2 while waiting.
+    for await (const _ of task.acceptUserMessage(
+      {
+        userMessage: {
+          parts: [
+            {
+              kind: 'data',
+              data: { callId: 'tool-2', outcome: 'proceed_once' },
+            },
+          ],
+        },
+      } as unknown as RequestContext,
+      new AbortController().signal,
+    )) {
+      // consume generator
+    }
+
+    // 6. Both tools complete successfully
+    updateHandler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      schedulerId: 'task-id',
+      toolCalls: [
+        {
+          request: { callId: 'tool-1', name: 't1' },
+          status: CoreToolCallStatus.Success,
+          response: { responseParts: [] },
+        },
+        {
+          request: { callId: 'tool-2', name: 't2' },
+          status: CoreToolCallStatus.Success,
+          response: { responseParts: [] },
+        },
+      ],
+    });
+
+    // 7. Verify that the original waitPromise resolves.
+    await expect(waitPromise).resolves.toBeUndefined();
+  });
+
+  it('should reject waitForPendingTools when tools are cancelled', async () => {
+    // @ts-expect-error - private constructor
+    const task = new Task('task-id', 'context-id', mockConfig);
+
+    // 1. Register a tool
+    task['_registerToolCall']('tool-1', 'scheduled');
+
+    // 2. Start waiting
+    const waitPromise = task.waitForPendingTools();
+
+    // 3. Cancel pending tools
+    task.cancelPendingTools('User requested cancellation');
+
+    // 4. Verify waitPromise rejects with the reason
+    await expect(waitPromise).rejects.toThrow('User requested cancellation');
+  });
+
+  it('should handle concurrent tool scheduling correctly', async () => {
+    // @ts-expect-error - private constructor
+    const task = new Task('task-id', 'context-id', mockConfig);
+
+    // 1. Register a tool and start waiting
+    task['_registerToolCall']('tool-1', 'scheduled');
+    const waitPromise = task.waitForPendingTools();
+
+    // 2. Schedule another tool concurrently (e.g. from a secondary user message)
+    // This should NOT resolve the current waitPromise until both are done
+    await task.scheduleToolCalls(
+      [{ callId: 'tool-2', name: 't2', args: {} }],
+      new AbortController().signal,
+    );
+
+    expect(task['pendingToolCalls'].size).toBe(2);
+
+    // 3. Resolve tool 1
+    task['_resolveToolCall']('tool-1');
+
+    // 4. Verify waitPromise is still pending
+    let resolved = false;
+    waitPromise.then(() => (resolved = true));
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(resolved).toBe(false);
+
+    // 5. Resolve tool 2
+    task['_resolveToolCall']('tool-2');
+
+    // 6. Now it should resolve
+    await expect(waitPromise).resolves.toBeUndefined();
+  });
+});

packages/a2a-server/src/agent/task-event-driven.test.ts

@@ -0,0 +1,762 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { Task } from './task.js';
+import {
+  type Config,
+  MessageBusType,
+  ToolConfirmationOutcome,
+  ApprovalMode,
+  Scheduler,
+  type MessageBus,
+  type ToolLiveOutput,
+} from '@google/gemini-cli-core';
+import { createMockConfig } from '../utils/testing_utils.js';
+import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+
+describe('Task Event-Driven Scheduler', () => {
+  let mockConfig: Config;
+  let mockEventBus: ExecutionEventBus;
+  let messageBus: MessageBus;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConfig = createMockConfig({
+      isEventDrivenSchedulerEnabled: () => true,
+    }) as Config;
+    messageBus = mockConfig.messageBus;
+    mockEventBus = {
+      publish: vi.fn(),
+      on: vi.fn(),
+      off: vi.fn(),
+      once: vi.fn(),
+      removeAllListeners: vi.fn(),
+      finished: vi.fn(),
+    };
+  });
+
+  it('should instantiate Scheduler when enabled', () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+    expect(task.scheduler).toBeInstanceOf(Scheduler);
+  });
+
+  it('should subscribe to TOOL_CALLS_UPDATE and map status changes', async () => {
+    // @ts-expect-error - Calling private constructor
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'executing',
+    };
+
+    // Simulate MessageBus event
+    // Simulate MessageBus event
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    if (!handler) {
+      throw new Error('TOOL_CALLS_UPDATE handler not found');
+    }
+
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    expect(mockEventBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: expect.objectContaining({
+          state: 'submitted', // initial task state
+        }),
+        metadata: expect.objectContaining({
+          coderAgent: expect.objectContaining({
+            kind: 'tool-call-update',
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('should handle tool confirmations by publishing to MessageBus', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-1',
+      confirmationDetails: { type: 'info', title: 'test', prompt: 'test' },
+    };
+
+    // Simulate MessageBus event to stash the correlationId
+    // Simulate MessageBus event
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    if (!handler) {
+      throw new Error('TOOL_CALLS_UPDATE handler not found');
+    }
+
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    // Simulate A2A client confirmation
+    const part = {
+      kind: 'data',
+      data: {
+        callId: '1',
+        outcome: 'proceed_once',
+      },
+    };
+
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart(part);
+    expect(handled).toBe(true);
+
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-1',
+        confirmed: true,
+        outcome: ToolConfirmationOutcome.ProceedOnce,
+      }),
+    );
+  });
+
+  it('should handle Rejection (Cancel) and Modification (ModifyWithEditor)', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-1',
+      confirmationDetails: { type: 'info', title: 'test', prompt: 'test' },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    // Simulate Rejection (Cancel)
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '1', outcome: 'cancel' },
+    });
+    expect(handled).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-1',
+        confirmed: false,
+      }),
+    );
+
+    const toolCall2 = {
+      request: { callId: '2', name: 'ls', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-2',
+      confirmationDetails: { type: 'info', title: 'test', prompt: 'test' },
+    };
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall2],
+      schedulerId: 'task-id',
+    });
+
+    // Simulate ModifyWithEditor
+    const handled2 = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '2', outcome: 'modify_with_editor' },
+    });
+    expect(handled2).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-2',
+        confirmed: false,
+        outcome: ToolConfirmationOutcome.ModifyWithEditor,
+        payload: undefined,
+      }),
+    );
+  });
+
+  it('should handle MCP Server tool operations correctly', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'call_mcp_tool', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-mcp-1',
+      confirmationDetails: {
+        type: 'mcp',
+        title: 'MCP Server Operation',
+        prompt: 'test_mcp',
+      },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    // Simulate ProceedOnce for MCP
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '1', outcome: 'proceed_once' },
+    });
+    expect(handled).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-mcp-1',
+        confirmed: true,
+        outcome: ToolConfirmationOutcome.ProceedOnce,
+      }),
+    );
+  });
+
+  it('should handle MCP Server tool ProceedAlwaysServer outcome', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'call_mcp_tool', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-mcp-2',
+      confirmationDetails: {
+        type: 'mcp',
+        title: 'MCP Server Operation',
+        prompt: 'test_mcp',
+      },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '1', outcome: 'proceed_always_server' },
+    });
+    expect(handled).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-mcp-2',
+        confirmed: true,
+        outcome: ToolConfirmationOutcome.ProceedAlwaysServer,
+      }),
+    );
+  });
+
+  it('should handle MCP Server tool ProceedAlwaysTool outcome', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'call_mcp_tool', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-mcp-3',
+      confirmationDetails: {
+        type: 'mcp',
+        title: 'MCP Server Operation',
+        prompt: 'test_mcp',
+      },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '1', outcome: 'proceed_always_tool' },
+    });
+    expect(handled).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-mcp-3',
+        confirmed: true,
+        outcome: ToolConfirmationOutcome.ProceedAlwaysTool,
+      }),
+    );
+  });
+
+  it('should handle MCP Server tool ProceedAlwaysAndSave outcome', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'call_mcp_tool', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-mcp-4',
+      confirmationDetails: {
+        type: 'mcp',
+        title: 'MCP Server Operation',
+        prompt: 'test_mcp',
+      },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '1', outcome: 'proceed_always_and_save' },
+    });
+    expect(handled).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-mcp-4',
+        confirmed: true,
+        outcome: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+      }),
+    );
+  });
+
+  it('should execute without confirmation in YOLO mode and not transition to input-required', async () => {
+    // Enable YOLO mode
+    const yoloConfig = createMockConfig({
+      isEventDrivenSchedulerEnabled: () => true,
+      getApprovalMode: () => ApprovalMode.YOLO,
+    }) as Config;
+    const yoloMessageBus = yoloConfig.messageBus;
+
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', yoloConfig, mockEventBus);
+    task.setTaskStateAndPublishUpdate = vi.fn();
+
+    const toolCall = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-1',
+      confirmationDetails: { type: 'info', title: 'test', prompt: 'test' },
+    };
+
+    const handler = (yoloMessageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    // Should NOT auto-publish ProceedOnce anymore, because PolicyEngine handles it directly
+    expect(yoloMessageBus.publish).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+      }),
+    );
+
+    // Should NOT transition to input-required since it was auto-approved
+    expect(task.setTaskStateAndPublishUpdate).not.toHaveBeenCalledWith(
+      'input-required',
+      expect.anything(),
+      undefined,
+      undefined,
+      true,
+    );
+  });
+
+  it('should handle output updates via the message bus', async () => {
+    // @ts-expect-error - Calling private constructor
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'executing',
+      liveOutput: 'chunk1',
+    };
+
+    // Simulate MessageBus event
+    // Simulate MessageBus event
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    if (!handler) {
+      throw new Error('TOOL_CALLS_UPDATE handler not found');
+    }
+
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    // Should publish artifact update for output
+    expect(mockEventBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'artifact-update',
+        artifact: expect.objectContaining({
+          artifactId: 'tool-1-output',
+          parts: [{ kind: 'text', text: 'chunk1' }],
+        }),
+      }),
+    );
+  });
+
+  it('should complete artifact creation without hanging', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCallId = 'create-file-123';
+    task['_registerToolCall'](toolCallId, 'executing');
+
+    const toolCall = {
+      request: {
+        callId: toolCallId,
+        name: 'writeFile',
+        args: { path: 'test.sh' },
+      },
+      status: 'success',
+      result: { ok: true },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall],
+      schedulerId: 'task-id',
+    });
+
+    // The tool should be complete and registered appropriately, eventually
+    // triggering the toolCompletionPromise resolution when all clear.
+    const internalTask = task as unknown as {
+      completedToolCalls: unknown[];
+      pendingToolCalls: Map<string, string>;
+    };
+    expect(internalTask.completedToolCalls.length).toBe(1);
+    expect(internalTask.pendingToolCalls.size).toBe(0);
+  });
+
+  it('should preserve messageId across multiple text chunks to prevent UI duplication', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    // Initialize the ID for the first turn (happens internally upon LLM stream)
+    task.currentAgentMessageId = 'test-id-123';
+
+    // Simulate sending multiple text chunks
+    task._sendTextContent('chunk 1');
+    task._sendTextContent('chunk 2');
+
+    // Both text contents should have been published with the same messageId
+    const textCalls = (mockEventBus.publish as Mock).mock.calls.filter(
+      (call) => call[0].status?.message?.kind === 'message',
+    );
+    expect(textCalls.length).toBe(2);
+    expect(textCalls[0][0].status.message.messageId).toBe('test-id-123');
+    expect(textCalls[1][0].status.message.messageId).toBe('test-id-123');
+
+    // Simulate starting a new turn by calling getAndClearCompletedTools
+    // (which precedes sendCompletedToolsToLlm where a new ID is minted)
+    task.getAndClearCompletedTools();
+
+    // sendCompletedToolsToLlm internally rolls the ID forward.
+    // Simulate what sendCompletedToolsToLlm does:
+    const internalTask = task as unknown as {
+      setTaskStateAndPublishUpdate: (state: string, change: unknown) => void;
+    };
+    internalTask.setTaskStateAndPublishUpdate('working', {});
+
+    // Simulate what sendCompletedToolsToLlm does: generate a new UUID for the next turn
+    task.currentAgentMessageId = 'test-id-456';
+
+    task._sendTextContent('chunk 3');
+
+    const secondTurnCalls = (mockEventBus.publish as Mock).mock.calls.filter(
+      (call) => call[0].status?.message?.messageId === 'test-id-456',
+    );
+    expect(secondTurnCalls.length).toBe(1);
+    expect(secondTurnCalls[0][0].status.message.parts[0].text).toBe('chunk 3');
+  });
+
+  it('should handle parallel tool calls correctly', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const toolCall1 = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-1',
+      confirmationDetails: { type: 'info', title: 'test 1', prompt: 'test 1' },
+    };
+
+    const toolCall2 = {
+      request: { callId: '2', name: 'pwd', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-2',
+      confirmationDetails: { type: 'info', title: 'test 2', prompt: 'test 2' },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    // Publish update for both tool calls simultaneously
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall1, toolCall2],
+      schedulerId: 'task-id',
+    });
+
+    // Confirm first tool call
+    const handled1 = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '1', outcome: 'proceed_once' },
+    });
+    expect(handled1).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-1',
+        confirmed: true,
+      }),
+    );
+
+    // Confirm second tool call
+    const handled2 = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: '2', outcome: 'cancel' },
+    });
+    expect(handled2).toBe(true);
+    expect(messageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: 'corr-2',
+        confirmed: false,
+      }),
+    );
+  });
+
+  it('should handle multi-turn tool resolution correctly', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig);
+
+    task['_registerToolCall']('1', 'scheduled');
+    task['_registerToolCall']('2', 'scheduled');
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    // Turn 1: Resolve tool 1
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [
+        {
+          request: { callId: '1', name: 't1' },
+          status: 'success',
+          response: { responseParts: [] },
+        },
+      ],
+      schedulerId: 'task-id',
+    });
+
+    expect(task['pendingToolCalls'].size).toBe(1);
+    expect(task['pendingToolCalls'].has('2')).toBe(true);
+
+    // Turn 2: Resolve tool 2
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [
+        {
+          request: { callId: '2', name: 't2' },
+          status: 'success',
+          response: { responseParts: [] },
+        },
+      ],
+      schedulerId: 'task-id',
+    });
+
+    expect(task['pendingToolCalls'].size).toBe(0);
+  });
+
+  it('should handle subagent progress events from the scheduler', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    // Trigger _schedulerOutputUpdate with subagent progress
+    task['_schedulerOutputUpdate']('tool-1', {
+      isSubagentProgress: true,
+      agentName: 'researcher',
+      recentActivity: [],
+    } as ToolLiveOutput);
+
+    expect(mockEventBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'artifact-update',
+        artifact: expect.objectContaining({
+          parts: [
+            expect.objectContaining({
+              text: expect.stringContaining('researcher'),
+            }),
+          ],
+        }),
+      }),
+    );
+  });
+
+  it('should wait for executing tools before transitioning to input-required state', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    task.setTaskStateAndPublishUpdate = vi.fn();
+
+    // Register tool 1 as executing
+    task['_registerToolCall']('1', 'executing');
+
+    const toolCall1 = {
+      request: { callId: '1', name: 'ls', args: {} },
+      status: 'executing',
+    };
+
+    const toolCall2 = {
+      request: { callId: '2', name: 'pwd', args: {} },
+      status: 'awaiting_approval',
+      correlationId: 'corr-2',
+      confirmationDetails: { type: 'info', title: 'test 2', prompt: 'test 2' },
+    };
+
+    const handler = (messageBus.subscribe as Mock).mock.calls.find(
+      (call: unknown[]) => call[0] === MessageBusType.TOOL_CALLS_UPDATE,
+    )?.[1];
+
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall1, toolCall2],
+      schedulerId: 'task-id',
+    });
+
+    // Should NOT transition to input-required yet
+    expect(task.setTaskStateAndPublishUpdate).not.toHaveBeenCalledWith(
+      'input-required',
+      expect.anything(),
+      undefined,
+      undefined,
+      true,
+    );
+
+    // Complete tool 1
+    const toolCall1Complete = {
+      ...toolCall1,
+      status: 'success',
+      result: { ok: true },
+    };
+
+    handler({
+      type: MessageBusType.TOOL_CALLS_UPDATE,
+      toolCalls: [toolCall1Complete, toolCall2],
+      schedulerId: 'task-id',
+    });
+
+    // Now it should transition
+    expect(task.setTaskStateAndPublishUpdate).toHaveBeenCalledWith(
+      'input-required',
+      expect.anything(),
+      undefined,
+      undefined,
+      true,
+    );
+  });
+
+  it('should ignore confirmations for unknown tool calls', async () => {
+    // @ts-expect-error - Calling private constructor
+    const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);
+
+    const handled = await (
+      task as unknown as {
+        _handleToolConfirmationPart: (part: unknown) => Promise<boolean>;
+      }
+    )._handleToolConfirmationPart({
+      kind: 'data',
+      data: { callId: 'unknown-id', outcome: 'proceed_once' },
+    });
+
+    // Should return false for unhandled tool call
+    expect(handled).toBe(false);
+
+    // Should not publish anything to the message bus
+    expect(messageBus.publish).not.toHaveBeenCalled();
+  });
+});

packages/a2a-server/src/agent/task.test.ts

@@ -0,0 +1,755 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { Task } from './task.js';
+import {
+  GeminiEventType,
+  type Config,
+  type ToolCallRequestInfo,
+  type GitService,
+  type CompletedToolCall,
+  type ToolCall,
+  type ToolCallsUpdateMessage,
+  MessageBusType,
+} from '@google/gemini-cli-core';
+import { createMockConfig } from '../utils/testing_utils.js';
+import type { ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
+import { CoderAgentEvent } from '../types.js';
+
+const mockProcessRestorableToolCalls = vi.hoisted(() => vi.fn());
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...original,
+    processRestorableToolCalls: mockProcessRestorableToolCalls,
+  };
+});
+
+describe('Task', () => {
+  it('scheduleToolCalls should not modify the input requests array', async () => {
+    const mockConfig = createMockConfig();
+
+    const mockEventBus: ExecutionEventBus = {
+      publish: vi.fn(),
+      on: vi.fn(),
+      off: vi.fn(),
+      once: vi.fn(),
+      removeAllListeners: vi.fn(),
+      finished: vi.fn(),
+    };
+
+    // The Task constructor is private. We'll bypass it for this unit test.
+    // @ts-expect-error - Calling private constructor for test purposes.
+    const task = new Task(
+      'task-id',
+      'context-id',
+      mockConfig as Config,
+      mockEventBus,
+    );
+
+    task['setTaskStateAndPublishUpdate'] = vi.fn();
+    task['getProposedContent'] = vi.fn().mockResolvedValue('new content');
+
+    const requests: ToolCallRequestInfo[] = [
+      {
+        callId: '1',
+        name: 'replace',
+        args: {
+          file_path: 'test.txt',
+          old_string: 'old',
+          new_string: 'new',
+        },
+        isClientInitiated: false,
+        prompt_id: 'prompt-id-1',
+      },
+    ];
+
+    const originalRequests = JSON.parse(JSON.stringify(requests));
+    const abortController = new AbortController();
+
+    await task.scheduleToolCalls(requests, abortController.signal);
+
+    expect(requests).toEqual(originalRequests);
+  });
+
+  describe('scheduleToolCalls', () => {
+    const mockConfig = createMockConfig();
+    const mockEventBus: ExecutionEventBus = {
+      publish: vi.fn(),
+      on: vi.fn(),
+      off: vi.fn(),
+      once: vi.fn(),
+      removeAllListeners: vi.fn(),
+      finished: vi.fn(),
+    };
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('should not create a checkpoint if no restorable tools are called', async () => {
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+      const requests: ToolCallRequestInfo[] = [
+        {
+          callId: '1',
+          name: 'run_shell_command',
+          args: { command: 'ls' },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-1',
+        },
+      ];
+      const abortController = new AbortController();
+      await task.scheduleToolCalls(requests, abortController.signal);
+      expect(mockProcessRestorableToolCalls).not.toHaveBeenCalled();
+    });
+
+    it('should create a checkpoint if a restorable tool is called', async () => {
+      const mockConfig = createMockConfig({
+        getCheckpointingEnabled: () => true,
+        getGitService: () => Promise.resolve({} as GitService),
+      });
+      mockProcessRestorableToolCalls.mockResolvedValue({
+        checkpointsToWrite: new Map([['test.json', 'test content']]),
+        toolCallToCheckpointMap: new Map(),
+        errors: [],
+      });
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+      const requests: ToolCallRequestInfo[] = [
+        {
+          callId: '1',
+          name: 'replace',
+          args: {
+            file_path: 'test.txt',
+            old_string: 'old',
+            new_string: 'new',
+          },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-1',
+        },
+      ];
+      const abortController = new AbortController();
+      await task.scheduleToolCalls(requests, abortController.signal);
+      expect(mockProcessRestorableToolCalls).toHaveBeenCalledOnce();
+    });
+
+    it('should process all restorable tools for checkpointing in a single batch', async () => {
+      const mockConfig = createMockConfig({
+        getCheckpointingEnabled: () => true,
+        getGitService: () => Promise.resolve({} as GitService),
+      });
+      mockProcessRestorableToolCalls.mockResolvedValue({
+        checkpointsToWrite: new Map([
+          ['test1.json', 'test content 1'],
+          ['test2.json', 'test content 2'],
+        ]),
+        toolCallToCheckpointMap: new Map([
+          ['1', 'test1'],
+          ['2', 'test2'],
+        ]),
+        errors: [],
+      });
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+      const requests: ToolCallRequestInfo[] = [
+        {
+          callId: '1',
+          name: 'replace',
+          args: {
+            file_path: 'test.txt',
+            old_string: 'old',
+            new_string: 'new',
+          },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-1',
+        },
+        {
+          callId: '2',
+          name: 'write_file',
+          args: { file_path: 'test2.txt', content: 'new content' },
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-2',
+        },
+        {
+          callId: '3',
+          name: 'not_restorable',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-id-3',
+        },
+      ];
+      const abortController = new AbortController();
+      await task.scheduleToolCalls(requests, abortController.signal);
+      expect(mockProcessRestorableToolCalls).toHaveBeenCalledExactlyOnceWith(
+        [
+          expect.objectContaining({ callId: '1' }),
+          expect.objectContaining({ callId: '2' }),
+        ],
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+  });
+
+  describe('acceptAgentMessage', () => {
+    it('should set currentTraceId when event has traceId', async () => {
+      const mockConfig = createMockConfig();
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const event = {
+        type: 'content',
+        value: 'test',
+        traceId: 'test-trace-id',
+      };
+
+      await task.acceptAgentMessage(event);
+
+      expect(mockEventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            traceId: 'test-trace-id',
+          }),
+        }),
+      );
+    });
+
+    it('should handle Citation event and publish to event bus', async () => {
+      const mockConfig = createMockConfig();
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const citationText = 'Source: example.com';
+      const citationEvent = {
+        type: GeminiEventType.Citation,
+        value: citationText,
+      };
+
+      await task.acceptAgentMessage(citationEvent);
+
+      expect(mockEventBus.publish).toHaveBeenCalledOnce();
+      const publishedEvent = (mockEventBus.publish as Mock).mock.calls[0][0];
+
+      expect(publishedEvent.kind).toBe('status-update');
+      expect(publishedEvent.taskId).toBe('task-id');
+      expect(publishedEvent.metadata.coderAgent.kind).toBe(
+        CoderAgentEvent.CitationEvent,
+      );
+      expect(publishedEvent.status.message).toBeDefined();
+      expect(publishedEvent.status.message.parts).toEqual([
+        {
+          kind: 'text',
+          text: citationText,
+        },
+      ]);
+    });
+
+    it('should capture usageMetadata on Finished event and include it in final status update', async () => {
+      const mockConfig = createMockConfig();
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const finishedEvent = {
+        type: GeminiEventType.Finished,
+        value: {
+          reason: 'STOP',
+          usageMetadata: {
+            promptTokenCount: 100,
+            candidatesTokenCount: 50,
+            totalTokenCount: 150,
+          },
+        },
+      };
+
+      await task.acceptAgentMessage(finishedEvent);
+      expect(task.usageMetadata).toEqual({
+        promptTokenCount: 100,
+        candidatesTokenCount: 50,
+        totalTokenCount: 150,
+      });
+
+      task.setTaskStateAndPublishUpdate(
+        'input-required',
+        { kind: CoderAgentEvent.StateChangeEvent },
+        undefined,
+        undefined,
+        true, // final
+      );
+
+      expect(mockEventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          final: true,
+          metadata: expect.objectContaining({
+            usageMetadata: {
+              promptTokenCount: 100,
+              candidatesTokenCount: 50,
+              totalTokenCount: 150,
+            },
+          }),
+        }),
+      );
+    });
+
+    it('should update modelInfo and reflect it in metadata and status updates', async () => {
+      const mockConfig = createMockConfig();
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor for test purposes.
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const modelInfoEvent = {
+        type: GeminiEventType.ModelInfo,
+        value: 'new-model-name',
+      };
+
+      await task.acceptAgentMessage(modelInfoEvent);
+
+      expect(task.modelInfo).toBe('new-model-name');
+
+      // Check getMetadata
+      const metadata = await task.getMetadata();
+      expect(metadata.model).toBe('new-model-name');
+
+      // Check status update
+      task.setTaskStateAndPublishUpdate(
+        'working',
+        { kind: CoderAgentEvent.StateChangeEvent },
+        'Working...',
+      );
+
+      expect(mockEventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            model: 'new-model-name',
+          }),
+        }),
+      );
+    });
+
+    it.each([
+      { eventType: GeminiEventType.Retry, eventName: 'Retry' },
+      { eventType: GeminiEventType.InvalidStream, eventName: 'InvalidStream' },
+    ])(
+      'should handle $eventName event without triggering error handling',
+      async ({ eventType }) => {
+        const mockConfig = createMockConfig();
+        const mockEventBus: ExecutionEventBus = {
+          publish: vi.fn(),
+          on: vi.fn(),
+          off: vi.fn(),
+          once: vi.fn(),
+          removeAllListeners: vi.fn(),
+          finished: vi.fn(),
+        };
+
+        // @ts-expect-error - Calling private constructor
+        const task = new Task(
+          'task-id',
+          'context-id',
+          mockConfig as Config,
+          mockEventBus,
+        );
+
+        const cancelPendingToolsSpy = vi.spyOn(task, 'cancelPendingTools');
+        const setTaskStateSpy = vi.spyOn(task, 'setTaskStateAndPublishUpdate');
+
+        const event = {
+          type: eventType,
+        };
+
+        await task.acceptAgentMessage(event);
+
+        expect(cancelPendingToolsSpy).not.toHaveBeenCalled();
+        expect(setTaskStateSpy).not.toHaveBeenCalled();
+      },
+    );
+  });
+
+  describe('currentPromptId and promptCount', () => {
+    it('should correctly initialize and update promptId and promptCount', async () => {
+      const mockConfig = createMockConfig();
+      mockConfig.getGeminiClient = vi.fn().mockReturnValue({
+        sendMessageStream: vi.fn().mockReturnValue((async function* () {})()),
+      });
+      mockConfig.getSessionId = () => 'test-session-id';
+
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      // Initial state
+      expect(task.currentPromptId).toBeUndefined();
+      expect(task.promptCount).toBe(0);
+
+      // First user message should set prompt_id
+      const userMessage1 = {
+        userMessage: {
+          parts: [{ kind: 'text', text: 'hello' }],
+        },
+      } as RequestContext;
+      const abortController1 = new AbortController();
+      for await (const _ of task.acceptUserMessage(
+        userMessage1,
+        abortController1.signal,
+      )) {
+        // no-op
+      }
+
+      const expectedPromptId1 = 'test-session-id########0';
+      expect(task.promptCount).toBe(1);
+      expect(task.currentPromptId).toBe(expectedPromptId1);
+
+      // A new user message should generate a new prompt_id
+      const userMessage2 = {
+        userMessage: {
+          parts: [{ kind: 'text', text: 'world' }],
+        },
+      } as RequestContext;
+      const abortController2 = new AbortController();
+      for await (const _ of task.acceptUserMessage(
+        userMessage2,
+        abortController2.signal,
+      )) {
+        // no-op
+      }
+
+      const expectedPromptId2 = 'test-session-id########1';
+      expect(task.promptCount).toBe(2);
+      expect(task.currentPromptId).toBe(expectedPromptId2);
+
+      // Subsequent tool call processing should use the same prompt_id
+      const completedTool = {
+        request: { callId: 'tool-1' },
+        response: { responseParts: [{ text: 'tool output' }] },
+      } as CompletedToolCall;
+      const abortController3 = new AbortController();
+      for await (const _ of task.sendCompletedToolsToLlm(
+        [completedTool],
+        abortController3.signal,
+      )) {
+        // no-op
+      }
+
+      expect(task.promptCount).toBe(2);
+      expect(task.currentPromptId).toBe(expectedPromptId2);
+    });
+  });
+
+  describe('Race Condition Fix', () => {
+    const mockConfig = createMockConfig();
+    const mockEventBus: ExecutionEventBus = {
+      publish: vi.fn(),
+      on: vi.fn(),
+      off: vi.fn(),
+      once: vi.fn(),
+      removeAllListeners: vi.fn(),
+      finished: vi.fn(),
+    };
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('should NOT transition to input-required if a tool is still validating', async () => {
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      // Manually register two tool calls
+      task['_registerToolCall']('tool-1', 'awaiting_approval');
+      task['_registerToolCall']('tool-2', 'validating');
+
+      // Call checkInputRequiredState (private)
+      task['checkInputRequiredState']();
+
+      // Verify task state did NOT change to input-required
+      expect(task.taskState).not.toBe('input-required');
+      expect(mockEventBus.publish).not.toHaveBeenCalledWith(
+        expect.objectContaining({
+          status: expect.objectContaining({ state: 'input-required' }),
+        }),
+      );
+    });
+
+    it('should transition to input-required if all active tools are awaiting approval', async () => {
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      // Transition from submitted to working first to simulate normal flow
+      task.taskState = 'working';
+
+      // Manually register tool calls
+      task['_registerToolCall']('tool-1', 'awaiting_approval');
+
+      // Call checkInputRequiredState
+      task['checkInputRequiredState']();
+
+      // Verify task state changed to input-required
+      expect(task.taskState).toBe('input-required');
+      expect(mockEventBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          status: expect.objectContaining({ state: 'input-required' }),
+        }),
+      );
+    });
+
+    it('handleEventDrivenToolCallsUpdate should ignore events for other schedulers', async () => {
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const handleEventDrivenToolCallSpy = vi.spyOn(
+        task as unknown as {
+          handleEventDrivenToolCall: Task['handleEventDrivenToolCall'];
+        },
+        'handleEventDrivenToolCall',
+      );
+
+      const otherEvent: ToolCallsUpdateMessage = {
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [
+          { request: { callId: '1' }, status: 'executing' } as ToolCall,
+        ],
+        schedulerId: 'other-task-id',
+      };
+
+      task['handleEventDrivenToolCallsUpdate'](otherEvent);
+
+      expect(handleEventDrivenToolCallSpy).not.toHaveBeenCalled();
+
+      const ownEvent: ToolCallsUpdateMessage = {
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [
+          { request: { callId: '1' }, status: 'executing' } as ToolCall,
+        ],
+        schedulerId: 'task-id',
+      };
+
+      task['handleEventDrivenToolCallsUpdate'](ownEvent);
+
+      expect(handleEventDrivenToolCallSpy).toHaveBeenCalled();
+    });
+
+    describe('Pending Tools state', () => {
+      it('should correctly report pending tools presence and count', () => {
+        const mockConfig = createMockConfig();
+        const mockEventBus: ExecutionEventBus = {
+          publish: vi.fn(),
+          on: vi.fn(),
+          off: vi.fn(),
+          once: vi.fn(),
+          removeAllListeners: vi.fn(),
+          finished: vi.fn(),
+        };
+
+        // @ts-expect-error - Calling private constructor
+        const task = new Task(
+          'task-id',
+          'context-id',
+          mockConfig as Config,
+          mockEventBus,
+        );
+
+        expect(task.hasPendingTools).toBe(false);
+        expect(task.pendingToolsCount).toBe(0);
+
+        task['_registerToolCall']('tool-1', 'scheduled');
+        expect(task.hasPendingTools).toBe(true);
+        expect(task.pendingToolsCount).toBe(1);
+      });
+    });
+  });
+
+  describe('Serialization and Mapping', () => {
+    it('should map internal "validating" status to "scheduled" for the client and include outcome', async () => {
+      const mockConfig = createMockConfig();
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const mockToolCall = {
+        request: { callId: 'tool-1' },
+        status: 'validating',
+        outcome: 'accepted',
+        tool: { name: 'test-tool' },
+      };
+
+      const message = task['toolStatusMessage'](
+        mockToolCall as unknown as ToolCall,
+        'task-id',
+        'context-id',
+      );
+      const serialized = (
+        message.parts![0] as {
+          data: { status: string; outcome: string };
+        }
+      ).data;
+
+      expect(serialized.status).toBe('scheduled');
+      expect(serialized.outcome).toBe('accepted');
+    });
+
+    it('should correctly detect changes when status or outcome changes', async () => {
+      const mockConfig = createMockConfig();
+      const mockEventBus: ExecutionEventBus = {
+        publish: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+        once: vi.fn(),
+        removeAllListeners: vi.fn(),
+        finished: vi.fn(),
+      };
+
+      // @ts-expect-error - Calling private constructor
+      const task = new Task(
+        'task-id',
+        'context-id',
+        mockConfig as Config,
+        mockEventBus,
+      );
+
+      const toolCall1 = {
+        request: { callId: 'tool-1' },
+        status: 'awaiting_approval',
+      };
+
+      // First update - should trigger change
+      const changed1 = task['handleEventDrivenToolCall'](
+        toolCall1 as unknown as ToolCall,
+      );
+      expect(changed1).toBe(true);
+
+      // Second update with same status - should NOT trigger change
+      const changed2 = task['handleEventDrivenToolCall'](
+        toolCall1 as unknown as ToolCall,
+      );
+      expect(changed2).toBe(false);
+
+      // Update with new outcome - SHOULD trigger change
+      const toolCall2 = {
+        request: { callId: 'tool-1' },
+        status: 'awaiting_approval',
+        outcome: 'accepted',
+      };
+      const changed3 = task['handleEventDrivenToolCall'](
+        toolCall2 as unknown as ToolCall,
+      );
+      expect(changed3).toBe(true);
+    });
+  });
+});

packages/a2a-server/src/commands/command-registry.test.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Command } from './types.js';
+
+const {
+  mockExtensionsCommand,
+  mockListExtensionsCommand,
+  mockExtensionsCommandInstance,
+  mockListExtensionsCommandInstance,
+} = vi.hoisted(() => {
+  const listInstance: Command = {
+    name: 'extensions list',
+    description: 'Lists all installed extensions.',
+    execute: vi.fn(),
+  };
+
+  const extInstance: Command = {
+    name: 'extensions',
+    description: 'Manage extensions.',
+    execute: vi.fn(),
+    subCommands: [listInstance],
+  };
+
+  return {
+    mockListExtensionsCommandInstance: listInstance,
+    mockExtensionsCommandInstance: extInstance,
+    mockExtensionsCommand: vi.fn(() => extInstance),
+    mockListExtensionsCommand: vi.fn(() => listInstance),
+  };
+});
+
+vi.mock('./extensions.js', () => ({
+  ExtensionsCommand: mockExtensionsCommand,
+  ListExtensionsCommand: mockListExtensionsCommand,
+}));
+
+vi.mock('./init.js', () => ({
+  InitCommand: vi.fn(() => ({
+    name: 'init',
+    description: 'Initializes the server.',
+    execute: vi.fn(),
+  })),
+}));
+
+vi.mock('./restore.js', () => ({
+  RestoreCommand: vi.fn(() => ({
+    name: 'restore',
+    description: 'Restores the server.',
+    execute: vi.fn(),
+  })),
+}));
+
+import { commandRegistry } from './command-registry.js';
+
+describe('CommandRegistry', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    commandRegistry.initialize();
+  });
+
+  it('should register ExtensionsCommand on initialization', async () => {
+    expect(mockExtensionsCommand).toHaveBeenCalled();
+    const command = commandRegistry.get('extensions');
+    expect(command).toBe(mockExtensionsCommandInstance);
+  }, 20000);
+
+  it('should register sub commands on initialization', async () => {
+    const command = commandRegistry.get('extensions list');
+    expect(command).toBe(mockListExtensionsCommandInstance);
+  });
+
+  it('get() should return undefined for a non-existent command', async () => {
+    const command = commandRegistry.get('non-existent');
+    expect(command).toBeUndefined();
+  });
+
+  it('register() should register a new command', async () => {
+    const mockCommand: Command = {
+      name: 'test-command',
+      description: '',
+      execute: vi.fn(),
+    };
+    commandRegistry.register(mockCommand);
+    const command = commandRegistry.get('test-command');
+    expect(command).toBe(mockCommand);
+  });
+
+  it('register() should register a nested command', async () => {
+    const mockSubSubCommand: Command = {
+      name: 'test-command-sub-sub',
+      description: '',
+      execute: vi.fn(),
+    };
+    const mockSubCommand: Command = {
+      name: 'test-command-sub',
+      description: '',
+      execute: vi.fn(),
+      subCommands: [mockSubSubCommand],
+    };
+    const mockCommand: Command = {
+      name: 'test-command',
+      description: '',
+      execute: vi.fn(),
+      subCommands: [mockSubCommand],
+    };
+    commandRegistry.register(mockCommand);
+
+    const command = commandRegistry.get('test-command');
+    const subCommand = commandRegistry.get('test-command-sub');
+    const subSubCommand = commandRegistry.get('test-command-sub-sub');
+
+    expect(command).toBe(mockCommand);
+    expect(subCommand).toBe(mockSubCommand);
+    expect(subSubCommand).toBe(mockSubSubCommand);
+  });
+
+  it('register() should not enter an infinite loop with a cyclic command', async () => {
+    const { debugLogger } = await import('@google/gemini-cli-core');
+    const warnSpy = vi.spyOn(debugLogger, 'warn').mockImplementation(() => {});
+    const mockCommand: Command = {
+      name: 'cyclic-command',
+      description: '',
+      subCommands: [],
+      execute: vi.fn(),
+    };
+
+    mockCommand.subCommands?.push(mockCommand); // Create cycle
+
+    commandRegistry.register(mockCommand);
+
+    expect(commandRegistry.get('cyclic-command')).toBe(mockCommand);
+    expect(warnSpy).toHaveBeenCalledWith(
+      'Command cyclic-command already registered. Skipping.',
+    );
+    warnSpy.mockRestore();
+  });
+});

packages/a2a-server/src/commands/command-registry.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MemoryCommand } from './memory.js';
+import { debugLogger } from '@google/gemini-cli-core';
+import { ExtensionsCommand } from './extensions.js';
+import { InitCommand } from './init.js';
+import { RestoreCommand } from './restore.js';
+import type { Command } from './types.js';
+
+export class CommandRegistry {
+  private readonly commands = new Map<string, Command>();
+
+  constructor() {
+    this.initialize();
+  }
+
+  initialize() {
+    this.commands.clear();
+    this.register(new ExtensionsCommand());
+    this.register(new RestoreCommand());
+    this.register(new InitCommand());
+    this.register(new MemoryCommand());
+  }
+
+  register(command: Command) {
+    if (this.commands.has(command.name)) {
+      debugLogger.warn(`Command ${command.name} already registered. Skipping.`);
+      return;
+    }
+
+    this.commands.set(command.name, command);
+
+    for (const subCommand of command.subCommands ?? []) {
+      this.register(subCommand);
+    }
+  }
+
+  get(commandName: string): Command | undefined {
+    return this.commands.get(commandName);
+  }
+
+  getAllCommands(): Command[] {
+    return [...this.commands.values()];
+  }
+}
+
+export const commandRegistry = new CommandRegistry();

packages/a2a-server/src/commands/extensions.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ExtensionsCommand, ListExtensionsCommand } from './extensions.js';
+import type { CommandContext } from './types.js';
+
+const mockListExtensions = vi.hoisted(() => vi.fn());
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+
+  return {
+    ...original,
+    listExtensions: mockListExtensions,
+  };
+});
+
+describe('ExtensionsCommand', () => {
+  it('should have the correct name', () => {
+    const command = new ExtensionsCommand();
+    expect(command.name).toEqual('extensions');
+  });
+
+  it('should have the correct description', () => {
+    const command = new ExtensionsCommand();
+    expect(command.description).toEqual('Manage extensions.');
+  });
+
+  it('should have "extensions list" as a subcommand', () => {
+    const command = new ExtensionsCommand();
+    expect(command.subCommands.map((c) => c.name)).toContain('extensions list');
+  });
+
+  it('should be a top-level command', () => {
+    const command = new ExtensionsCommand();
+    expect(command.topLevel).toBe(true);
+  });
+
+  it('should default to listing extensions', async () => {
+    const command = new ExtensionsCommand();
+    const mockConfig = { config: {} } as CommandContext;
+    const mockExtensions = [{ name: 'ext1' }];
+    mockListExtensions.mockReturnValue(mockExtensions);
+
+    const result = await command.execute(mockConfig, []);
+
+    expect(result).toEqual({ name: 'extensions list', data: mockExtensions });
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig.config);
+  });
+});
+
+describe('ListExtensionsCommand', () => {
+  it('should have the correct name', () => {
+    const command = new ListExtensionsCommand();
+    expect(command.name).toEqual('extensions list');
+  });
+
+  it('should call listExtensions with the provided config', async () => {
+    const command = new ListExtensionsCommand();
+    const mockConfig = { config: {} } as CommandContext;
+    const mockExtensions = [{ name: 'ext1' }];
+    mockListExtensions.mockReturnValue(mockExtensions);
+
+    const result = await command.execute(mockConfig, []);
+
+    expect(result).toEqual({ name: 'extensions list', data: mockExtensions });
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig.config);
+  });
+
+  it('should return a message when no extensions are installed', async () => {
+    const command = new ListExtensionsCommand();
+    const mockConfig = { config: {} } as CommandContext;
+    mockListExtensions.mockReturnValue([]);
+
+    const result = await command.execute(mockConfig, []);
+
+    expect(result).toEqual({
+      name: 'extensions list',
+      data: 'No extensions installed.',
+    });
+    expect(mockListExtensions).toHaveBeenCalledWith(mockConfig.config);
+  });
+});

packages/a2a-server/src/commands/extensions.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { listExtensions } from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class ExtensionsCommand implements Command {
+  readonly name = 'extensions';
+  readonly description = 'Manage extensions.';
+  readonly subCommands = [new ListExtensionsCommand()];
+  readonly topLevel = true;
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    return new ListExtensionsCommand().execute(context, _);
+  }
+}
+
+export class ListExtensionsCommand implements Command {
+  readonly name = 'extensions list';
+  readonly description = 'Lists all installed extensions.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensions = listExtensions(context.config);
+    const data = extensions.length ? extensions : 'No extensions installed.';
+
+    return { name: this.name, data };
+  }
+}

packages/a2a-server/src/commands/init.test.ts

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { InitCommand } from './init.js';
+import {
+  performInit,
+  type CommandActionReturn,
+  type Config,
+} from '@google/gemini-cli-core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CoderAgentExecutor } from '../agent/executor.js';
+import { CoderAgentEvent } from '../types.js';
+import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import { createMockConfig } from '../utils/testing_utils.js';
+import type { CommandContext } from './types.js';
+import { logger } from '../utils/logger.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    performInit: vi.fn(),
+  };
+});
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    existsSync: vi.fn(),
+    writeFileSync: vi.fn(),
+  };
+});
+
+vi.mock('../agent/executor.js', () => ({
+  CoderAgentExecutor: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(),
+  })),
+}));
+
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+describe('InitCommand', () => {
+  let eventBus: ExecutionEventBus;
+  let command: InitCommand;
+  let context: CommandContext;
+  let publishSpy: ReturnType<typeof vi.spyOn>;
+  let mockExecute: ReturnType<typeof vi.fn>;
+  const mockWorkspacePath = path.resolve('/tmp');
+
+  beforeEach(() => {
+    process.env['CODER_AGENT_WORKSPACE_PATH'] = mockWorkspacePath;
+    eventBus = {
+      publish: vi.fn(),
+    } as unknown as ExecutionEventBus;
+    command = new InitCommand();
+    const mockConfig = createMockConfig({
+      getModel: () => 'gemini-pro',
+    });
+    const mockExecutorInstance = new CoderAgentExecutor();
+    context = {
+      config: mockConfig as unknown as Config,
+      agentExecutor: mockExecutorInstance,
+      eventBus,
+    } as CommandContext;
+    publishSpy = vi.spyOn(eventBus, 'publish');
+    mockExecute = vi.fn();
+    vi.spyOn(mockExecutorInstance, 'execute').mockImplementation(mockExecute);
+    vi.clearAllMocks();
+  });
+
+  it('has requiresWorkspace set to true', () => {
+    expect(command.requiresWorkspace).toBe(true);
+  });
+
+  describe('execute', () => {
+    it('handles info from performInit', async () => {
+      vi.mocked(performInit).mockReturnValue({
+        type: 'message',
+        messageType: 'info',
+        content: 'GEMINI.md already exists.',
+      } as CommandActionReturn);
+
+      await command.execute(context, []);
+
+      expect(logger.info).toHaveBeenCalledWith(
+        '[EventBus event]: ',
+        expect.objectContaining({
+          kind: 'status-update',
+          status: expect.objectContaining({
+            state: 'completed',
+            message: expect.objectContaining({
+              parts: [{ kind: 'text', text: 'GEMINI.md already exists.' }],
+            }),
+          }),
+        }),
+      );
+
+      expect(publishSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'status-update',
+          status: expect.objectContaining({
+            state: 'completed',
+            message: expect.objectContaining({
+              parts: [{ kind: 'text', text: 'GEMINI.md already exists.' }],
+            }),
+          }),
+        }),
+      );
+    });
+
+    it('handles error from performInit', async () => {
+      vi.mocked(performInit).mockReturnValue({
+        type: 'message',
+        messageType: 'error',
+        content: 'An error occurred.',
+      } as CommandActionReturn);
+
+      await command.execute(context, []);
+
+      expect(publishSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'status-update',
+          status: expect.objectContaining({
+            state: 'failed',
+            message: expect.objectContaining({
+              parts: [{ kind: 'text', text: 'An error occurred.' }],
+            }),
+          }),
+        }),
+      );
+    });
+
+    describe('when handling submit_prompt', () => {
+      beforeEach(() => {
+        vi.mocked(performInit).mockReturnValue({
+          type: 'submit_prompt',
+          content: 'Create a new GEMINI.md file.',
+        } as CommandActionReturn);
+      });
+
+      it('writes the file and executes the agent', async () => {
+        await command.execute(context, []);
+
+        expect(fs.writeFileSync).toHaveBeenCalledWith(
+          path.join(mockWorkspacePath, 'GEMINI.md'),
+          '',
+          'utf8',
+        );
+        expect(mockExecute).toHaveBeenCalled();
+      });
+
+      it('passes autoExecute to the agent executor', async () => {
+        await command.execute(context, []);
+
+        expect(mockExecute).toHaveBeenCalledWith(
+          expect.objectContaining({
+            userMessage: expect.objectContaining({
+              parts: expect.arrayContaining([
+                expect.objectContaining({
+                  text: 'Create a new GEMINI.md file.',
+                }),
+              ]),
+              metadata: {
+                coderAgent: {
+                  kind: CoderAgentEvent.StateAgentSettingsEvent,
+                  workspacePath: mockWorkspacePath,
+                  autoExecute: true,
+                },
+              },
+            }),
+          }),
+          eventBus,
+        );
+      });
+    });
+  });
+});

packages/a2a-server/src/commands/init.ts

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CoderAgentEvent, type AgentSettings } from '../types.js';
+import { performInit } from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+import type { CoderAgentExecutor } from '../agent/executor.js';
+import type {
+  ExecutionEventBus,
+  RequestContext,
+  AgentExecutionEvent,
+} from '@a2a-js/sdk/server';
+import { v4 as uuidv4 } from 'uuid';
+import { logger } from '../utils/logger.js';
+
+export class InitCommand implements Command {
+  name = 'init';
+  description = 'Analyzes the project and creates a tailored GEMINI.md file';
+  requiresWorkspace = true;
+  streaming = true;
+
+  private handleMessageResult(
+    result: { content: string; messageType: 'info' | 'error' },
+    context: CommandContext,
+    eventBus: ExecutionEventBus,
+    taskId: string,
+    contextId: string,
+  ): CommandExecutionResponse {
+    const statusState = result.messageType === 'error' ? 'failed' : 'completed';
+    const eventType =
+      result.messageType === 'error'
+        ? CoderAgentEvent.StateChangeEvent
+        : CoderAgentEvent.TextContentEvent;
+
+    const event: AgentExecutionEvent = {
+      kind: 'status-update',
+      taskId,
+      contextId,
+      status: {
+        state: statusState,
+        message: {
+          kind: 'message',
+          role: 'agent',
+          parts: [{ kind: 'text', text: result.content }],
+          messageId: uuidv4(),
+          taskId,
+          contextId,
+        },
+        timestamp: new Date().toISOString(),
+      },
+      final: true,
+      metadata: {
+        coderAgent: { kind: eventType },
+        model: context.config.getModel(),
+      },
+    };
+
+    logger.info('[EventBus event]: ', event);
+    eventBus.publish(event);
+    return {
+      name: this.name,
+      data: result,
+    };
+  }
+
+  private async handleSubmitPromptResult(
+    result: { content: unknown },
+    context: CommandContext,
+    geminiMdPath: string,
+    eventBus: ExecutionEventBus,
+    taskId: string,
+    contextId: string,
+  ): Promise<CommandExecutionResponse> {
+    fs.writeFileSync(geminiMdPath, '', 'utf8');
+
+    if (!context.agentExecutor) {
+      throw new Error('Agent executor not found in context.');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const agentExecutor = context.agentExecutor as CoderAgentExecutor;
+
+    const agentSettings: AgentSettings = {
+      kind: CoderAgentEvent.StateAgentSettingsEvent,
+      workspacePath: process.env['CODER_AGENT_WORKSPACE_PATH']!,
+      autoExecute: true,
+    };
+
+    if (typeof result.content !== 'string') {
+      throw new Error('Init command content must be a string.');
+    }
+    const promptText = result.content;
+
+    const requestContext: RequestContext = {
+      userMessage: {
+        kind: 'message',
+        role: 'user',
+        parts: [{ kind: 'text', text: promptText }],
+        messageId: uuidv4(),
+        taskId,
+        contextId,
+        metadata: {
+          coderAgent: agentSettings,
+        },
+      },
+      taskId,
+      contextId,
+    };
+
+    // The executor will handle the entire agentic loop, including
+    // creating the task, streaming responses, and handling tools.
+    await agentExecutor.execute(requestContext, eventBus);
+    return {
+      name: this.name,
+      data: geminiMdPath,
+    };
+  }
+
+  async execute(
+    context: CommandContext,
+    _args: string[] = [],
+  ): Promise<CommandExecutionResponse> {
+    if (!context.eventBus) {
+      return {
+        name: this.name,
+        data: 'Use executeStream to get streaming results.',
+      };
+    }
+
+    const geminiMdPath = path.join(
+      process.env['CODER_AGENT_WORKSPACE_PATH']!,
+      'GEMINI.md',
+    );
+    const result = performInit(fs.existsSync(geminiMdPath));
+
+    const taskId = uuidv4();
+    const contextId = uuidv4();
+
+    switch (result.type) {
+      case 'message':
+        return this.handleMessageResult(
+          result,
+          context,
+          context.eventBus,
+          taskId,
+          contextId,
+        );
+      case 'submit_prompt':
+        return this.handleSubmitPromptResult(
+          result,
+          context,
+          geminiMdPath,
+          context.eventBus,
+          taskId,
+          contextId,
+        );
+      default:
+        throw new Error('Unknown result type from performInit');
+    }
+  }
+}

packages/a2a-server/src/commands/memory.test.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  listMemoryFiles,
+  refreshMemory,
+  showMemory,
+  type Config,
+} from '@google/gemini-cli-core';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  ListMemoryCommand,
+  MemoryCommand,
+  RefreshMemoryCommand,
+  ShowMemoryCommand,
+} from './memory.js';
+import type { CommandContext } from './types.js';
+
+// Mock the core functions
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    showMemory: vi.fn(),
+    refreshMemory: vi.fn(),
+    listMemoryFiles: vi.fn(),
+  };
+});
+
+const mockShowMemory = vi.mocked(showMemory);
+const mockRefreshMemory = vi.mocked(refreshMemory);
+const mockListMemoryFiles = vi.mocked(listMemoryFiles);
+
+describe('a2a-server memory commands', () => {
+  let mockContext: CommandContext;
+  let mockConfig: Config;
+
+  beforeEach(() => {
+    mockConfig = {} as unknown as Config;
+
+    mockContext = {
+      config: mockConfig,
+    };
+  });
+
+  describe('MemoryCommand', () => {
+    it('delegates to ShowMemoryCommand', async () => {
+      const command = new MemoryCommand();
+      mockShowMemory.mockReturnValue({
+        type: 'message',
+        messageType: 'info',
+        content: 'showing memory',
+      });
+      const response = await command.execute(mockContext, []);
+      expect(response.data).toBe('showing memory');
+      expect(mockShowMemory).toHaveBeenCalledWith(mockContext.config);
+    });
+  });
+
+  describe('ShowMemoryCommand', () => {
+    it('executes showMemory and returns the content', async () => {
+      const command = new ShowMemoryCommand();
+      mockShowMemory.mockReturnValue({
+        type: 'message',
+        messageType: 'info',
+        content: 'test memory content',
+      });
+
+      const response = await command.execute(mockContext, []);
+
+      expect(mockShowMemory).toHaveBeenCalledWith(mockContext.config);
+      expect(response.name).toBe('memory show');
+      expect(response.data).toBe('test memory content');
+    });
+  });
+
+  describe('RefreshMemoryCommand', () => {
+    it('executes refreshMemory and returns the content', async () => {
+      const command = new RefreshMemoryCommand();
+      mockRefreshMemory.mockResolvedValue({
+        type: 'message',
+        messageType: 'info',
+        content: 'memory refreshed',
+      });
+
+      const response = await command.execute(mockContext, []);
+
+      expect(mockRefreshMemory).toHaveBeenCalledWith(mockContext.config);
+      expect(response.name).toBe('memory refresh');
+      expect(response.data).toBe('memory refreshed');
+    });
+  });
+
+  describe('ListMemoryCommand', () => {
+    it('executes listMemoryFiles and returns the content', async () => {
+      const command = new ListMemoryCommand();
+      mockListMemoryFiles.mockReturnValue({
+        type: 'message',
+        messageType: 'info',
+        content: 'file1.md\nfile2.md',
+      });
+
+      const response = await command.execute(mockContext, []);
+
+      expect(mockListMemoryFiles).toHaveBeenCalledWith(mockContext.config);
+      expect(response.name).toBe('memory list');
+      expect(response.data).toBe('file1.md\nfile2.md');
+    });
+  });
+});

packages/a2a-server/src/commands/memory.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  listMemoryFiles,
+  refreshMemory,
+  showMemory,
+} from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class MemoryCommand implements Command {
+  readonly name = 'memory';
+  readonly description = 'Manage memory.';
+  readonly subCommands = [
+    new ShowMemoryCommand(),
+    new RefreshMemoryCommand(),
+    new ListMemoryCommand(),
+  ];
+  readonly topLevel = true;
+  readonly requiresWorkspace = true;
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    return new ShowMemoryCommand().execute(context, _);
+  }
+}
+
+export class ShowMemoryCommand implements Command {
+  readonly name = 'memory show';
+  readonly description = 'Shows the current memory contents.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const result = showMemory(context.config);
+    return { name: this.name, data: result.content };
+  }
+}
+
+export class RefreshMemoryCommand implements Command {
+  readonly name = 'memory refresh';
+  readonly description = 'Refreshes the memory from the source.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const result = await refreshMemory(context.config);
+    return { name: this.name, data: result.content };
+  }
+}
+
+export class ListMemoryCommand implements Command {
+  readonly name = 'memory list';
+  readonly description = 'Lists the paths of the GEMINI.md files in use.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const result = listMemoryFiles(context.config);
+    return { name: this.name, data: result.content };
+  }
+}

packages/a2a-server/src/commands/restore.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RestoreCommand, ListCheckpointsCommand } from './restore.js';
+import type { CommandContext } from './types.js';
+import type { Config } from '@google/gemini-cli-core';
+import { createMockConfig } from '../utils/testing_utils.js';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+const mockPerformRestore = vi.hoisted(() => vi.fn());
+const mockLoggerInfo = vi.hoisted(() => vi.fn());
+const mockGetCheckpointInfoList = vi.hoisted(() => vi.fn());
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...original,
+    performRestore: mockPerformRestore,
+    getCheckpointInfoList: mockGetCheckpointInfoList,
+  };
+});
+
+const mockFs = vi.hoisted(() => ({
+  readFile: vi.fn(),
+  readdir: vi.fn(),
+  mkdir: vi.fn(),
+}));
+
+vi.mock('node:fs/promises', () => mockFs);
+
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: mockLoggerInfo,
+  },
+}));
+
+describe('RestoreCommand', () => {
+  const mockConfig = {
+    config: createMockConfig() as Config,
+    git: {},
+  } as CommandContext;
+
+  it('should return error if no checkpoint name is provided', async () => {
+    const command = new RestoreCommand();
+    const result = await command.execute(mockConfig, []);
+    expect(result.data).toEqual({
+      type: 'message',
+      messageType: 'error',
+      content: 'Please provide a checkpoint name to restore.',
+    });
+  });
+
+  it('should restore a checkpoint when a valid file is provided', async () => {
+    const command = new RestoreCommand();
+    const toolCallData = {
+      toolCall: {
+        name: 'test-tool',
+        args: {},
+      },
+      history: [],
+      clientHistory: [],
+      commitHash: '123',
+    };
+    mockFs.readFile.mockResolvedValue(JSON.stringify(toolCallData));
+    const restoreContent = {
+      type: 'message',
+      messageType: 'info',
+      content: 'Restored',
+    };
+    mockPerformRestore.mockReturnValue(
+      (async function* () {
+        yield restoreContent;
+      })(),
+    );
+    const result = await command.execute(mockConfig, ['checkpoint1.json']);
+    expect(result.data).toEqual([restoreContent]);
+  });
+
+  it('should show "file not found" error for a non-existent checkpoint', async () => {
+    const command = new RestoreCommand();
+    const error = new Error('File not found');
+    (error as NodeJS.ErrnoException).code = 'ENOENT';
+    mockFs.readFile.mockRejectedValue(error);
+    const result = await command.execute(mockConfig, ['checkpoint2.json']);
+    expect(result.data).toEqual({
+      type: 'message',
+      messageType: 'error',
+      content: 'File not found: checkpoint2.json',
+    });
+  });
+
+  it('should handle invalid JSON in checkpoint file', async () => {
+    const command = new RestoreCommand();
+    mockFs.readFile.mockResolvedValue('invalid json');
+    const result = await command.execute(mockConfig, ['checkpoint1.json']);
+    expect((result.data as { content: string }).content).toContain(
+      'An unexpected error occurred during restore.',
+    );
+  });
+});
+
+describe('ListCheckpointsCommand', () => {
+  const mockConfig = {
+    config: createMockConfig() as Config,
+  } as CommandContext;
+
+  it('should list all available checkpoints', async () => {
+    const command = new ListCheckpointsCommand();
+    const checkpointInfo = [{ file: 'checkpoint1.json', description: 'Test' }];
+    mockFs.readdir.mockResolvedValue(['checkpoint1.json']);
+    mockFs.readFile.mockResolvedValue(
+      JSON.stringify({ toolCall: { name: 'Test', args: {} } }),
+    );
+    mockGetCheckpointInfoList.mockReturnValue(checkpointInfo);
+    const result = await command.execute(mockConfig);
+    expect((result.data as { content: string }).content).toEqual(
+      JSON.stringify(checkpointInfo),
+    );
+  });
+
+  it('should handle errors when listing checkpoints', async () => {
+    const command = new ListCheckpointsCommand();
+    mockFs.readdir.mockRejectedValue(new Error('Read error'));
+    const result = await command.execute(mockConfig);
+    expect((result.data as { content: string }).content).toContain(
+      'An unexpected error occurred while listing checkpoints.',
+    );
+  });
+});

packages/a2a-server/src/commands/restore.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  getCheckpointInfoList,
+  getToolCallDataSchema,
+  isNodeError,
+  performRestore,
+} from '@google/gemini-cli-core';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class RestoreCommand implements Command {
+  readonly name = 'restore';
+  readonly description =
+    'Restore to a previous checkpoint, or list available checkpoints to restore. This will reset the conversation and file history to the state it was in when the checkpoint was created';
+  readonly topLevel = true;
+  readonly requiresWorkspace = true;
+  readonly subCommands = [new ListCheckpointsCommand()];
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const { config, git: gitService } = context;
+    const argsStr = args.join(' ');
+
+    try {
+      if (!argsStr) {
+        return {
+          name: this.name,
+          data: {
+            type: 'message',
+            messageType: 'error',
+            content: 'Please provide a checkpoint name to restore.',
+          },
+        };
+      }
+
+      const selectedFile = argsStr.endsWith('.json')
+        ? argsStr
+        : `${argsStr}.json`;
+
+      const checkpointDir = config.storage.getProjectTempCheckpointsDir();
+      const filePath = path.join(checkpointDir, selectedFile);
+
+      let data: string;
+      try {
+        data = await fs.readFile(filePath, 'utf-8');
+      } catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+          return {
+            name: this.name,
+            data: {
+              type: 'message',
+              messageType: 'error',
+              content: `File not found: ${selectedFile}`,
+            },
+          };
+        }
+        throw error;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const toolCallData = JSON.parse(data);
+      const ToolCallDataSchema = getToolCallDataSchema();
+      const parseResult = ToolCallDataSchema.safeParse(toolCallData);
+
+      if (!parseResult.success) {
+        return {
+          name: this.name,
+          data: {
+            type: 'message',
+            messageType: 'error',
+            content: 'Checkpoint file is invalid or corrupted.',
+          },
+        };
+      }
+
+      const restoreResultGenerator = performRestore(
+        parseResult.data,
+        gitService,
+      );
+      const restoreResult = [];
+      for await (const result of restoreResultGenerator) {
+        restoreResult.push(result);
+      }
+
+      return {
+        name: this.name,
+        data: restoreResult,
+      };
+    } catch {
+      return {
+        name: this.name,
+        data: {
+          type: 'message',
+          messageType: 'error',
+          content: 'An unexpected error occurred during restore.',
+        },
+      };
+    }
+  }
+}
+
+export class ListCheckpointsCommand implements Command {
+  readonly name = 'restore list';
+  readonly description = 'Lists all available checkpoints.';
+  readonly topLevel = false;
+
+  async execute(context: CommandContext): Promise<CommandExecutionResponse> {
+    const { config } = context;
+
+    try {
+      const checkpointDir = config.storage.getProjectTempCheckpointsDir();
+      await fs.mkdir(checkpointDir, { recursive: true });
+      const files = await fs.readdir(checkpointDir);
+      const jsonFiles = files.filter((file) => file.endsWith('.json'));
+
+      const checkpointFiles = new Map<string, string>();
+      for (const file of jsonFiles) {
+        const filePath = path.join(checkpointDir, file);
+        const data = await fs.readFile(filePath, 'utf-8');
+        checkpointFiles.set(file, data);
+      }
+
+      const checkpointInfoList = getCheckpointInfoList(checkpointFiles);
+
+      return {
+        name: this.name,
+        data: {
+          type: 'message',
+          messageType: 'info',
+          content: JSON.stringify(checkpointInfoList),
+        },
+      };
+    } catch {
+      return {
+        name: this.name,
+        data: {
+          type: 'message',
+          messageType: 'error',
+          content: 'An unexpected error occurred while listing checkpoints.',
+        },
+      };
+    }
+  }
+}

packages/a2a-server/src/commands/types.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ExecutionEventBus, AgentExecutor } from '@a2a-js/sdk/server';
+import type { Config, GitService } from '@google/gemini-cli-core';
+
+export interface CommandContext {
+  config: Config;
+  git?: GitService;
+  agentExecutor?: AgentExecutor;
+  eventBus?: ExecutionEventBus;
+}
+
+export interface CommandArgument {
+  readonly name: string;
+  readonly description: string;
+  readonly isRequired?: boolean;
+}
+
+export interface Command {
+  readonly name: string;
+  readonly description: string;
+  readonly arguments?: CommandArgument[];
+  readonly subCommands?: Command[];
+  readonly topLevel?: boolean;
+  readonly requiresWorkspace?: boolean;
+  readonly streaming?: boolean;
+
+  execute(
+    config: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse>;
+}
+
+export interface CommandExecutionResponse {
+  readonly name: string;
+  readonly data: unknown;
+}

packages/a2a-server/src/config/config.test.ts

@@ -0,0 +1,575 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as path from 'node:path';
+import { loadConfig } from './config.js';
+import type { Settings } from './settings.js';
+import {
+  type ExtensionLoader,
+  getCodeAssistServer,
+  Config,
+  ExperimentFlags,
+  fetchAdminControlsOnce,
+  type FetchAdminControlsResponse,
+  AuthType,
+  isHeadlessMode,
+  FatalAuthenticationError,
+  PolicyDecision,
+  ApprovalMode,
+  PRIORITY_YOLO_ALLOW_ALL,
+  createPolicyEngineConfig,
+} from '@google/gemini-cli-core';
+import type { AgentSettings } from '../types.js';
+
+// Mock dependencies
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    PRIORITY_YOLO_ALLOW_ALL: 998,
+    Config: vi.fn().mockImplementation((params) => {
+      const mockConfig = {
+        ...params,
+        initialize: vi.fn(),
+        waitForMcpInit: vi.fn(),
+        refreshAuth: vi.fn(),
+        getExperiments: vi.fn().mockReturnValue({
+          flags: {
+            [actual.ExperimentFlags.ENABLE_ADMIN_CONTROLS]: {
+              boolValue: false,
+            },
+          },
+        }),
+        getRemoteAdminSettings: vi.fn(),
+        setRemoteAdminSettings: vi.fn(),
+      };
+      return mockConfig;
+    }),
+    startupProfiler: {
+      flush: vi.fn(),
+    },
+    isHeadlessMode: vi.fn().mockReturnValue(false),
+    getCodeAssistServer: vi.fn(),
+    fetchAdminControlsOnce: vi.fn(),
+    createPolicyEngineConfig: vi
+      .fn()
+      .mockImplementation(
+        (_settings, mode, _defaultPoliciesDir, _interactive) => ({
+          rules:
+            mode === actual.ApprovalMode.YOLO
+              ? [
+                  {
+                    toolName: '*',
+                    decision: actual.PolicyDecision.ALLOW,
+                    priority: actual.PRIORITY_YOLO_ALLOW_ALL,
+                    modes: [actual.ApprovalMode.YOLO],
+                    allowRedirection: true,
+                  },
+                ]
+              : [
+                  {
+                    toolName: 'read_file',
+                    decision: actual.PolicyDecision.ALLOW,
+                    priority: 1.05,
+                    source: 'Default: read-only.toml',
+                  },
+                ],
+          checkers: [],
+        }),
+      ),
+    coreEvents: {
+      emitAdminSettingsChanged: vi.fn(),
+    },
+  };
+});
+
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+describe('loadConfig', () => {
+  const mockSettings = {} as Settings;
+  const mockExtensionLoader = {} as ExtensionLoader;
+  const taskId = 'test-task-id';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubEnv('GEMINI_API_KEY', 'test-key');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  describe('admin settings overrides', () => {
+    it('should not fetch admin controls if experiment is disabled', async () => {
+      await loadConfig(mockSettings, mockExtensionLoader, taskId);
+      expect(fetchAdminControlsOnce).not.toHaveBeenCalled();
+    });
+
+    it('should pass clientName as a2a-server to Config', async () => {
+      await loadConfig(mockSettings, mockExtensionLoader, taskId);
+      expect(Config).toHaveBeenCalledWith(
+        expect.objectContaining({
+          clientName: 'a2a-server',
+        }),
+      );
+    });
+
+    describe('when admin controls experiment is enabled', () => {
+      beforeEach(() => {
+        // We need to cast to any here to modify the mock implementation
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (Config as any).mockImplementation((params: unknown) => {
+          const mockConfig = {
+            ...(params as object),
+            initialize: vi.fn(),
+            waitForMcpInit: vi.fn(),
+            refreshAuth: vi.fn(),
+            getExperiments: vi.fn().mockReturnValue({
+              flags: {
+                [ExperimentFlags.ENABLE_ADMIN_CONTROLS]: {
+                  boolValue: true,
+                },
+              },
+            }),
+            getRemoteAdminSettings: vi.fn().mockReturnValue({}),
+            setRemoteAdminSettings: vi.fn(),
+          };
+          return mockConfig;
+        });
+      });
+
+      it('should fetch admin controls and apply them', async () => {
+        const mockAdminSettings: FetchAdminControlsResponse = {
+          mcpSetting: {
+            mcpEnabled: false,
+          },
+          cliFeatureSetting: {
+            extensionsSetting: {
+              extensionsEnabled: false,
+            },
+          },
+          strictModeDisabled: false,
+        };
+        vi.mocked(fetchAdminControlsOnce).mockResolvedValue(mockAdminSettings);
+
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+
+        expect(Config).toHaveBeenLastCalledWith(
+          expect.objectContaining({
+            disableYoloMode: !mockAdminSettings.strictModeDisabled,
+            mcpEnabled: mockAdminSettings.mcpSetting?.mcpEnabled,
+            extensionsEnabled:
+              mockAdminSettings.cliFeatureSetting?.extensionsSetting
+                ?.extensionsEnabled,
+          }),
+        );
+      });
+
+      it('should treat unset admin settings as false when admin settings are passed', async () => {
+        const mockAdminSettings: FetchAdminControlsResponse = {
+          mcpSetting: {
+            mcpEnabled: true,
+          },
+        };
+        vi.mocked(fetchAdminControlsOnce).mockResolvedValue(mockAdminSettings);
+
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+
+        expect(Config).toHaveBeenLastCalledWith(
+          expect.objectContaining({
+            disableYoloMode: !false,
+            mcpEnabled: mockAdminSettings.mcpSetting?.mcpEnabled,
+            extensionsEnabled: undefined,
+          }),
+        );
+      });
+
+      it('should not pass default unset admin settings when no admin settings are present', async () => {
+        const mockAdminSettings: FetchAdminControlsResponse = {};
+        vi.mocked(fetchAdminControlsOnce).mockResolvedValue(mockAdminSettings);
+
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+
+        expect(Config).toHaveBeenLastCalledWith(expect.objectContaining({}));
+      });
+
+      it('should fetch admin controls using the code assist server when available', async () => {
+        const mockAdminSettings: FetchAdminControlsResponse = {
+          mcpSetting: {
+            mcpEnabled: true,
+          },
+          strictModeDisabled: true,
+        };
+        const mockCodeAssistServer = { projectId: 'test-project' };
+        vi.mocked(getCodeAssistServer).mockReturnValue(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          mockCodeAssistServer as any,
+        );
+        vi.mocked(fetchAdminControlsOnce).mockResolvedValue(mockAdminSettings);
+
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+
+        expect(fetchAdminControlsOnce).toHaveBeenCalledWith(
+          mockCodeAssistServer,
+          true,
+        );
+        expect(Config).toHaveBeenLastCalledWith(
+          expect.objectContaining({
+            disableYoloMode: !mockAdminSettings.strictModeDisabled,
+            mcpEnabled: mockAdminSettings.mcpSetting?.mcpEnabled,
+            extensionsEnabled: undefined,
+          }),
+        );
+      });
+    });
+  });
+
+  it('should set customIgnoreFilePaths when CUSTOM_IGNORE_FILE_PATHS env var is present', async () => {
+    const testPath = '/tmp/ignore';
+    vi.stubEnv('CUSTOM_IGNORE_FILE_PATHS', testPath);
+    const config = await loadConfig(mockSettings, mockExtensionLoader, taskId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((config as any).fileFiltering.customIgnoreFilePaths).toEqual([
+      testPath,
+    ]);
+  });
+
+  it('should set customIgnoreFilePaths when settings.fileFiltering.customIgnoreFilePaths is present', async () => {
+    const testPath = '/settings/ignore';
+    const settings: Settings = {
+      fileFiltering: {
+        customIgnoreFilePaths: [testPath],
+      },
+    };
+    const config = await loadConfig(settings, mockExtensionLoader, taskId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((config as any).fileFiltering.customIgnoreFilePaths).toEqual([
+      testPath,
+    ]);
+  });
+
+  it('should merge customIgnoreFilePaths from settings and env var', async () => {
+    const envPath = '/env/ignore';
+    const settingsPath = '/settings/ignore';
+    vi.stubEnv('CUSTOM_IGNORE_FILE_PATHS', envPath);
+    const settings: Settings = {
+      fileFiltering: {
+        customIgnoreFilePaths: [settingsPath],
+      },
+    };
+    const config = await loadConfig(settings, mockExtensionLoader, taskId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((config as any).fileFiltering.customIgnoreFilePaths).toEqual([
+      settingsPath,
+      envPath,
+    ]);
+  });
+
+  it('should split CUSTOM_IGNORE_FILE_PATHS using system delimiter', async () => {
+    const paths = ['/path/one', '/path/two'];
+    vi.stubEnv('CUSTOM_IGNORE_FILE_PATHS', paths.join(path.delimiter));
+    const config = await loadConfig(mockSettings, mockExtensionLoader, taskId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((config as any).fileFiltering.customIgnoreFilePaths).toEqual(paths);
+  });
+
+  it('should have empty customIgnoreFilePaths when both are missing', async () => {
+    const config = await loadConfig(mockSettings, mockExtensionLoader, taskId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((config as any).fileFiltering.customIgnoreFilePaths).toEqual([]);
+  });
+
+  describe('policy engine configuration', () => {
+    it('should map tool settings into policySettings', async () => {
+      const settings: Settings = {
+        tools: {
+          allowed: ['v2-allowed'],
+          exclude: ['v2-exclude'],
+          core: ['v2-core'],
+        },
+        mcpServers: {
+          test: { command: 'test', args: [] },
+        },
+        policyPaths: ['/path/to/policy'],
+        adminPolicyPaths: ['/path/to/admin/policy'],
+      };
+
+      await loadConfig(settings, mockExtensionLoader, taskId);
+
+      expect(createPolicyEngineConfig).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tools: {
+            core: ['v2-core'],
+            exclude: ['v2-exclude'],
+            allowed: ['v2-allowed'],
+          },
+          mcpServers: settings.mcpServers,
+          policyPaths: settings.policyPaths,
+          adminPolicyPaths: settings.adminPolicyPaths,
+        }),
+        ApprovalMode.DEFAULT,
+        undefined,
+        true,
+      );
+    });
+  });
+
+  describe('tool configuration', () => {
+    it('should pass V2 tools.allowed to Config properly', async () => {
+      const settings: Settings = {
+        tools: {
+          allowed: ['shell', 'fetch'],
+        },
+      };
+      await loadConfig(settings, mockExtensionLoader, taskId);
+      expect(Config).toHaveBeenCalledWith(
+        expect.objectContaining({
+          allowedTools: ['shell', 'fetch'],
+        }),
+      );
+    });
+
+    it('should pass enableAgents to Config constructor', async () => {
+      const settings: Settings = {
+        experimental: {
+          enableAgents: false,
+        },
+      };
+      await loadConfig(settings, mockExtensionLoader, taskId);
+      expect(Config).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enableAgents: false,
+        }),
+      );
+    });
+
+    it('should default enableAgents to true when not provided', async () => {
+      await loadConfig(mockSettings, mockExtensionLoader, taskId);
+      expect(Config).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enableAgents: true,
+        }),
+      );
+    });
+
+    describe('interactivity', () => {
+      it('should always set interactive true', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(true);
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            interactive: true,
+          }),
+        );
+
+        vi.mocked(isHeadlessMode).mockReturnValue(false);
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            interactive: true,
+          }),
+        );
+      });
+
+      it('should set enableInteractiveShell based on headless mode', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(false);
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            enableInteractiveShell: true,
+          }),
+        );
+
+        vi.mocked(isHeadlessMode).mockReturnValue(true);
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            enableInteractiveShell: false,
+          }),
+        );
+      });
+    });
+
+    describe('YOLO mode', () => {
+      it('should enable YOLO mode and add policy rule when GEMINI_YOLO_MODE is true', async () => {
+        vi.stubEnv('GEMINI_YOLO_MODE', 'true');
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            approvalMode: 'yolo',
+            policyEngineConfig: expect.objectContaining({
+              rules: expect.arrayContaining([
+                expect.objectContaining({
+                  decision: PolicyDecision.ALLOW,
+                  priority: PRIORITY_YOLO_ALLOW_ALL,
+                  modes: ['yolo'],
+                  allowRedirection: true,
+                }),
+              ]),
+            }),
+          }),
+        );
+      });
+
+      it('should use default approval mode and load default rules when GEMINI_YOLO_MODE is not true', async () => {
+        vi.stubEnv('GEMINI_YOLO_MODE', 'false');
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+        expect(Config).toHaveBeenCalledWith(
+          expect.objectContaining({
+            approvalMode: 'default',
+            policyEngineConfig: expect.objectContaining({
+              rules: expect.arrayContaining([
+                expect.objectContaining({
+                  toolName: 'read_file',
+                  decision: PolicyDecision.ALLOW,
+                }),
+              ]),
+            }),
+          }),
+        );
+      });
+    });
+
+    describe('authentication logic', () => {
+      const setupConfigMock = (refreshAuthMock: ReturnType<typeof vi.fn>) => {
+        vi.mocked(Config).mockImplementation(
+          (params: unknown) =>
+            ({
+              ...(params as object),
+              initialize: vi.fn(),
+              waitForMcpInit: vi.fn(),
+              refreshAuth: refreshAuthMock,
+              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
+              getRemoteAdminSettings: vi.fn(),
+              setRemoteAdminSettings: vi.fn(),
+            }) as unknown as Config,
+        );
+      };
+
+      beforeEach(() => {
+        vi.stubEnv('USE_CCPA', 'true');
+        vi.stubEnv('GEMINI_API_KEY', '');
+      });
+
+      afterEach(() => {
+        vi.unstubAllEnvs();
+      });
+
+      it('should attempt COMPUTE_ADC by default and bypass LOGIN_WITH_GOOGLE if successful', async () => {
+        const refreshAuthMock = vi.fn().mockResolvedValue(undefined);
+        setupConfigMock(refreshAuthMock);
+
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+
+        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
+        expect(refreshAuthMock).not.toHaveBeenCalledWith(
+          AuthType.LOGIN_WITH_GOOGLE,
+        );
+      });
+
+      it('should fallback to LOGIN_WITH_GOOGLE if COMPUTE_ADC fails and interactive mode is available', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(false);
+        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
+          if (authType === AuthType.COMPUTE_ADC) {
+            return Promise.reject(new Error('ADC failed'));
+          }
+          return Promise.resolve();
+        });
+        setupConfigMock(refreshAuthMock);
+
+        await loadConfig(mockSettings, mockExtensionLoader, taskId);
+
+        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
+        expect(refreshAuthMock).toHaveBeenCalledWith(
+          AuthType.LOGIN_WITH_GOOGLE,
+        );
+      });
+
+      it('should throw FatalAuthenticationError in headless mode if COMPUTE_ADC fails', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(true);
+
+        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
+          if (authType === AuthType.COMPUTE_ADC) {
+            return Promise.reject(new Error('ADC not found'));
+          }
+          return Promise.resolve();
+        });
+        setupConfigMock(refreshAuthMock);
+
+        await expect(
+          loadConfig(mockSettings, mockExtensionLoader, taskId),
+        ).rejects.toThrow(
+          'COMPUTE_ADC failed: ADC not found. (LOGIN_WITH_GOOGLE fallback skipped due to headless mode. Run in an interactive terminal to use OAuth.)',
+        );
+
+        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
+        expect(refreshAuthMock).not.toHaveBeenCalledWith(
+          AuthType.LOGIN_WITH_GOOGLE,
+        );
+      });
+
+      it('should include both original and fallback error when LOGIN_WITH_GOOGLE fallback fails', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(false);
+
+        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
+          if (authType === AuthType.COMPUTE_ADC) {
+            throw new Error('ADC failed');
+          }
+          if (authType === AuthType.LOGIN_WITH_GOOGLE) {
+            throw new FatalAuthenticationError('OAuth failed');
+          }
+          return Promise.resolve();
+        });
+        setupConfigMock(refreshAuthMock);
+
+        await expect(
+          loadConfig(mockSettings, mockExtensionLoader, taskId),
+        ).rejects.toThrow(
+          'OAuth failed. The initial COMPUTE_ADC attempt also failed: ADC failed',
+        );
+      });
+    });
+  });
+});
+
+describe('setIsTrusted', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('should return true when GEMINI_FOLDER_TRUST env var is true', async () => {
+    vi.stubEnv('GEMINI_FOLDER_TRUST', 'true');
+    const { setIsTrusted } = await import('./config.js');
+    expect(setIsTrusted(undefined)).toBe(true);
+    expect(setIsTrusted({ isTrusted: false } as AgentSettings)).toBe(true);
+  });
+
+  it('should return false when GEMINI_FOLDER_TRUST env var is false', async () => {
+    vi.stubEnv('GEMINI_FOLDER_TRUST', 'false');
+    const { setIsTrusted } = await import('./config.js');
+    expect(setIsTrusted(undefined)).toBe(false);
+    expect(setIsTrusted({ isTrusted: true } as AgentSettings)).toBe(false);
+  });
+
+  it('should fallback to agentSettings.isTrusted if env var is undefined', async () => {
+    const { setIsTrusted } = await import('./config.js');
+    expect(setIsTrusted({ isTrusted: true } as AgentSettings)).toBe(true);
+    expect(setIsTrusted({ isTrusted: false } as AgentSettings)).toBe(false);
+    expect(setIsTrusted(undefined)).toBe(false);
+  });
+});

packages/a2a-server/src/config/config.ts

@@ -0,0 +1,318 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as dotenv from 'dotenv';
+
+import {
+  AuthType,
+  Config,
+  ApprovalMode,
+  GEMINI_DIR,
+  DEFAULT_GEMINI_EMBEDDING_MODEL,
+  startupProfiler,
+  PREVIEW_GEMINI_MODEL,
+  homedir,
+  GitService,
+  fetchAdminControlsOnce,
+  getCodeAssistServer,
+  ExperimentFlags,
+  isHeadlessMode,
+  FatalAuthenticationError,
+  createPolicyEngineConfig,
+  type PolicySettings,
+  type TelemetryTarget,
+  type ConfigParameters,
+  type ExtensionLoader,
+} from '@google/gemini-cli-core';
+
+import { logger } from '../utils/logger.js';
+import type { Settings } from './settings.js';
+import { type AgentSettings, CoderAgentEvent } from '../types.js';
+
+const INITIAL_FOLDER_TRUST = process.env['GEMINI_FOLDER_TRUST'];
+
+export async function loadConfig(
+  settings: Settings,
+  extensionLoader: ExtensionLoader,
+  taskId: string,
+  trusted: boolean = false,
+): Promise<Config> {
+  const workspaceDir = process.cwd();
+
+  const folderTrust =
+    settings.folderTrust === true ||
+    process.env['GEMINI_FOLDER_TRUST'] === 'true';
+
+  let checkpointing = process.env['CHECKPOINTING']
+    ? process.env['CHECKPOINTING'] === 'true'
+    : settings.checkpointing?.enabled;
+
+  if (checkpointing) {
+    if (!(await GitService.verifyGitAvailability())) {
+      logger.warn(
+        '[Config] Checkpointing is enabled but git is not installed. Disabling checkpointing.',
+      );
+      checkpointing = false;
+    }
+  }
+
+  const approvalMode =
+    process.env['GEMINI_YOLO_MODE'] === 'true'
+      ? ApprovalMode.YOLO
+      : ApprovalMode.DEFAULT;
+
+  const policySettings: PolicySettings = {
+    mcpServers: settings.mcpServers,
+    tools: {
+      core: settings.tools?.core,
+      exclude: settings.tools?.exclude,
+      allowed: settings.tools?.allowed,
+    },
+    policyPaths: settings.policyPaths,
+    adminPolicyPaths: settings.adminPolicyPaths,
+  };
+
+  const policyEngineConfig = await createPolicyEngineConfig(
+    policySettings,
+    approvalMode,
+    undefined,
+    true,
+  );
+
+  const configParams: ConfigParameters = {
+    sessionId: taskId,
+    clientName: 'a2a-server',
+    model: PREVIEW_GEMINI_MODEL,
+    embeddingModel: DEFAULT_GEMINI_EMBEDDING_MODEL,
+    sandbox: undefined, // Sandbox might not be relevant for a server-side agent
+    targetDir: workspaceDir, // Or a specific directory the agent operates on
+    debugMode: process.env['DEBUG'] === 'true' || false,
+    question: '', // Not used in server mode directly like CLI
+
+    coreTools: settings.tools?.core || undefined,
+    excludeTools: settings.tools?.exclude || undefined,
+    allowedTools: settings.tools?.allowed || undefined,
+    showMemoryUsage: settings.showMemoryUsage || false,
+    approvalMode,
+    policyEngineConfig,
+    mcpServers: settings.mcpServers,
+    cwd: workspaceDir,
+    telemetry: {
+      enabled: settings.telemetry?.enabled,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      target: settings.telemetry?.target as TelemetryTarget,
+      otlpEndpoint:
+        process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] ??
+        settings.telemetry?.otlpEndpoint,
+      logPrompts: settings.telemetry?.logPrompts,
+    },
+    // Git-aware file filtering settings
+    fileFiltering: {
+      respectGitIgnore: settings.fileFiltering?.respectGitIgnore,
+      respectGeminiIgnore: settings.fileFiltering?.respectGeminiIgnore,
+      enableRecursiveFileSearch:
+        settings.fileFiltering?.enableRecursiveFileSearch,
+      customIgnoreFilePaths: [
+        ...(settings.fileFiltering?.customIgnoreFilePaths || []),
+        ...(process.env['CUSTOM_IGNORE_FILE_PATHS']
+          ? process.env['CUSTOM_IGNORE_FILE_PATHS'].split(path.delimiter)
+          : []),
+      ],
+    },
+    ideMode: false,
+    folderTrust,
+    trustedFolder: trusted,
+    extensionLoader,
+    checkpointing,
+    interactive: true,
+    enableInteractiveShell: !isHeadlessMode(),
+    ptyInfo: 'auto',
+    enableAgents: settings.experimental?.enableAgents ?? true,
+  };
+
+  // Set an initial config to use to get a code assist server.
+  // This is needed to fetch admin controls.
+  const initialConfig = new Config({
+    ...configParams,
+  });
+
+  const codeAssistServer = getCodeAssistServer(initialConfig);
+
+  const adminControlsEnabled =
+    initialConfig.getExperiments()?.flags[ExperimentFlags.ENABLE_ADMIN_CONTROLS]
+      ?.boolValue ?? false;
+
+  // Initialize final config parameters to the previous parameters.
+  // If no admin controls are needed, these will be used as-is for the final
+  // config.
+  const finalConfigParams = { ...configParams };
+  if (adminControlsEnabled) {
+    const adminSettings = await fetchAdminControlsOnce(
+      codeAssistServer,
+      adminControlsEnabled,
+    );
+
+    // Admin settings are able to be undefined if unset, but if any are present,
+    // we should initialize them all.
+    // If any are present, undefined settings should be treated as if they were
+    // set to false.
+    // If NONE are present, disregard admin settings entirely, and pass the
+    // final config as is.
+    if (Object.keys(adminSettings).length !== 0) {
+      finalConfigParams.disableYoloMode = !adminSettings.strictModeDisabled;
+      finalConfigParams.mcpEnabled = adminSettings.mcpSetting?.mcpEnabled;
+      finalConfigParams.extensionsEnabled =
+        adminSettings.cliFeatureSetting?.extensionsSetting?.extensionsEnabled;
+    }
+  }
+
+  const config = new Config(finalConfigParams);
+
+  // Needed to initialize ToolRegistry, and git checkpointing if enabled
+  await config.initialize();
+
+  await config.waitForMcpInit();
+  startupProfiler.flush(config);
+
+  await refreshAuthentication(config, 'Config');
+
+  return config;
+}
+
+export function setIsTrusted(
+  agentSettings: AgentSettings | undefined,
+): boolean {
+  if (INITIAL_FOLDER_TRUST !== undefined) {
+    return INITIAL_FOLDER_TRUST === 'true';
+  }
+  return !!agentSettings?.isTrusted;
+}
+
+export function setTargetDir(agentSettings: AgentSettings | undefined): string {
+  const originalCWD = process.cwd();
+  const targetDir =
+    process.env['CODER_AGENT_WORKSPACE_PATH'] ??
+    (agentSettings?.kind === CoderAgentEvent.StateAgentSettingsEvent
+      ? agentSettings.workspacePath
+      : undefined);
+
+  if (!targetDir) {
+    return originalCWD;
+  }
+
+  logger.info(
+    `[CoderAgentExecutor] Overriding workspace path to: ${targetDir}`,
+  );
+
+  try {
+    const resolvedPath = path.resolve(targetDir);
+    process.chdir(resolvedPath);
+    return resolvedPath;
+  } catch (e) {
+    logger.error(
+      `[CoderAgentExecutor] Error resolving workspace path: ${e}, returning original os.cwd()`,
+    );
+    return originalCWD;
+  }
+}
+
+export function loadEnvironment(): void {
+  const envFilePath = findEnvFile(process.cwd());
+  if (envFilePath) {
+    dotenv.config({ path: envFilePath, override: true });
+  }
+}
+
+function findEnvFile(startDir: string): string | null {
+  let currentDir = path.resolve(startDir);
+  while (true) {
+    // prefer gemini-specific .env under GEMINI_DIR
+    const geminiEnvPath = path.join(currentDir, GEMINI_DIR, '.env');
+    if (fs.existsSync(geminiEnvPath)) {
+      return geminiEnvPath;
+    }
+    const envPath = path.join(currentDir, '.env');
+    if (fs.existsSync(envPath)) {
+      return envPath;
+    }
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir || !parentDir) {
+      // check .env under home as fallback, again preferring gemini-specific .env
+      const homeGeminiEnvPath = path.join(process.cwd(), GEMINI_DIR, '.env');
+      if (fs.existsSync(homeGeminiEnvPath)) {
+        return homeGeminiEnvPath;
+      }
+      const homeEnvPath = path.join(homedir(), '.env');
+      if (fs.existsSync(homeEnvPath)) {
+        return homeEnvPath;
+      }
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+async function refreshAuthentication(
+  config: Config,
+  logPrefix: string,
+): Promise<void> {
+  if (process.env['USE_CCPA']) {
+    logger.info(`[${logPrefix}] Using CCPA Auth:`);
+
+    logger.info(`[${logPrefix}] Attempting COMPUTE_ADC first.`);
+    try {
+      await config.refreshAuth(AuthType.COMPUTE_ADC);
+      logger.info(`[${logPrefix}] COMPUTE_ADC successful.`);
+    } catch (adcError) {
+      const adcMessage =
+        adcError instanceof Error ? adcError.message : String(adcError);
+      logger.info(
+        `[${logPrefix}] COMPUTE_ADC failed or not available: ${adcMessage}`,
+      );
+
+      const useComputeAdc =
+        process.env['GEMINI_CLI_USE_COMPUTE_ADC'] === 'true';
+      const isHeadless = isHeadlessMode();
+
+      if (isHeadless || useComputeAdc) {
+        const reason = isHeadless
+          ? 'headless mode'
+          : 'GEMINI_CLI_USE_COMPUTE_ADC=true';
+        throw new FatalAuthenticationError(
+          `COMPUTE_ADC failed: ${adcMessage}. (LOGIN_WITH_GOOGLE fallback skipped due to ${reason}. Run in an interactive terminal to use OAuth.)`,
+        );
+      }
+
+      logger.info(
+        `[${logPrefix}] COMPUTE_ADC failed, falling back to LOGIN_WITH_GOOGLE.`,
+      );
+      try {
+        await config.refreshAuth(AuthType.LOGIN_WITH_GOOGLE);
+      } catch (e) {
+        if (e instanceof FatalAuthenticationError) {
+          const originalMessage = e instanceof Error ? e.message : String(e);
+          throw new FatalAuthenticationError(
+            `${originalMessage}. The initial COMPUTE_ADC attempt also failed: ${adcMessage}`,
+          );
+        }
+        throw e;
+      }
+    }
+
+    logger.info(
+      `[${logPrefix}] GOOGLE_CLOUD_PROJECT: ${process.env['GOOGLE_CLOUD_PROJECT']}`,
+    );
+  } else if (process.env['GEMINI_API_KEY']) {
+    logger.info(`[${logPrefix}] Using Gemini API Key`);
+    await config.refreshAuth(AuthType.USE_GEMINI);
+  } else {
+    const errorMessage = `[${logPrefix}] Unable to set GeneratorConfig. Please provide a GEMINI_API_KEY or set USE_CCPA.`;
+    logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}

packages/a2a-server/src/config/extension.ts

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Copied exactly from packages/cli/src/config/extension.ts, last PR #1026
+
+import {
+  GEMINI_DIR,
+  type MCPServerConfig,
+  type ExtensionInstallMetadata,
+  type GeminiCLIExtension,
+  homedir,
+} from '@google/gemini-cli-core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { logger } from '../utils/logger.js';
+
+export const EXTENSIONS_DIRECTORY_NAME = path.join(GEMINI_DIR, 'extensions');
+export const EXTENSIONS_CONFIG_FILENAME = 'gemini-extension.json';
+export const INSTALL_METADATA_FILENAME = '.gemini-extension-install.json';
+
+/**
+ * Extension definition as written to disk in gemini-extension.json files.
+ * This should *not* be referenced outside of the logic for reading files.
+ * If information is required for manipulating extensions (load, unload, update)
+ * outside of the loading process that data needs to be stored on the
+ * GeminiCLIExtension class defined in Core.
+ */
+interface ExtensionConfig {
+  name: string;
+  version: string;
+  mcpServers?: Record<string, MCPServerConfig>;
+  contextFileName?: string | string[];
+  excludeTools?: string[];
+}
+
+export function loadExtensions(workspaceDir: string): GeminiCLIExtension[] {
+  const allExtensions = [
+    ...loadExtensionsFromDir(workspaceDir),
+    ...loadExtensionsFromDir(homedir()),
+  ];
+
+  const uniqueExtensions: GeminiCLIExtension[] = [];
+  const seenNames = new Set<string>();
+  for (const extension of allExtensions) {
+    if (!seenNames.has(extension.name)) {
+      logger.info(
+        `Loading extension: ${extension.name} (version: ${extension.version})`,
+      );
+      uniqueExtensions.push(extension);
+      seenNames.add(extension.name);
+    }
+  }
+
+  return uniqueExtensions;
+}
+
+function loadExtensionsFromDir(dir: string): GeminiCLIExtension[] {
+  const extensionsDir = path.join(dir, EXTENSIONS_DIRECTORY_NAME);
+  if (!fs.existsSync(extensionsDir)) {
+    return [];
+  }
+
+  const extensions: GeminiCLIExtension[] = [];
+  for (const subdir of fs.readdirSync(extensionsDir)) {
+    const extensionDir = path.join(extensionsDir, subdir);
+
+    const extension = loadExtension(extensionDir);
+    if (extension != null) {
+      extensions.push(extension);
+    }
+  }
+  return extensions;
+}
+
+function loadExtension(extensionDir: string): GeminiCLIExtension | null {
+  if (!fs.statSync(extensionDir).isDirectory()) {
+    logger.error(
+      `Warning: unexpected file ${extensionDir} in extensions directory.`,
+    );
+    return null;
+  }
+
+  const configFilePath = path.join(extensionDir, EXTENSIONS_CONFIG_FILENAME);
+  if (!fs.existsSync(configFilePath)) {
+    logger.error(
+      `Warning: extension directory ${extensionDir} does not contain a config file ${configFilePath}.`,
+    );
+    return null;
+  }
+
+  try {
+    const configContent = fs.readFileSync(configFilePath, 'utf-8');
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const config = JSON.parse(configContent) as ExtensionConfig;
+    if (!config.name || !config.version) {
+      logger.error(
+        `Invalid extension config in ${configFilePath}: missing name or version.`,
+      );
+      return null;
+    }
+
+    const installMetadata = loadInstallMetadata(extensionDir);
+
+    const contextFiles = getContextFileNames(config)
+      .map((contextFileName) => path.join(extensionDir, contextFileName))
+      .filter((contextFilePath) => fs.existsSync(contextFilePath));
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return {
+      name: config.name,
+      version: config.version,
+      path: extensionDir,
+      contextFiles,
+      installMetadata,
+      mcpServers: config.mcpServers,
+      excludeTools: config.excludeTools,
+      isActive: true, // Barring any other signals extensions should be considered Active.
+    } as GeminiCLIExtension;
+  } catch (e) {
+    logger.error(
+      `Warning: error parsing extension config in ${configFilePath}: ${e}`,
+    );
+    return null;
+  }
+}
+
+function getContextFileNames(config: ExtensionConfig): string[] {
+  if (!config.contextFileName) {
+    return ['GEMINI.md'];
+  } else if (!Array.isArray(config.contextFileName)) {
+    return [config.contextFileName];
+  }
+  return config.contextFileName;
+}
+
+export function loadInstallMetadata(
+  extensionDir: string,
+): ExtensionInstallMetadata | undefined {
+  const metadataFilePath = path.join(extensionDir, INSTALL_METADATA_FILENAME);
+  try {
+    const configContent = fs.readFileSync(metadataFilePath, 'utf-8');
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const metadata = JSON.parse(configContent) as ExtensionInstallMetadata;
+    return metadata;
+  } catch (e) {
+    logger.warn(
+      `Failed to load or parse extension install metadata at ${metadataFilePath}: ${e}`,
+    );
+    return undefined;
+  }
+}

packages/a2a-server/src/config/settings.test.ts

@@ -0,0 +1,235 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { loadSettings, USER_SETTINGS_PATH } from './settings.js';
+import { debugLogger, checkPathTrust } from '@google/gemini-cli-core';
+
+const mocks = vi.hoisted(() => {
+  const suffix = Math.random().toString(36).slice(2);
+  return {
+    suffix,
+  };
+});
+
+vi.mock('node:os', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:os')>();
+  const path = await import('node:path');
+  return {
+    ...actual,
+    homedir: () => path.join(actual.tmpdir(), `gemini-home-${mocks.suffix}`),
+  };
+});
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  const path = await import('node:path');
+  const os = await import('node:os');
+  return {
+    ...actual,
+    GEMINI_DIR: '.gemini',
+    debugLogger: {
+      error: vi.fn(),
+    },
+    getErrorMessage: (error: unknown) => String(error),
+    homedir: () => path.join(os.tmpdir(), `gemini-home-${mocks.suffix}`),
+    checkPathTrust: vi.fn(() => ({ isTrusted: false })),
+    isHeadlessMode: vi.fn(() => true),
+  };
+});
+
+describe('loadSettings', () => {
+  const mockHomeDir = path.join(os.tmpdir(), `gemini-home-${mocks.suffix}`);
+  const mockWorkspaceDir = path.join(
+    os.tmpdir(),
+    `gemini-workspace-${mocks.suffix}`,
+  );
+  const mockGeminiHomeDir = path.join(mockHomeDir, '.gemini');
+  const mockGeminiWorkspaceDir = path.join(mockWorkspaceDir, '.gemini');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Create the directories using the real fs
+    if (!fs.existsSync(mockGeminiHomeDir)) {
+      fs.mkdirSync(mockGeminiHomeDir, { recursive: true });
+    }
+    if (!fs.existsSync(mockGeminiWorkspaceDir)) {
+      fs.mkdirSync(mockGeminiWorkspaceDir, { recursive: true });
+    }
+
+    // Clean up settings files before each test
+    if (fs.existsSync(USER_SETTINGS_PATH)) {
+      fs.rmSync(USER_SETTINGS_PATH);
+    }
+    const workspaceSettingsPath = path.join(
+      mockGeminiWorkspaceDir,
+      'settings.json',
+    );
+    if (fs.existsSync(workspaceSettingsPath)) {
+      fs.rmSync(workspaceSettingsPath);
+    }
+  });
+
+  afterEach(() => {
+    try {
+      if (fs.existsSync(mockHomeDir)) {
+        fs.rmSync(mockHomeDir, { recursive: true, force: true });
+      }
+      if (fs.existsSync(mockWorkspaceDir)) {
+        fs.rmSync(mockWorkspaceDir, { recursive: true, force: true });
+      }
+    } catch (e) {
+      debugLogger.error('Failed to cleanup temp dirs', e);
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('should load other top-level settings correctly', () => {
+    const settings = {
+      showMemoryUsage: true,
+      tools: {
+        core: ['tool1', 'tool2'],
+      },
+      mcpServers: {
+        server1: {
+          command: 'cmd',
+          args: ['arg'],
+        },
+      },
+      fileFiltering: {
+        respectGitIgnore: true,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(settings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.showMemoryUsage).toBe(true);
+    expect(result.tools?.core).toEqual(['tool1', 'tool2']);
+    expect(result.mcpServers).toHaveProperty('server1');
+    expect(result.fileFiltering?.respectGitIgnore).toBe(true);
+  });
+
+  it('should load experimental settings correctly', () => {
+    const settings = {
+      experimental: {
+        enableAgents: true,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(settings));
+
+    const result = loadSettings(mockWorkspaceDir);
+    expect(result.experimental?.enableAgents).toBe(true);
+  });
+
+  it('should overwrite top-level settings from workspace (shallow merge)', () => {
+    const userSettings = {
+      showMemoryUsage: false,
+      fileFiltering: {
+        respectGitIgnore: true,
+        enableRecursiveFileSearch: true,
+      },
+    };
+    fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(userSettings));
+
+    const workspaceSettings = {
+      showMemoryUsage: true,
+      fileFiltering: {
+        respectGitIgnore: false,
+      },
+    };
+    const workspaceSettingsPath = path.join(
+      mockGeminiWorkspaceDir,
+      'settings.json',
+    );
+    fs.writeFileSync(workspaceSettingsPath, JSON.stringify(workspaceSettings));
+
+    const result = loadSettings(mockWorkspaceDir, true);
+    // Primitive value overwritten
+    expect(result.showMemoryUsage).toBe(true);
+
+    // Object value completely replaced (shallow merge behavior)
+    expect(result.fileFiltering?.respectGitIgnore).toBe(false);
+    expect(result.fileFiltering?.enableRecursiveFileSearch).toBeUndefined();
+  });
+
+  describe('security', () => {
+    it('should NOT load workspace settings if workspace is NOT trusted', () => {
+      const userSettings = { showMemoryUsage: false };
+      fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(userSettings));
+
+      const workspaceSettings = { showMemoryUsage: true };
+      const workspaceSettingsPath = path.join(
+        mockGeminiWorkspaceDir,
+        'settings.json',
+      );
+      fs.writeFileSync(
+        workspaceSettingsPath,
+        JSON.stringify(workspaceSettings),
+      );
+
+      // checkPathTrust is mocked to return isTrusted: false by default
+      const result = loadSettings(mockWorkspaceDir);
+      expect(result.showMemoryUsage).toBe(false);
+    });
+
+    it('should load workspace settings if workspace IS trusted', () => {
+      vi.mocked(checkPathTrust).mockReturnValueOnce({
+        isTrusted: true,
+        source: 'file',
+      });
+      const userSettings = { showMemoryUsage: false };
+      fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(userSettings));
+
+      const workspaceSettings = { showMemoryUsage: true };
+      const workspaceSettingsPath = path.join(
+        mockGeminiWorkspaceDir,
+        'settings.json',
+      );
+      fs.writeFileSync(
+        workspaceSettingsPath,
+        JSON.stringify(workspaceSettings),
+      );
+
+      const result = loadSettings(mockWorkspaceDir);
+      expect(result.showMemoryUsage).toBe(true);
+    });
+
+    it('should NOT allow workspace settings to override adminPolicyPaths or policyPaths even if trusted', () => {
+      vi.mocked(checkPathTrust).mockReturnValueOnce({
+        isTrusted: true,
+        source: 'file',
+      });
+      const userSettings = {
+        adminPolicyPaths: ['/trusted/admin'],
+        policyPaths: ['/trusted/user'],
+      };
+      fs.writeFileSync(USER_SETTINGS_PATH, JSON.stringify(userSettings));
+
+      const workspaceSettings = {
+        adminPolicyPaths: ['./malicious/admin'],
+        policyPaths: ['./malicious/user'],
+        showMemoryUsage: true,
+      };
+      const workspaceSettingsPath = path.join(
+        mockGeminiWorkspaceDir,
+        'settings.json',
+      );
+      fs.writeFileSync(
+        workspaceSettingsPath,
+        JSON.stringify(workspaceSettings),
+      );
+
+      const result = loadSettings(mockWorkspaceDir);
+      expect(result.showMemoryUsage).toBe(true);
+      expect(result.adminPolicyPaths).toEqual(['/trusted/admin']);
+      expect(result.policyPaths).toEqual(['/trusted/user']);
+    });
+  });
+});

packages/a2a-server/src/config/settings.ts

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+  type MCPServerConfig,
+  debugLogger,
+  GEMINI_DIR,
+  getErrorMessage,
+  type TelemetrySettings,
+  homedir,
+  checkPathTrust,
+  isHeadlessMode,
+} from '@google/gemini-cli-core';
+import stripJsonComments from 'strip-json-comments';
+
+export const USER_SETTINGS_DIR = path.join(homedir(), GEMINI_DIR);
+export const USER_SETTINGS_PATH = path.join(USER_SETTINGS_DIR, 'settings.json');
+
+// TODO: Ensure full compatibility with V2 nested settings structure (settings.schema.json).
+// This involves updating the interface and implementing migration logic to support legacy V1 (flat) settings,
+// similar to how packages/cli/src/config/settings.ts handles it.
+export interface Settings {
+  mcpServers?: Record<string, MCPServerConfig>;
+  tools?: {
+    allowed?: string[];
+    exclude?: string[];
+    core?: string[];
+  };
+  telemetry?: TelemetrySettings;
+  showMemoryUsage?: boolean;
+  checkpointing?: CheckpointingSettings;
+  folderTrust?: boolean;
+  general?: {
+    previewFeatures?: boolean;
+  };
+
+  // Git-aware file filtering settings
+  fileFiltering?: {
+    respectGitIgnore?: boolean;
+    respectGeminiIgnore?: boolean;
+    enableRecursiveFileSearch?: boolean;
+    customIgnoreFilePaths?: string[];
+  };
+  experimental?: {
+    enableAgents?: boolean;
+  };
+  policyPaths?: string[];
+  adminPolicyPaths?: string[];
+}
+
+export interface SettingsError {
+  message: string;
+  path: string;
+}
+
+export interface CheckpointingSettings {
+  enabled?: boolean;
+}
+
+/**
+ * Loads settings from user and workspace directories.
+ * Project settings override user settings if the workspace is trusted.
+ *
+ * How is it different to gemini-cli/cli: Returns already merged settings rather
+ * than `LoadedSettings` (unnecessary since we are not modifying users
+ * settings.json).
+ */
+export function loadSettings(
+  workspaceDir: string,
+  isTrustedOverride?: boolean,
+): Settings {
+  let userSettings: Settings = {};
+  let workspaceSettings: Settings = {};
+  const settingsErrors: SettingsError[] = [];
+
+  // Load user settings
+  try {
+    if (fs.existsSync(USER_SETTINGS_PATH)) {
+      const userContent = fs.readFileSync(USER_SETTINGS_PATH, 'utf-8');
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      const parsedUserSettings = JSON.parse(
+        stripJsonComments(userContent),
+      ) as Settings;
+      userSettings = resolveEnvVarsInObject(parsedUserSettings);
+    }
+  } catch (error: unknown) {
+    settingsErrors.push({
+      message: getErrorMessage(error),
+      path: USER_SETTINGS_PATH,
+    });
+  }
+
+  let isTrusted = isTrustedOverride;
+  if (isTrusted === undefined) {
+    const { isTrusted: trustResult } = checkPathTrust({
+      path: workspaceDir,
+      isFolderTrustEnabled: userSettings.folderTrust ?? true,
+      isHeadless: isHeadlessMode(),
+    });
+    isTrusted = trustResult ?? false;
+  }
+
+  const workspaceSettingsPath = path.join(
+    workspaceDir,
+    GEMINI_DIR,
+    'settings.json',
+  );
+
+  // Load workspace settings only if trusted
+  if (isTrusted) {
+    try {
+      if (fs.existsSync(workspaceSettingsPath)) {
+        const projectContent = fs.readFileSync(workspaceSettingsPath, 'utf-8');
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        const parsedWorkspaceSettings = JSON.parse(
+          stripJsonComments(projectContent),
+        ) as Settings;
+        workspaceSettings = resolveEnvVarsInObject(parsedWorkspaceSettings);
+      }
+    } catch (error: unknown) {
+      settingsErrors.push({
+        message: getErrorMessage(error),
+        path: workspaceSettingsPath,
+      });
+    }
+  }
+
+  if (settingsErrors.length > 0) {
+    debugLogger.error('Errors loading settings:');
+    for (const error of settingsErrors) {
+      debugLogger.error(`  Path: ${error.path}`);
+      debugLogger.error(`  Message: ${error.message}`);
+    }
+  }
+
+  // If there are overlapping keys, the values of workspaceSettings will
+  // override values from userSettings
+  const mergedSettings = {
+    ...userSettings,
+    ...workspaceSettings,
+  };
+
+  // Security: ensure policyPaths and adminPolicyPaths are only loaded from trusted, user-level
+  // configuration and cannot be overridden by workspace-level settings, even if the
+  // workspace is trusted.
+  mergedSettings.policyPaths = userSettings.policyPaths;
+  mergedSettings.adminPolicyPaths = userSettings.adminPolicyPaths;
+
+  return mergedSettings;
+}
+
+function resolveEnvVarsInString(value: string): string {
+  const envVarRegex = /\$(?:(\w+)|{([^}]+)})/g; // Find $VAR_NAME or ${VAR_NAME}
+  return value.replace(
+    envVarRegex,
+    (match: string, varName1: string, varName2: string) => {
+      const varName = varName1 || varName2;
+      const envValue = process?.env?.[varName];
+      if (typeof envValue === 'string') {
+        return envValue;
+      }
+      return match;
+    },
+  );
+}
+
+function resolveEnvVarsInObject<T>(obj: T): T {
+  if (
+    obj === null ||
+    obj === undefined ||
+    typeof obj === 'boolean' ||
+    typeof obj === 'number'
+  ) {
+    return obj;
+  }
+
+  if (typeof obj === 'string') {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return resolveEnvVarsInString(obj) as unknown as T;
+  }
+
+  if (Array.isArray(obj)) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-return
+    return obj.map((item) => resolveEnvVarsInObject(item)) as unknown as T;
+  }
+
+  if (typeof obj === 'object') {
+    const newObj = { ...obj } as T;
+    for (const key in newObj) {
+      if (Object.prototype.hasOwnProperty.call(newObj, key)) {
+        newObj[key] = resolveEnvVarsInObject(newObj[key]);
+      }
+    }
+    return newObj;
+  }
+
+  return obj;
+}

packages/a2a-server/src/http/app.ts

@@ -0,0 +1,413 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import express, { type Request } from 'express';
+
+import type { AgentCard, Message } from '@a2a-js/sdk';
+import {
+  type TaskStore,
+  DefaultRequestHandler,
+  InMemoryTaskStore,
+  DefaultExecutionEventBus,
+  type AgentExecutionEvent,
+  UnauthenticatedUser,
+} from '@a2a-js/sdk/server';
+import { A2AExpressApp, type UserBuilder } from '@a2a-js/sdk/server/express'; // Import server components
+import { v4 as uuidv4 } from 'uuid';
+import { logger } from '../utils/logger.js';
+import type { AgentSettings } from '../types.js';
+import { GCSTaskStore, NoOpTaskStore } from '../persistence/gcs.js';
+import { CoderAgentExecutor } from '../agent/executor.js';
+import { requestStorage } from './requestStorage.js';
+import { loadConfig, loadEnvironment, setTargetDir } from '../config/config.js';
+import { loadSettings } from '../config/settings.js';
+import { loadExtensions } from '../config/extension.js';
+import { commandRegistry } from '../commands/command-registry.js';
+import {
+  debugLogger,
+  SimpleExtensionLoader,
+  GitService,
+  checkPathTrust,
+  isHeadlessMode,
+} from '@google/gemini-cli-core';
+import type { Command, CommandArgument } from '../commands/types.js';
+
+type CommandResponse = {
+  name: string;
+  description: string;
+  arguments: CommandArgument[];
+  subCommands: CommandResponse[];
+};
+
+const coderAgentCard: AgentCard = {
+  name: 'Gemini SDLC Agent',
+  description:
+    'An agent that generates code based on natural language instructions and streams file outputs.',
+  url: 'http://localhost:41242/',
+  provider: {
+    organization: 'Google',
+    url: 'https://google.com',
+  },
+  protocolVersion: '0.3.0',
+  version: '0.0.2', // Incremented version
+  capabilities: {
+    streaming: true,
+    pushNotifications: false,
+    stateTransitionHistory: true,
+  },
+  securitySchemes: {
+    bearerAuth: {
+      type: 'http',
+      scheme: 'bearer',
+    },
+    basicAuth: {
+      type: 'http',
+      scheme: 'basic',
+    },
+  },
+  security: [{ bearerAuth: [] }, { basicAuth: [] }],
+  defaultInputModes: ['text'],
+  defaultOutputModes: ['text'],
+  skills: [
+    {
+      id: 'code_generation',
+      name: 'Code Generation',
+      description:
+        'Generates code snippets or complete files based on user requests, streaming the results.',
+      tags: ['code', 'development', 'programming'],
+      examples: [
+        'Write a python function to calculate fibonacci numbers.',
+        'Create an HTML file with a basic button that alerts "Hello!" when clicked.',
+      ],
+      inputModes: ['text'],
+      outputModes: ['text'],
+    },
+  ],
+  supportsAuthenticatedExtendedCard: false,
+};
+
+export function updateCoderAgentCardUrl(port: number) {
+  coderAgentCard.url = `http://localhost:${port}/`;
+}
+
+const customUserBuilder: UserBuilder = async (req: Request) => {
+  const auth = req.headers['authorization'];
+  if (auth) {
+    const scheme = auth.split(' ')[0];
+    logger.info(
+      `[customUserBuilder] Received Authorization header with scheme: ${scheme}`,
+    );
+  }
+  if (!auth) return new UnauthenticatedUser();
+
+  // 1. Bearer Auth
+  if (auth.startsWith('Bearer ')) {
+    const token = auth.substring(7);
+    if (token === 'valid-token') {
+      return { userName: 'bearer-user', isAuthenticated: true };
+    }
+  }
+
+  // 2. Basic Auth
+  if (auth.startsWith('Basic ')) {
+    const credentials = Buffer.from(auth.substring(6), 'base64').toString();
+    if (credentials === 'admin:password') {
+      return { userName: 'basic-user', isAuthenticated: true };
+    }
+  }
+
+  return new UnauthenticatedUser();
+};
+
+async function handleExecuteCommand(
+  req: express.Request,
+  res: express.Response,
+  context: {
+    config: Awaited<ReturnType<typeof loadConfig>>;
+    git: GitService | undefined;
+    agentExecutor: CoderAgentExecutor;
+  },
+) {
+  logger.info('[CoreAgent] Received /executeCommand request: ', req.body);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const { command, args } = req.body;
+  try {
+    if (typeof command !== 'string') {
+      return res.status(400).json({ error: 'Invalid "command" field.' });
+    }
+
+    if (args && !Array.isArray(args)) {
+      return res.status(400).json({ error: '"args" field must be an array.' });
+    }
+
+    const commandToExecute = commandRegistry.get(command);
+
+    if (commandToExecute?.requiresWorkspace) {
+      if (!process.env['CODER_AGENT_WORKSPACE_PATH']) {
+        return res.status(400).json({
+          error: `Command "${command}" requires a workspace, but CODER_AGENT_WORKSPACE_PATH is not set.`,
+        });
+      }
+    }
+
+    if (!commandToExecute) {
+      return res.status(404).json({ error: `Command not found: ${command}` });
+    }
+
+    if (commandToExecute.streaming) {
+      const eventBus = new DefaultExecutionEventBus();
+      res.setHeader('Content-Type', 'text/event-stream');
+      const eventHandler = (event: AgentExecutionEvent) => {
+        const jsonRpcResponse = {
+          jsonrpc: '2.0',
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          id: 'taskId' in event ? event.taskId : (event as Message).messageId,
+          result: event,
+        };
+        res.write(`data: ${JSON.stringify(jsonRpcResponse)}\n`);
+      };
+      eventBus.on('event', eventHandler);
+
+      await commandToExecute.execute({ ...context, eventBus }, args ?? []);
+
+      eventBus.off('event', eventHandler);
+      eventBus.finished();
+      return res.end(); // Explicit return for streaming path
+    } else {
+      const result = await commandToExecute.execute(context, args ?? []);
+      logger.info('[CoreAgent] Sending /executeCommand response: ', result);
+      return res.status(200).json(result);
+    }
+  } catch (e) {
+    logger.error(
+      `Error executing /executeCommand: ${command} with args: ${JSON.stringify(
+        args,
+      )}`,
+      e,
+    );
+    const errorMessage =
+      e instanceof Error ? e.message : 'Unknown error executing command';
+    return res.status(500).json({ error: errorMessage });
+  }
+}
+
+export async function createApp() {
+  try {
+    // Load the server configuration once on startup.
+    const workspaceRoot = setTargetDir(undefined);
+    loadEnvironment();
+
+    // Use a temporary settings load to check if folder trust is enabled.
+    // This is similar to how the CLI handles the initial trust check.
+    const initialSettings = loadSettings(workspaceRoot, false);
+    const { isTrusted } = checkPathTrust({
+      path: workspaceRoot,
+      isFolderTrustEnabled: initialSettings.folderTrust ?? true,
+      isHeadless: isHeadlessMode(),
+    });
+
+    const settings = loadSettings(workspaceRoot, isTrusted ?? false);
+    const extensions = loadExtensions(workspaceRoot);
+    const config = await loadConfig(
+      settings,
+      new SimpleExtensionLoader(extensions),
+      'a2a-server',
+      isTrusted ?? false,
+    );
+
+    let git: GitService | undefined;
+    if (config.getCheckpointingEnabled()) {
+      git = new GitService(config.getTargetDir(), config.storage);
+      await git.initialize();
+    }
+
+    // loadEnvironment() is called within getConfig now
+    const bucketName = process.env['GCS_BUCKET_NAME'];
+    let taskStoreForExecutor: TaskStore;
+    let taskStoreForHandler: TaskStore;
+
+    if (bucketName) {
+      logger.info(`Using GCSTaskStore with bucket: ${bucketName}`);
+      const gcsTaskStore = new GCSTaskStore(bucketName);
+      taskStoreForExecutor = gcsTaskStore;
+      taskStoreForHandler = new NoOpTaskStore(gcsTaskStore);
+    } else {
+      logger.info('Using InMemoryTaskStore');
+      const inMemoryTaskStore = new InMemoryTaskStore();
+      taskStoreForExecutor = inMemoryTaskStore;
+      taskStoreForHandler = inMemoryTaskStore;
+    }
+
+    const agentExecutor = new CoderAgentExecutor(taskStoreForExecutor);
+
+    const context = { config, git, agentExecutor };
+
+    const requestHandler = new DefaultRequestHandler(
+      coderAgentCard,
+      taskStoreForHandler,
+      agentExecutor,
+    );
+
+    let expressApp = express();
+    expressApp.use((req, res, next) => {
+      requestStorage.run({ req }, next);
+    });
+
+    const appBuilder = new A2AExpressApp(requestHandler, customUserBuilder);
+    expressApp = appBuilder.setupRoutes(expressApp, '');
+    expressApp.use(express.json());
+
+    expressApp.post('/tasks', async (req, res) => {
+      try {
+        const taskId = uuidv4();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        const agentSettings = req.body.agentSettings as
+          | AgentSettings
+          | undefined;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const contextId = req.body.contextId || uuidv4();
+        const wrapper = await agentExecutor.createTask(
+          taskId,
+          contextId,
+          agentSettings,
+        );
+        await taskStoreForExecutor.save(wrapper.toSDKTask());
+        res.status(201).json(wrapper.id);
+      } catch (error) {
+        logger.error('[CoreAgent] Error creating task:', error);
+        const errorMessage =
+          error instanceof Error
+            ? error.message
+            : 'Unknown error creating task';
+        res.status(500).send({ error: errorMessage });
+      }
+    });
+
+    expressApp.post('/executeCommand', (req, res) => {
+      void handleExecuteCommand(req, res, context);
+    });
+
+    expressApp.get('/listCommands', (req, res) => {
+      try {
+        const transformCommand = (
+          command: Command,
+          visited: string[],
+        ): CommandResponse | undefined => {
+          const commandName = command.name;
+          if (visited.includes(commandName)) {
+            debugLogger.warn(
+              `Command ${commandName} already inserted in the response, skipping`,
+            );
+            return undefined;
+          }
+
+          return {
+            name: command.name,
+            description: command.description,
+            arguments: command.arguments ?? [],
+            subCommands: (command.subCommands ?? [])
+              .map((subCommand) =>
+                transformCommand(subCommand, visited.concat(commandName)),
+              )
+              .filter(
+                (subCommand): subCommand is CommandResponse => !!subCommand,
+              ),
+          };
+        };
+
+        const commands = commandRegistry
+          .getAllCommands()
+          .filter((command) => command.topLevel)
+          .map((command) => transformCommand(command, []));
+
+        return res.status(200).json({ commands });
+      } catch (e) {
+        logger.error('Error executing /listCommands:', e);
+        const errorMessage =
+          e instanceof Error ? e.message : 'Unknown error listing commands';
+        return res.status(500).json({ error: errorMessage });
+      }
+    });
+
+    expressApp.get('/tasks/metadata', async (req, res) => {
+      // This endpoint is only meaningful if the task store is in-memory.
+      if (!(taskStoreForExecutor instanceof InMemoryTaskStore)) {
+        res.status(501).send({
+          error:
+            'Listing all task metadata is only supported when using InMemoryTaskStore.',
+        });
+      }
+      try {
+        const wrappers = agentExecutor.getAllTasks();
+        if (wrappers && wrappers.length > 0) {
+          const tasksMetadata = await Promise.all(
+            wrappers.map((wrapper) => wrapper.task.getMetadata()),
+          );
+          res.status(200).json(tasksMetadata);
+        } else {
+          res.status(204).send();
+        }
+      } catch (error) {
+        logger.error('[CoreAgent] Error getting all task metadata:', error);
+        const errorMessage =
+          error instanceof Error
+            ? error.message
+            : 'Unknown error getting task metadata';
+        res.status(500).send({ error: errorMessage });
+      }
+    });
+
+    expressApp.get('/tasks/:taskId/metadata', async (req, res) => {
+      const taskId = req.params.taskId;
+      let wrapper = agentExecutor.getTask(taskId);
+      if (!wrapper) {
+        const sdkTask = await taskStoreForExecutor.load(taskId);
+        if (sdkTask) {
+          wrapper = await agentExecutor.reconstruct(sdkTask);
+        }
+      }
+      if (!wrapper) {
+        res.status(404).send({ error: 'Task not found' });
+        return;
+      }
+      res.json({ metadata: await wrapper.task.getMetadata() });
+    });
+    return expressApp;
+  } catch (error) {
+    logger.error('[CoreAgent] Error during startup:', error);
+    process.exit(1);
+  }
+}
+
+export async function main() {
+  try {
+    const expressApp = await createApp();
+    const port = Number(process.env['CODER_AGENT_PORT'] || 0);
+
+    const server = expressApp.listen(port, 'localhost', () => {
+      const address = server.address();
+      let actualPort;
+      if (process.env['CODER_AGENT_PORT']) {
+        actualPort = process.env['CODER_AGENT_PORT'];
+      } else if (address && typeof address !== 'string') {
+        actualPort = address.port;
+      } else {
+        throw new Error('[Core Agent] Could not find port number.');
+      }
+      updateCoderAgentCardUrl(Number(actualPort));
+      logger.info(
+        `[CoreAgent] Agent Server started on http://localhost:${actualPort}`,
+      );
+      logger.info(
+        `[CoreAgent] Agent Card: http://localhost:${actualPort}/.well-known/agent-card.json`,
+      );
+      logger.info('[CoreAgent] Press Ctrl+C to stop the server');
+    });
+  } catch (error) {
+    logger.error('[CoreAgent] Error during startup:', error);
+    process.exit(1);
+  }
+}

packages/a2a-server/src/http/endpoints.test.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import request from 'supertest';
+import type express from 'express';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import { createApp, updateCoderAgentCardUrl } from './app.js';
+import type { TaskMetadata } from '../types.js';
+import { createMockConfig } from '../utils/testing_utils.js';
+import { debugLogger, type Config } from '@google/gemini-cli-core';
+
+// Mock the logger to avoid polluting test output
+// Comment out to help debug
+vi.mock('../utils/logger.js', () => ({
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+// Mock Task.create to avoid its complex setup
+vi.mock('../agent/task.js', () => {
+  class MockTask {
+    id: string;
+    contextId: string;
+    taskState = 'submitted';
+    config = {
+      getContentGeneratorConfig: vi
+        .fn()
+        .mockReturnValue({ model: 'gemini-pro' }),
+    };
+    geminiClient = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+    };
+    constructor(id: string, contextId: string) {
+      this.id = id;
+      this.contextId = contextId;
+    }
+    static create = vi
+      .fn()
+      .mockImplementation((id, contextId) =>
+        Promise.resolve(new MockTask(id, contextId)),
+      );
+    getMetadata = vi.fn().mockImplementation(async () => ({
+      id: this.id,
+      contextId: this.contextId,
+      taskState: this.taskState,
+      model: 'gemini-pro',
+      mcpServers: [],
+      availableTools: [],
+    }));
+  }
+  return { Task: MockTask };
+});
+
+vi.mock('../config/config.js', async () => {
+  const actual = await vi.importActual('../config/config.js');
+  return {
+    ...actual,
+    loadConfig: vi
+      .fn()
+      .mockImplementation(async () => createMockConfig({}) as Config),
+  };
+});
+
+describe('Agent Server Endpoints', () => {
+  let app: express.Express;
+  let server: Server;
+  let testWorkspace: string;
+
+  const createTask = (contextId: string) =>
+    request(app)
+      .post('/tasks')
+      .send({
+        contextId,
+        agentSettings: {
+          kind: 'agent-settings',
+          workspacePath: testWorkspace,
+        },
+      })
+      .set('Content-Type', 'application/json');
+
+  beforeAll(async () => {
+    // Create a unique temporary directory for the workspace to avoid conflicts
+    testWorkspace = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'gemini-agent-test-'),
+    );
+    app = await createApp();
+    await new Promise<void>((resolve) => {
+      server = app.listen(0, () => {
+        const port = (server.address() as AddressInfo).port;
+        updateCoderAgentCardUrl(port);
+        resolve();
+      });
+    });
+  });
+
+  afterAll(async () => {
+    if (server) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => {
+          if (err) return reject(err);
+          resolve();
+        });
+      });
+    }
+
+    if (testWorkspace) {
+      try {
+        fs.rmSync(testWorkspace, { recursive: true, force: true });
+      } catch (e) {
+        debugLogger.warn(`Could not remove temp dir '${testWorkspace}':`, e);
+      }
+    }
+  });
+
+  it('should create a new task via POST /tasks', async () => {
+    const response = await createTask('test-context');
+    expect(response.status).toBe(201);
+    expect(response.body).toBeTypeOf('string'); // Should return the task ID
+  }, 7000);
+
+  it('should get metadata for a specific task via GET /tasks/:taskId/metadata', async () => {
+    const createResponse = await createTask('test-context-2');
+    const taskId = createResponse.body;
+    const response = await request(app).get(`/tasks/${taskId}/metadata`);
+    expect(response.status).toBe(200);
+    expect(response.body.metadata.id).toBe(taskId);
+  }, 6000);
+
+  it('should get metadata for all tasks via GET /tasks/metadata', async () => {
+    const createResponse = await createTask('test-context-3');
+    const taskId = createResponse.body;
+    const response = await request(app).get('/tasks/metadata');
+    expect(response.status).toBe(200);
+    expect(Array.isArray(response.body)).toBe(true);
+    expect(response.body.length).toBeGreaterThan(0);
+    const taskMetadata = response.body.find(
+      (m: TaskMetadata) => m.id === taskId,
+    );
+    expect(taskMetadata).toBeDefined();
+  });
+
+  it('should return 404 for a non-existent task', async () => {
+    const response = await request(app).get('/tasks/fake-task/metadata');
+    expect(response.status).toBe(404);
+  });
+
+  it('should return agent metadata via GET /.well-known/agent-card.json', async () => {
+    const response = await request(app).get('/.well-known/agent-card.json');
+    const port = (server.address() as AddressInfo).port;
+    expect(response.status).toBe(200);
+    expect(response.body.name).toBe('Gemini SDLC Agent');
+    expect(response.body.url).toBe(`http://localhost:${port}/`);
+  });
+});

packages/a2a-server/src/http/requestStorage.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type express from 'express';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const requestStorage = new AsyncLocalStorage<{ req: express.Request }>();

packages/a2a-server/src/http/server.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as url from 'node:url';
+import * as path from 'node:path';
+
+import { logger } from '../utils/logger.js';
+import { main } from './app.js';
+
+// Check if the module is the main script being run
+const isMainModule =
+  path.basename(process.argv[1]) ===
+  path.basename(url.fileURLToPath(import.meta.url));
+
+if (
+  import.meta.url.startsWith('file:') &&
+  isMainModule &&
+  process.env['NODE_ENV'] !== 'test'
+) {
+  process.on('uncaughtException', (error) => {
+    logger.error('Unhandled exception:', error);
+    process.exit(1);
+  });
+
+  main().catch((error) => {
+    logger.error('[CoreAgent] Unhandled error in main:', error);
+    process.exit(1);
+  });
+}

packages/a2a-server/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './agent/executor.js';
+export * from './http/app.js';
+export * from './types.js';

packages/a2a-server/src/persistence/gcs.test.ts

@@ -0,0 +1,446 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Storage } from '@google-cloud/storage';
+import * as fse from 'fs-extra';
+import * as tar from 'tar';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import { v4 as uuidv4 } from 'uuid';
+import type { Task as SDKTask } from '@a2a-js/sdk';
+import type { TaskStore } from '@a2a-js/sdk/server';
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  vi,
+  type Mocked,
+  type MockedClass,
+  type Mock,
+} from 'vitest';
+
+import { GCSTaskStore, NoOpTaskStore } from './gcs.js';
+import { logger } from '../utils/logger.js';
+import * as configModule from '../config/config.js';
+import { getPersistedState, METADATA_KEY } from '../types.js';
+
+// Mock dependencies
+const fsMocks = vi.hoisted(() => ({
+  readdir: vi.fn(),
+  createReadStream: vi.fn(),
+}));
+
+vi.mock('@google-cloud/storage');
+vi.mock('fs-extra', () => ({
+  pathExists: vi.fn(),
+  readdir: vi.fn(),
+  remove: vi.fn(),
+  ensureDir: vi.fn(),
+  createReadStream: vi.fn(),
+}));
+vi.mock('node:fs', async () => {
+  const actual = await vi.importActual<typeof import('node:fs')>('node:fs');
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      readdir: fsMocks.readdir,
+    },
+    createReadStream: fsMocks.createReadStream,
+  };
+});
+vi.mock('fs', async () => {
+  const actual = await vi.importActual<typeof import('node:fs')>('node:fs');
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      readdir: fsMocks.readdir,
+    },
+    createReadStream: fsMocks.createReadStream,
+  };
+});
+vi.mock('tar', async () => {
+  const actualFs = await vi.importActual<typeof import('node:fs')>('node:fs');
+  return {
+    c: vi.fn(({ file }) => {
+      if (file) {
+        actualFs.writeFileSync(file, Buffer.from('dummy tar content'));
+      }
+      return Promise.resolve();
+    }),
+    x: vi.fn().mockResolvedValue(undefined),
+    t: vi.fn().mockResolvedValue(undefined),
+    r: vi.fn().mockResolvedValue(undefined),
+    u: vi.fn().mockResolvedValue(undefined),
+  };
+});
+vi.mock('zlib');
+vi.mock('uuid');
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+vi.mock('../config/config.js', () => ({
+  setTargetDir: vi.fn(),
+}));
+vi.mock('node:stream/promises', () => ({
+  pipeline: vi.fn(),
+}));
+vi.mock('../types.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../types.js')>();
+  return {
+    ...actual,
+    getPersistedState: vi.fn(),
+  };
+});
+
+const mockStorage = Storage as MockedClass<typeof Storage>;
+const mockFse = fse as Mocked<typeof fse>;
+const mockCreateReadStream = fsMocks.createReadStream;
+const mockTar = tar as Mocked<typeof tar>;
+const mockGzipSync = gzipSync as Mock;
+const mockGunzipSync = gunzipSync as Mock;
+const mockUuidv4 = uuidv4 as Mock;
+const mockSetTargetDir = configModule.setTargetDir as Mock;
+const mockGetPersistedState = getPersistedState as Mock;
+const TEST_METADATA_KEY = METADATA_KEY || '__persistedState';
+
+type MockWriteStream = {
+  emit: Mock<(event: string, ...args: unknown[]) => boolean>;
+  removeListener: Mock<
+    (event: string, cb: (error?: Error | null) => void) => MockWriteStream
+  >;
+  once: Mock<
+    (event: string, cb: (error?: Error | null) => void) => MockWriteStream
+  >;
+  on: Mock<
+    (event: string, cb: (error?: Error | null) => void) => MockWriteStream
+  >;
+  destroy: Mock<() => void>;
+  write: Mock<(chunk: unknown, encoding?: unknown, cb?: unknown) => boolean>;
+  end: Mock<(cb?: unknown) => void>;
+  destroyed: boolean;
+};
+
+type MockFile = {
+  save: Mock<(data: Buffer | string) => Promise<void>>;
+  download: Mock<() => Promise<[Buffer]>>;
+  exists: Mock<() => Promise<[boolean]>>;
+  createWriteStream: Mock<() => MockWriteStream>;
+};
+
+type MockBucket = {
+  exists: Mock<() => Promise<[boolean]>>;
+  file: Mock<(path: string) => MockFile>;
+  name: string;
+};
+
+type MockStorageInstance = {
+  bucket: Mock<(name: string) => MockBucket>;
+  getBuckets: Mock<() => Promise<[Array<{ name: string }>]>>;
+  createBucket: Mock<(name: string) => Promise<[MockBucket]>>;
+};
+
+describe('GCSTaskStore', () => {
+  let bucketName: string;
+  let mockBucket: MockBucket;
+  let mockFile: MockFile;
+  let mockWriteStream: MockWriteStream;
+  let mockStorageInstance: MockStorageInstance;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    bucketName = 'test-bucket';
+
+    mockWriteStream = {
+      emit: vi.fn().mockReturnValue(true),
+      removeListener: vi.fn().mockReturnValue(mockWriteStream),
+      on: vi.fn((event, cb) => {
+        if (event === 'finish') setTimeout(cb, 0); // Simulate async finish
+        return mockWriteStream;
+      }),
+      once: vi.fn((event, cb) => {
+        if (event === 'finish') setTimeout(cb, 0); // Simulate async finish        return mockWriteStream;
+      }),
+      destroy: vi.fn(),
+      write: vi.fn().mockReturnValue(true),
+      end: vi.fn(),
+      destroyed: false,
+    };
+
+    mockFile = {
+      save: vi.fn().mockResolvedValue(undefined),
+      download: vi.fn().mockResolvedValue([Buffer.from('')]),
+      exists: vi.fn().mockResolvedValue([true]),
+      createWriteStream: vi.fn().mockReturnValue(mockWriteStream),
+    };
+
+    mockBucket = {
+      exists: vi.fn().mockResolvedValue([true]),
+      file: vi.fn().mockReturnValue(mockFile),
+      name: bucketName,
+    };
+
+    mockStorageInstance = {
+      bucket: vi.fn().mockReturnValue(mockBucket),
+      getBuckets: vi.fn().mockResolvedValue([[{ name: bucketName }]]),
+      createBucket: vi.fn().mockResolvedValue([mockBucket]),
+    };
+    mockStorage.mockReturnValue(mockStorageInstance as unknown as Storage);
+
+    mockUuidv4.mockReturnValue('test-uuid');
+    mockSetTargetDir.mockReturnValue('/tmp/workdir');
+    mockGetPersistedState.mockReturnValue({
+      _agentSettings: {},
+      _taskState: 'submitted',
+    });
+    (fse.pathExists as Mock).mockResolvedValue(true);
+    fsMocks.readdir.mockResolvedValue(['file1.txt']);
+    mockFse.remove.mockResolvedValue(undefined);
+    mockFse.ensureDir.mockResolvedValue(undefined);
+    mockGzipSync.mockReturnValue(Buffer.from('compressed'));
+    mockGunzipSync.mockReturnValue(Buffer.from('{}'));
+    mockCreateReadStream.mockReturnValue({ on: vi.fn(), pipe: vi.fn() });
+    mockFse.createReadStream.mockReturnValue({
+      on: vi.fn(),
+      pipe: vi.fn(),
+    } as unknown as import('node:fs').ReadStream);
+  });
+
+  describe('Constructor & Initialization', () => {
+    it('should initialize and check bucket existence', async () => {
+      const store = new GCSTaskStore(bucketName);
+      await store['ensureBucketInitialized']();
+      expect(mockStorage).toHaveBeenCalledTimes(1);
+      expect(mockStorageInstance.getBuckets).toHaveBeenCalled();
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Bucket test-bucket exists'),
+      );
+    });
+
+    it('should create bucket if it does not exist', async () => {
+      mockStorageInstance.getBuckets.mockResolvedValue([[]]);
+      const store = new GCSTaskStore(bucketName);
+      await store['ensureBucketInitialized']();
+      expect(mockStorageInstance.createBucket).toHaveBeenCalledWith(bucketName);
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('Bucket test-bucket created successfully'),
+      );
+    });
+
+    it('should throw if bucket creation fails', async () => {
+      mockStorageInstance.getBuckets.mockResolvedValue([[]]);
+      mockStorageInstance.createBucket.mockRejectedValue(
+        new Error('Create failed'),
+      );
+      const store = new GCSTaskStore(bucketName);
+      await expect(store['ensureBucketInitialized']()).rejects.toThrow(
+        'Failed to create GCS bucket test-bucket: Error: Create failed',
+      );
+    });
+  });
+
+  describe('save', () => {
+    const mockTask: SDKTask = {
+      id: 'task1',
+      contextId: 'ctx1',
+      kind: 'task',
+      status: { state: 'working' },
+      metadata: {},
+    };
+
+    it('should save metadata and workspace', async () => {
+      const store = new GCSTaskStore(bucketName);
+      await store.save(mockTask);
+
+      expect(mockFile.save).toHaveBeenCalledTimes(1);
+      expect(mockTar.c).toHaveBeenCalledTimes(1);
+      expect(mockFse.remove).toHaveBeenCalledTimes(1);
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('metadata saved to GCS'),
+      );
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('workspace saved to GCS'),
+      );
+    });
+
+    it('should handle tar creation failure', async () => {
+      mockFse.pathExists.mockImplementation(
+        async (path) =>
+          !path.toString().includes('task-task1-workspace-test-uuid.tar.gz'),
+      );
+      const store = new GCSTaskStore(bucketName);
+      await expect(store.save(mockTask)).rejects.toThrow(
+        'tar.c command failed to create',
+      );
+    });
+
+    it('should throw an error if taskId contains path traversal sequences', async () => {
+      const store = new GCSTaskStore('test-bucket');
+      const maliciousTask: SDKTask = {
+        id: '../../../malicious-task',
+        metadata: {
+          _internal: {
+            agentSettings: {
+              cacheDir: '/tmp/cache',
+              dataDir: '/tmp/data',
+              logDir: '/tmp/logs',
+              tempDir: '/tmp/temp',
+            },
+            taskState: 'working',
+          },
+        },
+        kind: 'task',
+        status: {
+          state: 'working',
+          timestamp: new Date().toISOString(),
+        },
+        contextId: 'test-context',
+        history: [],
+        artifacts: [],
+      };
+      await expect(store.save(maliciousTask)).rejects.toThrow(
+        'Invalid taskId: ../../../malicious-task',
+      );
+    });
+  });
+
+  describe('load', () => {
+    it('should load task metadata and workspace', async () => {
+      mockGunzipSync.mockReturnValue(
+        Buffer.from(
+          JSON.stringify({
+            [TEST_METADATA_KEY]: {
+              _agentSettings: {},
+              _taskState: 'submitted',
+            },
+            _contextId: 'ctx1',
+          }),
+        ),
+      );
+      mockFile.download.mockResolvedValue([Buffer.from('compressed metadata')]);
+      mockFile.download.mockResolvedValueOnce([
+        Buffer.from('compressed metadata'),
+      ]);
+      mockBucket.file = vi.fn((path) => {
+        const newMockFile = { ...mockFile };
+        if (path.includes('metadata')) {
+          newMockFile.download = vi
+            .fn()
+            .mockResolvedValue([Buffer.from('compressed metadata')]);
+          newMockFile.exists = vi.fn().mockResolvedValue([true]);
+        } else {
+          newMockFile.download = vi
+            .fn()
+            .mockResolvedValue([Buffer.from('compressed workspace')]);
+          newMockFile.exists = vi.fn().mockResolvedValue([true]);
+        }
+        return newMockFile;
+      });
+
+      const store = new GCSTaskStore(bucketName);
+      const task = await store.load('task1');
+
+      expect(task).toBeDefined();
+      expect(task?.id).toBe('task1');
+      expect(mockBucket.file).toHaveBeenCalledWith(
+        'tasks/task1/metadata.tar.gz',
+      );
+      expect(mockBucket.file).toHaveBeenCalledWith(
+        'tasks/task1/workspace.tar.gz',
+      );
+      expect(mockTar.x).toHaveBeenCalledTimes(1);
+      expect(mockFse.remove).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return undefined if metadata not found', async () => {
+      mockFile.exists.mockResolvedValue([false]);
+      const store = new GCSTaskStore(bucketName);
+      const task = await store.load('task1');
+      expect(task).toBeUndefined();
+      expect(mockBucket.file).toHaveBeenCalledWith(
+        'tasks/task1/metadata.tar.gz',
+      );
+    });
+
+    it('should load metadata even if workspace not found', async () => {
+      mockGunzipSync.mockReturnValue(
+        Buffer.from(
+          JSON.stringify({
+            [TEST_METADATA_KEY]: {
+              _agentSettings: {},
+              _taskState: 'submitted',
+            },
+            _contextId: 'ctx1',
+          }),
+        ),
+      );
+
+      mockBucket.file = vi.fn((path) => {
+        const newMockFile = { ...mockFile };
+        if (path.includes('workspace.tar.gz')) {
+          newMockFile.exists = vi.fn().mockResolvedValue([false]);
+        } else {
+          newMockFile.exists = vi.fn().mockResolvedValue([true]);
+          newMockFile.download = vi
+            .fn()
+            .mockResolvedValue([Buffer.from('compressed metadata')]);
+        }
+        return newMockFile;
+      });
+
+      const store = new GCSTaskStore(bucketName);
+      const task = await store.load('task1');
+
+      expect(task).toBeDefined();
+      expect(mockTar.x).not.toHaveBeenCalled();
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('workspace archive not found'),
+      );
+    });
+  });
+
+  it('should throw an error if taskId contains path traversal sequences', async () => {
+    const store = new GCSTaskStore('test-bucket');
+    const maliciousTaskId = '../../../malicious-task';
+    await expect(store.load(maliciousTaskId)).rejects.toThrow(
+      `Invalid taskId: ${maliciousTaskId}`,
+    );
+  });
+});
+
+describe('NoOpTaskStore', () => {
+  let realStore: TaskStore;
+  let noOpStore: NoOpTaskStore;
+
+  beforeEach(() => {
+    // Create a mock of the real store to delegate to
+    realStore = {
+      save: vi.fn(),
+      load: vi.fn().mockResolvedValue({ id: 'task-123' } as SDKTask),
+    };
+    noOpStore = new NoOpTaskStore(realStore);
+  });
+
+  it("should not call the real store's save method", async () => {
+    const mockTask: SDKTask = { id: 'test-task' } as SDKTask;
+    await noOpStore.save(mockTask);
+    expect(realStore.save).not.toHaveBeenCalled();
+  });
+
+  it('should delegate the load method to the real store', async () => {
+    const taskId = 'task-123';
+    const result = await noOpStore.load(taskId);
+    expect(realStore.load).toHaveBeenCalledWith(taskId);
+    expect(result).toBeDefined();
+    expect(result?.id).toBe(taskId);
+  });
+});

packages/a2a-server/src/persistence/gcs.ts

@@ -0,0 +1,319 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Storage } from '@google-cloud/storage';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import * as tar from 'tar';
+import * as fse from 'fs-extra';
+import { promises as fsPromises, createReadStream } from 'node:fs';
+import { tmpdir } from '@google/gemini-cli-core';
+import { join } from 'node:path';
+import type { Task as SDKTask } from '@a2a-js/sdk';
+import type { TaskStore } from '@a2a-js/sdk/server';
+import { logger } from '../utils/logger.js';
+import { setTargetDir } from '../config/config.js';
+import { getPersistedState, type PersistedTaskMetadata } from '../types.js';
+import { v4 as uuidv4 } from 'uuid';
+
+type ObjectType = 'metadata' | 'workspace';
+
+const getTmpArchiveFilename = (taskId: string): string =>
+  `task-${taskId}-workspace-${uuidv4()}.tar.gz`;
+
+// Validate the taskId to prevent path traversal attacks by ensuring it only contains safe characters.
+const isTaskIdValid = (taskId: string): boolean => {
+  // Allow only alphanumeric characters, dashes, and underscores, and ensure it's not empty.
+  const validTaskIdRegex = /^[a-zA-Z0-9_-]+$/;
+  return validTaskIdRegex.test(taskId);
+};
+
+export class GCSTaskStore implements TaskStore {
+  private storage: Storage;
+  private bucketName: string;
+  private bucketInitialized: Promise<void>;
+
+  constructor(bucketName: string) {
+    if (!bucketName) {
+      throw new Error('GCS bucket name is required.');
+    }
+    this.storage = new Storage();
+    this.bucketName = bucketName;
+    logger.info(`GCSTaskStore initializing with bucket: ${this.bucketName}`);
+    // Prerequisites: user account or service account must have storage admin IAM role
+    // and the bucket name must be unique.
+    this.bucketInitialized = this.initializeBucket();
+  }
+
+  private async initializeBucket(): Promise<void> {
+    try {
+      const [buckets] = await this.storage.getBuckets();
+      const exists = buckets.some((bucket) => bucket.name === this.bucketName);
+
+      if (!exists) {
+        logger.info(
+          `Bucket ${this.bucketName} does not exist in the list. Attempting to create...`,
+        );
+        try {
+          await this.storage.createBucket(this.bucketName);
+          logger.info(`Bucket ${this.bucketName} created successfully.`);
+        } catch (createError) {
+          logger.info(
+            `Failed to create bucket ${this.bucketName}: ${createError}`,
+          );
+          throw new Error(
+            `Failed to create GCS bucket ${this.bucketName}: ${createError}`,
+          );
+        }
+      } else {
+        logger.info(`Bucket ${this.bucketName} exists.`);
+      }
+    } catch (error) {
+      logger.info(
+        `Error during bucket initialization for ${this.bucketName}: ${error}`,
+      );
+      throw new Error(
+        `Failed to initialize GCS bucket ${this.bucketName}: ${error}`,
+      );
+    }
+  }
+
+  private async ensureBucketInitialized(): Promise<void> {
+    await this.bucketInitialized;
+  }
+
+  private getObjectPath(taskId: string, type: ObjectType): string {
+    if (!isTaskIdValid(taskId)) {
+      throw new Error(`Invalid taskId: ${taskId}`);
+    }
+    return `tasks/${taskId}/${type}.tar.gz`;
+  }
+
+  async save(task: SDKTask): Promise<void> {
+    await this.ensureBucketInitialized();
+    const taskId = task.id;
+    const persistedState = getPersistedState(
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      task.metadata as PersistedTaskMetadata,
+    );
+
+    if (!persistedState) {
+      throw new Error(`Task ${taskId} is missing persisted state in metadata.`);
+    }
+    const workDir = process.cwd();
+
+    const metadataObjectPath = this.getObjectPath(taskId, 'metadata');
+    const workspaceObjectPath = this.getObjectPath(taskId, 'workspace');
+
+    const dataToStore = task.metadata;
+
+    try {
+      const jsonString = JSON.stringify(dataToStore);
+      const compressedMetadata = gzipSync(Buffer.from(jsonString));
+      const metadataFile = this.storage
+        .bucket(this.bucketName)
+        .file(metadataObjectPath);
+      await metadataFile.save(compressedMetadata, {
+        contentType: 'application/gzip',
+      });
+      logger.info(
+        `Task ${taskId} metadata saved to GCS: gs://${this.bucketName}/${metadataObjectPath}`,
+      );
+
+      if (await fse.pathExists(workDir)) {
+        const entries = await fsPromises.readdir(workDir);
+        if (entries.length > 0) {
+          const tmpArchiveFile = join(tmpdir(), getTmpArchiveFilename(taskId));
+          try {
+            await tar.c(
+              {
+                gzip: true,
+                file: tmpArchiveFile,
+                cwd: workDir,
+                portable: true,
+              },
+              entries,
+            );
+
+            if (!(await fse.pathExists(tmpArchiveFile))) {
+              throw new Error(
+                `tar.c command failed to create ${tmpArchiveFile}`,
+              );
+            }
+
+            const workspaceFile = this.storage
+              .bucket(this.bucketName)
+              .file(workspaceObjectPath);
+            const sourceStream = createReadStream(tmpArchiveFile);
+            const destStream = workspaceFile.createWriteStream({
+              contentType: 'application/gzip',
+              resumable: true,
+            });
+
+            await new Promise<void>((resolve, reject) => {
+              sourceStream.on('error', (err) => {
+                logger.error(
+                  `Error in source stream for ${tmpArchiveFile}:`,
+                  err,
+                );
+                // Attempt to close destStream if source fails
+                if (!destStream.destroyed) {
+                  destStream.destroy(err);
+                }
+                reject(err);
+              });
+
+              destStream.on('error', (err) => {
+                logger.error(
+                  `Error in GCS dest stream for ${workspaceObjectPath}:`,
+                  err,
+                );
+                reject(err);
+              });
+
+              destStream.on('finish', () => {
+                logger.info(
+                  `GCS destStream finished for ${workspaceObjectPath}`,
+                );
+                resolve();
+              });
+
+              logger.info(
+                `Piping ${tmpArchiveFile} to GCS object ${workspaceObjectPath}`,
+              );
+              sourceStream.pipe(destStream);
+            });
+            logger.info(
+              `Task ${taskId} workspace saved to GCS: gs://${this.bucketName}/${workspaceObjectPath}`,
+            );
+          } catch (error) {
+            logger.error(
+              `Error during workspace save process for ${taskId}:`,
+              error,
+            );
+            throw error;
+          } finally {
+            logger.info(`Cleaning up temporary file: ${tmpArchiveFile}`);
+            try {
+              if (await fse.pathExists(tmpArchiveFile)) {
+                await fse.remove(tmpArchiveFile);
+                logger.info(
+                  `Successfully removed temporary file: ${tmpArchiveFile}`,
+                );
+              } else {
+                logger.warn(
+                  `Temporary file not found for cleanup: ${tmpArchiveFile}`,
+                );
+              }
+            } catch (removeError) {
+              logger.error(
+                `Error removing temporary file ${tmpArchiveFile}:`,
+                removeError,
+              );
+            }
+          }
+        } else {
+          logger.info(
+            `Workspace directory ${workDir} is empty, skipping workspace save for task ${taskId}.`,
+          );
+        }
+      } else {
+        logger.info(
+          `Workspace directory ${workDir} not found, skipping workspace save for task ${taskId}.`,
+        );
+      }
+    } catch (error) {
+      logger.error(`Failed to save task ${taskId} to GCS:`, error);
+      throw error;
+    }
+  }
+
+  async load(taskId: string): Promise<SDKTask | undefined> {
+    await this.ensureBucketInitialized();
+    const metadataObjectPath = this.getObjectPath(taskId, 'metadata');
+    const workspaceObjectPath = this.getObjectPath(taskId, 'workspace');
+
+    try {
+      const metadataFile = this.storage
+        .bucket(this.bucketName)
+        .file(metadataObjectPath);
+      const [metadataExists] = await metadataFile.exists();
+      if (!metadataExists) {
+        logger.info(`Task ${taskId} metadata not found in GCS.`);
+        return undefined;
+      }
+      const [compressedMetadata] = await metadataFile.download();
+      const jsonData = gunzipSync(compressedMetadata).toString();
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const loadedMetadata = JSON.parse(jsonData);
+      logger.info(`Task ${taskId} metadata loaded from GCS.`);
+
+      const persistedState = getPersistedState(loadedMetadata);
+      if (!persistedState) {
+        throw new Error(
+          `Loaded metadata for task ${taskId} is missing internal persisted state.`,
+        );
+      }
+      const agentSettings = persistedState._agentSettings;
+
+      const workDir = setTargetDir(agentSettings);
+      await fse.ensureDir(workDir);
+      const workspaceFile = this.storage
+        .bucket(this.bucketName)
+        .file(workspaceObjectPath);
+      const [workspaceExists] = await workspaceFile.exists();
+      if (workspaceExists) {
+        const tmpArchiveFile = join(tmpdir(), getTmpArchiveFilename(taskId));
+        try {
+          await workspaceFile.download({ destination: tmpArchiveFile });
+          await tar.x({ file: tmpArchiveFile, cwd: workDir });
+          logger.info(
+            `Task ${taskId} workspace restored from GCS to ${workDir}`,
+          );
+        } finally {
+          if (await fse.pathExists(tmpArchiveFile)) {
+            await fse.remove(tmpArchiveFile);
+          }
+        }
+      } else {
+        logger.info(`Task ${taskId} workspace archive not found in GCS.`);
+      }
+
+      return {
+        id: taskId,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        contextId: loadedMetadata._contextId || uuidv4(),
+        kind: 'task',
+        status: {
+          state: persistedState._taskState,
+          timestamp: new Date().toISOString(),
+        },
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        metadata: loadedMetadata,
+        history: [],
+        artifacts: [],
+      };
+    } catch (error) {
+      logger.error(`Failed to load task ${taskId} from GCS:`, error);
+      throw error;
+    }
+  }
+}
+
+export class NoOpTaskStore implements TaskStore {
+  constructor(private realStore: TaskStore) {}
+
+  async save(task: SDKTask): Promise<void> {
+    logger.info(`[NoOpTaskStore] save called for task ${task.id} - IGNORED`);
+    return Promise.resolve();
+  }
+
+  async load(taskId: string): Promise<SDKTask | undefined> {
+    logger.info(
+      `[NoOpTaskStore] load called for task ${taskId}, delegating to real store.`,
+    );
+    return this.realStore.load(taskId);
+  }
+}

packages/a2a-server/src/types.ts

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  MCPServerStatus,
+  ToolConfirmationOutcome,
+} from '@google/gemini-cli-core';
+import type { TaskState } from '@a2a-js/sdk';
+
+// Interfaces and enums for the CoderAgent protocol.
+
+export enum CoderAgentEvent {
+  /**
+   * An event requesting one or more tool call confirmations.
+   */
+  ToolCallConfirmationEvent = 'tool-call-confirmation',
+  /**
+   * An event updating on the status of one or more tool calls.
+   */
+  ToolCallUpdateEvent = 'tool-call-update',
+  /**
+   * An event providing text updates on the task.
+   */
+  TextContentEvent = 'text-content',
+  /**
+   * An event that indicates a change in the task's execution state.
+   */
+  StateChangeEvent = 'state-change',
+  /**
+   * An user-sent event to initiate the agent.
+   */
+  StateAgentSettingsEvent = 'agent-settings',
+  /**
+   * An event that contains a thought from the agent.
+   */
+  ThoughtEvent = 'thought',
+  /**
+   * An event that contains citation from the agent.
+   */
+  CitationEvent = 'citation',
+}
+
+export interface AgentSettings {
+  kind: CoderAgentEvent.StateAgentSettingsEvent;
+  workspacePath: string;
+  autoExecute?: boolean;
+  isTrusted?: boolean;
+}
+
+export interface ToolCallConfirmation {
+  kind: CoderAgentEvent.ToolCallConfirmationEvent;
+}
+
+export interface ToolCallUpdate {
+  kind: CoderAgentEvent.ToolCallUpdateEvent;
+}
+
+export interface TextContent {
+  kind: CoderAgentEvent.TextContentEvent;
+}
+
+export interface StateChange {
+  kind: CoderAgentEvent.StateChangeEvent;
+}
+
+export interface Thought {
+  kind: CoderAgentEvent.ThoughtEvent;
+}
+
+export interface Citation {
+  kind: CoderAgentEvent.CitationEvent;
+}
+
+export type ThoughtSummary = {
+  subject: string;
+  description: string;
+};
+
+export interface ToolConfirmationResponse {
+  outcome: ToolConfirmationOutcome;
+  callId: string;
+}
+
+export type CoderAgentMessage =
+  | AgentSettings
+  | ToolCallConfirmation
+  | ToolCallUpdate
+  | TextContent
+  | StateChange
+  | Thought
+  | Citation;
+
+export interface TaskMetadata {
+  id: string;
+  contextId: string;
+  taskState: TaskState;
+  model: string;
+  mcpServers: Array<{
+    name: string;
+    status: MCPServerStatus;
+    tools: Array<{
+      name: string;
+      description: string;
+      parameterSchema: unknown;
+    }>;
+  }>;
+  availableTools: Array<{
+    name: string;
+    description: string;
+    parameterSchema: unknown;
+  }>;
+}
+
+export interface PersistedStateMetadata {
+  _agentSettings: AgentSettings;
+  _taskState: TaskState;
+}
+
+export type PersistedTaskMetadata = { [k: string]: unknown };
+
+export const METADATA_KEY = '__persistedState';
+
+function isAgentSettings(value: unknown): value is AgentSettings {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'kind' in value &&
+    value.kind === CoderAgentEvent.StateAgentSettingsEvent &&
+    'workspacePath' in value &&
+    typeof value.workspacePath === 'string'
+  );
+}
+
+function isPersistedStateMetadata(
+  value: unknown,
+): value is PersistedStateMetadata {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '_agentSettings' in value &&
+    '_taskState' in value &&
+    isAgentSettings(value._agentSettings)
+  );
+}
+
+export function getPersistedState(
+  metadata: PersistedTaskMetadata,
+): PersistedStateMetadata | undefined {
+  const state = metadata?.[METADATA_KEY];
+  if (isPersistedStateMetadata(state)) {
+    return state;
+  }
+  return undefined;
+}
+
+export function getContextIdFromMetadata(
+  metadata: PersistedTaskMetadata | undefined,
+): string | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+  const contextId = metadata['_contextId'];
+  return typeof contextId === 'string' ? contextId : undefined;
+}
+
+export function getAgentSettingsFromMetadata(
+  metadata: PersistedTaskMetadata | undefined,
+): AgentSettings | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+  const coderAgent = metadata['coderAgent'];
+  if (isAgentSettings(coderAgent)) {
+    return coderAgent;
+  }
+  return undefined;
+}
+
+export function setPersistedState(
+  metadata: PersistedTaskMetadata,
+  state: PersistedStateMetadata,
+): PersistedTaskMetadata {
+  return {
+    ...metadata,
+    [METADATA_KEY]: state,
+  };
+}

packages/a2a-server/src/utils/executor_utils.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Message } from '@a2a-js/sdk';
+import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import { v4 as uuidv4 } from 'uuid';
+
+import { CoderAgentEvent, type StateChange } from '../types.js';
+
+export async function pushTaskStateFailed(
+  error: unknown,
+  eventBus: ExecutionEventBus,
+  taskId: string,
+  contextId: string,
+) {
+  const errorMessage =
+    error instanceof Error ? error.message : 'Agent execution error';
+  const stateChange: StateChange = {
+    kind: CoderAgentEvent.StateChangeEvent,
+  };
+  eventBus.publish({
+    kind: 'status-update',
+    taskId,
+    contextId,
+    status: {
+      state: 'failed',
+      message: {
+        kind: 'message',
+        role: 'agent',
+        parts: [
+          {
+            kind: 'text',
+            text: errorMessage,
+          },
+        ],
+        messageId: uuidv4(),
+        taskId,
+        contextId,
+      } as Message,
+    },
+    final: true,
+    metadata: {
+      coderAgent: stateChange,
+      model: 'unknown',
+      error: errorMessage,
+    },
+  });
+}

packages/a2a-server/src/utils/logger.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    // First, add a timestamp to the log info object
+    winston.format.timestamp({
+      format: 'YYYY-MM-DD HH:mm:ss.SSS A', // Custom timestamp format
+    }),
+    // Here we define the custom output format
+    winston.format.printf((info) => {
+      const { level, timestamp, message, ...rest } = info;
+      return (
+        `[${level.toUpperCase()}] ${timestamp} -- ${message}` +
+        `${Object.keys(rest).length > 0 ? `\n${JSON.stringify(rest, null, 2)}` : ''}`
+      ); // Only print ...rest if present
+    }),
+  ),
+  transports: [new winston.transports.Console()],
+});
+
+export { logger };

packages/a2a-server/src/utils/testing_utils.ts

@@ -0,0 +1,233 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as path from 'node:path';
+import type {
+  Task as SDKTask,
+  TaskStatusUpdateEvent,
+  SendStreamingMessageSuccessResponse,
+} from '@a2a-js/sdk';
+import {
+  ApprovalMode,
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
+  GeminiClient,
+  HookSystem,
+  type MessageBus,
+  PolicyDecision,
+  tmpdir,
+  type Config,
+  type Storage,
+  NoopSandboxManager,
+  type ToolRegistry,
+  type SandboxManager,
+} from '@google/gemini-cli-core';
+import { createMockMessageBus } from '@google/gemini-cli-core/src/test-utils/mock-message-bus.js';
+import { expect, vi } from 'vitest';
+
+export function createMockConfig(
+  overrides: Partial<Config> = {},
+): Partial<Config> {
+  const tmpDir = tmpdir();
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const mockConfig = {
+    get config() {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return this as unknown as Config;
+    },
+    get toolRegistry() {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      const config = this as unknown as Config;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return config.getToolRegistry?.() as unknown as ToolRegistry;
+    },
+    get messageBus() {
+      return (
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        (this as unknown as Config).getMessageBus?.() as unknown as MessageBus
+      );
+    },
+    get geminiClient() {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      const config = this as unknown as Config;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return config.getGeminiClient?.() as unknown as GeminiClient;
+    },
+    getToolRegistry: vi.fn().mockReturnValue({
+      getTool: vi.fn(),
+      getAllToolNames: vi.fn().mockReturnValue([]),
+      getAllTools: vi.fn().mockReturnValue([]),
+      getToolsByServer: vi.fn().mockReturnValue([]),
+    }),
+    getApprovalMode: vi.fn().mockReturnValue(ApprovalMode.DEFAULT),
+    getIdeMode: vi.fn().mockReturnValue(false),
+    isInteractive: () => true,
+    getAllowedTools: vi.fn().mockReturnValue([]),
+    getWorkspaceContext: vi.fn().mockReturnValue({
+      isPathWithinWorkspace: () => true,
+    }),
+    getTargetDir: () => tmpDir,
+    getCheckpointingEnabled: vi.fn().mockReturnValue(false),
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    storage: {
+      getProjectTempDir: () => tmpDir,
+      getProjectTempCheckpointsDir: () => path.join(tmpDir, 'checkpoints'),
+    } as Storage,
+    getTruncateToolOutputThreshold: () =>
+      DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
+    getActiveModel: vi.fn().mockReturnValue(DEFAULT_GEMINI_MODEL),
+    getDebugMode: vi.fn().mockReturnValue(false),
+    getContentGeneratorConfig: vi.fn().mockReturnValue({ model: 'gemini-pro' }),
+    getModel: vi.fn().mockReturnValue('gemini-pro'),
+    getUsageStatisticsEnabled: vi.fn().mockReturnValue(false),
+    setFallbackModelHandler: vi.fn(),
+    initialize: vi.fn().mockResolvedValue(undefined),
+    getProxy: vi.fn().mockReturnValue(undefined),
+    getHistory: vi.fn().mockReturnValue([]),
+    getEmbeddingModel: vi.fn().mockReturnValue('text-embedding-004'),
+    getSessionId: vi.fn().mockReturnValue('test-session-id'),
+    getUserTier: vi.fn(),
+    getMessageBus: vi.fn(),
+    getPolicyEngine: vi.fn(),
+    getEnableExtensionReloading: vi.fn().mockReturnValue(false),
+    getEnableHooks: vi.fn().mockReturnValue(false),
+    getMcpClientManager: vi.fn().mockReturnValue({
+      getMcpServers: vi.fn().mockReturnValue({}),
+    }),
+    getTelemetryLogPromptsEnabled: vi.fn().mockReturnValue(false),
+    getTelemetryTracesEnabled: vi.fn().mockReturnValue(false),
+    getGitService: vi.fn(),
+    validatePathAccess: vi.fn().mockReturnValue(undefined),
+    getShellExecutionConfig: vi.fn().mockReturnValue({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      sandboxManager: new NoopSandboxManager() as unknown as SandboxManager,
+      sanitizationConfig: {
+        allowedEnvironmentVariables: [],
+        blockedEnvironmentVariables: [],
+        enableEnvironmentVariableRedaction: false,
+      },
+    }),
+    isContextManagementEnabled: vi.fn().mockReturnValue(false),
+    getContextManagementConfig: vi.fn().mockReturnValue({ enabled: false }),
+    getExperimentalGemma: vi.fn().mockReturnValue(false),
+    ...overrides,
+  } as unknown as Config;
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  (mockConfig as unknown as { config: Config; promptId: string }).promptId =
+    'test-prompt-id';
+
+  mockConfig.getMessageBus = vi.fn().mockReturnValue(createMockMessageBus());
+  mockConfig.getHookSystem = vi
+    .fn()
+    .mockReturnValue(new HookSystem(mockConfig));
+
+  mockConfig.getGeminiClient = vi
+    .fn()
+    .mockReturnValue(new GeminiClient(mockConfig));
+
+  mockConfig.getPolicyEngine = vi.fn().mockReturnValue({
+    check: async () => {
+      const mode = mockConfig.getApprovalMode();
+      if (mode === ApprovalMode.YOLO) {
+        return { decision: PolicyDecision.ALLOW };
+      }
+      return { decision: PolicyDecision.ASK_USER };
+    },
+  });
+
+  return mockConfig;
+}
+
+export function createStreamMessageRequest(
+  text: string,
+  messageId: string,
+  taskId?: string,
+) {
+  const request: {
+    jsonrpc: string;
+    id: string;
+    method: string;
+    params: {
+      message: {
+        kind: string;
+        role: string;
+        parts: [{ kind: string; text: string }];
+        messageId: string;
+      };
+      metadata: {
+        coderAgent: {
+          kind: string;
+          workspacePath: string;
+        };
+      };
+      taskId?: string;
+    };
+  } = {
+    jsonrpc: '2.0',
+    id: '1',
+    method: 'message/stream',
+    params: {
+      message: {
+        kind: 'message',
+        role: 'user',
+        parts: [{ kind: 'text', text }],
+        messageId,
+      },
+      metadata: {
+        coderAgent: {
+          kind: 'agent-settings',
+          workspacePath: '/tmp',
+        },
+      },
+    },
+  };
+
+  if (taskId) {
+    request.params.taskId = taskId;
+  }
+
+  return request;
+}
+
+export function assertUniqueFinalEventIsLast(
+  events: SendStreamingMessageSuccessResponse[],
+) {
+  // Final event is input-required & final
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const finalEvent = events[events.length - 1].result as TaskStatusUpdateEvent;
+  expect(finalEvent.metadata?.['coderAgent']).toMatchObject({
+    kind: 'state-change',
+  });
+  expect(finalEvent.status?.state).toBe('input-required');
+  expect(finalEvent.final).toBe(true);
+
+  // There is only one event with final and its the last
+  expect(
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    events.filter((e) => (e.result as TaskStatusUpdateEvent).final).length,
+  ).toBe(1);
+  expect(
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    events.findIndex((e) => (e.result as TaskStatusUpdateEvent).final),
+  ).toBe(events.length - 1);
+}
+
+export function assertTaskCreationAndWorkingStatus(
+  events: SendStreamingMessageSuccessResponse[],
+) {
+  // Initial task creation event
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const taskEvent = events[0].result as SDKTask;
+  expect(taskEvent.kind).toBe('task');
+  expect(taskEvent.status.state).toBe('submitted');
+
+  // Status update: working
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const workingEvent = events[1].result as TaskStatusUpdateEvent;
+  expect(workingEvent.kind).toBe('status-update');
+  expect(workingEvent.status.state).toBe('working');
+}

packages/a2a-server/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "composite": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["index.ts", "src/**/*.ts", "src/**/*.json"],
+  "exclude": ["node_modules", "dist"]
+}

packages/a2a-server/vitest.config.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/// <reference types="vitest" />
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['**/*.{test,spec}.?(c|m)[jt]s?(x)'],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    globals: true,
+    reporters: ['default', 'junit'],
+    silent: true,
+    outputFile: {
+      junit: 'junit.xml',
+    },
+    coverage: {
+      enabled: true,
+      provider: 'v8',
+      reportsDirectory: './coverage',
+      include: ['src/**/*'],
+      reporter: [
+        ['text', { file: 'full-text-summary.txt' }],
+        'html',
+        'json',
+        'lcov',
+        'cobertura',
+        ['json-summary', { outputFile: 'coverage-summary.json' }],
+      ],
+    },
+    poolOptions: {
+      threads: {
+        minThreads: 8,
+        maxThreads: 16,
+      },
+    },
+    server: {
+      deps: {
+        inline: [/@google\/gemini-cli-core/],
+      },
+    },
+  },
+});