Heartbeat Daemon

The heartbeat daemon runs proactive background agents on a cron schedule. Each heartbeat checks configured triggers — emails, RSS feeds, price thresholds, news keywords — and fires an agent when conditions are met.

Configuration

Heartbeats are defined as an array under the heartbeats key in astra.yml. Each entry specifies a schedule, the agent to invoke, and the trigger condition that must be satisfied before the agent is spawned:

yaml

heartbeats:
  - name: morning-briefing
    cron: '0 7 * * *'          # Every day at 07:00
    agent: briefing-agent
    trigger: rss
    condition:
      feeds:
        - https://feeds.example.com/tech
        - https://feeds.example.com/markets
      keywords: ['AI', 'acquisition', 'outage']

  - name: price-alert
    cron: '*/5 * * * *'        # Every 5 minutes
    agent: trading-agent
    trigger: price
    condition:
      symbol: BTC-USD
      threshold: 70000
      direction: above

  - name: inbox-triage
    cron: '*/15 * * * *'       # Every 15 minutes
    agent: email-agent
    trigger: email
    condition:
      label: INBOX
      unreadOnly: true
      minCount: 1

Trigger types

Trigger	Fires when	Key condition fields
`email`	Unread email count meets `minCount`	`label`, `unreadOnly`, `minCount`
`rss`	A feed item matches any listed keyword	`feeds`, `keywords`
`price`	Asset price crosses the threshold in the given direction	`symbol`, `threshold`, `direction`
`webhook`	An inbound HTTP POST is received at the heartbeat endpoint	`secret` (HMAC validation)
`custom`	A user-defined script returns exit code 0	`script` (path to executable)

Example: morning briefing

The following complete heartbeat definition fires a briefing agent each morning only when at least one monitored RSS feed contains a matching keyword:

yaml

heartbeats:
  - name: morning-briefing
    cron: '0 7 * * 1-5'        # Weekdays at 07:00
    agent: briefing-agent
    trigger: rss
    condition:
      feeds:
        - https://feeds.arstechnica.com/arstechnica/index
        - https://hnrss.org/frontpage
      keywords: ['funding', 'breach', 'launch', 'shutdown']

How it works

Cron scheduler — At each scheduled tick the daemon wakes and loads the heartbeat definition from astra.yml
Trigger evaluation — The daemon calls the appropriate trigger adapter (email, RSS, price, etc.) and evaluates the condition against live data. Evaluation is short-circuited as soon as the condition is definitively false
Agent spawn — If the condition passes, the daemon spawns the named agent with a context payload derived from the trigger data (e.g., the matching feed items or the current price). The agent runs to completion and the result is stored in the session log

ℹIf a heartbeat's agent is still running when the next cron tick fires, the new invocation is skipped to prevent overlap. Increase the cron interval or optimize the agent if overlaps are frequent.