Documentation
¶
Overview ¶
Package attention implements the v0.1 attention engine: the seven locked triggers (A–G) from docs/superpowers/specs/2026-04-20-ctm-serve- ui-v0.1-design.md §4 "Attention engine". The engine subscribes to the hub's global stream, maintains per-session state, and publishes `attention_raised` / `attention_cleared` events on state transitions.
Index ¶
Constants ¶
const ( StateClear = "" StateLastErrorCall = "last_error_call" StateErrorBurst = "error_burst" StateStuck = "stuck" StateTmuxDead = "tmux_dead" StateQuotaHigh = "quota_high" StateContextImminent = "context_imminent" StateYoloUnchecked = "yolo_unchecked" )
State values are the canonical alert identifiers consumed by the UI (see spec §6 Session.attention.state). Empty string means "clear".
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the attention evaluator. A single instance runs per serve process, subscribed to the hub's global stream.
func NewEngine ¶
func NewEngine(hub *events.Hub, quota QuotaSource, sessions SessionSource, thr Thresholds, clock func() time.Time) *Engine
NewEngine constructs an Engine. clock == nil uses time.Now.
func (*Engine) LastToolCallAt ¶
LastToolCallAt returns the timestamp of the most recent tool_call event observed for this session (from live stream or hub replay). Exposed so the sessions API can surface real activity instead of just last_attached_at — used as the primary list sort key.
type QuotaSource ¶
type QuotaSource interface {
WeeklyPct() (float64, bool)
FiveHourPct() (float64, bool)
ContextPct(session string) (int, bool)
}
QuotaSource is the read side of ingest.QuotaIngester the engine needs. Percentages are float64 to match the underlying accessor; the engine compares against the configured int threshold after a plain cast.
type SessionSource ¶
type SessionSource interface {
Names() []string
Mode(name string) string
TmuxAlive(name string) bool
LastCheckpointAt(name string) (time.Time, bool)
}
SessionSource supplies per-session metadata for triggers C/D/G.
type Snapshot ¶
Snapshot is the point-in-time per-session view surfaced via the SessionEnricher into /api/sessions. An empty State means "no alert".
type Thresholds ¶
type Thresholds struct {
ErrorRatePct int
ErrorRateWindow int
IdleMinutes int
QuotaPct int
ContextPct int
YoloUncheckedMinutes int
}
Thresholds wires the seven spec-mandated defaults through to the engine. Server-side config maps onto these fields.
func Defaults ¶
func Defaults() Thresholds
Defaults returns the thresholds documented in spec §1 "Attention triggers". Any field left zero by a caller is NOT backfilled here — callers pass `Defaults()` and then override as needed.
Source Files