@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/agents.ts

@@ -0,0 +1,1097 @@
+/**
+ * agent/src/agents.ts
+ * AgentService — CRUD/read access to the Agent model.
+ *
+ * Mirrors the sibling *Service modules (AgentEnvService, AgentTokenService,
+ * etc.) so route handlers never call prisma.agent.* directly.
+ */
+
+import { findRepoNameCollisions } from "@app-vitals/agent-lib/clone-plan";
+import { DEFAULT_AGENT_ENV } from "@app-vitals/agent-lib/default-agent-env";
+import { isGithubLogin } from "@app-vitals/agent-lib/github-login";
+import { isOrgRepo } from "@app-vitals/agent-lib/org-repo";
+import { SECRET_ENV_VARS } from "@app-vitals/agent-lib/secret-env-vars";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import type { AgentAnthropicIdentity } from "./agent-anthropic-identity.ts";
+import type { AgentCronJobService } from "./agent-cron-jobs.ts";
+import type { AgentEnvService } from "./agent-envs.ts";
+import { AgentMemberService } from "./agent-members.ts";
+import type { AgentPluginService } from "./agent-plugins.ts";
+import type { AgentProvisioner } from "./agent-provisioner.ts";
+import type { AgentToolService } from "./agent-tools.ts";
+import {
+  type SpecialtyManifestResolver,
+  SpecialtyRegistry,
+} from "./specialty-manifest-loader.ts";
+import { ANTHROPIC_CREDENTIALS_BLOCKED_CODE } from "./anthropic-credential-guard.ts";
+import type { PrismaTransactionClient } from "./prisma-tx.ts";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface CreateAgentInput {
+  name: string;
+  slackId?: string | null;
+  selfHosted?: boolean;
+  /** Specialty name. Omitted means Prisma's column default ("coding") applies. */
+  typeName?: string;
+  /** Initial repos[] — the manifest repos merged with any request-supplied repos. */
+  repos?: string[];
+  /** Initial reviewAuthorAllowlist[]. */
+  reviewAuthorAllowlist?: string[];
+  /** Initial patchAuthorAllowlist[]. Independent of reviewAuthorAllowlist. */
+  patchAuthorAllowlist?: string[];
+  /** Initial restrictSlackToMembers flag. Omitted means the column default (false) applies. */
+  restrictSlackToMembers?: boolean;
+  /** Owning Account (SSP-4.1). Omitted means the agent has no account (legacy behavior). */
+  accountId?: string;
+  /** Owner's email (PAI-1.2). Already normalized by createAgent(); omitted means no owner. */
+  ownerEmail?: string;
+}
+
+export interface AgentRecord {
+  id: string;
+  name: string;
+  slackId: string | null;
+  selfHosted: boolean;
+  typeName: string;
+  createdAt: Date;
+  updatedAt: Date;
+  /** Owning account (SSP-5.2 admin Account column); null for legacy agents. */
+  accountId?: string | null;
+  /**
+   * Optional here even though listAll()/listByIds()/searchByName() below
+   * always return the full Prisma row (repos included, since none of them
+   * pass a `select` clause) — kept optional so existing call sites/test
+   * doubles constructing a narrower AgentRecord literal don't need updating.
+   * Consumed by the merged fleet-wide queue-activity view (AAV-2.1) to build
+   * the repo -> agentId[] eligibility index (agent-work-queue-merge.ts's
+   * buildEligibilityIndex()).
+   */
+  repos?: string[];
+}
+
+/**
+ * The owner and per-agent Anthropic identity IDs (inherited, all optional) are
+ * selected by list()/getSummary() so reconcile targets carry them; GET /agents
+ * strips them from its response.
+ */
+export interface AgentSummary extends Partial<AgentAnthropicIdentity> {
+  id: string;
+  name: string;
+  selfHosted: boolean;
+  typeName: string;
+  /** Owning account; null/absent for platform agents. */
+  accountId?: string | null;
+}
+
+export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
+  id: string;
+  name: string;
+  slackId: string | null;
+  selfHosted: boolean;
+  repos: string[];
+  reviewAuthorAllowlist: string[];
+  patchAuthorAllowlist: string[];
+  restrictSlackToMembers: boolean;
+  typeName: string;
+  /**
+   * Owning account, null for unassigned (platform) agents. Optional here so
+   * existing test doubles constructing a narrower AgentDetail literal don't
+   * need updating.
+   */
+  accountId?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  /**
+   * Required env keys declared by the agent's type manifest that have no
+   * corresponding AgentEnv row yet — key names only, never values
+   * (secrets_in_logs). Always present (empty array when the type's required
+   * contract is empty or every required key is set). Informational only —
+   * not a create blocker or provisioning gate (ATS-4.2).
+   */
+  missingRequiredEnv: string[];
+  /**
+   * ATE-1.1: trial expiry tracking, both additive/nullable. trialExpiresAt is
+   * settable via PATCH /agents/:id (see UpdateSelfHostedInput below).
+   * trialExpiryWarnedAt is written internally by ATE-2.1's warning check —
+   * read-only via this route, GET/PATCH responses only. Optional here (like
+   * `repos` above) so existing test doubles constructing a narrower
+   * AgentDetail literal don't need updating.
+   */
+  trialExpiresAt?: Date | null;
+  trialExpiryWarnedAt?: Date | null;
+  /**
+   * APM-1.3: the six real agent-policy fields (APM-1.1 DB columns,
+   * Prisma-column defaults noted per field below). Optional here (like
+   * `repos`/`trialExpiresAt` above) so existing test doubles constructing a
+   * narrower AgentDetail literal don't need updating.
+   */
+  autoPostReviews?: boolean;
+  allowSelfReview?: boolean;
+  minConfidence?: number;
+  maxFindings?: number;
+  cleanupMergedWorktrees?: boolean;
+  cleanupAfterDays?: number;
+}
+
+interface UpdateSelfHostedInput {
+  /** SSP-5.3: owning account; null clears it (unassigned/platform agent). */
+  accountId?: string | null;
+  /**
+   * Optional to mirror Prisma's generated AgentUpdateInput shape (undefined
+   * means "leave unchanged"); callers such as PATCH /agents/:id currently
+   * always pass a value since selfHosted is treated as required at the route
+   * level, but the type stays permissive to match the underlying data layer.
+   */
+  selfHosted?: boolean;
+  repos?: string[];
+  reviewAuthorAllowlist?: string[];
+  patchAuthorAllowlist?: string[];
+  restrictSlackToMembers?: boolean;
+  /**
+   * Backfills agent.slackId (UAP-1.3) — nullable so it can also be
+   * explicitly cleared via PATCH /agents/:id.
+   */
+  slackId?: string | null;
+  /**
+   * ATE-1.1: nullable so it can also be explicitly cleared via
+   * PATCH /agents/:id (omitted entirely means "leave unchanged").
+   */
+  trialExpiresAt?: Date | null;
+  /** APM-1.3: see AgentDetail's doc comment for these six fields. */
+  autoPostReviews?: boolean;
+  allowSelfReview?: boolean;
+  minConfidence?: number;
+  maxFindings?: number;
+  cleanupMergedWorktrees?: boolean;
+  cleanupAfterDays?: number;
+}
+
+interface AgentIdAndRepos {
+  id: string;
+  repos: string[];
+  reviewAuthorAllowlist: string[];
+  patchAuthorAllowlist: string[];
+  restrictSlackToMembers: boolean;
+  memberEmails: string[];
+  /**
+   * ATE-3.1: read by the runtime config route so the agent process can gate
+   * Slack access once its trial has passed. Optional so pre-existing
+   * fixtures/doubles built against this interface before ATE-3.1 (e.g.
+   * agents.unit.test.ts's getById() `toEqual` fixtures) keep compiling
+   * unchanged.
+   */
+  trialExpiresAt?: Date | null;
+  /**
+   * WIF-2.1: read by the runtime config route to decide whether Anthropic
+   * credentials are stripped under federation. Optional for fixture compat.
+   */
+  selfHosted?: boolean;
+  /**
+   * SSP-8.3: status of the owning Account, or null when the agent has none.
+   * Read by the runtime config route so the agent process can pause Slack.
+   * Optional for the same fixture-compat reason as trialExpiresAt.
+   */
+  accountStatus?: string | null;
+  /**
+   * ARD-6.1: the agent's Specialty name, surfaced on the runtime config
+   * response so the agent process can pick its workspace template directory.
+   * Optional for the same fixture-compat reason as trialExpiresAt.
+   */
+  typeName?: string;
+  /**
+   * APM-1.5: the 6 agent-policy fields, read by the runtime GET /:id/config
+   * route for direct passthrough. Required (not optional) since the Prisma
+   * select below always returns them (each column has a schema default).
+   */
+  autoPostReviews: boolean;
+  allowSelfReview: boolean;
+  minConfidence: number;
+  maxFindings: number;
+  cleanupMergedWorktrees: boolean;
+  cleanupAfterDays: number;
+}
+
+export interface AgentOption {
+  id: string;
+  name: string;
+}
+
+export interface UpdateAgentFieldsInput {
+  name?: string;
+  /** SSP-5.3: owning account; null clears it (unassigned/platform agent). */
+  accountId?: string | null;
+  repos?: string[];
+  reviewAuthorAllowlist?: string[];
+  patchAuthorAllowlist?: string[];
+  restrictSlackToMembers?: boolean;
+  selfHosted?: boolean;
+  slackId?: string | null;
+  /**
+   * ATE-2.1: stamped internally by TrialExpiryWarningSweeper once a warning
+   * Slack alert has been sent — never accepted from PATCH /agents/:id (see
+   * agents-api.ts's PatchAgentBodySchema, which omits this field entirely).
+   */
+  trialExpiryWarnedAt?: Date | null;
+  /** APM-1.3: see AgentDetail's doc comment for these six fields. */
+  autoPostReviews?: boolean;
+  allowSelfReview?: boolean;
+  minConfidence?: number;
+  maxFindings?: number;
+  cleanupMergedWorktrees?: boolean;
+  cleanupAfterDays?: number;
+}
+
+// ─── Select shapes ────────────────────────────────────────────────────────────
+
+const SUMMARY_SELECT = {
+  id: true,
+  name: true,
+  selfHosted: true,
+  typeName: true,
+  accountId: true,
+  ownerEmail: true,
+  anthropicIdentityName: true,
+  anthropicServiceAccountId: true,
+  anthropicFederationRuleId: true,
+  k8sServiceAccountName: true,
+} as const;
+
+const DETAIL_SELECT = {
+  id: true,
+  name: true,
+  slackId: true,
+  selfHosted: true,
+  repos: true,
+  reviewAuthorAllowlist: true,
+  patchAuthorAllowlist: true,
+  restrictSlackToMembers: true,
+  typeName: true,
+  accountId: true,
+  createdAt: true,
+  updatedAt: true,
+  trialExpiresAt: true,
+  trialExpiryWarnedAt: true,
+  autoPostReviews: true,
+  allowSelfReview: true,
+  minConfidence: true,
+  maxFindings: true,
+  cleanupMergedWorktrees: true,
+  cleanupAfterDays: true,
+  // ownerEmail and the three Anthropic identity fields are returned by GET
+  // /agents/:id (serializeAgent picks them explicitly). k8sServiceAccountName
+  // stays out of the API response; the post-PATCH reconcile of the agent's
+  // workload needs it.
+  ownerEmail: true,
+  anthropicIdentityName: true,
+  anthropicServiceAccountId: true,
+  anthropicFederationRuleId: true,
+  k8sServiceAccountName: true,
+} as const;
+
+// ─── Service ──────────────────────────────────────────────────────────────────
+
+export class AgentService {
+  constructor(
+    private prisma: PrismaClient,
+    private specialtyRegistry: SpecialtyManifestResolver = new SpecialtyRegistry(),
+    private agentMemberService: Pick<
+      AgentMemberService,
+      "listByAgentId"
+    > = new AgentMemberService(prisma),
+  ) {}
+
+  /**
+   * Create a new agent row, plus `missingRequiredEnv` (see
+   * computeMissingRequiredEnv) — a freshly created agent has no AgentEnv rows
+   * yet, so this always reflects the full set of the type's required keys.
+   *
+   * @param client - defaults to `this.prisma`; pass the `tx` argument from a
+   *   caller's `prisma.$transaction(async (tx) => ...)` to make this write
+   *   participate in that transaction (see createAgent() below).
+   */
+  async create(
+    input: CreateAgentInput,
+    client: PrismaTransactionClient = this.prisma,
+  ): Promise<AgentDetail> {
+    const row = await client.agent.create({
+      data: {
+        name: input.name,
+        slackId: input.slackId ?? null,
+        selfHosted: input.selfHosted ?? false,
+        ...(input.typeName !== undefined ? { typeName: input.typeName } : {}),
+        ...(input.repos !== undefined ? { repos: input.repos } : {}),
+        ...(input.reviewAuthorAllowlist !== undefined
+          ? { reviewAuthorAllowlist: input.reviewAuthorAllowlist }
+          : {}),
+        ...(input.patchAuthorAllowlist !== undefined
+          ? { patchAuthorAllowlist: input.patchAuthorAllowlist }
+          : {}),
+        ...(input.restrictSlackToMembers !== undefined
+          ? { restrictSlackToMembers: input.restrictSlackToMembers }
+          : {}),
+        ...(input.accountId !== undefined
+          ? { accountId: input.accountId }
+          : {}),
+        ...(input.ownerEmail !== undefined
+          ? { ownerEmail: input.ownerEmail }
+          : {}),
+      },
+    });
+    const missingRequiredEnv = await this.computeMissingRequiredEnv(
+      row.id,
+      row.typeName,
+      client,
+    );
+    return { ...row, missingRequiredEnv };
+  }
+
+  /**
+   * Delete an agent row by id. Used as the provisioning-failure rollback path
+   * on create(), and (out of scope here) internally by deleteAgentFully().
+   *
+   * @param client - defaults to `this.prisma`; pass the `tx` argument from a
+   *   caller's `prisma.$transaction(async (tx) => ...)` to make this write
+   *   participate in that transaction (see createAgent() below).
+   */
+  async delete(
+    id: string,
+    client: PrismaTransactionClient = this.prisma,
+  ): Promise<void> {
+    await client.agent.delete({ where: { id } });
+  }
+
+  /**
+   * Run a function inside a single interactive Prisma transaction — a thin
+   * wrapper over `this.prisma.$transaction()` so callers outside this class
+   * (e.g. createAgent() below, driven from admin-ui.ts with injected service
+   * doubles in tests) never need direct access to the raw PrismaClient.
+   */
+  async runTransaction<T>(
+    fn: (tx: PrismaTransactionClient) => Promise<T>,
+  ): Promise<T> {
+    return this.prisma.$transaction(fn);
+  }
+
+  /**
+   * List all agents (id + name + selfHosted + typeName), ordered by name asc.
+   */
+  async list(): Promise<AgentSummary[]> {
+    return this.prisma.agent.findMany({
+      select: SUMMARY_SELECT,
+      orderBy: { name: "asc" },
+    });
+  }
+
+  /**
+   * Get {id, name, selfHosted, typeName} for a single agent. Returns null if
+   * not found.
+   */
+  async getSummary(id: string): Promise<AgentSummary | null> {
+    return this.prisma.agent.findUnique({
+      where: { id },
+      select: SUMMARY_SELECT,
+    });
+  }
+
+  /**
+   * The env-contract gap: the type manifest's required env keys minus the
+   * keys already present in this agent's AgentEnv rows (key names only,
+   * never values — the AgentEnv query below selects only `key`, never
+   * `value`, so decrypted secrets can never reach this computation).
+   * Skips the AgentEnv query entirely when the manifest declares no required
+   * keys. Purely informational: never blocks create or gates provisioning
+   * (ATS-4.2).
+   */
+  private async computeMissingRequiredEnv(
+    agentId: string,
+    typeName: string,
+    client: PrismaTransactionClient = this.prisma,
+  ): Promise<string[]> {
+    const requiredKeys = this.specialtyRegistry
+      .getManifest(typeName)
+      .env.required.map((entry) => entry.key);
+
+    if (requiredKeys.length === 0) return [];
+
+    // Key names only — never select/decrypt AgentEnv.value here.
+    const presentEnvRows = await client.agentEnv.findMany({
+      where: { agentId },
+      select: { key: true },
+    });
+    const presentKeys = new Set(presentEnvRows.map((r) => r.key));
+    return requiredKeys.filter((key) => !presentKeys.has(key));
+  }
+
+  /**
+   * Get the full agent record (incl. repos/typeName/timestamps), plus
+   * `missingRequiredEnv` (see computeMissingRequiredEnv). Returns null if not
+   * found.
+   */
+  async getDetail(id: string): Promise<AgentDetail | null> {
+    const row = await this.prisma.agent.findUnique({
+      where: { id },
+      select: DETAIL_SELECT,
+    });
+    if (!row) return null;
+
+    const missingRequiredEnv = await this.computeMissingRequiredEnv(
+      id,
+      row.typeName,
+    );
+    return { ...row, missingRequiredEnv };
+  }
+
+  /**
+   * Returns whether an agent with the given id exists.
+   */
+  async exists(id: string): Promise<boolean> {
+    const agent = await this.prisma.agent.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+    return agent !== null;
+  }
+
+  /**
+   * Update selfHosted (and optionally repos) for an agent. Returns the full
+   * updated record.
+   */
+  async updateSelfHosted(
+    id: string,
+    input: UpdateSelfHostedInput,
+  ): Promise<AgentDetail> {
+    const row = await this.prisma.agent.update({
+      where: { id },
+      data: {
+        selfHosted: input.selfHosted,
+        ...(input.accountId !== undefined
+          ? { accountId: input.accountId }
+          : {}),
+        ...(input.repos !== undefined ? { repos: input.repos } : {}),
+        ...(input.reviewAuthorAllowlist !== undefined
+          ? { reviewAuthorAllowlist: input.reviewAuthorAllowlist }
+          : {}),
+        ...(input.patchAuthorAllowlist !== undefined
+          ? { patchAuthorAllowlist: input.patchAuthorAllowlist }
+          : {}),
+        ...(input.restrictSlackToMembers !== undefined
+          ? { restrictSlackToMembers: input.restrictSlackToMembers }
+          : {}),
+        ...(input.slackId !== undefined ? { slackId: input.slackId } : {}),
+        ...(input.trialExpiresAt !== undefined
+          ? { trialExpiresAt: input.trialExpiresAt }
+          : {}),
+        ...(input.autoPostReviews !== undefined
+          ? { autoPostReviews: input.autoPostReviews }
+          : {}),
+        ...(input.allowSelfReview !== undefined
+          ? { allowSelfReview: input.allowSelfReview }
+          : {}),
+        ...(input.minConfidence !== undefined
+          ? { minConfidence: input.minConfidence }
+          : {}),
+        ...(input.maxFindings !== undefined
+          ? { maxFindings: input.maxFindings }
+          : {}),
+        ...(input.cleanupMergedWorktrees !== undefined
+          ? { cleanupMergedWorktrees: input.cleanupMergedWorktrees }
+          : {}),
+        ...(input.cleanupAfterDays !== undefined
+          ? { cleanupAfterDays: input.cleanupAfterDays }
+          : {}),
+      },
+      select: DETAIL_SELECT,
+    });
+    const missingRequiredEnv = await this.computeMissingRequiredEnv(
+      id,
+      row.typeName,
+    );
+    return { ...row, missingRequiredEnv };
+  }
+
+  /**
+   * Get {id, repos, reviewAuthorAllowlist, patchAuthorAllowlist,
+   * restrictSlackToMembers, memberEmails, trialExpiresAt, accountStatus, and the 6 APM-1.5
+   * agent-policy fields} for a single agent — used by the runtime
+   * config/crons routes. Returns null if not found.
+   */
+  async getById(id: string): Promise<AgentIdAndRepos | null> {
+    const row = await this.prisma.agent.findUnique({
+      where: { id },
+      select: {
+        id: true,
+        repos: true,
+        reviewAuthorAllowlist: true,
+        patchAuthorAllowlist: true,
+        restrictSlackToMembers: true,
+        trialExpiresAt: true,
+        selfHosted: true,
+        typeName: true,
+        account: { select: { status: true } },
+        autoPostReviews: true,
+        allowSelfReview: true,
+        minConfidence: true,
+        maxFindings: true,
+        cleanupMergedWorktrees: true,
+        cleanupAfterDays: true,
+      },
+    });
+    if (!row) return null;
+
+    const members = await this.agentMemberService.listByAgentId(id);
+    const memberEmails = members.map((m) => m.email);
+    const { account, ...rest } = row;
+    return { ...rest, memberEmails, accountStatus: account?.status ?? null };
+  }
+
+  /**
+   * List every agent, full record, no filtering — used by dashboard-style
+   * pages (e.g. /admin/agents isAdmin branch, /admin/provision, /admin/tasks,
+   * /admin/prs, /admin/chat) that want every field back in whatever default
+   * order Prisma returns.
+   */
+  async listAll(): Promise<AgentRecord[]> {
+    return this.prisma.agent.findMany();
+  }
+
+  /**
+   * List agents matching a given set of ids — used for batch-resolving
+   * agent ids to full records (e.g. the non-admin /admin/agents filter path
+   * and agentNames-resolution on the tasks/PRs pages).
+   */
+  async listByIds(ids: string[]): Promise<AgentRecord[]> {
+    return this.prisma.agent.findMany({ where: { id: { in: ids } } });
+  }
+
+  /**
+   * Search agents by name, case-insensitive substring match — used by the
+   * /admin/tasks agent-name filter.
+   */
+  async searchByName(query: string): Promise<AgentRecord[]> {
+    return this.prisma.agent.findMany({
+      where: { name: { contains: query, mode: "insensitive" } },
+    });
+  }
+
+  /**
+   * List {id, name} for all agents, ordered by name asc. Backs both the
+   * full-record-mapped-to-{id,name} call sites (chat page, provision pages)
+   * and the name-only autocomplete call site (tasks page).
+   */
+  async listOptions(): Promise<AgentOption[]> {
+    return this.prisma.agent.findMany({
+      select: { id: true, name: true },
+      orderBy: { name: "asc" },
+    });
+  }
+
+  /**
+   * Generic partial-field update for an agent's
+   * name/repos/reviewAuthorAllowlist/patchAuthorAllowlist/
+   * restrictSlackToMembers/selfHosted/slackId. Only fields present in the
+   * input are touched. Returns the full updated detail record.
+   */
+  async updateFields(
+    id: string,
+    input: UpdateAgentFieldsInput,
+    client: PrismaTransactionClient = this.prisma,
+  ): Promise<AgentDetail> {
+    const row = await client.agent.update({
+      where: { id },
+      data: {
+        ...(input.name !== undefined && { name: input.name }),
+        ...(input.accountId !== undefined && { accountId: input.accountId }),
+        ...(input.repos !== undefined && { repos: input.repos }),
+        ...(input.reviewAuthorAllowlist !== undefined && {
+          reviewAuthorAllowlist: input.reviewAuthorAllowlist,
+        }),
+        ...(input.patchAuthorAllowlist !== undefined && {
+          patchAuthorAllowlist: input.patchAuthorAllowlist,
+        }),
+        ...(input.restrictSlackToMembers !== undefined && {
+          restrictSlackToMembers: input.restrictSlackToMembers,
+        }),
+        ...(input.selfHosted !== undefined && {
+          selfHosted: input.selfHosted,
+        }),
+        ...(input.slackId !== undefined && { slackId: input.slackId }),
+        ...(input.trialExpiryWarnedAt !== undefined && {
+          trialExpiryWarnedAt: input.trialExpiryWarnedAt,
+        }),
+        ...(input.autoPostReviews !== undefined && {
+          autoPostReviews: input.autoPostReviews,
+        }),
+        ...(input.allowSelfReview !== undefined && {
+          allowSelfReview: input.allowSelfReview,
+        }),
+        ...(input.minConfidence !== undefined && {
+          minConfidence: input.minConfidence,
+        }),
+        ...(input.maxFindings !== undefined && {
+          maxFindings: input.maxFindings,
+        }),
+        ...(input.cleanupMergedWorktrees !== undefined && {
+          cleanupMergedWorktrees: input.cleanupMergedWorktrees,
+        }),
+        ...(input.cleanupAfterDays !== undefined && {
+          cleanupAfterDays: input.cleanupAfterDays,
+        }),
+      },
+      select: DETAIL_SELECT,
+    });
+    const missingRequiredEnv = await this.computeMissingRequiredEnv(
+      id,
+      row.typeName,
+      client,
+    );
+    return { ...row, missingRequiredEnv };
+  }
+}
+
+// ─── createAgent() ────────────────────────────────────────────────────────────
+
+/**
+ * Raw form-shaped input for createAgent() — mirrors exactly what
+ * admin-ui.ts's POST /admin/agents handler extracts from the submitted
+ * FormData, before any parsing/validation. createAgent() owns all of the
+ * parsing (multi-line repo/allowlist/member lists, dedup, format validation)
+ * that the old inline handler used to do itself, so there is exactly one
+ * implementation of agent creation (APA-1.1).
+ */
+export interface CreateAgentFormInput {
+  name: string | undefined;
+  typeName: string | undefined;
+  /**
+   * "in-cluster" means K8s-provisioned; anything else (including absent)
+   * means self-hosted — matches the pre-APA-1.1 handler's fallback rule.
+   */
+  runtime: string | undefined;
+  reposRaw: string | undefined;
+  authorAllowlistRaw: string | undefined;
+  patchAuthorAllowlistRaw: string | undefined;
+  memberEmailsRaw: string | undefined;
+  /** Raw "true"/"false" form value — only the literal string "true" enables it. */
+  restrictSlackToMembersRaw: string | undefined;
+  claudeCodeOauthToken: string | undefined;
+  anthropicApiKey: string | undefined;
+  /**
+   * Owning Account (SSP-4.1). Service-level input only — callers must
+   * resolve it from the authenticated principal, never from a request body.
+   * When set, the account's status and maxAgents quota are enforced
+   * race-safely inside the creation transaction.
+   */
+  accountId?: string;
+  /**
+   * Agent owner (PAI-1.2). Service-level input only — callers must resolve it
+   * from the authenticated principal, never from a request body. createAgent()
+   * trims and lower-cases it; blank is treated as absent.
+   */
+  ownerEmail?: string;
+}
+
+// Deliberately simple: one @, no whitespace, a dotted domain. Enough to keep
+// a non-email admin key name out of the ownerEmail column.
+const OWNER_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Resolve the agent owner for the JSON API (PAI-1.2): the session user's
+ * email when present; otherwise the bearer caller's name, but only if it is
+ * itself a valid email address (an admin API key named like one). Anything
+ * else — a plain key name or an agent id — yields undefined so a non-email
+ * never lands in the email column. Always lower-cased.
+ */
+export function resolveOwnerEmail(
+  callerEmail: string | undefined,
+  caller: { name: string } | undefined,
+): string | undefined {
+  const fromSession = callerEmail?.trim().toLowerCase();
+  if (fromSession) return fromSession;
+  const name = caller?.name.trim().toLowerCase();
+  return name && OWNER_EMAIL_RE.test(name) ? name : undefined;
+}
+
+/**
+ * Error codes matching the `?error=` query-param values the pre-APA-1.1
+ * inline handler redirected with — preserved 1:1 so createAgent() is a
+ * drop-in replacement: admin-ui.ts maps `errorCode` straight into the
+ * redirect URL (`/admin/agents/new?error=${errorCode}`).
+ */
+type CreateAgentErrorCode =
+  | "missing_fields"
+  | "invalid_type"
+  | "provisioning_disabled"
+  | "seed_failed"
+  | "invalid_repo_format"
+  | "repo_name_collision"
+  | "invalid_author_allowlist_format"
+  | "provision_failed"
+  | "quota_exceeded"
+  | "account_inactive"
+  | typeof ANTHROPIC_CREDENTIALS_BLOCKED_CODE;
+
+type CreateAgentResult =
+  | { ok: true; agent: AgentDetail; restrictSlackToMembers: boolean }
+  | { ok: false; errorCode: CreateAgentErrorCode; errorMessage?: string };
+
+/**
+ * Returns a message naming both repos of the first same-basename collision
+ * (different owners) in `repos`, or null when there is none. `repos/<name>`
+ * is keyed by basename alone, so such repos would share one clone folder.
+ */
+export function describeRepoNameCollision(repos: string[]): string | null {
+  const [collision] = findRepoNameCollisions(repos);
+  if (!collision) return null;
+  return `repos ${collision.collidesWith} and ${collision.repo} share the same name — repos/<name> clones would collide`;
+}
+
+/**
+ * Injected service dependencies for createAgent() — the same instances
+ * admin-ui.ts already constructs/receives via AdminUIDeps, narrowed to just
+ * the methods this function calls.
+ */
+export interface CreateAgentDeps {
+  agentService: Pick<
+    AgentService,
+    "create" | "delete" | "updateFields" | "runTransaction"
+  >;
+  agentToolService: Pick<AgentToolService, "add">;
+  agentPluginService: Pick<AgentPluginService, "add">;
+  agentMemberService: Pick<AgentMemberService, "add">;
+  agentEnvService: Pick<AgentEnvService, "patch">;
+  agentCronJobService: Pick<AgentCronJobService, "reconcileSystemCrons">;
+  provisioner: Pick<AgentProvisioner, "canProvision" | "provision">;
+  specialtyRegistry: Pick<SpecialtyManifestResolver, "tryGetManifest">;
+  /** WIF-2.1: Anthropic federation is enabled; defaults to false. */
+  anthropicFederationEnabled?: boolean;
+}
+
+/**
+ * Parses a textarea's newline-separated lines into a trimmed, non-empty
+ * list — optionally lower-cased and/or deduped. Mirrors the ad-hoc parsing
+ * the pre-APA-1.1 inline handler did separately for each of
+ * repos/authorAllowlist/patchAuthorAllowlist/memberEmails (repos was never
+ * deduped; the other three were).
+ */
+function parseLines(
+  raw: string,
+  opts: { lower?: boolean; dedup?: boolean } = {},
+): string[] {
+  const lines = raw
+    .split(/\r?\n/)
+    .map((l) => (opts.lower ? l.trim().toLowerCase() : l.trim()))
+    .filter((l) => l.length > 0);
+  return opts.dedup ? [...new Set(lines)] : lines;
+}
+
+/**
+ * Locks the account row (SELECT ... FOR UPDATE) so concurrent creates for the
+ * same account serialize, then checks it is active and under its maxAgents
+ * quota. Returns the failing error code, or null when a slot is available.
+ * The lock is held until the surrounding transaction commits, so the count
+ * below cannot be invalidated by a concurrent create.
+ */
+async function checkAccountQuota(
+  tx: PrismaTransactionClient,
+  accountId: string,
+): Promise<"account_inactive" | "quota_exceeded" | null> {
+  const rows = await tx.$queryRaw<{ status: string; maxAgents: number }[]>`
+    SELECT "status", "maxAgents" FROM "Account" WHERE "id" = ${accountId} FOR UPDATE`;
+  const account = rows[0];
+  if (!account) return "account_inactive";
+  if (account.status !== "active") return "account_inactive";
+  const count = await tx.agent.count({ where: { accountId } });
+  return count >= account.maxAgents ? "quota_exceeded" : null;
+}
+
+/** Discriminated outcome of the transactional portion of createAgent(). */
+type CreateAgentTxOutcome =
+  | { ok: true; agent: AgentDetail }
+  | { ok: false; errorCode: CreateAgentErrorCode; errorMessage?: string };
+
+/**
+ * Atomically create an agent: validate name/typeName, create the Agent row,
+ * seed AgentTool/AgentPlugin from the resolved type manifest, attach
+ * repos/allowlists/members, patch Claude credentials, provision Kubernetes
+ * resources when requested, and best-effort reconcile system crons.
+ *
+ * Extracted from admin-ui.ts's POST /admin/agents form handler (APA-1.1) so
+ * there is exactly one implementation of agent creation.
+ *
+ * All DB-writing steps — create, tool/plugin seeding, and attaching
+ * repos/allowlists/members — run inside a single interactive Prisma
+ * transaction via `agentService.runTransaction()`. A mid-sequence failure
+ * (seeding throws, or a repo/allowlist fails format validation) is handled
+ * by an explicit compensating `agentService.delete()` call *inside that same
+ * transaction*, followed by a normal (non-throwing) return — the delete
+ * commits atomically alongside everything that preceded it, so external
+ * readers never observe the agent in a half-seeded state and zero rows
+ * persist once the transaction commits. This preserves the pre-APA-1.1
+ * behavior of explicitly calling delete() on failure (observable by
+ * callers/tests that inject their own AgentService) while still giving the
+ * whole sequence true single-transaction atomicity.
+ *
+ * Kubernetes provisioning is an external side effect that cannot join that
+ * transaction: it runs after the transaction has already committed, and on
+ * failure the just-created Agent row is explicitly deleted as a separate
+ * statement — matching the pre-APA-1.1 delete-on-failure behavior exactly.
+ *
+ * reconcileSystemCrons() runs last and is best-effort/non-blocking —
+ * failures are logged, never surfaced as an error (mirrors the same call at
+ * agent boot, agent/src/index.ts).
+ */
+export async function createAgent(
+  deps: CreateAgentDeps,
+  input: CreateAgentFormInput,
+): Promise<CreateAgentResult> {
+  const name = input.name;
+  if (!name) {
+    return { ok: false, errorCode: "missing_fields" };
+  }
+
+  // Resolve the requested type BEFORE creating any row — an unknown/missing
+  // type must fail with zero rows created. The resolved manifest is
+  // captured (not discarded) so its tools/plugins can be seeded below.
+  const typeName = input.typeName;
+  const manifest = typeName
+    ? deps.specialtyRegistry.tryGetManifest(typeName)
+    : undefined;
+  if (!typeName || !manifest) {
+    return { ok: false, errorCode: "invalid_type" };
+  }
+
+  // Absent/unrecognized runtime means self-hosted — the historical behavior
+  // of this form.
+  const inCluster = input.runtime === "in-cluster";
+  // Same "validate before creating any row" rule as the type check above: a
+  // no-op provisioner would let provision() succeed while creating nothing,
+  // leaving an agent row with no workload behind it.
+  if (inCluster && !deps.provisioner.canProvision) {
+    return { ok: false, errorCode: "provisioning_disabled" };
+  }
+
+  // WIF-2.1: federated (in-cluster) agents must never carry Anthropic
+  // credentials — reject before any row is created.
+  if (
+    deps.anthropicFederationEnabled &&
+    inCluster &&
+    (input.claudeCodeOauthToken || input.anthropicApiKey)
+  ) {
+    return {
+      ok: false,
+      errorCode: ANTHROPIC_CREDENTIALS_BLOCKED_CODE,
+      errorMessage: `${ANTHROPIC_CREDENTIALS_BLOCKED_CODE}: Claude credentials cannot be set on an agent that uses Anthropic workload identity federation`,
+    };
+  }
+
+  const restrictSlackToMembers = input.restrictSlackToMembersRaw === "true";
+  const ownerEmail = input.ownerEmail?.trim().toLowerCase() || undefined;
+
+  const txResult = await deps.agentService.runTransaction<CreateAgentTxOutcome>(
+    async (tx) => {
+      // Quota enforcement must precede the create so a rejected request
+      // writes nothing. Skipped when tx is undefined (admin-ui.ts test
+      // doubles without runTransaction pass no real transaction).
+      if (input.accountId !== undefined && tx) {
+        const denied = await checkAccountQuota(tx, input.accountId);
+        if (denied) return { ok: false, errorCode: denied };
+      }
+
+      const agent = await deps.agentService.create(
+        {
+          name,
+          selfHosted: !inCluster,
+          typeName,
+          restrictSlackToMembers,
+          ...(input.accountId !== undefined
+            ? { accountId: input.accountId }
+            : {}),
+          ...(ownerEmail !== undefined ? { ownerEmail } : {}),
+        },
+        tx,
+      );
+
+      // Seed AgentTool/AgentPlugin rows from the resolved manifest. Roll the
+      // agent row back on any seeding failure so a retry with the same name
+      // doesn't collide with a half-seeded agent. Members/repos are NOT
+      // seeded from the manifest here — they have their own dedicated
+      // handling below, and the manifest's members/repos arrays are empty
+      // for every specialty that exists today.
+      try {
+        for (const pattern of manifest.tools) {
+          await deps.agentToolService.add(agent.id, pattern, tx);
+        }
+        for (const pluginName of manifest.plugins) {
+          await deps.agentPluginService.add(
+            agent.id,
+            pluginName,
+            undefined,
+            tx,
+          );
+        }
+      } catch (err) {
+        console.error(
+          "[agents] createAgent: tool/plugin seeding failed, rolling back:",
+          err,
+        );
+        await deps.agentService.delete(agent.id, tx).catch((cleanupErr) => {
+          console.error(
+            "[agents] createAgent: failed to roll back agent after seeding error:",
+            cleanupErr,
+          );
+        });
+        return { ok: false, errorCode: "seed_failed" };
+      }
+
+      // Attach repos if provided.
+      if (input.reposRaw) {
+        const repos = parseLines(input.reposRaw);
+        const invalid = repos.filter((r) => !isOrgRepo(r));
+        if (invalid.length > 0) {
+          await deps.agentService.delete(agent.id, tx);
+          return { ok: false, errorCode: "invalid_repo_format" };
+        }
+        const collision = describeRepoNameCollision(repos);
+        if (collision) {
+          await deps.agentService.delete(agent.id, tx);
+          return {
+            ok: false,
+            errorCode: "repo_name_collision",
+            errorMessage: collision,
+          };
+        }
+        if (repos.length > 0) {
+          await deps.agentService.updateFields(agent.id, { repos }, tx);
+        }
+      }
+
+      // Attach authorAllowlist if provided.
+      if (input.authorAllowlistRaw) {
+        const authorAllowlist = parseLines(input.authorAllowlistRaw, {
+          dedup: true,
+        });
+        const invalid = authorAllowlist.filter((l) => !isGithubLogin(l));
+        if (invalid.length > 0) {
+          await deps.agentService.delete(agent.id, tx);
+          return { ok: false, errorCode: "invalid_author_allowlist_format" };
+        }
+        if (authorAllowlist.length > 0) {
+          await deps.agentService.updateFields(
+            agent.id,
+            { reviewAuthorAllowlist: authorAllowlist },
+            tx,
+          );
+        }
+      }
+
+      // Attach patchAuthorAllowlist if provided.
+      if (input.patchAuthorAllowlistRaw) {
+        const patchAuthorAllowlist = parseLines(input.patchAuthorAllowlistRaw, {
+          dedup: true,
+        });
+        const invalid = patchAuthorAllowlist.filter((l) => !isGithubLogin(l));
+        if (invalid.length > 0) {
+          await deps.agentService.delete(agent.id, tx);
+          return { ok: false, errorCode: "invalid_author_allowlist_format" };
+        }
+        if (patchAuthorAllowlist.length > 0) {
+          await deps.agentService.updateFields(
+            agent.id,
+            { patchAuthorAllowlist },
+            tx,
+          );
+        }
+      }
+
+      // Attach member emails if provided — best-effort, mirrors the
+      // single-add POST /admin/agents/:id/members route: no format
+      // validation, and a failed/duplicate add is silently ignored rather
+      // than rolling back the agent.
+      if (input.memberEmailsRaw) {
+        const memberEmails = parseLines(input.memberEmailsRaw, {
+          lower: true,
+          dedup: true,
+        });
+        for (const email of memberEmails) {
+          try {
+            await deps.agentMemberService.add(agent.id, email, tx);
+          } catch {
+            // unique constraint violation — already a member, ignore
+          }
+        }
+      }
+
+      return { ok: true, agent };
+    },
+  );
+
+  if (!txResult.ok) {
+    return {
+      ok: false,
+      errorCode: txResult.errorCode,
+      errorMessage: txResult.errorMessage,
+    };
+  }
+  const agent = txResult.agent;
+
+  // Store the Claude credentials before provisioning so the pod comes up
+  // with them already in its env bundle rather than failing its first turn.
+  // Deliberately outside the transaction above (AgentEnvService.patch runs
+  // its own internal transaction) and not rolled back on failure, matching
+  // pre-APA-1.1 behavior: an uncaught error here propagates to the caller,
+  // leaving the already-committed agent row in place.
+  // Non-secret defaults (e.g. ANTHROPIC_MODEL) are seeded alongside so they
+  // show up in the agent's env view; the secret credentials below are
+  // operator-supplied only and never defaulted.
+  const initialEnv: Record<string, string> = { ...DEFAULT_AGENT_ENV };
+  if (input.claudeCodeOauthToken) {
+    initialEnv.CLAUDE_CODE_OAUTH_TOKEN = input.claudeCodeOauthToken;
+  }
+  if (input.anthropicApiKey) {
+    initialEnv.ANTHROPIC_API_KEY = input.anthropicApiKey;
+  }
+  await deps.agentEnvService.patch(
+    agent.id,
+    initialEnv,
+    new Set(SECRET_ENV_VARS),
+  );
+
+  if (inCluster) {
+    // Kubernetes provisioning is an external side effect that cannot join
+    // the DB transaction above — it runs after that transaction has already
+    // committed. Roll the row back explicitly on failure so a retry with the
+    // same name doesn't collide with a half-created agent.
+    try {
+      await deps.provisioner.provision(agent.id, {
+        slug: agent.name,
+        accountId: agent.accountId,
+      });
+    } catch (err) {
+      console.error(
+        "[agents] createAgent: provisioning failed, rolling back:",
+        err,
+      );
+      await deps.agentService.delete(agent.id).catch((cleanupErr) => {
+        console.error(
+          "[agents] createAgent: failed to roll back agent after provision error:",
+          cleanupErr,
+        );
+      });
+      return { ok: false, errorCode: "provision_failed" };
+    }
+  }
+
+  // Best-effort, mirroring the same call at agent boot (agent/src/index.ts).
+  // reconcileSystemCrons is a full three-pass reconcile, so a second run is a
+  // no-op — and failing here would strand the operator next to a live agent.
+  try {
+    await deps.agentCronJobService.reconcileSystemCrons(agent.id);
+  } catch (err) {
+    console.error(
+      "[agents] createAgent: failed to seed system crons (non-fatal):",
+      err,
+    );
+  }
+
+  return { ok: true, agent, restrictSlackToMembers };
+}