feat: update heartbeat defaults

2026-01-06 21:54:19 +00:00
parent dba09058f5
commit 7aa7fa79d0
18 changed files with 128 additions and 33 deletions
--- a/docs/clawd.md
+++ b/docs/clawd.md
@@ -18,7 +18,7 @@ You’re putting an agent in a position to:
 Start conservative:
 - Always set `whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
 - Use a dedicated WhatsApp number for the assistant.
- Keep heartbeats disabled until you trust the setup (omit `agent.heartbeat` or set `agent.heartbeat.every: "0m"`).
+- Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting `agent.heartbeat.every: "0m"`.

 ## Prerequisites

@@ -161,7 +161,9 @@ Example:

 ## Heartbeats (proactive mode)

-When `agent.heartbeat.every` is set to a positive interval, CLAWDBOT periodically runs a heartbeat prompt (default: `HEARTBEAT`).
+By default, CLAWDBOT runs a heartbeat every 30 minutes with the prompt:
+`Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
+Set `agent.heartbeat.every: "0m"` to disable.

 - If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agent.heartbeat.ackMaxChars`), CLAWDBOT suppresses outbound delivery for that heartbeat.

--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -786,14 +786,17 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 `ZAI_API_KEY` (or legacy `Z_AI_API_KEY`) in the environment.

 `agent.heartbeat` configures periodic heartbeat runs:
- `every`: duration string (`ms`, `s`, `m`, `h`); default unit minutes. Omit or set
-  `0m` to disable.
+- `every`: duration string (`ms`, `s`, `m`, `h`); default unit minutes. Default:
+  `30m`. Set `0m` to disable.
 - `model`: optional override model for heartbeat runs (`provider/model`).
- `target`: optional delivery provider (`last`, `whatsapp`, `telegram`, `discord`, `imessage`, `none`). Default: `last`.
- `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram).
- `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`).
+- `target`: optional delivery provider (`last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `none`). Default: `last`.
+- `to`: optional recipient override (provider-specific id, e.g. E.164 for WhatsApp, chat id for Telegram).
+- `prompt`: optional override for the heartbeat body (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`).
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).

+Heartbeats run full agent turns. Shorter intervals burn more tokens; adjust `every`
+and/or `model` accordingly.
+
 `agent.bash` configures background bash defaults:
 - `backgroundMs`: time before auto-background (ms, default 10000)
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
--- a/docs/cron.md
+++ b/docs/cron.md
@@ -14,7 +14,7 @@ Last updated: 2025-12-13
 ## Context

 Clawdbot already has:
- A **gateway heartbeat runner** that runs the agent with `HEARTBEAT` and suppresses `HEARTBEAT_OK` ([`src/infra/heartbeat-runner.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/heartbeat-runner.ts)).
+- A **gateway heartbeat runner** that runs the agent with the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) and suppresses `HEARTBEAT_OK` ([`src/infra/heartbeat-runner.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/heartbeat-runner.ts)).
 - A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in [`src/auto-reply/reply.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/auto-reply/reply.ts)).
 - A WebSocket **Gateway** daemon that is intended to be always-on ([`docs/gateway.md`](https://docs.clawd.bot/gateway)).

--- a/docs/heartbeat.md
+++ b/docs/heartbeat.md
@@ -9,13 +9,16 @@ Heartbeat runs periodic agent turns in the **main session** so the model can
 surface anything that needs attention without spamming the user.

 ## Prompt contract
- Heartbeat body defaults to `HEARTBEAT` (configurable via `agent.heartbeat.prompt`).
+- Heartbeat body defaults to: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.` (configurable via `agent.heartbeat.prompt`).
 - If nothing needs attention, the model should reply `HEARTBEAT_OK`.
 - During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears at
  the **start or end** of the reply. Clawdbot strips the token and discards the
  reply if the remaining content is **≤ `ackMaxChars`** (default: 30).
 - If `HEARTBEAT_OK` is in the **middle** of a reply, it is not treated specially.
 - For alerts, do **not** include `HEARTBEAT_OK`; return only the alert text.
+- Heartbeat prompt text is sent **verbatim** as the user message. Clawdbot does
+  not append extra body text. The system prompt includes a Heartbeats section
+  and the run is flagged as a heartbeat internally.

 ### Stray `HEARTBEAT_OK` outside heartbeats
 If the model accidentally includes `HEARTBEAT_OK` at the start or end of a
@@ -35,11 +38,11 @@ and final replies:
 {
  agent: {
    heartbeat: {
-      every: "30m",           // duration string: ms|s|m|h (0m disables)
+      every: "30m",           // default: 30m (0m disables)
      model: "anthropic/claude-opus-4-5",
-      target: "last",          // last | whatsapp | telegram | none
-      to: "+15551234567",      // optional override for whatsapp/telegram
-      prompt: "HEARTBEAT",     // optional override
+      target: "last",          // last | whatsapp | telegram | discord | slack | signal | imessage | none
+      to: "+15551234567",      // optional provider-specific override (e.g. E.164 or chat id)
+      prompt: "Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.",
      ackMaxChars: 30          // max chars allowed after HEARTBEAT_OK
    }
  }
@@ -47,17 +50,28 @@ and final replies:
 ```

 ### Fields
- `every`: heartbeat interval (duration string; default unit minutes). Omit or set
-  to `0m` to disable.
+- `every`: heartbeat interval (duration string; default unit minutes). Default:
+  `30m`. Set to `0m` to disable.
 - `model`: optional model override for heartbeat runs (`provider/model`).
 - `target`: where heartbeat output is delivered.
  - `last` (default): send to the last used external provider.
-  - `whatsapp` / `telegram`: force the provider (optionally set `to`).
+  - `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage`: force the provider (optionally set `to`).
  - `none`: do not deliver externally; output stays in the session (WebChat-visible).
 - `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram).
- `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`).
+- `prompt`: optional override for the heartbeat body (default shown above). Safe to
+  change; heartbeat acks are still keyed off `HEARTBEAT_OK`.
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30).

+## Cost awareness
+Heartbeats run full agent turns. Shorter intervals burn more tokens. If you
+don’t need frequent checks, increase `every`, pick a cheaper `model`, or set
+`target: "none"` to keep results internal.
+
+## HEARTBEAT.md (optional)
+If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the
+agent to read it. Keep it tiny (short checklist or reminders) to avoid prompt
+bloat.
+
 ## Behavior
 - Runs in the main session (`main`, or `global` when scope is global).
 - Uses the main lane queue; if requests are in flight, the wake is retried.
@@ -66,6 +80,12 @@ and final replies:
 - If `target` resolves to no external destination (no last route or `none`), the
  heartbeat still runs but no outbound message is sent.

+## Ideas for use
+- Check up on the user (light, respectful pings during daytime).
+- Handle mundane tasks (triage inboxes, summarize queues, refresh notes).
+- Nudge on open loops or reminders.
+- Background monitoring (health checks, status polling, low-priority alerts).
+
 ## Wake hook
 - The gateway exposes a heartbeat wake hook so cron/jobs/webhooks can request an
  immediate run (`requestHeartbeatNow`).
--- a/docs/templates/AGENTS.md
+++ b/docs/templates/AGENTS.md
@@ -115,7 +115,12 @@ Skills provide your tools. When you need one, check its `SKILL.md`. Keep local n

 ## 💓 Heartbeats - Be Proactive!

-When you receive a `HEARTBEAT` message, don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
+When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
+
+Default heartbeat prompt:
+`Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
+
+You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small.

 **Things to check (rotate through these, 2-4 times per day):**
 - **Emails** - Any urgent unread messages?
--- a/docs/templates/HEARTBEAT.md
+++ b/docs/templates/HEARTBEAT.md
@@ -0,0 +1,8 @@
+---
+summary: "Workspace template for HEARTBEAT.md"
+read_when:
+  - Bootstrapping a workspace manually
+---
+# HEARTBEAT.md
+
+Keep this file empty unless you want a tiny checklist for heartbeat runs. Keep it small.
--- a/docs/thinking.md
+++ b/docs/thinking.md
@@ -38,7 +38,7 @@ read_when:
 - Elevated mode docs live in [`docs/elevated.md`](https://docs.clawd.bot/elevated).

 ## Heartbeats
- Heartbeat probe body is `HEARTBEAT`. Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
+- Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).

 ## Web chat UI
 - The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
--- a/docs/whatsapp.md
+++ b/docs/whatsapp.md
@@ -115,7 +115,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 ## Heartbeats
 - **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
 - **Agent heartbeat** is global (`agent.heartbeat.*`) and runs in the main session.
-  - Uses `HEARTBEAT` prompt + `HEARTBEAT_OK` skip behavior.
+  - Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) + `HEARTBEAT_OK` skip behavior.
  - Delivery defaults to the last used provider (or configured target).

 ## Reconnect behavior