@app-vitals/agent-admin 0.15.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-admin",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "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.15.0",
+    "@app-vitals/agent-lib": "0.16.1",
     "@hono/zod-openapi": "^1.0.0",
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",

package/src/account-agent-create.ts

@@ -3,9 +3,9 @@
  *
  * Shared rules for self-serve agent creation by account users (SSP-4.2),
  * used by both the admin UI form handler and the JSON API route so the two
- * cannot drift: account users always create "coding" agents stamped with
- * THEIR account (never a client-supplied one), and quota / account-status
- * failures surface as clear messages.
+ * cannot drift: account users always create the self-serve specialty (see
+ * getSelfServeSpecialty) stamped with THEIR account (never a client-supplied
+ * one), and quota / account-status failures surface as clear messages.
  */
 
 import type { CallerScope } from "./caller-scope.ts";
@@ -14,7 +14,7 @@ import { resolveDefaultSpecialtyName } from "./specialty-manifest-loader.ts";
 /**
  * The only specialty account users may create: SHIPWRIGHT_SELF_SERVE_AGENT_TYPE
  * when set, else the platform's default specialty (SHIPWRIGHT_DEFAULT_AGENT_TYPE,
- * "coding" when unset).
+ * "specialist" when unset).
  */
 export function getSelfServeSpecialty(
   env: Record<string, string | undefined> = process.env,

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

@@ -7,8 +7,8 @@ import { describe, expect, it } from "bun:test";
 import { getSelfServeSpecialty } from "./account-agent-create.ts";
 
 describe("getSelfServeSpecialty", () => {
-  it("defaults to coding", () => {
-    expect(getSelfServeSpecialty({})).toBe("coding");
+  it("defaults to specialist", () => {
+    expect(getSelfServeSpecialty({})).toBe("specialist");
     expect(
       getSelfServeSpecialty({ SHIPWRIGHT_DEFAULT_AGENT_TYPE: "fixture" }),
     ).toBe("fixture");

package/src/admin-boot.ts

@@ -65,6 +65,7 @@ import {
   type AdminExtension,
   type AdminExtensionContext,
   collectServiceIntegrations,
+  collectSpecialtyDefaults,
   mountRouteContributions,
   resolveAdminExtensions,
   startBackgroundPasses,
@@ -178,7 +179,15 @@ export async function startAdmin(
     undefined,
     anthropicFederationEnabled,
   );
-  const agentCronJobService = new AgentCronJobService(prisma);
+  // Extension-supplied specialty defaults (crons/tools/plugins), consulted by
+  // the cron reconcile and create-time seeding before the manifest.
+  const specialtyDefaults = collectSpecialtyDefaults(extensions);
+  const agentCronJobService = new AgentCronJobService(
+    prisma,
+    undefined,
+    undefined,
+    specialtyDefaults,
+  );
   const agentCronRunService = new AgentCronRunService(prisma);
   const agentToolService = new AgentToolService(prisma);
   const agentTokenService = new AgentTokenService(prisma);
@@ -450,6 +459,7 @@ export async function startAdmin(
     agentMemberService,
     callerScopeResolver,
     specialtyRegistry: new SpecialtyRegistry(),
+    specialtyDefaults,
     agentChatTokenService,
     agentGitHubInstallationsService,
     prisma,
@@ -541,6 +551,7 @@ export async function startAdmin(
     agentService,
     provisioner,
     anthropicFederationEnabled,
+    specialtyDefaults,
     serviceIntegrations,
     chatService: deletionChatService,
     slack: slackClient,

package/src/admin-extension.ts

@@ -24,6 +24,12 @@
  *   agentDetailCards(ctx)  — extra cards on the agent detail page, each placed
  *                            in the header or the Configuration group
  *   backgroundPasses(ctx)  — interval loops, started after the platform sweepers
+ *   specialtyDefaults(name) — a specialty's default crons/tools/plugins. Like
+ *                            serviceIntegrations it needs no context and is
+ *                            collected before the services are built; the cron
+ *                            reconcile and create-time seeding consult it
+ *                            before the specialty manifest, which remains the
+ *                            fallback when no extension returns anything
  *
  * openApi() is static (no context): scripts/generate-admin-spec.ts calls it to
  * fold extension routes/schemas into admin/openapi.json without booting.
@@ -52,6 +58,10 @@ import type { AgentPhaseMethodologyServiceLike } from "./api.ts";
 import type { createCallerScopeResolver } from "./caller-scope.ts";
 import type { PushService } from "./push-service.ts";
 import type { ServiceIntegration } from "./service-integration.ts";
+import type {
+  SpecialtyDefaults,
+  SpecialtyDefaultsResolver,
+} from "./specialty-defaults.ts";
 
 /** The platform services an extension may build on. */
 export interface AdminPlatformServices {
@@ -168,6 +178,8 @@ export interface AdminExtension {
   name?: string;
   /** See the header: env-only, resolved before the provisioner is built. */
   serviceIntegrations?(env: NodeJS.ProcessEnv): ServiceIntegration[];
+  /** See the header: undefined means "no opinion" — the manifest applies. */
+  specialtyDefaults?(specialty: string): SpecialtyDefaults | undefined;
   services?(ctx: AdminExtensionContext): AdminExtensionServices;
   apiRoutes?(ctx: AdminExtensionContext): AdminRouteContribution[];
   adminUiRoutes?(ctx: AdminExtensionContext): AdminRouteContribution[];
@@ -344,6 +356,23 @@ export function collectServiceIntegrations(
   return extensions.flatMap((ext) => ext.serviceIntegrations?.(env) ?? []);
 }
 
+/**
+ * Builds the resolver the cron reconcile and create-time seeding consult
+ * before the manifest. The first extension returning defaults wins; with none
+ * registered (or none answering) it returns undefined and the manifest applies.
+ */
+export function collectSpecialtyDefaults(
+  extensions: readonly AdminExtension[],
+): SpecialtyDefaultsResolver {
+  return (specialty) => {
+    for (const ext of extensions) {
+      const defaults = ext.specialtyDefaults?.(specialty);
+      if (defaults) return defaults;
+    }
+    return undefined;
+  };
+}
+
 /** Mounts each contribution on root, in order. */
 export function mountRouteContributions(
   root: AnyHono,

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

@@ -9,6 +9,7 @@ import {
   applyOpenApiContributions,
   collectOpenApiContributions,
   collectServiceIntegrations,
+  collectSpecialtyDefaults,
   mountRouteContributions,
   renderAgentDetailCardSlots,
   renderAgentDetailCards,
@@ -530,3 +531,21 @@ describe("renderAgentDetailCardSlots", () => {
     expect(rendered).toBe(1);
   });
 });
+
+describe("collectSpecialtyDefaults", () => {
+  it("returns undefined with no extensions or hookless extensions", () => {
+    expect(collectSpecialtyDefaults([])("coding")).toBeUndefined();
+    expect(
+      collectSpecialtyDefaults([{ name: "bare" }])("coding"),
+    ).toBeUndefined();
+  });
+
+  it("returns the first extension's defaults that answers for the specialty", () => {
+    const resolve = collectSpecialtyDefaults([
+      { specialtyDefaults: (s) => (s === "a" ? { tools: ["A"] } : undefined) },
+      { specialtyDefaults: () => ({ tools: ["B"] }) },
+    ]);
+    expect(resolve("a")).toEqual({ tools: ["A"] });
+    expect(resolve("b")).toEqual({ tools: ["B"] });
+  });
+});

package/src/admin-local-agent.smoke.test.ts

@@ -1523,7 +1523,7 @@ describe("admin UI — account users create / delete agents (SSP-4.2)", () => {
     expect(res.status).toBe(403);
   });
 
-  it("POST /admin/agents — account user's agent is stamped with their account and forced to coding", async () => {
+  it("POST /admin/agents — account user's agent is stamped with their account and forced to the self-serve specialty", async () => {
     const { deps, created } = depsCapturingCreate("acct-a");
     const res = await createAdminUIApp(deps).request(
       "/admin/agents",

package/src/admin-ui-pages.ts

@@ -11,6 +11,7 @@
  */
 
 import { PROGRESS_LABELS } from "@app-vitals/agent-lib/progress-phases";
+import { getSelfServeSpecialty } from "./account-agent-create.ts";
 import { renderAdminPage } from "./admin-ui-layout.ts";
 import {
   BREAKPOINT_MOBILE_MAX,
@@ -18,7 +19,6 @@ import {
   renderAdminToolbar,
 } from "./admin-ui-styles.ts";
 import type { ManualStep } from "./agent-deletion-checklist.ts";
-import type { SpecialtyOption } from "./specialty-manifest-loader.ts";
 import { isAudioFilename } from "./attachment-validation.ts";
 import { parseChatMarkers } from "./chat-markers.ts";
 import type {
@@ -28,6 +28,7 @@ import type {
   ThreadStats,
 } from "./http-chat-client.ts";
 import { renderPushToggle } from "./push-toggle.ts";
+import type { SpecialtyOption } from "./specialty-manifest-loader.ts";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -79,7 +80,7 @@ export interface AgentDetail {
    * Rendered as a checkbox on both the create and edit forms.
    */
   restrictSlackToMembers: boolean;
-  /** The agent's type name (e.g. "coding"), resolved at creation time. */
+  /** The agent's type name (e.g. "specialist"), resolved at creation time. */
   specialty: string;
   /**
    * Required env keys declared by the agent's type manifest with no
@@ -487,7 +488,7 @@ export function renderNewLocalAgentPage(
     /**
      * Set for self-serve account users (SSP-4.2): shows the account's
      * remaining agent quota and the prerequisites, and pins the type to
-     * "coding" (the server forces it regardless).
+     * the self-serve specialty (the server forces it regardless).
      */
     selfServe?: { remaining: number; max: number; contactEmail: string };
   },
@@ -566,7 +567,7 @@ export function renderNewLocalAgentPage(
     </div>`
     : "";
   const typeFieldHtml = selfServe
-    ? `<input type="hidden" name="type" value="coding" />`
+    ? `<input type="hidden" name="type" value="${escapeHtml(getSelfServeSpecialty())}" />`
     : `<div class="form-group">
           <label class="form-label" for="type">Specialty <span style="color:#ef4444">*</span></label>
           <select id="type" name="type" class="form-input" required>

package/src/admin-ui-pages.unit.test.ts

@@ -6,7 +6,7 @@
  * No I/O, no Hono, no HTTP — pure string → string.
  */
 
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
 import { renderZeroQuotaNotice } from "./admin-ui-account-pages.ts";
 import {
   type AgentDetail,
@@ -4259,12 +4259,40 @@ describe("renderNewLocalAgentPage — self-serve account user (SSP-4.2)", () =>
     expect(html).toContain("Claude API key");
   });
 
-  test("forces the coding type via a hidden input instead of a type select", () => {
-    const html = renderNewLocalAgentPage(USER_NAME, [CODING_TYPE], {
-      selfServe,
+  describe("hidden type input", () => {
+    const saved = {
+      selfServe: process.env.SHIPWRIGHT_SELF_SERVE_AGENT_TYPE,
+      defaultType: process.env.SHIPWRIGHT_DEFAULT_AGENT_TYPE,
+    };
+    const restore = (key: string, value: string | undefined) => {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    };
+    afterEach(() => {
+      restore("SHIPWRIGHT_SELF_SERVE_AGENT_TYPE", saved.selfServe);
+      restore("SHIPWRIGHT_DEFAULT_AGENT_TYPE", saved.defaultType);
+    });
+
+    test("carries the SHIPWRIGHT_SELF_SERVE_AGENT_TYPE value instead of a type select", () => {
+      process.env.SHIPWRIGHT_SELF_SERVE_AGENT_TYPE = "base";
+      const html = renderNewLocalAgentPage(USER_NAME, [CODING_TYPE], {
+        selfServe,
+      });
+      expect(html).toContain('<input type="hidden" name="type" value="base"');
+      expect(html).not.toContain('name="type" value="coding"');
+      expect(html).not.toMatch(/<select[^>]*name="type"/);
+    });
+
+    test("falls back to the resolved default specialty when the env is unset", () => {
+      delete process.env.SHIPWRIGHT_SELF_SERVE_AGENT_TYPE;
+      delete process.env.SHIPWRIGHT_DEFAULT_AGENT_TYPE;
+      const html = renderNewLocalAgentPage(USER_NAME, [CODING_TYPE], {
+        selfServe,
+      });
+      expect(html).toContain(
+        '<input type="hidden" name="type" value="specialist"',
+      );
     });
-    expect(html).toContain('<input type="hidden" name="type" value="coding"');
-    expect(html).not.toMatch(/<select[^>]*name="type"/);
   });
 
   test("at zero remaining, explains the limit and points at the contact email", () => {

package/src/admin-ui.ts

@@ -78,6 +78,7 @@ import {
   type SpecialtyManifestResolver,
   SpecialtyRegistry,
 } from "./specialty-manifest-loader.ts";
+import type { SpecialtyDefaultsResolver } from "./specialty-defaults.ts";
 import type { AgentService } from "./agents.ts";
 import { createAgent, describeRepoNameCollision } from "./agents.ts";
 import { AnthropicCredentialsBlockedError } from "./anthropic-credential-guard.ts";
@@ -352,6 +353,8 @@ export interface AdminUIDeps {
    * already used by agents-api.ts's AdminDeps.
    */
   specialtyRegistry?: SpecialtyManifestResolver;
+  /** Extension-supplied specialty defaults, consulted before the manifest. */
+  specialtyDefaults?: SpecialtyDefaultsResolver;
   /**
    * Cleanup deps for the full delete-agent orchestration (POST
    * /admin/agents/:id/delete → deleteAgentFully()). Matches
@@ -782,6 +785,7 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
     accountCreatedNotifier,
     accountServices,
     specialtyRegistry = new SpecialtyRegistry(),
+    specialtyDefaults,
     callerScopeResolver = memberOnlyCallerScopeResolver(agentMemberService),
     serviceIntegrations,
     chatService,
@@ -1507,7 +1511,7 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
       return c.redirect("/admin/agents/new", 302);
     }
     const connectSlack = connectSlackRaw === "true";
-    // SSP-4.2: account users always create "coding" agents in their own
+    // SSP-4.2: account users always create self-serve-specialty agents in their own
     // account — any submitted type/accountId is ignored.
     if (accountId !== null) specialty = getSelfServeSpecialty();
     // Absent/unrecognized runtime means self-hosted — the historical behavior
@@ -1557,6 +1561,7 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
         agentCronJobService,
         provisioner,
         specialtyRegistry,
+        specialtyDefaults,
         anthropicFederationEnabled: deps.anthropicFederationEnabled,
       },
       {

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

@@ -11,6 +11,10 @@
 
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import type { PrismaClient } from "../prisma/client/client.ts";
+import {
+  type AdminExtension,
+  collectSpecialtyDefaults,
+} from "./admin-extension.ts";
 import { AgentCronJobService } from "./agent-cron-jobs.ts";
 import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
 import { createAdminPrismaClient } from "./prisma-client.ts";
@@ -581,3 +585,93 @@ describeOrSkip("AgentCronJobService (integration)", () => {
     expect(await service.list(agentId)).toEqual([]);
   });
 });
+
+// A fixture extension supplying defaults, wired the way admin-boot.ts does.
+const fixtureExtension: AdminExtension = {
+  name: "fixture",
+  specialtyDefaults: (specialty) =>
+    specialty === FIXTURE_TYPE
+      ? {
+          crons: [
+            {
+              name: "ext-loop",
+              schedule: "*/10 * * * *",
+              prompt: "/ext:loop",
+              enabled: true,
+            },
+            {
+              name: "ext-child",
+              schedule: "5 * * * *",
+              prompt: "/ext:child",
+              enabled: false,
+              parentCron: "ext-loop",
+            },
+          ],
+        }
+      : undefined,
+};
+
+describeOrSkip("AgentCronJobService specialtyDefaults (integration)", () => {
+  let prisma: PrismaClient;
+  let service: AgentCronJobService;
+
+  beforeEach(async () => {
+    prisma = makePrisma();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agent.deleteMany();
+    service = new AgentCronJobService(
+      prisma,
+      undefined,
+      fixtureResolver,
+      collectSpecialtyDefaults([fixtureExtension]),
+    );
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("reconcile seeds the extension's crons instead of the manifest's", async () => {
+    const agentId = await createAgent(prisma);
+    const result = await service.reconcileSystemCrons(agentId);
+    expect(result).toEqual({ created: 2, updated: 0, deleted: 0 });
+    const jobs = await service.list(agentId);
+    expect(jobs.map((j) => j.name).sort()).toEqual(["ext-child", "ext-loop"]);
+    const loop = jobs.find((j) => j.name === "ext-loop");
+    const child = jobs.find((j) => j.name === "ext-child");
+    expect(child?.parentCronId).toBe(loop?.id as string);
+    expect(child?.enabled).toBe(false);
+  });
+
+  it("re-reconcile keeps ids and enabled state and deletes orphaned system crons", async () => {
+    const agentId = await createAgent(prisma);
+    await service.reconcileSystemCrons(agentId);
+    const before = await service.list(agentId);
+    const loop = before.find((j) => j.name === "ext-loop");
+    await prisma.agentCronJob.update({
+      where: { id: loop?.id as string },
+      data: { enabled: false },
+    });
+    await prisma.agentCronJob.create({
+      data: {
+        agentId,
+        name: "stale-system",
+        system: true,
+        schedule: "* * * * *",
+        prompt: "x",
+      },
+    });
+
+    const result = await service.reconcileSystemCrons(agentId);
+
+    expect(result).toEqual({ created: 0, updated: 2, deleted: 1 });
+    const after = await service.list(agentId);
+    const loopAfter = after.find((j) => j.name === "ext-loop");
+    expect(loopAfter?.id).toBe(loop?.id as string);
+    expect(loopAfter?.enabled).toBe(false);
+    expect(after.some((j) => j.name === "stale-system")).toBe(false);
+  });
+});

package/src/agent-cron-jobs.ts

@@ -8,16 +8,17 @@
  */
 
 import type { AgentCronJob, PrismaClient } from "../prisma/client/client.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
+import type {
+  SpecialtyDefaultCron,
+  SpecialtyDefaultsResolver,
+} from "./specialty-defaults.ts";
 import {
   type SpecialtyManifestResolver,
   SpecialtyRegistry,
-  missingDefaultSpecialtyError,
-  resolveDefaultSpecialtyName,
-  resolveSpecialtiesDir,
 } from "./specialty-manifest-loader.ts";
 import type { SpecialtyManifest } from "./specialty-registry.ts";
-import { type Clock, SystemClock } from "./clock.ts";
-import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
 
 /**
  * The shape of a single cron template resolved from a specialty's manifest.
@@ -87,6 +88,7 @@ export class AgentCronJobService {
     private prisma: PrismaClient,
     private clock: Clock = SystemClock(),
     private specialtyRegistry: SpecialtyManifestResolver = new SpecialtyRegistry(),
+    private specialtyDefaults: SpecialtyDefaultsResolver = () => undefined,
   ) {}
 
   /**
@@ -443,11 +445,10 @@ export class AgentCronJobService {
    * The cron list is resolved from the agent's type manifest — the agent's
    * stored `specialty` is looked up via the injected SpecialtyRegistry's
    * `tryGetManifest()` (the parsed `specialties/{specialty}/manifest.yaml`),
-   * deliberately WITHOUT the "coding" fallback: a non-default type with no
-   * loadable manifest logs an error and reconciles nothing (no seeding of
-   * coding crons, no deletion of existing system crons), while a "coding"
-   * manifest that cannot load throws — the universal fallback failing is a
-   * startup bug. This replaced the former hardcoded
+   * deliberately WITHOUT the default-type fallback: any type (the default
+   * included) with no loadable manifest logs an error and reconciles nothing
+   * (no seeding of another type's crons, no deletion of existing system
+   * crons). This replaced the former hardcoded
    * SYSTEM_CRONS array as the source of truth (ATS-3.2).
    *
    * Two passes so parent/child links resolve regardless of the manifest's
@@ -483,9 +484,9 @@ export class AgentCronJobService {
   async reconcileSystemCrons(
     agentId: string,
   ): Promise<{ created: number; updated: number; deleted: number }> {
-    // Resolve the agent's type manifest → its declared cron list. No "coding"
-    // fallback: seeding enabled coding crons on a non-coding agent is worse
-    // than leaving its crons untouched.
+    // Resolve the agent's type manifest → its declared cron list. No default-type
+    // fallback: seeding another type's crons on an agent is worse than
+    // leaving its crons untouched.
     const agent = await this.prisma.agent.findUnique({
       where: { id: agentId },
       select: { specialty: true },
@@ -494,22 +495,19 @@ export class AgentCronJobService {
       throw new NotFoundError(`agent ${agentId} not found`);
     }
     const { specialty } = agent;
-    const manifest = this.specialtyRegistry.tryGetManifest(specialty);
-    if (!manifest) {
-      const defaultName = resolveDefaultSpecialtyName();
-      if (specialty === defaultName) {
-        throw missingDefaultSpecialtyError(
-          defaultName,
-          resolveSpecialtiesDir(),
-          new Error(`reconcileSystemCrons for agent ${agentId}`),
-        );
-      }
+    // Extension-supplied crons win; the manifest is the fallback.
+    const extensionCrons = this.specialtyDefaults(specialty)?.crons;
+    const manifest = extensionCrons
+      ? undefined
+      : this.specialtyRegistry.tryGetManifest(specialty);
+    if (!extensionCrons && !manifest) {
       console.error(
         `reconcileSystemCrons: no loadable manifest for specialty "${specialty}" (agent ${agentId}) — leaving crons untouched`,
       );
       return { created: 0, updated: 0, deleted: 0 };
     }
-    const manifestCrons: readonly ManifestCron[] = manifest.crons;
+    const manifestCrons: readonly (ManifestCron | SpecialtyDefaultCron)[] =
+      extensionCrons ?? manifest?.crons ?? [];
 
     // Fetch all existing system crons for this agent
     const existingSystemCrons = await this.prisma.agentCronJob.findMany({
@@ -566,7 +564,7 @@ export class AgentCronJobService {
               preCheck: systemCron.preCheck ?? null,
               channel: null,
               user: null,
-              enabled: systemCron.enabled,
+              enabled: systemCron.enabled ?? true,
             },
           });
           idByName.set(systemCron.name, createdCron.id);