Documentation
¶
Overview ¶
Package events provides a lightweight pub/sub event bus for runtime observability.
Index ¶
- type ContextBuiltData
- type ConversationStartedData
- type CustomEventData
- type Emitter
- func (e *Emitter) ContextBuilt(messageCount, tokenCount, tokenBudget int, truncated bool)
- func (e *Emitter) ConversationStarted(systemPrompt string)
- func (e *Emitter) EmitCustom(eventType EventType, middlewareName, eventName string, ...)
- func (e *Emitter) MessageCreated(role, content string, index int, toolCalls []MessageToolCall, ...)
- func (e *Emitter) MessageUpdated(index int, latencyMs int64, inputTokens, outputTokens int, totalCost float64)
- func (e *Emitter) MiddlewareCompleted(name string, index int, duration time.Duration)
- func (e *Emitter) MiddlewareFailed(name string, index int, err error, duration time.Duration)
- func (e *Emitter) MiddlewareStarted(name string, index int)
- func (e *Emitter) PipelineCompleted(duration time.Duration, totalCost float64, ...)
- func (e *Emitter) PipelineFailed(err error, duration time.Duration)
- func (e *Emitter) PipelineStarted(middlewareCount int)
- func (e *Emitter) ProviderCallCompleted(data *ProviderCallCompletedData)
- func (e *Emitter) ProviderCallFailed(provider, model string, err error, duration time.Duration)
- func (e *Emitter) ProviderCallStarted(provider, model string, messageCount, toolCount int)
- func (e *Emitter) StateLoaded(conversationID string, messageCount int)
- func (e *Emitter) StateSaved(conversationID string, messageCount int)
- func (e *Emitter) StreamInterrupted(reason string)
- func (e *Emitter) TokenBudgetExceeded(required, budget, excess int)
- func (e *Emitter) ToolCallCompleted(toolName, callID string, duration time.Duration, status string)
- func (e *Emitter) ToolCallFailed(toolName, callID string, err error, duration time.Duration)
- func (e *Emitter) ToolCallStarted(toolName, callID string, args map[string]interface{})
- func (e *Emitter) ValidationFailed(validatorName, validatorType string, err error, duration time.Duration, ...)
- func (e *Emitter) ValidationPassed(validatorName, validatorType string, duration time.Duration)
- func (e *Emitter) ValidationStarted(validatorName, validatorType string)
- type Event
- type EventBus
- type EventData
- type EventType
- type Listener
- type MessageCreatedData
- type MessageToolCall
- type MessageToolResult
- type MessageUpdatedData
- type MiddlewareCompletedData
- type MiddlewareFailedData
- type MiddlewareStartedData
- type PipelineCompletedData
- type PipelineFailedData
- type PipelineStartedData
- type ProviderCallCompletedData
- type ProviderCallFailedData
- type ProviderCallStartedData
- type StateLoadedData
- type StateSavedData
- type StreamInterruptedData
- type TokenBudgetExceededData
- type ToolCallCompletedData
- type ToolCallFailedData
- type ToolCallStartedData
- type ValidationFailedData
- type ValidationPassedData
- type ValidationStartedData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContextBuiltData ¶
type ContextBuiltData struct {
MessageCount int
TokenCount int
TokenBudget int
Truncated bool
// contains filtered or unexported fields
}
ContextBuiltData contains data for context building events.
type ConversationStartedData ¶ added in v1.1.5
type ConversationStartedData struct {
SystemPrompt string // The assembled system prompt for this conversation
// contains filtered or unexported fields
}
ConversationStartedData contains data for conversation start events.
type CustomEventData ¶
type CustomEventData struct {
MiddlewareName string
EventName string
Data map[string]interface{}
Message string
// contains filtered or unexported fields
}
CustomEventData allows middleware to emit arbitrary structured events.
type Emitter ¶
type Emitter struct {
// contains filtered or unexported fields
}
Emitter provides helpers for publishing runtime events with shared metadata.
func NewEmitter ¶
NewEmitter creates a new event emitter.
func (*Emitter) ContextBuilt ¶
ContextBuilt emits the context.built event.
func (*Emitter) ConversationStarted ¶ added in v1.1.5
ConversationStarted emits the conversation.started event with the system prompt.
func (*Emitter) EmitCustom ¶
func (e *Emitter) EmitCustom( eventType EventType, middlewareName, eventName string, data map[string]interface{}, message string, )
EmitCustom allows middleware to emit arbitrary event types with structured payloads.
func (*Emitter) MessageCreated ¶ added in v1.1.5
func (e *Emitter) MessageCreated( role, content string, index int, toolCalls []MessageToolCall, toolResult *MessageToolResult, )
MessageCreated emits the message.created event.
func (*Emitter) MessageUpdated ¶ added in v1.1.5
func (e *Emitter) MessageUpdated(index int, latencyMs int64, inputTokens, outputTokens int, totalCost float64)
MessageUpdated emits the message.updated event.
func (*Emitter) MiddlewareCompleted ¶
MiddlewareCompleted emits the middleware.completed event.
func (*Emitter) MiddlewareFailed ¶
MiddlewareFailed emits the middleware.failed event.
func (*Emitter) MiddlewareStarted ¶
MiddlewareStarted emits the middleware.started event.
func (*Emitter) PipelineCompleted ¶
func (e *Emitter) PipelineCompleted( duration time.Duration, totalCost float64, inputTokens, outputTokens, messageCount int, )
PipelineCompleted emits the pipeline.completed event.
func (*Emitter) PipelineFailed ¶
PipelineFailed emits the pipeline.failed event.
func (*Emitter) PipelineStarted ¶
PipelineStarted emits the pipeline.started event.
func (*Emitter) ProviderCallCompleted ¶
func (e *Emitter) ProviderCallCompleted(data *ProviderCallCompletedData)
ProviderCallCompleted emits the provider.call.completed event.
func (*Emitter) ProviderCallFailed ¶
ProviderCallFailed emits the provider.call.failed event.
func (*Emitter) ProviderCallStarted ¶
ProviderCallStarted emits the provider.call.started event.
func (*Emitter) StateLoaded ¶
StateLoaded emits the state.loaded event.
func (*Emitter) StateSaved ¶
StateSaved emits the state.saved event.
func (*Emitter) StreamInterrupted ¶
StreamInterrupted emits the stream.interrupted event.
func (*Emitter) TokenBudgetExceeded ¶
TokenBudgetExceeded emits the context.token_budget_exceeded event.
func (*Emitter) ToolCallCompleted ¶
ToolCallCompleted emits the tool.call.completed event.
func (*Emitter) ToolCallFailed ¶
ToolCallFailed emits the tool.call.failed event.
func (*Emitter) ToolCallStarted ¶
ToolCallStarted emits the tool.call.started event.
func (*Emitter) ValidationFailed ¶
func (e *Emitter) ValidationFailed( validatorName, validatorType string, err error, duration time.Duration, violations []string, )
ValidationFailed emits the validation.failed event.
func (*Emitter) ValidationPassed ¶
ValidationPassed emits the validation.passed event.
func (*Emitter) ValidationStarted ¶
ValidationStarted emits the validation.started event.
type Event ¶
type Event struct {
Type EventType
Timestamp time.Time
RunID string
SessionID string
ConversationID string
Data EventData
}
Event represents a runtime event delivered to listeners.
type EventBus ¶
type EventBus struct {
// contains filtered or unexported fields
}
EventBus manages event distribution to listeners.
func (*EventBus) Clear ¶
func (eb *EventBus) Clear()
Clear removes all listeners (primarily for tests).
func (*EventBus) SubscribeAll ¶
SubscribeAll registers a listener for all event types.
type EventData ¶
type EventData interface {
// contains filtered or unexported methods
}
EventData is a marker interface for event payloads.
type EventType ¶
type EventType string
EventType identifies the type of event emitted by the runtime.
const ( // EventPipelineStarted marks pipeline start. EventPipelineStarted EventType = "pipeline.started" // EventPipelineCompleted marks pipeline completion. EventPipelineCompleted EventType = "pipeline.completed" // EventPipelineFailed marks pipeline failure. EventPipelineFailed EventType = "pipeline.failed" // EventMiddlewareStarted marks middleware start. EventMiddlewareStarted EventType = "middleware.started" // EventMiddlewareCompleted marks middleware completion. EventMiddlewareCompleted EventType = "middleware.completed" // EventMiddlewareFailed marks middleware failure. EventMiddlewareFailed EventType = "middleware.failed" // EventProviderCallStarted marks provider call start. EventProviderCallStarted EventType = "provider.call.started" // EventProviderCallCompleted marks provider call completion. EventProviderCallCompleted EventType = "provider.call.completed" // EventProviderCallFailed marks provider call failure. EventProviderCallFailed EventType = "provider.call.failed" // EventToolCallStarted marks tool call start. EventToolCallStarted EventType = "tool.call.started" // EventToolCallCompleted marks tool call completion. EventToolCallCompleted EventType = "tool.call.completed" // EventToolCallFailed marks tool call failure. EventToolCallFailed EventType = "tool.call.failed" // EventValidationStarted marks validation start. EventValidationStarted EventType = "validation.started" // EventValidationPassed marks validation success. EventValidationPassed EventType = "validation.passed" // EventValidationFailed marks validation failure. EventValidationFailed EventType = "validation.failed" // EventContextBuilt marks context creation. EventContextBuilt EventType = "context.built" // EventTokenBudgetExceeded marks token budget overflow. EventTokenBudgetExceeded EventType = "context.token_budget_exceeded" // EventStateLoaded marks state load. EventStateLoaded EventType = "state.loaded" // EventStateSaved marks state save. EventStateSaved EventType = "state.saved" // EventStreamInterrupted marks a stream interruption. EventStreamInterrupted EventType = "stream.interrupted" // EventMessageCreated marks message creation. EventMessageCreated EventType = "message.created" // EventMessageUpdated marks message update (e.g., cost/latency after completion). EventMessageUpdated EventType = "message.updated" // EventConversationStarted marks the start of a new conversation. EventConversationStarted EventType = "conversation.started" )
type MessageCreatedData ¶ added in v1.1.5
type MessageCreatedData struct {
Role string
Content string
Index int // Position in conversation history
ToolCalls []MessageToolCall // Tool calls requested by assistant (if any)
ToolResult *MessageToolResult // Tool result for tool messages (if any)
// contains filtered or unexported fields
}
MessageCreatedData contains data for message creation events.
type MessageToolCall ¶ added in v1.1.5
type MessageToolCall struct {
ID string `json:"id"` // Unique identifier for this tool call
Name string `json:"name"` // Name of the tool to invoke
Args string `json:"args"` // JSON-encoded tool arguments as string
}
MessageToolCall represents a tool call in a message event (mirrors runtime/types.MessageToolCall).
type MessageToolResult ¶ added in v1.1.5
type MessageToolResult struct {
ID string `json:"id"` // References the MessageToolCall.ID
Name string `json:"name"` // Tool name that was executed
Content string `json:"content"` // Result content
Error string `json:"error,omitempty"` // Error message if tool failed
LatencyMs int64 `json:"latency_ms,omitempty"` // Tool execution latency
}
MessageToolResult represents a tool result in a message event (mirrors runtime/types.MessageToolResult).
type MessageUpdatedData ¶ added in v1.1.5
type MessageUpdatedData struct {
Index int // Position in conversation history
LatencyMs int64
InputTokens int
OutputTokens int
TotalCost float64
// contains filtered or unexported fields
}
MessageUpdatedData contains data for message update events.
type MiddlewareCompletedData ¶
type MiddlewareCompletedData struct {
Name string
Index int
Duration time.Duration
// contains filtered or unexported fields
}
MiddlewareCompletedData contains data for middleware completion events.
type MiddlewareFailedData ¶
type MiddlewareFailedData struct {
Name string
Index int
Error error
Duration time.Duration
// contains filtered or unexported fields
}
MiddlewareFailedData contains data for middleware failure events.
type MiddlewareStartedData ¶
type MiddlewareStartedData struct {
Name string
Index int
// contains filtered or unexported fields
}
MiddlewareStartedData contains data for middleware start events.
type PipelineCompletedData ¶
type PipelineCompletedData struct {
Duration time.Duration
TotalCost float64
InputTokens int
OutputTokens int
MessageCount int
// contains filtered or unexported fields
}
PipelineCompletedData contains data for pipeline completion events.
type PipelineFailedData ¶
type PipelineFailedData struct {
Error error
Duration time.Duration
// contains filtered or unexported fields
}
PipelineFailedData contains data for pipeline failure events.
type PipelineStartedData ¶
type PipelineStartedData struct {
MiddlewareCount int
// contains filtered or unexported fields
}
PipelineStartedData contains data for pipeline start events.
type ProviderCallCompletedData ¶
type ProviderCallCompletedData struct {
Provider string
Model string
Duration time.Duration
InputTokens int
OutputTokens int
CachedTokens int
Cost float64
FinishReason string
ToolCallCount int
// contains filtered or unexported fields
}
ProviderCallCompletedData contains data for provider call completion events.
type ProviderCallFailedData ¶
type ProviderCallFailedData struct {
Provider string
Model string
Error error
Duration time.Duration
// contains filtered or unexported fields
}
ProviderCallFailedData contains data for provider call failure events.
type ProviderCallStartedData ¶
type ProviderCallStartedData struct {
Provider string
Model string
MessageCount int
ToolCount int
// contains filtered or unexported fields
}
ProviderCallStartedData contains data for provider call start events.
type StateLoadedData ¶
type StateLoadedData struct {
ConversationID string
MessageCount int
// contains filtered or unexported fields
}
StateLoadedData contains data for state load events.
type StateSavedData ¶
type StateSavedData struct {
ConversationID string
MessageCount int
// contains filtered or unexported fields
}
StateSavedData contains data for state save events.
type StreamInterruptedData ¶
type StreamInterruptedData struct {
Reason string
// contains filtered or unexported fields
}
StreamInterruptedData contains data for stream interruption events.
type TokenBudgetExceededData ¶
type TokenBudgetExceededData struct {
RequiredTokens int
Budget int
Excess int
// contains filtered or unexported fields
}
TokenBudgetExceededData contains data for token budget exceeded events.
type ToolCallCompletedData ¶
type ToolCallCompletedData struct {
ToolName string
CallID string
Duration time.Duration
Status string // e.g. "success", "error", "pending"
// contains filtered or unexported fields
}
ToolCallCompletedData contains data for tool call completion events.
type ToolCallFailedData ¶
type ToolCallFailedData struct {
ToolName string
CallID string
Error error
Duration time.Duration
// contains filtered or unexported fields
}
ToolCallFailedData contains data for tool call failure events.
type ToolCallStartedData ¶
type ToolCallStartedData struct {
ToolName string
CallID string
Args map[string]interface{}
// contains filtered or unexported fields
}
ToolCallStartedData contains data for tool call start events.
type ValidationFailedData ¶
type ValidationFailedData struct {
ValidatorName string
ValidatorType string
Error error
Duration time.Duration
Violations []string
// contains filtered or unexported fields
}
ValidationFailedData contains data for validation failure events.
type ValidationPassedData ¶
type ValidationPassedData struct {
ValidatorName string
ValidatorType string
Duration time.Duration
// contains filtered or unexported fields
}
ValidationPassedData contains data for validation success events.
type ValidationStartedData ¶
type ValidationStartedData struct {
ValidatorName string
ValidatorType string // e.g. "input", "output", "semantic"
// contains filtered or unexported fields
}
ValidationStartedData contains data for validation start events.