@app-vitals/agent-admin 0.16.1 → 0.16.2

package/openapi.platform.json

@@ -537,7 +537,7 @@
           },
           "specialty": {
             "type": "string",
-            "example": "coding"
+            "example": "specialist"
           }
         },
         "required": [
@@ -558,7 +558,7 @@
           "specialty": {
             "type": "string",
             "minLength": 1,
-            "example": "coding"
+            "example": "specialist"
           },
           "runtime": {
             "type": "string",
@@ -3091,11 +3091,11 @@
           },
           "specialty": {
             "type": "string",
-            "example": "coding"
+            "example": "specialist"
           },
           "typeName": {
             "type": "string",
-            "example": "coding",
+            "example": "specialist",
             "deprecated": true
           },
           "phaseMethodology": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-admin",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.135.0",
-    "@app-vitals/agent-lib": "0.16.1",
+    "@app-vitals/agent-lib": "0.16.2",
     "@hono/zod-openapi": "^1.0.0",
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",

package/prisma/client/internal/class.ts

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

package/prisma/migrations/20261030100000_set_agent_specialty_default_specialist/migration.sql

@@ -0,0 +1,4 @@
+-- PCD-3.4: change the Agent.specialty column default from 'coding' to 'specialist'.
+-- Default only: no row rewrites, no constraint, no backfill, so every existing
+-- agent keeps its stored value.
+ALTER TABLE "Agent" ALTER COLUMN "specialty" SET DEFAULT 'specialist';

package/prisma/schema/schema.prisma

@@ -44,7 +44,7 @@ model Agent {
   restrictSlackToMembers Boolean  @default(false)
   // The agent's Specialty name (manifest key). AGR-6.3 made it required and
   // dropped the legacy typeName column.
-  specialty              String   @default("coding")
+  specialty              String   @default("specialist")
   // SSP-1.2: owning account. Nullable/additive — existing agents keep NULL.
   accountId              String?
   account                Account? @relation(fields: [accountId], references: [id], onDelete: Restrict)

package/src/admin-boot.ts

@@ -69,6 +69,7 @@ import {
   mountRouteContributions,
   resolveAdminExtensions,
   startBackgroundPasses,
+  withExtensionAgentTypes,
 } from "./admin-extension.ts";
 import { createAdminUIApp } from "./admin-ui.ts";
 import { AgentAskService } from "./agent-ask.ts";
@@ -182,6 +183,10 @@ export async function startAdmin(
   // Extension-supplied specialty defaults (crons/tools/plugins), consulted by
   // the cron reconcile and create-time seeding before the manifest.
   const specialtyDefaults = collectSpecialtyDefaults(extensions);
+  const specialtyRegistry = withExtensionAgentTypes(
+    new SpecialtyRegistry(),
+    extensions,
+  );
   const agentCronJobService = new AgentCronJobService(
     prisma,
     undefined,
@@ -458,7 +463,7 @@ export async function startAdmin(
     agentPluginService,
     agentMemberService,
     callerScopeResolver,
-    specialtyRegistry: new SpecialtyRegistry(),
+    specialtyRegistry,
     specialtyDefaults,
     agentChatTokenService,
     agentGitHubInstallationsService,
@@ -551,6 +556,7 @@ export async function startAdmin(
     agentService,
     provisioner,
     anthropicFederationEnabled,
+    specialtyRegistry,
     specialtyDefaults,
     serviceIntegrations,
     chatService: deletionChatService,

package/src/admin-extension.ts

@@ -30,6 +30,11 @@
  *                            reconcile and create-time seeding consult it
  *                            before the specialty manifest, which remains the
  *                            fallback when no extension returns anything
+ *   agentTypes()           — agent types this extension offers in the new-agent
+ *                            picker and accepts in POST /admin/agents, for
+ *                            types with no manifest on disk. Extension entries
+ *                            win over a manifest of the same name; a type's
+ *                            crons still come from specialtyDefaults(name)
  *
  * openApi() is static (no context): scripts/generate-admin-spec.ts calls it to
  * fold extension routes/schemas into admin/openapi.json without booting.
@@ -62,6 +67,10 @@ import type {
   SpecialtyDefaults,
   SpecialtyDefaultsResolver,
 } from "./specialty-defaults.ts";
+import type {
+  SpecialtyManifestResolver,
+  SpecialtyOption,
+} from "./specialty-manifest-loader.ts";
 
 /** The platform services an extension may build on. */
 export interface AdminPlatformServices {
@@ -180,6 +189,8 @@ export interface AdminExtension {
   serviceIntegrations?(env: NodeJS.ProcessEnv): ServiceIntegration[];
   /** See the header: undefined means "no opinion" — the manifest applies. */
   specialtyDefaults?(specialty: string): SpecialtyDefaults | undefined;
+  /** See the header: additive; merged over the manifest-discovered types. */
+  agentTypes?(): SpecialtyOption[];
   services?(ctx: AdminExtensionContext): AdminExtensionServices;
   apiRoutes?(ctx: AdminExtensionContext): AdminRouteContribution[];
   adminUiRoutes?(ctx: AdminExtensionContext): AdminRouteContribution[];
@@ -373,6 +384,40 @@ export function collectSpecialtyDefaults(
   };
 }
 
+/**
+ * Merges every extension's agentTypes() over the manifest-discovered `base`
+ * list. Order is base first, then new extension names; on a name collision the
+ * extension's entry replaces the base entry in place.
+ */
+export function mergeAgentTypes(
+  base: readonly SpecialtyOption[],
+  extensions: readonly AdminExtension[],
+): SpecialtyOption[] {
+  const byName = new Map(base.map((type) => [type.name, type]));
+  for (const ext of extensions) {
+    for (const type of ext.agentTypes?.() ?? []) byName.set(type.name, type);
+  }
+  return [...byName.values()];
+}
+
+/**
+ * Wraps the registry so the new-agent picker lists extension types and
+ * POST /admin/agents accepts them. With no extension declaring agentTypes()
+ * the wrapped registry behaves exactly like `registry`.
+ */
+export function withExtensionAgentTypes(
+  registry: SpecialtyManifestResolver,
+  extensions: readonly AdminExtension[],
+): SpecialtyManifestResolver {
+  return {
+    getManifest: (specialty) => registry.getManifest(specialty),
+    tryGetManifest: (specialty) => registry.tryGetManifest(specialty),
+    listTypes: () => mergeAgentTypes(registry.listTypes(), extensions),
+    hasExtensionType: (specialty) =>
+      mergeAgentTypes([], extensions).some((type) => type.name === specialty),
+  };
+}
+
 /** Mounts each contribution on root, in order. */
 export function mountRouteContributions(
   root: AnyHono,

package/src/admin-extension.unit.test.ts

@@ -10,11 +10,13 @@ import {
   collectOpenApiContributions,
   collectServiceIntegrations,
   collectSpecialtyDefaults,
+  mergeAgentTypes,
   mountRouteContributions,
   renderAgentDetailCardSlots,
   renderAgentDetailCards,
   resolveAdminExtensions,
   startBackgroundPasses,
+  withExtensionAgentTypes,
 } from "./admin-extension.ts";
 
 // The seam only hands the context through to hooks, so an opaque stand-in is
@@ -549,3 +551,62 @@ describe("collectSpecialtyDefaults", () => {
     expect(resolve("b")).toEqual({ tools: ["B"] });
   });
 });
+
+describe("mergeAgentTypes", () => {
+  const base = [
+    { name: "specialist", displayName: "Specialist" },
+    { name: "coding", displayName: "Manifest Coding" },
+  ];
+
+  it("returns the base list unchanged with no or hookless extensions", () => {
+    expect(mergeAgentTypes(base, [])).toEqual(base);
+    expect(mergeAgentTypes(base, [{ name: "bare" }])).toEqual(base);
+    expect(mergeAgentTypes([], [])).toEqual([]);
+  });
+
+  it("appends extension types, across multiple extensions", () => {
+    const merged = mergeAgentTypes(base, [
+      { agentTypes: () => [{ name: "a", displayName: "A" }] },
+      { agentTypes: () => [{ name: "b", displayName: "B" }] },
+    ]);
+    expect(merged.map((t) => t.name)).toEqual([
+      "specialist",
+      "coding",
+      "a",
+      "b",
+    ]);
+  });
+
+  it("lets the extension win on a name collision, keeping position", () => {
+    const merged = mergeAgentTypes(base, [
+      { agentTypes: () => [{ name: "coding", displayName: "Coding Agent" }] },
+      { agentTypes: () => [{ name: "coding", displayName: "Later Wins" }] },
+    ]);
+    expect(merged).toEqual([
+      { name: "specialist", displayName: "Specialist" },
+      { name: "coding", displayName: "Later Wins" },
+    ]);
+  });
+});
+
+describe("withExtensionAgentTypes", () => {
+  const registry = {
+    getManifest: () => {
+      throw new Error("unused");
+    },
+    tryGetManifest: () => undefined,
+    listTypes: () => [{ name: "specialist", displayName: "Specialist" }],
+  };
+
+  it("merges listTypes and reports extension-only types", () => {
+    const wrapped = withExtensionAgentTypes(registry, [
+      { agentTypes: () => [{ name: "coding", displayName: "Coding Agent" }] },
+    ]);
+    expect(wrapped.listTypes().map((t) => t.name)).toEqual([
+      "specialist",
+      "coding",
+    ]);
+    expect(wrapped.hasExtensionType?.("coding")).toBe(true);
+    expect(wrapped.hasExtensionType?.("specialist")).toBe(false);
+  });
+});

package/src/admin-ui.smoke.test.ts

@@ -7,9 +7,11 @@
  */
 
 import { beforeAll, describe, expect, it } from "bun:test";
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { sign } from "hono/jwt";
+import { withExtensionAgentTypes } from "./admin-extension.ts";
 import { createAdminUIApp } from "./admin-ui.ts";
 import { SpecialtyRegistry } from "./specialty-manifest-loader.ts";
 import {
@@ -5666,6 +5668,36 @@ describe("admin UI — create agent seeds manifest tools and plugins", () => {
     expect(seededPlugins).toEqual(["fixture-plugin"]);
   });
 
+  it("an extension-contributed type (ETP-1.2) shows in the picker and POST /admin/agents accepts it with no manifest", async () => {
+    const emptyDir = mkdtempSync(join(tmpdir(), "no-specialties-"));
+    const registry = withExtensionAgentTypes(
+      new SpecialtyRegistry({ typesDir: emptyDir }),
+      [{ agentTypes: () => [{ name: "coding", displayName: "Coding Agent" }] }],
+    );
+    const deps = makeMockDeps();
+    deps.specialtyRegistry = registry;
+    const app = createAdminUIApp(deps);
+    const form = await app.request("/admin/agents/new", {
+      headers: { Cookie: `admin_session=${cookie}` },
+    });
+    expect(await form.text()).toContain(
+      '<option value="coding">Coding Agent</option>',
+    );
+    const res = await app.request("/admin/agents", {
+      method: "POST",
+      body: new URLSearchParams({
+        name: "Ext Agent",
+        type: "coding",
+      }).toString(),
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Cookie: `admin_session=${cookie}`,
+      },
+    });
+    expect(res.status).toBe(302);
+    expect(res.headers.get("Location")).toBe(`/admin/agents/${AGENT_ID}`);
+  });
+
   it("POST /admin/agents rolls back the agent and redirects with error when tool seeding fails", async () => {
     let deletedId: string | undefined;
     const deps = makeMockDeps();

package/src/agent-specialty-backfill.integration.test.ts

@@ -40,6 +40,9 @@ function migrationSql(dir: string): string {
 const ADD_TYPE_NAME = migrationSql("20260724000000_add_agent_type_name");
 const ADD_SPECIALTY = migrationSql("20261029000000_add_agent_specialty");
 const DROP_TYPE_NAME = migrationSql("20261030000000_drop_agent_type_name");
+const SET_DEFAULT_SPECIALIST = migrationSql(
+  "20261030100000_set_agent_specialty_default_specialist",
+);
 
 describeOrSkip("typeName -> specialty migrations (AGR-6.1 / AGR-6.3)", () => {
   const schema = `agr63_${process.pid}_${Date.now()}`;
@@ -123,4 +126,31 @@ describeOrSkip("typeName -> specialty migrations (AGR-6.1 / AGR-6.3)", () => {
     );
     expect(def.rows[0]?.specialty).toBe("coding");
   });
+
+  it("set_agent_specialty_default_specialist changes only the default and leaves rows unchanged (PCD-3.4)", async () => {
+    await client.query(ADD_TYPE_NAME);
+    await client.query(ADD_SPECIALTY);
+    await client.query(DROP_TYPE_NAME);
+    for (const [i, s] of LIVE_SPECIALTIES.entries()) {
+      await client.query(
+        `INSERT INTO "Agent" ("id","name","specialty") VALUES ($1,$2,$3)`,
+        [`a${i}`, `agent-${i}`, s],
+      );
+    }
+
+    await client.query(SET_DEFAULT_SPECIALIST);
+
+    const { rows } = await client.query<{ specialty: string }>(
+      `SELECT "specialty" FROM "Agent" ORDER BY "id"`,
+    );
+    expect(rows.map((r) => r.specialty)).toEqual([...LIVE_SPECIALTIES]);
+
+    await client.query(
+      `INSERT INTO "Agent" ("id","name") VALUES ('a9','agent-9')`,
+    );
+    const def = await client.query<{ specialty: string }>(
+      `SELECT "specialty" FROM "Agent" WHERE "id" = 'a9'`,
+    );
+    expect(def.rows[0]?.specialty).toBe("specialist");
+  });
 });

package/src/agents-api.integration.test.ts

@@ -311,7 +311,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
 
   // ─── specialty field ─────────────────────────────────────────────────────────
 
-  it("GET /agents includes specialty:'coding' for an agent created before specialty existed", async () => {
+  it("GET /agents includes specialty:'specialist' for an agent created before specialty existed", async () => {
     const res = await app.request("/agents", {
       headers: { Cookie: `admin_session=${cookie}` },
     });
@@ -319,28 +319,28 @@ describeOrSkip("admin CRUD API (integration)", () => {
     const body = await res.json();
     const entry = body.find((a: { id: string }) => a.id === agentId);
     expect(entry).toBeDefined();
-    expect(entry.specialty).toBe("coding");
+    expect(entry.specialty).toBe("specialist");
   });
 
-  it("GET /agents/:id includes specialty:'coding' by default", async () => {
+  it("GET /agents/:id includes specialty:'specialist' by default", async () => {
     const res = await app.request(`/agents/${agentId}`, {
       headers: { Cookie: `admin_session=${cookie}` },
     });
     expect(res.status).toBe(200);
     const body = await res.json();
-    expect(body.specialty).toBe("coding");
+    expect(body.specialty).toBe("specialist");
   });
 
   // ─── Migration backfill read-back (pre-existing rows + child rows) ────────────
   //
   // Simulates the exact scenario the 20260724000000_add_agent_type_name
   // migration must handle: rows that existed *before* the specialty column was
-  // added (never received an explicit value) must read back specialty="coding"
+  // added (never received an explicit value) must read back specialty="specialist"
   // via the column DEFAULT, and every child row (cron/plugin/tool/env/member)
   // must be completely untouched — same count, same updatedAt — since the
   // migration only ALTERs the Agent table.
 
-  it("migration backfill: pre-existing agent rows read back specialty='coding' and child rows (cron/plugin/tool/env/member) are untouched", async () => {
+  it("migration backfill: pre-existing agent rows read back specialty='specialist' and child rows (cron/plugin/tool/env/member) are untouched", async () => {
     // Seed a second "pre-existing" agent with one row in every child table,
     // simulating data that existed prior to the specialty migration landing.
     const preExisting = await prisma.agent.create({
@@ -383,7 +383,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
     const rawAgent = await prisma.agent.findUniqueOrThrow({
       where: { id: preExisting.id },
     });
-    expect(rawAgent.specialty).toBe("coding");
+    expect(rawAgent.specialty).toBe("specialist");
 
     // Read back via the HTTP API too — end-to-end confirmation.
     const res = await app.request(`/agents/${preExisting.id}`, {
@@ -391,7 +391,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
     });
     expect(res.status).toBe(200);
     const body = await res.json();
-    expect(body.specialty).toBe("coding");
+    expect(body.specialty).toBe("specialist");
 
     // Child row counts are unchanged — exactly one of each, still linked to
     // the same agent.
@@ -455,7 +455,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
     const rawAgent = await prisma.agent.findUniqueOrThrow({
       where: { id: agentId },
     });
-    expect(rawAgent.specialty).toBe("coding");
+    expect(rawAgent.specialty).toBe("specialist");
   });
 
   // ─── repos field round-trip ───────────────────────────────────────────────────

package/src/agents.integration.test.ts

@@ -574,7 +574,7 @@ describeOrSkip("Agent.specialty — final shape (AGR-6.3)", () => {
     ).toBe("research");
   });
 
-  it("specialty is required: NULL is rejected and omitting it applies the 'coding' default", async () => {
+  it("specialty is required: NULL is rejected and omitting it applies the 'specialist' default", async () => {
     await expect(
       (async () =>
         prisma.agent.create({
@@ -584,6 +584,6 @@ describeOrSkip("Agent.specialty — final shape (AGR-6.3)", () => {
 
     const created = await agentService.create({ name: "No Specialty" });
     createdIds.push(created.id);
-    expect(created.specialty).toBe("coding");
+    expect(created.specialty).toBe("specialist");
   });
 });

package/src/agents.ts

@@ -33,7 +33,7 @@ interface CreateAgentInput {
   name: string;
   slackId?: string | null;
   selfHosted?: boolean;
-  /** Specialty name. Omitted means Prisma's column default ("coding") applies. */
+  /** Specialty name. Omitted means Prisma's column default ("specialist") applies. */
   specialty?: string;
   /** Initial repos[] — the manifest repos merged with any request-supplied repos. */
   repos?: string[];
@@ -784,7 +784,10 @@ export interface CreateAgentDeps {
   agentEnvService: Pick<AgentEnvService, "patch">;
   agentCronJobService: Pick<AgentCronJobService, "reconcileSystemCrons">;
   provisioner: Pick<AgentProvisioner, "canProvision" | "provision">;
-  specialtyRegistry: Pick<SpecialtyManifestResolver, "tryGetManifest">;
+  specialtyRegistry: Pick<
+    SpecialtyManifestResolver,
+    "tryGetManifest" | "hasExtensionType"
+  >;
   /** Extension-supplied tools/plugins, consulted before the manifest's. */
   specialtyDefaults?: SpecialtyDefaultsResolver;
   /** WIF-2.1: Anthropic federation is enabled; defaults to false. */
@@ -884,7 +887,12 @@ export async function createAgent(
   const extensionDefaults = specialty
     ? deps.specialtyDefaults?.(specialty)
     : undefined;
-  if (!specialty || (!manifest && !extensionDefaults)) {
+  if (
+    !specialty ||
+    (!manifest &&
+      !extensionDefaults &&
+      !deps.specialtyRegistry.hasExtensionType?.(specialty))
+  ) {
     return { ok: false, errorCode: "invalid_type" };
   }
 

package/src/openapi-schemas.ts

@@ -34,7 +34,7 @@ export const AgentSummarySchema = z
     id: z.string().openapi({ example: "clx1234567890" }),
     name: z.string().openapi({ example: "Bodhi" }),
     selfHosted: z.boolean().openapi({ example: false }),
-    specialty: z.string().openapi({ example: "coding" }),
+    specialty: z.string().openapi({ example: "specialist" }),
   })
   .openapi("AgentSummary");
 
@@ -147,7 +147,7 @@ export const PatchAgentBodySchema = z
 export const CreateAgentBodySchema = z
   .object({
     name: z.string().min(1).openapi({ example: "Bodhi" }),
-    specialty: z.string().min(1).openapi({ example: "coding" }),
+    specialty: z.string().min(1).openapi({ example: "specialist" }),
     /**
      * "in-cluster" means K8s-provisioned; anything else (including absent)
      * means self-hosted.
@@ -1343,7 +1343,7 @@ export const AgentConfigResponseSchema = z
      * ARD-6.1: the agent's Specialty name, used by the runtime to pick its
      * workspace template directory.
      */
-    specialty: z.string().openapi({ example: "coding" }),
+    specialty: z.string().openapi({ example: "specialist" }),
     /**
      * DEPRECATED back-compat alias of `specialty` (always equal to it). Kept
      * only for pre-AGR-6.3 runtime images, whose entrypoint reads
@@ -1353,7 +1353,7 @@ export const AgentConfigResponseSchema = z
     typeName: z
       .string()
       .optional()
-      .openapi({ example: "coding", deprecated: true }),
+      .openapi({ example: "specialist", deprecated: true }),
     /**
      * PMC-1.1: phase -> subagentType (or null) map, covering all six pipeline
      * phases (see AGENT_PHASES) regardless of whether the agent has an

package/src/specialty-manifest-loader.ts

@@ -121,7 +121,9 @@ export interface SpecialtyManifestResolver {
   getManifest(specialty: string): SpecialtyManifest;
   /**
    * Resolve `specialty` to its parsed manifest WITHOUT falling back to
-   * the default type — returns undefined for an unknown type instead. No warning is
+   * the default type — returns undefined for an unknown type instead (the one exception
+   * is the built-in default type when no specialty is discoverable, matching the
+   * picker's fallback option). No warning is
    * logged (an unknown type here is an expected, callers-handle-it outcome,
    * not a degraded-boot condition). Used by POST /admin/agents to reject an
    * unknown requested `type` with 400 rather than silently seeding a
@@ -134,9 +136,17 @@ export interface SpecialtyManifestResolver {
    * type picker. A directory whose manifest fails to load or parse is
    * skipped (not thrown) — the picker still renders every other valid type
    * rather than 500ing the whole /admin/agents/new page over one bad
-   * manifest. Order matches the underlying `list` fn's order.
+   * manifest. Order matches the underlying `list` fn's order. Never throws:
+   * a missing type dir is treated as empty (with a warning), and when no type
+   * is discoverable the built-in default option is returned.
    */
   listTypes(): SpecialtyOption[];
+  /**
+   * True when an AdminExtension declares `specialty` via agentTypes() — a type
+   * with no manifest that POST /admin/agents must still accept. Optional: the
+   * disk-backed registry has none.
+   */
+  hasExtensionType?(specialty: string): boolean;
 }
 
 export class SpecialtyRegistry implements SpecialtyManifestResolver {
@@ -198,11 +208,41 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
    * internally by getManifest().
    */
   tryGetManifest(specialty: string): SpecialtyManifest | undefined {
-    return this.tryLoad(specialty);
+    const manifest = this.tryLoad(specialty);
+    if (manifest || specialty !== DEFAULT_SPECIALTY_NAME) return manifest;
+    // The picker offers the built-in default when nothing is discoverable, so
+    // creating an agent with it must resolve too.
+    return this.discoverOptions().length === 0
+      ? parseSpecialtyManifest(BUILT_IN_FALLBACK_MANIFEST_YAML)
+      : undefined;
   }
 
   listTypes(): SpecialtyOption[] {
-    const specialties = this.list();
+    const options = this.discoverOptions();
+    if (options.length > 0) return options;
+    // Nothing discoverable: offer the built-in default so the picker is never empty.
+    const fallback = parseSpecialtyManifest(BUILT_IN_FALLBACK_MANIFEST_YAML);
+    return [
+      {
+        name: fallback.metadata.name,
+        displayName: fallback.metadata.displayName,
+      },
+    ];
+  }
+
+  /** Every loadable specialty found on disk; empty when the dir is missing or has none. */
+  private discoverOptions(): SpecialtyOption[] {
+    let specialties: string[];
+    try {
+      specialties = this.list();
+    } catch (err) {
+      // Missing dir (e.g. npm consumers, where agent-types/ is not shipped).
+      this.warn(
+        `SpecialtyRegistry: could not list specialties under "${this.typesDir}" — ` +
+          `treating as empty (${err instanceof Error ? err.message : String(err)})`,
+      );
+      specialties = [];
+    }
     const options: SpecialtyOption[] = [];
     for (const specialty of specialties) {
       const manifest = this.tryLoad(specialty);

package/src/specialty-manifest-loader.unit.test.ts

@@ -160,6 +160,38 @@ describe("SpecialtyRegistry", () => {
     expect(warnings).toHaveLength(0);
   });
 
+  it("tryGetManifest resolves the built-in default type when no specialty is discoverable", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => {
+        throw new Error("ENOENT: no such file or directory");
+      },
+      read: (t) => {
+        throw new Error(`ENOENT: no manifest for ${t}`);
+      },
+      warn: () => {},
+    });
+
+    expect(registry.tryGetManifest(DEFAULT_SPECIALTY_NAME)?.metadata.name).toBe(
+      DEFAULT_SPECIALTY_NAME,
+    );
+    expect(registry.tryGetManifest("nonexistent-type")).toBeUndefined();
+  });
+
+  it("tryGetManifest does not synthesize the default type when other specialties are discoverable", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => ["coding"],
+      read: (t) => {
+        if (t === "coding") return manifestYaml("coding");
+        throw new Error(`ENOENT: no manifest for ${t}`);
+      },
+      warn: () => {},
+    });
+
+    expect(registry.tryGetManifest(DEFAULT_SPECIALTY_NAME)).toBeUndefined();
+  });
+
   it("tryGetManifest shares the cache with getManifest — reader called once per type", () => {
     let reads = 0;
     const registry = new SpecialtyRegistry({
@@ -259,14 +291,47 @@ voice: true
     expect(types).toEqual([{ name: "coding", displayName: "coding" }]);
   });
 
-  it("listTypes returns an empty array when no type directories are discovered", () => {
+  it("listTypes falls back to the built-in default option when no type directories are discovered", () => {
     const registry = new SpecialtyRegistry({
       defaultTypeName: DEFAULT_SPECIALTY_NAME,
       list: () => [],
       read: (t) => manifestYaml(t),
     });
 
-    expect(registry.listTypes()).toEqual([]);
+    expect(registry.listTypes()).toEqual([
+      { name: DEFAULT_SPECIALTY_NAME, displayName: "Specialist Agent" },
+    ]);
+  });
+
+  it("listTypes warns and returns the built-in default when the list fn throws (missing dir)", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      warn: (m) => warnings.push(m),
+      list: () => {
+        throw new Error("ENOENT: no such file or directory");
+      },
+      read: (t) => manifestYaml(t),
+    });
+
+    expect(registry.listTypes()).toEqual([
+      { name: DEFAULT_SPECIALTY_NAME, displayName: "Specialist Agent" },
+    ]);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("ENOENT");
+  });
+
+  it("listTypes does not throw on a nonexistent typesDir with the real lister", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      typesDir: "/nonexistent/agent-types",
+      warn: (m) => warnings.push(m),
+    });
+
+    expect(registry.listTypes()).toEqual([
+      { name: DEFAULT_SPECIALTY_NAME, displayName: "Specialist Agent" },
+    ]);
+    expect(warnings.length).toBeGreaterThan(0);
   });
 });