event

package
v0.23.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 8, 2026 License: MIT Imports: 1 Imported by: 0

README ¶

Event Protocol

The event package defines the high-performance communication protocol for HotPlex. It provides the callback mechanisms and metadata structures required for real-time AI interaction.

📡 Event Models

  • Event: The base structure for all system events.
  • EventMetadata: Contextual information including timestamps, session IDs, and trace IDs.
  • Callback: A unified function signature used throughout the codebase for event handling.

🔄 Interaction Pattern

HotPlex events follow a Streamed Observer pattern:

  1. Dispatch: The Engine generates events (tokens, status updates, security blocks).
  2. Metadata Injection: The event is wrapped with session-specific metadata.
  3. Execution: Registered callbacks (CLI, WebSocket, or ChatApps) process the event in real-time.

🛠 Practical Usage

// Register a simple observer
engine.Execute(ctx, cfg, prompt, func(ev event.Event) {
    switch ev.Type {
    case types.MessageTypeToken:
        processToken(ev)
    case types.MessageTypeDangerBlock:
        triggerSecurityAlert(ev)
    }
})

Documentation ¶

Index ¶

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Callback ¶ 

type Callback func(eventType string, data any) error

Callback is a function type for receiving streamed events

func WrapSafe ¶ 

func WrapSafe(logger *slog.Logger, cb Callback) Callback

WrapSafe executes a callback safely, handling expected errors

type EventMeta ¶ 

type EventMeta struct {
	// Timing
	DurationMs      int64 `json:"duration_ms"`       // Event duration in milliseconds
	TotalDurationMs int64 `json:"total_duration_ms"` // Total elapsed time since start

	// Tool call info
	ToolName string `json:"tool_name"` // Tool name (e.g., "bash", "editor_write", "memo_search")
	ToolID   string `json:"tool_id"`   // Unique tool call ID
	Status   string `json:"status"`    // "running", "success", "error"
	ErrorMsg string `json:"error_msg"` // Error message if status=error

	// Token usage (when available)
	InputTokens      int32 `json:"input_tokens"`       // Input tokens
	OutputTokens     int32 `json:"output_tokens"`      // Output tokens
	CacheWriteTokens int32 `json:"cache_write_tokens"` // Cache write tokens
	CacheReadTokens  int32 `json:"cache_read_tokens"`  // Cache read tokens

	// Summaries for UI
	InputSummary  string `json:"input_summary"`  // Human-readable input summary
	OutputSummary string `json:"output_summary"` // Truncated output preview

	// File operations
	FilePath  string `json:"file_path"`  // Affected file path
	LineCount int32  `json:"line_count"` // Number of lines affected

	// Progress (for long-running operations)
	Progress    int32 `json:"progress"`     // Progress percentage (0-100)
	TotalSteps  int32 `json:"total_steps"`  // Total number of steps (for multi-stage operations)
	CurrentStep int32 `json:"current_step"` // Current step number
}

EventMeta contains detailed metadata for streaming

type EventWithMeta ¶ 

type EventWithMeta struct {
	EventType string     `json:"event_type"` // Event type (thinking, tool_use, tool_result, etc.)
	EventData string     `json:"event_data"` // Event data content
	Meta      *EventMeta `json:"meta"`       // Enhanced metadata (never nil when created via NewEventWithMeta)
}

EventWithMeta extends the basic event with metadata for observability. This type is used by executors (DirectExecutor, ReActExecutor, PlanningExecutor) and CCRunner to send detailed event metadata to the frontend.

func NewEventWithMeta ¶ 

func NewEventWithMeta(eventType, eventData string, meta *EventMeta) *EventWithMeta

NewEventWithMeta creates a new EventWithMeta with guaranteed non-nil Meta. If meta is nil, an empty EventMeta{} is used instead. This prevents nil pointer dereferences when accessing Meta fields.

type SessionStatsData ¶ 

type SessionStatsData struct {
	SessionID            string   `json:"session_id"`
	StartTime            int64    `json:"start_time"` // Unix timestamp
	EndTime              int64    `json:"end_time"`   // Unix timestamp
	TotalDurationMs      int64    `json:"total_duration_ms"`
	ThinkingDurationMs   int64    `json:"thinking_duration_ms"`
	ToolDurationMs       int64    `json:"tool_duration_ms"`
	GenerationDurationMs int64    `json:"generation_duration_ms"`
	InputTokens          int32    `json:"input_tokens"`
	OutputTokens         int32    `json:"output_tokens"`
	CacheWriteTokens     int32    `json:"cache_write_tokens"`
	CacheReadTokens      int32    `json:"cache_read_tokens"`
	TotalTokens          int32    `json:"total_tokens"`
	ToolCallCount        int32    `json:"tool_call_count"`
	ToolsUsed            []string `json:"tools_used"`
	FilesModified        int32    `json:"files_modified"`
	FilePaths            []string `json:"file_paths"`
	TotalCostUSD         float64  `json:"total_cost_usd"`
	ModelUsed            string   `json:"model_used"`
	IsError              bool     `json:"is_error"`
	ErrorMessage         string   `json:"error_message,omitempty"`
}

SessionStatsData represents the final session statistics sent to the frontend and stored in database.

Source Files ¶

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.