@app-vitals/agent-admin 0.12.0 → 0.13.1

package/src/agents.unit.test.ts

@@ -29,7 +29,7 @@ interface FakeAgentRow {
   reviewAuthorAllowlist: string[];
   patchAuthorAllowlist: string[];
   restrictSlackToMembers: boolean;
-  typeName: string;
+  specialty: string;
   createdAt: Date;
   updatedAt: Date;
   // APM-1.3: the six real agent-policy fields (APM-1.1 DB columns).
@@ -93,7 +93,7 @@ function makeFakePrisma(
         reviewAuthorAllowlist: data.reviewAuthorAllowlist ?? [],
         patchAuthorAllowlist: data.patchAuthorAllowlist ?? [],
         restrictSlackToMembers: data.restrictSlackToMembers ?? false,
-        typeName: "coding",
+        specialty: "coding",
         createdAt: new Date("2024-01-01"),
         updatedAt: new Date("2024-01-01"),
         autoPostReviews: true,
@@ -257,8 +257,8 @@ function fakeRegistry(
   requiredEnvByType: Record<string, string[]>,
 ): SpecialtyManifestResolver {
   return {
-    getManifest(typeName: string): SpecialtyManifest {
-      const required = requiredEnvByType[typeName] ?? [];
+    getManifest(specialty: string): SpecialtyManifest {
+      const required = requiredEnvByType[specialty] ?? [];
       return {
         env: {
           required: required.map((key) => ({
@@ -270,9 +270,9 @@ function fakeRegistry(
         },
       } as unknown as SpecialtyManifest;
     },
-    tryGetManifest(typeName: string): SpecialtyManifest | undefined {
-      if (!(typeName in requiredEnvByType)) return undefined;
-      return this.getManifest(typeName);
+    tryGetManifest(specialty: string): SpecialtyManifest | undefined {
+      if (!(specialty in requiredEnvByType)) return undefined;
+      return this.getManifest(specialty);
     },
     listTypes() {
       return Object.keys(requiredEnvByType).map((name) => ({
@@ -293,7 +293,7 @@ function seedRow(overrides: Partial<FakeAgentRow> = {}): FakeAgentRow {
     reviewAuthorAllowlist: [],
     patchAuthorAllowlist: [],
     restrictSlackToMembers: false,
-    typeName: "coding",
+    specialty: "coding",
     createdAt: new Date("2024-01-01"),
     updatedAt: new Date("2024-01-01"),
     autoPostReviews: true,
@@ -399,7 +399,7 @@ describe("AgentService.delete", () => {
 // ─── list ───────────────────────────────────────────────────────────────────
 
 describe("AgentService.list", () => {
-  it("returns id/name/selfHosted/typeName for all agents, ordered by name asc", async () => {
+  it("returns id/name/selfHosted/specialty for all agents, ordered by name asc", async () => {
     const prisma = makeFakePrisma([
       seedRow({ id: "a1", name: "Zeta", selfHosted: false }),
       seedRow({ id: "a2", name: "Alpha", selfHosted: true }),
@@ -413,14 +413,12 @@ describe("AgentService.list", () => {
         id: "a2",
         name: "Alpha",
         selfHosted: true,
-        typeName: "coding",
         specialty: "coding",
       },
       {
         id: "a1",
         name: "Zeta",
         selfHosted: false,
-        typeName: "coding",
         specialty: "coding",
       },
     ]);
@@ -437,7 +435,7 @@ describe("AgentService.list", () => {
 // ─── getSummary ─────────────────────────────────────────────────────────────
 
 describe("AgentService.getSummary", () => {
-  it("returns {id, name, selfHosted, typeName} for an existing agent", async () => {
+  it("returns {id, name, selfHosted, specialty} for an existing agent", async () => {
     const row = seedRow({ id: "a1", name: "Existing", selfHosted: true });
     const prisma = makeFakePrisma([row]) as unknown as FakePrisma;
     const service = new AgentService(prisma as never);
@@ -446,7 +444,6 @@ describe("AgentService.getSummary", () => {
       id: "a1",
       name: "Existing",
       selfHosted: true,
-      typeName: "coding",
       specialty: "coding",
     });
   });
@@ -462,7 +459,7 @@ describe("AgentService.getSummary", () => {
 // ─── getDetail ──────────────────────────────────────────────────────────────
 
 describe("AgentService.getDetail", () => {
-  it("returns the full record including repos, typeName, timestamps, and an empty missingRequiredEnv when the type has no required contract", async () => {
+  it("returns the full record including repos, specialty, timestamps, and an empty missingRequiredEnv when the type has no required contract", async () => {
     const row = seedRow({
       id: "a1",
       name: "Existing",
@@ -487,7 +484,6 @@ describe("AgentService.getDetail", () => {
       reviewAuthorAllowlist: ["octocat"],
       patchAuthorAllowlist: [],
       restrictSlackToMembers: false,
-      typeName: "coding",
       specialty: "coding",
       createdAt: row.createdAt,
       updatedAt: row.updatedAt,
@@ -527,7 +523,7 @@ describe("AgentService.getDetail", () => {
     expect(detail?.cleanupAfterDays).toBe(30);
   });
 
-  it("defaults typeName to 'coding' when the row was seeded without an explicit value", async () => {
+  it("defaults specialty to 'coding' when the row was seeded without an explicit value", async () => {
     const row = seedRow({ id: "a1" });
     const prisma = makeFakePrisma([row]) as unknown as FakePrisma;
     const service = new AgentService(
@@ -537,7 +533,7 @@ describe("AgentService.getDetail", () => {
 
     const detail = await service.getDetail("a1");
 
-    expect(detail?.typeName).toBe("coding");
+    expect(detail?.specialty).toBe("coding");
   });
 
   it("returns null when the agent does not exist", async () => {
@@ -548,7 +544,7 @@ describe("AgentService.getDetail", () => {
   });
 
   it("lists a required env key in missingRequiredEnv when no AgentEnv row exists for it", async () => {
-    const row = seedRow({ id: "a1", typeName: "coding" });
+    const row = seedRow({ id: "a1", specialty: "coding" });
     const prisma = makeFakePrisma([row]) as unknown as FakePrisma;
     const service = new AgentService(
       prisma as never,
@@ -561,7 +557,7 @@ describe("AgentService.getDetail", () => {
   });
 
   it("clears a required key from missingRequiredEnv once its AgentEnv row is seeded", async () => {
-    const row = seedRow({ id: "a1", typeName: "coding" });
+    const row = seedRow({ id: "a1", specialty: "coding" });
     const prisma = makeFakePrisma([row], {
       a1: ["CLAUDE_CODE_OAUTH_TOKEN"],
     }) as unknown as FakePrisma;
@@ -576,7 +572,7 @@ describe("AgentService.getDetail", () => {
   });
 
   it("returns an empty missingRequiredEnv array (not undefined/null) when the manifest's required contract is empty, without querying AgentEnv", async () => {
-    const row = seedRow({ id: "a1", typeName: "coding" });
+    const row = seedRow({ id: "a1", specialty: "coding" });
     const prisma = makeFakePrisma([row]) as unknown as FakePrisma;
     let findManyCalled = false;
     const originalFindMany = prisma.agentEnv.findMany.bind(prisma.agentEnv);
@@ -597,7 +593,7 @@ describe("AgentService.getDetail", () => {
   });
 
   it("never includes AgentEnv values in the computed result — only key names are read", async () => {
-    const row = seedRow({ id: "a1", typeName: "coding" });
+    const row = seedRow({ id: "a1", specialty: "coding" });
     const prisma = makeFakePrisma([row], {
       a1: ["CLAUDE_CODE_OAUTH_TOKEN"],
     }) as unknown as FakePrisma;
@@ -747,8 +743,7 @@ describe("AgentService.getById", () => {
       restrictSlackToMembers: false,
       memberEmails: [],
       accountStatus: null,
-      // ARD-6.1: getById() now selects typeName for the runtime config response.
-      typeName: "coding",
+      // ARD-6.1: getById() now selects specialty for the runtime config response.
       specialty: "coding",
       selfHosted: false,
       // APM-1.5: getById() now selects these 6 policy fields too.
@@ -785,8 +780,7 @@ describe("AgentService.getById", () => {
       restrictSlackToMembers: false,
       memberEmails: [],
       accountStatus: null,
-      // ARD-6.1: getById() now selects typeName for the runtime config response.
-      typeName: "coding",
+      // ARD-6.1: getById() now selects specialty for the runtime config response.
       specialty: "coding",
       selfHosted: false,
       // APM-1.5: getById() now selects these 6 policy fields too.
@@ -1055,7 +1049,6 @@ describe("AgentService.updateFields", () => {
       reviewAuthorAllowlist: ["octocat"],
       patchAuthorAllowlist: [],
       restrictSlackToMembers: false,
-      typeName: "coding",
       specialty: "coding",
       createdAt: row.createdAt,
       updatedAt: new Date("2024-01-02"),
@@ -1151,14 +1144,14 @@ function fakeCreateSpecialtyRegistry(
   byType: Record<string, SpecialtyManifest> = { coding: CODING_MANIFEST },
 ): Pick<SpecialtyManifestResolver, "tryGetManifest"> {
   return {
-    tryGetManifest: (typeName: string) => byType[typeName],
+    tryGetManifest: (specialty: string) => byType[specialty],
   };
 }
 
 interface CreateAgentHarnessCalls {
   created: Array<{
     name: string;
-    typeName?: string;
+    specialty?: string;
     selfHosted?: boolean;
   }>;
   deleted: string[];
@@ -1211,7 +1204,7 @@ function makeCreateAgentHarness(
         reviewAuthorAllowlist: input.reviewAuthorAllowlist ?? [],
         patchAuthorAllowlist: input.patchAuthorAllowlist ?? [],
         restrictSlackToMembers: input.restrictSlackToMembers ?? false,
-        typeName: input.typeName ?? "coding",
+        specialty: input.specialty ?? "coding",
         createdAt: new Date("2024-01-01"),
         updatedAt: new Date("2024-01-01"),
         missingRequiredEnv: [],
@@ -1219,7 +1212,7 @@ function makeCreateAgentHarness(
       agents.set(id, detail);
       calls.created.push({
         name: input.name,
-        typeName: input.typeName,
+        specialty: input.specialty,
         selfHosted: input.selfHosted,
       });
       return detail;
@@ -1313,7 +1306,7 @@ function baseCreateAgentInput(
 ): CreateAgentFormInput {
   return {
     name: "Test Agent",
-    typeName: "coding",
+    specialty: "coding",
     runtime: undefined,
     reposRaw: undefined,
     authorAllowlistRaw: undefined,
@@ -1434,24 +1427,24 @@ describe("createAgent()", () => {
     expect(calls.created).toEqual([]);
   });
 
-  it("returns invalid_type and creates nothing when typeName is unknown", async () => {
+  it("returns invalid_type and creates nothing when specialty is unknown", async () => {
     const { deps, calls } = makeCreateAgentHarness();
 
     const result = await createAgent(
       deps,
-      baseCreateAgentInput({ typeName: "nonexistent" }),
+      baseCreateAgentInput({ specialty: "nonexistent" }),
     );
 
     expect(result).toEqual({ ok: false, errorCode: "invalid_type" });
     expect(calls.created).toEqual([]);
   });
 
-  it("returns invalid_type and creates nothing when typeName is missing", async () => {
+  it("returns invalid_type and creates nothing when specialty is missing", async () => {
     const { deps, calls } = makeCreateAgentHarness();
 
     const result = await createAgent(
       deps,
-      baseCreateAgentInput({ typeName: undefined }),
+      baseCreateAgentInput({ specialty: undefined }),
     );
 
     expect(result).toEqual({ ok: false, errorCode: "invalid_type" });

package/src/api.smoke.test.ts

@@ -39,6 +39,7 @@ interface MockAgent {
   restrictSlackToMembers: boolean;
   memberEmails: string[];
   accountStatus?: string | null;
+  specialty?: string;
   selfHosted?: boolean;
   // APM-1.5: the 6 agent-policy fields passed through by GET /:id/config.
   autoPostReviews: boolean;
@@ -94,6 +95,7 @@ function makeMockAgentService(agents: Map<string, MockAgent>): {
     restrictSlackToMembers: boolean;
     memberEmails: string[];
     accountStatus?: string | null;
+    specialty: string;
     selfHosted?: boolean;
     autoPostReviews: boolean;
     allowSelfReview: boolean;
@@ -112,6 +114,7 @@ function makeMockAgentService(agents: Map<string, MockAgent>): {
       restrictSlackToMembers: boolean;
       memberEmails: string[];
       accountStatus?: string | null;
+      specialty: string;
       selfHosted?: boolean;
       autoPostReviews: boolean;
       allowSelfReview: boolean;
@@ -130,6 +133,7 @@ function makeMockAgentService(agents: Map<string, MockAgent>): {
             restrictSlackToMembers: agent.restrictSlackToMembers,
             memberEmails: agent.memberEmails,
             accountStatus: agent.accountStatus,
+            specialty: agent.specialty ?? "coding",
             selfHosted: agent.selfHosted,
             autoPostReviews: agent.autoPostReviews,
             allowSelfReview: agent.allowSelfReview,
@@ -228,6 +232,7 @@ function buildApp(opts?: {
   restrictSlackToMembers?: boolean;
   memberEmails?: string[];
   accountStatus?: string | null;
+  specialty?: string;
   selfHosted?: boolean;
   anthropicFederationEnabled?: boolean;
   phaseMethodology?: MockPhaseMethodology[];
@@ -283,6 +288,7 @@ function buildApp(opts?: {
       restrictSlackToMembers,
       memberEmails,
       accountStatus: opts?.accountStatus,
+      specialty: opts?.specialty,
       selfHosted: opts?.selfHosted,
       autoPostReviews,
       allowSelfReview,
@@ -332,6 +338,21 @@ describe("GET /:id/config with no phase-methodology service (platform only)", ()
   });
 });
 
+describe("GET /:id/config deprecated typeName alias (AGR-6.3)", () => {
+  // Pre-AGR-6.3 runtime images read only config.typeName to set
+  // SHIPWRIGHT_AGENT_TYPE; the alias must mirror specialty until they roll.
+  test("typeName equals specialty for a non-coding specialty", async () => {
+    const app = buildApp({ specialty: "research" });
+    const res = await app.request(`/${KNOWN_AGENT_ID}/config`, {
+      headers: { Authorization: `Bearer ${VALID_ADMIN_KEY}` },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.specialty).toBe("research");
+    expect(body.typeName).toBe("research");
+  });
+});
+
 describe("GET /:id/config features (COS-43.1)", () => {
   const get = (app: ReturnType<typeof buildApp>) =>
     app.request(`/${KNOWN_AGENT_ID}/config`, {
@@ -736,6 +757,7 @@ function buildCombinedApp() {
           patchAuthorAllowlist: [],
           restrictSlackToMembers: false,
           memberEmails: [],
+          specialty: "coding",
           // APM-1.5: required by AgentConfigResponseSchema.
           autoPostReviews: true,
           allowSelfReview: false,
@@ -772,7 +794,7 @@ function buildCombinedApp() {
         reviewAuthorAllowlist: [],
         patchAuthorAllowlist: [],
         restrictSlackToMembers: false,
-        typeName: "coding",
+        specialty: "coding",
         createdAt: new Date(),
         updatedAt: new Date(),
         missingRequiredEnv: [],
@@ -791,7 +813,7 @@ function buildCombinedApp() {
         reviewAuthorAllowlist: [],
         patchAuthorAllowlist: [],
         restrictSlackToMembers: false,
-        typeName: "coding",
+        specialty: "coding",
         createdAt: new Date(),
         updatedAt: new Date(),
         missingRequiredEnv: [],

package/src/api.ts

@@ -23,7 +23,6 @@ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import type { AgentCronJob } from "./agent-cron-jobs.ts";
 import type { AgentEnvBundle } from "./agent-envs.ts";
 import type { AgentTokenService } from "./agent-tokens.ts";
-import { resolveSpecialty } from "./agent-specialty.ts";
 import { anthropicCredentialKeysIn } from "./anthropic-credential-guard.ts";
 import { type AdminApiKey, createAdminAuthMiddleware } from "./api-auth.ts";
 import {
@@ -67,13 +66,16 @@ export interface AgentConfigResponse {
    */
   accountStatus?: string | null;
   /**
-   * ARD-6.1: the agent's Specialty name (e.g. "coding"). Additive and
-   * optional — fixtures/doubles built before this field keep compiling, and
-   * the agent runtime treats an absent value as "coding".
+   * ARD-6.1: the agent's Specialty name (e.g. "coding"), read by the agent
+   * runtime to pick its workspace template directory.
+   */
+  specialty: string;
+  /**
+   * @deprecated Back-compat alias of `specialty` for pre-AGR-6.3 runtime
+   * images (their entrypoint reads `config.typeName`). Remove once every
+   * runtime image reads `specialty`.
    */
   typeName?: string;
-  /** AGR-6.1: specialty (specialty ?? typeName); additive, optional for doubles. */
-  specialty?: string;
   /**
    * PMC-1.1: phase -> subagentType (or null) map, covering all six pipeline
    * phases regardless of whether the agent has an explicit override row for
@@ -136,8 +138,7 @@ interface AgentServiceLike {
     trialExpiresAt?: Date | null;
     /** SSP-8.3: owning account status; optional for pre-existing test doubles. */
     accountStatus?: string | null;
-    typeName?: string;
-    specialty?: string | null;
+    specialty: string;
     /** WIF-2.1: optional so pre-existing test doubles keep compiling; absent is treated as not self-hosted. */
     selfHosted?: boolean;
     /** APM-1.5: the 6 agent-policy fields, direct-passthrough into the response. */
@@ -349,14 +350,12 @@ export function createAgentRuntimeApp(deps: AgentRuntimeDeps): OpenAPIHono {
         ? agent.trialExpiresAt.toISOString()
         : null,
       accountStatus: agent.accountStatus ?? null,
-      typeName: agent.typeName,
-      specialty:
-        agent.typeName === undefined
-          ? undefined
-          : resolveSpecialty({
-              typeName: agent.typeName,
-              specialty: agent.specialty,
-            }),
+      specialty: agent.specialty,
+      // DEPRECATED (AGR-6.3): back-compat alias for pre-AGR-6.3 runtime images,
+      // whose entrypoint only reads `config.typeName` to set
+      // SHIPWRIGHT_AGENT_TYPE. Without it those pods silently fall back to
+      // coding templates. Remove in a follow-up once all images have rolled.
+      typeName: agent.specialty,
       // Omitted entirely when no phase-methodology service was supplied
       // (platform-only admin, no coding extension).
       ...(agentPhaseMethodologyService ? { phaseMethodology } : {}),

package/src/openapi-schemas.ts

@@ -34,7 +34,6 @@ export const AgentSummarySchema = z
     id: z.string().openapi({ example: "clx1234567890" }),
     name: z.string().openapi({ example: "Bodhi" }),
     selfHosted: z.boolean().openapi({ example: false }),
-    typeName: z.string().openapi({ example: "coding" }),
     specialty: z.string().openapi({ example: "coding" }),
   })
   .openapi("AgentSummary");
@@ -148,7 +147,7 @@ export const PatchAgentBodySchema = z
 export const CreateAgentBodySchema = z
   .object({
     name: z.string().min(1).openapi({ example: "Bodhi" }),
-    typeName: z.string().min(1).openapi({ example: "coding" }),
+    specialty: z.string().min(1).openapi({ example: "coding" }),
     /**
      * "in-cluster" means K8s-provisioned; anything else (including absent)
      * means self-hosted.
@@ -1341,12 +1340,20 @@ export const AgentConfigResponseSchema = z
       .optional()
       .openapi({ example: "active" }),
     /**
-     * ARD-6.1: the agent's Specialty name. Optional (additive) — the runtime
-     * falls back to "coding" templates when absent.
+     * ARD-6.1: the agent's Specialty name, used by the runtime to pick its
+     * workspace template directory.
      */
-    typeName: z.string().optional().openapi({ example: "coding" }),
-    /** AGR-6.1: specialty (specialty ?? typeName); additive next to typeName. */
-    specialty: z.string().optional().openapi({ example: "coding" }),
+    specialty: z.string().openapi({ example: "coding" }),
+    /**
+     * DEPRECATED back-compat alias of `specialty` (always equal to it). Kept
+     * only for pre-AGR-6.3 runtime images, whose entrypoint reads
+     * `config.typeName` to set SHIPWRIGHT_AGENT_TYPE. Remove in a follow-up
+     * once every runtime image reads `specialty`.
+     */
+    typeName: z
+      .string()
+      .optional()
+      .openapi({ example: "coding", 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/slack-provisioning-service.integration.test.ts

@@ -140,7 +140,7 @@ function makeService(opts?: {
           reviewAuthorAllowlist: [],
           patchAuthorAllowlist: [],
           restrictSlackToMembers: false,
-          typeName: "coding",
+          specialty: "coding",
           missingRequiredEnv: [],
         })),
       updateFields: async (id: string, input: unknown) => {
@@ -156,7 +156,7 @@ function makeService(opts?: {
           reviewAuthorAllowlist: [],
           patchAuthorAllowlist: [],
           restrictSlackToMembers: false,
-          typeName: "coding",
+          specialty: "coding",
           missingRequiredEnv: [],
         };
       },

package/src/slack-provisioning.integration.test.ts

@@ -242,7 +242,7 @@ function makeMockDeps(
         reviewAuthorAllowlist: [],
         patchAuthorAllowlist: [],
         restrictSlackToMembers: false,
-        typeName: "coding",
+        specialty: "coding",
         missingRequiredEnv: [],
       }),
       updateFields: async (id: string) => ({
@@ -256,7 +256,7 @@ function makeMockDeps(
         reviewAuthorAllowlist: [],
         patchAuthorAllowlist: [],
         restrictSlackToMembers: false,
-        typeName: "coding",
+        specialty: "coding",
         missingRequiredEnv: [],
       }),
     },

package/src/specialty-manifest-loader.ts

@@ -1,8 +1,8 @@
 /**
  * admin/src/specialty-manifest-loader.ts
  *
- * SpecialtyRegistry — resolves an agent's stored `typeName` to its parsed
- * Specialty manifest by loading `specialties/{typeName}/manifest.yaml` from
+ * SpecialtyRegistry — resolves an agent's stored `specialty` to its parsed
+ * Specialty manifest by loading `specialties/{specialty}/manifest.yaml` from
  * disk (relative to the repo root) and validating it via
  * parseSpecialtyManifest().
  *
@@ -10,7 +10,7 @@
  * (and, in time, its default plugins/tools/env contract). It replaces the
  * former hardcoded SYSTEM_CRONS array in admin/src/system-crons.ts.
  *
- * Fallback contract: an unknown `typeName` (a value with no matching
+ * Fallback contract: an unknown `specialty` (a value with no matching
  * directory under specialties/) resolves to the "coding" manifest with a
  * logged warning — never throws. This keeps the boot-path
  * POST /agents/:id/crons/reconcile route from beginning to 5xx for an agent
@@ -36,13 +36,13 @@ import {
 export const DEFAULT_SPECIALTY_NAME = "coding";
 
 /** Reads a manifest's raw YAML text for a type; throws if it does not exist. */
-type ManifestReader = (typeName: string) => string;
+type ManifestReader = (specialty: string) => string;
 
-/** Sink for the unknown-typeName warning (defaults to console.warn). */
+/** Sink for the unknown-specialty warning (defaults to console.warn). */
 type WarnFn = (message: string) => void;
 
 /**
- * Lists the typeName of every discoverable specialty directory (e.g. the
+ * Lists the name of every discoverable specialty directory (e.g. the
  * names of the subdirectories under specialties/). Used by listTypes() to
  * discover candidates before resolving each one's manifest via `read`.
  */
@@ -99,12 +99,12 @@ export function resolveDefaultSpecialtyName(
   return env.SHIPWRIGHT_DEFAULT_AGENT_TYPE || DEFAULT_SPECIALTY_NAME;
 }
 
-/** Default reader: loads {typesDir}/{typeName}/manifest.yaml from disk. */
+/** Default reader: loads {typesDir}/{specialty}/manifest.yaml from disk. */
 export function defaultManifestReader(
-  typeName: string,
+  specialty: string,
   typesDir: string = resolveSpecialtiesDir(),
 ): string {
-  return readFileSync(join(typesDir, typeName, "manifest.yaml"), "utf-8");
+  return readFileSync(join(typesDir, specialty, "manifest.yaml"), "utf-8");
 }
 
 /** Default lister: the directory names under the specialties dir on disk. */
@@ -122,20 +122,20 @@ export function defaultTypeDirLister(
  */
 export interface SpecialtyManifestResolver {
   /**
-   * Resolve `typeName` to its parsed manifest. Falls back to the "coding"
+   * Resolve `specialty` to its parsed manifest. Falls back to the "coding"
    * manifest (with a warning) when the type is unknown. Never throws for an
    * unknown type — only if the "coding" fallback itself fails to load.
    */
-  getManifest(typeName: string): SpecialtyManifest;
+  getManifest(specialty: string): SpecialtyManifest;
   /**
-   * Resolve `typeName` to its parsed manifest WITHOUT falling back to
+   * Resolve `specialty` to its parsed manifest WITHOUT falling back to
    * "coding" — returns undefined for an unknown type instead. 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
    * "coding" agent under a different label.
    */
-  tryGetManifest(typeName: string): SpecialtyManifest | undefined;
+  tryGetManifest(specialty: string): SpecialtyManifest | undefined;
   /**
    * Discover every specialty directory (via the injected `list` fn) and
    * resolve each to its {name, displayName} for populating the new-agent
@@ -178,18 +178,18 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
       opts.defaultTypeName ?? resolveDefaultSpecialtyName();
   }
 
-  getManifest(typeName: string): SpecialtyManifest {
-    const resolved = this.tryLoad(typeName);
+  getManifest(specialty: string): SpecialtyManifest {
+    const resolved = this.tryLoad(specialty);
     if (resolved) return resolved;
 
     // Unknown type — warn once and fall back to "coding". The fallback load is
     // deliberately NOT wrapped in tryLoad: if "coding" can't load, that's a
     // hard startup bug and must surface, not silently become a no-op.
     this.warn(
-      `SpecialtyRegistry: unknown agent typeName "${typeName}" — ` +
+      `SpecialtyRegistry: unknown agent specialty "${specialty}" — ` +
         `falling back to "${this.defaultTypeName}" manifest`,
     );
-    if (typeName === this.defaultTypeName) {
+    if (specialty === this.defaultTypeName) {
       // Guard against infinite intent: the default itself failed to load.
       throw missingDefaultSpecialtyError(this.defaultTypeName, this.typesDir);
     }
@@ -205,19 +205,19 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
   }
 
   /**
-   * Resolve `typeName` without falling back to "coding" — see the interface
+   * Resolve `specialty` without falling back to "coding" — see the interface
    * doc comment. Thin public wrapper around the existing tryLoad() used
    * internally by getManifest().
    */
-  tryGetManifest(typeName: string): SpecialtyManifest | undefined {
-    return this.tryLoad(typeName);
+  tryGetManifest(specialty: string): SpecialtyManifest | undefined {
+    return this.tryLoad(specialty);
   }
 
   listTypes(): SpecialtyOption[] {
-    const typeNames = this.list();
+    const specialties = this.list();
     const options: SpecialtyOption[] = [];
-    for (const typeName of typeNames) {
-      const manifest = this.tryLoad(typeName);
+    for (const specialty of specialties) {
+      const manifest = this.tryLoad(specialty);
       if (!manifest) continue;
       options.push({
         name: manifest.metadata.name,
@@ -228,28 +228,28 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
   }
 
   /** Load + cache a manifest, returning undefined only if the file is missing. */
-  private tryLoad(typeName: string): SpecialtyManifest | undefined {
-    const cached = this.cache.get(typeName);
+  private tryLoad(specialty: string): SpecialtyManifest | undefined {
+    const cached = this.cache.get(specialty);
     if (cached) return cached;
     let raw: string;
     try {
-      raw = this.read(typeName);
+      raw = this.read(specialty);
     } catch {
       return undefined;
     }
-    return this.parseAndCache(typeName, raw);
+    return this.parseAndCache(specialty, raw);
   }
 
   /** Load + cache a manifest, propagating any read/parse error. */
-  private loadOrThrow(typeName: string): SpecialtyManifest {
-    const cached = this.cache.get(typeName);
+  private loadOrThrow(specialty: string): SpecialtyManifest {
+    const cached = this.cache.get(specialty);
     if (cached) return cached;
-    return this.parseAndCache(typeName, this.read(typeName));
+    return this.parseAndCache(specialty, this.read(specialty));
   }
 
-  private parseAndCache(typeName: string, raw: string): SpecialtyManifest {
+  private parseAndCache(specialty: string, raw: string): SpecialtyManifest {
     const manifest = parseSpecialtyManifest(raw);
-    this.cache.set(typeName, manifest);
+    this.cache.set(specialty, manifest);
     return manifest;
   }
 }