Honor no-delivery cron system events

Al-bots · Al-bots · commit 2af56d891969 · 2026-05-28T23:48:21.000+05:00
diff --git a/src/agents/tools/cron-tool.ts b/src/agents/tools/cron-tool.ts
@@ -560,6 +560,9 @@ CRITICAL CONSTRAINTS:
 - sessionTarget="isolated" | "current" | "session:xxx" REQUIRES payload.kind="agentTurn"
 - Webhook: delivery.mode="webhook" and delivery.to URL.
 Default: prefer isolated agentTurn jobs unless the user explicitly wants current-session binding.
+For silent background automation that uses tools or stores memory, use
+sessionTarget="isolated" + payload.kind="agentTurn" + delivery.mode="none";
+do not use a main systemEvent job for tool-running background work.
 
 RESTRICTED CRON RUNS:
 - Some isolated cron runs get narrow self-cleanup grant: status/list self-only, get/runs current job only, mutation only remove current job.
diff --git a/src/cron/service.runs-one-shot-main-job-disables-it.test.ts b/src/cron/service.runs-one-shot-main-job-disables-it.test.ts
@@ -191,12 +191,18 @@ async function addWakeModeNowMainSystemEventJob(
 
 async function addMainOneShotHelloJob(
   cron: CronService,
-  params: { atMs: number; name: string; deleteAfterRun?: boolean },
+  params: {
+    atMs: number;
+    name: string;
+    deleteAfterRun?: boolean;
+    delivery?: { mode: "none" };
+  },
 ) {
   return cron.add({
     name: params.name,
     enabled: true,
     ...(params.deleteAfterRun === undefined ? {} : { deleteAfterRun: params.deleteAfterRun }),
+    ...(params.delivery ? { delivery: params.delivery } : {}),
     schedule: { kind: "at", at: new Date(params.atMs).toISOString() },
     sessionTarget: "main",
     wakeMode: "now",
@@ -255,13 +261,18 @@ function createStartedCronService(
   });
 }
 
-async function createMainOneShotJobHarness(params: { name: string; deleteAfterRun?: boolean }) {
+async function createMainOneShotJobHarness(params: {
+  name: string;
+  deleteAfterRun?: boolean;
+  delivery?: { mode: "none" };
+}) {
   const harness = await createMainOneShotHarness();
   const atMs = Date.parse("2025-12-13T00:00:02.000Z");
   const job = await addMainOneShotHelloJob(harness.cron, {
     atMs,
     name: params.name,
     deleteAfterRun: params.deleteAfterRun,
+    delivery: params.delivery,
   });
   return { ...harness, atMs, job };
 }
@@ -306,6 +317,24 @@ describe("CronService", () => {
     await stopCronAndCleanup(cron, store);
   });
 
+  it("does not wake the assistant for explicit no-delivery main systemEvent jobs", async () => {
+    const { store, cron, enqueueSystemEvent, requestHeartbeat, events, atMs, job } =
+      await createMainOneShotJobHarness({
+        name: "silent main system event",
+        deleteAfterRun: false,
+        delivery: { mode: "none" },
+      });
+
+    vi.setSystemTime(new Date(atMs));
+    await vi.runOnlyPendingTimersAsync();
+    await events.waitFor((evt) => evt.jobId === job.id && evt.action === "finished");
+
+    expectMainSystemEventPosted(enqueueSystemEvent, { text: "hello", jobId: job.id });
+    expect(requestHeartbeat).not.toHaveBeenCalled();
+
+    await stopCronAndCleanup(cron, store);
+  });
+
   it("runs a one-shot job and deletes it after success by default", async () => {
     const { store, cron, enqueueSystemEvent, requestHeartbeat, events, job } =
       await createMainOneShotJobHarness({
diff --git a/src/cron/service/timer.ts b/src/cron/service/timer.ts
@@ -471,6 +471,10 @@ function resolveMainSessionCronDeliveryContext(
   }
 }
 
+function hasExplicitNoDelivery(job: CronJob): boolean {
+  return normalizeOptionalLowercaseString(job.delivery?.mode) === "none";
+}
+
 function resolveCronTaskChildSessionKey(params: {
   state: CronServiceState;
   job: CronJob;
@@ -1761,13 +1765,17 @@ async function executeMainSessionCronJob(
   const cronStartedAt =
     typeof job.state.runningAtMs === "number" ? job.state.runningAtMs : state.deps.nowMs();
   const cronRunSessionKey = resolveMainSessionCronRunSessionKey(job, cronStartedAt);
+  const suppressHeartbeat = hasExplicitNoDelivery(job);
   const deliveryContext = resolveMainSessionCronDeliveryContext(state, job);
   state.deps.enqueueSystemEvent(text, {
     agentId: job.agentId,
     sessionKey: cronRunSessionKey,
     contextKey: `cron:${job.id}`,
-    ...(deliveryContext ? { deliveryContext } : {}),
+    ...(!suppressHeartbeat && deliveryContext ? { deliveryContext } : {}),
   });
+  if (suppressHeartbeat) {
+    return { status: "ok", summary: text, sessionKey: cronRunSessionKey };
+  }
   if (job.wakeMode === "now" && state.deps.runHeartbeatOnce) {
     const reason = `cron:${job.id}`;
     const maxWaitMs = state.deps.wakeNowHeartbeatBusyMaxWaitMs ?? 2 * 60_000;
