cron: expose payload on CronHookContext for middleware hooks

Arry8 · Arry8 · commit dbe6470ada33 · 2026-03-15T17:10:53.000-04:00
beforeRun/afterComplete/onFailure/afterRun hooks now receive ctx.payload
so scripts can inspect kind, command, message, etc. and make decisions
(abort, conditional logic, audit) without guessing from the job name.

- Add payload: CronPayload to CronHookContext type (hooks.ts)
- Pass structuredClone(job.payload) in all three makeHookCtx sites
  (timer.ts scheduled runs, timer.ts catch-up runs, ops.ts manual runs)
- hooks.test.ts: 3 new tests — kind-based abort, non-matching kind,
  payload field access via ctx.meta
diff --git a/src/cron/hooks.test.ts b/src/cron/hooks.test.ts
@@ -35,6 +35,7 @@ beforeEach(() => {
 
 function makeCtx(
   hookPoint: "beforeRun" | "afterComplete" | "onFailure" | "afterRun",
+  payload: CronHookContext["payload"] = { kind: "agentTurn", message: "hello" },
 ): CronHookContext {
   return {
     hookPoint,
@@ -45,6 +46,7 @@ function makeCtx(
       agentId: "test-agent",
       schedule: { kind: "every", everyMs: 60_000 },
     },
+    payload,
     meta: {},
     log: noopLog,
   };
@@ -320,4 +322,44 @@ describe("runCronHooks", () => {
     const result = await runCronHooks("afterRun", makeCtx("afterRun"), entries);
     expect(result.aborted).toBe(false);
   });
+
+  it("exposes payload.kind to hook via ctx.payload", async () => {
+    // Hook reads ctx.payload.kind and aborts only when it is "agentTurn".
+    const script = inlineHook(
+      `async function(ctx) { return ctx.payload.kind === "agentTurn" ? { abort: true, reason: "kind-check" } : {}; }`,
+    );
+    const entries = [{ script, priority: 10 }];
+    const result = await runCronHooks(
+      "beforeRun",
+      makeCtx("beforeRun", { kind: "agentTurn", message: "hi" }),
+      entries,
+    );
+    expect(result.aborted).toBe(true);
+    expect(result.reason).toBe("kind-check");
+  });
+
+  it("does not abort when payload.kind does not match hook condition", async () => {
+    const script = inlineHook(
+      `async function(ctx) { return ctx.payload.kind === "agentTurn" ? { abort: true } : {}; }`,
+    );
+    const entries = [{ script, priority: 10 }];
+    // systemEvent payload — hook condition should not trigger abort.
+    const result = await runCronHooks(
+      "beforeRun",
+      makeCtx("beforeRun", { kind: "systemEvent", text: "ping" }),
+      entries,
+    );
+    expect(result.aborted).toBe(false);
+  });
+
+  it("exposes all payload fields to the hook", async () => {
+    // Hook reads nested payload fields and signals via meta to verify they are accessible.
+    const script = inlineHook(
+      `async function(ctx) { ctx.meta.seenMessage = ctx.payload.message; }`,
+    );
+    const entries = [{ script, priority: 10 }];
+    const ctx = makeCtx("afterRun", { kind: "agentTurn", message: "check-fields" });
+    await runCronHooks("afterRun", ctx, entries);
+    expect(ctx.meta.seenMessage).toBe("check-fields");
+  });
 });
diff --git a/src/cron/hooks.ts b/src/cron/hooks.ts
@@ -4,7 +4,7 @@ import type { CronConfig, CronHookEntry, CronLifecycleHookPoint } from "../confi
 import { importFileModule, resolveFunctionModuleExport } from "../hooks/module-loader.js";
 import { resolveUserPath } from "../utils.js";
 import type { Logger } from "./service/state.js";
-import type { CronJob } from "./types.js";
+import type { CronJob, CronPayload } from "./types.js";
 
 const DEFAULT_PRIORITY = 10;
 const HOOK_TIMEOUT_MS = 10_000;
@@ -13,6 +13,8 @@ export type CronHookContext = {
   hookPoint: CronLifecycleHookPoint;
   workflow: string;
   job: Pick<CronJob, "id" | "name" | "agentId" | "schedule">;
+  /** The job's payload for this run. Hook scripts can inspect kind/command/message to make decisions. */
+  payload: CronPayload;
   error?: string;
   status?: string;
   durationMs?: number;
diff --git a/src/cron/service/ops.ts b/src/cron/service/ops.ts
@@ -478,6 +478,7 @@ async function finishPreparedManualRun(
       agentId: executionJob.agentId,
       schedule: executionJob.schedule,
     },
+    payload: structuredClone(executionJob.payload),
     meta: hookMeta,
     log: state.deps.log,
     basePath: hookBasePath,
diff --git a/src/cron/service/timer.ts b/src/cron/service/timer.ts
@@ -645,6 +645,7 @@ export async function onTimer(state: CronServiceState) {
         hookPoint,
         workflow: "cron",
         job: { id: job.id, name: job.name, agentId: job.agentId, schedule: job.schedule },
+        payload: structuredClone(job.payload),
         meta: hookMeta,
         log: state.deps.log,
         basePath: hookBasePath,
@@ -1027,6 +1028,7 @@ async function runStartupCatchupCandidate(
     hookPoint,
     workflow: "cron",
     job: { id: job.id, name: job.name, agentId: job.agentId, schedule: job.schedule },
+    payload: structuredClone(job.payload),
     meta: hookMeta,
     log: state.deps.log,
     basePath: hookBasePath,
