events

type AnnotatedSession struct {
	// SessionID is the unique session identifier.
	SessionID string

	// Events are all events in the session, sorted by timestamp.
	Events []*Event

	// Annotations are all annotations for this session.
	Annotations []*annotations.Annotation

	// Timeline is the assembled media timeline.
	Timeline *MediaTimeline

	// Metadata contains session-level metadata.
	Metadata SessionMetadata
}

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

type AnnotationHandler func(annotation *annotations.Annotation, position time.Duration)

type AudioHandler func(data []byte, track TrackType, position time.Duration) bool

type AudioInputData struct {

	// Actor identifies the source of the audio (e.g., "user", "environment").
	Actor string `json:"actor"`
	// Payload contains the audio data or reference.
	Payload BinaryPayload `json:"payload"`
	// Metadata contains audio format information.
	Metadata AudioMetadata `json:"metadata"`
	// TurnID links this audio to a specific conversation turn.
	TurnID string `json:"turn_id,omitempty"`
	// ChunkIndex is the sequence number for streaming audio (0-based).
	ChunkIndex int `json:"chunk_index"`
	// IsFinal indicates this is the last chunk in the stream.
	IsFinal bool `json:"is_final"`
	// contains filtered or unexported fields
}

type AudioMetadata struct {
	// SampleRate is the audio sample rate in Hz (e.g., 16000, 24000, 44100).
	SampleRate int `json:"sample_rate"`
	// Channels is the number of audio channels (1=mono, 2=stereo).
	Channels int `json:"channels"`
	// Encoding is the audio encoding format (e.g., "pcm", "pcm_linear16", "opus", "mp3").
	Encoding string `json:"encoding"`
	// BitsPerSample is the bit depth for PCM audio (e.g., 16, 24, 32).
	BitsPerSample int `json:"bits_per_sample,omitempty"`
	// DurationMs is the duration of the audio in milliseconds.
	DurationMs int64 `json:"duration_ms"`
}

type AudioOutputData struct {

	// Payload contains the audio data or reference.
	Payload BinaryPayload `json:"payload"`
	// Metadata contains audio format information.
	Metadata AudioMetadata `json:"metadata"`
	// TurnID links this audio to a specific conversation turn.
	TurnID string `json:"turn_id,omitempty"`
	// ChunkIndex is the sequence number for streaming audio (0-based).
	ChunkIndex int `json:"chunk_index"`
	// IsFinal indicates this is the last chunk in the stream.
	IsFinal bool `json:"is_final"`
	// GeneratedFrom indicates what generated this audio (e.g., "tts", "model").
	GeneratedFrom string `json:"generated_from,omitempty"`
	// contains filtered or unexported fields
}

type AudioTranscriptionData struct {

	// Text is the transcribed text.
	Text string `json:"text"`
	// Language is the detected or specified language code (e.g., "en-US").
	Language string `json:"language,omitempty"`
	// Confidence is the confidence score (0.0 to 1.0) if available.
	Confidence float64 `json:"confidence,omitempty"`
	// TurnID links this transcription to a specific conversation turn.
	TurnID string `json:"turn_id,omitempty"`
	// AudioEventID references the audio event this transcription is derived from.
	AudioEventID string `json:"audio_event_id,omitempty"`
	// IsFinal indicates this is the final transcription (vs. interim results).
	IsFinal bool `json:"is_final"`
	// Provider is the STT provider used (e.g., "whisper", "google", "deepgram").
	Provider string `json:"provider,omitempty"`
	// contains filtered or unexported fields
}

type BinaryPayload struct {
	// StorageRef is a URI or path to the stored binary data.
	// Examples: "file://recordings/audio/chunk-001.pcm", "s3://bucket/key"
	StorageRef string `json:"storage_ref"`
	// MIMEType is the MIME type of the binary data.
	MIMEType string `json:"mime_type"`
	// Size is the size of the binary data in bytes.
	Size int64 `json:"size"`
	// Checksum is an optional integrity checksum (e.g., SHA256).
	Checksum string `json:"checksum,omitempty"`
	// InlineData contains the raw bytes if small enough to embed directly.
	// If set, StorageRef may be empty.
	InlineData []byte `json:"inline_data,omitempty"`
}

type BlobStore interface {
	// Store saves binary data and returns a storage reference.
	// The reference can be used to retrieve the data later.
	Store(ctx context.Context, sessionID string, data []byte, mimeType string) (*BinaryPayload, error)

	// StoreReader saves binary data from a reader and returns a storage reference.
	// This is more efficient for large payloads.
	StoreReader(ctx context.Context, sessionID string, r io.Reader, mimeType string) (*BinaryPayload, error)

	// Load retrieves binary data by storage reference.
	Load(ctx context.Context, ref string) ([]byte, error)

	// LoadReader returns a reader for binary data by storage reference.
	// The caller is responsible for closing the reader.
	LoadReader(ctx context.Context, ref string) (io.ReadCloser, error)

	// Delete removes binary data by storage reference.
	Delete(ctx context.Context, ref string) error

	// Close releases any resources held by the store.
	Close() error
}

type ContextBuiltData struct {
	MessageCount int
	TokenCount   int
	TokenBudget  int
	Truncated    bool
	// contains filtered or unexported fields
}

type ConversationStartedData struct {
	SystemPrompt string // The assembled system prompt for this conversation
	// contains filtered or unexported fields
}

type CustomEventData struct {
	MiddlewareName string
	EventName      string
	Data           map[string]interface{}
	Message        string
	// contains filtered or unexported fields
}

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

type Event struct {
	Type           EventType
	Timestamp      time.Time
	RunID          string
	SessionID      string
	ConversationID string
	Data           EventData
}

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

type EventData interface {
	// contains filtered or unexported methods
}

type EventFilter struct {
	SessionID      string
	ConversationID string
	RunID          string
	Types          []EventType
	Since          time.Time
	Until          time.Time
	Limit          int
}

type EventStore interface {
	// Append adds an event to the store.
	Append(ctx context.Context, event *Event) error

	// Query returns events matching the filter.
	Query(ctx context.Context, filter *EventFilter) ([]*Event, error)

	// QueryRaw returns stored events with raw data preserved.
	// This is useful for export/import where data serialization must be preserved.
	QueryRaw(ctx context.Context, filter *EventFilter) ([]*StoredEvent, error)

	// Stream returns a channel of events for a session.
	// The channel is closed when all events have been sent or context is canceled.
	Stream(ctx context.Context, sessionID string) (<-chan *Event, error)

	// Close releases any resources held by the store.
	Close() error
}

type EventStoreWithBlobs struct {
	EventStore
	BlobStore
}

type EventType string

type ExportConfig struct {
	// Format is the output format.
	Format ExportFormat

	// OutputPath is the path to write the output file.
	OutputPath string

	// IncludeAnnotations when true, overlays annotations on video output.
	IncludeAnnotations bool

	// IncludeEvents when true, overlays events on video output.
	IncludeEvents bool

	// IncludeTranscriptions when true, overlays transcriptions on video output.
	IncludeTranscriptions bool

	// VideoWidth is the output video width (default: 1280).
	VideoWidth int

	// VideoHeight is the output video height (default: 720).
	VideoHeight int

	// FontSize is the font size for overlays (default: 24).
	FontSize int

	// AudioMix specifies how to mix audio tracks.
	// "stereo" = input on left, output on right
	// "mono" = mix both to mono
	// "output" = output audio only
	// "input" = input audio only
	AudioMix string

	// FFmpegPath is the path to ffmpeg binary (default: "ffmpeg").
	FFmpegPath string

	// StartTime is the start position for export (default: 0).
	StartTime time.Duration

	// EndTime is the end position for export (default: full duration).
	EndTime time.Duration

	// OnProgress is called with progress updates (0.0 to 1.0).
	OnProgress func(progress float64)
}

type ExportFormat string

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

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

type ImageInputData struct {

	// Actor identifies the source of the image (e.g., "user", "environment").
	Actor string `json:"actor"`
	// Payload contains the image data or reference.
	Payload BinaryPayload `json:"payload"`
	// Metadata contains image format information.
	Metadata VideoMetadata `json:"metadata"` // Reuse VideoMetadata for dimensions
	// Description is an optional description of the image content.
	Description string `json:"description,omitempty"`
	// contains filtered or unexported fields
}

type ImageOutputData struct {

	// Payload contains the image data or reference.
	Payload BinaryPayload `json:"payload"`
	// Metadata contains image format information.
	Metadata VideoMetadata `json:"metadata"` // Reuse VideoMetadata for dimensions
	// GeneratedFrom indicates what generated this image (e.g., "dalle", "stable-diffusion").
	GeneratedFrom string `json:"generated_from,omitempty"`
	// Prompt is the prompt used to generate the image (if applicable).
	Prompt string `json:"prompt,omitempty"`
	// contains filtered or unexported fields
}

type JSONSegment struct {
	StartTime  float64 `json:"start_time_seconds"`
	Duration   float64 `json:"duration_seconds"`
	StorageRef string  `json:"storage_ref"`
	Size       int64   `json:"size_bytes"`
}

type JSONTimeline struct {
	SessionID string             `json:"session_id"`
	Duration  float64            `json:"duration_seconds"`
	Metadata  SessionMetadata    `json:"metadata"`
	Events    []JSONTimelineItem `json:"events"`
	Tracks    []JSONTrack        `json:"tracks"`
}

type JSONTimelineItem struct {
	Time     float64                `json:"time_seconds"`
	Duration float64                `json:"duration_seconds,omitempty"`
	Type     string                 `json:"type"`
	Data     map[string]interface{} `json:"data"`
}

type JSONTrack struct {
	Type     string        `json:"type"`
	Duration float64       `json:"duration_seconds"`
	Segments []JSONSegment `json:"segments"`
}

type Listener func(*Event)

type MediaSegment struct {
	// StartTime is when this segment starts relative to session start.
	StartTime time.Duration
	// Duration is how long this segment lasts.
	Duration time.Duration
	// Payload contains the media data or reference.
	Payload *BinaryPayload
	// Metadata contains format information.
	Metadata interface{} // AudioMetadata or VideoMetadata
	// EventIndex is the index of the source event.
	EventIndex int
	// ChunkIndex is the original chunk sequence number.
	ChunkIndex int
}

type MediaTimeline struct {
	// SessionID is the session this timeline belongs to.
	SessionID string
	// SessionStart is when the session started.
	SessionStart time.Time
	// SessionEnd is when the session ended.
	SessionEnd time.Time
	// Tracks contains all media tracks indexed by type.
	Tracks map[TrackType]*MediaTrack
	// Events are all the source events.
	Events []*Event
	// contains filtered or unexported fields
}

type MediaTrack struct {
	// Type identifies the track type.
	Type TrackType
	// Segments are the ordered media segments in this track.
	Segments []*MediaSegment
	// TotalDuration is the total duration of all segments.
	TotalDuration time.Duration
	// Format contains track-level format information.
	Format interface{} // AudioMetadata or VideoMetadata
}

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
}

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
}

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
}

type MessageUpdatedData struct {
	Index        int // Position in conversation history
	LatencyMs    int64
	InputTokens  int
	OutputTokens int
	TotalCost    float64
	// contains filtered or unexported fields
}

type MiddlewareCompletedData struct {
	Name     string
	Index    int
	Duration time.Duration
	// contains filtered or unexported fields
}

type MiddlewareFailedData struct {
	Name     string
	Index    int
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

type MiddlewareStartedData struct {
	Name  string
	Index int
	// contains filtered or unexported fields
}

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

type PipelineCompletedData struct {
	Duration     time.Duration
	TotalCost    float64
	InputTokens  int
	OutputTokens int
	MessageCount int
	// contains filtered or unexported fields
}

type PipelineFailedData struct {
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

type PipelineStartedData struct {
	MiddlewareCount int
	// contains filtered or unexported fields
}

type PlayerCallback func(event *Event, position time.Duration) bool

type PlayerConfig struct {
	// Speed is the playback speed multiplier (1.0 = real-time, 2.0 = 2x speed, 0.5 = half speed).
	// Default: 1.0
	Speed float64

	// OnEvent is called for each event during replay.
	// If nil, events are still played but not observed.
	OnEvent PlayerCallback

	// OnStateChange is called when the player state changes.
	OnStateChange func(state PlayerState)

	// OnComplete is called when playback reaches the end.
	OnComplete func()

	// OnError is called when an error occurs during playback.
	OnError func(err error)

	// SkipTiming when true, delivers all events immediately without timing delays.
	// Useful for fast-forward or event analysis.
	SkipTiming bool
}

type PlayerState int

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
}

type ProviderCallFailedData struct {
	Provider string
	Model    string
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

type ProviderCallStartedData struct {
	Provider     string
	Model        string
	MessageCount int
	ToolCount    int
	// contains filtered or unexported fields
}

type Rect struct {
	X      int `json:"x"`
	Y      int `json:"y"`
	Width  int `json:"width"`
	Height int `json:"height"`
}

type ScreenshotData struct {

	// Payload contains the image data or reference.
	Payload BinaryPayload `json:"payload"`
	// Metadata contains image format information.
	Metadata VideoMetadata `json:"metadata"` // Reuse VideoMetadata for dimensions
	// WindowTitle is the title of the captured window (if applicable).
	WindowTitle string `json:"window_title,omitempty"`
	// WindowBounds contains the window position and size.
	WindowBounds *Rect `json:"window_bounds,omitempty"`
	// Reason describes why the screenshot was taken (e.g., "before_action", "after_action", "periodic").
	Reason string `json:"reason,omitempty"`
	// contains filtered or unexported fields
}

type SerializableEvent struct {
	Type           EventType       `json:"type"`
	Timestamp      time.Time       `json:"timestamp"`
	RunID          string          `json:"run_id,omitempty"`
	SessionID      string          `json:"session_id"`
	ConversationID string          `json:"conversation_id,omitempty"`
	DataType       string          `json:"data_type,omitempty"`
	Data           json.RawMessage `json:"data,omitempty"`
}

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

type SessionMetadata struct {
	// StartTime is when the session started.
	StartTime time.Time
	// EndTime is when the session ended.
	EndTime time.Time
	// Duration is the total session duration.
	Duration time.Duration

	// EventCounts by type.
	EventCounts map[EventType]int
	// AnnotationCounts by type.
	AnnotationCounts map[annotations.AnnotationType]int

	// HasAudioInput indicates if the session has audio input.
	HasAudioInput bool
	// HasAudioOutput indicates if the session has audio output.
	HasAudioOutput bool
	// HasVideo indicates if the session has video.
	HasVideo bool

	// TotalAudioInputDuration is the total duration of audio input.
	TotalAudioInputDuration time.Duration
	// TotalAudioOutputDuration is the total duration of audio output.
	TotalAudioOutputDuration time.Duration

	// ConversationTurns is the number of conversation turns.
	ConversationTurns int
	// ToolCalls is the number of tool calls.
	ToolCalls int
	// ProviderCalls is the number of provider calls.
	ProviderCalls int
}

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

type StageCompletedData struct {
	Name      string
	Index     int
	Duration  time.Duration
	StageType string
	// contains filtered or unexported fields
}

type StageFailedData struct {
	Name      string
	Index     int
	Error     error
	Duration  time.Duration
	StageType string
	// contains filtered or unexported fields
}

type StageStartedData struct {
	Name      string
	Index     int
	StageType string // Type of stage (transform, accumulate, generate, sink, bidirectional)
	// contains filtered or unexported fields
}

type StateLoadedData struct {
	ConversationID string
	MessageCount   int
	// contains filtered or unexported fields
}

type StateSavedData struct {
	ConversationID string
	MessageCount   int
	// contains filtered or unexported fields
}

type StoredEvent struct {
	Sequence int64              `json:"seq"`
	ParentID int64              `json:"parent_id,omitempty"`
	Event    *SerializableEvent `json:"event"`
}

type StreamInterruptedData struct {
	Reason string
	// contains filtered or unexported fields
}

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

type SyncPlayerConfig struct {
	// Speed is the playback speed multiplier (1.0 = real-time).
	Speed float64

	// OnEvent is called for each event during replay.
	OnEvent PlayerCallback

	// OnAudio is called with audio data chunks during playback.
	// The handler receives raw PCM data that can be played through speakers.
	OnAudio AudioHandler

	// OnAnnotation is called when an annotation becomes active.
	OnAnnotation AnnotationHandler

	// OnStateChange is called when the player state changes.
	OnStateChange func(state PlayerState)

	// OnComplete is called when playback reaches the end.
	OnComplete func()

	// OnError is called when an error occurs during playback.
	OnError func(err error)

	// AudioBufferSize is the size of audio chunks delivered to OnAudio.
	// Default: 4096 bytes
	AudioBufferSize int

	// SkipTiming when true, delivers all events immediately without timing delays.
	SkipTiming bool
}

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

type TimelineItem struct {
	// Type is the item type.
	Type TimelineItemType
	// Time is when this item occurs relative to session start.
	Time time.Duration
	// Duration is how long this item spans (0 for instantaneous items).
	Duration time.Duration
	// Event is the event (if Type == TimelineItemEvent).
	Event *Event
	// Annotation is the annotation (if Type == TimelineItemAnnotation).
	Annotation *annotations.Annotation
	// Track is the media track (if Type == TimelineItemMedia).
	Track TrackType
	// Segment is the media segment (if Type == TimelineItemMedia).
	Segment *MediaSegment
}

type TimelineItemType int

type TimelineView struct {
	// Items are all items in the timeline, sorted by time.
	Items []TimelineItem
}

type TokenBudgetExceededData struct {
	RequiredTokens int
	Budget         int
	Excess         int
	// contains filtered or unexported fields
}

type ToolCallCompletedData struct {
	ToolName string
	CallID   string
	Duration time.Duration
	Status   string // e.g. "success", "error", "pending"
	// contains filtered or unexported fields
}

type ToolCallFailedData struct {
	ToolName string
	CallID   string
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

type ToolCallStartedData struct {
	ToolName string
	CallID   string
	Args     map[string]interface{}
	// contains filtered or unexported fields
}

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

type TrackType string

type ValidationFailedData struct {
	ValidatorName string
	ValidatorType string
	Error         error
	Duration      time.Duration
	Violations    []string
	// contains filtered or unexported fields
}

type ValidationPassedData struct {
	ValidatorName string
	ValidatorType string
	Duration      time.Duration
	// contains filtered or unexported fields
}

type ValidationStartedData struct {
	ValidatorName string
	ValidatorType string // e.g. "input", "output", "semantic"
	// contains filtered or unexported fields
}

type VideoFrameData struct {

	// Payload contains the frame data or reference.
	Payload BinaryPayload `json:"payload"`
	// Metadata contains video format information.
	Metadata VideoMetadata `json:"metadata"`
	// FrameIndex is the frame sequence number.
	FrameIndex int64 `json:"frame_index"`
	// TimestampMs is the frame timestamp in milliseconds from session start.
	TimestampMs int64 `json:"timestamp_ms"`
	// IsKeyframe indicates if this is a keyframe (for seeking).
	IsKeyframe bool `json:"is_keyframe"`
	// contains filtered or unexported fields
}

type VideoMetadata struct {
	// Width is the video frame width in pixels.
	Width int `json:"width"`
	// Height is the video frame height in pixels.
	Height int `json:"height"`
	// Encoding is the video encoding format (e.g., "h264", "vp8", "mjpeg", "raw").
	Encoding string `json:"encoding"`
	// FrameRate is the frames per second.
	FrameRate float64 `json:"frame_rate,omitempty"`
	// DurationMs is the duration in milliseconds (for video segments).
	DurationMs int64 `json:"duration_ms,omitempty"`
}