docs: document cron delivery helpers

steipete · steipete · commit 9d2c7bcb6655 · 2026-06-04T13:37:20.000-04:00
diff --git a/src/cron/active-jobs.ts b/src/cron/active-jobs.ts
@@ -1,3 +1,4 @@
+/** Tracks in-process cron executions so schedulers and wake paths avoid duplicate runs. */
 import { resolveGlobalSingleton } from "../shared/global-singleton.js";
 
 type CronActiveJobState = {
diff --git a/src/cron/delivery-context.ts b/src/cron/delivery-context.ts
@@ -1,3 +1,4 @@
+/** Converts live or stored session routing into cron delivery config. */
 import { extractDeliveryInfo } from "../config/sessions/delivery-info.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/cron/delivery-field-schemas.ts b/src/cron/delivery-field-schemas.ts
@@ -1,3 +1,4 @@
+/** Parses user-provided cron delivery fields into narrow runtime values. */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { z, type ZodType } from "zod";
 
@@ -8,6 +9,7 @@ const trimLowercaseStringPreprocess = (value: unknown) =>
 
 const DeliveryModeFieldSchema = z
   .preprocess(trimLowercaseStringPreprocess, z.enum(["deliver", "announce", "none", "webhook"]))
+  // "deliver" is the historical CLI spelling; runtime delivery uses announce.
   .transform((value) => (value === "deliver" ? "announce" : value));
 
 /** Accepts non-empty string fields after trimming and lowercasing user-provided delivery input. */
diff --git a/src/cron/delivery-plan.ts b/src/cron/delivery-plan.ts
@@ -1,3 +1,4 @@
+/** Resolves cron delivery and failure-notification routing from job config. */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
@@ -42,6 +43,8 @@ function resolveAnnounceChannel(params: {
   if (params.channel && params.channel !== "last") {
     return params.channel;
   }
+  // A prefixed recipient like "slack:C123" is enough to infer the channel when
+  // the cron config intentionally leaves channel at "last" or unset.
   return (
     (resolveTargetPrefixedChannel(params.to) as CronMessageChannel | undefined) ??
     params.channel ??
@@ -101,6 +104,8 @@ export function resolveCronDeliveryPlan(job: CronJob): CronDeliveryPlan {
     (job.sessionTarget === "isolated" ||
       job.sessionTarget === "current" ||
       job.sessionTarget.startsWith("session:"));
+  // Isolated/current/session cron jobs default to announce delivery so their
+  // output reaches the initiating session unless the job opts out.
   const resolvedMode = isIsolatedAgentTurn ? "announce" : "none";
 
   return {
@@ -196,6 +201,7 @@ export function resolveFailureDestination(
 
   const resolvedMode = mode ?? "announce";
   if (resolvedMode === "webhook" && !to) {
+    // Webhook failure destinations are only useful with a concrete URL/target.
     return null;
   }
 
@@ -207,6 +213,7 @@ export function resolveFailureDestination(
   };
 
   if (delivery && isSameDeliveryTarget(delivery, result)) {
+    // Avoid sending the same failure text through the primary delivery route twice.
     return null;
   }
 
diff --git a/src/cron/delivery-preview.ts b/src/cron/delivery-preview.ts
@@ -1,3 +1,4 @@
+/** Builds dry-run cron delivery labels for CLI/UI list surfaces. */
 import { resolveDefaultAgentId } from "../agents/agent-scope-config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { hasExplicitCronDeliveryTarget, resolveCronDeliveryPlan } from "./delivery-plan.js";
@@ -45,6 +46,7 @@ export async function resolveCronDeliveryPreview(params: {
     return { label: "not requested", detail: "not requested" };
   }
   if (plan.mode === "webhook") {
+    // Webhook previews do not resolve channel targets; runtime only needs the configured URL.
     const target = plan.to ? `webhook:${plan.to}` : "webhook";
     return { label: target, detail: plan.to ? "webhook" : "webhook target missing" };
   }
diff --git a/src/cron/delivery.ts b/src/cron/delivery.ts
@@ -1,3 +1,4 @@
+/** Sends cron announce payloads and best-effort failure notifications. */
 import { sendDurableMessageBatch } from "../channels/message/runtime.js";
 import type { CliDeps } from "../cli/deps.types.js";
 import { createOutboundSendDeps } from "../cli/outbound-send-deps.js";
@@ -55,6 +56,8 @@ async function resolveCronAnnounceDelivery(params: {
     }
   | { ok: false; error: Error }
 > {
+  // Resolve the target before building outbound identity/session so send errors
+  // report the configured route, not only the cron job id.
   const resolvedTarget = await resolveDeliveryTarget(params.cfg, params.agentId, {
     channel: params.target.channel as CronMessageChannel | undefined,
     to: params.target.to,
@@ -95,6 +98,8 @@ async function deliverCronAnnouncePayload(params: {
   message: string;
   abortSignal: AbortSignal;
 }): Promise<void> {
+  // Cron delivery is durable and non-best-effort for primary announces; partial
+  // channel failure must surface as a cron run failure.
   const send = await sendDurableMessageBatch({
     cfg: params.cfg,
     channel: params.delivery.resolvedTarget.channel,
diff --git a/src/cron/heartbeat-policy.ts b/src/cron/heartbeat-policy.ts
@@ -1,3 +1,4 @@
+/** Decides when cron heartbeat acknowledgements should stay out of visible delivery. */
 import { hasOutboundReplyContent } from "openclaw/plugin-sdk/reply-payload";
 import { stripHeartbeatToken } from "../auto-reply/heartbeat.js";
 
@@ -24,6 +25,8 @@ export function shouldSkipHeartbeatOnlyDelivery(
   if (hasAnyNonTextContent) {
     return false;
   }
+  // Heartbeat acks may include tiny punctuation/noise; strip the token before
+  // deciding whether there is user-visible text worth delivering.
   return payloads.some((payload) => {
     const result = stripHeartbeatToken(payload.text, {
       mode: "heartbeat",

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tracks in-process cron executions so schedulers and wake paths avoid duplicate runs. */`
`1`	`2`	`import { resolveGlobalSingleton } from "../shared/global-singleton.js";`
`2`	`3`
`3`	`4`	`type CronActiveJobState = {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Converts live or stored session routing into cron delivery config. */`
`1`	`2`	`import { extractDeliveryInfo } from "../config/sessions/delivery-info.js";`
`2`	`3`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Builds dry-run cron delivery labels for CLI/UI list surfaces. */`
`1`	`2`	`import { resolveDefaultAgentId } from "../agents/agent-scope-config.js";`
`2`	`3`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`3`	`4`	`import { hasExplicitCronDeliveryTarget, resolveCronDeliveryPlan } from "./delivery-plan.js";`
`@@ -45,6 +46,7 @@ export async function resolveCronDeliveryPreview(params: {`
`45`	`46`	`return { label: "not requested", detail: "not requested" };`
`46`	`47`	`}`
`47`	`48`	`if (plan.mode === "webhook") {`
	`49`	`+ // Webhook previews do not resolve channel targets; runtime only needs the configured URL.`
`48`	`50`	const target = plan.to ? `webhook:${plan.to}` : "webhook";
`49`	`51`	`return { label: target, detail: plan.to ? "webhook" : "webhook target missing" };`
`50`	`52`	`}`