Heartbeat

Heartbeat is the resident runtime check that records Anyy liveness and watches for failed cron jobs. It runs inside the gateway while the resident runtime is active.

It does not call the model. It reads local state, updates the heartbeat meta record, and can publish a notification when it sees a new cron failure signature.

Heartbeat Status

Use:

anyy heartbeat status
anyy heartbeat status --json

The status payload includes:

Field	Meaning
enabled	Whether heartbeat is enabled in config.
status	ok, degraded, disabled, or unknown.
tick_interval	How often the gateway heartbeat loop runs.
failure_cooldown	Stored cooldown value for failure notifications.
delivery_targets	Notification targets, defaulting to gateway.
actor_id	Always heartbeat.
role_id / workspace_id	Scope used for heartbeat notifications.
last_tick_at	Last successful heartbeat tick timestamp, when present.
last_notification_at	Last cron-failure notification timestamp, when present.
cron_failed_jobs	Count of enabled cron jobs whose last status is failed.

anyy status --json and gateway status RPC include heartbeat status beside cron, channels, MCP, storage, and gateway listener summaries.

Configuration

Configure heartbeat under heartbeat:

heartbeat:
  enabled: true
  tick_interval: 1m
  failure_cooldown: 15m
  delivery_targets:
    - gateway
  role_id: home
  workspace_id: default

Defaults:

Field	Default	Meaning
enabled	true	Starts heartbeat while the gateway is running.
tick_interval	1m	Interval between ticks.
failure_cooldown	15m	Cooldown value stored with failure notification state.
delivery_targets	["gateway"]	Delivery targets for heartbeat notifications.
role_id	home	Role scope for heartbeat events.
workspace_id	default	Workspace scope for heartbeat events.

Durations accept Go duration strings such as 30s, 1m, or 15m. The compatibility fields tick_interval_seconds and failure_cooldown_seconds are also accepted.

Runtime Events

On each tick, heartbeat:

1. Loads the previous heartbeat state record.
2. Scans enabled cron jobs for last_status: failed.
3. Publishes one notification when a new failure signature appears.
4. Saves updated heartbeat state with liveness and failure metadata.

The notification title is Anyy heartbeat. The message identifies the cron job that last failed.

Heartbeat notifications are scoped with:

Metadata	Value
source	heartbeat
actor_id	heartbeat
role_id	Configured role id, default home.
workspace_id	Configured workspace id, default default.

Heartbeat removes legacy user_id, agent_id, and deliver fields from its stored state when it writes the current record.

Observability

Use anyy doctor when heartbeat status is missing, stale, or degraded. The doctor output includes a heartbeat probe based on the same status payload.

Common checks:

Symptom	Check
status is unknown	The gateway may not have ticked yet, or the state database may be new.
status is disabled	heartbeat.enabled is false.
status is degraded	Cron failure scanning or notification delivery returned an error.
last_tick_at is stale	Confirm the resident gateway is running for the expected home/profile.

Heartbeat is profile-local. If you use multiple profiles or --home values, run the status command against the same home that runs the resident gateway.