A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
Steer heartbeats by default with configurable delivery mode (#358)
Seth Karten97d933bf6c9e
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.mdindex deef57a9bf..3d172e3fdb 100644--- a/packages/coding-agent/CHANGELOG.md+++ b/packages/coding-agent/CHANGELOG.md@@ -3,6 +3,7 @@## [Unreleased]- Added `/btw` and `/side` for one-turn inline side questions that use the current context without changing the main session ([ENG-4509](https://linear.app/primeintellect/issue/ENG-4509/add-btw-and-side-side-question-flows)).+- Changed scheduled heartbeat prompts to steer (interrupt the current turn) by default, with a `steer`/`follow_up` delivery mode selectable via `/heartbeat --steer|--follow-up` and the `rlm_heartbeat` skill's `delivery_mode` argument.- Changed the new-chat splash to show only version, model, and cwd metadata and rotate among five example prompts.- Fixed stale heartbeat jobs reopening archived, deleted, or concurrently terminated sessions ([ENG-4519](https://linear.app/primeintellect/issue/ENG-4519/heartbeats-rebirth-sessions-that-were-previously-killed)).diff --git a/packages/coding-agent/skills/rlm-heartbeat/SKILL.md b/packages/coding-agent/skills/rlm-heartbeat/SKILL.mdindex d7a6dc23d7..6ee2d995d8 100644--- a/packages/coding-agent/skills/rlm-heartbeat/SKILL.md+++ b/packages/coding-agent/skills/rlm-heartbeat/SKILL.md@@ -13,6 +13,7 @@ Call directly from IPython:```pythonawait rlm_heartbeat.create("check test progress", interval="5m", label="tests")+await rlm_heartbeat.create("watch build", delivery_mode="follow_up")await rlm_heartbeat.list()await rlm_heartbeat.update("job-id", status="pause")await rlm_heartbeat.delete("job-id")@@ -22,15 +23,25 @@ await rlm_heartbeat.delete("job-id")- `await rlm_heartbeat.list(include_inactive=False)` — list this session'sinternal RLM heartbeats. By default this includes active and paused entries.-- `await rlm_heartbeat.create(instruction, interval=None, label=None)` — create- a recurring heartbeat for this session. The default interval is every 5- minutes. Multiple RLM heartbeats may run at once; use labels to distinguish- them.+- `await rlm_heartbeat.create(instruction, interval=None, label=None,+ delivery_mode=None)` — create a recurring heartbeat for this session. The+ default interval is every 5 minutes. Multiple RLM heartbeats may run at once;+ use labels to distinguish them. `delivery_mode` is `"steer"` (default) or+ `"follow_up"`.- `await rlm_heartbeat.update(id, instruction=None, interval=None, label=None,- status=None)` — update one RLM heartbeat by id. `status` may be `"pause"` or- `"resume"`.+ status=None, delivery_mode=None)` — update one RLM heartbeat by id. `status`+ may be `"pause"` or `"resume"`; `delivery_mode` may be `"steer"` or+ `"follow_up"`.- `await rlm_heartbeat.delete(id)` — cancel one RLM heartbeat by id.+## Delivery mode++Each heartbeat has a delivery mode controlling how the scheduled prompt reaches+the session when it is busy:++- `steer` (default): interrupt the current turn so the heartbeat runs promptly.+- `follow_up`: wait for the current turn to finish before running the heartbeat.+## Rules- Use this only for agent-internal recurring checks and long-running taskdiff --git a/packages/coding-agent/skills/rlm-heartbeat/src/rlm_heartbeat/__init__.py b/packages/coding-agent/skills/rlm-heartbeat/src/rlm_heartbeat/__init__.pyindex 0f946a7d61..1f57d5f7b3 100644--- a/packages/coding-agent/skills/rlm-heartbeat/src/rlm_heartbeat/__init__.py+++ b/packages/coding-agent/skills/rlm-heartbeat/src/rlm_heartbeat/__init__.py@@ -12,6 +12,17 @@ from typing import Any, Literalfrom rlm import host_requestStatusUpdate = Literal["pause", "resume"]+DeliveryMode = Literal["steer", "follow_up"]+++def _normalize_delivery_mode(delivery_mode: DeliveryMode | None) -> str | None:+ if delivery_mode is None:+ return None+ if not isinstance(delivery_mode, str):+ raise TypeError(f"delivery_mode must be str or None, got {type(delivery_mode).__name__}")+ if delivery_mode not in {"steer", "follow_up"}:+ raise ValueError('delivery_mode must be "steer", "follow_up", or None')+ return delivery_modeasync def list(include_inactive: bool = False) -> dict[str, Any]:@@ -21,8 +32,18 @@ async def list(include_inactive: bool = False) -> dict[str, Any]:return await host_request("rlm_heartbeat.list", {"include_inactive": include_inactive})-async def create(instruction: str, interval: str | None = None, label: str | None = None) -> dict[str, Any]:- """Create an internal recurring heartbeat for the current agent session."""+async def create(+ instruction: str,+ interval: str | None = None,+ label: str | None = None,+ delivery_mode: DeliveryMode | None = None,+) -> dict[str, Any]:+ """Create an internal recurring heartbeat for the current agent session.++ delivery_mode controls how the scheduled prompt is delivered when the+ session is busy: "steer" (default) interrupts the current turn, "follow_up"+ waits for it to finish.+ """if not isinstance(instruction, str):raise TypeError(f"instruction must be str, got {type(instruction).__name__}")payload: dict[str, Any] = {"instruction": instruction}@@ -34,6 +55,9 @@ async def create(instruction: str, interval: str | None = None, label: str | Nonif not isinstance(label, str):raise TypeError(f"label must be str or None, got {type(label).__name__}")payload["label"] = label+ normalized_delivery_mode = _normalize_delivery_mode(delivery_mode)+ if normalized_delivery_mode is not None:+ payload["delivery_mode"] = normalized_delivery_modereturn await host_request("rlm_heartbeat.create", payload)@@ -43,6 +67,7 @@ async def update(interval: str | None = None,label: str | None = None,status: StatusUpdate | None = None,+ delivery_mode: DeliveryMode | None = None,) -> dict[str, Any]:"""Update one internal RLM heartbeat for the current agent session."""if not isinstance(id, str):@@ -64,6 +89,9 @@ async def update(if status not in {"pause", "resume"}:raise ValueError('status must be "pause", "resume", or None')payload["status"] = status+ normalized_delivery_mode = _normalize_delivery_mode(delivery_mode)+ if normalized_delivery_mode is not None:+ payload["delivery_mode"] = normalized_delivery_modereturn await host_request("rlm_heartbeat.update", payload)diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.tsindex bb652242cd..014dd2fabc 100644--- a/packages/coding-agent/src/core/agent-session.ts+++ b/packages/coding-agent/src/core/agent-session.ts@@ -93,6 +93,7 @@ import {loadContextTreeChildrenFromDisk,} from "./context-tree.js";import type { AgentCronJob, AgentRlmHeartbeatController, AgentRlmHeartbeatStatusUpdate } from "./cron-jobs.js";+import { normalizeHeartbeatDeliveryMode } from "./cron-jobs.js";import { DEFAULT_THINKING_LEVEL } from "./defaults.js";import { exportSessionToHtml, type ToolHtmlRenderer } from "./export-html/index.js";import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";@@ -416,6 +417,7 @@ type QueuedAgentMessage = UserMessage | CustomMessage;interface QueuedSteeringMessage {text: string;previewLabel?: string;+ queueKey?: string;agentMessageId?: string;message: QueuedAgentMessage;}@@ -1477,12 +1479,14 @@ export class AgentSession {if (payload.label !== undefined && typeof payload.label !== "string") {throw new Error("rlm_heartbeat.create label must be a string when provided");}+ const deliveryMode = normalizeHeartbeatDeliveryMode(payload.delivery_mode ?? payload.deliveryMode);return {heartbeat: rlmHeartbeatHostResponse(controller.createRlmHeartbeat({instruction: payload.instruction,interval: payload.interval,label: payload.label,+ deliveryMode,}),),};@@ -1503,11 +1507,14 @@ export class AgentSession {if (payload.status !== undefined && !isRlmHeartbeatStatusUpdate(payload.status)) {throw new Error('rlm_heartbeat.update status must be "pause" or "resume" when provided');}+ const rawDeliveryMode = payload.delivery_mode ?? payload.deliveryMode;+ const deliveryMode = normalizeHeartbeatDeliveryMode(rawDeliveryMode);if (payload.instruction === undefined &&payload.interval === undefined &&payload.label === undefined &&- payload.status === undefined+ payload.status === undefined &&+ rawDeliveryMode === undefined) {throw new Error("rlm_heartbeat.update requires at least one field to update");}@@ -1517,6 +1524,7 @@ export class AgentSession {interval: payload.interval,label: payload.label,status: payload.status,+ deliveryMode,});return { heartbeat: heartbeat ? rlmHeartbeatHostResponse(heartbeat) : null };}@@ -3032,7 +3040,11 @@ export class AgentSession {* @param images Optional image attachments to include with the message* @throws Error if text is an extension command*/- async steer(text: string, images?: ImageContent[]): Promise<void> {+ async steer(+ text: string,+ images?: ImageContent[],+ options: { queueKey?: string; agentMessageId?: string } = {},+ ): Promise<void> {// Check for extension commands (cannot be queued)if (text.startsWith("/")) {this._throwIfExtensionCommand(text);@@ -3042,7 +3054,10 @@ export class AgentSession {let expandedText = this._expandSkillCommand(text);expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);- await this._queueSteer(expandedText, images);+ await this._queueSteer(expandedText, images, {+ queueKey: options.queueKey,+ agentMessageId: options.agentMessageId,+ });}/**@@ -3076,12 +3091,14 @@ export class AgentSession {text: string,images?: ImageContent[],options: {+ queueKey?: string;agentMessageId?: string;content?: (TextContent | ImageContent)[];customMessage?: CustomMessage;} = {},): Promise<void> {await this._queueSteer(text, images, {+ queueKey: options.queueKey,agentMessageId: options.agentMessageId,content: options.content,message: options.customMessage,@@ -3143,7 +3160,11 @@ export class AgentSession {}return queued;}- await this._queueSteer(text, undefined, { agentMessageId: options.agentMessageId, content });+ await this._queueSteer(text, undefined, {+ agentMessageId: options.agentMessageId,+ queueKey: options.queueKey,+ content,+ });return true;} catch (error) {this._pendingNextTurnMessages.unshift(...pendingNextTurnMessages);@@ -3175,7 +3196,11 @@ export class AgentSession {}return queued;}- await this._queueSteer(text, undefined, { message: queuedMessage, previewLabel: options.previewLabel });+ await this._queueSteer(text, undefined, {+ message: queuedMessage,+ previewLabel: options.previewLabel,+ queueKey: options.queueKey,+ });return true;} catch (error) {this._pendingNextTurnMessages.unshift(...pendingNextTurnMessages);@@ -3191,6 +3216,7 @@ export class AgentSession {images?: ImageContent[],options: {agentMessageId?: string;+ queueKey?: string;content?: (TextContent | ImageContent)[];message?: QueuedAgentMessage;previewLabel?: string;@@ -3207,6 +3233,7 @@ export class AgentSession {this._steeringMessages.push({text,previewLabel: options.previewLabel,+ queueKey: options.queueKey,agentMessageId: options.agentMessageId,message,});@@ -3492,13 +3519,18 @@ export class AgentSession {}removeQueuedFollowUp(queueKey: string): boolean {- const removed = this._followUpMessages.filter((message) => message.queueKey === queueKey);- if (removed.length === 0) {+ const removedSteering = this._steeringMessages.filter((message) => message.queueKey === queueKey);+ const removedFollowUp = this._followUpMessages.filter((message) => message.queueKey === queueKey);+ if (removedSteering.length === 0 && removedFollowUp.length === 0) {return false;}+ this._steeringMessages = this._steeringMessages.filter((message) => message.queueKey !== queueKey);this._followUpMessages = this._followUpMessages.filter((message) => message.queueKey !== queueKey);- const removedMessages = new Set<AgentMessage>(removed.map((message) => message.message));- for (const message of removed) {+ const removedMessages = new Set<AgentMessage>([+ ...removedSteering.map((message) => message.message),+ ...removedFollowUp.map((message) => message.message),+ ]);+ for (const message of [...removedSteering, ...removedFollowUp]) {this._rejectAgentMessageDelivery(message.agentMessageId,new Error("Queued agent message was cleared before delivery."),@@ -6990,6 +7022,7 @@ function rlmHeartbeatHostResponse(job: AgentCronJob): Record<string, unknown> {id: job.id,status: job.status,label: job.label ?? null,+ delivery_mode: job.deliveryMode ?? "steer",instruction: job.prompt,schedule: job.schedule,created_at: job.createdAt,diff --git a/packages/coding-agent/src/core/cron-jobs.ts b/packages/coding-agent/src/core/cron-jobs.tsindex f388b75627..50c7a34bda 100644--- a/packages/coding-agent/src/core/cron-jobs.ts+++ b/packages/coding-agent/src/core/cron-jobs.ts@@ -10,6 +10,11 @@ export type AgentCronJobSource = "cron" | "heartbeat" | "rlm_heartbeat";export type AgentCronJobRuntimeKind = "top-level" | "subagent";export type AgentHeartbeatUpdateAction = "pause" | "resume" | "clear";export type AgentRlmHeartbeatStatusUpdate = "pause" | "resume";+/**+ * How a scheduled heartbeat prompt is delivered when the target session is busy:+ * "steer" interrupts the current turn, "follow_up" waits for it to finish.+ */+export type AgentHeartbeatDeliveryMode = "steer" | "follow_up";export interface AgentCronSchedule {kind: AgentCronScheduleKind;@@ -22,6 +27,8 @@ export interface AgentCronJob {status: AgentCronJobStatus;source?: AgentCronJobSource;runtimeKind?: AgentCronJobRuntimeKind;+ /** Delivery mode for heartbeat/rlm_heartbeat jobs when the session is busy. Defaults to "steer". */+ deliveryMode?: AgentHeartbeatDeliveryMode;activeSessionId: string;sessionId: string;sessionFile: string;@@ -48,6 +55,7 @@ export interface CreateAgentCronJobInput {scheduleText: string;source?: AgentCronJobSource;runtimeKind?: AgentCronJobRuntimeKind;+ deliveryMode?: AgentHeartbeatDeliveryMode;now?: Date;}@@ -76,13 +84,14 @@ const MAX_TIMEOUT_MS = 2_147_483_647;const ONE_SECOND_MS = 1000;const ONE_MINUTE_MS = 60_000;export const DEFAULT_HEARTBEAT_SCHEDULE = "every 5m";+export const DEFAULT_HEARTBEAT_DELIVERY_MODE: AgentHeartbeatDeliveryMode = "steer";export type ParsedHeartbeatCommand =| { type: "status" }| { type: "pause" }| { type: "resume" }| { type: "clear" }- | { type: "set"; schedule: string; instruction: string };+ | { type: "set"; schedule: string; instruction: string; deliveryMode?: AgentHeartbeatDeliveryMode };export interface AgentCronToolController {getHeartbeat(): AgentCronJob | undefined;@@ -90,13 +99,19 @@ export interface AgentCronToolController {export interface AgentRlmHeartbeatController {listRlmHeartbeats(options?: { includeInactive?: boolean }): AgentCronJob[];- createRlmHeartbeat(input: { instruction: string; interval?: string; label?: string }): AgentCronJob;+ createRlmHeartbeat(input: {+ instruction: string;+ interval?: string;+ label?: string;+ deliveryMode?: AgentHeartbeatDeliveryMode;+ }): AgentCronJob;updateRlmHeartbeat(input: {id: string;instruction?: string;interval?: string;label?: string;status?: AgentRlmHeartbeatStatusUpdate;+ deliveryMode?: AgentHeartbeatDeliveryMode;}): AgentCronJob | undefined;deleteRlmHeartbeat(id: string): AgentCronJob | undefined;}@@ -224,6 +239,7 @@ export class AgentCronJobStore {status: "active",source: "heartbeat",runtimeKind: input.runtimeKind,+ deliveryMode: input.deliveryMode ?? DEFAULT_HEARTBEAT_DELIVERY_MODE,activeSessionId: input.activeSessionId,sessionId: input.sessionId,sessionFile: input.sessionFile,@@ -270,6 +286,7 @@ export class AgentCronJobStore {status: "active",source: "rlm_heartbeat",runtimeKind: input.runtimeKind,+ deliveryMode: input.deliveryMode ?? DEFAULT_HEARTBEAT_DELIVERY_MODE,activeSessionId: input.activeSessionId,sessionId: input.sessionId,sessionFile: input.sessionFile,@@ -294,6 +311,7 @@ export class AgentCronJobStore {prompt?: string;scheduleText?: string;status?: AgentRlmHeartbeatStatusUpdate;+ deliveryMode?: AgentHeartbeatDeliveryMode;now?: Date;},): AgentCronJob | undefined {@@ -312,6 +330,9 @@ export class AgentCronJobStore {if (update.label !== undefined) {nextJob = { ...nextJob, label: normalizeOptionalLabel(update.label) };}+ if (update.deliveryMode !== undefined) {+ nextJob = { ...nextJob, deliveryMode: update.deliveryMode };+ }if (update.prompt !== undefined) {const prompt = update.prompt.trim();if (!prompt) {@@ -744,6 +765,22 @@ export function normalizeHeartbeatSchedule(input: string | undefined): string {return text;}+export function normalizeHeartbeatDeliveryMode(value: unknown): AgentHeartbeatDeliveryMode | undefined {+ if (value === undefined || value === null) {+ return undefined;+ }+ if (value === "steer" || value === "follow_up") {+ return value;+ }+ throw new Error('Heartbeat delivery mode must be "steer" or "follow_up"');+}++export function resolveHeartbeatStreamingBehavior(+ deliveryMode: AgentHeartbeatDeliveryMode | undefined,+): "steer" | "followUp" {+ return (deliveryMode ?? DEFAULT_HEARTBEAT_DELIVERY_MODE) === "follow_up" ? "followUp" : "steer";+}+export function parseHeartbeatCommand(input: string): ParsedHeartbeatCommand {const text = input.replace(/^\/heartbeat\b/, "").trim();if (!text || text === "status") {@@ -759,31 +796,50 @@ export function parseHeartbeatCommand(input: string): ParsedHeartbeatCommand {return { type: "clear" };}- const option = consumeEveryOption(text);+ const leadingDelivery = consumeDeliveryOption(text);+ let deliveryMode = leadingDelivery.deliveryMode;+ let remaining = leadingDelivery.rest;++ const option = consumeEveryOption(remaining);if (option) {- if (!option.rest) {- throw new Error("Usage: /heartbeat [--every <interval>] <instruction>");+ const trailingDelivery = consumeDeliveryOption(option.rest);+ deliveryMode = trailingDelivery.deliveryMode ?? deliveryMode;+ if (!trailingDelivery.rest) {+ throw new Error("Usage: /heartbeat [--every <interval>] [--steer|--follow-up] <instruction>");}return {type: "set",schedule: normalizeHeartbeatSchedule(option.interval),- instruction: option.rest,+ instruction: trailingDelivery.rest,+ ...(deliveryMode ? { deliveryMode } : {}),};}- const leadingSchedule = consumeLeadingEverySchedule(text);+ const leadingSchedule = consumeLeadingEverySchedule(remaining);if (leadingSchedule) {- if (!leadingSchedule.rest) {- throw new Error("Usage: /heartbeat [--every <interval>] <instruction>");+ const trailingDelivery = consumeDeliveryOption(leadingSchedule.rest);+ deliveryMode = trailingDelivery.deliveryMode ?? deliveryMode;+ if (!trailingDelivery.rest) {+ throw new Error("Usage: /heartbeat [--every <interval>] [--steer|--follow-up] <instruction>");}return {type: "set",schedule: normalizeHeartbeatSchedule(leadingSchedule.interval),- instruction: leadingSchedule.rest,+ instruction: trailingDelivery.rest,+ ...(deliveryMode ? { deliveryMode } : {}),};}- return { type: "set", schedule: DEFAULT_HEARTBEAT_SCHEDULE, instruction: text };+ remaining = remaining.trim();+ if (!remaining) {+ throw new Error("Usage: /heartbeat [--every <interval>] [--steer|--follow-up] <instruction>");+ }+ return {+ type: "set",+ schedule: DEFAULT_HEARTBEAT_SCHEDULE,+ instruction: remaining,+ ...(deliveryMode ? { deliveryMode } : {}),+ };}export function nextRunAtForSchedule(schedule: AgentCronSchedule, after: Date): Date | undefined {@@ -830,6 +886,70 @@ export function createAgentHeartbeatToolDefinitions(controller: AgentCronToolCon];}+function consumeDeliveryOption(text: string): { deliveryMode: AgentHeartbeatDeliveryMode | undefined; rest: string } {+ let rest = text.trim();+ if (/(?:^|\s)--deliver=?$/i.test(rest)) {+ throw new Error('Heartbeat delivery mode must be "steer" or "follow_up"');+ }+ let deliveryMode: AgentHeartbeatDeliveryMode | undefined;+ let leading = consumeLeadingDeliveryFlag(rest);+ while (leading) {+ deliveryMode = leading.deliveryMode;+ rest = leading.rest.trim();+ leading = consumeLeadingDeliveryFlag(rest);+ }++ let trailing = consumeTrailingDeliveryFlag(rest);+ let trailingDeliveryMode: AgentHeartbeatDeliveryMode | undefined;+ while (trailing) {+ // Consume all trailing flags, but keep the rightmost flag's mode because it+ // is textually latest and should win over earlier flags.+ trailingDeliveryMode ??= trailing.deliveryMode;+ rest = trailing.rest.trim();+ trailing = consumeTrailingDeliveryFlag(rest);+ }+ return { deliveryMode: trailingDeliveryMode ?? deliveryMode, rest };+}++function consumeLeadingDeliveryFlag(+ text: string,+): { deliveryMode: AgentHeartbeatDeliveryMode; rest: string } | undefined {+ const match = /^--(?:deliver(?:=|\s+)(\S+)|(steer)|(follow[-_]up))(?:\s+|$)([\s\S]*)$/i.exec(text);+ if (!match) {+ return undefined;+ }+ return {+ deliveryMode: parseDeliveryModeToken(match[1] ?? match[2] ?? match[3] ?? ""),+ rest: match[4]?.trim() ?? "",+ };+}++function consumeTrailingDeliveryFlag(+ text: string,+): { deliveryMode: AgentHeartbeatDeliveryMode; rest: string } | undefined {+ const deliverWithSpace = /^([\s\S]*?)\s+--deliver\s+(\S+)$/i.exec(text);+ if (deliverWithSpace) {+ return { deliveryMode: parseDeliveryModeToken(deliverWithSpace[2] ?? ""), rest: deliverWithSpace[1] ?? "" };+ }+ const deliverWithEquals = /^([\s\S]*?)\s+--deliver=(\S+)$/i.exec(text);+ if (deliverWithEquals) {+ return { deliveryMode: parseDeliveryModeToken(deliverWithEquals[2] ?? ""), rest: deliverWithEquals[1] ?? "" };+ }+ const shorthand = /^([\s\S]*?)\s+--(steer|follow[-_]up)$/i.exec(text);+ if (shorthand) {+ return { deliveryMode: parseDeliveryModeToken(shorthand[2] ?? ""), rest: shorthand[1] ?? "" };+ }+ return undefined;+}++function parseDeliveryModeToken(token: string): AgentHeartbeatDeliveryMode {+ const normalized = token.toLowerCase().replace("-", "_");+ if (normalized === "steer" || normalized === "follow_up") {+ return normalized;+ }+ throw new Error('Heartbeat delivery mode must be "steer" or "follow_up"');+}+function consumeEveryOption(text: string): { interval: string; rest: string } | undefined {const match =/^--every(?:=|\s+)(?:"([^"]+)"|'([^']+)'|(\d+\s*(?:s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours))|(\S+))(?:\s+|$)([\s\S]*)$/i.exec(@@ -855,7 +975,8 @@ function consumeLeadingEverySchedule(text: string): { interval: string; rest: strest: text.slice(match[0].length).trim()- .replace(/^--\s*/, "")+ // Strip only a standalone "--" separator, never a flag like "--follow-up".+ .replace(/^--(?=\s|$)/, "").trim(),};}@@ -865,15 +986,26 @@ export function isHeartbeatCronJob(job: AgentCronJob): boolean {}export function shouldDeferHeartbeatCronJob(job: AgentCronJob, activity: HeartbeatCronSessionActivity): boolean {- return (- isHeartbeatCronJob(job) &&- (activity.isStreaming ||- activity.isCompacting === true ||- activity.isRetrying === true ||- activity.isBashRunning ||- activity.hasAcceptedPromptInFlight === true ||- activity.pendingMessageCount > 0)- );+ if (!isHeartbeatCronJob(job)) {+ return false;+ }+ // States where delivering a heartbeat is unsafe or would stack redundant work,+ // regardless of delivery mode.+ const busyBesidesStreaming =+ activity.isCompacting === true ||+ activity.isRetrying === true ||+ activity.isBashRunning ||+ activity.hasAcceptedPromptInFlight === true ||+ activity.pendingMessageCount > 0;+ if (busyBesidesStreaming) {+ return true;+ }+ // "steer" heartbeats interrupt the current turn, so a plain streaming turn must+ // not defer them; "follow_up" heartbeats wait, so streaming still defers.+ if (resolveHeartbeatStreamingBehavior(job.deliveryMode) === "steer") {+ return false;+ }+ return activity.isStreaming;}function nextCronRunAfter(expression: string, after: Date): Date {@@ -1070,6 +1202,9 @@ function isAgentCronJob(value: unknown): value is AgentCronJob {(candidate.runtimeKind === undefined ||candidate.runtimeKind === "top-level" ||candidate.runtimeKind === "subagent") &&+ (candidate.deliveryMode === undefined ||+ candidate.deliveryMode === "steer" ||+ candidate.deliveryMode === "follow_up") &&typeof candidate.activeSessionId === "string" &&typeof candidate.sessionId === "string" &&typeof candidate.sessionFile === "string" &&diff --git a/packages/coding-agent/src/core/slash-commands.ts b/packages/coding-agent/src/core/slash-commands.tsindex 69b84f5fca..a0d6cdcb4c 100644--- a/packages/coding-agent/src/core/slash-commands.ts+++ b/packages/coding-agent/src/core/slash-commands.ts@@ -89,8 +89,9 @@ const CANONICAL_BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [},{name: "heartbeat",- description: "Set or view a persistent heartbeat; supports pause, resume, stop, and clear",- argumentHint: "[status|pause|resume|stop|every <duration> <instruction>]",+ description:+ "Set or view a persistent heartbeat; delivery defaults to steer, use --follow-up to queue; supports pause, resume, stop, and clear",+ argumentHint: "[status|pause|resume|stop|[every <duration>] [--steer|--follow-up] <instruction>]",takesArgument: true,},{ name: "resume", description: "Resume a different session" },diff --git a/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts b/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.tsindex c471da5b26..b1ec3f9a42 100644--- a/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts+++ b/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts@@ -3,7 +3,7 @@ import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core"import type { ImageContent, Transport } from "@earendil-works/pi-ai";import type { CompactionResult } from "../../core/compaction/index.js";import type { ContextTreeNode } from "../../core/context-tree.js";-import type { AgentCronJob, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";+import type { AgentCronJob, AgentHeartbeatDeliveryMode, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";import type { RefinementResult } from "../../core/refinement/index.js";import type { DeleteSessionFileResult } from "../../core/session-file-actions.js";import type { SessionStats } from "../../core/session-stats.js";@@ -343,12 +343,17 @@ export class DaemonAgentConnection implements AgentConnection {return data.heartbeat ?? undefined;}- async setHeartbeat(schedule: string, instruction: string): Promise<AgentCronJob> {+ async setHeartbeat(+ schedule: string,+ instruction: string,+ deliveryMode?: AgentHeartbeatDeliveryMode,+ ): Promise<AgentCronJob> {const data = await this.requestData<{ heartbeat: AgentCronJob }>({type: "heartbeat_set",activeSessionId: this.activeSessionId,schedule,prompt: instruction,+ ...(deliveryMode ? { deliveryMode } : {}),});return data.heartbeat;}diff --git a/packages/coding-agent/src/modes/agent-connection/in-process-agent-connection.ts b/packages/coding-agent/src/modes/agent-connection/in-process-agent-connection.tsindex 7649d6cb98..0c2aa61d51 100644--- a/packages/coding-agent/src/modes/agent-connection/in-process-agent-connection.ts+++ b/packages/coding-agent/src/modes/agent-connection/in-process-agent-connection.ts@@ -4,7 +4,7 @@ import type { ImageContent, Transport } from "@earendil-works/pi-ai";import type { AgentSessionRuntime } from "../../core/agent-session-runtime.js";import type { CompactionResult } from "../../core/compaction/index.js";import type { ContextTreeNode } from "../../core/context-tree.js";-import type { AgentCronJob, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";+import type { AgentCronJob, AgentHeartbeatDeliveryMode, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";import type { RefinementResult } from "../../core/refinement/index.js";import { type DeleteSessionFileResult, deleteSessionFile } from "../../core/session-file-actions.js";import { SessionManager } from "../../core/session-manager.js";@@ -178,7 +178,11 @@ export class InProcessAgentConnection implements AgentConnection {return undefined;}- async setHeartbeat(_schedule: string, _instruction: string): Promise<AgentCronJob> {+ async setHeartbeat(+ _schedule: string,+ _instruction: string,+ _deliveryMode?: AgentHeartbeatDeliveryMode,+ ): Promise<AgentCronJob> {throw new Error("Heartbeats require daemon mode");}diff --git a/packages/coding-agent/src/modes/agent-connection/types.ts b/packages/coding-agent/src/modes/agent-connection/types.tsindex 2af19911f1..69b4f4e202 100644--- a/packages/coding-agent/src/modes/agent-connection/types.ts+++ b/packages/coding-agent/src/modes/agent-connection/types.ts@@ -3,7 +3,7 @@ import type { Api, ImageContent, Model, TextContent, Transport, Usage } from "@eimport type { AuthSourceToken } from "../../core/auth-storage.js";import type { CompactionResult } from "../../core/compaction/index.js";import type { ContextTreeNode } from "../../core/context-tree.js";-import type { AgentCronJob, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";+import type { AgentCronJob, AgentHeartbeatDeliveryMode, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";import type { ReplayBuiltInToolName } from "../../core/extensions/index.js";import type { GoalState } from "../../core/goals.js";import type { RefinementResult } from "../../core/refinement/index.js";@@ -541,7 +541,11 @@ export interface AgentConnection {addCronJob(schedule: string, prompt: string): Promise<AgentCronJob>;cancelCronJob(jobId: string): Promise<AgentCronJob>;getHeartbeat(): Promise<AgentCronJob | undefined>;- setHeartbeat(schedule: string, instruction: string): Promise<AgentCronJob>;+ setHeartbeat(+ schedule: string,+ instruction: string,+ deliveryMode?: AgentHeartbeatDeliveryMode,+ ): Promise<AgentCronJob>;updateHeartbeat(action: AgentHeartbeatUpdateAction): Promise<AgentCronJob | undefined>;getUserMessagesForForking(): Promise<AgentConnectionUserMessage[]>;getLastAssistantText(): Promise<string | undefined>;diff --git a/packages/coding-agent/src/modes/daemon/daemon-mode.ts b/packages/coding-agent/src/modes/daemon/daemon-mode.tsindex 5a10efbbc8..a28aa0f227 100644--- a/packages/coding-agent/src/modes/daemon/daemon-mode.ts+++ b/packages/coding-agent/src/modes/daemon/daemon-mode.ts@@ -64,11 +64,14 @@ import {type AgentCronJob,AgentCronJobStore,AgentCronScheduler,+ type AgentHeartbeatDeliveryMode,type AgentHeartbeatUpdateAction,createAgentHeartbeatToolDefinitions,DEFAULT_HEARTBEAT_SCHEDULE,isHeartbeatCronJob,+ normalizeHeartbeatDeliveryMode,normalizeHeartbeatSchedule,+ resolveHeartbeatStreamingBehavior,shouldDeferHeartbeatCronJob,} from "../../core/cron-jobs.js";import type {@@ -697,11 +700,12 @@ export class AgentDaemon {return current && this.isCronJobRunnableForState(current, state, requirePersistedJob) ? current : undefined;};if (isHeartbeatCronJob(runnableJob)) {+ const streamingBehavior = resolveHeartbeatStreamingBehavior(runnableJob.deliveryMode);const didPrompt = await this.promptHeartbeatWithAgentMessagePreparingGuard(state,runnableJob,{- streamingBehavior: "followUp",+ streamingBehavior,followUpQueueKey: `heartbeat:${runnableJob.id}`,source: "rpc",},@@ -734,7 +738,7 @@ export class AgentDaemon {): Promise<boolean> {return this.withAgentMessagePreparingGuard(state,- (session) => {+ (session, clearPreparing) => {const prompt =options?.agentMessageId === undefined? session.prompt.bind(session)@@ -742,6 +746,9 @@ export class AgentDaemon {return prompt(message, {...options,preflightResult: (didSucceed) => {+ if (didSucceed && session.isStreaming) {+ clearPreparing();+ }options?.preflightResult?.(didSucceed);},});@@ -759,10 +766,13 @@ export class AgentDaemon {let promptJob = job;return this.withAgentMessagePreparingGuard(state,- (session) =>+ (session, clearPreparing) =>session.promptHeartbeat(promptJob, {...options,preflightResult: (didSucceed) => {+ if (didSucceed && session.isStreaming) {+ clearPreparing();+ }options?.preflightResult?.(didSucceed);},}),@@ -782,7 +792,7 @@ export class AgentDaemon {private async withAgentMessagePreparingGuard(state: ActiveSessionState,- run: (session: AgentSession) => Promise<void>,+ run: (session: AgentSession, clearPreparing: () => void) => Promise<void>,canRun?: () => boolean,): Promise<boolean> {const activeSessionId = state.activeSessionId;@@ -805,11 +815,11 @@ export class AgentDaemon {};try {await this.agentMessageTargetLocks.get(activeSessionId)?.catch(() => undefined);- const session = state.runtime.session;if (canRun && !canRun()) {return false;}- await run(session);+ const session = state.runtime.session;+ await run(session, clearPreparing);return true;} finally {clearPreparing();@@ -835,7 +845,12 @@ export class AgentDaemon {return job;}- private createHeartbeatForState(state: ActiveSessionState, schedule: string, instruction: string): AgentCronJob {+ private createHeartbeatForState(+ state: ActiveSessionState,+ schedule: string,+ instruction: string,+ deliveryMode?: AgentHeartbeatDeliveryMode,+ ): AgentCronJob {const session = state.runtime.session;const sessionFile = session.sessionFile;if (!sessionFile) {@@ -850,6 +865,7 @@ export class AgentDaemon {runtimeKind: state.runtime.metadata.kind,scheduleText: normalizeHeartbeatSchedule(schedule),prompt: instruction,+ deliveryMode: deliveryMode ?? previousHeartbeat?.deliveryMode,});if (previousHeartbeat) {this.removeQueuedHeartbeatFollowUp(state, previousHeartbeat);@@ -877,7 +893,7 @@ export class AgentDaemon {private createRlmHeartbeatForState(state: ActiveSessionState,- input: { instruction: string; interval?: string; label?: string },+ input: { instruction: string; interval?: string; label?: string; deliveryMode?: AgentHeartbeatDeliveryMode },): AgentCronJob {const session = state.runtime.session;const sessionFile = session.sessionFile;@@ -893,6 +909,7 @@ export class AgentDaemon {label: input.label,scheduleText: normalizeHeartbeatSchedule(input.interval ?? DEFAULT_HEARTBEAT_SCHEDULE),prompt: input.instruction,+ deliveryMode: input.deliveryMode,});this.cronScheduler.wake();return job;@@ -900,16 +917,29 @@ export class AgentDaemon {private updateRlmHeartbeatForState(state: ActiveSessionState,- input: { id: string; instruction?: string; interval?: string; label?: string; status?: "pause" | "resume" },+ input: {+ id: string;+ instruction?: string;+ interval?: string;+ label?: string;+ status?: "pause" | "resume";+ deliveryMode?: AgentHeartbeatDeliveryMode;+ },): AgentCronJob | undefined {const job = this.cronStore.updateRlmHeartbeat(state.activeSessionId, input.id, {label: input.label,prompt: input.instruction,scheduleText: input.interval ? normalizeHeartbeatSchedule(input.interval) : undefined,status: input.status,+ deliveryMode: input.deliveryMode,});if (job) {- if (input.instruction !== undefined || input.interval !== undefined || input.status === "pause") {+ if (+ input.instruction !== undefined ||+ input.interval !== undefined ||+ input.status === "pause" ||+ input.deliveryMode !== undefined+ ) {this.removeQueuedHeartbeatFollowUp(state, job);}this.cronScheduler.wake();@@ -1625,12 +1655,16 @@ export class AgentDaemon {const state = this.getSessionState(command.activeSessionId);if (command.expandPromptTemplates === false) {await state.runtime.session.restoreSteeringMessage(command.message, command.images, {+ queueKey: command.queueKey,agentMessageId: command.agentMessageId,content: command.content,customMessage: command.customMessage,});} else {- await state.runtime.session.steer(command.message, command.images);+ await state.runtime.session.steer(command.message, command.images, {+ queueKey: command.queueKey,+ agentMessageId: command.agentMessageId,+ });}return success(command.id, "steer");}@@ -1923,7 +1957,8 @@ export class AgentDaemon {case "heartbeat_set": {const state = this.getSessionState(command.activeSessionId);- const heartbeat = this.createHeartbeatForState(state, command.schedule, command.prompt);+ const deliveryMode = normalizeHeartbeatDeliveryMode(command.deliveryMode);+ const heartbeat = this.createHeartbeatForState(state, command.schedule, command.prompt, deliveryMode);return success(command.id, "heartbeat_set", { heartbeat });}@@ -2552,6 +2587,7 @@ export class AgentDaemon {message: message.text,...(message.content ? { content: message.content } : {}),...(message.images ? { images: message.images } : {}),+ ...(message.queueKey ? { queueKey: message.queueKey } : {}),...(message.agentMessageId ? { agentMessageId: message.agentMessageId } : {}),...(message.customMessage ? { customMessage: message.customMessage } : {}),})),diff --git a/packages/coding-agent/src/modes/daemon/daemon-protocol.ts b/packages/coding-agent/src/modes/daemon/daemon-protocol.tsindex 8682a85291..72b5eb5b6a 100644--- a/packages/coding-agent/src/modes/daemon/daemon-protocol.ts+++ b/packages/coding-agent/src/modes/daemon/daemon-protocol.ts@@ -7,7 +7,7 @@ import type {} from "../../core/agent-messages.js";import type { AgentSessionRuntimeConfig } from "../../core/agent-session-config.js";import type { AgentSessionRuntimeMetadata } from "../../core/agent-session-runtime.js";-import type { AgentCronJob, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";+import type { AgentCronJob, AgentHeartbeatDeliveryMode, AgentHeartbeatUpdateAction } from "../../core/cron-jobs.js";import type { CustomMessage } from "../../core/messages.js";import type { SessionCwdIssue } from "../../core/session-cwd.js";import type { DeleteSessionFileResult } from "../../core/session-file-actions.js";@@ -285,6 +285,7 @@ export type DaemonCommand =message: string;content?: (TextContent | ImageContent)[];images?: ImageContent[];+ queueKey?: string;expandPromptTemplates?: boolean;agentMessageId?: string;customMessage?: CustomMessage;@@ -349,7 +350,14 @@ export type DaemonCommand =| { id?: string; type: "cron_add"; activeSessionId: string; schedule: string; prompt: string }| { id?: string; type: "cron_cancel"; jobId: string }| { id?: string; type: "heartbeat_get"; activeSessionId: string }- | { id?: string; type: "heartbeat_set"; activeSessionId: string; schedule: string; prompt: string }+ | {+ id?: string;+ type: "heartbeat_set";+ activeSessionId: string;+ schedule: string;+ prompt: string;+ deliveryMode?: AgentHeartbeatDeliveryMode;+ }| { id?: string; type: "heartbeat_update"; activeSessionId: string; action: AgentHeartbeatUpdateAction }| { id?: string; type: "set_model"; activeSessionId: string; provider: string; modelId: string }| { id?: string; type: "cycle_model"; activeSessionId: string; direction?: "forward" | "backward" }diff --git a/packages/coding-agent/src/modes/interactive/interactive-mode.ts b/packages/coding-agent/src/modes/interactive/interactive-mode.tsindex 7d8563af69..550bfabb42 100644--- a/packages/coding-agent/src/modes/interactive/interactive-mode.ts+++ b/packages/coding-agent/src/modes/interactive/interactive-mode.ts@@ -67,7 +67,7 @@ import {uploadAgentTraceFile,} from "../../core/agent-traces.js";import { isNoModelsAvailableMessage } from "../../core/auth-guidance.js";-import { type AgentCronJob, parseHeartbeatCommand } from "../../core/cron-jobs.js";+import { type AgentCronJob, DEFAULT_HEARTBEAT_DELIVERY_MODE, parseHeartbeatCommand } from "../../core/cron-jobs.js";import type {AutocompleteProviderFactory,ContextUsage,@@ -425,6 +425,16 @@ const HEARTBEAT_ARGUMENT_COMPLETIONS: AutocompleteItem[] = [label: "every <duration> <instruction>",description: "Set an interval, then add an instruction: /heartbeat every 10s Scan the logs",},+ {+ value: "--steer ",+ label: "--steer <instruction>",+ description: "Deliver by interrupting the current turn (default)",+ },+ {+ value: "--follow-up ",+ label: "--follow-up <instruction>",+ description: "Deliver as a follow-up after the current turn finishes",+ },];const DEAD_TERMINAL_ERROR_CODES = new Set(["EIO", "EPIPE", "ENOTCONN"]);@@ -8196,9 +8206,15 @@ export class InteractiveMode {return;}case "set": {- const heartbeat = await this.agentConnection.setHeartbeat(command.schedule, command.instruction);+ const heartbeat = await this.agentConnection.setHeartbeat(+ command.schedule,+ command.instruction,+ command.deliveryMode,+ );this.patchConnectionState({ heartbeat });- this.showStatus(`Heartbeat set\nNext run: ${heartbeat.nextRunAt ?? "-"}`);+ this.showStatus(+ `Heartbeat set\nDelivery: ${heartbeat.deliveryMode ?? DEFAULT_HEARTBEAT_DELIVERY_MODE}\nNext run: ${heartbeat.nextRunAt ?? "-"}`,+ );return;}case "pause": {@@ -8249,6 +8265,7 @@ export class InteractiveMode {"",`${theme.fg("dim", "Status:")} ${job.status}`,`${theme.fg("dim", "Every:")} ${job.schedule.expression}`,+ `${theme.fg("dim", "Delivery:")} ${job.deliveryMode ?? DEFAULT_HEARTBEAT_DELIVERY_MODE}`,`${theme.fg("dim", "Instruction:")} ${job.prompt}`,`${theme.fg("dim", "Next:")} ${next}`,`${theme.fg("dim", "Last:")} ${last}`,diff --git a/packages/coding-agent/test/cron-jobs.test.ts b/packages/coding-agent/test/cron-jobs.test.tsindex 525e9b7413..add488b48e 100644--- a/packages/coding-agent/test/cron-jobs.test.ts+++ b/packages/coding-agent/test/cron-jobs.test.ts@@ -7,8 +7,10 @@ import {AgentCronJobStore,AgentCronScheduler,createAgentHeartbeatToolDefinitions,+ normalizeHeartbeatDeliveryMode,parseAgentCronSchedule,parseHeartbeatCommand,+ resolveHeartbeatStreamingBehavior,shouldDeferHeartbeatCronJob,} from "../src/core/cron-jobs.js";@@ -49,7 +51,7 @@ describe("parseHeartbeatCommand", () => {expect(parseHeartbeatCommand("/heartbeat stop")).toEqual({ type: "clear" });});- it("defaults new heartbeat instructions to every five minutes", () => {+ it("leaves delivery mode unset when an instruction omits the delivery option", () => {expect(parseHeartbeatCommand("/heartbeat check on me")).toEqual({type: "set",schedule: "every 5m",@@ -74,6 +76,82 @@ describe("parseHeartbeatCommand", () => {instruction: "check status",});});++ it("opts into follow-up delivery via --follow-up before or after the interval", () => {+ expect(parseHeartbeatCommand("/heartbeat check on me --follow-up")).toEqual({+ type: "set",+ schedule: "every 5m",+ instruction: "check on me",+ deliveryMode: "follow_up",+ });+ expect(parseHeartbeatCommand("/heartbeat --follow-up check on me")).toEqual({+ type: "set",+ schedule: "every 5m",+ instruction: "check on me",+ deliveryMode: "follow_up",+ });+ expect(parseHeartbeatCommand("/heartbeat --follow-up --every 30s check on me")).toEqual({+ type: "set",+ schedule: "every 30s",+ instruction: "check on me",+ deliveryMode: "follow_up",+ });+ expect(parseHeartbeatCommand("/heartbeat every 10m --follow-up check status")).toEqual({+ type: "set",+ schedule: "every 10m",+ instruction: "check status",+ deliveryMode: "follow_up",+ });+ expect(parseHeartbeatCommand("/heartbeat --deliver follow_up check status")).toEqual({+ type: "set",+ schedule: "every 5m",+ instruction: "check status",+ deliveryMode: "follow_up",+ });+ expect(parseHeartbeatCommand("/heartbeat check status --deliver=follow_up")).toEqual({+ type: "set",+ schedule: "every 5m",+ instruction: "check status",+ deliveryMode: "follow_up",+ });+ });++ it("rejects invalid delivery mode values in delivery flag positions", () => {+ for (const command of [+ "/heartbeat --deliver",+ "/heartbeat --deliver=",+ "/heartbeat check status --deliver",+ "/heartbeat check status --deliver=",+ ]) {+ expect(() => parseHeartbeatCommand(command)).toThrow('Heartbeat delivery mode must be "steer" or "follow_up"');+ }+ expect(() => parseHeartbeatCommand("/heartbeat --deliver later check status")).toThrow(+ 'Heartbeat delivery mode must be "steer" or "follow_up"',+ );+ expect(() => parseHeartbeatCommand("/heartbeat check status --deliver=later")).toThrow(+ 'Heartbeat delivery mode must be "steer" or "follow_up"',+ );+ expect(() => parseHeartbeatCommand("/heartbeat every 10m --deliver later check status")).toThrow(+ 'Heartbeat delivery mode must be "steer" or "follow_up"',+ );+ });++ it("keeps delivery-like flags in the middle of an instruction as instruction text", () => {+ expect(parseHeartbeatCommand("/heartbeat remind me to mention --follow-up in docs")).toEqual({+ type: "set",+ schedule: "every 5m",+ instruction: "remind me to mention --follow-up in docs",+ });+ });++ it("accepts an explicit --steer flag that keeps the default delivery mode", () => {+ expect(parseHeartbeatCommand("/heartbeat --steer check on me")).toEqual({+ type: "set",+ schedule: "every 5m",+ instruction: "check on me",+ deliveryMode: "steer",+ });+ });});describe("AgentCronJobStore", () => {@@ -208,6 +286,54 @@ describe("AgentCronJobStore", () => {expect(store.list().find((job) => job.id === first.id)).toMatchObject({ status: "cancelled" });});+ it("defaults heartbeats to steer delivery and persists an explicit follow_up opt-out", () => {+ const store = new AgentCronJobStore(makeStorePath(tempDirs));+ const steerHeartbeat = store.createHeartbeat({+ activeSessionId: "active-1",+ sessionId: "session-1",+ sessionFile: "/tmp/session.jsonl",+ cwd: "/tmp/project",+ scheduleText: "every 5m",+ prompt: "steer by default",+ now: start,+ });+ expect(steerHeartbeat.deliveryMode).toBe("steer");++ const followUpHeartbeat = store.createHeartbeat({+ activeSessionId: "active-2",+ sessionId: "session-2",+ sessionFile: "/tmp/session-2.jsonl",+ cwd: "/tmp/project",+ scheduleText: "every 5m",+ prompt: "queue as follow-up",+ deliveryMode: "follow_up",+ now: start,+ });+ expect(followUpHeartbeat.deliveryMode).toBe("follow_up");+ expect(store.getHeartbeat("active-2")).toMatchObject({ deliveryMode: "follow_up" });+ });++ it("defaults RLM heartbeats to steer delivery and updates the delivery mode", () => {+ const store = new AgentCronJobStore(makeStorePath(tempDirs));+ const rlmHeartbeat = store.createRlmHeartbeat({+ activeSessionId: "active-1",+ sessionId: "session-1",+ sessionFile: "/tmp/session.jsonl",+ cwd: "/tmp/project",+ scheduleText: "every 5m",+ prompt: "watch progress",+ now: start,+ });+ expect(rlmHeartbeat.deliveryMode).toBe("steer");++ const updated = store.updateRlmHeartbeat("active-1", rlmHeartbeat.id, {+ deliveryMode: "follow_up",+ now: new Date("2026-01-01T12:35:00.000Z"),+ });+ expect(updated).toMatchObject({ id: rlmHeartbeat.id, deliveryMode: "follow_up" });+ expect(store.listRlmHeartbeats("active-1")[0]).toMatchObject({ deliveryMode: "follow_up" });+ });+it("pauses, resumes, and clears heartbeat state", () => {const store = new AgentCronJobStore(makeStorePath(tempDirs));const job = store.createHeartbeat({@@ -832,9 +958,9 @@ describe("shouldDeferHeartbeatCronJob", () => {runCount: 0,};- it("defers user and RLM heartbeats while the target session is working", () => {+ it("defers follow-up heartbeats while the target session is working", () => {for (const source of ["heartbeat", "rlm_heartbeat"] as const) {- const job = { ...baseJob, source };+ const job = { ...baseJob, source, deliveryMode: "follow_up" as const };expect(shouldDeferHeartbeatCronJob(job, {@@ -860,6 +986,67 @@ describe("shouldDeferHeartbeatCronJob", () => {}});+ it("lets steer heartbeats interrupt a plain streaming turn", () => {+ for (const source of ["heartbeat", "rlm_heartbeat"] as const) {+ // Default (undefined) delivery mode is steer.+ for (const job of [+ { ...baseJob, source },+ { ...baseJob, source, deliveryMode: "steer" as const },+ ]) {+ expect(+ shouldDeferHeartbeatCronJob(job, {+ isStreaming: true,+ isBashRunning: false,+ pendingMessageCount: 0,+ }),+ ).toBe(false);+ }+ }+ });++ it("defers steer heartbeats when delivering would be unsafe or would stack work", () => {+ const job = { ...baseJob, source: "heartbeat" as const, deliveryMode: "steer" as const };++ expect(+ shouldDeferHeartbeatCronJob(job, {+ isStreaming: true,+ isCompacting: true,+ isBashRunning: false,+ pendingMessageCount: 0,+ }),+ ).toBe(true);+ expect(+ shouldDeferHeartbeatCronJob(job, {+ isStreaming: false,+ isBashRunning: true,+ pendingMessageCount: 0,+ }),+ ).toBe(true);+ expect(+ shouldDeferHeartbeatCronJob(job, {+ isStreaming: false,+ isBashRunning: false,+ pendingMessageCount: 1,+ }),+ ).toBe(true);+ expect(+ shouldDeferHeartbeatCronJob(job, {+ isStreaming: false,+ isRetrying: true,+ isBashRunning: false,+ pendingMessageCount: 0,+ }),+ ).toBe(true);+ expect(+ shouldDeferHeartbeatCronJob(job, {+ isStreaming: false,+ isBashRunning: false,+ hasAcceptedPromptInFlight: true,+ pendingMessageCount: 0,+ }),+ ).toBe(true);+ });+it("allows heartbeats when the target session is idle", () => {expect(shouldDeferHeartbeatCronJob(@@ -879,6 +1066,24 @@ describe("shouldDeferHeartbeatCronJob", () => {});});+describe("heartbeat delivery mode", () => {+ it("normalizes valid delivery modes and rejects invalid ones", () => {+ expect(normalizeHeartbeatDeliveryMode(undefined)).toBeUndefined();+ expect(normalizeHeartbeatDeliveryMode(null)).toBeUndefined();+ expect(normalizeHeartbeatDeliveryMode("steer")).toBe("steer");+ expect(normalizeHeartbeatDeliveryMode("follow_up")).toBe("follow_up");+ expect(() => normalizeHeartbeatDeliveryMode("followup")).toThrow(+ 'Heartbeat delivery mode must be "steer" or "follow_up"',+ );+ });++ it("resolves delivery mode to a streaming behavior, defaulting to steer", () => {+ expect(resolveHeartbeatStreamingBehavior(undefined)).toBe("steer");+ expect(resolveHeartbeatStreamingBehavior("steer")).toBe("steer");+ expect(resolveHeartbeatStreamingBehavior("follow_up")).toBe("followUp");+ });+});+describe("createAgentHeartbeatToolDefinitions", () => {it("exposes only read-only user heartbeat inspection to the model", () => {const tools = createAgentHeartbeatToolDefinitions({diff --git a/packages/coding-agent/test/daemon-mode.test.ts b/packages/coding-agent/test/daemon-mode.test.tsindex 5169940c55..5ca64e320d 100644--- a/packages/coding-agent/test/daemon-mode.test.ts+++ b/packages/coding-agent/test/daemon-mode.test.ts@@ -2872,7 +2872,12 @@ describe("daemon mode helpers", () => {).runCronJob.bind(daemon);const result = await runCronJob(- makeCronJob({ id: "heartbeat-1", source: "heartbeat", activeSessionId: state.activeSessionId }),+ makeCronJob({+ id: "heartbeat-1",+ source: "heartbeat",+ activeSessionId: state.activeSessionId,+ deliveryMode: "follow_up",+ }),);expect(result).toBe("skipped");@@ -2922,10 +2927,20 @@ describe("daemon mode helpers", () => {).runCronJob.bind(daemon);const first = await runCronJob(- makeCronJob({ id: "rlm-1", source: "rlm_heartbeat", activeSessionId: state.activeSessionId }),+ makeCronJob({+ id: "rlm-1",+ source: "rlm_heartbeat",+ activeSessionId: state.activeSessionId,+ deliveryMode: "follow_up",+ }),);const second = await runCronJob(- makeCronJob({ id: "rlm-2", source: "rlm_heartbeat", activeSessionId: state.activeSessionId }),+ makeCronJob({+ id: "rlm-2",+ source: "rlm_heartbeat",+ activeSessionId: state.activeSessionId,+ deliveryMode: "follow_up",+ }),);expect(first).toBe("skipped");@@ -3164,7 +3179,7 @@ describe("daemon mode helpers", () => {expect(prompt).not.toHaveBeenCalled();});- it("prompts idle sessions with a followUp streaming behavior to survive a mid-call stream start", async () => {+ it("delivers heartbeats with a steering behavior by default", async () => {const daemon = new AgentDaemon("/tmp/prime-agent-test.sock", {defaultSessionConfig: { agentDir: "/tmp/prime-agent-test-agent", cwd: "/tmp" },createRuntime: async () => {@@ -3172,7 +3187,12 @@ describe("daemon mode helpers", () => {},});const prompt = vi.fn(async () => {});- const promptHeartbeat = vi.fn(async () => {});+ const promptHeartbeat = vi.fn(+ async (+ _job: AgentCronJob,+ _options?: { streamingBehavior?: "steer" | "followUp"; followUpQueueKey?: string },+ ) => {},+ );const followUp = vi.fn(async () => true);const state = makeState("active-1") as ActiveSessionState & {runtime: ActiveSessionState["runtime"] & {@@ -3200,6 +3220,128 @@ describe("daemon mode helpers", () => {makeCronJob({ id: "heartbeat-1", source: "heartbeat", activeSessionId: state.activeSessionId }),);+ // The preparing guard adds an internal preflightResult hook.+ expect(promptHeartbeat).toHaveBeenCalledWith(+ expect.objectContaining({ id: "heartbeat-1", prompt: "heartbeat prompt" }),+ expect.objectContaining({+ streamingBehavior: "steer",+ source: "rpc",+ }),+ );+ expect(promptHeartbeat.mock.calls[0]?.[1]).toMatchObject({ followUpQueueKey: "heartbeat:heartbeat-1" });+ expect(prompt).not.toHaveBeenCalled();+ expect(followUp).not.toHaveBeenCalled();+ });++ it("delivers steer heartbeats after an RPC prompt finishes preflight while its turn is still streaming", async () => {+ const daemon = new AgentDaemon("/tmp/prime-agent-test.sock", {+ defaultSessionConfig: { agentDir: "/tmp/prime-agent-test-agent", cwd: "/tmp" },+ createRuntime: async () => {+ throw new Error("unexpected runtime creation");+ },+ });+ let releasePrompt = () => {};+ const promptFinished = new Promise<void>((resolve) => {+ releasePrompt = resolve;+ });+ let reportPromptStarted = () => {};+ const promptStarted = new Promise<void>((resolve) => {+ reportPromptStarted = resolve;+ });+ const sessionState = {+ isStreaming: false,+ isBashRunning: false,+ pendingMessageCount: 0,+ };+ const prompt = vi.fn(async (_message: string, options?: { preflightResult?: (didSucceed: boolean) => void }) => {+ sessionState.isStreaming = true;+ options?.preflightResult?.(true);+ reportPromptStarted();+ await promptFinished;+ });+ const promptHeartbeat = vi.fn(+ async (+ _job: AgentCronJob,+ options?: { streamingBehavior?: "steer" | "followUp"; preflightResult?: (didSucceed: boolean) => void },+ ) => {+ options?.preflightResult?.(true);+ },+ );+ const state = makeState("active-1") as ActiveSessionState & {+ runtime: ActiveSessionState["runtime"] & {+ session: typeof sessionState & {+ prompt: typeof prompt;+ promptHeartbeat: typeof promptHeartbeat;+ };+ };+ };+ state.runtime.session = Object.assign(sessionState, { prompt, promptHeartbeat }) as never;+ const internals = daemon as unknown as {+ sessions: Map<string, ActiveSessionState>;+ agentMessagePreparingTargets: Map<string, number>;+ promptWithAgentMessagePreparingGuard(state: ActiveSessionState, message: string): Promise<void>;+ runCronJob(job: AgentCronJob): Promise<"skipped" | undefined>;+ };+ internals.sessions.set(state.activeSessionId, state);++ const promptPromise = internals.promptWithAgentMessagePreparingGuard(state, "long-running prompt");+ await promptStarted;+ const preparingReleased = !internals.agentMessagePreparingTargets.has(state.activeSessionId);+ const result = await internals.runCronJob(+ makeCronJob({ id: "heartbeat-1", source: "heartbeat", activeSessionId: state.activeSessionId }),+ );+ releasePrompt();+ await promptPromise;++ expect(preparingReleased).toBe(true);+ expect(result).toBeUndefined();+ expect(promptHeartbeat).toHaveBeenCalledWith(+ expect.objectContaining({ id: "heartbeat-1" }),+ expect.objectContaining({ streamingBehavior: "steer" }),+ );+ });++ it("delivers follow-up heartbeats with a followUp behavior and coalescing key", async () => {+ const daemon = new AgentDaemon("/tmp/prime-agent-test.sock", {+ defaultSessionConfig: { agentDir: "/tmp/prime-agent-test-agent", cwd: "/tmp" },+ createRuntime: async () => {+ throw new Error("unexpected runtime creation");+ },+ });+ const prompt = vi.fn(async () => {});+ const promptHeartbeat = vi.fn(async () => {});+ const followUp = vi.fn(async () => true);+ const state = makeState("active-1") as ActiveSessionState & {+ runtime: ActiveSessionState["runtime"] & {+ session: {+ isStreaming: boolean;+ isBashRunning: boolean;+ pendingMessageCount: number;+ prompt: typeof prompt;+ promptHeartbeat: typeof promptHeartbeat;+ followUp: typeof followUp;+ };+ };+ };+ state.runtime.session = {+ isStreaming: false,+ isBashRunning: false,+ pendingMessageCount: 0,+ prompt,+ promptHeartbeat,+ followUp,+ } as never;+ (daemon as unknown as { sessions: Map<string, ActiveSessionState> }).sessions.set(state.activeSessionId, state);++ await (daemon as unknown as { runCronJob(job: AgentCronJob): Promise<"skipped" | undefined> }).runCronJob(+ makeCronJob({+ id: "heartbeat-1",+ source: "heartbeat",+ activeSessionId: state.activeSessionId,+ deliveryMode: "follow_up",+ }),+ );+// The preparing guard adds an internal preflightResult hook.expect(promptHeartbeat).toHaveBeenCalledWith(expect.objectContaining({ id: "heartbeat-1", prompt: "heartbeat prompt" }),@@ -3263,6 +3405,207 @@ describe("daemon mode helpers", () => {expect(followUp).not.toHaveBeenCalled();});+ it("forwards queue keys when expanded daemon steer commands are queued", async () => {+ const daemon = new AgentDaemon("/tmp/prime-agent-test.sock", {+ defaultSessionConfig: { agentDir: "/tmp/prime-agent-test-agent", cwd: "/tmp" },+ createRuntime: async () => {+ throw new Error("unexpected runtime creation");+ },+ });+ const steer = vi.fn(async () => {});+ const restoreSteeringMessage = vi.fn(async () => {});+ const state = makeState("active-1") as ActiveSessionState & {+ runtime: ActiveSessionState["runtime"] & {+ session: {+ steer: typeof steer;+ restoreSteeringMessage: typeof restoreSteeringMessage;+ };+ };+ };+ state.runtime.session = { steer, restoreSteeringMessage } as never;+ const internals = daemon as unknown as {+ sessions: Map<string, ActiveSessionState>;+ handleCommand(client: DaemonSocketClient, command: DaemonCommand): Promise<unknown>;+ };+ internals.sessions.set(state.activeSessionId, state);++ await internals.handleCommand(makeClient("client-1", state.activeSessionId), {+ id: "command-1",+ type: "steer",+ activeSessionId: state.activeSessionId,+ message: "queued heartbeat",+ queueKey: "heartbeat:job-1",+ agentMessageId: "agentmsg_steer",+ });++ expect(steer).toHaveBeenCalledWith("queued heartbeat", undefined, {+ queueKey: "heartbeat:job-1",+ agentMessageId: "agentmsg_steer",+ });+ expect(restoreSteeringMessage).not.toHaveBeenCalled();+ });++ it("rejects invalid heartbeat delivery modes before persisting", async () => {+ const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-heartbeat-delivery-mode-"));+ try {+ const daemon = new AgentDaemon(join(tempDir, "daemon.sock"), {+ defaultSessionConfig: { agentDir: tempDir, cwd: tempDir },+ createRuntime: async () => {+ throw new Error("unexpected runtime creation");+ },+ });+ const sessionFile = join(tempDir, "session.jsonl");+ const state = makeState("active-1") as ActiveSessionState & {+ runtime: ActiveSessionState["runtime"] & {+ session: ActiveSessionState["runtime"]["session"] & {+ sessionFile: string;+ sessionId: string;+ };+ };+ };+ state.runtime = {+ ...state.runtime,+ cwd: tempDir,+ session: {+ sessionFile,+ sessionId: "session-1",+ },+ } as never;+ const internals = daemon as unknown as {+ cronStore: AgentCronJobStore;+ sessions: Map<string, ActiveSessionState>;+ handleCommand(client: DaemonSocketClient, command: DaemonCommand): Promise<unknown>;+ };+ internals.sessions.set(state.activeSessionId, state);++ await expect(+ internals.handleCommand(makeClient("client-1", state.activeSessionId), {+ id: "command-1",+ type: "heartbeat_set",+ activeSessionId: state.activeSessionId,+ schedule: "every 5m",+ prompt: "check the run",+ deliveryMode: "followup" as never,+ }),+ ).rejects.toThrow('Heartbeat delivery mode must be "steer" or "follow_up"');+ expect(internals.cronStore.getHeartbeat(state.activeSessionId)).toBeUndefined();+ } finally {+ rmSync(tempDir, { recursive: true, force: true });+ }+ });++ it("preserves the current heartbeat delivery mode when replacement omits it", async () => {+ const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-heartbeat-preserve-delivery-mode-"));+ try {+ const daemon = new AgentDaemon(join(tempDir, "daemon.sock"), {+ defaultSessionConfig: { agentDir: tempDir, cwd: tempDir },+ createRuntime: async () => {+ throw new Error("unexpected runtime creation");+ },+ });+ const state = makeState("active-1") as ActiveSessionState & {+ runtime: ActiveSessionState["runtime"] & {+ session: ActiveSessionState["runtime"]["session"] & {+ removeQueuedFollowUp: ReturnType<typeof vi.fn>;+ sessionFile: string;+ sessionId: string;+ };+ };+ };+ state.runtime = {+ ...state.runtime,+ cwd: tempDir,+ session: {+ removeQueuedFollowUp: vi.fn(() => false),+ sessionFile: join(tempDir, "session.jsonl"),+ sessionId: "session-1",+ },+ } as never;+ const internals = daemon as unknown as {+ sessions: Map<string, ActiveSessionState>;+ handleCommand(+ client: DaemonSocketClient,+ command: DaemonCommand,+ ): Promise<{+ data: { heartbeat: AgentCronJob };+ }>;+ };+ internals.sessions.set(state.activeSessionId, state);+ const client = makeClient("client-1", state.activeSessionId);++ await internals.handleCommand(client, {+ id: "command-1",+ type: "heartbeat_set",+ activeSessionId: state.activeSessionId,+ schedule: "every 5m",+ prompt: "first instruction",+ deliveryMode: "follow_up",+ });+ const replacement = await internals.handleCommand(client, {+ id: "command-2",+ type: "heartbeat_set",+ activeSessionId: state.activeSessionId,+ schedule: "every 10m",+ prompt: "replacement instruction",+ });++ expect(replacement.data.heartbeat).toMatchObject({+ prompt: "replacement instruction",+ deliveryMode: "follow_up",+ });+ } finally {+ rmSync(tempDir, { recursive: true, force: true });+ }+ });++ it("removes queued RLM heartbeat follow-ups when only delivery mode changes", () => {+ const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-rlm-delivery-mode-"));+ try {+ const daemon = new AgentDaemon(join(tempDir, "daemon.sock"), {+ defaultSessionConfig: { agentDir: tempDir, cwd: tempDir },+ createRuntime: async () => {+ throw new Error("unexpected runtime creation");+ },+ });+ const removeQueuedFollowUp = vi.fn(() => true);+ const state = makeState("active-1") as ActiveSessionState & {+ runtime: ActiveSessionState["runtime"] & {+ session: ActiveSessionState["runtime"]["session"] & {+ removeQueuedFollowUp: typeof removeQueuedFollowUp;+ };+ };+ };+ state.runtime.session = { removeQueuedFollowUp } as never;+ const internals = daemon as unknown as {+ cronStore: AgentCronJobStore;+ updateRlmHeartbeatForState(+ state: ActiveSessionState,+ input: { id: string; deliveryMode: "steer" | "follow_up" },+ ): AgentCronJob | undefined;+ };+ const rlmHeartbeat = internals.cronStore.createRlmHeartbeat({+ activeSessionId: state.activeSessionId,+ sessionId: "session-1",+ sessionFile: join(tempDir, "session.jsonl"),+ cwd: tempDir,+ scheduleText: "every 5m",+ prompt: "check internal state",+ deliveryMode: "follow_up",+ now: new Date("2026-01-01T12:00:00.000Z"),+ });++ const updated = internals.updateRlmHeartbeatForState(state, {+ id: rlmHeartbeat.id,+ deliveryMode: "steer",+ });++ expect(updated).toMatchObject({ id: rlmHeartbeat.id, deliveryMode: "steer" });+ expect(removeQueuedFollowUp).toHaveBeenCalledWith(`heartbeat:${rlmHeartbeat.id}`);+ } finally {+ rmSync(tempDir, { recursive: true, force: true });+ }+ });+it("removes queued heartbeat follow-ups when a heartbeat is cleared", async () => {const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-heartbeat-clear-"));try {@@ -3561,11 +3904,17 @@ describe("daemon mode helpers", () => {});});-function makeCronJob(input: { id: string; source: AgentCronJob["source"]; activeSessionId: string }): AgentCronJob {+function makeCronJob(input: {+ id: string;+ source: AgentCronJob["source"];+ activeSessionId: string;+ deliveryMode?: AgentCronJob["deliveryMode"];+}): AgentCronJob {return {id: input.id,status: "active",source: input.source,+ ...(input.deliveryMode ? { deliveryMode: input.deliveryMode } : {}),activeSessionId: input.activeSessionId,sessionId: "session-1",sessionFile: "/tmp/session.jsonl",diff --git a/packages/coding-agent/test/interactive-mode-heartbeat-command.test.ts b/packages/coding-agent/test/interactive-mode-heartbeat-command.test.tsindex 48f5d0b542..a1c65e194e 100644--- a/packages/coding-agent/test/interactive-mode-heartbeat-command.test.ts+++ b/packages/coding-agent/test/interactive-mode-heartbeat-command.test.ts@@ -10,15 +10,27 @@ const interactiveModePrototype = InteractiveMode.prototype as unknown as Interacdescribe("InteractiveMode /heartbeat", () => {describe("argument autocomplete", () => {- it("lists the interval syntax starter for an empty prefix", () => {+ it("lists the interval and delivery-mode starters for an empty prefix", () => {const items = interactiveModePrototype.getHeartbeatArgumentCompletions("");- expect(items?.map((item) => item.label)).toEqual(["every <duration> <instruction>"]);+ expect(items?.map((item) => item.label)).toEqual([+ "every <duration> <instruction>",+ "--steer <instruction>",+ "--follow-up <instruction>",+ ]);const everyItem = items?.find((item) => item.label === "every <duration> <instruction>");expect(everyItem?.value).toBe("every ");expect(everyItem?.description).toBe("Set an interval, then add an instruction: /heartbeat every 10s Scan the logs",);+ const followUpItem = items?.find((item) => item.label === "--follow-up <instruction>");+ expect(followUpItem?.value).toBe("--follow-up ");+ });++ it("filters delivery-mode flags by keyword", () => {+ const items = interactiveModePrototype.getHeartbeatArgumentCompletions("--fol");++ expect(items?.map((item) => item.label)).toEqual(["--follow-up <instruction>"]);});it("does not autocomplete lifecycle commands over free-form instructions", () => {diff --git a/packages/coding-agent/test/kernel-rlm-heartbeat-skill.test.ts b/packages/coding-agent/test/kernel-rlm-heartbeat-skill.test.tsindex be05bef51a..8a47a0f91c 100644--- a/packages/coding-agent/test/kernel-rlm-heartbeat-skill.test.ts+++ b/packages/coding-agent/test/kernel-rlm-heartbeat-skill.test.ts@@ -91,7 +91,7 @@ describe("RLM heartbeat skill over the kernel host bridge", () => {const manager = await provisioner.ensure();const result = await manager.execute(`import json-created = await rlm_heartbeat.create("check tests", interval="5m", label="tests")+created = await rlm_heartbeat.create("check tests", interval="5m", label="tests", delivery_mode="follow_up")listed = await rlm_heartbeat.list(include_inactive=True)updated = await rlm_heartbeat.update(created["heartbeat"]["id"], status="pause")deleted = await rlm_heartbeat.delete(created["heartbeat"]["id"])@@ -121,6 +121,7 @@ print(json.dumps({instruction: "check tests",interval: "5m",label: "tests",+ delivery_mode: "follow_up",});expect(requests[1].payload).toMatchObject({ type: "rlm_heartbeat.list", include_inactive: true });expect(requests[2].payload).toMatchObject({ type: "rlm_heartbeat.update", id: "job-1", status: "pause" });@@ -145,4 +146,33 @@ except RuntimeError as error:'RuntimeError: host request type "rlm_heartbeat.list" is not available in this session',);});++ it("rejects non-string delivery modes before calling the host", async () => {+ let hostRequestCount = 0;+ provisioner = new IpythonKernelProvisioner(tempDir, {+ pythonSkills: [bundledRlmHeartbeatSkill()],+ hostHandlers: {+ "rlm_heartbeat.create": async () => {+ hostRequestCount++;+ return {};+ },+ },+ });++ const manager = await provisioner.ensure();+ const result = await manager.execute(`+for value in ([], {}):+ try:+ await rlm_heartbeat.create("check tests", delivery_mode=value)+ except TypeError as error:+ print(f"TypeError: {error}")+`);++ expect(result.status).toBe("ok");+ expect(result.stdout.trim().split("\n")).toEqual([+ "TypeError: delivery_mode must be str or None, got list",+ "TypeError: delivery_mode must be str or None, got dict",+ ]);+ expect(hostRequestCount).toBe(0);+ });});diff --git a/packages/coding-agent/test/slash-commands.test.ts b/packages/coding-agent/test/slash-commands.test.tsindex c707b63010..cc866dcc7f 100644--- a/packages/coding-agent/test/slash-commands.test.ts+++ b/packages/coding-agent/test/slash-commands.test.ts@@ -18,8 +18,9 @@ describe("built-in slash commands", () => {test("exposes heartbeat syntax guidance", () => {expect(BUILTIN_SLASH_COMMANDS.find((command) => command.name === "heartbeat")).toMatchObject({- description: "Set or view a persistent heartbeat; supports pause, resume, stop, and clear",- argumentHint: "[status|pause|resume|stop|every <duration> <instruction>]",+ description:+ "Set or view a persistent heartbeat; delivery defaults to steer, use --follow-up to queue; supports pause, resume, stop, and clear",+ argumentHint: "[status|pause|resume|stop|[every <duration>] [--steer|--follow-up] <instruction>]",takesArgument: true,});});diff --git a/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts b/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.tsindex e8ad07cc94..eb48cddee9 100644--- a/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts+++ b/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts@@ -22,7 +22,12 @@ type AgentDaemonUpdateInternals = {};type QueueInternals = {- _steeringMessages: Array<{ text: string; agentMessageId?: string; message: UserMessage | CustomMessage }>;+ _steeringMessages: Array<{+ text: string;+ queueKey?: string;+ agentMessageId?: string;+ message: UserMessage | CustomMessage;+ }>;_followUpMessages: Array<{text: string;queueKey?: string;@@ -312,7 +317,9 @@ describe("issue #4257 update restart resume", () => {};const customFollowUp = createCustomMessage("custom heartbeat");const queueInternals = parentHarness.session as unknown as QueueInternals;- queueInternals._steeringMessages = [{ text: "queued work", agentMessageId: "agentmsg_steer", message }];+ queueInternals._steeringMessages = [+ { text: "queued work", queueKey: "heartbeat:steer", agentMessageId: "agentmsg_steer", message },+ ];queueInternals._followUpMessages = [{text: "heartbeat",@@ -371,7 +378,15 @@ describe("issue #4257 update restart resume", () => {clientEnv: { PRIME_SESSION: "pane-1" },runtimeMetadata: { kind: "top-level" },queue: {- steering: [{ message: "queued work", content, images: [image], agentMessageId: "agentmsg_steer" }],+ steering: [+ {+ message: "queued work",+ content,+ images: [image],+ queueKey: "heartbeat:steer",+ agentMessageId: "agentmsg_steer",+ },+ ],followUp: [{message: "heartbeat",@@ -770,6 +785,7 @@ describe("issue #4257 update restart resume", () => {activeSessionId: "active-1",message: "restored steer",content: restoredSteerContent,+ queueKey: "heartbeat:steer",expandPromptTemplates: false,agentMessageId: "agentmsg_restored_steer",}),@@ -814,6 +830,7 @@ describe("issue #4257 update restart resume", () => {expect.objectContaining({text: "restored steer",content: restoredSteerContent,+ queueKey: "heartbeat:steer",agentMessageId: "agentmsg_restored_steer",}),]);diff --git a/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts b/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.tsindex 1aed13d7e1..0c537e775d 100644--- a/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts+++ b/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts@@ -306,6 +306,55 @@ describe("ENG-4482 heartbeat injected prompt UI", () => {expect(harness.session.getFollowUpMessagePreviews()).toEqual([]);});+ it("removes queued steered heartbeat prompts by heartbeat queue key", async () => {+ let releaseToolExecution: (() => void) | undefined;+ const toolRelease = new Promise<void>((resolve) => {+ releaseToolExecution = resolve;+ });+ const waitTool: AgentTool = {+ name: "wait",+ label: "Wait",+ description: "Wait for release",+ parameters: Type.Object({}),+ execute: async () => {+ await toolRelease;+ return {+ content: [{ type: "text", text: "released" }],+ details: {},+ };+ },+ };+ const harness = await createHarness({ tools: [waitTool] });+ harnesses.push(harness);+ const heartbeatText = "Check whether the long-running task needs another step.";+ const heartbeatPreview = `Heartbeat prompt: ${heartbeatText}`;+ harness.setResponses([+ fauxAssistantMessage(fauxToolCall("wait", {}), { stopReason: "toolUse" }),+ fauxAssistantMessage("original turn complete"),+ ]);+ const sawToolStart = new Promise<void>((resolve) => {+ const unsubscribe = harness.session.subscribe((event) => {+ if (event.type === "tool_execution_start") {+ unsubscribe();+ resolve();+ }+ });+ });++ const promptPromise = harness.session.prompt("start");+ await sawToolStart;+ await harness.session.promptHeartbeat(createHeartbeat(), { streamingBehavior: "steer" });++ expect(harness.session.getSteeringMessagePreviews()).toEqual([heartbeatPreview]);+ expect(harness.session.removeQueuedFollowUp("heartbeat:heartbeat-1")).toBe(true);+ expect(harness.session.getSteeringMessagePreviews()).toEqual([]);++ releaseToolExecution?.();+ await promptPromise;++ expect(getUserTexts(harness)).toEqual(["start"]);+ });+it("renders heartbeat prompts as expandable injected prompt panels", () => {const component = new InjectedPromptMessageComponent(createHeartbeatPromptMessage(createHeartbeat()));const collapsed = render(component);diff --git a/packages/coding-agent/test/suite/regressions/4519-heartbeat-rebirth.test.ts b/packages/coding-agent/test/suite/regressions/4519-heartbeat-rebirth.test.tsindex 6532cb3a26..a6f5e25e24 100644--- a/packages/coding-agent/test/suite/regressions/4519-heartbeat-rebirth.test.ts+++ b/packages/coding-agent/test/suite/regressions/4519-heartbeat-rebirth.test.ts@@ -309,7 +309,7 @@ describe("ENG-4519 heartbeat rebirth", () => {expect(promptHeartbeat).toHaveBeenCalledWith(expect.objectContaining({ id: heartbeat.id, prompt: "continue scheduled work" }),expect.objectContaining({- streamingBehavior: "followUp",+ streamingBehavior: "steer",followUpQueueKey: `heartbeat:${heartbeat.id}`,source: "rpc",}),