a2a-server persistence should be A2A compliant

[sammccauley117]

What would you like to be added?

a2a-server persistence should be updated to be A2A compliant and enable associating multiple tasks with individual context IDs.

Why is this needed?

A2A states that "a contextId is a crucial identifier that logically groups multiple Task objects". However, the current implementation of task v. context is convoluted. The current persistence model has tasks being stored as a directory in tasks/{taskId}/ and the metadata which contains the context ID is stored within that directory. This makes it infeasible to group multiple tasks.

Additional context

Currently, the file structure is like so:

tasks/
├── task-01/
│   ├── metadata.tar.gz
│   └── workspace.tar.gz
├── task-02/
│   ├── metadata.tar.gz
│   └── workspace.tar.gz
└── task-03/
    ├── metadata.tar.gz
    └── workspace.tar.gz

[gemini-cli]

This is a feature enhancement request to make the a2a-server persistence model compliant with the A2A protocol. It belongs to the background area as it deals with the task persistence mechanism. No priority label was applied as none were available in the provided list.

[sammccauley117]

Proposal: Rearchitecting the A2A Server Persistence Layer

Executive Summary

The current A2A server persistence layer is not scalable, compliant with the A2A specification, or easy to maintain. It lacks the concept of a contextId for grouping tasks, uses an inefficient storage format, and bypasses the A2A SDK's intended state management flow.

This proposal outlines a new architecture centered around two key decisions:

1. Enforce Linear Task Execution: For our initial implementation, we will simplify the agent's logic by allowing only one active task at a time within a given context. A new task can only begin after the previous one has completed, creating a single, linear history.
2. Adopt a Scalable GCS Layout: We will implement a GCS structure that uses a file-based index to efficiently map tasks to contexts, allowing for both fast lookups and logical grouping of all related data.

This rearchitecting will result in a robust, scalable, and A2A-compliant persistence layer that provides a solid foundation for future features.

Core Architectural Decisions

Linear Task Execution

The A2A specification allows for parallel tasks within a single context, which creates significant complexity in determining which workspace state a new task should inherit. To de-risk the initial implementation, we will enforce a strictly linear history.

• Rule: A new task will always resume from the workspace of the most recently completed task in the context.
• Enforcement: The agent will reject any attempt to start a new task if another task in the same context is already in a non-terminal state (e.g., working). However, sending a message that continues an existing task currently in an input-required state is a valid and required part of the linear workflow.
• Benefit: This eliminates ambiguity and dramatically simplifies state management for both the agent and the client. Support for parallel tasks can be added in a future release.

GCS Persistence Model

We will adopt a context-partitioned GCS layout that separates the index from the data.

Current Layout (Problematic)

The current flat layout prevents grouping tasks by context.

gs://<your-bucket-name>/
└─── tasks/
     └─── <taskId_A>/
          ├─── metadata.tar.gz
          └─── workspace.tar.gz

Proposed Layout (Solution)

This new layout provides a scalable index and logical data grouping.

gs://<your-bucket-name>/
│
├─── tasks/  (Index)
│    └─── <taskId_A>/
│         └─── contextId.txt   (Content: "contextId_1")
│
└─── contexts/  (Data Store)
     └─── <contextId_1>/
          └─── <taskId_A>/
               ├─── task.json  (Standard A2A Task object)
               └─── workspace.tar.gz

Problem Analysis: Key Issues Identified

Issue 1: Incorrect Persistence Layout & No Indexing

• Current State: The GCSTaskStore saves everything under a flat tasks/<taskId>/ directory structure in the GCS bucket.
• Problem: This is the most critical issue. It completely ignores the contextId. There is no way to group related tasks, making it impossible to efficiently reconstruct a conversation or trace the evolution of a workspace across multiple steps. The load(taskId) method can only work because it doesn't need the contextId for its simple path, but this fundamentally breaks the A2A model of contextual interaction.

Issue 2: Inefficient and Non-Standard Data Format

• Current State: The GCSTaskStore saves the task's metadata as a gzipped tarball (metadata.tar.gz).
• Problem: This is unnecessary and inefficient. The metadata is a single JSON object. Tarring a single file adds overhead with no benefit. The standard and most efficient way to store this is as a single JSON object (task.json), which can be read directly without requiring a tar extraction step.

Issue 3: State Management Mismatch & Non-Standard Persistence

• Current State: The CoderAgentExecutor uses its own in-memory Task class, which is different from the A2A SDK's Task object. To persist, it uses a TaskWrapper to serialize its internal state into the metadata field of the SDK Task object.
• Problem: This creates a fragile, non-standard persistence format. The source of truth is an internal class structure, not the A2A Task object itself. The load method in GCSTaskStore only reconstructs a minimal SDKTask shell, not the full, rich object with history and artifacts as defined by the A2A spec. This breaks the principle that the persisted Task should be the complete and canonical record of the interaction.

Issue 4: Bypassed A2A State Management

• Current State: In app.ts, the DefaultRequestHandler (from the A2A SDK) is initialized with a NoOpTaskStore. This special store intentionally prevents the A2A handler from saving any state. All saving is done manually inside the CoderAgentExecutor.
• Problem: This is a major architectural flaw. It fights against the A2A SDK's design. The DefaultRequestHandler is built to manage the lifecycle of tasks and interact with a TaskStore automatically. By providing a no-op store, the current implementation bypasses this, forcing the CoderAgentExecutor to reinvent state management, leading to inconsistencies.

Issue 5: Non-Standard API Endpoints

• Current State: The app.ts file defines custom endpoints like POST /tasks and GET /tasks/:taskId/metadata.
• Problem: While useful for debugging, these are not part of the A2A specification. A compliant A2A client would not know how to use them. Tasks should be created via the standard message/send or message/stream A2A methods. Relying on these custom endpoints creates a second, non-standard way of interacting with the agent.

Rearchitecting Plan

The implementation will involve replacing the existing GCSTaskStore and realigning the application to use the A2A SDK's state management capabilities correctly.

1. Implement the New GCSTaskStore: The new store will implement the proposed GCS layout.

   • save(task) will write the task.json, workspace.tar.gz, and the contextId.txt pointer file.
   • load(taskId) will use the pointer file to find the context, then load the task data and workspace.

2. Integrate with A2A SDK:

   • The NoOpTaskStore will be removed. A single instance of the new GCSTaskStore will be passed to both the DefaultRequestHandler and the CoderAgentExecutor.
   • This allows the A2A SDK to manage the task lifecycle and persistence as intended.

3. Simplify CoderAgentExecutor:

   • The TaskWrapper and custom metadata persistence logic will be removed.
   • The executor's responsibility will be simplified to performing the agent's work and emitting events. It will receive state via the RequestContext and will no longer directly manage persistence.

4. Standardize API:

   • The non-standard POST /tasks and GET /tasks/... endpoints will be removed. All client interaction will occur through the standard A2A methods (message/send, message/stream, etc.).

Alternatives Considered

The following options were also considered as optimizations:

• Workspace Persistence Optimization: The workspace.tar.gz model is inefficient for large projects. A "Phase 2" should involve moving to a git-based persistence model, where each task is a commit in a context-specific repository. This will dramatically improve performance and reduce storage costs.
• Support for Parallel Tasks: Once the core linear model is stable, we can plan a "Phase 3" to add support for branching and parallel task execution as described in the A2A specification.
• Firestore Indexing: If the GCS-based index ever becomes a bottleneck, it can be migrated to a dedicated database like Firestore for higher performance and transactional integrity.

However, these are outside the scope of V1.

[gemini-cli]

Hello! As part of our effort to keep our backlog manageable and focus on the most active issues, we are tidying up older reports.

It looks like this issue hasn't been active for a while, so we are closing it for now. However, if you are still experiencing this bug on the latest stable build, please feel free to comment on this issue or create a new one with updated details.

Thank you for your contribution!