@app-vitals/agent-admin 0.0.1 → 0.1.0

package/prisma/schema/schema.prisma

@@ -0,0 +1,506 @@
+// Shipwright — Admin Service Schema
+// Owns: Agent, AgentEnv, AgentCronJob, AgentTool, AgentToken, AgentPlugin,
+// plus the coding-owned models in coding.prisma (AgentWorkQueueSnapshot,
+// AgentPhaseMethodology, SessionFollow, SessionAlertState).
+// Agent is a first-class model (standalone, not embedded in a User model).
+//
+// WARNING: This schema uses DATABASE_URL_SHIPWRIGHT_ADMIN — a dedicated database
+// for the admin service. Do NOT point this at a shared database.
+
+// Prisma 7: the `prisma-client` generator (ESM, driver-adapter based) replaces
+// `prisma-client-js`, and the datasource block no longer accepts `url` — the
+// connection string for CLI/Migrate lives in ../../prisma.config.ts, and the
+// runtime client connects through a PrismaPg driver adapter (see
+// admin/src/prisma-client.ts).
+generator client {
+  provider = "prisma-client"
+  output   = "../client"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+// ─── Agent ────────────────────────────────────────────────────────────────────
+// A Shipwright agent: an autonomous runner that picks tasks, builds, and ships PRs.
+
+model Agent {
+  id                     String   @id @default(cuid())
+  name                   String
+  slackId                String?  @unique
+  slackBotToken          String?  // AES-256-GCM encrypted at the service layer
+  anthropicApiKey        String?  // AES-256-GCM encrypted at the service layer
+  selfHosted             Boolean  @default(false)
+  repos                  String[] @default([])
+  // DBR-2.1→2.4: renamed from authorAllowlist. DBR-2.1 added this column as
+  // a dual-written/dual-read twin of the old authorAllowlist column and
+  // backfilled it; DBR-2.2/2.3 migrated the admin UI and the agent's
+  // runtime read path onto this field exclusively; DBR-2.4 dropped the old
+  // authorAllowlist column now that nothing reads or writes it.
+  // CODING-OWNED (AEP-3.4): reviewAuthorAllowlist and patchAuthorAllowlist are
+  // read by the coding review/patch flows. Kept on Agent (no column move).
+  reviewAuthorAllowlist  String[] @default([])
+  patchAuthorAllowlist   String[] @default([])
+  restrictSlackToMembers Boolean  @default(false)
+  typeName               String   @default("coding")
+  // SSP-1.2: owning account. Nullable/additive — existing agents keep NULL.
+  accountId              String?
+  account                Account? @relation(fields: [accountId], references: [id], onDelete: Restrict)
+  // ATE-1.1: trial expiry tracking. Both nullable/additive — null means "no
+  // trial configured" / "no warning sent yet". trialExpiresAt is settable via
+  // PATCH /agents/:id like other nullable scalar fields; trialExpiryWarnedAt
+  // is written internally by ATE-2.1's warning check (not user-editable via
+  // the PATCH route) but is included in GET/PATCH responses.
+  trialExpiresAt         DateTime?
+  trialExpiryWarnedAt    DateTime?
+  // PAI-1.1: owner and Anthropic identity. All nullable/additive — existing
+  // agents keep NULL. anthropicIdentityName is unique across agents.
+  ownerEmail                String?
+  anthropicIdentityName     String?  @unique
+  anthropicServiceAccountId String?
+  anthropicFederationRuleId String?
+  k8sServiceAccountName     String?
+  // APM-1.1: the 6 agent policy fields (auto_post_reviews, allow_self_review,
+  // min_confidence, max_findings, cleanup_merged_worktrees,
+  // cleanup_after_days). Originally mirrored from the legacy
+  // state/agent-policy.md; the DB is now the only source and each column
+  // carries its documented default.
+  // CODING-OWNED (AEP-3.4): autoPostReviews, allowSelfReview, minConfidence,
+  // maxFindings configure the coding review flow; cleanupMergedWorktrees and
+  // cleanupAfterDays below are runtime-owned.
+  autoPostReviews        Boolean  @default(true)
+  allowSelfReview        Boolean  @default(false)
+  minConfidence          Int      @default(75)
+  maxFindings            Int      @default(5)
+  cleanupMergedWorktrees Boolean  @default(true)
+  cleanupAfterDays       Int      @default(14)
+  createdAt              DateTime @default(now())
+  updatedAt              DateTime @updatedAt
+
+  envVars          AgentEnv[]
+  cronJobs         AgentCronJob[]
+  tools            AgentTool[]
+  tokens           AgentToken[]
+  plugins          AgentPlugin[]
+  members          AgentMember[]
+  chatTokenUsage   AgentChatTokenUsageDailyByModel[]
+  workQueueSnapshot AgentWorkQueueSnapshot?
+  githubInstallationsSnapshot AgentGitHubInstallationsSnapshot?
+  phaseMethodologies AgentPhaseMethodology[]
+
+  @@index([accountId])
+}
+
+// ─── Agent Env ────────────────────────────────────────────────────────────────
+// Generic key/value env var store for deployed agents.
+// Keys are env var names (e.g. ANTHROPIC_API_KEY). Values are AES-256-GCM encrypted.
+
+model AgentEnv {
+  id        String   @id @default(cuid())
+  agentId   String
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  key       String   // env var name
+  value     String   // AES-256-GCM encrypted
+  secret    Boolean  @default(false) // when true, GET /agents/:id/envs masks the value as ***
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([agentId, key])
+}
+
+// ─── Agent Cron Jobs ──────────────────────────────────────────────────────────
+// Scheduled prompts per agent.
+// Delivery target is either a Slack channel ID or a Slack user ID (DM).
+// Validation that exactly one of channel/user is set happens in the service layer.
+
+model AgentCronJob {
+  id        String   @id @default(cuid())
+  agentId   String
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  schedule  String   // cron expression e.g. "0 9 * * 1-5"
+  prompt    String
+  channel   String?  // Slack channel ID (mutually exclusive with user)
+  user      String?  // Slack user ID for DMs
+  silent    Boolean  @default(false)
+  enabled   Boolean  @default(true)
+  preCheck  String?  // optional pre-check script e.g. "shipwright:check-docs-freshness.ts"
+  name      String?  // stable key for system crons; null for user-created crons
+  system    Boolean  @default(false)
+  // Set when the trial-expiry lockdown (not the user) disabled this cron, so
+  // restoreLockdownDisabled() can re-enable exactly those crons. Null for
+  // enabled crons and for crons the user disabled manually.
+  lockdownDisabledAt DateTime?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Self-relation: a parent cron can have child "phase" crons (e.g. dev-task/
+  // review/patch/deploy phases of a single logical loop). Null for top-level
+  // crons. Deleting a parent cascades to its phase children.
+  parentCronId String?
+  parentCron   AgentCronJob?  @relation("CronPhases", fields: [parentCronId], references: [id], onDelete: Cascade)
+  phases       AgentCronJob[] @relation("CronPhases")
+
+  runs      AgentCronRun[]
+  phaseRuns AgentCronRun[] @relation("PhaseRuns")
+
+  @@index([parentCronId])
+}
+
+// ─── Agent Tools ──────────────────────────────────────────────────────────────
+// Allowed tool patterns per agent. Each row grants an agent permission to use
+// a specific tool pattern (e.g. "Read", "Bash", "Write"). The unique constraint
+// on [agentId, pattern] prevents duplicates.
+
+model AgentTool {
+  id        String   @id @default(cuid())
+  agentId   String
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  pattern   String
+  enabled   Boolean  @default(true)
+  createdAt DateTime @default(now())
+
+  @@unique([agentId, pattern])
+}
+
+// ─── Agent Tokens ─────────────────────────────────────────────────────────────
+// Scoped API tokens for agent authentication. The raw token is returned once at
+// creation; only the SHA-256 hash is stored. Token validation is O(1) via the
+// hash index.
+
+model AgentToken {
+  id        String    @id @default(cuid())
+  agentId   String
+  agent     Agent     @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  token     String    @unique // SHA-256 hash of the raw token (hex)
+  label     String?
+  createdAt DateTime  @default(now())
+  revokedAt DateTime?
+}
+
+// ─── Agent Plugins ────────────────────────────────────────────────────────────
+// Claude Code plugins installed per agent. Each row represents one installed
+// plugin package. The unique constraint on [agentId, name] prevents duplicates.
+
+model AgentPlugin {
+  id        String   @id @default(cuid())
+  agentId   String
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  name      String   // plugin package name e.g. "@shipwright/plugin"
+  version   String?  // pinned version; null = latest
+  enabled   Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([agentId, name])
+}
+
+// ─── Agent Members ────────────────────────────────────────────────────────────
+// Non-admin users granted web UI access to a specific agent.
+// Admins (SHIPWRIGHT_ADMIN_ALLOWED_EMAILS) bypass this table entirely.
+// Members can view and edit only the agents they are listed on.
+
+model AgentMember {
+  id        String   @id @default(cuid())
+  agentId   String
+  email     String
+  createdAt DateTime @default(now())
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+
+  @@unique([agentId, email])
+  @@index([email])
+}
+
+// ─── Accounts ─────────────────────────────────────────────────────────────────
+// SSP-1.2: self-serve agent provisioning. An Account owns agents and has
+// members (email-keyed) and pending invites. Phase 1: one account per email
+// (UNIQUE(email) on AccountMember). Enum-like strings are validated in the
+// service layer, matching the rest of this schema.
+
+model Account {
+  id                  String    @id @default(cuid())
+  name                String
+  status              String    @default("active") // 'active' | 'suspended' | 'trial_expired'
+  maxAgents           Int       @default(0)
+  plan                String?
+  trialExpiresAt      DateTime?
+  trialExpiryWarnedAt DateTime?
+  createdAt           DateTime  @default(now())
+  updatedAt           DateTime  @updatedAt
+
+  agents  Agent[]
+  members AccountMember[]
+  invites AccountInvite[]
+}
+
+model AccountMember {
+  id        String   @id @default(cuid())
+  accountId String
+  email     String   @unique // lowercased; one account per email in Phase 1
+  role      String   // 'owner' | 'member'
+  createdAt DateTime @default(now())
+  account   Account  @relation(fields: [accountId], references: [id], onDelete: Cascade)
+
+  @@unique([accountId, email])
+}
+
+model AccountInvite {
+  id         String    @id @default(cuid())
+  accountId  String
+  email      String    // lowercased
+  invitedBy  String
+  createdAt  DateTime  @default(now())
+  acceptedAt DateTime?
+  account    Account   @relation(fields: [accountId], references: [id], onDelete: Cascade)
+
+  @@unique([accountId, email])
+  @@index([email])
+}
+
+// ─── Agent Cron Runs ──────────────────────────────────────────────────────────
+// Execution history for AgentCronJob firings. Each row records one cron invocation:
+// whether it was skipped (pre-check returned false), the outcome, and any error.
+// agentId is denormalized for efficient agent-level history queries.
+
+model AgentCronRun {
+  id                 String    @id @default(cuid())
+  cronId             String
+  cron               AgentCronJob @relation(fields: [cronId], references: [id], onDelete: Cascade)
+  agentId            String    // denormalized from cron.agentId for efficient queries
+  startedAt          DateTime
+  completedAt        DateTime?
+  skipped            Boolean   @default(false)
+  skipReason         String?
+  outcome            String?
+  error              String?
+  itemType           String?   // work item type this run was dispatched against ("task" | "pr");
+                                // null when the tick had no dispatch (skipped tick, empty queue)
+  itemId             String?   // work item id this run was dispatched against (e.g. "WLS-2.2" or
+                                // "acme/x#123"); null when the tick had no dispatch
+  commandVariant     String?   // which slash-command variant a loop dispatch ran ("default" | "alternate");
+                                // null for runs with no variant attribution
+  sessionId          String?   // Claude session id this cron run corresponds to
+  lastHeartbeatAt    DateTime? // Most recent debounced progress-push (recordProgress())
+                                // timestamp, sourced from the agent's injected Clock. Null
+                                // for runs that never reported progress (short/legacy runs).
+                                // Lets the admin UI show a "last checked in" signal — and a
+                                // best-effort in-progress duration — for a run that stalls
+                                // or crashes before reaching completedAt. Additive/nullable;
+                                // no backfill for existing rows.
+  createdAt          DateTime  @default(now())
+
+  // Secondary/denormalized pointer to the phase cron (a child AgentCronJob)
+  // this run was dispatched by, distinct from cronId which always points at
+  // the top-level cron. Null until phase crons are wired up (LPC-1.2+).
+  // SetNull (not Cascade) on delete: deleting a phase cron shouldn't delete
+  // the parent cron's run history, which cronId's own Cascade already owns.
+  phaseId   String?
+  phaseCron AgentCronJob? @relation("PhaseRuns", fields: [phaseId], references: [id], onDelete: SetNull)
+
+  // ── Run telemetry (prompt-audit metrics; all additive/nullable) ──────────
+  // First-turn context baseline: the usage of the run's first assistant
+  // message. baselineContextTokens = input + cacheCreation + cacheRead of
+  // that turn — the full always-loaded context (system prompt, tool schemas,
+  // CLAUDE.md/rules, skill listing, cron prompt) independent of cache
+  // warmth. Null for resumed sessions (their first turn replays history)
+  // and for runs reported by older agent builds.
+  baselineModel               String?
+  baselineContextTokens       Int?
+  baselineInputTokens         Int?
+  baselineCacheCreationTokens Int?
+  baselineCacheReadTokens     Int?
+  // Distinct usage-bearing assistant turns / distinct tool_use blocks.
+  turns     Int?
+  toolCalls Int?
+  // sha256[:12] over the workspace's always-loaded markdown (CLAUDE.md, its
+  // @imports, no-`paths` rules) + plugin version — groups runs by what the
+  // model was given, so before/after series for a markdown change key on
+  // content rather than merge date. Computed agent-side.
+  contextFingerprint String?
+  pluginVersion      String?
+  claudeCodeVersion  String?
+
+  modelBreakdown AgentCronRunModelBreakdown[]
+  skillUsage     AgentCronRunSkillUsage[]
+
+  @@index([cronId])
+  @@index([agentId, startedAt])
+  @@index([phaseId])
+  @@index([startedAt])
+  @@index([contextFingerprint])
+}
+
+// ─── Agent Cron Run Skill Usage ──────────────────────────────────────────────
+// Per-skill / per-subagent token attribution for a cron run, derived from the
+// Claude CLI stream by the agent. `kind` is "skill" (a plugin
+// skill invoked via the Skill tool), "agent" (a subagent type invoked via the
+// Agent tool), or "root" (turns before any skill was invoked). Attribution is
+// last-wins: every turn after an invoke is charged to the most recently
+// invoked skill. invokeContextDelta is input + cacheCreation of the first
+// turn after the skill's first invoke — the new context admitted when its
+// body loaded. The unique constraint on [cronRunId, kind, name] allows upsert.
+
+model AgentCronRunSkillUsage {
+  id                  String       @id @default(cuid())
+  cronRunId           String
+  kind                String
+  name                String
+  invocations         Int          @default(0)
+  turns               Int          @default(0)
+  inputTokens         Int          @default(0)
+  outputTokens        Int          @default(0)
+  cacheReadTokens     Int          @default(0)
+  cacheCreationTokens Int          @default(0)
+  invokeContextDelta  Int?
+  cronRun             AgentCronRun @relation(fields: [cronRunId], references: [id], onDelete: Cascade)
+
+  @@unique([cronRunId, kind, name])
+  @@index([kind, name])
+}
+
+// ─── Agent Cron Run Model Breakdown ──────────────────────────────────────────
+// Per-model token breakdown for a cron run. Populated when sub-agents use
+// different models in a single run. The unique constraint on [cronRunId, model]
+// allows upsert semantics.
+
+model AgentCronRunModelBreakdown {
+  id                  String       @id @default(cuid())
+  cronRunId           String
+  model               String
+  inputTokens         Int          @default(0)
+  outputTokens        Int          @default(0)
+  cacheReadTokens     Int          @default(0)
+  cacheCreationTokens Int          @default(0)
+  costUsd             Float        @default(0)
+  cronRun             AgentCronRun @relation(fields: [cronRunId], references: [id], onDelete: Cascade)
+
+  @@unique([cronRunId, model])
+}
+
+// ─── Agent Chat Token Usage (Daily, per Model) ───────────────────────────────
+// Daily rollup table for Slack/chat session token usage per agent per model.
+// Accumulated atomically via INSERT ... ON CONFLICT ... DO UPDATE (no read-modify-write).
+// Totals and byAgent aggregations are computed by summing across models.
+
+model AgentChatTokenUsageDailyByModel {
+  id                  String   @id @default(cuid())
+  agentId             String
+  agent               Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  date                String   // YYYY-MM-DD
+  model               String   // e.g. "claude-sonnet-4-5"
+  inputTokens BigInt   @default(0)
+  outputTokens BigInt   @default(0)
+  cacheReadTokens BigInt   @default(0)
+  cacheCreationTokens BigInt   @default(0)
+  costUsd             Float    @default(0)
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+
+  @@unique([agentId, date, model])
+}
+
+// ─── Agent Ask ──────────────────────────────────────────────────────────────
+// Audit row per agent-to-agent ask (COS-31.1, POST /agents/:id/ask). Written
+// before the chat call and updated after it. The question text is never
+// stored. No relation to Agent on purpose: the audit trail outlives either
+// agent. threadId is null until the chat thread is created (and stays null
+// when that call fails). status: created | pending | replied | failed.
+
+model AgentAsk {
+  id          String    @id @default(cuid())
+  fromAgentId String
+  toAgentId   String
+  threadId    String?
+  depth       Int
+  waitMs      Int
+  ttlSeconds  Int
+  status      String
+  callerLabel String
+  createdAt   DateTime  @default(now())
+  repliedAt   DateTime?
+
+  @@index([toAgentId, createdAt])
+  @@index([fromAgentId, createdAt])
+}
+
+// ─── Agent GitHub Installations Snapshot ────────────────────────────────────
+// One row per agent holding the agent's most recently reported GitHub App
+// installations (owner, installation id, state, sanitized lastError). PUT
+// replaces the whole list — a dropped installation disappears. No tokens or
+// other credentials are ever stored here.
+
+model AgentGitHubInstallationsSnapshot {
+  id            String   @id @default(cuid())
+  agentId       String   @unique
+  agent         Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  reportedAt    DateTime
+  installations Json     // GitHubInstallation[]
+  createdAt     DateTime @default(now())
+}
+
+// ─── Push Subscription ──────────────────────────────────────────────────────
+// A single browser/device Web Push subscription (RFC 8291) belonging to a
+// user. One user may have many rows (multi-device). Keyed by the unique push
+// `endpoint`; `p256dh` and `auth` are the subscription's public key + auth
+// secret used to encrypt the payload. `detailOptIn` is the USER'S opt-in for
+// how much notification detail they want on a locked screen — the effective
+// level is min(operator ceiling SHIPWRIGHT_ADMIN_PUSH_MAX_DETAIL, detailOptIn).
+// Values: "generic" | "title" | "preview". Never carries an agentId — targeting
+// is by userEmail via ChatThreadWatch, so a subscription is agent-agnostic.
+model PushSubscription {
+  id          String   @id @default(cuid())
+  userEmail   String
+  endpoint    String   @unique
+  p256dh      String   // base64url of the UA public key
+  auth        String   // base64url of the UA auth secret
+  detailOptIn String   @default("generic") // user opt-in: generic | title | preview
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([userEmail])
+}
+
+// ─── Chat Thread Watch ──────────────────────────────────────────────────────
+// Records that a user is "watching" a chat thread so the agent's reply can be
+// targeted to exactly the right subscriber(s) without fanning out to every
+// member of the agent. Upserted whenever a user sends a message in a thread.
+// The chat Message model has no author column, and admin is the only web front
+// door that knows both userEmail and threadId at send time — so authorship
+// targeting lives here, not in the chat service.
+model ChatThreadWatch {
+  id        String   @id @default(cuid())
+  userEmail String
+  threadId  String
+  agentId   String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([userEmail, threadId])
+  @@index([threadId])
+}
+
+// ─── User Notification Prefs ─────────────────────────────────────────────────
+// One row per user, holding their notification preferences. `userEmail` is
+// the primary key (one row per user, not per session). `autoFollowSessions`
+// controls whether sessions *visible to* the user (any session in an agent or
+// repo they can see — not only sessions they started) are auto-followed by
+// session-alert-sweeper.ts; `autoFollowSince` records when that behavior was
+// turned on (null if never explicitly set), and the sweeper skips
+// auto-following sessions that were already waiting before that moment. When
+// it is null the sweeper falls back to this row's `createdAt` as the boundary
+// — `autoFollowSessions` defaults to true and a row is created just by loading
+// the settings page, so "null" must not mean "no boundary", or the first sweep
+// would back-follow and immediately push the whole waiting backlog. Rows that
+// predate the sweeper were stamped once by
+// 20260911000000_backfill_auto_follow_since.
+// `reminderHourLocal` is validated to be an integer in
+// [0, 23] at the service layer (session-follow-service.ts), not here — Prisma
+// has no native CHECK constraint support in this schema style.
+model UserNotificationPrefs {
+  userEmail          String    @id
+  autoFollowSessions Boolean   @default(true)
+  reminderHourLocal  Int       @default(9)
+  autoFollowSince    DateTime?
+  createdAt          DateTime  @default(now())
+  updatedAt          DateTime  @updatedAt
+}
+

package/prisma.config.ts

@@ -0,0 +1,34 @@
+/**
+ * admin/prisma.config.ts
+ *
+ * Prisma 7 CLI configuration for the admin service.
+ *
+ * Prisma 7 removed `url` from the `datasource` block in the schema (prisma/schema/), so the
+ * connection string used by CLI commands (`prisma migrate deploy|dev`,
+ * `prisma db ...`) is declared here instead. The *runtime* client does not read
+ * this file at all — it connects through a `PrismaPg` driver adapter built in
+ * admin/src/prisma-client.ts.
+ *
+ * `datasource.url` is read straight off `process.env` rather than Prisma's
+ * `env()` helper on purpose: `env()` throws when the variable is unset, which
+ * would break `prisma generate` (run in `postinstall` and in admin/Dockerfile)
+ * in environments that legitimately have no database — generate needs the
+ * schema, not a connection. Leaving it `undefined` defers the failure to the
+ * commands that actually need a URL, which report it themselves.
+ *
+ * Paths are relative to this file (admin/), matching the existing
+ * `--schema=prisma/schema` invocations in package.json, Taskfile.yml,
+ * admin/Dockerfile, scripts/hitl.ts, and scripts/dev-tmux.ts.
+ */
+
+import { defineConfig } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema",
+  migrations: {
+    path: "prisma/migrations",
+  },
+  datasource: {
+    url: process.env.DATABASE_URL_SHIPWRIGHT_ADMIN,
+  },
+});

package/src/account-agent-create.ts

@@ -0,0 +1,42 @@
+/**
+ * admin/src/account-agent-create.ts
+ *
+ * Shared rules for self-serve agent creation by account users (SSP-4.2),
+ * used by both the admin UI form handler and the JSON API route so the two
+ * cannot drift: account users always create "coding" agents stamped with
+ * THEIR account (never a client-supplied one), and quota / account-status
+ * failures surface as clear messages.
+ */
+
+import type { CallerScope } from "./caller-scope.ts";
+import { resolveDefaultSpecialtyName } from "./specialty-manifest-loader.ts";
+
+/**
+ * The only specialty account users may create: SHIPWRIGHT_SELF_SERVE_AGENT_TYPE
+ * when set, else the platform's default specialty (SHIPWRIGHT_DEFAULT_AGENT_TYPE,
+ * "coding" when unset).
+ */
+export function getSelfServeSpecialty(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return (
+    env.SHIPWRIGHT_SELF_SERVE_AGENT_TYPE || resolveDefaultSpecialtyName(env)
+  );
+}
+
+/** Account the caller may create agents in, or null when they have none. */
+export function accountIdFromScope(scope: CallerScope): string | null {
+  return scope.kind === "scoped" ? scope.accountId : null;
+}
+
+/** Clear, user-facing messages for the account-specific createAgent() errors. */
+export const ACCOUNT_CREATE_ERROR_MESSAGES = {
+  quota_exceeded: "This account has reached its agent limit.",
+  account_inactive: "This account is not active.",
+} as const;
+
+export function isAccountCreateErrorCode(
+  code: string,
+): code is keyof typeof ACCOUNT_CREATE_ERROR_MESSAGES {
+  return code in ACCOUNT_CREATE_ERROR_MESSAGES;
+}

package/src/account-agent-create.unit.test.ts

@@ -0,0 +1,28 @@
+/**
+ * admin/src/account-agent-create.unit.test.ts
+ * Unit tests for self-serve specialty resolution (AEP-1.2).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { getSelfServeSpecialty } from "./account-agent-create.ts";
+
+describe("getSelfServeSpecialty", () => {
+  it("defaults to coding", () => {
+    expect(getSelfServeSpecialty({})).toBe("coding");
+    expect(
+      getSelfServeSpecialty({ SHIPWRIGHT_DEFAULT_AGENT_TYPE: "fixture" }),
+    ).toBe("fixture");
+    expect(
+      getSelfServeSpecialty({
+        SHIPWRIGHT_DEFAULT_AGENT_TYPE: "fixture",
+        SHIPWRIGHT_SELF_SERVE_AGENT_TYPE: "other",
+      }),
+    ).toBe("other");
+  });
+
+  it("honours SHIPWRIGHT_SELF_SERVE_AGENT_TYPE", () => {
+    expect(
+      getSelfServeSpecialty({ SHIPWRIGHT_SELF_SERVE_AGENT_TYPE: "base" }),
+    ).toBe("base");
+  });
+});