Documentation
¶
Overview ¶
Package events provides an append-only event log for bc.
Events are stored as JSONL (one JSON object per line) at .bc/events.jsonl. This provides an audit trail for agent spawns, stops, work assignments, status reports, and messages.
Index ¶
Constants ¶
const ( // DefaultMaxFileSize is the size threshold (in bytes) that triggers rotation. DefaultMaxFileSize int64 = 10 * 1024 * 1024 // 10 MB // DefaultMaxRotatedFiles is the number of rotated files to keep. DefaultMaxRotatedFiles = 5 // DefaultReadLimit caps the number of events returned by Read and ReadByAgent // to prevent unbounded memory usage. Matches the SQLite store limit. DefaultReadLimit = 1000 // MaxReadLastLimit caps the value of n in ReadLast to prevent abuse. MaxReadLastLimit = 10000 )
const (
// DefaultMaxLines is the max number of lines kept in the JSONL file.
DefaultMaxLines = 10000
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
Data map[string]any `json:"data,omitempty"`
Timestamp time.Time `json:"ts"`
Type EventType `json:"type"`
Agent string `json:"agent,omitempty"`
Message string `json:"message,omitempty"`
}
Event is a single log entry.
type EventStore ¶
type EventStore interface {
Append(event Event) error
Read() ([]Event, error)
ReadLast(n int) ([]Event, error)
ReadByAgent(name string) ([]Event, error)
Close() error
}
EventStore is the interface for reading and writing events. Both the file-based Log and SQLiteLog implement this interface.
type EventType ¶
type EventType string
EventType identifies what happened.
const ( AgentSpawned EventType = "agent.spawned" AgentStopped EventType = "agent.stopped" AgentReport EventType = "agent.report" WorkAssigned EventType = "work.assigned" WorkStarted EventType = "work.started" WorkCompleted EventType = "work.completed" WorkFailed EventType = "work.failed" MessageSent EventType = "message.sent" QueueLoaded EventType = "queue.loaded" HealthCheck EventType = "health.check" HealthFailed EventType = "health.failed" HealthRecovered EventType = "health.recovered" )
type JSONLWriter ¶
type JSONLWriter struct {
// contains filtered or unexported fields
}
JSONLWriter appends SSE events to a JSONL file with line-count rotation. It is safe for concurrent use.
func NewJSONLWriter ¶
func NewJSONLWriter(path string, maxLines int) *JSONLWriter
NewJSONLWriter creates a writer that appends to the given path. maxLines controls when rotation triggers (0 = DefaultMaxLines).
func (*JSONLWriter) CurrentTasks ¶
func (w *JSONLWriter) CurrentTasks() ([]TaskItem, error)
CurrentTasks scans the JSONL event history for TaskCreate/TaskUpdate events and builds the current task state. It returns all non-deleted tasks.
func (*JSONLWriter) ReadLast ¶
func (w *JSONLWriter) ReadLast(n int) ([]SSEEvent, int, error)
ReadLast returns the last n events from the JSONL file, oldest first.
type Log ¶
type Log struct{}
Log manages the append-only event log file. Deprecated: Log is retained for reference; use JSONLWriter or SQLiteLog instead.
type PostgresLog ¶
type PostgresLog struct {
// contains filtered or unexported fields
}
PostgresLog stores events in a Postgres database. It implements the EventStore interface.
func NewPostgresLog ¶
func NewPostgresLog(db *sql.DB) *PostgresLog
NewPostgresLog creates a PostgresLog from an existing *sql.DB connection.
func (*PostgresLog) Append ¶
func (p *PostgresLog) Append(event Event) error
Append writes a single event to the database.
func (*PostgresLog) Close ¶
func (p *PostgresLog) Close() error
Close is a no-op — the shared DB is owned by the caller.
func (*PostgresLog) InitSchema ¶
func (p *PostgresLog) InitSchema() error
InitSchema creates the events table in Postgres if it doesn't exist.
func (*PostgresLog) Read ¶
func (p *PostgresLog) Read() ([]Event, error)
Read returns all events ordered by timestamp.
func (*PostgresLog) ReadByAgent ¶
func (p *PostgresLog) ReadByAgent(name string) ([]Event, error)
ReadByAgent returns events for a specific agent.
type SQLiteLog ¶
type SQLiteLog struct {
// contains filtered or unexported fields
}
SQLiteLog stores events in a SQLite database. It implements the EventStore interface.
func NewSQLiteLog ¶
NewSQLiteLog opens the events table using the shared workspace database. Returns an error if no shared database is available.
func (*SQLiteLog) ReadByAgent ¶
ReadByAgent returns events for a specific agent.
type SSEEvent ¶
type SSEEvent struct {
Data any `json:"data"`
Timestamp time.Time `json:"ts"`
Type string `json:"type"`
}
SSEEvent is a single persisted SSE event with its broadcast timestamp.
type TaskItem ¶
type TaskItem struct {
ID string `json:"id"`
Subject string `json:"subject"`
Status string `json:"status"`
Owner string `json:"owner,omitempty"`
Description string `json:"description,omitempty"`
BlockedBy []string `json:"blockedBy,omitempty"`
}
TaskItem represents a task extracted from SSE event history.
Source Files