@app-vitals/agent-admin 0.0.0-stage → 0.1.0

package/src/agent-cron-jobs.ts

@@ -0,0 +1,615 @@
+/**
+ * agent/src/agent-cron-jobs.ts
+ * AgentCronJobService — CRUD for scheduled prompts per agent.
+ *
+ * Cron expression validation uses an inline 5-field regex check.
+ * Delivery target must be either a Slack channel ID or a Slack user ID (DM)
+ * — not both, and not neither (unless silent=true).
+ */
+
+import type { AgentCronJob, PrismaClient } from "../prisma/client/client.ts";
+import {
+  type SpecialtyManifestResolver,
+  SpecialtyRegistry,
+  missingDefaultSpecialtyError,
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+} from "./specialty-manifest-loader.ts";
+import type { SpecialtyManifest } from "./specialty-registry.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
+
+/**
+ * The shape of a single cron template resolved from a specialty's manifest.
+ * Structurally identical to the former SYSTEM_CRONS SystemCron entries — the
+ * manifest is now the source of truth (see specialty-manifest-loader.ts).
+ */
+type ManifestCron = SpecialtyManifest["crons"][number];
+
+export type { AgentCronJob };
+
+interface CronRunSummary {
+  startedAt: Date;
+  completedAt: Date | null;
+  skipped: boolean;
+  outcome: string | null;
+}
+
+export interface AgentCronJobWithRunSummary extends AgentCronJob {
+  lastRun: CronRunSummary | null;
+  runCountToday: number;
+}
+
+export interface CreateAgentCronJobInput {
+  schedule: string;
+  prompt: string;
+  channel?: string | null;
+  user?: string | null;
+  silent?: boolean;
+  enabled?: boolean;
+  preCheck?: string | null;
+  name?: string | null;
+  system?: boolean;
+}
+
+/**
+ * Validates a cron expression.
+ * Accepts standard 5-field cron: minute hour day-of-month month day-of-week.
+ * Each field may contain digits, *, /, -, and comma (e.g. a minute field of
+ * "0,30" for a twice-hourly, staggered schedule is valid).
+ */
+export function isValidCron(schedule: string): boolean {
+  const fields = schedule.trim().split(/\s+/);
+  if (fields.length !== 5) return false;
+  const fieldPattern = /^(\*|[0-9]+([-,][0-9]+)*)(\/[0-9]+)?$|^\*\/[0-9]+$/;
+  return fields.every((f) => fieldPattern.test(f));
+}
+
+function validateDeliveryTarget(
+  channel: string | null,
+  user: string | null,
+  silent: boolean,
+): void {
+  if (channel && user) {
+    throw new UnprocessableEntityError(
+      "channel and user are mutually exclusive — set one or the other, not both",
+    );
+  }
+  if (!silent && !channel && !user) {
+    throw new UnprocessableEntityError(
+      "at least one of channel or user must be set (unless silent=true)",
+    );
+  }
+}
+
+export class AgentCronJobService {
+  constructor(
+    private prisma: PrismaClient,
+    private clock: Clock = SystemClock(),
+    private specialtyRegistry: SpecialtyManifestResolver = new SpecialtyRegistry(),
+  ) {}
+
+  /**
+   * List all cron jobs for a given agent.
+   */
+  async list(agentId: string): Promise<AgentCronJob[]> {
+    return this.prisma.agentCronJob.findMany({
+      where: { agentId },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  /**
+   * List all cron jobs for a given agent with run summary data.
+   * Each job includes:
+   *   - lastRun: the most recent run record (null if none)
+   *   - runCountToday: count of runs since midnight UTC today
+   */
+  async listWithRunSummary(
+    agentId: string,
+  ): Promise<AgentCronJobWithRunSummary[]> {
+    const jobs = await this.prisma.agentCronJob.findMany({
+      where: { agentId },
+      orderBy: { createdAt: "asc" },
+    });
+
+    // Compute midnight UTC today for the runCountToday boundary
+    const todayMidnightUtc = new Date(this.clock.now());
+    todayMidnightUtc.setUTCHours(0, 0, 0, 0);
+
+    // Fetch run summaries for all cron IDs in one pass
+    const cronIds = jobs.map((j) => j.id);
+    if (cronIds.length === 0) return [];
+
+    // Most recent run per cron job — use DISTINCT ON to get the latest run
+    // per cronId in a single query instead of N parallel findFirst calls.
+    const [lastRunsRaw, todayCounts] = await Promise.all([
+      // Single query: DISTINCT ON ("cronId") ordered by startedAt DESC gives
+      // the most-recent run row per cron, reducing N+1 to one round-trip.
+      this.prisma.$queryRaw<
+        {
+          cronId: string;
+          startedAt: Date;
+          completedAt: Date | null;
+          skipped: boolean;
+          outcome: string | null;
+        }[]
+      >`
+        SELECT DISTINCT ON ("cronId")
+          "cronId",
+          "startedAt",
+          "completedAt",
+          "skipped",
+          "outcome"
+        FROM "AgentCronRun"
+        WHERE "cronId" = ANY(${cronIds}::text[])
+        ORDER BY "cronId", "startedAt" DESC
+      `,
+      // Count today's runs per cronId
+      this.prisma.agentCronRun.groupBy({
+        by: ["cronId"],
+        where: {
+          cronId: { in: cronIds },
+          startedAt: { gte: todayMidnightUtc },
+        },
+        _count: { id: true },
+      }),
+    ]);
+
+    // Build lookup maps
+    // lastRunsRaw is a flat array of one row per cronId (DISTINCT ON result) —
+    // crons with no runs are simply absent, so we default to null via Map.get().
+    const lastRunByCronId = new Map<string, CronRunSummary>();
+    for (const run of lastRunsRaw) {
+      lastRunByCronId.set(run.cronId, {
+        startedAt: run.startedAt,
+        completedAt: run.completedAt,
+        skipped: run.skipped,
+        outcome: run.outcome,
+      });
+    }
+
+    const todayCountByCronId = new Map<string, number>();
+    for (const row of todayCounts) {
+      todayCountByCronId.set(row.cronId, row._count.id);
+    }
+
+    return jobs.map((job) => ({
+      ...job,
+      lastRun: lastRunByCronId.get(job.id) ?? null,
+      runCountToday: todayCountByCronId.get(job.id) ?? 0,
+    }));
+  }
+
+  async get(agentId: string, cronId: string): Promise<AgentCronJob> {
+    const job = await this.prisma.agentCronJob.findUnique({
+      where: { id: cronId },
+    });
+    if (!job || job.agentId !== agentId) {
+      throw new NotFoundError(`cron job ${cronId} not found`);
+    }
+    return job;
+  }
+
+  /**
+   * List all enabled cron jobs across all agents.
+   * Used by the runtime sync loop on startup and every 60s.
+   */
+  async listEnabled(): Promise<AgentCronJob[]> {
+    return this.prisma.agentCronJob.findMany({
+      where: { enabled: true },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  /**
+   * List all enabled cron jobs belonging to an agent whose trial has expired
+   * (`trialExpiresAt` strictly before `now`) — the working set for the
+   * trial-expiry lockdown sweep (ATE-3.1, admin/src/trial-expiry-sweeper.ts).
+   * A single join query rather than an N+1 per-cron agent lookup: filtering
+   * on the related `agent.trialExpiresAt` happens in the same round-trip.
+   * An agent with `trialExpiresAt` null never matches (Prisma's `lt` filter
+   * excludes null), and `now` itself is exclusive (`lt`, not `lte`) so a
+   * trial expiring at exactly `now` is not yet treated as expired.
+   */
+  async listEnabledWithExpiredTrial(now: Date): Promise<AgentCronJob[]> {
+    return this.prisma.agentCronJob.findMany({
+      where: { enabled: true, agent: { trialExpiresAt: { lt: now } } },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  /**
+   * List all enabled cron jobs belonging to an agent whose account is locked
+   * (status 'suspended' or 'trial_expired') — the working set for the
+   * account-level lockdown (SSP-8.2, admin/src/account-lifecycle.ts).
+   * Optionally narrowed to one account. Agents with accountId null never
+   * match.
+   */
+  async listEnabledInLockedAccounts(
+    accountId?: string,
+  ): Promise<AgentCronJob[]> {
+    return this.prisma.agentCronJob.findMany({
+      where: {
+        enabled: true,
+        agent: {
+          account: {
+            status: { in: ["suspended", "trial_expired"] },
+            ...(accountId !== undefined ? { id: accountId } : {}),
+          },
+        },
+      },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  /**
+   * Create a new cron job for the given agent.
+   * Validates:
+   *   - schedule is a valid 5-field cron expression
+   *   - channel and user are mutually exclusive (422 if both set)
+   *   - at least one of channel or user is set (unless silent=true)
+   * Throws UnprocessableEntityError for invalid inputs.
+   */
+  async create(
+    agentId: string,
+    input: CreateAgentCronJobInput,
+  ): Promise<AgentCronJob> {
+    if (!isValidCron(input.schedule)) {
+      throw new UnprocessableEntityError(
+        `invalid cron expression: "${input.schedule}"`,
+      );
+    }
+
+    const channel = input.channel ?? null;
+    const user = input.user ?? null;
+    const silent = input.silent ?? false;
+
+    validateDeliveryTarget(channel, user, silent);
+
+    return this.prisma.agentCronJob.create({
+      data: {
+        agentId,
+        schedule: input.schedule,
+        prompt: input.prompt,
+        channel,
+        user,
+        silent,
+        enabled: input.enabled ?? true,
+        preCheck: input.preCheck ?? null,
+        name: input.name ?? null,
+        system: input.system ?? false,
+      },
+    });
+  }
+
+  /**
+   * Delete a cron job. Verifies agentId ownership before deleting.
+   * Throws NotFoundError if the cronId doesn't exist or belongs to a different agent.
+   */
+  async delete(agentId: string, cronId: string): Promise<void> {
+    const existing = await this.prisma.agentCronJob.findUnique({
+      where: { id: cronId },
+    });
+
+    if (!existing || existing.agentId !== agentId) {
+      throw new NotFoundError(`cron job ${cronId} not found`);
+    }
+
+    await this.prisma.agentCronJob.delete({ where: { id: cronId } });
+  }
+
+  /**
+   * Update a cron job's schedule, prompt, channel, user, silent, preCheck, and enabled.
+   * Applies the same validation as create():
+   *   - schedule must be a valid cron expression
+   *   - channel and user are mutually exclusive (422 if both set)
+   *   - at least one of channel or user must be set (unless silent=true)
+   * Throws NotFoundError if the cronId doesn't exist or belongs to a different agent.
+   * Throws UnprocessableEntityError for invalid inputs.
+   */
+  async update(
+    agentId: string,
+    cronId: string,
+    input: {
+      schedule: string;
+      prompt: string;
+      channel?: string | null;
+      user?: string | null;
+      silent?: boolean;
+      preCheck?: string | null;
+      enabled?: boolean;
+    },
+  ): Promise<AgentCronJob> {
+    await this.get(agentId, cronId);
+
+    if (!isValidCron(input.schedule)) {
+      throw new UnprocessableEntityError(
+        `invalid cron expression: "${input.schedule}"`,
+      );
+    }
+
+    const channel = input.channel ?? null;
+    const user = input.user ?? null;
+    const silent = input.silent ?? false;
+
+    validateDeliveryTarget(channel, user, silent);
+
+    return this.prisma.agentCronJob.update({
+      where: { id: cronId },
+      data: {
+        schedule: input.schedule,
+        prompt: input.prompt,
+        channel,
+        user,
+        silent,
+        ...(input.preCheck !== undefined && { preCheck: input.preCheck }),
+        // Any explicit enabled change is a user decision — clear the lockdown
+        // marker so restoreLockdownDisabled() never overrides it.
+        ...(input.enabled !== undefined && {
+          enabled: input.enabled,
+          lockdownDisabledAt: null,
+        }),
+      },
+    });
+  }
+
+  /**
+   * Update only the preCheck field of a cron job.
+   * Pass null to clear the preCheck script.
+   * Throws NotFoundError if the cronId doesn't exist or belongs to a different agent.
+   */
+  async updatePreCheck(
+    agentId: string,
+    cronId: string,
+    preCheck: string | null,
+  ): Promise<AgentCronJob> {
+    await this.get(agentId, cronId);
+    return this.prisma.agentCronJob.update({
+      where: { id: cronId },
+      data: { preCheck },
+    });
+  }
+
+  /**
+   * Update only the delivery-target fields of a cron job (channel, user, silent).
+   * Does not touch schedule or prompt.
+   * Throws NotFoundError if the cronId doesn't exist or belongs to a different agent.
+   */
+  async updateDelivery(
+    agentId: string,
+    cronId: string,
+    input: {
+      channel?: string | null;
+      user?: string | null;
+      silent?: boolean;
+    },
+  ): Promise<AgentCronJob> {
+    await this.get(agentId, cronId);
+
+    return this.prisma.agentCronJob.update({
+      where: { id: cronId },
+      data: {
+        ...(input.channel !== undefined && { channel: input.channel }),
+        ...(input.user !== undefined && { user: input.user }),
+        ...(input.silent !== undefined && { silent: input.silent }),
+      },
+    });
+  }
+
+  /**
+   * Enable or disable a cron job.
+   * Throws NotFoundError if the cronId doesn't exist or belongs to a different agent.
+   *
+   * `lockdownDisabledAt` tracks who disabled the cron: passing
+   * `{ lockdown: true }` with `enabled: false` stamps it (trial-expiry
+   * lockdown); every other call clears it, so a manual disable or re-enable
+   * never leaves a stale marker for restoreLockdownDisabled() to act on.
+   */
+  async setEnabled(
+    agentId: string,
+    cronId: string,
+    enabled: boolean,
+    opts?: { lockdown?: boolean },
+  ): Promise<AgentCronJob> {
+    await this.get(agentId, cronId);
+
+    return this.prisma.agentCronJob.update({
+      where: { id: cronId },
+      data: {
+        enabled,
+        lockdownDisabledAt: !enabled && opts?.lockdown ? new Date() : null,
+      },
+    });
+  }
+
+  /**
+   * Re-enable exactly the crons the lockdown disabled for the given agents
+   * (lockdownDisabledAt set) and clear the marker. Crons the user disabled
+   * manually carry no marker and are left alone. Returns the number restored.
+   */
+  async restoreLockdownDisabled(agentIds: string[]): Promise<number> {
+    if (agentIds.length === 0) return 0;
+    const { count } = await this.prisma.agentCronJob.updateMany({
+      where: { agentId: { in: agentIds }, lockdownDisabledAt: { not: null } },
+      data: { enabled: true, lockdownDisabledAt: null },
+    });
+    return count;
+  }
+
+  /**
+   * Reconcile system crons for the given agent.
+   *
+   * The cron list is resolved from the agent's type manifest — the agent's
+   * stored `typeName` is looked up via the injected SpecialtyRegistry's
+   * `tryGetManifest()` (the parsed `specialties/{typeName}/manifest.yaml`),
+   * deliberately WITHOUT the "coding" fallback: a non-default type with no
+   * loadable manifest logs an error and reconciles nothing (no seeding of
+   * coding crons, no deletion of existing system crons), while a "coding"
+   * manifest that cannot load throws — the universal fallback failing is a
+   * startup bug. This replaced the former hardcoded
+   * SYSTEM_CRONS array as the source of truth (ATS-3.2).
+   *
+   * Two passes so parent/child links resolve regardless of the manifest's
+   * cron order or whether this is the agent's very first reconcile (i.e.
+   * the parent row may not exist yet when a child entry is processed):
+   *
+   * Pass 1 — for each manifest cron entry:
+   *   - If an existing system cron with matching name exists: update it in
+   *     place with the current manifest definition, preserving its id and
+   *     existing enabled state. Updating in place (rather than delete+create)
+   *     keeps the row's id stable across restarts so AgentCronRun history
+   *     (FK onDelete: Cascade) is never wiped out from under it.
+   *   - If no matching cron exists: create it with the manifest's default
+   *     enabled state.
+   *   Records each entry's resulting row id in a name → id map as it goes.
+   *
+   * Pass 2 — for each entry that declares `parentCron`, resolves the
+   * parent's row id from the name → id map built in pass 1 and sets
+   * parentCronId on the child. If an entry does not declare `parentCron`
+   * (or declares one that doesn't resolve to a known row), any existing
+   * non-null parentCronId on that row is cleared back to null. Self-heals
+   * the link on every reconcile call in both directions — null→set (e.g.
+   * a pre-existing row from before parentCron was introduced) and set→null
+   * (e.g. a parentCron declaration removed from the manifest).
+   *
+   * Orphan pass: delete any cron with system=true whose name is no longer in
+   * the resolved manifest cron list.
+   *
+   * All three passes run inside a single transaction for atomicity.
+   *
+   * Returns a summary { created, updated, deleted }.
+   */
+  async reconcileSystemCrons(
+    agentId: string,
+  ): Promise<{ created: number; updated: number; deleted: number }> {
+    // Resolve the agent's type manifest → its declared cron list. No "coding"
+    // fallback: seeding enabled coding crons on a non-coding agent is worse
+    // than leaving its crons untouched.
+    const agent = await this.prisma.agent.findUnique({
+      where: { id: agentId },
+      select: { typeName: true },
+    });
+    if (!agent) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+    const manifest = this.specialtyRegistry.tryGetManifest(agent.typeName);
+    if (!manifest) {
+      const defaultName = resolveDefaultSpecialtyName();
+      if (agent.typeName === defaultName) {
+        throw missingDefaultSpecialtyError(
+          defaultName,
+          resolveSpecialtiesDir(),
+          new Error(`reconcileSystemCrons for agent ${agentId}`),
+        );
+      }
+      console.error(
+        `reconcileSystemCrons: no loadable manifest for typeName "${agent.typeName}" (agent ${agentId}) — leaving crons untouched`,
+      );
+      return { created: 0, updated: 0, deleted: 0 };
+    }
+    const manifestCrons: readonly ManifestCron[] = manifest.crons;
+
+    // Fetch all existing system crons for this agent
+    const existingSystemCrons = await this.prisma.agentCronJob.findMany({
+      where: { agentId, system: true },
+    });
+
+    // Build a map of name → existing cron
+    const existingByName = new Map<string, AgentCronJob>();
+    for (const cron of existingSystemCrons) {
+      if (cron.name) {
+        existingByName.set(cron.name, cron);
+      }
+    }
+
+    // Build set of valid manifest cron names for orphan detection
+    const systemCronNames = new Set(manifestCrons.map((c) => c.name));
+
+    let created = 0;
+    let updated = 0;
+    let deleted = 0;
+
+    // Wrap all mutations in a transaction so a crash mid-loop cannot leave
+    // the agent missing required system crons (e.g. shipwright-dev-task).
+    await this.prisma.$transaction(async (tx) => {
+      // Pass 1: reconcile each manifest cron entry, recording name → row id.
+      const idByName = new Map<string, string>();
+      for (const systemCron of manifestCrons) {
+        const existing = existingByName.get(systemCron.name);
+
+        if (existing) {
+          // Update in place — preserves id (and thus AgentCronRun history,
+          // which cascade-deletes when its AgentCronJob is deleted) and the
+          // existing enabled state.
+          await tx.agentCronJob.update({
+            where: { id: existing.id },
+            data: {
+              schedule: systemCron.schedule,
+              prompt: systemCron.prompt,
+              silent: systemCron.silent ?? false,
+              preCheck: systemCron.preCheck ?? null,
+            },
+          });
+          idByName.set(systemCron.name, existing.id);
+          updated++;
+        } else {
+          const createdCron = await tx.agentCronJob.create({
+            data: {
+              agentId,
+              name: systemCron.name,
+              system: true,
+              schedule: systemCron.schedule,
+              prompt: systemCron.prompt,
+              silent: systemCron.silent ?? false,
+              preCheck: systemCron.preCheck ?? null,
+              channel: null,
+              user: null,
+              enabled: systemCron.enabled,
+            },
+          });
+          idByName.set(systemCron.name, createdCron.id);
+          created++;
+        }
+      }
+
+      // Pass 2: link declared parent/child crons now that every row in this
+      // reconcile has a known id, regardless of array order or first-boot.
+      // Also clears parentCronId back to null when an entry no longer
+      // declares a resolvable parentCron, so the link self-heals in both
+      // directions rather than only null→set.
+      for (const systemCron of manifestCrons) {
+        const childId = idByName.get(systemCron.name);
+        if (!childId) continue;
+        const parentId = systemCron.parentCron
+          ? idByName.get(systemCron.parentCron)
+          : undefined;
+
+        if (parentId) {
+          await tx.agentCronJob.update({
+            where: { id: childId },
+            data: { parentCronId: parentId },
+          });
+        } else {
+          const existing = existingByName.get(systemCron.name);
+          if (existing && existing.parentCronId !== null) {
+            await tx.agentCronJob.update({
+              where: { id: childId },
+              data: { parentCronId: null },
+            });
+          }
+        }
+      }
+
+      // Orphan pass: delete any system cron whose name is not in the manifest.
+      for (const cron of existingSystemCrons) {
+        if (!cron.name || !systemCronNames.has(cron.name)) {
+          await tx.agentCronJob.delete({ where: { id: cron.id } });
+          deleted++;
+        }
+      }
+    });
+
+    return { created, updated, deleted };
+  }
+}