added missing doc comments, resolved minor interface inconsistencies, added AgentExtendedCardProducer interface

Author: yarolegovich

a2a/errors.go

@@ -17,19 +17,30 @@ package a2a
 import "errors"
 
 var (
+	// ErrTaskNotFound indicates that a task with the provided ID was not found.
 	ErrTaskNotFound = errors.New("task not found")
 
+	// ErrTaskNotCancelable indicates that the task was in a state where it could not be cancelled.
 	ErrTaskNotCancelable = errors.New("task cannot be canceled")
 
+	// ErrPushNotificationNotSupported indicates that the agent does not support push notifications.
 	ErrPushNotificationNotSupported = errors.New("push notification not supported")
 
+	// ErrUnsupportedOperation indicates that the requested operation is not supported by the agent.
 	ErrUnsupportedOperation = errors.New("this operation is not supported")
 
+	// ErrUnsupportedContentType indicates an incompatibility between the requested
+	// content types and the agent's capabilities.
 	ErrUnsupportedContentType = errors.New("incompatible content types")
 
+	// ErrInvalidAgentResponse indicates that the agent returned a response that
+	// does not conform to the specification for the current method.
 	ErrInvalidAgentResponse = errors.New("invalid agent response")
 
+	// ErrInvalidRequest indicates that the received request was invalid.
 	ErrInvalidRequest = errors.New("invalid request")
 
+	// ErrAuthenticatedExtendedCardNotConfigured indicates that the agent does not have an Authenticated
+	// Extended Card configured.
 	ErrAuthenticatedExtendedCardNotConfigured = errors.New("extended card not configured")
 )

a2a/push.go

@@ -23,8 +23,7 @@ type GetTaskPushConfigParams struct {
 	ConfigID *string
 }
 
-// Defines parameters for listing all push notification configurations associated
-// with a task.
+// Defines parameters for listing all push notification configurations associated with a task.
 type ListTaskPushConfigParams struct {
 	// The unique identifier of the task.
 	TaskID TaskID

a2asrv/agent.go

@@ -20,12 +20,36 @@ import (
 	"github.com/a2aproject/a2a-go/a2a"
 )
 
+// AgentExecutor implementations translate agent outputs to A2A events.
 type AgentExecutor interface {
-	Execute(ctx context.Context, reqCtx RequestContext, queue EventQueue) error
+	// Execute invokes an agent with the provided context and translates agent outputs
+	// into A2A events writing them to the provided event queue.
+	//
+	// Returns an error if agent invocation failed.
+	Execute(ctx context.Context, reqCtx RequestContext, queue EventWriter) error
 
-	Cancel(ctx context.Context, reqCtx RequestContext, queue EventQueue) error
+	// Cancel requests the agent to stop processing an ongoing task.
+	//
+	// The agent should attempt to gracefully stop the task identified by the
+	// task ID in the request context and publish a TaskStatusUpdateEvent with
+	// state TaskStateCanceled to the event queue.
+	//
+	// Returns an error if the cancellation request cannot be processed.
+	Cancel(ctx context.Context, reqCtx RequestContext, queue EventWriter) error
 }
 
+// AgentCardProducer creates an AgentCard instances used for agent discovery and capability negotiation.
 type AgentCardProducer interface {
+	// Card returns a self-describing manifest for an agent. It provides essential
+	// metadata including the agent's identity, capabilities, skills, supported
+	// communication methods, and security requirements and is publicly available.
 	Card() a2a.AgentCard
 }
+
+// ExtendedAgentCardProducer can create both public agent cards and cards available to authenticated users only.
+type ExtendedAgentCardProducer interface {
+	AgentCardProducer
+
+	// ExtendedCard returns a manifest for an agent which is only available to authenticated users.
+	ExtendedCard() a2a.AgentCard
+}

a2asrv/events.go

@@ -20,23 +20,37 @@ import (
 	"github.com/a2aproject/a2a-go/a2a"
 )
 
+// EventReader defines the interface for reading events from a queue.
+// A2A server stack reads events written by AgentExecutor.
 type EventReader interface {
+	// Read dequeues an event or blocks if the queue is empty.
 	Read(ctx context.Context) (a2a.Event, error)
 }
 
+// EventWriter defines the interface for writing events to a queue.
+// AgentExecutor translates agent responses to Messages, Tasks or Task update events.
 type EventWriter interface {
+	// Write enqueues an event or blocks if a bounded queue is full.
 	Write(ctx context.Context, event a2a.Event) error
 }
 
+// EventQueue defines the interface for publishing and consuming
+// events generated during agent execution.
 type EventQueue interface {
 	EventReader
 	EventWriter
 
+	// Close shuts down a connection to the queue.
 	Close()
 }
 
+// EventQueueManager manages event queues on a per-task basis.
+// It provides lifecycle management for task-specific event queues,
+// enabling multiple clients to attach to the same task's event stream.
 type EventQueueManager interface {
+	// GetOrCreate returns an existing queue if one exists, or creates a new one.
 	GetOrCreate(ctx context.Context, taskId a2a.TaskID) (EventQueue, error)
 
+	// Destroy closes the queue for the specified task and frees all associates resources.
 	Destroy(ctx context.Context, taskId a2a.TaskID) error
 }

a2asrv/handler.go

@@ -21,22 +21,32 @@ import (
 	"github.com/a2aproject/a2a-go/a2a"
 )
 
+// RequestHandler defines a transport-agnostic interface for handling incoming A2A requests.
 type RequestHandler interface {
+	// OnGetTask handles the 'tasks/get' protocol method.
 	OnGetTask(ctx context.Context, query a2a.TaskQueryParams) (a2a.Task, error)
 
+	// OnCancelTask handles the 'tasks/cancel' protocol method.
 	OnCancelTask(ctx context.Context, id a2a.TaskIDParams) (a2a.Task, error)
 
+	// OnSendMessage handles the 'message/send' protocol method (non-streaming).
 	OnSendMessage(ctx context.Context, message a2a.MessageSendParams) (a2a.SendMessageResult, error)
 
+	// OnResubscribeToTask handles the `tasks/resubscribe` protocol method.
 	OnResubscribeToTask(ctx context.Context, id a2a.TaskIDParams) iter.Seq2[a2a.Event, error]
 
+	// OnMessageSendStream handles the 'message/stream' protocol method (streaming).
 	OnSendMessageStream(ctx context.Context, message a2a.MessageSendParams) iter.Seq2[a2a.Event, error]
 
+	// OnGetTaskPushNotificationConfig handles the `tasks/pushNotificationConfig/get` protocol method.
 	OnGetTaskPushConfig(ctx context.Context, params a2a.GetTaskPushConfigParams) (a2a.TaskPushConfig, error)
 
+	// OnListTaskPushNotificationConfig handles the `tasks/pushNotificationConfig/list` protocol method.
 	OnListTaskPushConfig(ctx context.Context, params a2a.ListTaskPushConfigParams) ([]a2a.TaskPushConfig, error)
 
+	// OnSetTaskPushConfig handles the `tasks/pushNotificationConfig/set` protocol method.
 	OnSetTaskPushConfig(ctx context.Context, params a2a.TaskPushConfig) (a2a.TaskPushConfig, error)
 
+	// OnDeleteTaskPushNotificationConfig handles the `tasks/pushNotificationConfig/delete` protocol method.
 	OnDeleteTaskPushConfig(ctx context.Context, params a2a.DeleteTaskPushConfigParams) error
 }

a2asrv/reqctx.go

@@ -20,14 +20,23 @@ import (
 	"github.com/a2aproject/a2a-go/a2a"
 )
 
+// RequestContextBuilder defines an extension point for constructing request contexts
+// that contain the information needed by AgentExecutor implementations to process incoming requests.
 type RequestContextBuilder interface {
+	// Build constructs a RequestContext from the provided parameters.
 	Build(ctx context.Context, p a2a.MessageSendParams, t *a2a.Task) RequestContext
 }
 
+// RequestContext provides information about an incoming A2A request to AgentExecutor.
 type RequestContext struct {
-	Request      a2a.MessageSendParams
-	TaskID       a2a.TaskID
-	Task         *a2a.Task
+	// Request which triggered the execution.
+	Request a2a.MessageSendParams
+	// TaskID is an ID of the task or a newly generated UUIDv4 in case Message did not reference any Task.
+	TaskID a2a.TaskID
+	// Task is present if request message specified a TaskID.
+	Task *a2a.Task
+	// RelatedTasks can be present when Message includes Task references and RequestContextBuilder is configured to load them.
 	RelatedTasks []a2a.Task
-	ContextID    string
+	// ContextID is a server-generated identifier for maintaining context across multiple related tasks or interactions. Matches the Task ContextID.
+	ContextID string
 }

a2asrv/tasks.go

@@ -20,20 +20,34 @@ import (
 	"github.com/a2aproject/a2a-go/a2a"
 )
 
+// PushNotifier defines the interface for sending push notifications
+// about task state changes to external endpoints.
 type PushNotifier interface {
+	// SendPush sends a push notification containing the latest task state.
 	SendPush(ctx context.Context, task a2a.Task) error
 }
 
+// PushConfigStore manages push notification configurations for tasks.
 type PushConfigStore interface {
+	// Save creates or updates a push notification configuration for a task.
+	// PushConfig has an ID and a Task can have multiple associated configurations.
 	Save(ctx context.Context, taskId a2a.TaskID, config a2a.PushConfig) error
 
+	// Get retrieves all registered push configurations for a Task.
 	Get(ctx context.Context, taskId a2a.TaskID) ([]a2a.PushConfig, error)
 
-	Delete(ctx context.Context, taskId a2a.TaskID) error
+	// Delete removes a push configuration registered for a Task with the given configID.
+	Delete(ctx context.Context, taskId a2a.TaskID, configID string) error
+
+	// DeleteAll removes all registered push configurations of a Task.
+	DeleteAll(ctx context.Context, taskId a2a.TaskID) error
 }
 
+// TaskStore provides storage for A2A tasks.
 type TaskStore interface {
+	// Save stores a task.
 	Save(ctx context.Context, task a2a.Task) error
 
+	// Get retrieves a task by ID.
 	Get(ctx context.Context, taskId a2a.TaskID) (a2a.Task, error)
 }