@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/agent-cron-runs.ts

@@ -0,0 +1,489 @@
+/**
+ * admin/src/agent-cron-runs.ts
+ * AgentCronRunService — create and list AgentCronRun records.
+ *
+ * Each run records one cron invocation: whether it was skipped (pre-check
+ * returned false), the outcome, and any error.
+ */
+
+import type {
+  AgentCronRun,
+  Prisma,
+  PrismaClient,
+} from "../prisma/client/client.ts";
+import { NotFoundError } from "./errors.ts";
+
+export type { AgentCronRun };
+
+/** An AgentCronRun with its per-model token/cost breakdown rows attached. */
+type AgentCronRunWithModelBreakdown = Prisma.AgentCronRunGetPayload<{
+  include: { modelBreakdown: true };
+}>;
+
+/**
+ * An AgentCronRun with its per-model token/cost breakdown rows and its
+ * owning cron's id/name/schedule attached — used by cross-cron listings
+ * (e.g. listForAgent) so callers don't need N+1 cron lookups.
+ */
+type AgentCronRunWithCron = Prisma.AgentCronRunGetPayload<{
+  include: {
+    modelBreakdown: true;
+    cron: { select: { id: true; name: true; schedule: true } };
+    phaseCron: { select: { id: true; name: true } };
+  };
+}>;
+
+interface CreateAgentCronRunInput {
+  startedAt: Date;
+  completedAt?: Date | null;
+  skipped?: boolean;
+  skipReason?: string | null;
+  outcome?: string | null;
+  error?: string | null;
+  /** Child AgentCronJob id (FK) of the pipeline phase this run served (dev-task/review/patch/deploy). Null for legacy five-job crons or runs with no phase attribution. */
+  phaseId?: string | null;
+  /** Work item type this run was dispatched against ("task" | "pr"). Null when the tick had no dispatch. */
+  itemType?: string | null;
+  /** Work item id this run was dispatched against (e.g. "WLS-2.2" or "acme/x#123"). Null when the tick had no dispatch. */
+  itemId?: string | null;
+  /** Slash-command variant this dispatch ran ("default" | "alternate"). Null when the run had no variant attribution. */
+  commandVariant?: string | null;
+}
+
+export interface ModelBreakdownEntry {
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  costUsd: number;
+}
+
+/**
+ * First-turn context baseline reported by the agent: the usage of the run's
+ * first assistant message, whose input + cacheCreation + cacheRead is the
+ * full always-loaded context independent of cache warmth
+ * (computed agent-side from the Claude CLI stream).
+ */
+interface ContextBaselineEntry {
+  model: string;
+  contextTokens: number;
+  inputTokens: number;
+  cacheCreationTokens: number;
+  cacheReadTokens: number;
+}
+
+/** Per-skill / per-subagent token attribution row reported by the agent. */
+interface SkillUsageEntry {
+  kind: string;
+  name: string;
+  invocations: number;
+  turns: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  invokeContextDelta?: number | null;
+}
+
+export interface PatchAgentCronRunInput {
+  completedAt?: Date | null;
+  outcome?: string | null;
+  error?: string | null;
+  skipped?: boolean;
+  skipReason?: string | null;
+  inputTokens?: number | null;
+  outputTokens?: number | null;
+  cacheReadTokens?: number | null;
+  cacheCreationTokens?: number | null;
+  /** Agent session id this run was executed under. Null clears it. */
+  sessionId?: string | null;
+  /**
+   * Most recent debounced progress-push (recordProgress()) timestamp,
+   * sourced from the agent's injected Clock. Null clears it. Overwritten on
+   * every progress push — always the latest, not a history.
+   */
+  lastHeartbeatAt?: Date | null;
+  modelBreakdown?: ModelBreakdownEntry[];
+  /** Spread onto the baseline* columns. */
+  contextBaseline?: ContextBaselineEntry;
+  turns?: number | null;
+  toolCalls?: number | null;
+  contextFingerprint?: string | null;
+  pluginVersion?: string | null;
+  claudeCodeVersion?: string | null;
+  /** Upserted per [cronRunId, kind, name], like modelBreakdown per model. */
+  skillUsage?: SkillUsageEntry[];
+}
+
+interface ListAgentCronRunsOptions {
+  limit?: number;
+  offset?: number;
+  /** Narrow to runs dispatched against this work item (e.g. "WLS-2.2" or "acme/x#123"). */
+  itemId?: string;
+  /** Narrow to runs dispatched by this phase cron (a child AgentCronJob id). */
+  phaseId?: string;
+}
+
+interface AgentCronRunList {
+  items: AgentCronRunWithModelBreakdown[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+interface ListForAgentOptions {
+  /** Narrow to a single cron. Still scoped to agentId — a cronId belonging
+   * to a different agent yields an empty result, not an error. */
+  cronId?: string;
+  /**
+   * "skipped" filters WHERE skipped = true regardless of the outcome column
+   * (mirrors the cronRunOutcomeLabel display convention: skipped is a
+   * boolean flag, not an outcome column value). Any other value filters
+   * WHERE skipped = false AND outcome = value. Omitted means no filter.
+   */
+  outcome?: string;
+  limit?: number;
+  offset?: number;
+}
+
+interface AgentCronRunListForAgent {
+  items: AgentCronRunWithCron[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/**
+ * Filter options for `listAcrossAgents()`. Mirrors `ListForAgentOptions` —
+ * the agent scoping itself comes from the `agentIds` array argument, not
+ * from an option here.
+ */
+interface ListAcrossAgentsOptions {
+  /** Narrow to a single cron, still scoped to the given agentIds. */
+  cronId?: string;
+  /**
+   * "skipped" filters WHERE skipped = true regardless of the outcome column
+   * (same semantics as ListForAgentOptions.outcome). Any other value filters
+   * WHERE skipped = false AND outcome = value. Omitted means no filter.
+   */
+  outcome?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export class AgentCronRunService {
+  constructor(private prisma: PrismaClient) {}
+
+  /**
+   * Create a new run record for a cron job.
+   * Validates that the cronId exists and belongs to agentId.
+   * Throws NotFoundError if the cronId doesn't exist or is not owned by agentId.
+   */
+  async create(
+    cronId: string,
+    agentId: string,
+    input: CreateAgentCronRunInput,
+  ): Promise<AgentCronRun> {
+    // Validate ownership
+    const job = await this.prisma.agentCronJob.findUnique({
+      where: { id: cronId },
+    });
+    if (!job || job.agentId !== agentId) {
+      throw new NotFoundError(`cron job ${cronId} not found`);
+    }
+
+    return this.prisma.agentCronRun.create({
+      data: {
+        cronId,
+        agentId,
+        startedAt: input.startedAt,
+        completedAt: input.completedAt ?? null,
+        skipped: input.skipped ?? false,
+        skipReason: input.skipReason ?? null,
+        outcome: input.outcome ?? null,
+        error: input.error ?? null,
+        phaseId: input.phaseId ?? null,
+        itemType: input.itemType ?? null,
+        itemId: input.itemId ?? null,
+        commandVariant: input.commandVariant ?? null,
+      },
+    });
+  }
+
+  /**
+   * Update an existing run record with completion data and/or token fields.
+   * Validates that the runId exists, belongs to agentId, and belongs to cronId.
+   * Throws NotFoundError if the run doesn't exist, is not owned by agentId, or
+   * does not belong to the given cronId (prevents cross-cron access).
+   */
+  async patch(
+    runId: string,
+    agentId: string,
+    cronId: string,
+    input: PatchAgentCronRunInput,
+  ): Promise<AgentCronRunWithModelBreakdown> {
+    const run = await this.prisma.agentCronRun.findUnique({
+      where: { id: runId },
+    });
+    if (!run || run.agentId !== agentId) {
+      throw new NotFoundError(`cron run ${runId} not found`);
+    }
+    if (run.cronId !== cronId) {
+      throw new NotFoundError(`cron run ${runId} not found`);
+    }
+
+    // The top-level token fields (inputTokens/outputTokens/…) are still accepted
+    // on the input for backward compatibility with older agent builds, but they
+    // are no longer persisted: those columns were dropped and all token
+    // accounting now flows through AgentCronRunModelBreakdown (see modelBreakdown
+    // below). We simply ignore them here.
+    // TODO(CTT-cleanup): remove top-level token field acceptance once all agent
+    // builds send modelBreakdown only (see agent/src/runtime/cron-handler.ts's
+    // buildTokenPayload()).
+    const runData = {
+      ...(input.completedAt !== undefined && {
+        completedAt: input.completedAt,
+      }),
+      ...(input.outcome !== undefined && { outcome: input.outcome }),
+      ...(input.error !== undefined && { error: input.error }),
+      ...(input.skipped !== undefined && { skipped: input.skipped }),
+      ...(input.skipReason !== undefined && { skipReason: input.skipReason }),
+      ...(input.sessionId !== undefined && { sessionId: input.sessionId }),
+      ...(input.lastHeartbeatAt !== undefined && {
+        lastHeartbeatAt: input.lastHeartbeatAt,
+      }),
+      ...(input.contextBaseline !== undefined && {
+        baselineModel: input.contextBaseline.model,
+        baselineContextTokens: input.contextBaseline.contextTokens,
+        baselineInputTokens: input.contextBaseline.inputTokens,
+        baselineCacheCreationTokens: input.contextBaseline.cacheCreationTokens,
+        baselineCacheReadTokens: input.contextBaseline.cacheReadTokens,
+      }),
+      ...(input.turns !== undefined && { turns: input.turns }),
+      ...(input.toolCalls !== undefined && { toolCalls: input.toolCalls }),
+      ...(input.contextFingerprint !== undefined && {
+        contextFingerprint: input.contextFingerprint,
+      }),
+      ...(input.pluginVersion !== undefined && {
+        pluginVersion: input.pluginVersion,
+      }),
+      ...(input.claudeCodeVersion !== undefined && {
+        claudeCodeVersion: input.claudeCodeVersion,
+      }),
+    };
+
+    const breakdownUpserts = (input.modelBreakdown ?? []).map((entry) =>
+      this.prisma.agentCronRunModelBreakdown.upsert({
+        where: {
+          cronRunId_model: { cronRunId: runId, model: entry.model },
+        },
+        create: {
+          cronRunId: runId,
+          model: entry.model,
+          inputTokens: entry.inputTokens,
+          outputTokens: entry.outputTokens,
+          cacheReadTokens: entry.cacheReadTokens,
+          cacheCreationTokens: entry.cacheCreationTokens,
+          costUsd: entry.costUsd,
+        },
+        update: {
+          inputTokens: entry.inputTokens,
+          outputTokens: entry.outputTokens,
+          cacheReadTokens: entry.cacheReadTokens,
+          cacheCreationTokens: entry.cacheCreationTokens,
+          costUsd: entry.costUsd,
+        },
+      }),
+    );
+    // Per-skill attribution rows follow the same upsert-per-key pattern as
+    // the model breakdown (unique on [cronRunId, kind, name]).
+    const skillUsageUpserts = (input.skillUsage ?? []).map((entry) => {
+      const fields = {
+        invocations: entry.invocations,
+        turns: entry.turns,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        cacheReadTokens: entry.cacheReadTokens,
+        cacheCreationTokens: entry.cacheCreationTokens,
+        invokeContextDelta: entry.invokeContextDelta ?? null,
+      };
+      return this.prisma.agentCronRunSkillUsage.upsert({
+        where: {
+          cronRunId_kind_name: {
+            cronRunId: runId,
+            kind: entry.kind,
+            name: entry.name,
+          },
+        },
+        create: {
+          cronRunId: runId,
+          kind: entry.kind,
+          name: entry.name,
+          ...fields,
+        },
+        update: fields,
+      });
+    });
+
+    if (breakdownUpserts.length > 0 || skillUsageUpserts.length > 0) {
+      // Wrap the run update and all child upserts in a single transaction
+      // so the writes are atomic — partial breakdown/attribution rows are
+      // never visible. The run update (with its modelBreakdown include) must
+      // be the LAST statement in the array: Prisma's array-form $transaction
+      // issues statements in order, so an earlier include would return
+      // breakdown rows as they stood before this call's upserts ran.
+      const results = await this.prisma.$transaction([
+        ...breakdownUpserts,
+        ...skillUsageUpserts,
+        this.prisma.agentCronRun.update({
+          where: { id: runId },
+          data: runData,
+          include: { modelBreakdown: true },
+        }),
+      ]);
+      const updatedRun = results[
+        results.length - 1
+      ] as AgentCronRunWithModelBreakdown;
+      return updatedRun;
+    }
+
+    return this.prisma.agentCronRun.update({
+      where: { id: runId },
+      data: runData,
+      include: { modelBreakdown: true },
+    });
+  }
+
+  /**
+   * List all runs for a cron job, sorted descending by startedAt.
+   * Validates that the cronId exists and belongs to agentId.
+   * Throws NotFoundError if the cronId doesn't exist or is not owned by agentId.
+   * Defaults to limit=20, offset=0.
+   */
+  async list(
+    cronId: string,
+    agentId: string,
+    opts?: ListAgentCronRunsOptions,
+  ): Promise<AgentCronRunList> {
+    const limit = opts?.limit ?? 20;
+    const offset = opts?.offset ?? 0;
+
+    // Validate ownership
+    const job = await this.prisma.agentCronJob.findUnique({
+      where: { id: cronId },
+    });
+    if (!job || job.agentId !== agentId) {
+      throw new NotFoundError(`cron job ${cronId} not found`);
+    }
+
+    const where: Prisma.AgentCronRunWhereInput = { cronId, agentId };
+    if (opts?.itemId) {
+      where.itemId = opts.itemId;
+    }
+    if (opts?.phaseId) {
+      where.phaseId = opts.phaseId;
+    }
+
+    const [items, total] = await this.prisma.$transaction([
+      this.prisma.agentCronRun.findMany({
+        where,
+        orderBy: { startedAt: "desc" },
+        take: limit,
+        skip: offset,
+        include: { modelBreakdown: true },
+      }),
+      this.prisma.agentCronRun.count({ where }),
+    ]);
+
+    return { items, total, limit, offset };
+  }
+
+  /**
+   * List all runs for an agent across every cron it owns, sorted descending
+   * by startedAt. Unlike `.list()`, this method is agent-scoped by
+   * construction and does not validate a specific cronId's ownership — if
+   * opts.cronId is given but belongs to a different agent, the WHERE clause
+   * (agentId AND cronId) simply matches no rows.
+   * Defaults to limit=20, offset=0.
+   */
+  async listForAgent(
+    agentId: string,
+    opts?: ListForAgentOptions,
+  ): Promise<AgentCronRunListForAgent> {
+    const limit = opts?.limit ?? 20;
+    const offset = opts?.offset ?? 0;
+
+    const where: Prisma.AgentCronRunWhereInput = { agentId };
+    if (opts?.cronId) {
+      where.cronId = opts.cronId;
+    }
+    if (opts?.outcome === "skipped") {
+      where.skipped = true;
+    } else if (opts?.outcome !== undefined) {
+      where.skipped = false;
+      where.outcome = opts.outcome;
+    }
+
+    const [items, total] = await this.prisma.$transaction([
+      this.prisma.agentCronRun.findMany({
+        where,
+        orderBy: { startedAt: "desc" },
+        take: limit,
+        skip: offset,
+        include: {
+          modelBreakdown: true,
+          cron: { select: { id: true, name: true, schedule: true } },
+          phaseCron: { select: { id: true, name: true } },
+        },
+      }),
+      this.prisma.agentCronRun.count({ where }),
+    ]);
+
+    return { items, total, limit, offset };
+  }
+
+  /**
+   * List runs across a set of agents, sorted descending by startedAt.
+   * Unlike `.listForAgent()`, this is scoped to a list of agent ids rather
+   * than a single one — used by fleet-wide views (e.g. an org dashboard)
+   * that need a globally-ordered feed across many agents' cron history.
+   * An empty agentIds array yields an empty result, not an error.
+   * Defaults to limit=20, offset=0.
+   */
+  async listAcrossAgents(
+    agentIds: string[],
+    opts?: ListAcrossAgentsOptions,
+  ): Promise<AgentCronRunListForAgent> {
+    const limit = opts?.limit ?? 20;
+    const offset = opts?.offset ?? 0;
+
+    const where: Prisma.AgentCronRunWhereInput = { agentId: { in: agentIds } };
+    if (opts?.cronId) {
+      where.cronId = opts.cronId;
+    }
+    if (opts?.outcome === "skipped") {
+      where.skipped = true;
+    } else if (opts?.outcome !== undefined) {
+      where.skipped = false;
+      where.outcome = opts.outcome;
+    }
+
+    const [items, total] = await this.prisma.$transaction([
+      this.prisma.agentCronRun.findMany({
+        where,
+        orderBy: { startedAt: "desc" },
+        take: limit,
+        skip: offset,
+        include: {
+          modelBreakdown: true,
+          cron: { select: { id: true, name: true, schedule: true } },
+          phaseCron: { select: { id: true, name: true } },
+        },
+      }),
+      this.prisma.agentCronRun.count({ where }),
+    ]);
+
+    return { items, total, limit, offset };
+  }
+}

package/src/agent-deletion-checklist.ts

@@ -0,0 +1,128 @@
+/**
+ * admin/src/agent-deletion-checklist.ts
+ *
+ * Pure builder for the operator-facing "manual steps" checklist surfaced when
+ * an agent is deleted. Several agent secrets (GH_TOKEN, LINEAR_API_KEY,
+ * STRIPE_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ...) are
+ * hand-pasted into AgentEnv with no stored ID/owner metadata, so no automated
+ * revocation is possible on agent delete. Rather than silently dropping them,
+ * this module turns the agent's `AgentEnv` rows into a reminder checklist for
+ * the operator to work through by hand.
+ *
+ * Uses the existing `AgentEnv.secret` boolean (checked by default in the "add
+ * env var" admin UI form) — no schema changes needed.
+ *
+ * This function is PURE — no fs, no network, no Prisma, no clock. It only
+ * shapes plain objects from plain objects, so it's unit-tested in isolation
+ * without a DB. See ./agent-manifest.ts for the same "pure builder" pattern.
+ */
+
+/** A single operator-facing reminder produced for one AgentEnv row. */
+export interface ManualStep {
+  /** The AgentEnv key this reminder is about (e.g. "GH_TOKEN"). */
+  key: string;
+  /** Human-readable instructions for the operator. */
+  message: string;
+}
+
+/**
+ * Per-agent Anthropic identity pieces still present after a failed removal.
+ * A null/absent piece is already gone and gets no entry.
+ */
+export interface LeftoverIdentity {
+  anthropicFederationRuleId?: string | null;
+  anthropicServiceAccountId?: string | null;
+  k8sServiceAccountName?: string | null;
+}
+
+/**
+ * Keys handled by the Slack app deletion step (ADC-2.1 / ADC-3.1) — excluded
+ * entirely from this checklist so operators aren't told to do the same
+ * cleanup twice.
+ */
+const SLACK_APP_MANAGED_KEYS = new Set([
+  "SLACK_APP_ID",
+  "SLACK_SIGNING_SECRET",
+  "SLACK_BOT_TOKEN",
+]);
+
+/**
+ * Named/standard keys with specific revocation instructions. Exact-match on
+ * key name — a differently-cased key (e.g. "gh_token") falls through to the
+ * generic custom-secret message rather than being matched here, since
+ * AgentEnv keys are conventionally upper-snake-case and we'd rather surface
+ * an unexpected casing than silently apply the wrong instructions.
+ */
+const NAMED_KEY_INSTRUCTIONS: Record<string, string> = {
+  GH_TOKEN:
+    "Revoke this GitHub personal access token at https://github.com/settings/tokens (or the fine-grained PAT settings page).",
+  ANTHROPIC_API_KEY: "Revoke/rotate this key in the Anthropic console.",
+  CLAUDE_CODE_OAUTH_TOKEN:
+    "Revoke this token via `claude auth logout` or the Anthropic console.",
+};
+
+/**
+ * Build the manual-steps checklist for the given `AgentEnv` rows.
+ *
+ * Bucketing:
+ * - Named/standard keys (GH_TOKEN, ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN)
+ *   get a specific instruction.
+ * - Slack-app-managed keys (SLACK_APP_ID, SLACK_SIGNING_SECRET,
+ *   SLACK_BOT_TOKEN) are excluded — handled by the Slack app deletion step.
+ * - Any other row with `secret: true` gets a generic "verify manually"
+ *   reminder, naming the key.
+ * - Rows with `secret: false` never produce an entry, regardless of key name.
+ *
+ * Order-preserving and non-deduplicating: one `ManualStep` per matching input
+ * row, in input order (duplicate keys produce duplicate entries).
+ *
+ * `leftoverIdentity` (optional) appends one entry per per-agent Anthropic
+ * identity piece still present after a failed removal, in removal order:
+ * federation rule, Anthropic service account, Kubernetes ServiceAccount.
+ */
+export function buildManualStepsChecklist(
+  envRows: { key: string; secret: boolean }[],
+  leftoverIdentity?: LeftoverIdentity,
+): ManualStep[] {
+  const steps: ManualStep[] = [];
+
+  for (const row of envRows) {
+    if (!row.secret) continue;
+    if (SLACK_APP_MANAGED_KEYS.has(row.key)) continue;
+
+    const namedInstruction = NAMED_KEY_INSTRUCTIONS[row.key];
+    if (namedInstruction !== undefined) {
+      steps.push({ key: row.key, message: namedInstruction });
+      continue;
+    }
+
+    steps.push({
+      key: row.key,
+      message: `Custom secret '${row.key}' was added manually and has no automated revocation — verify whether it needs to be revoked at the source.`,
+    });
+  }
+
+  // Identity pieces the automated removal left behind, in removal order. The
+  // rule goes first: Anthropic refuses to archive a service account while a
+  // live rule references it.
+  if (leftoverIdentity?.anthropicFederationRuleId) {
+    steps.push({
+      key: "anthropicFederationRuleId",
+      message: `Anthropic federation rule ${leftoverIdentity.anthropicFederationRuleId} was not archived automatically — archive it in the Anthropic console first (a service account cannot be archived while a live rule references it).`,
+    });
+  }
+  if (leftoverIdentity?.anthropicServiceAccountId) {
+    steps.push({
+      key: "anthropicServiceAccountId",
+      message: `Anthropic service account ${leftoverIdentity.anthropicServiceAccountId} was not archived automatically — archive it in the Anthropic console once its federation rule is archived.`,
+    });
+  }
+  if (leftoverIdentity?.k8sServiceAccountName) {
+    steps.push({
+      key: "k8sServiceAccountName",
+      message: `Kubernetes ServiceAccount ${leftoverIdentity.k8sServiceAccountName} was not deleted automatically — delete it from the agent namespace with kubectl.`,
+    });
+  }
+
+  return steps;
+}