History

HA NOVA History

Scope

Read-only timeline work:

• entity state history over a bounded time range
• logbook queries over a bounded time range
• long-term statistics over a bounded time range
• concise "what happened?" summaries

Not in scope:

• live subscriptions
• system logs
• trace debugging
• calendar queries
• giant raw exports

Use ha-nova:read for traces and ha-nova:fallback for calendars or subscriptions.

Bootstrap (once per session)

Verify relay CLI: ha-nova relay health If this fails: ha-nova setup

Relay Contract

Use file-based relay requests:

• ha-nova relay core --method GET --path --out
• ha-nova relay core --method GET --path --out
• ha-nova relay ws --data-file --out
• ha-nova relay jq --file --jq-file

For ha-nova relay jq, the filter is positional unless --jq-file is used. Do not invent a --jq flag.

Canonical paths:

• /api/history/period/?filter_entity_id=&end_time=
• /api/logbook/?entity=&end_time=
• recorder/statistics_during_period

Prefer minimal_response and no_attributes on large history queries when the task only needs state transitions. Relay-core response shape here stays under .data.body.

• history series: .data.body[0]
• logbook entries: .data.body
• do not probe .[0] or .[0][0] against the relay envelope

Recorder statistics response stays under WS .data.

Flow

1. Resolve the exact entity target when needed.
2. Set a bounded window.

• if the user gave a range, use it
• otherwise default to the last 24 hours for history/logbook
• otherwise default to the last 30 days for statistics/trend questions
• if the requested window is too broad, narrow it before querying

1. Choose the source:

• history for state transitions and values
• logbook for human-readable events and automation activity
• statistics for multi-day trends, comparisons, or long-term summaries

1. Execute the read into ``.
2. Summarize first:

• key transitions
• first/last seen values
• notable gaps or bursts
• key periods or trend direction for statistics
• if the raw state series can contain unknown or unavailable, do not run numeric min/max across the whole series unless you first filter to numeric states safely
• prefer simple reductions that do not depend on fragile timestamp parsing unless the user explicitly asked for gap analysis
• for the default summary, do not build complex jq expressions just to recover min/max event timestamps; numeric range plus a few direct sample timestamps is enough

1. Only show raw excerpts if the user explicitly asks.

Output Format

• Target
• Window
• Summary
• Key events, Key transitions, or Key periods
• Next step

Keep default output compact. Raw payload dumps are opt-in only.

Safety

• Read-only skill. No writes.
• No guessed entity ids.
• If more than one entity could match, ask one blocking question.
• If the data is incomplete for the requested conclusion, say so explicitly.

Guardrails

• Never run an unbounded history/logbook/statistics query.
• Cap default investigative windows at 24 hours unless the user asked for more.
• If the user asks for a very large export, narrow the request first.
• Prefer a short summary over dumping a long raw timeline.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: markusleben
• Source: markusleben/ha-nova
• License: MIT
• Homepage: https://github.com/markusleben/ha-nova

Install and usage instructions live in the source repository linked above.