Skip to content

Defer heartbeat delivery while sessions are active #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kevinjosethomas merged 4 commits into from
Jun 29, 2026
Merged

Defer heartbeat delivery while sessions are active #265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
13da4e7
Defer heartbeat cron jobs while sessions are active
sethkarten Jun 25, 2026
5a73a9b
remove dead heartbeat follow-up plumbing and surface deferred skips
kevinjosethomas Jun 29, 2026
f4501f8
pass followUp streaming behavior on cron prompt to survive mid-call s…
kevinjosethomas Jun 29, 2026
da4ff04
coalesce raced heartbeat follow-ups with a per-job queue key
kevinjosethomas Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions packages/coding-agent/src/core/cron-jobs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ export interface AgentCronJob {
updatedAt: string;
nextRunAt?: string;
lastRunAt?: string;
lastSkippedAt?: string;
lastError?: string;
runCount: number;
}
Expand All @@ -58,6 +59,12 @@ export interface AgentCronSchedulerHooks {
onError?: (job: AgentCronJob, error: unknown) => void;
}

export interface HeartbeatCronSessionActivity {
isStreaming: boolean;
isBashRunning: boolean;
pendingMessageCount: number;
}

interface CronJobsFile {
jobs?: unknown;
}
Expand Down Expand Up @@ -483,7 +490,12 @@ export class AgentCronJobStore {
return job;
}
const nextRunAt = nextRunAtForSchedule(job.schedule, now);
updated = { ...job, nextRunAt: nextRunAt?.toISOString(), updatedAt: now.toISOString() };
updated = {
...job,
nextRunAt: nextRunAt?.toISOString(),
lastSkippedAt: now.toISOString(),
updatedAt: now.toISOString(),
};
return updated;
});
if (updated) {
Expand Down Expand Up @@ -760,7 +772,8 @@ export function formatAgentCronJob(job: AgentCronJob): string {
const preview = job.prompt.replace(/\s+/g, " ").slice(0, 80);
const error = job.lastError ? ` error=${job.lastError}` : "";
const label = job.label ? ` label="${job.label}"` : "";
return `${job.id} ${job.status}${label} next=${next} last=${last} runs=${job.runCount} schedule="${job.schedule.expression}" prompt="${preview}"${error}`;
const skipped = job.lastSkippedAt ? ` skipped=${new Date(job.lastSkippedAt).toLocaleString()}` : "";
return `${job.id} ${job.status}${label} next=${next} last=${last}${skipped} runs=${job.runCount} schedule="${job.schedule.expression}" prompt="${preview}"${error}`;
}

export function createAgentHeartbeatToolDefinitions(controller: AgentCronToolController): ToolDefinition[] {
Expand Down Expand Up @@ -814,6 +827,16 @@ function consumeLeadingEverySchedule(text: string): { interval: string; rest: st
};
}

export function isHeartbeatCronJob(job: AgentCronJob): boolean {
return job.source === "heartbeat" || job.source === "rlm_heartbeat";
}

export function shouldDeferHeartbeatCronJob(job: AgentCronJob, activity: HeartbeatCronSessionActivity): boolean {
return (
isHeartbeatCronJob(job) && (activity.isStreaming || activity.isBashRunning || activity.pendingMessageCount > 0)
);
}

function nextCronRunAfter(expression: string, after: Date): Date {
const fields = parseCronExpression(expression);
const candidate = new Date(after.getTime());
Expand Down
21 changes: 10 additions & 11 deletions packages/coding-agent/src/modes/daemon/daemon-mode.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ import {
type AgentHeartbeatUpdateAction,
createAgentHeartbeatToolDefinitions,
DEFAULT_HEARTBEAT_SCHEDULE,
isHeartbeatCronJob,
normalizeHeartbeatSchedule,
shouldDeferHeartbeatCronJob,
} from "../../core/cron-jobs.js";
import type {
CreateRlmSubagentRuntimeOptions,
Expand Down Expand Up @@ -471,18 +473,19 @@ export class AgentDaemon {
if (!state) {
return;
}
const followUpQueueKey = isHeartbeatCronJob(job) ? `heartbeat:${job.id}` : undefined;
if (followUpQueueKey && (state.runtime.session.isStreaming || state.runtime.session.pendingMessageCount > 0)) {
const didQueue = await state.runtime.session.followUp(job.prompt, undefined, { queueKey: followUpQueueKey });
return didQueue ? undefined : "skipped";
if (shouldDeferHeartbeatCronJob(job, state.runtime.session)) {
return "skipped";
}
if (!followUpQueueKey && (state.runtime.session.isStreaming || state.runtime.session.pendingMessageCount > 0)) {
if (
!isHeartbeatCronJob(job) &&
(state.runtime.session.isStreaming || state.runtime.session.pendingMessageCount > 0)
) {
await state.runtime.session.followUp(job.prompt);
return;
}
await state.runtime.session.prompt(job.prompt, {
Comment thread
macroscopeapp[bot] marked this conversation as resolved.
streamingBehavior: state.runtime.session.isStreaming ? "followUp" : undefined,
followUpQueueKey,
streamingBehavior: "followUp",
followUpQueueKey: isHeartbeatCronJob(job) ? `heartbeat:${job.id}` : undefined,
source: "rpc",
});
}
Expand Down Expand Up @@ -1670,10 +1673,6 @@ export class AgentDaemon {
}
}

function isHeartbeatCronJob(job: AgentCronJob): boolean {
return job.source === "heartbeat" || job.source === "rlm_heartbeat";
}

function serializeSavedSessionInfo(session: SessionInfo): DaemonSavedSessionInfo {
return {
path: session.path,
Expand Down
65 changes: 65 additions & 0 deletions packages/coding-agent/test/cron-jobs.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import {
createAgentHeartbeatToolDefinitions,
parseAgentCronSchedule,
parseHeartbeatCommand,
shouldDeferHeartbeatCronJob,
} from "../src/core/cron-jobs.js";

const start = new Date("2026-01-01T12:34:00.000Z");
Expand Down Expand Up @@ -702,6 +703,7 @@ describe("AgentCronScheduler", () => {
id: job.id,
status: "active",
nextRunAt: "2026-01-01T12:45:00.000Z",
lastSkippedAt: "2026-01-01T12:40:00.000Z",
runCount: 0,
});
expect(store.getHeartbeat("active-1")).not.toHaveProperty("lastRunAt");
Expand Down Expand Up @@ -752,6 +754,69 @@ describe("AgentCronScheduler", () => {
});
});

describe("shouldDeferHeartbeatCronJob", () => {
const baseJob: AgentCronJob = {
id: "job-1",
status: "active",
activeSessionId: "active-1",
sessionId: "session-1",
sessionFile: "/tmp/session.jsonl",
cwd: "/tmp/project",
prompt: "check progress",
schedule: { kind: "interval", expression: "every 5m", intervalMs: 300_000 },
createdAt: "2026-01-01T12:34:00.000Z",
updatedAt: "2026-01-01T12:34:00.000Z",
nextRunAt: "2026-01-01T12:39:00.000Z",
runCount: 0,
};

it("defers user and RLM heartbeats while the target session is working", () => {
for (const source of ["heartbeat", "rlm_heartbeat"] as const) {
const job = { ...baseJob, source };

expect(
shouldDeferHeartbeatCronJob(job, {
isStreaming: 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);
}
});

it("allows heartbeats when the target session is idle", () => {
expect(
shouldDeferHeartbeatCronJob(
{ ...baseJob, source: "heartbeat" },
{ isStreaming: false, isBashRunning: false, pendingMessageCount: 0 },
),
).toBe(false);
});

it("does not defer ordinary cron jobs", () => {
expect(
shouldDeferHeartbeatCronJob(
{ ...baseJob, source: "cron" },
{ isStreaming: true, isBashRunning: true, pendingMessageCount: 2 },
),
).toBe(false);
});
});

describe("createAgentHeartbeatToolDefinitions", () => {
it("exposes only read-only user heartbeat inspection to the model", () => {
const tools = createAgentHeartbeatToolDefinitions({
Expand Down
Loading