Documentation
¶
Overview ¶
Package events provides a zero-dependency, non-blocking in-memory event bus for real-time CRUD, execution, shell, and background task observability across TUI and HTTP SSE.
Index ¶
Constants ¶
const ( DefaultHubCapacity = 500 DefaultReadPreview = 16 * 1024 DefaultShellPreview = 24 * 1024 DefaultCodePreview = 16 * 1024 )
Variables ¶
This section is empty.
Functions ¶
func CapPreview ¶
CapPreview trims s safely on a UTF-8 boundary to maxBytes (keeping the head).
func CapTailPreview ¶
CapTailPreview trims the oldest head bytes of s safely on a UTF-8 boundary (aligned to a newline when nearby) so live rolling shell/task previews retain the newest maxBytes.
func FormatBytes ¶
FormatBytes renders a compact human-readable byte count for live streaming headers.
Types ¶
type Event ¶
type Event struct {
Seq int64 `json:"seq"`
Timestamp string `json:"timestamp"`
Kind Kind `json:"kind"`
SessionID string `json:"sessionId,omitempty"`
RunID string `json:"runId,omitempty"`
StreamID string `json:"streamId,omitempty"`
TxID string `json:"txId,omitempty"`
TxPhase string `json:"txPhase,omitempty"` // "open" | "committed" | "rolled_back"
Tool string `json:"tool"`
Title string `json:"title,omitempty"`
Cwd string `json:"cwd,omitempty"`
Path string `json:"path,omitempty"`
AbsPath string `json:"absPath,omitempty"`
OldPath string `json:"oldPath,omitempty"`
OldAbsPath string `json:"oldAbsPath,omitempty"`
Status string `json:"status,omitempty"` // "running" | "ok" | "error" | "denied" | "canceled" | "timeout"
DurationMs int64 `json:"durationMs,omitempty"`
HostOps int `json:"hostOps,omitempty"`
ExitCode *int `json:"exitCode,omitempty"`
Summary string `json:"summary,omitempty"`
Error string `json:"error,omitempty"`
Detail string `json:"detail,omitempty"`
DetailKind string `json:"detailKind,omitempty"` // "text" | "code" | "shell" | "search" | "image"
Truncated bool `json:"truncated,omitempty"`
Diff *diff.Result `json:"diff,omitempty"`
}
Event represents a single real-time execution or file CRUD observation.
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub maintains a bounded ring buffer of recent events and fans out live events non-blockingly.
func (*Hub) Active ¶
Active returns true when events should be computed and emitted (either live subscribers exist or alwaysRecord is enabled). Callers can check Active() to avoid diff/preview work when idle.
func (*Hub) Emit ¶
Emit timestamps, sequences, buffers, and broadcasts an event without ever blocking the caller.
func (*Hub) SetAlwaysRecord ¶
SetAlwaysRecord forces event capture even before any subscriber connects (useful in HTTP mode so late-attaching `mcplex ui --url ...` clients can replay recent activity immediately).
type Kind ¶
type Kind string
Kind identifies the category of an observed MCPlex runtime event.
const ( KindExecStart Kind = "exec_start" KindExecEnd Kind = "exec_end" KindFileCreate Kind = "create" KindFileRead Kind = "read" KindFileUpdate Kind = "update" KindFileDelete Kind = "delete" KindFileRename Kind = "rename" KindSearch Kind = "search" KindShell Kind = "shell" KindTask Kind = "task" KindStreamChunk Kind = "stream_chunk" KindTxStatus Kind = "tx_status" KindMCPCall Kind = "mcp_call" )
type LiveStream ¶
type LiveStream struct {
// contains filtered or unexported fields
}
LiveStream is a race-free, throttled io.Writer that strictly orders:
EmitStart (running) -> 0..N KindStreamChunk -> EmitEnd (terminal status).
When hub == nil or !hub.Active(), writes are zero-allocation no-ops.
func NewLiveStream ¶
func NewLiveStream(hub *Hub, base Event, interval time.Duration, maxChunkBytes int, summaryFn func(totalBytes int64) string) *LiveStream
NewLiveStream constructs a throttled live output emitter for a shell command or background task.
func (*LiveStream) EmitEnd ¶
func (s *LiveStream) EmitEnd(finalEv Event)
EmitEnd stops all pending flush timers and emits the authoritative terminal event for this stream.
func (*LiveStream) EmitStart ¶
func (s *LiveStream) EmitStart(summary string)
EmitStart emits the initial "running" event, folding in any early bytes written before EmitStart.
func (*LiveStream) Flush ¶
func (s *LiveStream) Flush()
Flush pushes any complete UTF-8 bytes currently buffered as a KindStreamChunk event.