Documentation
¶
Overview ¶
Package conditions generates the "Current Conditions" section of the system prompt. This gives the agent real-time awareness of when and where it's running — information that affects every decision (e.g., "should I wake the user at 3am?").
The section is placed early in the system prompt (after persona and inject files, before talents) because models attend more strongly to content near the beginning. The heading level (H1) signals importance.
Package statewindow maintains a rolling window of Home Assistant state changes and injects them into the agent's system prompt. The window uses a circular buffer with dual eviction: count-based (buffer capacity) and age-based (configurable max age applied at read time).
Package watchlist manages a dynamic set of Home Assistant entities whose state is injected into the agent's system prompt each turn. Entities are persisted in SQLite so the watchlist survives restarts.
Index ¶
- func CurrentConditions(timezone string) string
- func FormatContextUsage(info ContextUsageInfo) string
- func FormatDelta(t time.Time, now time.Time) string
- func FormatDeltaOnly(t time.Time, now time.Time) string
- func ParseTimeOrDelta(s string, now time.Time) (time.Time, error)
- type ContextUsageInfo
- type StateGetter
- type StateWindowEntry
- type StateWindowProvider
- type WatchlistProvider
- type WatchlistStore
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CurrentConditions ¶
CurrentConditions returns a formatted "# Current Conditions" section for injection into the system prompt. The timezone parameter should be an IANA timezone name (e.g., "America/Chicago"). If empty or invalid, the system's local timezone is used.
func FormatContextUsage ¶
func FormatContextUsage(info ContextUsageInfo) string
FormatContextUsage renders a single-line context usage string for the system prompt. Each segment is conditionally included based on available data. Returns an empty string when no data fields are populated.
func FormatDelta ¶
FormatDelta returns a delta-annotated timestamp string relative to now. Past timestamps produce just the delta: "(-3247s)". Future timestamps keep the absolute time and annotate: "2026-03-07T18:00-06:00 (+52143s)".
func FormatDeltaOnly ¶
FormatDeltaOnly returns just the signed delta string: "-3247s" or "+3600s".
func ParseTimeOrDelta ¶
ParseTimeOrDelta parses either an absolute RFC3339 timestamp or a signed offset ("+3600s", "-300s") relative to now. Any tool parameter that accepts a timestamp should use this for backwards-compatible offset support.
Types ¶
type ContextUsageInfo ¶
type ContextUsageInfo struct {
// Model is the default model name (e.g., "claude-opus-4-20250514").
// The "(routed)" suffix is appended when Routed is true, signaling
// that the router may select a different model for this turn.
Model string
// Routed indicates whether a router is configured (actual model may differ).
Routed bool
// TokenCount is the estimated token count of the active conversation.
TokenCount int
// ContextWindow is the context window size of the default model.
ContextWindow int
// MessageCount is the number of messages in the active conversation.
MessageCount int
// SessionAge is how long the current session has been active.
// Zero means unknown or no active session.
SessionAge time.Duration
// CompactionCount is the number of compaction summaries in the conversation.
CompactionCount int
// ConversationID is the active conversation identifier.
ConversationID string
// SessionID is the active session identifier (short form, 8 chars).
SessionID string
// RequestID is the per-turn request identifier.
RequestID string
}
ContextUsageInfo holds the data needed to render the context usage line in the Current Conditions system prompt section. All fields are pre-computed by the caller so that formatting is deterministic and free of I/O.
type StateGetter ¶
type StateGetter interface {
GetState(ctx context.Context, entityID string) (*homeassistant.State, error)
}
StateGetter abstracts the Home Assistant REST client for fetching entity state. Using an interface keeps the provider testable without a real HA instance.
type StateWindowEntry ¶
type StateWindowEntry struct {
EntityID string
OldState string
NewState string
Timestamp time.Time
}
Entry records a single state transition observed from the Home Assistant WebSocket event stream.
type StateWindowProvider ¶
type StateWindowProvider struct {
// contains filtered or unexported fields
}
Provider maintains a rolling window of recent state changes and implements the agent.ContextProvider interface. It is safe for concurrent use: HandleStateChange writes under a write lock while GetContext reads under a read lock.
func NewStateWindowProvider ¶
func NewStateWindowProvider(maxEntries int, maxAge time.Duration, loc *time.Location, logger *slog.Logger) *StateWindowProvider
NewStateWindowProvider creates a state window provider with the given buffer capacity and maximum entry age. The loc parameter controls the timezone used when formatting future-event timestamps in the context output; nil falls back to time.Local. Entries older than maxAge are filtered out at read time in GetContext.
func (*StateWindowProvider) GetContext ¶
GetContext returns a formatted context block listing recent state changes for injection into the agent's system prompt. Entries older than maxAge are excluded. Returns an empty string when no valid entries exist.
func (*StateWindowProvider) HandleStateChange ¶
func (p *StateWindowProvider) HandleStateChange(entityID, oldState, newState string)
HandleStateChange records a state transition in the circular buffer. It matches the homeassistant.StateWatchHandler function signature and can be composed directly into the state watcher handler chain.
type WatchlistProvider ¶
type WatchlistProvider struct {
// contains filtered or unexported fields
}
Provider implements agent.ContextProvider by fetching live state for all watched entities and formatting them as a markdown block for system prompt injection.
func NewWatchlistProvider ¶
func NewWatchlistProvider(store *WatchlistStore, ha StateGetter, logger *slog.Logger) *WatchlistProvider
NewProvider creates a watchlist context provider.
func (*WatchlistProvider) GetContext ¶
GetContext returns a formatted markdown block of watched entity states for injection into the agent's system prompt. Returns an empty string when the watchlist is empty. Implements agent.ContextProvider.
type WatchlistStore ¶
type WatchlistStore struct {
// contains filtered or unexported fields
}
Store persists the set of watched entity IDs in SQLite.
func NewWatchlistStore ¶
func NewWatchlistStore(db *sql.DB) (*WatchlistStore, error)
NewStore creates a watchlist store, running migrations on first use.
func (*WatchlistStore) Add ¶
func (s *WatchlistStore) Add(entityID string) error
Add inserts an entity into the watchlist. Duplicates are silently ignored.
func (*WatchlistStore) List ¶
func (s *WatchlistStore) List() ([]string, error)
List returns all watched entity IDs in insertion order.
func (*WatchlistStore) Remove ¶
func (s *WatchlistStore) Remove(entityID string) error
Remove deletes an entity from the watchlist. Non-existent IDs are a no-op.
Source Files