event

Documentation

Overview

Package event defines the ACP-compatible Envelope and the standard set of event type identifiers exchanged across the bus.

Index

• Constants
• func IsTerminal(eventType string) bool
• func NewID() string
• type DeltaPayload
• type Envelope
  • func New(eventType string) *Envelope
  • func NewEvent(eventType string) *Envelope
  • func NewRequest() *Envelope
  • func (e *Envelope) Clone() *Envelope
• type ErrorPayload
• type FinalPayload
• type StartedPayload

Constants

const (
	CodeAgentTimeout     = "AGENT_TIMEOUT"
	CodeAgentUnavailable = "AGENT_UNAVAILABLE"
	CodeBackpressureDrop = "BACKPRESSURE_DROP"
	CodeTransportFailure = "TRANSPORT_FAILURE"
	CodeCodecFailure     = "CODEC_FAILURE"
	CodeAuthFailure      = "AUTH_FAILURE"
	CodeInvalidRequest   = "INVALID_REQUEST"
	CodeNoHandler        = "NO_HANDLER"
)

Standard error codes used by ErrorPayload.Code.

const (
	SpecVersion   = "acp/1.0"
	SchemaVersion = 1
)

Spec/schema versions advertised by every Envelope produced by this SDK.

const (
	// User input.
	MessageReceived = "agent.message.received"

	// Response lifecycle.
	ResponseStarted = "agent.response.started"
	ResponseDelta   = "agent.response.delta"
	ResponseFinal   = "agent.response.final"
	ResponseError   = "agent.response.error"

	// Tool calls (reserved, enabled in v0.2+).
	ToolCall   = "agent.tool.call"
	ToolResult = "agent.tool.result"

	// Async tasks (reserved, enabled in v0.3+ with JetStream).
	TaskCreated   = "agent.task.created"
	TaskCompleted = "agent.task.completed"
)

Standard event types.

Functions

func IsTerminal

func IsTerminal(eventType string) bool

IsTerminal reports whether the event type closes a streaming response, i.e. no further deltas are expected after it on the same correlation_id.

func NewID

func NewID() string

NewID returns a freshly minted event identifier. The format is UUIDv7 (RFC 9562): time-ordered, 36 chars with hyphens, natively supported by every major language and database.

On entropy failure NewID falls back to UUIDv4 so callers never see an empty ID. The fallback path is exercised by tests via uuid.SetRand.

Types

type DeltaPayload

type DeltaPayload struct {
	Delta string         `json:"delta,omitempty"`
	Data  map[string]any `json:"data,omitempty"`
}

DeltaPayload is the streamed increment for agent.response.delta. The Delta field carries the textual token stream; structured payloads can use Data.

type Envelope

type Envelope struct {
	SpecVersion   string `json:"spec_version"`
	SchemaVersion int    `json:"schema_version"`

	EventID    string    `json:"event_id"`
	EventType  string    `json:"event_type"`
	OccurredAt time.Time `json:"occurred_at"`

	TraceID        string `json:"trace_id,omitempty"`
	SpanID         string `json:"span_id,omitempty"`
	Traceparent    string `json:"traceparent,omitempty"`
	SessionID      string `json:"session_id,omitempty"`
	ConversationID string `json:"conversation_id,omitempty"`
	CorrelationID  string `json:"correlation_id,omitempty"`
	ReplyTo        string `json:"reply_to,omitempty"`

	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`

	Channel  string `json:"channel,omitempty"`
	TenantID string `json:"tenant_id,omitempty"`
	UserID   string `json:"user_id,omitempty"`

	Seq     uint64 `json:"seq,omitempty"`
	IsFinal bool   `json:"is_final,omitempty"`

	Payload  json.RawMessage `json:"payload,omitempty"`
	Metadata map[string]any  `json:"metadata,omitempty"`
}

Envelope is the wire-level container for every message routed by the bus.

func New

func New(eventType string) *Envelope

New constructs an Envelope pre-populated with spec/schema version, a fresh UUIDv7 event_id, and the current UTC timestamp.

func NewEvent

func NewEvent(eventType string) *Envelope

NewEvent creates an envelope for pub/sub broadcasting. eventType should be a business routing key, e.g. "goc.incident.created".

func NewRequest

func NewRequest() *Envelope

NewRequest creates an envelope for Invoke / StreamInvoke payloads. It always uses MessageReceived as the event type.

func (*Envelope) Clone

func (e *Envelope) Clone() *Envelope

Clone returns a shallow copy suitable for in-pipeline mutation. Payload bytes are shared by reference; callers that mutate the payload should copy it.

type ErrorPayload

type ErrorPayload struct {
	Code      string         `json:"code"`
	Message   string         `json:"message"`
	Retryable bool           `json:"retryable"`
	Cause     map[string]any `json:"cause,omitempty"`
}

ErrorPayload is the standardized failure shape for agent.response.error and failed agent.tool.result events.

type FinalPayload

type FinalPayload struct {
	Result map[string]any `json:"result,omitempty"`
}

FinalPayload terminates a streaming response with the consolidated result.

type StartedPayload

type StartedPayload struct {
	Meta map[string]any `json:"meta,omitempty"`
}

StartedPayload accompanies agent.response.started and carries optional upstream metadata (model name, planned tool calls, etc.).