@app-vitals/agent-runtime 0.3.0 → 0.4.0

package/boot.ts

@@ -58,6 +58,7 @@ import { createContextStampReader } from "./context-stamp.ts";
 import { reportCronFailure } from "./cron-failure-reporter.ts";
 import type { CronHandlerDeps } from "./cron-handler.ts";
 import { handleCronRequest } from "./cron-handler.ts";
+import { createRunNowHonourer } from "./cron-run-now.ts";
 import {
   HttpCronRunReporter,
   NoopCronRunReporter,
@@ -684,6 +685,54 @@ export async function startAgent(
   const cronTasks = new Map<string, ReturnType<typeof nodeCron.schedule>>();
 
   if (runtimeClient && agentId) {
+    // Run-now requests (COS-42.1): honoured at most once each, in memory.
+    // Dispatch kind per job from the latest sync, so run-now takes the same
+    // path a scheduled tick would (loop-classified crons go through dispatchLoop).
+    let dispatchKinds = new Map<string, "loop" | "generic">();
+    const honourRunNow = createRunNowHonourer({
+      clock: SystemClock(),
+      dispatch: async (req) => {
+        if (dispatchKinds.get(req.jobId) === "loop") {
+          if (!extension.dispatchLoop) {
+            throw new Error(
+              `cron job ${req.jobId} classified as loop but the agent extension has no dispatchLoop`,
+            );
+          }
+          // dispatchLoop creates no run-now run of its own, so record one here:
+          // creating it clears the stamp and flips the audit row to honoured.
+          const reporter = cronRunReporter ?? new NoopCronRunReporter();
+          const startedAt = SystemClock().now();
+          const runId = await reporter.createRun(
+            req.jobId,
+            startedAt,
+            undefined,
+            undefined,
+            undefined,
+            req.commandVariant,
+          );
+          let outcome: "completed" | "failed" = "completed";
+          try {
+            await extension.dispatchLoop(req.jobId);
+          } catch (err) {
+            outcome = "failed";
+            throw err;
+          } finally {
+            await reporter
+              .completeRun(req.jobId, runId, SystemClock().now(), outcome)
+              .catch(() => {});
+          }
+          return;
+        }
+        await handleCronRequest(req, cronDeps);
+      },
+      onError: (jobId, err) =>
+        reportCronFailure(jobId, err, {
+          cronRunReporter: cronRunReporter ?? new NoopCronRunReporter(),
+          sentryClient: process.env.SENTRY_DSN ? Sentry : undefined,
+          clock: SystemClock(),
+        }),
+    });
+
     async function syncCrons() {
       if (!runtimeClient || !agentId) return;
       let jobs: Awaited<ReturnType<typeof runtimeClient.listAgentCronJobs>>;
@@ -705,6 +754,13 @@ export async function startAgent(
       // the coding extension's loop-cron-classifier.ts for the full decision.
       const scheduled = planCronSchedule(extension, jobs);
       const desired = new Map(scheduled.map((entry) => [entry.job.id, entry]));
+      dispatchKinds = new Map(
+        scheduled.map((entry) => [entry.job.id, entry.dispatch]),
+      );
+
+      // Fire-and-forget: a run can take minutes and must not hold up the sync.
+      // Only scheduled (enabled) jobs: a manually disabled cron is not run.
+      void honourRunNow(jobs.filter((job) => desired.has(job.id)));
 
       // Cancel removed/disabled jobs
       for (const [id, task] of cronTasks) {

package/cron-handler.ts

@@ -162,6 +162,8 @@ interface CronRequest {
   user?: string;
   silent?: boolean;
   preCheck?: string;
+  /** Run-attribution tag, e.g. "run-now" (COS-42.1); passed to createRun. */
+  commandVariant?: string;
 }
 
 export interface CronHandlerDeps {
@@ -266,7 +268,14 @@ export async function handleCronRequest(
 
   // CREATE run at start (before preCheck)
   const runId = cronRunReporter
-    ? await cronRunReporter.createRun(jobId, startedAt)
+    ? await cronRunReporter.createRun(
+        jobId,
+        startedAt,
+        undefined,
+        undefined,
+        undefined,
+        req.commandVariant,
+      )
     : null;
 
   // Best-effort redacted transcript upload (COS-43.1). Runs only after the

package/cron-handler.unit.test.ts

@@ -1176,6 +1176,34 @@ describe("handleCronRequest — telemetry forwarding", () => {
   });
 });
 
+describe("handleCronRequest — commandVariant (COS-42.1)", () => {
+  test("a run-now request creates its run with commandVariant run-now", async () => {
+    const created: unknown[][] = [];
+    const reporter: CronRunReporter = {
+      async createRun(...args: unknown[]) {
+        created.push(args);
+        return "run-now-1";
+      },
+      async completeRun() {},
+      async skipRun() {},
+      async recordProgress() {},
+      async recordSessionId() {},
+    };
+    await handleCronRequest(
+      {
+        jobId: "j-now",
+        prompt: "hello",
+        silent: true,
+        commandVariant: "run-now",
+      },
+      { ...deps, cronRunReporter: reporter },
+    );
+    expect(created).toHaveLength(1);
+    expect(created[0]?.[0]).toBe("j-now");
+    expect(created[0]?.[5]).toBe("run-now");
+  });
+});
+
 // ─── transcript upload hook (COS-43.1) ───────────────────────────────────────
 
 describe("handleCronRequest — transcript upload (COS-43.1)", () => {

package/cron-run-now.ts

@@ -0,0 +1,116 @@
+/**
+ * runtime/cron-run-now.ts
+ *
+ * Honours cron run-now requests (COS-42.1). The admin stamps
+ * `runRequestedAt` on a stored cron job; on each cron sync tick the runtime
+ * runs the job once when the stamp is strictly newer than the last one it
+ * honoured (held in memory) and at most 15 minutes old. An older stamp is
+ * logged as expired and never run. The request is dispatched with the job's
+ * own stored fields, never a prompt from anywhere else, and tagged
+ * commandVariant "run-now" so run creation clears the stamp admin-side.
+ */
+
+import type { Clock } from "./clock.ts";
+
+/** A request older than this is expired and never run. */
+export const RUN_NOW_FRESH_MS = 15 * 60_000;
+
+/** The stored cron job fields the honourer reads. */
+export interface RunNowJob {
+  id: string;
+  prompt: string;
+  channel?: string | null;
+  user?: string | null;
+  silent?: boolean;
+  preCheck?: string | null;
+  /** A manually disabled job is never run, even with a fresh stamp. */
+  enabled?: boolean;
+  /** ISO string on the wire (typed Date by the generated client). */
+  runRequestedAt?: string | Date | null;
+}
+
+export interface RunNowRequest {
+  jobId: string;
+  prompt: string;
+  channel?: string;
+  user?: string;
+  silent?: boolean;
+  preCheck?: string;
+  commandVariant: "run-now";
+}
+
+interface RunNowHonourerDeps {
+  clock: Clock;
+  /** Runs the job (handleCronRequest in production). */
+  dispatch: (req: RunNowRequest) => Promise<void>;
+  /** Called when a dispatch throws; the request is not retried. */
+  onError?: (jobId: string, err: unknown) => void | Promise<void>;
+  log?: (line: string) => void;
+}
+
+/**
+ * Returns a function to call with the fresh job list on every sync tick. It
+ * resolves once every dispatch it started has settled; callers that must not
+ * wait on long runs simply do not await it.
+ */
+export function createRunNowHonourer(
+  deps: RunNowHonourerDeps,
+): (jobs: readonly RunNowJob[]) => Promise<void> {
+  const { clock, dispatch, onError, log = console.log } = deps;
+  // jobId -> last honoured / last expired-logged runRequestedAt (epoch ms).
+  const lastHonoured = new Map<string, number>();
+  const expiredLogged = new Map<string, number>();
+
+  return async (jobs) => {
+    const running: Promise<void>[] = [];
+    for (const job of jobs) {
+      if (!job.runRequestedAt || job.enabled === false) continue;
+      const requestedMs = new Date(job.runRequestedAt).getTime();
+      if (Number.isNaN(requestedMs)) continue;
+      const requested = new Date(requestedMs).toISOString();
+
+      const seen = lastHonoured.get(job.id);
+      if (seen !== undefined && requestedMs <= seen) continue;
+
+      if (clock.now().getTime() - requestedMs > RUN_NOW_FRESH_MS) {
+        if (expiredLogged.get(job.id) !== requestedMs) {
+          expiredLogged.set(job.id, requestedMs);
+          log(
+            JSON.stringify({
+              event: "cron-run-now",
+              status: "expired",
+              jobId: job.id,
+              requestedAt: requested,
+            }),
+          );
+        }
+        continue;
+      }
+
+      // Recorded before dispatch so a slow or failing run is never repeated.
+      lastHonoured.set(job.id, requestedMs);
+      log(
+        JSON.stringify({
+          event: "cron-run-now",
+          status: "honouring",
+          jobId: job.id,
+          requestedAt: requested,
+        }),
+      );
+      running.push(
+        dispatch({
+          jobId: job.id,
+          prompt: job.prompt,
+          channel: job.channel ?? undefined,
+          user: job.user ?? undefined,
+          silent: job.silent,
+          preCheck: job.preCheck ?? undefined,
+          commandVariant: "run-now",
+        }).catch(async (err) => {
+          await onError?.(job.id, err);
+        }),
+      );
+    }
+    await Promise.all(running);
+  };
+}

package/cron-run-now.unit.test.ts

@@ -0,0 +1,156 @@
+/**
+ * runtime/cron-run-now.unit.test.ts
+ * Honour / expire / once logic for cron run-now requests (COS-42.1), with an
+ * injected clock and dispatch.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  createRunNowHonourer,
+  RUN_NOW_FRESH_MS,
+  type RunNowJob,
+} from "./cron-run-now.ts";
+
+const NOW = new Date("2026-10-26T12:00:00.000Z");
+
+function job(over: Partial<RunNowJob> = {}): RunNowJob {
+  return {
+    id: "job-1",
+    prompt: "stored prompt",
+    channel: "C1",
+    user: null,
+    silent: false,
+    preCheck: null,
+    runRequestedAt: null,
+    ...over,
+  };
+}
+
+function setup() {
+  let nowMs = NOW.getTime();
+  const dispatched: Array<Record<string, unknown>> = [];
+  const logs: string[] = [];
+  const honour = createRunNowHonourer({
+    clock: { now: () => new Date(nowMs) },
+    dispatch: async (req) => {
+      dispatched.push(req as unknown as Record<string, unknown>);
+    },
+    log: (line) => logs.push(line),
+  });
+  return {
+    honour,
+    dispatched,
+    logs,
+    advance: (ms: number) => {
+      nowMs += ms;
+    },
+  };
+}
+
+const ago = (ms: number) => new Date(NOW.getTime() - ms).toISOString();
+
+describe("createRunNowHonourer", () => {
+  it("never runs a manually disabled job", async () => {
+    const t = setup();
+    await t.honour([job({ enabled: false, runRequestedAt: ago(1000) })]);
+    expect(t.dispatched).toHaveLength(0);
+  });
+
+  it("runs a fresh request once with the stored job fields and run-now variant", async () => {
+    const { honour, dispatched } = setup();
+    await honour([job({ runRequestedAt: ago(60_000) })]);
+    expect(dispatched).toEqual([
+      {
+        jobId: "job-1",
+        prompt: "stored prompt",
+        channel: "C1",
+        user: undefined,
+        silent: false,
+        preCheck: undefined,
+        commandVariant: "run-now",
+      },
+    ]);
+  });
+
+  it("does not run the same request twice across ticks", async () => {
+    const { honour, dispatched, advance } = setup();
+    const j = job({ runRequestedAt: ago(60_000) });
+    await honour([j]);
+    advance(60_000);
+    await honour([j]);
+    await honour([j]);
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("runs again for a strictly newer request", async () => {
+    const { honour, dispatched, advance } = setup();
+    await honour([job({ runRequestedAt: ago(60_000) })]);
+    advance(120_000);
+    await honour([job({ runRequestedAt: ago(10_000) })]);
+    expect(dispatched).toHaveLength(2);
+  });
+
+  it("ignores an older-or-equal stamp than the last honoured", async () => {
+    const { honour, dispatched } = setup();
+    await honour([job({ runRequestedAt: ago(10_000) })]);
+    await honour([job({ runRequestedAt: ago(30_000) })]);
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("ignores a request older than 15 minutes and logs expired once", async () => {
+    const { honour, dispatched, logs } = setup();
+    const j = job({ runRequestedAt: ago(RUN_NOW_FRESH_MS + 1) });
+    await honour([j]);
+    await honour([j]);
+    expect(dispatched).toEqual([]);
+    const expired = logs.filter((l) => l.includes("expired"));
+    expect(expired).toHaveLength(1);
+    expect(logs.join("\n")).not.toContain("stored prompt");
+  });
+
+  it("a request exactly 15 minutes old is still fresh", async () => {
+    const { honour, dispatched } = setup();
+    await honour([job({ runRequestedAt: ago(RUN_NOW_FRESH_MS) })]);
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("a request that ages out between ticks without being seen expires", async () => {
+    const { honour, dispatched, logs, advance } = setup();
+    const j = job({ runRequestedAt: ago(0) });
+    advance(RUN_NOW_FRESH_MS + 60_000);
+    await honour([j]);
+    expect(dispatched).toEqual([]);
+    expect(logs.some((l) => l.includes("expired"))).toBe(true);
+  });
+
+  it("skips jobs with no request", async () => {
+    const { honour, dispatched, logs } = setup();
+    await honour([job(), job({ id: "job-2" })]);
+    expect(dispatched).toEqual([]);
+    expect(logs).toEqual([]);
+  });
+
+  it("a failing dispatch does not stop the other jobs and is not retried", async () => {
+    const dispatched: string[] = [];
+    const failures: string[] = [];
+    const honour = createRunNowHonourer({
+      clock: { now: () => NOW },
+      dispatch: async (req) => {
+        dispatched.push(req.jobId);
+        if (req.jobId === "bad") throw new Error("boom");
+      },
+      onError: (jobId) => {
+        failures.push(jobId);
+      },
+      log: () => {},
+    });
+    const jobs = [
+      job({ id: "bad", runRequestedAt: ago(1000) }),
+      job({ id: "good", runRequestedAt: ago(1000) }),
+    ];
+    await honour(jobs);
+    await honour(jobs);
+    expect(dispatched).toEqual(["bad", "good"]);
+    expect(failures).toEqual(["bad"]);
+  });
+});

package/cutover-validate.integration.test.ts

@@ -35,6 +35,8 @@ function makeCron(id: string): AgentCronJob {
     system: false,
     parentCronId: null,
     lockdownDisabledAt: null,
+    runRequestedAt: null,
+    runRequestedBy: null,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -40,8 +40,8 @@
     "./workspace-paths": "./workspace-paths.ts"
   },
   "dependencies": {
-    "@app-vitals/agent-admin": "0.3.0",
-    "@app-vitals/agent-lib": "0.3.0",
+    "@app-vitals/agent-admin": "0.4.0",
+    "@app-vitals/agent-lib": "0.4.0",
     "@octokit/auth-app": "^8.2.0",
     "@sentry/bun": "^10.63.0",
     "@slack/bolt": "^5.0.0",

package/shipwright-runtime-client.integration.test.ts

@@ -53,6 +53,8 @@ const SAMPLE_CRONS: AgentCronJob[] = [
     system: false,
     parentCronId: null,
     lockdownDisabledAt: null,
+    runRequestedAt: null,
+    runRequestedBy: null,
     createdAt: new Date("2025-01-01T00:00:00Z"),
     updatedAt: new Date("2025-01-01T00:00:00Z"),
   },