@app-vitals/agent-admin 0.3.0 → 0.4.0

package/src/cron-run-now.smoke.test.ts

@@ -0,0 +1,218 @@
+/**
+ * admin/src/cron-run-now.smoke.test.ts
+ *
+ * POST /agents/{id}/crons/{cronId}/run-now (COS-42.1) over the real admin
+ * route table and auth middleware, with an in-memory store and a fixed clock.
+ * Uses app.request() — no real server, no real DB.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import {
+  type AdminDeps,
+  createAdminApp,
+  parseAdminApiKeys,
+} from "./agents-api.ts";
+import { PLATFORM_OPS_ROUTES } from "./api-auth.ts";
+import type {
+  CronRunNowStore,
+  RunRequestRow,
+  RunNowCron,
+} from "./cron-run-now.ts";
+import { parseCronRunNowConfig } from "./cron-run-now-config.ts";
+
+const AGENT = "agent-a";
+const CRON = "cron-1";
+const LOCKED = "cron-locked";
+const SECRET_PROMPT = "super secret prompt text";
+
+const ADMIN = "admin-key";
+const READ = "platform-read-token";
+const OPS = "platform-ops-token";
+const OWN_KEY = "own-agent-key";
+const OTHER_KEY = "other-agent-key";
+
+const NOW = new Date("2026-10-26T12:00:00.000Z");
+
+function memoryStore() {
+  const crons = new Map<string, RunNowCron>([
+    [CRON, { id: CRON, agentId: AGENT, lockdownDisabledAt: null }],
+    [LOCKED, { id: LOCKED, agentId: AGENT, lockdownDisabledAt: NOW }],
+  ]);
+  const requests: RunRequestRow[] = [];
+  const events: string[] = [];
+  const store: CronRunNowStore = {
+    async findCron(agentId, cronId) {
+      const cron = crons.get(cronId);
+      return cron && cron.agentId === agentId ? cron : null;
+    },
+    async recordRequest(input) {
+      events.push("record");
+      const row: RunRequestRow = {
+        id: `req-${requests.length + 1}`,
+        status: "requested",
+        honouredRunId: null,
+        ...input,
+      };
+      requests.push(row);
+      return row;
+    },
+  };
+  return { store, requests, events };
+}
+
+function makeApp(opts: { enabled?: boolean } = {}) {
+  const mem = memoryStore();
+  const deps = {
+    agentService: { exists: async () => true },
+    agentTokenService: { validate: async () => null },
+    agentMemberService: { listByEmail: async () => [] },
+    adminApiKeys: parseAdminApiKeys(
+      `root:${ADMIN}:*,reader:${READ}:platform.read,operator:${OPS}:platform.ops,own:${OWN_KEY}:${AGENT},other:${OTHER_KEY}:agent-other`,
+    ),
+    sessionSecret: "s".repeat(32),
+    cronRunNow: {
+      config: parseCronRunNowConfig({
+        SHIPWRIGHT_CRON_RUN_NOW_ENABLED:
+          opts.enabled === false ? undefined : "enabled",
+      }),
+      store: mem.store,
+      clock: { now: () => NOW },
+    },
+  } as unknown as AdminDeps;
+  return { app: createAdminApp(deps), ...mem };
+}
+
+function runNow(
+  app: ReturnType<typeof createAdminApp>,
+  token: string,
+  init: { body?: string; cron?: string; contentType?: string } = {},
+) {
+  return app.request(`/agents/${AGENT}/crons/${init.cron ?? CRON}/run-now`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(init.contentType ? { "Content-Type": init.contentType } : {}),
+    },
+    ...(init.body !== undefined ? { body: init.body } : {}),
+  });
+}
+
+describe("POST /agents/{id}/crons/{cronId}/run-now", () => {
+  let logs: string[];
+  const spies: Array<{ mockRestore: () => void }> = [];
+  beforeEach(() => {
+    logs = [];
+    for (const m of ["log", "info", "warn", "error"] as const) {
+      spies.push(
+        spyOn(console, m).mockImplementation((...a: unknown[]) => {
+          logs.push(a.map(String).join(" "));
+        }),
+      );
+    }
+  });
+  afterEach(() => {
+    for (const s of spies.splice(0)) s.mockRestore();
+  });
+
+  it("flag off -> 404 for every caller, nothing written", async () => {
+    const { app, requests } = makeApp({ enabled: false });
+    for (const token of [ADMIN, OPS, OWN_KEY]) {
+      const res = await runNow(app, token);
+      expect(res.status).toBe(404);
+      expect(await res.json()).toEqual({ error: "Not found" });
+    }
+    expect(requests).toEqual([]);
+  });
+
+  it("any body -> 400, nothing written", async () => {
+    const { app, requests } = makeApp();
+    for (const init of [
+      {
+        body: JSON.stringify({ prompt: SECRET_PROMPT }),
+        contentType: "application/json",
+      },
+      { body: "{}", contentType: "application/json" },
+      { body: "x", contentType: "text/plain" },
+    ]) {
+      expect((await runNow(app, ADMIN, init)).status).toBe(400);
+    }
+    expect(requests).toEqual([]);
+  });
+
+  it("platform-read -> 403; other agent's key -> 403", async () => {
+    const { app, requests } = makeApp();
+    expect((await runNow(app, READ)).status).toBe(403);
+    expect((await runNow(app, OTHER_KEY)).status).toBe(403);
+    expect(requests).toEqual([]);
+  });
+
+  it("no credentials -> 401", async () => {
+    const { app } = makeApp();
+    const res = await app.request(`/agents/${AGENT}/crons/${CRON}/run-now`, {
+      method: "POST",
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("admin, platform-ops and the agent's own key -> 202 with an audit row", async () => {
+    const { app, requests } = makeApp();
+    for (const token of [ADMIN, OPS, OWN_KEY]) {
+      const res = await runNow(app, token);
+      expect(res.status).toBe(202);
+      expect(await res.json()).toEqual({ requestedAt: NOW.toISOString() });
+    }
+    expect(requests).toHaveLength(3);
+    for (const row of requests) {
+      expect(row).toMatchObject({
+        cronId: CRON,
+        agentId: AGENT,
+        requestedAt: NOW,
+        status: "requested",
+      });
+      expect(row.requestedBy.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("writes the audit row before responding", async () => {
+    const { app, events } = makeApp();
+    const res = await runNow(app, ADMIN);
+    expect(res.status).toBe(202);
+    expect(events).toEqual(["record"]);
+  });
+
+  it("lockdown-disabled cron -> 409", async () => {
+    const { app, requests } = makeApp();
+    const res = await runNow(app, ADMIN, { cron: LOCKED });
+    expect(res.status).toBe(409);
+    expect(requests).toEqual([]);
+  });
+
+  it("unknown cron -> 404", async () => {
+    const { app } = makeApp();
+    expect((await runNow(app, ADMIN, { cron: "nope" })).status).toBe(404);
+  });
+
+  it("logs one structured cron-run-now line and never the prompt", async () => {
+    const { app } = makeApp();
+    await runNow(app, ADMIN, {
+      body: JSON.stringify({ prompt: SECRET_PROMPT }),
+      contentType: "application/json",
+    });
+    await runNow(app, OPS);
+    const lines = logs.filter((l) => l.includes('"cron-run-now"'));
+    expect(lines).toHaveLength(1);
+    const parsed = JSON.parse(lines[0] as string);
+    expect(parsed).toMatchObject({
+      event: "cron-run-now",
+      agentId: AGENT,
+      cronId: CRON,
+    });
+    expect(logs.join("\n")).not.toContain(SECRET_PROMPT);
+  });
+
+  it("is on PLATFORM_OPS_ROUTES", () => {
+    expect(PLATFORM_OPS_ROUTES.map((r) => `${r.method} ${r.path}`)).toContain(
+      "POST /agents/{id}/crons/{cronId}/run-now",
+    );
+  });
+});

package/src/cron-run-now.ts

@@ -0,0 +1,207 @@
+/**
+ * admin/src/cron-run-now.ts
+ *
+ * Cron run-now (COS-42.1): POST /agents/{id}/crons/{cronId}/run-now asks the
+ * agent's runtime to fire one cron job immediately. The route takes NO body
+ * and never reads or logs a prompt: it only stamps `runRequestedAt` /
+ * `runRequestedBy` on the stored job and writes an AgentCronRunRequest audit
+ * row (before the 202). The runtime's cron sync honours the stamp once, while
+ * it is fresh, running the job's own stored prompt.
+ *
+ * Gates, in order: flag (SHIPWRIGHT_CRON_RUN_NOW_ENABLED, 404 when off) →
+ * caller (`*`, platform.ops, or the agent's own key; 403) → empty body (400)
+ * → cron exists for the agent (404) → not lockdown-disabled (409).
+ */
+
+import { callerLabel } from "@app-vitals/agent-lib/request-context";
+import { createRoute, type OpenAPIHono } from "@hono/zod-openapi";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import type { AdminAuthEnv, AdminScope } from "./api-auth.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import {
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+} from "./errors.ts";
+import type { CronRunNowConfig } from "./cron-run-now-config.ts";
+import {
+  CronIdParamSchema,
+  CronRunNowResponseSchema,
+  ErrorSchema,
+} from "./openapi-schemas.ts";
+
+// ─── Store ────────────────────────────────────────────────────────────────────
+
+/** The cron fields the route needs. Never the prompt. */
+export interface RunNowCron {
+  id: string;
+  agentId: string;
+  lockdownDisabledAt: Date | null;
+}
+
+/** One AgentCronRunRequest audit row. No prompt text, by design. */
+export interface RunRequestRow {
+  id: string;
+  cronId: string;
+  agentId: string;
+  requestedBy: string;
+  requestedAt: Date;
+  status: string;
+  honouredRunId: string | null;
+}
+
+export interface CronRunNowStore {
+  findCron(agentId: string, cronId: string): Promise<RunNowCron | null>;
+  /** Stamp the job and write the audit row, atomically. */
+  recordRequest(input: {
+    cronId: string;
+    agentId: string;
+    requestedBy: string;
+    requestedAt: Date;
+  }): Promise<RunRequestRow>;
+}
+
+/** Prisma-backed run-now store. */
+export class CronRunNowService implements CronRunNowStore {
+  constructor(
+    private prisma: Pick<
+      PrismaClient,
+      "agentCronJob" | "agentCronRunRequest" | "$transaction"
+    >,
+  ) {}
+
+  findCron(agentId: string, cronId: string): Promise<RunNowCron | null> {
+    return this.prisma.agentCronJob.findFirst({
+      where: { id: cronId, agentId },
+      select: { id: true, agentId: true, lockdownDisabledAt: true },
+    });
+  }
+
+  recordRequest(input: {
+    cronId: string;
+    agentId: string;
+    requestedBy: string;
+    requestedAt: Date;
+  }): Promise<RunRequestRow> {
+    return this.prisma.$transaction(async (tx) => {
+      await tx.agentCronJob.update({
+        where: { id: input.cronId },
+        data: {
+          runRequestedAt: input.requestedAt,
+          runRequestedBy: input.requestedBy,
+        },
+      });
+      // A newer stamp overwrites the job's, so any request still pending can
+      // never be honoured: mark it expired.
+      await tx.agentCronRunRequest.updateMany({
+        where: { cronId: input.cronId, status: "requested" },
+        data: { status: "expired" },
+      });
+      return tx.agentCronRunRequest.create({
+        data: { ...input, status: "requested" },
+      });
+    });
+  }
+}
+
+// ─── Deps ─────────────────────────────────────────────────────────────────────
+
+export interface CronRunNowDeps {
+  config: CronRunNowConfig;
+  store: CronRunNowStore;
+  /** Injected for deterministic timestamps; defaults to the system clock. */
+  clock?: Clock;
+}
+
+// ─── Route ────────────────────────────────────────────────────────────────────
+
+const jsonError = {
+  content: { "application/json": { schema: ErrorSchema } },
+};
+
+const runNowRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/crons/{cronId}/run-now",
+  summary: "Request an immediate run of a cron job",
+  description:
+    "Asks the agent's runtime to run the cron job once, now, with the job's own stored prompt. Takes no request body (any body is 400). Stamps `runRequestedAt` on the job and writes an AgentCronRunRequest audit row before returning 202; the runtime honours a fresh request (under 15 minutes old) once on its next cron sync. Callers: `*`, `platform.ops`, or the agent's own key. 404 unless SHIPWRIGHT_CRON_RUN_NOW_ENABLED is `enabled`; 409 when the trial-expiry lockdown disabled the cron.",
+  request: { params: CronIdParamSchema },
+  responses: {
+    202: {
+      description: "Run requested",
+      content: { "application/json": { schema: CronRunNowResponseSchema } },
+    },
+    400: { description: "A request body was sent", ...jsonError },
+    403: { description: "Caller not allowed", ...jsonError },
+    404: {
+      description: "Cron not found, or cron run-now disabled",
+      ...jsonError,
+    },
+    409: { description: "Cron disabled by lockdown", ...jsonError },
+  },
+});
+
+/**
+ * Register the run-now route on the admin app. Must run after the /agents/*
+ * auth middleware is mounted.
+ */
+export function registerCronRunNowRoutes(
+  app: OpenAPIHono<AdminAuthEnv>,
+  deps: { cronRunNow?: CronRunNowDeps },
+): void {
+  const { cronRunNow } = deps;
+  const enabled = cronRunNow?.config.enabled === true;
+
+  // Flag gate ahead of everything else, so a disabled route is a plain 404.
+  app.use("/agents/:id/crons/:cronId/run-now", async (c, next) => {
+    if (!enabled) return c.json({ error: "Not found" }, 404);
+    await next();
+  });
+
+  app.openapi(runNowRoute, async (c) => {
+    if (!cronRunNow) throw new NotFoundError();
+    const { id: agentId, cronId } = c.req.valid("param");
+
+    const scope = c.get("scope") as AdminScope | undefined;
+    const allowedCaller =
+      c.get("isAdmin") === true ||
+      scope?.kind === "platform-ops" ||
+      (scope?.kind === "agent" && scope.agentId === agentId);
+    if (!allowedCaller) {
+      throw new ForbiddenError(
+        "Only *, platform.ops or the agent's own key can request a run",
+      );
+    }
+
+    // The prompt is never taken from the request: reject any body.
+    if ((await c.req.text()).length > 0) {
+      throw new BadRequestError("run-now takes no request body");
+    }
+
+    const cron = await cronRunNow.store.findCron(agentId, cronId);
+    if (!cron) throw new NotFoundError(`cron job ${cronId} not found`);
+    if (cron.lockdownDisabledAt) {
+      throw new ConflictError("cron job is disabled by lockdown");
+    }
+
+    const requestedAt = (cronRunNow.clock ?? SystemClock()).now();
+    const requestedBy = callerLabel(c.get("caller"), scope?.kind);
+    await cronRunNow.store.recordRequest({
+      cronId,
+      agentId,
+      requestedBy,
+      requestedAt,
+    });
+    console.log(
+      JSON.stringify({
+        event: "cron-run-now",
+        agentId,
+        cronId,
+        requestedAt: requestedAt.toISOString(),
+        callerLabel: requestedBy,
+      }),
+    );
+    return c.json({ requestedAt: requestedAt.toISOString() }, 202);
+  });
+}

package/src/openapi-schemas.ts

@@ -227,6 +227,11 @@ export const AgentCronJobSchema = z
     name: z.string().nullable().openapi({ example: "morning-brief" }),
     system: z.boolean().openapi({ example: false }),
     parentCronId: z.string().nullable().openapi({ example: null }),
+    runRequestedAt: z.string().datetime().nullable().openapi({
+      example: null,
+      description:
+        "Set by POST .../run-now; the runtime honours it once while fresh (15 minutes) and run creation with commandVariant run-now clears it.",
+    }),
     createdAt: z
       .string()
       .datetime()
@@ -774,6 +779,15 @@ export const AgentAskBodySchema = z
   })
   .openapi("AgentAskBody");
 
+export const CronRunNowResponseSchema = z
+  .object({
+    requestedAt: z
+      .string()
+      .datetime()
+      .openapi({ example: "2026-10-26T12:00:00.000Z" }),
+  })
+  .openapi("CronRunNowResponse");
+
 export const AgentAskResponseSchema = z
   .object({
     askId: z.string().openapi({ example: "clx1111111111" }),

package/src/openapi-schemas.unit.test.ts

@@ -37,6 +37,8 @@ const validCronJob = {
   system: false,
   parentCronId: null,
   lockdownDisabledAt: null,
+  runRequestedAt: null,
+  runRequestedBy: null,
   createdAt: now,
   updatedAt: now,
 };
@@ -102,6 +104,8 @@ describe("AgentCronJobSchema", () => {
       system: false,
       parentCronId: null,
       lockdownDisabledAt: null,
+      runRequestedAt: null,
+      runRequestedBy: null,
       createdAt: now,
       updatedAt: now,
     };