vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-27 00:52:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(cron): add default stagger controls for scheduled jobs

Browse Source
This commit is contained in:
Peter Steinberger
2026-02-17 23:46:05 +01:00
parent b98b113b88
commit c26cf6aa83
20 changed files with 907 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
src/cli/cron-cli.test.ts
View File

@@ -1,14 +1,18 @@
import { Command } from "commander";
import { describe, expect, it, vi } from "vitest";
const callGatewayFromCli = vi.fn(
async (method: string, _opts: unknown, params?: unknown, _timeoutMs?: number) => {
if (method === "cron.status") {
return { enabled: true };
}
return { ok: true, params };
},
);
const defaultGatewayMock = async (
method: string,
_opts: unknown,
params?: unknown,
_timeoutMs?: number,
) => {
if (method === "cron.status") {
return { enabled: true };
}
return { ok: true, params };
};
const callGatewayFromCli = vi.fn(defaultGatewayMock);
vi.mock("./gateway-rpc.js", async () => {
const actual = await vi.importActual<typeof import("./gateway-rpc.js")>("./gateway-rpc.js");
@@ -45,8 +49,13 @@ function buildProgram() {
return program;
}
function resetGatewayMock() {
callGatewayFromCli.mockReset();
callGatewayFromCli.mockImplementation(defaultGatewayMock);
}
async function runCronEditAndGetPatch(editArgs: string[]): Promise<CronUpdatePatch> {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
await program.parseAsync(["cron", "edit", "job-1", ...editArgs], { from: "user" });
const updateCall = callGatewayFromCli.mock.calls.find((call) => call[0] === "cron.update");
@@ -55,7 +64,7 @@ async function runCronEditAndGetPatch(editArgs: string[]): Promise<CronUpdatePat
describe("cron cli", () => {
it("trims model and thinking on cron add", { timeout: 60_000 }, async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -89,7 +98,7 @@ describe("cron cli", () => {
});
it("defaults isolated cron add to announce delivery", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -116,7 +125,7 @@ describe("cron cli", () => {
});
it("infers sessionTarget from payload when --session is omitted", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -130,7 +139,7 @@ describe("cron cli", () => {
expect(params?.sessionTarget).toBe("main");
expect(params?.payload?.kind).toBe("systemEvent");
callGatewayFromCli.mockClear();
resetGatewayMock();
await program.parseAsync(
["cron", "add", "--name", "Isolated task", "--cron", "* * * * *", "--message", "hello"],
@@ -144,7 +153,7 @@ describe("cron cli", () => {
});
it("supports --keep-after-run on cron add", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -171,7 +180,7 @@ describe("cron cli", () => {
});
it("sends agent id on cron add", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -199,7 +208,7 @@ describe("cron cli", () => {
});
it("omits empty model and thinking on cron edit", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -218,7 +227,7 @@ describe("cron cli", () => {
});
it("trims model and thinking on cron edit", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -247,7 +256,7 @@ describe("cron cli", () => {
});
it("sets and clears agent id on cron edit", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -259,7 +268,7 @@ describe("cron cli", () => {
const patch = updateCall?.[2] as { patch?: { agentId?: unknown } };
expect(patch?.patch?.agentId).toBe("ops");
callGatewayFromCli.mockClear();
resetGatewayMock();
await program.parseAsync(["cron", "edit", "job-2", "--clear-agent"], {
from: "user",
});
@@ -269,7 +278,7 @@ describe("cron cli", () => {
});
it("allows model/thinking updates without --message", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -288,7 +297,7 @@ describe("cron cli", () => {
});
it("updates delivery settings without requiring --message", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -313,7 +322,7 @@ describe("cron cli", () => {
});
it("supports --no-deliver on cron edit", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -329,7 +338,7 @@ describe("cron cli", () => {
});
it("does not include undefined delivery fields when updating message", async () => {
callGatewayFromCli.mockClear();
resetGatewayMock();
const program = buildProgram();
@@ -404,4 +413,184 @@ describe("cron cli", () => {
expect(patch?.patch?.delivery?.mode).toBe("announce");
expect(patch?.patch?.delivery?.bestEffort).toBe(false);
});
it("sets explicit stagger for cron add", async () => {
resetGatewayMock();
const program = buildProgram();
await program.parseAsync(
[
"cron",
"add",
"--name",
"staggered",
"--cron",
"0 * * * *",
"--stagger",
"45s",
"--session",
"main",
"--system-event",
"tick",
],
{ from: "user" },
);
const addCall = callGatewayFromCli.mock.calls.find((call) => call[0] === "cron.add");
const params = addCall?.[2] as { schedule?: { kind?: string; staggerMs?: number } };
expect(params?.schedule?.kind).toBe("cron");
expect(params?.schedule?.staggerMs).toBe(45_000);
});
it("sets exact cron mode on add", async () => {
resetGatewayMock();
const program = buildProgram();
await program.parseAsync(
[
"cron",
"add",
"--name",
"exact",
"--cron",
"0 * * * *",
"--exact",
"--session",
"main",
"--system-event",
"tick",
],
{ from: "user" },
);
const addCall = callGatewayFromCli.mock.calls.find((call) => call[0] === "cron.add");
const params = addCall?.[2] as { schedule?: { kind?: string; staggerMs?: number } };
expect(params?.schedule?.kind).toBe("cron");
expect(params?.schedule?.staggerMs).toBe(0);
});
it("rejects --stagger with --exact on add", async () => {
resetGatewayMock();
const program = buildProgram();
await expect(
program.parseAsync(
[
"cron",
"add",
"--name",
"invalid",
"--cron",
"0 * * * *",
"--stagger",
"1m",
"--exact",
"--session",
"main",
"--system-event",
"tick",
],
{ from: "user" },
),
).rejects.toThrow("__exit__:1");
});
it("rejects --stagger when schedule is not cron", async () => {
resetGatewayMock();
const program = buildProgram();
await expect(
program.parseAsync(
[
"cron",
"add",
"--name",
"invalid",
"--every",
"10m",
"--stagger",
"30s",
"--session",
"main",
"--system-event",
"tick",
],
{ from: "user" },
),
).rejects.toThrow("__exit__:1");
});
it("sets explicit stagger for cron edit", async () => {
resetGatewayMock();
const program = buildProgram();
await program.parseAsync(["cron", "edit", "job-1", "--cron", "0 * * * *", "--stagger", "30s"], {
from: "user",
});
const updateCall = callGatewayFromCli.mock.calls.find((call) => call[0] === "cron.update");
const patch = updateCall?.[2] as {
patch?: { schedule?: { kind?: string; staggerMs?: number } };
};
expect(patch?.patch?.schedule?.kind).toBe("cron");
expect(patch?.patch?.schedule?.staggerMs).toBe(30_000);
});
it("applies --exact to existing cron job without requiring --cron on edit", async () => {
resetGatewayMock();
callGatewayFromCli.mockImplementation(
async (method: string, _opts: unknown, params?: unknown) => {
if (method === "cron.status") {
return { enabled: true };
}
if (method === "cron.list") {
return {
jobs: [
{
id: "job-1",
schedule: { kind: "cron", expr: "0 */2 * * *", tz: "UTC", staggerMs: 300_000 },
},
],
};
}
return { ok: true, params };
},
);
const program = buildProgram();
await program.parseAsync(["cron", "edit", "job-1", "--exact"], { from: "user" });
const updateCall = callGatewayFromCli.mock.calls.find((call) => call[0] === "cron.update");
const patch = updateCall?.[2] as {
patch?: { schedule?: { kind?: string; expr?: string; tz?: string; staggerMs?: number } };
};
expect(patch?.patch?.schedule).toEqual({
kind: "cron",
expr: "0 */2 * * *",
tz: "UTC",
staggerMs: 0,
});
});
it("rejects --exact on edit when existing job is not cron", async () => {
resetGatewayMock();
callGatewayFromCli.mockImplementation(
async (method: string, _opts: unknown, params?: unknown) => {
if (method === "cron.status") {
return { enabled: true };
}
if (method === "cron.list") {
return {
jobs: [{ id: "job-1", schedule: { kind: "every", everyMs: 60_000 } }],
};
}
return { ok: true, params };
},
);
const program = buildProgram();
await expect(
program.parseAsync(["cron", "edit", "job-1", "--exact"], { from: "user" }),
).rejects.toThrow("__exit__:1");
});
});

29
src/cli/cron-cli/register.cron-add.ts
View File

@@ -1,9 +1,9 @@
import type { Command } from "commander";
import type { CronJob } from "../../cron/types.js";
import type { GatewayRpcOpts } from "../gateway-rpc.js";
import { danger } from "../../globals.js";
import { sanitizeAgentId } from "../../routing/session-key.js";
import { defaultRuntime } from "../../runtime.js";
import type { GatewayRpcOpts } from "../gateway-rpc.js";
import { addGatewayClientOptions, callGatewayFromCli } from "../gateway-rpc.js";
import { parsePositiveIntOrUndefined } from "../program/helpers.js";
import {
@@ -74,8 +74,10 @@ export function registerCronAddCommand(cron: Command) {
.option("--wake <mode>", "Wake mode (now|next-heartbeat)", "now")
.option("--at <when>", "Run once at time (ISO) or +duration (e.g. 20m)")
.option("--every <duration>", "Run every duration (e.g. 10m, 1h)")
.option("--cron <expr>", "Cron expression (5-field)")
.option("--cron <expr>", "Cron expression (5-field or 6-field with seconds)")
.option("--tz <iana>", "Timezone for cron expressions (IANA)", "")
.option("--stagger <duration>", "Cron stagger window (e.g. 30s, 5m)")
.option("--exact", "Disable cron staggering (set stagger to 0)", false)
.option("--system-event <text>", "System event payload (main session)")
.option("--message <text>", "Agent message payload")
.option("--thinking <level>", "Thinking level for agent jobs (off|minimal|low|medium|high)")
@@ -93,6 +95,12 @@ export function registerCronAddCommand(cron: Command) {
.option("--json", "Output JSON", false)
.action(async (opts: GatewayRpcOpts & Record<string, unknown>, cmd?: Command) => {
try {
const staggerRaw = typeof opts.stagger === "string" ? opts.stagger.trim() : "";
const useExact = Boolean(opts.exact);
if (staggerRaw && useExact) {
throw new Error("Choose either --stagger or --exact, not both");
}
const schedule = (() => {
const at = typeof opts.at === "string" ? opts.at : "";
const every = typeof opts.every === "string" ? opts.every : "";
@@ -101,6 +109,9 @@ export function registerCronAddCommand(cron: Command) {
if (chosen !== 1) {
throw new Error("Choose exactly one schedule: --at, --every, or --cron");
}
if ((useExact || staggerRaw) && !cronExpr) {
throw new Error("--stagger/--exact are only valid with --cron");
}
if (at) {
const atIso = parseAt(at);
if (!atIso) {
@@ -115,10 +126,24 @@ export function registerCronAddCommand(cron: Command) {
}
return { kind: "every" as const, everyMs };
}
const staggerMs = (() => {
if (useExact) {
return 0;
}
if (!staggerRaw) {
return undefined;
}
const parsed = parseDurationMs(staggerRaw);
if (!parsed) {
throw new Error("Invalid --stagger; use e.g. 30s, 1m, 5m");
}
return parsed;
})();
return {
kind: "cron" as const,
expr: cronExpr,
tz: typeof opts.tz === "string" && opts.tz.trim() ? opts.tz.trim() : undefined,
staggerMs,
};
})();

48
src/cli/cron-cli/register.cron-edit.ts
View File

@@ -1,4 +1,5 @@
import type { Command } from "commander";
import type { CronJob } from "../../cron/types.js";
import { danger } from "../../globals.js";
import { sanitizeAgentId } from "../../routing/session-key.js";
import { defaultRuntime } from "../../runtime.js";
@@ -41,6 +42,8 @@ export function registerCronEditCommand(cron: Command) {
.option("--every <duration>", "Set interval duration like 10m")
.option("--cron <expr>", "Set cron expression")
.option("--tz <iana>", "Timezone for cron expressions (IANA)")
.option("--stagger <duration>", "Cron stagger window (e.g. 30s, 5m)")
.option("--exact", "Disable cron staggering (set stagger to 0)")
.option("--system-event <text>", "Set systemEvent payload")
.option("--message <text>", "Set agentTurn payload message")
.option("--thinking <level>", "Thinking level for agent jobs")
@@ -71,6 +74,24 @@ export function registerCronEditCommand(cron: Command) {
if (opts.announce && typeof opts.deliver === "boolean") {
throw new Error("Choose --announce or --no-deliver (not multiple).");
}
const staggerRaw = typeof opts.stagger === "string" ? opts.stagger.trim() : "";
const useExact = Boolean(opts.exact);
if (staggerRaw && useExact) {
throw new Error("Choose either --stagger or --exact, not both");
}
const requestedStaggerMs = (() => {
if (useExact) {
return 0;
}
if (!staggerRaw) {
return undefined;
}
const parsed = parseDurationMs(staggerRaw);
if (!parsed) {
throw new Error("Invalid --stagger; use e.g. 30s, 1m, 5m");
}
return parsed;
})();
const patch: Record<string, unknown> = {};
if (typeof opts.name === "string") {
@@ -117,6 +138,12 @@ export function registerCronEditCommand(cron: Command) {
if (scheduleChosen > 1) {
throw new Error("Choose at most one schedule change");
}
if (
(requestedStaggerMs !== undefined || typeof opts.tz === "string") &&
(opts.at || opts.every)
) {
throw new Error("--stagger/--exact/--tz are only valid for cron schedules");
}
if (opts.at) {
const atIso = parseAt(String(opts.at));
if (!atIso) {
@@ -134,6 +161,27 @@ export function registerCronEditCommand(cron: Command) {
kind: "cron",
expr: String(opts.cron),
tz: typeof opts.tz === "string" && opts.tz.trim() ? opts.tz.trim() : undefined,
staggerMs: requestedStaggerMs,
};
} else if (requestedStaggerMs !== undefined || typeof opts.tz === "string") {
const listed = (await callGatewayFromCli("cron.list", opts, {
includeDisabled: true,
})) as { jobs?: CronJob[] } | null;
const existing = (listed?.jobs ?? []).find((job) => job.id === id);
if (!existing) {
throw new Error(`unknown cron job id: ${id}`);
}
if (existing.schedule.kind !== "cron") {
throw new Error("Current job is not a cron schedule; use --cron to convert first");
}
const tz =
typeof opts.tz === "string" ? opts.tz.trim() || undefined : existing.schedule.tz;
patch.schedule = {
kind: "cron",
expr: existing.schedule.expr,
tz,
staggerMs:
requestedStaggerMs !== undefined ? requestedStaggerMs : existing.schedule.staggerMs,
};
}

50
src/cli/cron-cli/shared.test.ts
View File

@@ -60,4 +60,54 @@ describe("printCronList", () => {
expect(() => printCronList([jobWithTarget], mockRuntime)).not.toThrow();
expect(logs.some((line) => line.includes("isolated"))).toBe(true);
});
it("shows stagger label for cron schedules", () => {
const logs: string[] = [];
const mockRuntime = {
log: (msg: string) => logs.push(msg),
error: () => {},
exit: () => {},
} as RuntimeEnv;
const job: CronJob = {
id: "staggered-job",
name: "Staggered",
enabled: true,
createdAtMs: Date.now(),
updatedAtMs: Date.now(),
schedule: { kind: "cron", expr: "0 * * * *", staggerMs: 5 * 60_000 },
sessionTarget: "main",
wakeMode: "next-heartbeat",
payload: { kind: "systemEvent", text: "tick" },
state: {},
};
printCronList([job], mockRuntime);
expect(logs.some((line) => line.includes("(stagger 5m)"))).toBe(true);
});
it("shows exact label for cron schedules with stagger disabled", () => {
const logs: string[] = [];
const mockRuntime = {
log: (msg: string) => logs.push(msg),
error: () => {},
exit: () => {},
} as RuntimeEnv;
const job: CronJob = {
id: "exact-job",
name: "Exact",
enabled: true,
createdAtMs: Date.now(),
updatedAtMs: Date.now(),
schedule: { kind: "cron", expr: "0 7 * * *", staggerMs: 0 },
sessionTarget: "main",
wakeMode: "next-heartbeat",
payload: { kind: "systemEvent", text: "tick" },
state: {},
};
printCronList([job], mockRuntime);
expect(logs.some((line) => line.includes("(exact)"))).toBe(true);
});
});

12
src/cli/cron-cli/shared.ts
View File

@@ -1,10 +1,11 @@
import type { CronJob, CronSchedule } from "../../cron/types.js";
import type { GatewayRpcOpts } from "../gateway-rpc.js";
import { listChannelPlugins } from "../../channels/plugins/index.js";
import { parseAbsoluteTimeMs } from "../../cron/parse.js";
import type { CronJob, CronSchedule } from "../../cron/types.js";
import { resolveCronStaggerMs } from "../../cron/stagger.js";
import { formatDurationHuman } from "../../infra/format-time/format-duration.ts";
import { defaultRuntime } from "../../runtime.js";
import { colorize, isRich, theme } from "../../terminal/theme.js";
import type { GatewayRpcOpts } from "../gateway-rpc.js";
import { callGatewayFromCli } from "../gateway-rpc.js";
export const getCronChannelOptions = () =>
@@ -137,7 +138,12 @@ const formatSchedule = (schedule: CronSchedule) => {
if (schedule.kind === "every") {
return `every ${formatDurationHuman(schedule.everyMs)}`;
}
return schedule.tz ? `cron ${schedule.expr} @ ${schedule.tz}` : `cron ${schedule.expr}`;
const base = schedule.tz ? `cron ${schedule.expr} @ ${schedule.tz}` : `cron ${schedule.expr}`;
const staggerMs = resolveCronStaggerMs(schedule);
if (staggerMs <= 0) {
return `${base} (exact)`;
}
return `${base} (stagger ${formatDurationHuman(staggerMs)})`;
};
const formatStatus = (job: CronJob) => {