@app-vitals/agent-admin 0.16.0 → 0.16.2

package/src/agent-cron-jobs.unit.test.ts

@@ -12,8 +12,8 @@ import { describe, expect, test } from "bun:test";
 import type { AgentCronJob, PrismaClient } from "../prisma/client/client.ts";
 import { AgentCronJobService, isValidCron } from "./agent-cron-jobs.ts";
 import {
-  type SpecialtyManifestResolver,
   resolveDefaultSpecialtyName,
+  type SpecialtyManifestResolver,
 } from "./specialty-manifest-loader.ts";
 import type { SpecialtyManifest } from "./specialty-registry.ts";
 
@@ -374,36 +374,29 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
     expect(String(errors[0]?.[0])).toContain("agent-1");
   });
 
-  test("the default manifest that cannot load still throws", async () => {
+  test("the default type with no loadable manifest logs an error and changes nothing", async () => {
     const registry = fakeRegistry({});
-    const { prisma } = makeFakePrisma({
-      specialty: resolveDefaultSpecialtyName(),
-    });
-    const service = new AgentCronJobService(
-      prisma as unknown as PrismaClient,
-      undefined,
-      registry,
-    );
-
-    await expect(service.reconcileSystemCrons("agent-1")).rejects.toThrow(
-      resolveDefaultSpecialtyName(),
-    );
-  });
-
-  test("the default-manifest failure names the env vars that configure it", async () => {
-    const registry = fakeRegistry({});
-    const { prisma } = makeFakePrisma({
-      specialty: resolveDefaultSpecialtyName(),
+    const { prisma, rows } = makeFakePrisma({
+      specialty: "specialist",
+      existing: [{ id: "sys-1", name: "old-system", system: true }],
     });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
       registry,
     );
-
-    await expect(service.reconcileSystemCrons("agent-1")).rejects.toThrow(
-      /SHIPWRIGHT_SPECIALTIES_DIR.*SHIPWRIGHT_DEFAULT_AGENT_TYPE/s,
-    );
+    const original = console.error;
+    console.error = () => {};
+    try {
+      expect(await service.reconcileSystemCrons("agent-1")).toEqual({
+        created: 0,
+        updated: 0,
+        deleted: 0,
+      });
+    } finally {
+      console.error = original;
+    }
+    expect(Array.from(rows.keys())).toEqual(["sys-1"]);
   });
 
   test("a valid non-coding manifest reconciles normally", async () => {

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.fixture.integration.test.ts

@@ -50,13 +50,17 @@ describe("SpecialtyRegistry with the fixture specialty", () => {
     expect(fixtureRegistry().tryGetManifest("renamed-type")).toBeUndefined();
   });
 
-  it("fails with an actionable error when the default specialty is not on disk", () => {
+  it("warns and returns an empty-crons manifest when the default specialty is not on disk", () => {
+    const warnings: string[] = [];
     const registry = new SpecialtyRegistry({
       typesDir: FIXTURE_SPECIALTIES_DIR,
       defaultTypeName: "not-there",
-      warn: () => {},
+      warn: (m) => warnings.push(m),
     });
-    expect(() => registry.getManifest("fixture-or-anything")).toThrow(
+    const manifest = registry.getManifest("fixture-or-anything");
+    expect(manifest.crons).toEqual([]);
+    expect(manifest.plugins).toEqual([]);
+    expect(warnings.join("\n")).toMatch(
       /SHIPWRIGHT_SPECIALTIES_DIR.*SHIPWRIGHT_DEFAULT_AGENT_TYPE/s,
     );
   });

package/src/specialty-manifest-loader.ts

@@ -2,24 +2,25 @@
  * admin/src/specialty-manifest-loader.ts
  *
  * 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
+ * Specialty manifest by loading `{typesDir}/{specialty}/manifest.yaml` from
+ * disk (typesDir defaults to the shipped agent-types/) and validating it via
  * parseSpecialtyManifest().
  *
  * This is the runtime source of truth for an agent's default system crons
  * (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 `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
- * whose type was renamed or removed.
+ * Defaults: the default type is `specialist` and the type directory is the
+ * shipped `agent-types/` (both resolved by @app-vitals/agent-lib/default-specialty,
+ * the single shared helper; SHIPWRIGHT_DEFAULT_AGENT_TYPE /
+ * SHIPWRIGHT_SPECIALTIES_DIR override them).
  *
- * Hard-failure contract: if the "coding" manifest itself (the universal
- * fallback) cannot be loaded or fails validation, that is a configuration error
- * (it names SHIPWRIGHT_SPECIALTIES_DIR / SHIPWRIGHT_DEFAULT_AGENT_TYPE) and the error propagates — we never silently degrade the fallback into a
- * no-op that would strip every agent's system crons.
+ * Fallback contract: getManifest() never throws. An unknown `specialty` (no
+ * matching directory under the type dir) resolves to the default type's
+ * manifest with a logged warning. If even the default cannot be loaded (bad
+ * env override, missing/invalid manifest) it warns and returns a built-in
+ * minimal manifest with no crons/plugins, so the boot-path
+ * POST /agents/:id/crons/reconcile route never 5xxs over configuration.
  *
  * The class takes an injectable reader/warner so unit tests can drive it
  * without touching the filesystem (see agent-cron-jobs.unit.test.ts).
@@ -28,12 +29,47 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
-  type SpecialtyManifest,
+  DEFAULT_SPECIALTY_NAME,
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+} from "@app-vitals/agent-lib/default-specialty";
+import {
   parseSpecialtyManifest,
+  type SpecialtyManifest,
 } from "./specialty-registry.ts";
 
-/** The universal fallback type — every agent degrades to this manifest. */
-export const DEFAULT_SPECIALTY_NAME = "coding";
+export {
+  DEFAULT_SPECIALTY_NAME,
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+};
+
+/**
+ * Built-in last-resort manifest: used only when the default type itself cannot
+ * be loaded. Declares nothing (no crons, plugins, tools) so it never seeds
+ * anything unexpected.
+ */
+const BUILT_IN_FALLBACK_MANIFEST_YAML = `apiVersion: shipwright.dev/v1alpha1
+kind: Specialty
+metadata:
+  name: ${DEFAULT_SPECIALTY_NAME}
+  displayName: Specialist Agent
+  description: Built-in fallback used when the default specialty manifest cannot be loaded.
+  version: 0.0.0
+  skills: []
+identity:
+  templatesDir: workspace/
+crons: []
+plugins: []
+tools: []
+env:
+  required: []
+  optional: []
+members: []
+repos: []
+chat: true
+voice: true
+`;
 
 /** Reads a manifest's raw YAML text for a type; throws if it does not exist. */
 type ManifestReader = (specialty: string) => string;
@@ -54,51 +90,6 @@ export interface SpecialtyOption {
   displayName: string;
 }
 
-/**
- * Repo root resolved relative to this module (admin/src/ → ../../). The
- * specialties/ directory lives at the repo root alongside admin/.
- */
-const REPO_ROOT = join(import.meta.dir, "..", "..");
-const BUILT_IN_SPECIALTIES_DIR = join(REPO_ROOT, "specialties");
-
-/**
- * The specialties directory: SHIPWRIGHT_SPECIALTIES_DIR when set, else the
- * repo-root specialties/ (today's location).
- */
-export function resolveSpecialtiesDir(
-  env: Record<string, string | undefined> = process.env,
-): string {
-  return env.SHIPWRIGHT_SPECIALTIES_DIR || BUILT_IN_SPECIALTIES_DIR;
-}
-
-/**
- * The universal fallback type: SHIPWRIGHT_DEFAULT_AGENT_TYPE when set, else
- * "coding".
- */
-/**
- * The actionable error for a default specialty that cannot be loaded. The
- * platform ships no specialty of its own, so this is a configuration problem:
- * the operator must point the two env vars at a real specialties directory.
- */
-export function missingDefaultSpecialtyError(
-  defaultTypeName: string,
-  typesDir: string,
-  cause?: unknown,
-): Error {
-  const detail = cause instanceof Error ? ` (${cause.message})` : "";
-  return new Error(
-    `SpecialtyRegistry: the default specialty "${defaultTypeName}" could not be loaded from "${typesDir}"${detail}. ` +
-      "Set SHIPWRIGHT_SPECIALTIES_DIR to a directory containing <type>/manifest.yaml and " +
-      "SHIPWRIGHT_DEFAULT_AGENT_TYPE to the name of a specialty in it.",
-  );
-}
-
-export function resolveDefaultSpecialtyName(
-  env: Record<string, string | undefined> = process.env,
-): string {
-  return env.SHIPWRIGHT_DEFAULT_AGENT_TYPE || DEFAULT_SPECIALTY_NAME;
-}
-
 /** Default reader: loads {typesDir}/{specialty}/manifest.yaml from disk. */
 export function defaultManifestReader(
   specialty: string,
@@ -122,18 +113,21 @@ export function defaultTypeDirLister(
  */
 export interface SpecialtyManifestResolver {
   /**
-   * 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.
+   * Resolve `specialty` to its parsed manifest. Falls back to the default
+   * type's manifest (with a warning) when the type is unknown, and to a
+   * built-in empty-crons manifest (with a warning) if the default cannot load
+   * either. Never throws.
    */
   getManifest(specialty: string): SpecialtyManifest;
   /**
    * Resolve `specialty` to its parsed manifest WITHOUT falling back to
-   * "coding" — 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
-   * "coding" agent under a different label.
+   * default-type agent under a different label.
    */
   tryGetManifest(specialty: string): SpecialtyManifest | undefined;
   /**
@@ -142,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 {
@@ -157,8 +159,8 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
 
   /**
    * `typesDir` and `defaultTypeName` default to SHIPWRIGHT_SPECIALTIES_DIR /
-   * SHIPWRIGHT_DEFAULT_AGENT_TYPE, then to today's repo-root specialties/
-   * and "coding". An injected `read`/`list` takes precedence over `typesDir`.
+   * SHIPWRIGHT_DEFAULT_AGENT_TYPE, then to the shipped agent-types/
+   * and "specialist". An injected `read`/`list` takes precedence over `typesDir`.
    */
   constructor(
     opts: {
@@ -179,42 +181,68 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
   }
 
   getManifest(specialty: string): SpecialtyManifest {
-    const resolved = this.tryLoad(specialty);
+    const resolved = this.tryLoadSafe(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 specialty "${specialty}" — ` +
         `falling back to "${this.defaultTypeName}" manifest`,
     );
-    if (specialty === this.defaultTypeName) {
-      // Guard against infinite intent: the default itself failed to load.
-      throw missingDefaultSpecialtyError(this.defaultTypeName, this.typesDir);
-    }
-    try {
-      return this.loadOrThrow(this.defaultTypeName);
-    } catch (err) {
-      throw missingDefaultSpecialtyError(
-        this.defaultTypeName,
-        this.typesDir,
-        err,
-      );
+    if (specialty !== this.defaultTypeName) {
+      const fallback = this.tryLoadSafe(this.defaultTypeName);
+      if (fallback) return fallback;
     }
+    // Even the default is unloadable (bad SHIPWRIGHT_SPECIALTIES_DIR /
+    // SHIPWRIGHT_DEFAULT_AGENT_TYPE override). Degrade to an empty manifest
+    // rather than failing boot; the warning names the knobs to fix.
+    this.warn(
+      `SpecialtyRegistry: the default specialty "${this.defaultTypeName}" could not be loaded from "${this.typesDir}" — ` +
+        "using a built-in manifest with no crons. Check SHIPWRIGHT_SPECIALTIES_DIR and SHIPWRIGHT_DEFAULT_AGENT_TYPE.",
+    );
+    return parseSpecialtyManifest(BUILT_IN_FALLBACK_MANIFEST_YAML);
   }
 
   /**
-   * Resolve `specialty` without falling back to "coding" — see the interface
+   * Resolve `specialty` without falling back to the default type — see the interface
    * doc comment. Thin public wrapper around the existing tryLoad() used
    * 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);
@@ -227,6 +255,15 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
     return options;
   }
 
+  /** tryLoad, but an invalid (unparseable) manifest also yields undefined. */
+  private tryLoadSafe(specialty: string): SpecialtyManifest | undefined {
+    try {
+      return this.tryLoad(specialty);
+    } catch {
+      return undefined;
+    }
+  }
+
   /** Load + cache a manifest, returning undefined only if the file is missing. */
   private tryLoad(specialty: string): SpecialtyManifest | undefined {
     const cached = this.cache.get(specialty);
@@ -240,13 +277,6 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
     return this.parseAndCache(specialty, raw);
   }
 
-  /** Load + cache a manifest, propagating any read/parse error. */
-  private loadOrThrow(specialty: string): SpecialtyManifest {
-    const cached = this.cache.get(specialty);
-    if (cached) return cached;
-    return this.parseAndCache(specialty, this.read(specialty));
-  }
-
   private parseAndCache(specialty: string, raw: string): SpecialtyManifest {
     const manifest = parseSpecialtyManifest(raw);
     this.cache.set(specialty, manifest);