a2a

type Capabilities struct {
	// Streaming: server-sent events for long-running tasks. We
	// have BIAM (TaskNotify) which is conceptually the same;
	// phase 2 wires the HTTP transport.
	Streaming bool `json:"streaming"`

	// PushNotifications: webhook delivery on task transitions.
	// Same primitive as TaskNotify but cross-network. Phase 3+.
	PushNotifications bool `json:"pushNotifications"`

	// StateTransitionHistory: peer can replay every task
	// state. BIAM stores envelope history; we'll expose it
	// when phase 2 ships the HTTP /tasks/{id} endpoint.
	StateTransitionHistory bool `json:"stateTransitionHistory"`
}

type Card struct {
	// Name is the human-readable agent name shown in registries
	// and peer dashboards. We use clawtool's instance name when
	// the operator has set one; otherwise the bare project
	// name.
	Name string `json:"name"`

	// Description is one paragraph of plain text describing what
	// this agent does. Peers may render it in discovery UIs.
	Description string `json:"description"`

	// URL is the JSON-RPC endpoint base. Empty in phase 1
	// (Card-only mode); populated when phase 2 lands the HTTP
	// server.
	URL string `json:"url,omitempty"`

	// Version is the agent's product version (clawtool's
	// internal/version.Version). NOT the A2A protocol version;
	// that's protocolVersion below.
	Version string `json:"version"`

	// ProtocolVersion is the A2A spec the card conforms to.
	// Follow upstream as it evolves; pinning here lets peers
	// negotiate.
	ProtocolVersion string `json:"protocolVersion"`

	// Capabilities is the feature flag block. We surface only
	// the streaming + push-notifications primitives clawtool
	// can actually serve today; future phases flip more on as
	// the implementation lands.
	Capabilities Capabilities `json:"capabilities"`

	// Skills enumerates the high-level abilities this agent
	// advertises. We don't dump every internal tool — that
	// would leak the operator's private surface and overflow
	// the card. Skills are *coarse* groupings (research,
	// code-edit, dispatch) the peer chooses from.
	Skills []Skill `json:"skills"`

	// DefaultInputModes / DefaultOutputModes — A2A's MIME-typed
	// I/O contract. clawtool speaks plain text + JSON-RPC; we
	// don't ship audio / image modes today.
	DefaultInputModes  []string `json:"defaultInputModes"`
	DefaultOutputModes []string `json:"defaultOutputModes"`

	// SecuritySchemes describes the auth modes this agent
	// accepts. Phase 1 advertises an empty schemes block (peers
	// can read the card but can't authenticate yet). Phase 2+
	// adds Bearer / OAuth schemes per ADR-024 §Threat model.
	SecuritySchemes map[string]SecurityScheme `json:"securitySchemes,omitempty"`

	// PublishedAt is when this card snapshot was generated.
	// Useful for caches / freshness checks. Always UTC.
	PublishedAt time.Time `json:"publishedAt"`
}

type CardOptions struct {
	// Name overrides the default ("clawtool"); empty keeps default.
	Name string
	// URL is the JSON-RPC endpoint. Empty until phase 2 lands.
	URL string
	// ExtraSkills appends to the canonical skill list. Empty
	// gives just the canonical set.
	ExtraSkills []Skill
}

type SecurityScheme struct {
	Type        string `json:"type"`             // "http" | "oauth2" | "apiKey"
	Scheme      string `json:"scheme,omitempty"` // for http: "bearer" / "basic"
	Description string `json:"description,omitempty"`
}

type Skill struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Tags        []string `json:"tags,omitempty"`
	// Examples are short prompts a peer can use to test the
	// skill. Optional. Keep them representative, not
	// exhaustive — the card is a contract, not a tutorial.
	Examples []string `json:"examples,omitempty"`
}