federation

type Adapter interface {
	// Scheme returns the reference scheme this adapter serves ("a2a",
	// "mast", "http", ...). Must be non-empty, lowercase, and stable.
	Scheme() string

	// Invoke dispatches inputs to the remote agent identified by ref.
	// It returns an error only for dispatch-time failures (resolution,
	// validation); execution errors surface from Handle.Wait. v0.1
	// adapters MAY complete the entire remote interaction inside Invoke
	// (bounded by ctx and opts.Timeout) and return a resolved Handle.
	Invoke(ctx context.Context, ref Reference, inputs map[string]any, opts InvokeOptions) (Handle, error)
}

type Event struct {
	// Type discriminates the event ("status", "artifact",
	// "input-required", ...). Namespaced growth, additive-only.
	Type string

	// Data is the type-specific payload.
	Data map[string]any
}

type Handle interface {
	// Wait blocks until the invocation reaches a terminal state and
	// returns the Result, or the terminal error. Wait is idempotent:
	// subsequent calls return the same outcome. ctx bounds the wait
	// only; canceling it does not by itself cancel the remote task
	// (use Cancel).
	Wait(ctx context.Context) (*Result, error)

	// Events returns the intermediate-event stream. v0.1 adapters
	// return an already-closed channel (no events precede the terminal
	// state in synchronous mode); v0.2 streaming adapters deliver task
	// updates here. The channel is closed when the invocation reaches a
	// terminal state. Never returns nil.
	Events() <-chan Event

	// Cancel requests cancellation of the remote work. Idempotent;
	// best-effort. After a successful Cancel, Wait returns an error
	// wrapping ErrRemoteFailed (or the remote's terminal outcome if it
	// won the race).
	Cancel(ctx context.Context) error
}

type InvokeOptions struct {
	// Timeout bounds the whole invocation (dispatch through terminal
	// state). Zero means the adapter's / remote-agent config's default.
	Timeout time.Duration
}

type InvokeRemoteAgentArgs struct {
	// Reference identifies the remote agent:
	// <scheme>://<name>[/<skill>], e.g. a2a://external-triage/investigate-incident.
	Reference string `json:"reference"`

	// Inputs is the structured input payload for the remote agent.
	Inputs map[string]any `json:"inputs,omitempty"`
}

type Reference struct {
	// Scheme selects the adapter ("a2a", and in later versions "mast",
	// "http", "grpc"). Always lowercase.
	Scheme string

	// Name is the configured remote-agent name (URI host position).
	// Always lowercase.
	Name string

	// Skill is the optional skill selector. Empty means "the agent's
	// default / sole skill".
	Skill string

	// Raw is the reference string as given.
	Raw string
}

type Registry struct {
	// contains filtered or unexported fields
}

type Result struct {
	// State is the terminal state as reported by the remote, normalized
	// to the remote protocol's vocabulary (A2A: "completed"; a direct
	// message reply also reports "completed").
	State string

	// RemoteID identifies the remote unit of work when the protocol has
	// one (A2A task ID). Empty for direct request/response replies.
	RemoteID string

	// Text is the concatenated human-readable output (A2A text parts).
	Text string

	// Output is the structured output (A2A data parts, merged in
	// arrival order — later keys win).
	Output map[string]any

	// Raw is the protocol-level terminal payload, for debugging and for
	// callers that need fields Result does not model.
	Raw json.RawMessage
}