feat(coding-agent): add persistent session heartbeat

[sethkarten]

Context

This is a draft implementation of persistent session heartbeats for long-running Prime Agent work. The goal is to let a daemon-backed session keep checking in on a cadence without needing an active /goal loop or an external tmux/script wrapper.

What changed

• Adds durable daemon-backed scheduler storage at cron-jobs.json under the agent config directory.
• Makes /heartbeat a goal-style single persistent session state:
  • /heartbeat or /heartbeat status
  • /heartbeat [--every <interval>] <instruction>
  • /heartbeat pause
  • /heartbeat resume
  • /heartbeat clear or /heartbeat stop
• Defaults /heartbeat <instruction> to every 5m when no interval is specified.
• Replaces the old model tool draft with goal-like tools: get_heartbeat, create_heartbeat, and update_heartbeat.
• Supports recurring intervals like every 30s, 30s, every 10m, cron aliases like @hourly, and five-field cron expressions through the heartbeat scheduler.
• Keeps the slash-command surface heartbeat-only; there is no /cron command in this draft.

How to try it

In a daemon-backed Prime Agent session:

/heartbeat check on me
/heartbeat status
/heartbeat --every 30s check on me
/heartbeat pause
/heartbeat resume
/heartbeat clear

Natural-language self-setup should work when tools are enabled, e.g.:

Set up a recurring heartbeat every 30 seconds to check on me.

Validation

• npm --workspace packages/coding-agent test -- cron-jobs.test.ts daemon-command.test.ts slash-commands.test.ts
• npm run check
• Pre-commit hook reran npm run check.

I also ran the full npm --workspace packages/coding-agent test; it still has unrelated extension-loader environment failures because local tests cannot import @earendil-works/pi-agent-core/dist/index.js, plus one existing git watcher timeout.

Review focus

• Whether /heartbeat should mirror /goal this closely.
• Whether the default interval should stay 5m.
• Whether seconds-level intervals should stay in this draft or be limited later.
• Whether richer TUI management should be separate from this first pass.

Known gaps / intentional limits

• Heartbeat schedules must be recurring.
• Fixed intervals support seconds/minutes/hours; cron expressions remain minute-granularity and local-time only.
• No weekday/month names like MON, no cron seconds field, and no timezone support for cron expressions.
• In-process connections can inspect no heartbeat but cannot set one; heartbeat scheduling is daemon-backed.

---

Note

Medium Risk
Background scheduler can inject prompts into live sessions (including model-initiated heartbeats), affecting cost and behavior; daemon now hard-requires agentDir and runs timers for the process lifetime.

Overview
Adds daemon-backed scheduled prompts so long-running sessions can fire agent turns on a timer without relying on /goal or external wrappers.

A new cron-jobs.json store and in-process scheduler support one-shot (in 10m, at <date>), interval (every 30s), and five-field cron schedules. When a job is due, the daemon loads or reattaches the target session and calls prompt with the stored text (follow-up if the session is already streaming).

User-facing surfaces: daemon cron list|add|cancel (add uses -- between schedule and message), /heartbeat in interactive mode (goal-style status / set / pause / resume / clear, default every 5m), and model tools get_heartbeat, create_heartbeat, update_heartbeat on daemon sessions. Heartbeats are a single recurring job per session (source: heartbeat); general cron jobs can target any session. In-process AgentConnection stubs return empty or error for these APIs.

Daemon startup now requires agentDir, starts the scheduler, and stops it on shutdown; protocol and client adapters gain cron_* and heartbeat_* commands.

^{Reviewed by Cursor Bugbot for commit 9cf6fb0. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add persistent session heartbeat and cron job scheduling to the coding agent daemon

• Introduces AgentCronJobStore and AgentCronScheduler in cron-jobs.ts for persistent, file-backed scheduling of prompts against long-running daemon sessions, supporting one-shot, interval, and cron expressions.
• Adds a cron subcommand to the daemon CLI for listing, adding, and cancelling cron jobs, with -- as a separator between schedule and free-form prompt text.
• Exposes /heartbeat as a built-in slash command in interactive mode; users can set, pause, resume, clear, and inspect a per-session recurring heartbeat from the UI.
• Extends the AgentConnection interface and both daemon and in-process implementations with listCronJobs, addCronJob, cancelCronJob, getHeartbeat, setHeartbeat, and updateHeartbeat methods; in-process connections throw to signal daemon-only capability.
• Wires heartbeat tool definitions into daemon session runtimes (including subagent runtimes) so the model can manage heartbeats directly as tools.
• Risk: daemon now requires agentDir to be set (throws in constructor if missing), and the scheduler starts on daemon startup, adding background timer activity.

^{Macroscope summarized 9cf6fb0.}

[macroscopeapp]

🟢 Low daemon/daemon-mode.ts:851

When cancelling an already-cancelled cron job, the daemon throws "No cron job found" even though the job exists. This happens because AgentCronJobStore.cancel() returns undefined for both "job not found" and "already cancelled" cases (since cancelled is never assigned when `job.status === "cancelled""), and the daemon doesn't distinguish between these two outcomes. Consider checking the job's existence separately from its cancellability, or returning a clearer status from the store to distinguish "not found" from "already cancelled".

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/src/modes/daemon/daemon-mode.ts around line 851:

When cancelling an already-cancelled cron job, the daemon throws "No cron job found" even though the job exists. This happens because `AgentCronJobStore.cancel()` returns `undefined` for both "job not found" and "already cancelled" cases (since `cancelled` is never assigned when `job.status === "cancelled""), and the daemon doesn't distinguish between these two outcomes. Consider checking the job's existence separately from its cancellability, or returning a clearer status from the store to distinguish "not found" from "already cancelled".

Evidence trail:
packages/coding-agent/src/core/cron-jobs.ts lines 86-99 (cancel method logic); packages/coding-agent/src/modes/daemon/daemon-mode.ts lines 848-855 (cron_cancel handler)

[macroscopeapp]

🟡 Medium daemon/daemon-mode.ts:347

runCronJob checks state.runtime.session.isStreaming before calling prompt(), then passes streamingBehavior based on that snapshot. But prompt() internally re-checks isStreaming after multiple await calls (goal command handling, extension commands, input events). If another client sends a prompt during this window, isStreaming becomes true but streamingBehavior was already computed as undefined, causing the cron job to fail with "Agent is already processing" instead of being properly queued.

Since streamingBehavior: "followUp" is silently ignored when the agent is not streaming (the if (this.isStreaming) block is skipped entirely), consider passing it unconditionally to eliminate the race.

-		await state.runtime.session.prompt(job.prompt, {
-			streamingBehavior: state.runtime.session.isStreaming ? "followUp" : undefined,
+		await state.runtime.session.prompt(job.prompt, {
+			streamingBehavior: "followUp",
			source: "rpc",
		});

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/src/modes/daemon/daemon-mode.ts around lines 347-353:

`runCronJob` checks `state.runtime.session.isStreaming` before calling `prompt()`, then passes `streamingBehavior` based on that snapshot. But `prompt()` internally re-checks `isStreaming` after multiple `await` calls (goal command handling, extension commands, input events). If another client sends a prompt during this window, `isStreaming` becomes `true` but `streamingBehavior` was already computed as `undefined`, causing the cron job to fail with "Agent is already processing" instead of being properly queued.

Since `streamingBehavior: "followUp"` is silently ignored when the agent is not streaming (the `if (this.isStreaming)` block is skipped entirely), consider passing it unconditionally to eliminate the race.

Evidence trail:
packages/coding-agent/src/modes/daemon/daemon-mode.ts:347-353 (runCronJob snapshots isStreaming before prompt call), packages/coding-agent/src/core/agent-session.ts:1883-1948 (prompt() with multiple await points before re-checking isStreaming at line 1936), packages/coding-agent/src/core/agent-session.ts:1689-1690 (isStreaming is a live getter on agent.state.isStreaming), packages/agent/src/agent.ts:470-482 (runWithLifecycle synchronously sets isStreaming = true at line 482), packages/agent/src/agent.ts:345-352 (agent.prompt() calls runPromptMessages → runWithLifecycle)

[macroscopeapp]

🟢 Low core/cron-jobs.ts:441

The range parsing in parseCronField silently truncates malformed ranges with multiple hyphens like "1-2-3" to "1-2". The destructuring const [startText, endText] = rangeText.split("-") ignores everything after the second hyphen, so invalid input is accepted and parsed incorrectly instead of throwing an error.

-		} else if (rangeText?.includes("-")) {
-			const [startText, endText] = rangeText.split("-");
+		} else if (rangeText?.includes("-")) {
+			const parts = rangeText.split("-");
+			if (parts.length !== 2) {
+				throw new Error(`Invalid cron range: ${rangeText}`);
+			}
+			const [startText, endText] = parts;

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/src/core/cron-jobs.ts around lines 441-443:

The range parsing in `parseCronField` silently truncates malformed ranges with multiple hyphens like `"1-2-3"` to `"1-2"`. The destructuring `const [startText, endText] = rangeText.split("-")` ignores everything after the second hyphen, so invalid input is accepted and parsed incorrectly instead of throwing an error.

Evidence trail:
...

[macroscopeapp]

🟢 Low daemon/daemon-mode.ts:394

createCronJobForState throws with the message "Heartbeats require a persisted session file" when no session file exists, but this is the cron job path, not heartbeat. This misleads users about which feature failed. Consider changing the message to reference cron jobs.

-    		throw new Error("Heartbeats require a persisted session file");
+    		throw new Error("Cron jobs require a persisted session file");

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/src/modes/daemon/daemon-mode.ts around lines 394-398:

`createCronJobForState` throws with the message "Heartbeats require a persisted session file" when no session file exists, but this is the cron job path, not heartbeat. This misleads users about which feature failed. Consider changing the message to reference cron jobs.

Evidence trail:
packages/coding-agent/src/modes/daemon/daemon-mode.ts lines 393-409 (createCronJobForState with 'Heartbeats' error message at line 397), lines 411-427 (createHeartbeatForState with the same message at line 415 where it's correct). git_grep confirms both occurrences.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9cf6fb0. Configure here.}

[cursor]

Scheduler races session restore

High Severity

The cron scheduler starts immediately while restoreActiveSessions still runs in the background. A due job can call getOrCreateCronJobSession and open the same sessionFile before restore finishes, so two runtimes may attach to one session file and interleave writes.

Additional Locations (1)

• packages/coding-agent/src/modes/daemon/daemon-mode.ts#L443-L449

 

^{Reviewed by Cursor Bugbot for commit 9cf6fb0. Configure here.}

[sethkarten]

Superseded by #170, which is now the single combined heartbeat draft PR directly against main.