@app-vitals/agent-admin 0.2.1 → 0.4.0

package/src/api.smoke.test.ts

@@ -208,6 +208,8 @@ function makeCron(agentId: string, id: string): AgentCronJob {
     system: false,
     parentCronId: null,
     lockdownDisabledAt: null,
+    runRequestedAt: null,
+    runRequestedBy: null,
     createdAt: makeDate(),
     updatedAt: makeDate(),
   };
@@ -236,6 +238,7 @@ function buildApp(opts?: {
   maxFindings?: number;
   cleanupMergedWorktrees?: boolean;
   cleanupAfterDays?: number;
+  transcriptUploadEnabled?: boolean;
 }) {
   const hasAgent = opts?.hasAgent ?? true;
   const bundle: AgentEnvBundle | null =
@@ -308,6 +311,7 @@ function buildApp(opts?: {
     agentTokenService: { validate: async () => null },
     sessionSecret: SESSION_SECRET,
     anthropicFederationEnabled: opts?.anthropicFederationEnabled,
+    transcriptUploadEnabled: opts?.transcriptUploadEnabled,
   });
 }
 
@@ -326,6 +330,31 @@ describe("GET /:id/config with no phase-methodology service (platform only)", ()
   });
 });
 
+describe("GET /:id/config features (COS-43.1)", () => {
+  const get = (app: ReturnType<typeof buildApp>) =>
+    app.request(`/${KNOWN_AGENT_ID}/config`, {
+      headers: { Authorization: `Bearer ${VALID_ADMIN_KEY}` },
+    });
+
+  test("features default to all off", async () => {
+    const body = await (await get(buildApp())).json();
+    expect(body.features).toEqual({
+      transcriptUpload: false,
+      repoAccessCheck: false,
+    });
+  });
+
+  test("features.transcriptUpload follows the transcript flag", async () => {
+    const body = await (
+      await get(buildApp({ transcriptUploadEnabled: true }))
+    ).json();
+    expect(body.features).toEqual({
+      transcriptUpload: true,
+      repoAccessCheck: false,
+    });
+  });
+});
+
 describe("GET /:id/config (mounted as GET /agents/:id/config from root)", () => {
   test("200 with full bundle when agent exists with env vars, tools, plugins", async () => {
     const app = buildApp();
@@ -787,6 +816,8 @@ function buildCombinedApp() {
         system: false,
         parentCronId: null,
         lockdownDisabledAt: null,
+        runRequestedAt: null,
+        runRequestedBy: null,
         createdAt: new Date(),
         updatedAt: new Date(),
       }),
@@ -804,6 +835,8 @@ function buildCombinedApp() {
         system: false,
         parentCronId: null,
         lockdownDisabledAt: null,
+        runRequestedAt: null,
+        runRequestedBy: null,
         createdAt: new Date(),
         updatedAt: new Date(),
       }),
@@ -822,6 +855,8 @@ function buildCombinedApp() {
         system: false,
         parentCronId: null,
         lockdownDisabledAt: null,
+        runRequestedAt: null,
+        runRequestedBy: null,
         createdAt: new Date(),
         updatedAt: new Date(),
       }),
@@ -839,6 +874,8 @@ function buildCombinedApp() {
         system: false,
         parentCronId: null,
         lockdownDisabledAt: null,
+        runRequestedAt: null,
+        runRequestedBy: null,
         createdAt: new Date(),
         updatedAt: new Date(),
       }),
@@ -861,6 +898,8 @@ function buildCombinedApp() {
         system: false,
         parentCronId: null,
         lockdownDisabledAt: null,
+        runRequestedAt: null,
+        runRequestedBy: null,
         createdAt: new Date(),
         updatedAt: new Date(),
       }),

package/src/api.ts

@@ -93,6 +93,11 @@ export interface AgentConfigResponse {
   maxFindings: number;
   cleanupMergedWorktrees: boolean;
   cleanupAfterDays: number;
+  /**
+   * COS-43.1: feature flags the runtime acts on. Optional so fixtures built
+   * before it keep compiling; the live handler always populates it.
+   */
+  features?: { transcriptUpload: boolean; repoAccessCheck: boolean };
 }
 
 interface AgentEnvServiceLike {
@@ -169,6 +174,11 @@ export interface AgentRuntimeDeps {
   agentTokenService: Pick<AgentTokenService, "validate">;
   /** WIF-2.1: Anthropic federation is enabled; defaults to false. */
   anthropicFederationEnabled?: boolean;
+  /**
+   * COS-43.1: SHIPWRIGHT_TRANSCRIPT_API_ENABLED is on — surfaced to the runtime
+   * as `features.transcriptUpload` in the config bundle. Defaults to false.
+   */
+  transcriptUploadEnabled?: boolean;
 }
 
 // ─── Route definitions ────────────────────────────────────────────────────────
@@ -342,6 +352,11 @@ export function createAgentRuntimeApp(deps: AgentRuntimeDeps): OpenAPIHono {
       maxFindings: agent.maxFindings,
       cleanupMergedWorktrees: agent.cleanupMergedWorktrees,
       cleanupAfterDays: agent.cleanupAfterDays,
+      // COS-43.1: repoAccessCheck is wired by COS-44.1; false until then.
+      features: {
+        transcriptUpload: deps.transcriptUploadEnabled === true,
+        repoAccessCheck: false,
+      },
     };
 
     // The route's Zod schema requires phaseMethodology; a platform-only admin

package/src/chat.smoke.test.ts

@@ -187,6 +187,8 @@ const MOCK_CRON = {
   system: false,
   parentCronId: null,
   lockdownDisabledAt: null,
+  runRequestedAt: null,
+  runRequestedBy: null,
   silent: false,
   preCheck: null,
   createdAt: new Date("2024-01-01"),

package/src/cron-run-now-config.ts

@@ -0,0 +1,20 @@
+/**
+ * admin/src/cron-run-now-config.ts
+ *
+ * Pure parser for the cron run-now flag (COS-42.1). Takes an injected env
+ * object (no process.env reads) so it is deterministically unit-testable;
+ * admin-boot reads it once at startup and injects the resolved config as
+ * deps. Same "enabled" convention as the agent-ask and self-serve flags.
+ */
+
+/** Structural env shape — accepts `process.env` or a plain test object. */
+type CronRunNowEnv = Readonly<Record<string, string | undefined>>;
+
+export interface CronRunNowConfig {
+  /** True only when SHIPWRIGHT_CRON_RUN_NOW_ENABLED === "enabled". */
+  enabled: boolean;
+}
+
+export function parseCronRunNowConfig(env: CronRunNowEnv): CronRunNowConfig {
+  return { enabled: env.SHIPWRIGHT_CRON_RUN_NOW_ENABLED === "enabled" };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * admin/src/cron-run-now-config.unit.test.ts
+ * Pure parser tests for the cron run-now flag (COS-42.1).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { parseCronRunNowConfig } from "./cron-run-now-config.ts";
+
+describe("parseCronRunNowConfig", () => {
+  it('is on only for the literal "enabled"', () => {
+    expect(
+      parseCronRunNowConfig({ SHIPWRIGHT_CRON_RUN_NOW_ENABLED: "enabled" })
+        .enabled,
+    ).toBe(true);
+  });
+
+  it('"true", "" and absent are off', () => {
+    for (const value of ["true", "", "Enabled", " enabled", undefined]) {
+      expect(
+        parseCronRunNowConfig({ SHIPWRIGHT_CRON_RUN_NOW_ENABLED: value })
+          .enabled,
+      ).toBe(false);
+    }
+    expect(parseCronRunNowConfig({}).enabled).toBe(false);
+  });
+});

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);
+  });
+}