feat(cron): introduce delivery modes for isolated jobs

- Added support for new delivery modes in cron jobs: `announce`, `deliver`, and `none`.
- Updated documentation to reflect changes in delivery options and usage examples.
- Enhanced the cron job schema to include delivery configuration.
- Refactored related CLI commands and UI components to accommodate the new delivery settings.
- Improved handling of legacy delivery fields for backward compatibility.

This update allows users to choose how output from isolated jobs is delivered, enhancing flexibility in job management.

src/cron/delivery.ts

@@ -0,0 +1,80 @@
+import type { CronDeliveryMode, CronJob, CronMessageChannel } from "./types.js";
+
+export type CronDeliveryPlan = {
+  mode: CronDeliveryMode;
+  channel: CronMessageChannel;
+  to?: string;
+  bestEffort: boolean;
+  source: "delivery" | "payload";
+  requested: boolean;
+  legacyMode?: "explicit" | "auto" | "off";
+};
+
+function normalizeChannel(value: unknown): CronMessageChannel | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed as CronMessageChannel;
+}
+
+function normalizeTo(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveCronDeliveryPlan(job: CronJob): CronDeliveryPlan {
+  const payload = job.payload.kind === "agentTurn" ? job.payload : null;
+  const delivery = job.delivery;
+  const hasDelivery = delivery && typeof delivery === "object";
+  const rawMode = hasDelivery ? (delivery as { mode?: unknown }).mode : undefined;
+  const mode =
+    rawMode === "none" || rawMode === "announce" || rawMode === "deliver" ? rawMode : undefined;
+
+  const payloadChannel = normalizeChannel(payload?.channel);
+  const payloadTo = normalizeTo(payload?.to);
+  const payloadBestEffort = payload?.bestEffortDeliver === true;
+
+  const deliveryChannel = normalizeChannel(
+    (delivery as { channel?: unknown } | undefined)?.channel,
+  );
+  const deliveryTo = normalizeTo((delivery as { to?: unknown } | undefined)?.to);
+  const deliveryBestEffortRaw = (delivery as { bestEffort?: unknown } | undefined)?.bestEffort;
+  const deliveryBestEffort =
+    typeof deliveryBestEffortRaw === "boolean" ? deliveryBestEffortRaw : undefined;
+
+  const channel = (deliveryChannel ?? payloadChannel ?? "last") as CronMessageChannel;
+  const to = deliveryTo ?? payloadTo;
+  if (hasDelivery) {
+    const resolvedMode = mode ?? "none";
+    return {
+      mode: resolvedMode,
+      channel,
+      to,
+      bestEffort: deliveryBestEffort ?? false,
+      source: "delivery",
+      requested: resolvedMode !== "none",
+    };
+  }
+
+  const legacyMode =
+    payload?.deliver === true ? "explicit" : payload?.deliver === false ? "off" : "auto";
+  const hasExplicitTarget = Boolean(to);
+  const requested = legacyMode === "explicit" || (legacyMode === "auto" && hasExplicitTarget);
+
+  return {
+    mode: requested ? "deliver" : "none",
+    channel,
+    to,
+    bestEffort: payloadBestEffort,
+    source: "payload",
+    requested,
+    legacyMode,
+  };
+}

src/cron/isolated-agent/delivery-target.ts

@@ -24,6 +24,7 @@ export async function resolveDeliveryTarget(
   channel: Exclude<OutboundChannel, "none">;
   to?: string;
   accountId?: string;
+  threadId?: string | number;
   mode: "explicit" | "implicit";
   error?: Error;
 }> {
@@ -69,7 +70,13 @@ export async function resolveDeliveryTarget(
   const toCandidate = resolved.to;
 
   if (!toCandidate) {
-    return { channel, to: undefined, accountId: resolved.accountId, mode };
+    return {
+      channel,
+      to: undefined,
+      accountId: resolved.accountId,
+      threadId: resolved.threadId,
+      mode,
+    };
   }
 
   const docked = resolveOutboundTarget({
@@ -83,6 +90,7 @@ export async function resolveDeliveryTarget(
     channel,
     to: docked.ok ? docked.to : undefined,
     accountId: resolved.accountId,
+    threadId: resolved.threadId,
     mode,
     error: docked.ok ? undefined : docked.error,
   };

src/cron/isolated-agent/run.ts

@@ -31,6 +31,10 @@ import {
 import { runEmbeddedPiAgent } from "../../agents/pi-embedded.js";
 import { buildWorkspaceSkillSnapshot } from "../../agents/skills.js";
 import { getSkillsSnapshotVersion } from "../../agents/skills/refresh.js";
+import {
+  runSubagentAnnounceFlow,
+  type SubagentRunOutcome,
+} from "../../agents/subagent-announce.js";
 import { resolveAgentTimeoutMs } from "../../agents/timeout.js";
 import { hasNonzeroUsage } from "../../agents/usage.js";
 import { ensureAgentWorkspace } from "../../agents/workspace.js";
@@ -41,7 +45,11 @@ import {
   supportsXHighThinking,
 } from "../../auto-reply/thinking.js";
 import { createOutboundSendDeps, type CliDeps } from "../../cli/outbound-send-deps.js";
-import { resolveSessionTranscriptPath, updateSessionStore } from "../../config/sessions.js";
+import {
+  resolveAgentMainSessionKey,
+  resolveSessionTranscriptPath,
+  updateSessionStore,
+} from "../../config/sessions.js";
 import { registerAgentRunContext } from "../../infra/agent-events.js";
 import { deliverOutboundPayloads } from "../../infra/outbound/deliver.js";
 import { getRemoteSkillEligibility } from "../../infra/skills-remote.js";
@@ -53,6 +61,7 @@ import {
   getHookType,
   isExternalHookSession,
 } from "../../security/external-content.js";
+import { resolveCronDeliveryPlan } from "../delivery.js";
 import { resolveDeliveryTarget } from "./delivery-target.js";
 import {
   isHeartbeatOnlyResponse,
@@ -231,16 +240,15 @@ export async function runCronIsolatedAgentTurn(params: {
   });
 
   const agentPayload = params.job.payload.kind === "agentTurn" ? params.job.payload : null;
-  const deliveryMode =
-    agentPayload?.deliver === true ? "explicit" : agentPayload?.deliver === false ? "off" : "auto";
-  const hasExplicitTarget = Boolean(agentPayload?.to && agentPayload.to.trim());
-  const deliveryRequested =
-    deliveryMode === "explicit" || (deliveryMode === "auto" && hasExplicitTarget);
-  const bestEffortDeliver = agentPayload?.bestEffortDeliver === true;
+  const deliveryPlan = resolveCronDeliveryPlan(params.job);
+  const deliveryRequested = deliveryPlan.requested;
+  const bestEffortDeliver = deliveryPlan.bestEffort;
+  const legacyDeliveryMode =
+    deliveryPlan.source === "payload" ? deliveryPlan.legacyMode : undefined;
 
   const resolvedDelivery = await resolveDeliveryTarget(cfgWithAgentDefaults, agentId, {
-    channel: agentPayload?.channel ?? "last",
-    to: agentPayload?.to,
+    channel: deliveryPlan.channel ?? "last",
+    to: deliveryPlan.to,
   });
 
   const userTimezone = resolveUserTimezone(params.cfg.agents?.defaults?.userTimezone);
@@ -424,7 +432,7 @@ export async function runCronIsolatedAgentTurn(params: {
   const skipHeartbeatDelivery = deliveryRequested && isHeartbeatOnlyResponse(payloads, ackMaxChars);
   const skipMessagingToolDelivery =
     deliveryRequested &&
-    deliveryMode === "auto" &&
+    legacyDeliveryMode === "auto" &&
     runResult.didSendViaMessagingTool === true &&
     (runResult.messagingToolSentTargets ?? []).some((target) =>
       matchesMessagingToolDeliveryTarget(target, {
@@ -435,38 +443,70 @@ export async function runCronIsolatedAgentTurn(params: {
     );
 
   if (deliveryRequested && !skipHeartbeatDelivery && !skipMessagingToolDelivery) {
-    if (!resolvedDelivery.to) {
-      const reason =
-        resolvedDelivery.error?.message ?? "Cron delivery requires a recipient (--to).";
-      if (!bestEffortDeliver) {
+    if (deliveryPlan.mode === "announce") {
+      const requesterSessionKey = resolveAgentMainSessionKey({
+        cfg: cfgWithAgentDefaults,
+        agentId,
+      });
+      const useExplicitOrigin = deliveryPlan.channel !== "last" || Boolean(deliveryPlan.to?.trim());
+      const requesterOrigin = useExplicitOrigin
+        ? {
+            channel: resolvedDelivery.channel,
+            to: resolvedDelivery.to,
+            accountId: resolvedDelivery.accountId,
+            threadId: resolvedDelivery.threadId,
+          }
+        : undefined;
+      const outcome: SubagentRunOutcome = { status: "ok" };
+      const taskLabel = params.job.name?.trim() || "cron job";
+      await runSubagentAnnounceFlow({
+        childSessionKey: agentSessionKey,
+        childRunId: cronSession.sessionEntry.sessionId,
+        requesterSessionKey,
+        requesterOrigin,
+        requesterDisplayKey: requesterSessionKey,
+        task: taskLabel,
+        timeoutMs: 30_000,
+        cleanup: "keep",
+        roundOneReply: outputText ?? summary,
+        waitForCompletion: false,
+        label: `Cron: ${taskLabel}`,
+        outcome,
+      });
+    } else {
+      if (!resolvedDelivery.to) {
+        const reason =
+          resolvedDelivery.error?.message ?? "Cron delivery requires a recipient (--to).";
+        if (!bestEffortDeliver) {
+          return {
+            status: "error",
+            summary,
+            outputText,
+            error: reason,
+          };
+        }
         return {
-          status: "error",
-          summary,
+          status: "skipped",
+          summary: `Delivery skipped (${reason}).`,
           outputText,
-          error: reason,
         };
       }
-      return {
-        status: "skipped",
-        summary: `Delivery skipped (${reason}).`,
-        outputText,
-      };
-    }
-    try {
-      await deliverOutboundPayloads({
-        cfg: cfgWithAgentDefaults,
-        channel: resolvedDelivery.channel,
-        to: resolvedDelivery.to,
-        accountId: resolvedDelivery.accountId,
-        payloads,
-        bestEffort: bestEffortDeliver,
-        deps: createOutboundSendDeps(params.deps),
-      });
-    } catch (err) {
-      if (!bestEffortDeliver) {
-        return { status: "error", summary, outputText, error: String(err) };
+      try {
+        await deliverOutboundPayloads({
+          cfg: cfgWithAgentDefaults,
+          channel: resolvedDelivery.channel,
+          to: resolvedDelivery.to,
+          accountId: resolvedDelivery.accountId,
+          payloads,
+          bestEffort: bestEffortDeliver,
+          deps: createOutboundSendDeps(params.deps),
+        });
+      } catch (err) {
+        if (!bestEffortDeliver) {
+          return { status: "error", summary, outputText, error: String(err) };
+        }
+        return { status: "ok", summary, outputText };
       }
-      return { status: "ok", summary, outputText };
     }
   }
 

src/cron/normalize.test.ts

@@ -110,4 +110,28 @@ describe("normalizeCronJobCreate", () => {
     expect(schedule.kind).toBe("at");
     expect(schedule.atMs).toBe(Date.parse("2026-01-12T18:00:00Z"));
   });
+
+  it("normalizes delivery mode and channel", () => {
+    const normalized = normalizeCronJobCreate({
+      name: "delivery",
+      enabled: true,
+      schedule: { kind: "cron", expr: "* * * * *" },
+      sessionTarget: "isolated",
+      wakeMode: "now",
+      payload: {
+        kind: "agentTurn",
+        message: "hi",
+      },
+      delivery: {
+        mode: " ANNOUNCE ",
+        channel: " TeLeGrAm ",
+        to: " 7200373102 ",
+      },
+    }) as unknown as Record<string, unknown>;
+
+    const delivery = normalized.delivery as Record<string, unknown>;
+    expect(delivery.mode).toBe("announce");
+    expect(delivery.channel).toBe("telegram");
+    expect(delivery.to).toBe("7200373102");
+  });
 });

src/cron/normalize.ts

@@ -61,6 +61,30 @@ function coercePayload(payload: UnknownRecord) {
   return next;
 }
 
+function coerceDelivery(delivery: UnknownRecord) {
+  const next: UnknownRecord = { ...delivery };
+  if (typeof delivery.mode === "string") {
+    next.mode = delivery.mode.trim().toLowerCase();
+  }
+  if (typeof delivery.channel === "string") {
+    const trimmed = delivery.channel.trim().toLowerCase();
+    if (trimmed) {
+      next.channel = trimmed;
+    } else {
+      delete next.channel;
+    }
+  }
+  if (typeof delivery.to === "string") {
+    const trimmed = delivery.to.trim();
+    if (trimmed) {
+      next.to = trimmed;
+    } else {
+      delete next.to;
+    }
+  }
+  return next;
+}
+
 function unwrapJob(raw: UnknownRecord) {
   if (isRecord(raw.data)) {
     return raw.data;
@@ -118,6 +142,10 @@ export function normalizeCronJobInput(
     next.payload = coercePayload(base.payload);
   }
 
+  if (isRecord(base.delivery)) {
+    next.delivery = coerceDelivery(base.delivery);
+  }
+
   if (options.applyDefaults) {
     if (!next.wakeMode) {
       next.wakeMode = "next-heartbeat";

src/cron/service/jobs.ts

@@ -1,5 +1,7 @@
 import crypto from "node:crypto";
 import type {
+  CronDelivery,
+  CronDeliveryPatch,
   CronJob,
   CronJobCreate,
   CronJobPatch,
@@ -26,6 +28,12 @@ export function assertSupportedJobSpec(job: Pick<CronJob, "sessionTarget" | "pay
   }
 }
 
+function assertDeliverySupport(job: Pick<CronJob, "sessionTarget" | "delivery">) {
+  if (job.delivery && job.sessionTarget !== "isolated") {
+    throw new Error('cron delivery config is only supported for sessionTarget="isolated"');
+  }
+}
+
 export function findJobOrThrow(state: CronServiceState, id: string) {
   const job = state.store?.jobs.find((j) => j.id === id);
   if (!job) {
@@ -102,12 +110,14 @@ export function createJob(state: CronServiceState, input: CronJobCreate): CronJo
     sessionTarget: input.sessionTarget,
     wakeMode: input.wakeMode,
     payload: input.payload,
+    delivery: input.delivery,
     isolation: input.isolation,
     state: {
       ...input.state,
     },
   };
   assertSupportedJobSpec(job);
+  assertDeliverySupport(job);
   job.state.nextRunAtMs = computeJobNextRunAtMs(job, now);
   return job;
 }
@@ -137,6 +147,9 @@ export function applyJobPatch(job: CronJob, patch: CronJobPatch) {
   if (patch.payload) {
     job.payload = mergeCronPayload(job.payload, patch.payload);
   }
+  if (patch.delivery) {
+    job.delivery = mergeCronDelivery(job.delivery, patch.delivery);
+  }
   if (patch.isolation) {
     job.isolation = patch.isolation;
   }
@@ -147,6 +160,7 @@ export function applyJobPatch(job: CronJob, patch: CronJobPatch) {
     job.agentId = normalizeOptionalAgentId((patch as { agentId?: unknown }).agentId);
   }
   assertSupportedJobSpec(job);
+  assertDeliverySupport(job);
 }
 
 function mergeCronPayload(existing: CronPayload, patch: CronPayloadPatch): CronPayload {
@@ -219,6 +233,35 @@ function buildPayloadFromPatch(patch: CronPayloadPatch): CronPayload {
   };
 }
 
+function mergeCronDelivery(
+  existing: CronDelivery | undefined,
+  patch: CronDeliveryPatch,
+): CronDelivery {
+  const next: CronDelivery = {
+    mode: existing?.mode ?? "none",
+    channel: existing?.channel,
+    to: existing?.to,
+    bestEffort: existing?.bestEffort,
+  };
+
+  if (typeof patch.mode === "string") {
+    next.mode = patch.mode;
+  }
+  if ("channel" in patch) {
+    const channel = typeof patch.channel === "string" ? patch.channel.trim() : "";
+    next.channel = channel ? channel : undefined;
+  }
+  if ("to" in patch) {
+    const to = typeof patch.to === "string" ? patch.to.trim() : "";
+    next.to = to ? to : undefined;
+  }
+  if (typeof patch.bestEffort === "boolean") {
+    next.bestEffort = patch.bestEffort;
+  }
+
+  return next;
+}
+
 export function isJobDue(job: CronJob, nowMs: number, opts: { forced: boolean }) {
   if (opts.forced) {
     return true;

src/cron/service/timer.ts

@@ -125,7 +125,7 @@ export async function executeJob(
       emit(state, { jobId: job.id, action: "removed" });
     }
 
-    if (job.sessionTarget === "isolated") {
+    if (job.sessionTarget === "isolated" && !job.delivery) {
       const prefix = job.isolation?.postToMainPrefix?.trim() || "Cron";
       const mode = job.isolation?.postToMainMode ?? "summary";
 

src/cron/types.ts

@@ -10,6 +10,17 @@ export type CronWakeMode = "next-heartbeat" | "now";
 
 export type CronMessageChannel = ChannelId | "last";
 
+export type CronDeliveryMode = "none" | "announce" | "deliver";
+
+export type CronDelivery = {
+  mode: CronDeliveryMode;
+  channel?: CronMessageChannel;
+  to?: string;
+  bestEffort?: boolean;
+};
+
+export type CronDeliveryPatch = Partial<CronDelivery>;
+
 export type CronPayload =
   | { kind: "systemEvent"; text: string }
   | {
@@ -75,6 +86,7 @@ export type CronJob = {
   sessionTarget: CronSessionTarget;
   wakeMode: CronWakeMode;
   payload: CronPayload;
+  delivery?: CronDelivery;
   isolation?: CronIsolation;
   state: CronJobState;
 };
@@ -90,5 +102,6 @@ export type CronJobCreate = Omit<CronJob, "id" | "createdAtMs" | "updatedAtMs" |
 
 export type CronJobPatch = Partial<Omit<CronJob, "id" | "createdAtMs" | "state" | "payload">> & {
   payload?: CronPayloadPatch;
+  delivery?: CronDeliveryPatch;
   state?: Partial<CronJobState>;
 };