models

type AgentCapabilities struct {
	// If `true`, the agent supports `message/stream` and `tasks/resubscribe` for real-time
	// updates via Server-Sent Events (SSE). Default: `false`.
	Streaming bool `json:"streaming,omitempty"`
	// If `true`, the agent supports `tasks/pushNotificationConfig/set` and `tasks/pushNotificationConfig/get`
	// for asynchronous task updates via webhooks. Default: `false`.
	PushNotifications bool `json:"pushNotifications,omitempty"`
	// If `true`, the agent may include a detailed history of status changes
	// within the `Task` object (future enhancement; specific mechanism TBD). Default: `false`.
	StateTransitionHistory bool `json:"stateTransitionHistory,omitempty"`
}

type AgentCard struct {
	/**
	 * The version of the A2A protocol this agent supports.
	 * @default "0.2.5"
	 */
	ProtocolVersion string `json:"protocolVersion"`
	/**
	 * Human readable name of the agent.
	 * Example: "Recipe Agent"
	 */
	Name string `json:"name"`
	/**
	 * A human-readable description of the agent. Used to assist users and
	 * other agents in understanding what the agent can do.
	 * Example: "Agent that helps users with recipes and cooking."
	 */
	Description string `json:"description"`
	/**
	 * A URL to the address the agent is hosted at. This represents the
	 * preferred endpoint as declared by the agent.
	 */
	URL string `json:"url"`
	/**
	 * The transport of the preferred endpoint. If empty, defaults to JSONRPC.
	 */
	PreferredTransport string `json:"preferredTransport,omitempty"`
	/**
	 * Announcement of additional supported transports. Client can use any of
	 * the supported transports.
	 */
	// AdditionalInterfaces AgentInterface[] `json:"additionalInterfaces,omitempty"` todo: support?
	/** A URL to an icon for the agent. */
	IconUrl string `json:"iconUrl,omitempty"`
	/** The service provider of the agent */
	Provider *AgentProvider `json:"provider,omitempty"`
	/**
	 * The version of the agent - format is up to the provider.
	 * @TJS-examples ["1.0.0"]
	 */
	Version string `json:"version"`
	/**
	 * A URL to the address the agent is hosted at. This represents the
	 * preferred endpoint as declared by the agent.
	 */
	DocumentationURL string `json:"documentationUrl,omitempty"`
	/** Optional capabilities supported by the agent. */
	Capabilities AgentCapabilities `json:"capabilities"`
	/** Security scheme details used for authenticating with this agent. */
	SecuritySchemes map[string]*spec.SecurityScheme `json:"securitySchemes,omitempty"`
	/** Security requirements for contacting the agent. */
	Security []map[string][]string `json:"security,omitempty"`
	/**
	 * The set of interaction modes that the agent supports across all skills. This can be overridden per-skill.
	 * Supported media types for input.
	 */
	DefaultInputModes []string `json:"defaultInputModes"`
	/** Supported media types for output. */
	DefaultOutputModes []string `json:"defaultOutputModes"`
	/** Skills are a unit of capability that an agent can perform. */
	Skills []AgentSkill `json:"skills"`
	/**
	 * true if the agent supports providing an extended agent card when the user is authenticated.
	 * Defaults to false if not specified.
	 */
	SupportsAuthenticatedExtendedCard bool `json:"supportsAuthenticatedExtendedCard,omitempty"`
}

type AgentProvider struct {
	// Name of the organization or entity.
	Organization string `json:"organization"`
	// URL for the provider's organization website or relevant contact page.
	URL string `json:"url"`
}

type AgentSkill struct {
	// ID is the unique identifier for the skill
	ID string `json:"id"`
	// Name is the human-readable name of the skill
	Name string `json:"name"`
	// Description is an optional description of the skill
	Description *string `json:"description"`
	// Tags is an optional list of tags associated with the skill for categorization
	Tags []string `json:"tags"`
	// Examples is an optional list of example inputs or use cases for the skill
	Examples []string `json:"examples,omitempty"`
	// InputModes is an optional list of input modes supported by this skill
	InputModes []string `json:"inputModes,omitempty"`
	// OutputModes is an optional list of output modes supported by this skill
	OutputModes []string `json:"outputModes,omitempty"`
}

type Artifact struct {
	//unique identifier for the artifact generated by the agent. This identifier helps identify and assemble parts streamed by the agent
	ArtifactID string `json:"artifactId"`
	// Name is an optional name for the artifact
	Name string `json:"name,omitempty"`
	// Description is an optional description of the artifact
	Description string `json:"description,omitempty"`
	// Parts are the constituent parts of the artifact
	Parts []Part `json:"parts"`
	// Metadata is optional metadata associated with the artifact
	Metadata map[string]any `json:"metadata,omitempty"`
}

type AuthenticationInfo struct {
	// Schemes is a list of supported authentication schemes
	Schemes []string `json:"schemes"`
	// Credentials for authentication. Can be a string (e.g., token) or null if not required initially
	Credentials string `json:"credentials,omitempty"`
}

type FileContent struct {
	// Name is the optional name of the file
	Name string `json:"name,omitempty"`
	// MimeType is the optional MIME type of the file content
	MimeType string `json:"mimeType,omitempty"`

	// Bytes is the file content encoded as a Base64 string
	Bytes *string `json:"bytes,omitempty"`
	// URI is the URI pointing to the file content
	URI *string `json:"uri,omitempty"`
}

type GetTaskPushNotificationConfigParams struct {
	PushNotificationConfigID string `json:"pushNotificationConfigID,omitempty"`
}

type Message struct {
	// Indicates the sender of the message:
	// "user" for messages originating from the A2A Client (acting on behalf of an end-user or system).
	// "agent" for messages originating from the A2A Server (the remote agent).
	Role Role `json:"role"`
	// An array containing the content of the message, broken down into one or more parts.
	// A message MUST contain at least one part.
	// Using multiple parts allows for rich, multi-modal content (e.g., text accompanying an image).
	Parts []Part `json:"parts"`
	// Arbitrary key-value metadata associated with the message.
	// Keys SHOULD be strings; values can be any valid JSON type.
	// Useful for timestamps, source identifiers, language codes, etc.
	Metadata map[string]any `json:"metadata,omitempty"`
	// List of tasks referenced as contextual hint by this message.
	ReferenceTaskIDs []string `json:"referenceTaskIDs,omitempty"`
	// message identifier created by the message creator
	MessageID string `json:"messageId"`
	// task identifier the current message is related to
	TaskID *string `json:"taskId,omitempty"`
	// Context identifier the message is associated with
	ContextID *string `json:"contextId,omitempty"`
}

type MessageSendConfiguration struct {
	// AcceptedOutputModes specifies accepted output modalities by the client
	//AcceptedOutputModes []string `json:"acceptedOutputModes"` todo: why can client control server's output type...
	// HistoryLength specifies the number of recent messages to be retrieved
	//HistoryLength *int `json:"historyLength"`
	// PushNotificationConfig provides the server for sending asynchronous push notifications about task updates.
	PushNotificationConfig *PushNotificationConfig `json:"pushNotificationConfig,omitempty"`
	// Blocking specifies if the server should treat the client as a blocking request, true by default.
	Blocking *bool `json:"blocking,omitempty"`
}

type MessageSendParams struct {
	// The message to send to the agent. The `role` within this message is typically "user".
	Message Message `json:"message"`
	// Optional: additional configuration to send to the agent`.
	Configuration *MessageSendConfiguration `json:"configuration,omitempty"`
	// Arbitrary metadata for this specific `message/send` request.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Part struct {
	Kind PartKind `json:"kind"`
	// Text is the text content for text parts
	Text *string `json:"text,omitempty"`
	// File is the file content for file parts
	File *FileContent `json:"file,omitempty"`
	// Data is the structured data content for data parts
	Data map[string]any `json:"data,omitempty"`
	// Metadata is optional metadata associated with this part
	Metadata map[string]any `json:"metadata,omitempty"`
}

type PartKind string

type PushNotificationConfig struct {
	// The absolute HTTPS webhook URL where the A2A Server should POST task updates.
	// This URL MUST be HTTPS for security.
	URL string `json:"url"`
	// An optional, client-generated opaque token (e.g., a secret, a task-specific identifier, or a nonce).
	// The A2A Server SHOULD include this token in the notification request it sends to the `url`
	// (e.g., in a custom HTTP header like `X-A2A-Notification-Token` or similar).
	// This allows the client's webhook receiver to validate the relevance and authenticity of the notification.
	Token string `json:"token,omitempty"`
	// Authentication details the A2A Server needs to use when calling the client's `url`.
	// The client's webhook endpoint defines these requirements. This tells the A2A Server how to authenticate *itself* to the client's webhook.
	Authentication *AuthenticationInfo `json:"authentication,omitempty"`
}

type ResponseEvent struct {
	Message                        *Message
	TaskContent                    *TaskContent
	TaskStatusUpdateEventContent   *TaskStatusUpdateEventContent
	TaskArtifactUpdateEventContent *TaskArtifactUpdateEventContent
}

type ResponseKind string

type ResponseReader interface {
	Read() (*SendMessageStreamingResponseUnion, error)
	Close() error
}

type ResponseWriter interface {
	Write(ctx context.Context, f *SendMessageStreamingResponseUnion) error
	Close() error
}

type Role string

type SendMessageResponseUnion struct {
	Message *Message
	Task    *Task
}

type SendMessageStreamingResponseUnion struct {
	Message                 *Message
	Task                    *Task
	TaskStatusUpdateEvent   *TaskStatusUpdateEvent
	TaskArtifactUpdateEvent *TaskArtifactUpdateEvent
}

type ServerHandlers struct {
	AgentCard                 func(ctx context.Context) *AgentCard
	SendMessage               func(ctx context.Context, params *MessageSendParams) (*SendMessageResponseUnion, error)
	SendMessageStreaming      func(ctx context.Context, params *MessageSendParams, writer ResponseWriter) error
	GetTask                   func(ctx context.Context, params *TaskQueryParams) (*Task, error)
	CancelTask                func(ctx context.Context, params *TaskIDParams) (*Task, error)
	ResubscribeTask           func(ctx context.Context, params *TaskIDParams, writer ResponseWriter) error
	SetPushNotificationConfig func(ctx context.Context, params *TaskPushNotificationConfig) (*TaskPushNotificationConfig, error)
	GetPushNotificationConfig func(ctx context.Context, params *GetTaskPushNotificationConfigParams) (*TaskPushNotificationConfig, error)
}

type Task struct {
	// A unique identifier for the task. This ID is generated by the server.
	// It should be sufficiently unique (e.g., a UUID v4).
	ID string `json:"id"`
	// Server-generated id for contextual alignment across interactions
	// Useful for maintaining context across multiple, sequential, or related tasks.
	ContextID string `json:"contextId"` // todo: how to specify related tasks...

	// The current status of the task, including its lifecycle state, an optional associated message,
	// and a timestamp.
	Status TaskStatus `json:"status"`
	// An array of outputs (artifacts) generated by the agent for this task.
	// This array can be populated incrementally, especially during streaming.
	// Artifacts represent the tangible results of the task.
	Artifacts []*Artifact `json:"artifacts,omitempty"`
	// An optional array of recent messages exchanged within this task,
	// ordered chronologically (oldest first).
	// This history is included if requested by the client via the `historyLength` parameter
	// in `TaskSendParams` or `TaskQueryParams`.
	History []*Message `json:"history,omitempty"` // todo: what's the relation between status and history?
	// Arbitrary key-value metadata associated with the task.
	// Keys SHOULD be strings; values can be any valid JSON type (string, number, boolean, array, object).
	// This can be used for application-specific data, tracing info, etc.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskArtifactUpdateEvent struct {
	// The ID of the task associated with the generated artifact part
	TaskID string `json:"taskId"`
	// The context id the task is associated with
	ContextID string `json:"contextId"`

	// The artifact data. This could be a complete artifact or an incremental chunk.
	// The client uses `artifact.artifactId`, append, lastChunk to correctly assemble or update the artifact on its side.
	Artifact Artifact `json:"artifact"`
	/** Indicates if this artifact appends to a previous one. Omitted if artifact is a complete artifact. */
	Append bool `json:"append,omitempty"`
	/** Indicates if this is the last chunk of the artifact. Omitted if artifact is a complete artifact. */
	LastChunk bool `json:"lastChunk,omitempty"` // todo: what's the difference between Append and LastChunk, if LastChunk means all
	// Arbitrary metadata for this specific artifact update event.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskArtifactUpdateEventContent struct {
	// The artifact data. This could be a complete artifact or an incremental chunk.
	// The client uses `artifact.artifactId`, append, lastChunk to correctly assemble or update the artifact on its side.
	Artifact Artifact `json:"artifact"`
	/** Indicates if this artifact appends to a previous one. Omitted if artifact is a complete artifact. */
	Append bool `json:"append,omitempty"`
	/** Indicates if this is the last chunk of the artifact. Omitted if artifact is a complete artifact. */
	LastChunk bool `json:"lastChunk,omitempty"` // todo: what's the difference between Append and LastChunk, if LastChunk means all
	// Arbitrary metadata for this specific artifact update event.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskContent struct {
	// The current status of the task, including its lifecycle state, an optional associated message,
	// and a timestamp.
	Status TaskStatus `json:"status"`
	// An array of outputs (artifacts) generated by the agent for this task.
	// This array can be populated incrementally, especially during streaming.
	// Artifacts represent the tangible results of the task.
	Artifacts []*Artifact `json:"artifacts,omitempty"`
	// An optional array of recent messages exchanged within this task,
	// ordered chronologically (oldest first).
	// This history is included if requested by the client via the `historyLength` parameter
	// in `TaskSendParams` or `TaskQueryParams`.
	History []*Message `json:"history,omitempty"` // todo: what's the relation between status and history?
	// Arbitrary key-value metadata associated with the task.
	// Keys SHOULD be strings; values can be any valid JSON type (string, number, boolean, array, object).
	// This can be used for application-specific data, tracing info, etc.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskIDParams struct {
	// The ID of the task to which the operation applies (e.g., cancel, get push notification config).
	ID string `json:"id"`
	// Arbitrary metadata for this specific request.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskPushNotificationConfig struct {
	// The ID of the task for which push notification settings are being configured or retrieved.
	TaskID string `json:"taskId"`
	// The push notification configuration details.
	// When used as params for `set`, this provides the configuration to apply.
	// When used as result for `get`, this reflects the currently active configuration (server MAY omit secrets).
	PushNotificationConfig PushNotificationConfig `json:"pushNotificationConfig"`
}

type TaskQueryParams struct {
	// The ID of the task to retrieve.
	ID string `json:"id"`
	// Optional: If a positive integer `N` is provided, the server SHOULD include the last `N` messages
	// (chronologically) of the task's history in the `Task.history` field of the response.
	// If `0`, or omitted, no history is explicitly requested.
	HistoryLength *int `json:"historyLength,omitempty"`
	// Arbitrary metadata for this specific `tasks/get` request.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskState string

type TaskStatus struct {
	// The current lifecycle state of the task.
	State TaskState `json:"state"`
	// An optional message associated with the current status.
	// This could be a progress update from the agent, a prompt for more input,
	// a summary of the final result, or an error message.
	Message *Message `json:"message,omitempty"`
	// The date and time (UTC is STRONGLY recommended) when this status was recorded by the server.
	// Format: ISO 8601 `date-time` string (e.g., "2023-10-27T10:00:00Z").
	Timestamp string `json:"timestamp,omitempty"`
}

type TaskStatusUpdateEvent struct {
	// The ID of the task being updated.
	TaskID string `json:"taskId"`
	// The context id the task is associated with
	ContextID string `json:"contextId"`

	// The new status object for the task.
	Status TaskStatus `json:"status"`
	// If `true`, this `TaskStatusUpdateEvent` signifies the terminal status update for the current
	// `message/stream` interaction cycle. This means the task has reached a terminal or paused state
	// and the server does not expect to send more updates for *this specific* `stream` request.
	// The server typically closes the SSE connection after sending an event with `final: true`.
	// Default: `false` if omitted.
	Final bool `json:"final"`
	// Arbitrary metadata for this specific status update event.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskStatusUpdateEventContent struct {
	// The new status object for the task.
	Status TaskStatus `json:"status"`
	// If `true`, this `TaskStatusUpdateEvent` signifies the terminal status update for the current
	// `message/stream` interaction cycle. This means the task has reached a terminal or paused state
	// and the server does not expect to send more updates for *this specific* `stream` request.
	// The server typically closes the SSE connection after sending an event with `final: true`.
	// Default: `false` if omitted.
	Final bool `json:"final"`
	// Arbitrary metadata for this specific status update event.
	Metadata map[string]any `json:"metadata,omitempty"`
}