Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Add activity event store and UI

Juan Denis3ff432be25b5
diff --git a/agent/internal/agent/agent.go b/agent/internal/agent/agent.go
index b783e76d..d5d8c1ce 100644
--- a/agent/internal/agent/agent.go
+++ b/agent/internal/agent/agent.go
@@ -20,6 +20,7 @@ import (
"github.com/serverkit/agent/internal/auth"
"github.com/serverkit/agent/internal/config"
"github.com/serverkit/agent/internal/docker"
+ "github.com/serverkit/agent/internal/events"
"github.com/serverkit/agent/internal/ipc"
"github.com/serverkit/agent/internal/logger"
"github.com/serverkit/agent/internal/metrics"
@@ -40,6 +41,7 @@ type Agent struct {
terminal *terminal.Manager
ipc *ipc.Server
sampler *metricSampler
+ events *events.Store
// Active subscriptions
subscriptions map[string]context.CancelFunc
@@ -90,6 +92,15 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {
log.Info("Terminal/PTY support enabled")
}
+ // Persist the event store next to the existing config so it survives
+ // service restarts. Falls back to in-memory only if we can't infer a
+ // data directory (shouldn't happen on a normal install).
+ dataDir := ""
+ if cfg.Logging.File != "" {
+ dataDir = filepath.Dir(cfg.Logging.File)
+ }
+ eventStore := events.NewStore(200, events.DefaultPath(dataDir))
+
agent := &Agent{
cfg: cfg,
log: log,
@@ -99,6 +110,7 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {
metrics: metricsCollector,
terminal: termManager,
sampler: newMetricSampler(300), // 5 min @ 1 Hz
+ events: eventStore,
subscriptions: make(map[string]context.CancelFunc),
handlers: make(map[string]CommandHandler),
startTime: time.Now(),
@@ -188,6 +200,9 @@ func (a *Agent) Run(ctx context.Context) error {
"version", Version,
"features", fmt.Sprintf("docker=%v metrics=%v ipc=%v", a.cfg.Features.Docker, a.cfg.Features.Metrics, a.cfg.IPC.Enabled),
)
+ a.events.Append(events.KindServiceStart, events.SeverityInfo,
+ "Agent service started",
+ map[string]interface{}{"version": Version})
// Verify Docker connection if enabled
if a.docker != nil {
@@ -224,11 +239,20 @@ func (a *Agent) Run(ctx context.Context) error {
go a.samplerLoop(ctx)
}
+ // Watch WS connection state and emit Activity events on transitions.
+ // Polling at 1 Hz is fine — the activity tab is a human-readable
+ // timeline, not a real-time monitor.
+ go a.connectionWatcher(ctx)
+
// Wait for context cancellation or restart request
select {
case <-ctx.Done():
+ a.events.Append(events.KindServiceStop, events.SeverityInfo,
+ "Agent stopping (signal)", nil)
case <-a.restartCh:
a.log.Info("Restart requested")
+ a.events.Append(events.KindRestartRequested, events.SeverityInfo,
+ "Restart requested via IPC", nil)
}
// Cleanup
@@ -339,6 +363,41 @@ func abs(x int64) int64 {
return x
}
+// connectionWatcher polls the WS connection flag and emits Activity events
+// on each transition. Avoids dragging events.Store into the ws package or
+// adding a new callback API for one consumer.
+func (a *Agent) connectionWatcher(ctx context.Context) {
+ ticker := time.NewTicker(1 * time.Second)
+ defer ticker.Stop()
+
+ prev := false
+ first := true
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-ticker.C:
+ now := a.ws.IsConnected()
+ if now == prev && !first {
+ continue
+ }
+ first = false
+ if now {
+ a.events.Append(events.KindWSConnected, events.SeverityInfo,
+ "Connected to panel",
+ map[string]interface{}{"url": a.cfg.Server.URL})
+ } else if prev {
+ // Only log disconnect after we'd previously been up — avoids
+ // a spurious "lost connection" on cold-start before the
+ // first connect ever succeeds.
+ a.events.Append(events.KindWSDisconnected, events.SeverityWarn,
+ "Connection lost", nil)
+ }
+ prev = now
+ }
+ }
+}
+
// heartbeatLoop sends periodic heartbeats
func (a *Agent) heartbeatLoop(ctx context.Context) {
ticker := time.NewTicker(a.cfg.Server.PingInterval)
@@ -1364,6 +1423,15 @@ func (a *Agent) GetMetricsHistory() []ipc.MetricSample {
return a.sampler.snapshot()
}
+// GetEvents returns recent activity events newer than `since` (unix ms).
+// Pass 0 to get all events currently held in the ring buffer.
+func (a *Agent) GetEvents(since int64) []events.Event {
+ if a.events == nil {
+ return []events.Event{}
+ }
+ return a.events.Snapshot(since)
+}
+
// GetConnectionInfo returns WebSocket connection information for the IPC API
func (a *Agent) GetConnectionInfo() ipc.ConnectionInfo {
info := ipc.ConnectionInfo{
diff --git a/agent/internal/events/store.go b/agent/internal/events/store.go
new file mode 100644
index 00000000..8f1a4c3e
--- /dev/null
+++ b/agent/internal/events/store.go
@@ -0,0 +1,191 @@
+// Package events provides a small append-only event log that powers the
+// agent console's Activity tab. Events are higher-signal than raw log lines:
+// "Service started", "Connection lost (timeout)", "Restart requested by
+// tray". The agent process owns the store; producers across the codebase
+// (websocket, lifecycle, IPC handlers) push to it via Append; the IPC server
+// exposes the snapshot to the desktop UI.
+//
+// Persistence is a single JSON file rewritten on each Append. That sounds
+// wasteful but the buffer is tiny (~200 events, one or two KB) and these
+// events don't fire often enough for the rewrite cost to matter. Trade-off:
+// crash-during-write is a non-issue since each rewrite is the entire state.
+package events
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "sync"
+ "time"
+)
+
+// Kind is a stable identifier for the event type. Frontends use it to pick
+// icons and colours; storage uses it for filtering.
+type Kind string
+
+const (
+ KindServiceStart Kind = "service_start"
+ KindServiceStop Kind = "service_stop"
+ KindRestartRequested Kind = "restart_requested"
+ KindWSConnected Kind = "ws_connected"
+ KindWSDisconnected Kind = "ws_disconnected"
+ KindWSReconnecting Kind = "ws_reconnecting"
+ KindAuthFailed Kind = "auth_failed"
+ KindError Kind = "error"
+ KindInfo Kind = "info"
+)
+
+// Severity controls visual emphasis in the UI. Use sparingly — Info is the
+// default; Warn for transient issues; Error for things the user should act on.
+type Severity string
+
+const (
+ SeverityInfo Severity = "info"
+ SeverityWarn Severity = "warn"
+ SeverityError Severity = "error"
+)
+
+// Event is one entry in the activity log. Keep the JSON keys short and
+// stable — they're a public-ish wire format consumed by the desktop UI.
+type Event struct {
+ ID int64 `json:"id"`
+ Time int64 `json:"t"`
+ Kind Kind `json:"kind"`
+ Severity Severity `json:"sev"`
+ Message string `json:"msg"`
+ Metadata map[string]interface{} `json:"meta,omitempty"`
+}
+
+// Store is a bounded ring buffer of events with optional disk persistence.
+// Methods are safe for concurrent callers.
+type Store struct {
+ mu sync.Mutex
+ events []Event
+ cap int
+ nextID int64
+ persist string // file path; empty = in-memory only
+}
+
+// NewStore returns a new event store with the given capacity. If
+// persistPath is non-empty, the store loads events from that file on
+// startup and rewrites it on every Append. Pass "" to skip persistence
+// (e.g. tests).
+func NewStore(capacity int, persistPath string) *Store {
+ s := &Store{
+ events: make([]Event, 0, capacity),
+ cap: capacity,
+ persist: persistPath,
+ }
+ s.load()
+ return s
+}
+
+// Append records an event. Caller doesn't need to set ID or Time — the
+// store assigns them. Persistence errors are swallowed (best-effort) since
+// the in-memory buffer is the source of truth at runtime.
+func (s *Store) Append(kind Kind, sev Severity, message string, meta map[string]interface{}) Event {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ s.nextID++
+ ev := Event{
+ ID: s.nextID,
+ Time: time.Now().UnixMilli(),
+ Kind: kind,
+ Severity: sev,
+ Message: message,
+ Metadata: meta,
+ }
+
+ if len(s.events) >= s.cap {
+ copy(s.events, s.events[1:])
+ s.events = s.events[:len(s.events)-1]
+ }
+ s.events = append(s.events, ev)
+
+ s.saveLocked()
+ return ev
+}
+
+// Snapshot returns a copy of all events in chronological order. Optional
+// since=unix-ms returns only events newer than that; pass 0 to get all.
+func (s *Store) Snapshot(since int64) []Event {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ out := make([]Event, 0, len(s.events))
+ for _, ev := range s.events {
+ if ev.Time > since {
+ out = append(out, ev)
+ }
+ }
+ return out
+}
+
+// Clear drops all events and rewrites the persisted file.
+func (s *Store) Clear() {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.events = s.events[:0]
+ s.saveLocked()
+}
+
+// load reads persisted events from disk. Silent on missing file (first run)
+// and swallows malformed-file errors so a corrupt persist file can never
+// take down the agent — we'd rather lose history than fail to start.
+func (s *Store) load() {
+ if s.persist == "" {
+ return
+ }
+ data, err := os.ReadFile(s.persist)
+ if err != nil {
+ return
+ }
+ var events []Event
+ if err := json.Unmarshal(data, &events); err != nil {
+ return
+ }
+ if len(events) > s.cap {
+ events = events[len(events)-s.cap:]
+ }
+ s.events = events
+ for _, ev := range events {
+ if ev.ID > s.nextID {
+ s.nextID = ev.ID
+ }
+ }
+}
+
+// saveLocked persists the current buffer. Must be called with s.mu held.
+// Writes to a tempfile and renames so a partial write can't corrupt the
+// canonical file.
+func (s *Store) saveLocked() {
+ if s.persist == "" {
+ return
+ }
+ dir := filepath.Dir(s.persist)
+ if err := os.MkdirAll(dir, 0700); err != nil {
+ return
+ }
+ tmp, err := os.CreateTemp(dir, "events-*.tmp")
+ if err != nil {
+ return
+ }
+ enc := json.NewEncoder(tmp)
+ if err := enc.Encode(s.events); err != nil {
+ tmp.Close()
+ os.Remove(tmp.Name())
+ return
+ }
+ tmp.Close()
+ _ = os.Rename(tmp.Name(), s.persist)
+}
+
+// DefaultPath returns the canonical event-log file location next to the
+// agent's other data files.
+func DefaultPath(dataDir string) string {
+ if dataDir == "" {
+ return ""
+ }
+ return filepath.Join(dataDir, "events.json")
+}
diff --git a/agent/internal/ipc/handlers.go b/agent/internal/ipc/handlers.go
index 07a6c805..13e86820 100644
--- a/agent/internal/ipc/handlers.go
+++ b/agent/internal/ipc/handlers.go
@@ -63,6 +63,27 @@ func (h *Handlers) HandleMetricsHistory(w http.ResponseWriter, r *http.Request)
})
}
+// HandleEvents returns the agent's recent activity events. Optional `since`
+// query param (unix milliseconds) makes the endpoint cheap to poll: clients
+// pass the timestamp of the most recent event they've seen and only get
+// new ones back.
+func (h *Handlers) HandleEvents(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+ return
+ }
+ var since int64
+ if s := r.URL.Query().Get("since"); s != "" {
+ if parsed, err := strconv.ParseInt(s, 10, 64); err == nil {
+ since = parsed
+ }
+ }
+ evs := h.provider.GetEvents(since)
+ h.writeJSON(w, map[string]interface{}{
+ "events": evs,
+ })
+}
+
// HandleConnection returns WebSocket connection information
func (h *Handlers) HandleConnection(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
diff --git a/agent/internal/ipc/server.go b/agent/internal/ipc/server.go
index fdbe5f4d..bcc2fa62 100644
--- a/agent/internal/ipc/server.go
+++ b/agent/internal/ipc/server.go
@@ -8,6 +8,7 @@ import (
"time"
"github.com/serverkit/agent/internal/config"
+ "github.com/serverkit/agent/internal/events"
"github.com/serverkit/agent/internal/logger"
)
@@ -18,6 +19,7 @@ type StatusProvider interface {
GetMetricsHistory() []MetricSample
GetConnectionInfo() ConnectionInfo
GetRecentLogs(lines int) []string
+ GetEvents(since int64) []events.Event
Restart() error
}
@@ -126,6 +128,7 @@ func (s *Server) Start(ctx context.Context) error {
mux.HandleFunc("/status", handlers.HandleStatus)
mux.HandleFunc("/metrics", handlers.HandleMetrics)
mux.HandleFunc("/metrics/history", handlers.HandleMetricsHistory)
+ mux.HandleFunc("/events", handlers.HandleEvents)
mux.HandleFunc("/connection", handlers.HandleConnection)
mux.HandleFunc("/logs", handlers.HandleLogs)
mux.HandleFunc("/restart", handlers.HandleRestart)
diff --git a/agent/ui/src/ipc/client.js b/agent/ui/src/ipc/client.js
index 608eff77..994eaeb8 100644
--- a/agent/ui/src/ipc/client.js
+++ b/agent/ui/src/ipc/client.js
@@ -44,6 +44,7 @@ export const ipc = {
health: () => get('/health'),
status: () => get('/status'),
metricsHistory: () => get('/metrics/history'),
+ events: (since = 0) => get(`/events${since ? `?since=${since}` : ''}`),
connection: () => get('/connection'),
logs: (lines = 200) => get(`/logs?lines=${lines}`),
restart: () => post('/restart'),
diff --git a/agent/ui/src/ipc/hooks.js b/agent/ui/src/ipc/hooks.js
index 07145859..9c9fff88 100644
--- a/agent/ui/src/ipc/hooks.js
+++ b/agent/ui/src/ipc/hooks.js
@@ -51,3 +51,8 @@ export function useConnection(intervalMs = 5000) {
const { data, error } = usePolling(ipc.connection, intervalMs);
return { connection: data, error };
}
+
+export function useEvents(intervalMs = 3000) {
+ const { data, error } = usePolling(() => ipc.events(0), intervalMs);
+ return { events: data?.events || [], error };
+}
diff --git a/agent/ui/src/pages/Activity.jsx b/agent/ui/src/pages/Activity.jsx
index 90286834..8f74fb93 100644
--- a/agent/ui/src/pages/Activity.jsx
+++ b/agent/ui/src/pages/Activity.jsx
@@ -1,15 +1,134 @@
+import { useMemo, useState } from 'react';
+import {
+ Power,
+ Square,
+ RefreshCw,
+ Plug,
+ PlugZap,
+ AlertTriangle,
+ XCircle,
+ Info,
+} from 'lucide-react';
+import { useEvents } from '../ipc/hooks.js';
+
+// Maps backend event Kind → React icon. Anything unrecognized falls through
+// to the Info bubble so future kinds render gracefully without a UI patch.
+const KIND_ICON = {
+ service_start: Power,
+ service_stop: Square,
+ restart_requested: RefreshCw,
+ ws_connected: PlugZap,
+ ws_disconnected: Plug,
+ ws_reconnecting: RefreshCw,
+ auth_failed: XCircle,
+ error: AlertTriangle,
+ info: Info,
+};
+
+const SEVERITIES = ['all', 'info', 'warn', 'error'];
+
+function formatRelative(ts) {
+ const diffMs = Date.now() - ts;
+ const sec = Math.floor(diffMs / 1000);
+ if (sec < 5) return 'just now';
+ if (sec < 60) return `${sec}s ago`;
+ const min = Math.floor(sec / 60);
+ if (min < 60) return `${min}m ago`;
+ const hr = Math.floor(min / 60);
+ if (hr < 24) return `${hr}h ago`;
+ const day = Math.floor(hr / 24);
+ return `${day}d ago`;
+}
+
+function formatAbsolute(ts) {
+ const d = new Date(ts);
+ return d.toLocaleString();
+}
+
+function EventRow({ event }) {
+ const Icon = KIND_ICON[event.kind] || Info;
+ return (
+ <li className={`event event--${event.sev || 'info'}`}>
+ <div className="event__icon">
+ <Icon size={16} />
+ </div>
+ <div className="event__body">
+ <div className="event__msg">{event.msg}</div>
+ {event.meta && Object.keys(event.meta).length > 0 && (
+ <div className="event__meta">
+ {Object.entries(event.meta).map(([k, v]) => (
+ <span key={k} className="event__meta-item">
+ <strong>{k}:</strong> {String(v)}
+ </span>
+ ))}
+ </div>
+ )}
+ </div>
+ <time className="event__time" title={formatAbsolute(event.t)}>
+ {formatRelative(event.t)}
+ </time>
+ </li>
+ );
+}
+
export default function Activity() {
+ const { events, error } = useEvents(3000);
+ const [filter, setFilter] = useState('all');
+
+ const visible = useMemo(() => {
+ const list = filter === 'all'
+ ? events
+ : events.filter((e) => (e.sev || 'info') === filter);
+ // Newest first reads better as a timeline.
+ return [...list].reverse();
+ }, [events, filter]);
+
return (
<div className="page">
<header className="page__header">
- <h1 className="page__title">Activity</h1>
- <p className="page__sub">
- <span className="muted">Coming next milestone — human-readable event timeline.</span>
- </p>
+ <div>
+ <h1 className="page__title">Activity</h1>
+ <p className="page__sub muted">
+ Lifecycle events from this agent — service starts, connection changes, and operator actions.
+ </p>
+ </div>
+ <div className="filter-group">
+ {SEVERITIES.map((sev) => (
+ <button
+ key={sev}
+ type="button"
+ className={
+ 'chip' + (filter === sev ? ' chip--active' : '')
+ }
+ onClick={() => setFilter(sev)}
+ >
+ {sev}
+ </button>
+ ))}
+ </div>
</header>
- <div className="card empty-state">
- Pairing events, connection drops, restart actions, and panel-issued commands will land here.
- </div>
+
+ {error && (
+ <div className="banner banner--warn">
+ Can't reach the agent IPC server. ({error})
+ </div>
+ )}
+
+ <section className="card card--padded">
+ {visible.length === 0 ? (
+ <div className="empty-state">
+ {events.length === 0
+ ? 'No events yet — they\'ll appear here as the agent connects, restarts, or hits errors.'
+ : `Nothing matches the “${filter}” filter.`}
+ </div>
+ ) : (
+ <ul className="event-list">
+ {visible.map((ev) => (
+ <EventRow key={ev.id} event={ev} />
+ ))}
+ </ul>
+ )}
+ </section>
</div>
);
}
diff --git a/agent/ui/src/styles/main.scss b/agent/ui/src/styles/main.scss
index e3ff0eb0..e005e1d7 100644
--- a/agent/ui/src/styles/main.scss
+++ b/agent/ui/src/styles/main.scss
@@ -319,3 +319,121 @@ a {
font-size: 12px;
}
}
+
+// ─── Filter chips ────────────────────────────────────────────────────────
+
+.filter-group {
+ display: flex;
+ gap: 4px;
+}
+
+.chip {
+ background: $bg-card;
+ border: 1px solid $border-default;
+ color: $text-secondary;
+ border-radius: 999px;
+ padding: 4px 12px;
+ font-size: 12px;
+ font-weight: 500;
+ cursor: pointer;
+ text-transform: capitalize;
+ transition: all 120ms;
+
+ &:hover {
+ color: $text-primary;
+ border-color: $border-active;
+ }
+
+ &--active {
+ background: $bg-elevated;
+ color: $text-primary;
+ border-color: $border-active;
+ }
+}
+
+// ─── Activity timeline ───────────────────────────────────────────────────
+
+.card--padded {
+ padding: 0;
+ overflow: hidden;
+}
+
+.event-list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+}
+
+.event {
+ display: grid;
+ grid-template-columns: 32px 1fr auto;
+ gap: $space-md;
+ padding: 14px 18px;
+ border-bottom: 1px solid $border-subtle;
+ align-items: flex-start;
+
+ &:last-child {
+ border-bottom: none;
+ }
+
+ &__icon {
+ width: 32px;
+ height: 32px;
+ border-radius: $radius-sm;
+ display: grid;
+ place-items: center;
+ background: $bg-elevated;
+ color: $text-secondary;
+ flex-shrink: 0;
+ }
+
+ &__body {
+ min-width: 0;
+ }
+
+ &__msg {
+ color: $text-primary;
+ font-size: 13px;
+ line-height: 1.4;
+ }
+
+ &__meta {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 8px 14px;
+ margin-top: 4px;
+ font-size: 11px;
+ color: $text-tertiary;
+ }
+
+ &__meta-item {
+ word-break: break-all;
+
+ strong {
+ font-weight: 600;
+ color: $text-secondary;
+ margin-right: 4px;
+ }
+ }
+
+ &__time {
+ font-size: 11px;
+ color: $text-tertiary;
+ white-space: nowrap;
+ font-variant-numeric: tabular-nums;
+ }
+
+ &--warn {
+ .event__icon {
+ background: rgba($warning, 0.1);
+ color: $warning;
+ }
+ }
+
+ &--error {
+ .event__icon {
+ background: rgba($danger, 0.1);
+ color: $danger;
+ }
+ }
+}