a2asrv

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
}

type AgentExecutor interface {
	// 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 eventqueue.Queue) 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 cancelation request cannot be processed.
	Cancel(ctx context.Context, reqCtx RequestContext, queue eventqueue.Queue) error
}

type ExtendedAgentCardProducer interface {
	AgentCardProducer

	// ExtendedCard returns a manifest for an agent which is only available to authenticated users.
	ExtendedCard() *a2a.AgentCard
}

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 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
}

type PushNotifier interface {
	// SendPush sends a push notification containing the latest task state.
	SendPush(ctx context.Context, task *a2a.Task) error
}

type RequestContext struct {
	// 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 is a server-generated identifier for maintaining context across multiple related tasks or interactions. Matches the Task ContextID.
	ContextID string
}

type RequestContextBuilder interface {
	// Build constructs a RequestContext from the provided parameters.
	Build(ctx context.Context, p *a2a.MessageSendParams, t *a2a.Task) *RequestContext
}

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
}

type RequestHandlerOption func(*defaultRequestHandler)

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)
}