events

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
const (
	DefaultHubCapacity  = 500
	DefaultReadPreview  = 16 * 1024
	DefaultShellPreview = 24 * 1024
	DefaultCodePreview  = 16 * 1024
)
View Source
const MaxPendingStreamBytes = 64 * 1024

Variables

This section is empty.

Functions

func CapPreview

func CapPreview(s string, maxBytes int) (string, bool)

CapPreview trims s safely on a UTF-8 boundary to maxBytes (keeping the head).

func CapTailPreview

func CapTailPreview(s string, maxBytes int) (string, bool)

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

func FormatBytes(n int64) string

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"`
	SessionLabel string       `json:"sessionLabel,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"`
	Ops          []OpItem     `json:"ops,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 NewHub

func NewHub(capacity int) *Hub

NewHub constructs an EventHub retaining up to capacity recent events.

func (*Hub) Active

func (h *Hub) Active() bool

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) CurrentSeq added in v0.4.0

func (h *Hub) CurrentSeq() int64

CurrentSeq returns the latest sequence number assigned by this Hub.

func (*Hub) Emit

func (h *Hub) Emit(ev Event) Event

Emit timestamps, sequences, buffers, and broadcasts an event without ever blocking the caller.

func (*Hub) InstanceID added in v0.4.0

func (h *Hub) InstanceID() string

InstanceID returns the unique 8-byte hex server boot identifier for this Hub.

func (*Hub) Recent

func (h *Hub) Recent(sessionFilter string, limit int, afterSeq int64) []Event

Recent returns matching buffered events without subscribing.

func (*Hub) SetAlwaysRecord

func (h *Hub) SetAlwaysRecord(on bool)

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).

func (*Hub) SetSessionLabel added in v0.4.0

func (h *Hub) SetSessionLabel(sessionID, label string)

SetSessionLabel associates a human-readable client name (e.g. from MCP initialize clientInfo) with a SessionID so all subsequent events from that session carry SessionLabel automatically.

func (*Hub) Subscribe

func (h *Hub) Subscribe(sessionFilter string, replay int, afterSeq int64) (<-chan Event, []Event, func())

Subscribe attaches a live subscriber and returns matching replay events atomically under the same lock.

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, flushes any trailing buffered bytes, and emits the authoritative terminal event.

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.

func (*LiveStream) Write

func (s *LiveStream) Write(p []byte) (int, error)

Write buffers raw stdout/stderr bytes and flushes throttled UTF-8-safe chunks to the Hub.

type OpItem added in v0.4.0

type OpItem struct {
	Seq        int    `json:"seq,omitempty"`
	Wave       int    `json:"wave,omitempty"`
	Capability string `json:"capability"`
	Target     string `json:"target,omitempty"`
	StartMs    int64  `json:"startMs,omitempty"`
	DurationMs int64  `json:"durationMs"`
	Status     string `json:"status"` // "ok" | "error"
	Error      string `json:"error,omitempty"`
}

OpItem summarizes one host capability call inside an `exec` trace chain.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL