[v1.0] Expected breaking API changes

[yarolegovich]

The work on v1.0 migration is ongoing in release/spec-v1.

The breaking changes described here are not required for implementing the new specification. We're using this major version increment to introduce more structure and consistency into the public API, address some technical debt and make the SDK more configurable.

AgentExecutor

a2asrv.AgentExecutor gets decoupled from eventqueue.Queue. This was a misleading legacy API artifact: queues passed to agents were not created by eventqueue.Manager. AgentExecutor-generated events are first processed by the A2A server stack and only get into the queue after being stored in the TaskStore.

An attempt to Read from the provided queue on the AgentExecutor side would lead to panic.

Execute and Cancel will now return iter.Seq2[a2a.Event, error].

// Before
func (*agentExecutor) Execute(ctx context.Context, reqCtx *a2asrv.RequestContext, q eventqueue.Queue) error {
  return q.Write(ctx, a2a.NewMessage(a2a.MessageRoleAgent, a2a.TextPart{Text: "Hello, world!"}))
}

// Now
func (*agentExecutor) Execute(ctx context.Context, execCtx *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
  return func(yield func(a2a.Event, error) bool) {
    yield(a2a.NewMessage(a2a.MessageRoleAgent, a2a.TextPart{Text: "Hello, world!"}), nil)
  }
}

TaskStore

a2asrv/taskstore package gets introduced with TaskStore interface and the the default in-memory implementation.

This is better aligned with a2asrv/eventqueue and a2asrv/workqueue. TaskStore is a low-level component needed in different parts of the project. Previously it couldn't be referenced by these because of a circular dependency (TaskStore defined in a2asrv but also needed by a2asrv dependencies).

a2a.TaskVersion gets moved to the new package. a2a package is only intended for core protocol types shared by server and client, TaskVersion was not on the of them.

TaskStore.Save method will likely be replaced with separate Create and Update methods to make it easier for implementers to handle these cases separately. New structs will be introduced for grouping values.

package taskstore 

type StoredTask struct {
  Task    *a2a.Task
  Version TaskVersion
}

type UpdateRequest struct {
  Task        *a2a.TaskState
  Event       a2a.Event
  PrevVersion TaskVersion
}

type Store interface {
  Create(ctx context.Context, task *a2a.Task) (TaskVersion, error)
  Update(ctx context.Context, update *UpdateRequest) (TaskVersion, error)
  Get(ctx context.Context, taskID a2a.TaskID) (*StoredTask, error)
  List(ctx context.Context, req *a2a.ListTasksRequest) (*a2a.ListTasksResponse, error)
}

EventQueue

1. eventqueue.Queue gets removed and replaced with separated eventqueue.Reader and eventqueue.Writer.
2. eventqueue.Message gets introduced for grouping a2a.Task, taskstore.TaskVersion and a2a.ProtocolVersion. The protocol version will not be used for now, but will likely be needed to support rolling upgrades with breaking changes in the future. Protocol version is exported from a2a package.
3. eventqueue.Manager creates readers and writers separately.

If you had a custom manager implementation you can migrate it by removing Get and returning GetOrCreate result from both CreateWriter and CreateReader.

A custom queue implementation can be migrated by wrapping the data types it operated with into Message and using a2a.Version constant for setting Message.ProtocolVersion.

Interceptor

1. a2aclient.CallInterceptor and a2asrv.CallInterceptor can now return a value from Before. This allows to return a result without performing the actual call (re [Feat]: Support early return from client interceptors #130). To migrate your implementation simply add nil as the second return values.
2. a2aclient.WithInterceptors gets renamed to a2aclient.WithCallInterceptors to better match the API provided by a2asrv.
3. a2asrv.WithCallInterceptor gets renamed to a2asrv.WithCallInterceptors and takes vararg to match the API provided by a2client.

User

a2asrv.User get changed from an interface to a struct. Extensibility is now achieved using Attributes map[string]any.

This change will allow us to implement auth info propagation in distributed mode in a simpler way. Previously we would need to introduce AuthMarshaler abstraction and require users to provide it.

RequestContext

1. a2asrv.RequestContext gets renamed into a2asrv.ExecutorContext. The old naming was misleading because agent execution is happening in the detached (non-request) context.
2. a2asrv.RequestContextInterceptor becomes a2asrv.ExecutorContextInterceptor.
3. User and ServiceParams are added to the struct. Previously implementations could retrieve them from a2asrv.CallContext but the class becomes reserved for request scope now. In distributed mode a2asrv.CallContext will not be retrievable from context.

ReqMeta & CallMeta

a2asrv.ReqMeta and a2asrv.CallMeta are renamed to ServiceParams in both packages.

1. This is better aligned with the term used in the specification.
2. It is not conflicting with Metadata in payloads which was a common point of confusion.
3. It is symmetric for client and server packages.

Push Notifications

a2asrv.PushSender and a2asrv.PushConfigStore will be moved to a2asrv/push for consistency with the rest of the abstractions.

a2asrv.PushSender will be taking a2a.Event instead of a2a.Task because event will be the payload of push notification as per the new spec.

Transport

ServiceParams are now passed explicitly to a2aclient.Transport, so the method for extracting them from context was removed.