@app-vitals/agent-admin 0.12.0 → 0.13.1

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

@@ -72,12 +72,13 @@ const fixtureManifest = {
 
 /** Resolves only FIXTURE_TYPE; every other type is unknown. */
 const fixtureResolver: SpecialtyManifestResolver = {
-  getManifest(typeName: string): SpecialtyManifest {
-    if (typeName !== FIXTURE_TYPE) throw new Error(`no manifest: ${typeName}`);
+  getManifest(specialty: string): SpecialtyManifest {
+    if (specialty !== FIXTURE_TYPE)
+      throw new Error(`no manifest: ${specialty}`);
     return fixtureManifest;
   },
-  tryGetManifest(typeName: string): SpecialtyManifest | undefined {
-    return typeName === FIXTURE_TYPE ? fixtureManifest : undefined;
+  tryGetManifest(specialty: string): SpecialtyManifest | undefined {
+    return specialty === FIXTURE_TYPE ? fixtureManifest : undefined;
   },
   listTypes() {
     return [{ name: FIXTURE_TYPE, displayName: FIXTURE_TYPE }];
@@ -87,9 +88,9 @@ const fixtureResolver: SpecialtyManifestResolver = {
 async function createAgent(
   prisma: PrismaClient,
   name = "Test Agent",
-  typeName = FIXTURE_TYPE,
+  specialty = FIXTURE_TYPE,
 ): Promise<string> {
-  const agent = await prisma.agent.create({ data: { name, typeName } });
+  const agent = await prisma.agent.create({ data: { name, specialty } });
   return agent.id;
 }
 
@@ -570,7 +571,7 @@ describeOrSkip("AgentCronJobService (integration)", () => {
     expect(systemJobs.length).toBe(FIXTURE_CRONS.length);
   });
 
-  it("reconcileSystemCrons() for an unknown typeName changes nothing (no fallback)", async () => {
+  it("reconcileSystemCrons() for an unknown specialty changes nothing (no fallback)", async () => {
     const agentId = await createAgent(prisma, "Renamed Agent", "renamed-type");
 
     // Must not throw, and must not seed another specialty's crons.

package/src/agent-cron-jobs.ts

@@ -17,7 +17,6 @@ import {
 } from "./specialty-manifest-loader.ts";
 import type { SpecialtyManifest } from "./specialty-registry.ts";
 import { type Clock, SystemClock } from "./clock.ts";
-import { resolveSpecialty } from "./agent-specialty.ts";
 import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
 
 /**
@@ -442,8 +441,8 @@ export class AgentCronJobService {
    * Reconcile system crons for the given agent.
    *
    * The cron list is resolved from the agent's type manifest — the agent's
-   * stored `typeName` is looked up via the injected SpecialtyRegistry's
-   * `tryGetManifest()` (the parsed `specialties/{typeName}/manifest.yaml`),
+   * 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"
@@ -489,12 +488,12 @@ export class AgentCronJobService {
     // than leaving its crons untouched.
     const agent = await this.prisma.agent.findUnique({
       where: { id: agentId },
-      select: { typeName: true, specialty: true },
+      select: { specialty: true },
     });
     if (!agent) {
       throw new NotFoundError(`agent ${agentId} not found`);
     }
-    const specialty = resolveSpecialty(agent);
+    const { specialty } = agent;
     const manifest = this.specialtyRegistry.tryGetManifest(specialty);
     if (!manifest) {
       const defaultName = resolveDefaultSpecialtyName();

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

@@ -69,15 +69,15 @@ function fakeRegistry(
   const lookups: string[] = [];
   return {
     lookups,
-    getManifest(typeName: string): SpecialtyManifest {
-      lookups.push(typeName);
-      const crons = byType[typeName] ?? byType[fallbackType];
-      if (!crons) throw new Error(`no manifest for ${typeName}`);
+    getManifest(specialty: string): SpecialtyManifest {
+      lookups.push(specialty);
+      const crons = byType[specialty] ?? byType[fallbackType];
+      if (!crons) throw new Error(`no manifest for ${specialty}`);
       return manifestWithCrons(crons);
     },
-    tryGetManifest(typeName: string): SpecialtyManifest | undefined {
-      lookups.push(typeName);
-      const crons = byType[typeName];
+    tryGetManifest(specialty: string): SpecialtyManifest | undefined {
+      lookups.push(specialty);
+      const crons = byType[specialty];
       return crons ? manifestWithCrons(crons) : undefined;
     },
     listTypes() {
@@ -90,12 +90,12 @@ type FakeCronRow = AgentCronJob;
 
 /**
  * In-memory prisma double covering only what reconcileSystemCrons() touches:
- *   agent.findUnique (typeName resolution),
+ *   agent.findUnique (specialty resolution),
  *   agentCronJob.findMany, and a $transaction exposing
  *   agentCronJob.{create,update,delete}.
  */
 function makeFakePrisma(opts: {
-  typeName: string;
+  specialty: string;
   existing?: Partial<FakeCronRow>[];
 }) {
   let nextId = 1;
@@ -193,8 +193,8 @@ function makeFakePrisma(opts: {
       where,
     }: {
       where: { id: string };
-    }): Promise<{ typeName: string } | null> {
-      return where.id === "agent-1" ? { typeName: opts.typeName } : null;
+    }): Promise<{ specialty: string } | null> {
+      return where.id === "agent-1" ? { specialty: opts.specialty } : null;
     },
   };
 
@@ -229,9 +229,9 @@ const childCron: ManifestCron = {
 };
 
 describe("reconcileSystemCrons (unit, injected registry)", () => {
-  test("resolves the agent's typeName via the injected registry", async () => {
+  test("resolves the agent's specialty via the injected registry", async () => {
     const registry = fakeRegistry({ coding: [loopCron] });
-    const { prisma } = makeFakePrisma({ typeName: "coding" });
+    const { prisma } = makeFakePrisma({ specialty: "coding" });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
@@ -245,7 +245,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
 
   test("creates one row per manifest cron on a fresh agent", async () => {
     const registry = fakeRegistry({ coding: [loopCron, childCron] });
-    const { prisma, rows } = makeFakePrisma({ typeName: "coding" });
+    const { prisma, rows } = makeFakePrisma({ specialty: "coding" });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
@@ -265,7 +265,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
 
   test("links a child cron to its parent on first reconcile", async () => {
     const registry = fakeRegistry({ coding: [childCron, loopCron] });
-    const { prisma, rows } = makeFakePrisma({ typeName: "coding" });
+    const { prisma, rows } = makeFakePrisma({ specialty: "coding" });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
@@ -284,7 +284,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
   test("updates a matching existing row in place, preserving its id", async () => {
     const registry = fakeRegistry({ coding: [loopCron] });
     const { prisma, rows } = makeFakePrisma({
-      typeName: "coding",
+      specialty: "coding",
       existing: [{ id: "stable-id", name: "shipwright-loop", enabled: false }],
     });
     const service = new AgentCronJobService(
@@ -303,7 +303,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
   test("orphan pass deletes a system cron absent from the manifest", async () => {
     const registry = fakeRegistry({ coding: [loopCron] });
     const { prisma, rows } = makeFakePrisma({
-      typeName: "coding",
+      specialty: "coding",
       existing: [{ id: "orphan", name: "removed-cron" }],
     });
     const service = new AgentCronJobService(
@@ -321,7 +321,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
   test("clears a stale parentCronId when the entry no longer declares a resolvable parent", async () => {
     const registry = fakeRegistry({ coding: [loopCron] });
     const { prisma, rows } = makeFakePrisma({
-      typeName: "coding",
+      specialty: "coding",
       existing: [
         {
           id: "loop-id",
@@ -341,10 +341,10 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
     expect(rows.get("loop-id")?.parentCronId).toBeNull();
   });
 
-  test("an unknown non-coding typeName logs an error and changes nothing", async () => {
+  test("an unknown non-coding specialty logs an error and changes nothing", async () => {
     const registry = fakeRegistry({ coding: [loopCron] });
     const { prisma, rows } = makeFakePrisma({
-      typeName: "specialist",
+      specialty: "specialist",
       existing: [
         { id: "sys-1", name: "old-system", system: true },
         { id: "user-1", name: "mine", system: false },
@@ -377,7 +377,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
   test("the default manifest that cannot load still throws", async () => {
     const registry = fakeRegistry({});
     const { prisma } = makeFakePrisma({
-      typeName: resolveDefaultSpecialtyName(),
+      specialty: resolveDefaultSpecialtyName(),
     });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
@@ -393,7 +393,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
   test("the default-manifest failure names the env vars that configure it", async () => {
     const registry = fakeRegistry({});
     const { prisma } = makeFakePrisma({
-      typeName: resolveDefaultSpecialtyName(),
+      specialty: resolveDefaultSpecialtyName(),
     });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
@@ -408,7 +408,7 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
 
   test("a valid non-coding manifest reconciles normally", async () => {
     const registry = fakeRegistry({ specialist: [loopCron] });
-    const { prisma, rows } = makeFakePrisma({ typeName: "specialist" });
+    const { prisma, rows } = makeFakePrisma({ specialty: "specialist" });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,

package/src/agent-patch-author-allowlist.integration.test.ts

@@ -87,11 +87,11 @@ const CODING_MANIFEST: SpecialtyManifest = {
 function fakeSpecialtyRegistry(): SpecialtyManifestResolver {
   const byType: Record<string, SpecialtyManifest> = { coding: CODING_MANIFEST };
   return {
-    getManifest(typeName: string): SpecialtyManifest {
-      return byType[typeName] ?? (byType.coding as SpecialtyManifest);
+    getManifest(specialty: string): SpecialtyManifest {
+      return byType[specialty] ?? (byType.coding as SpecialtyManifest);
     },
-    tryGetManifest(typeName: string): SpecialtyManifest | undefined {
-      return byType[typeName];
+    tryGetManifest(specialty: string): SpecialtyManifest | undefined {
+      return byType[specialty];
     },
     listTypes() {
       return Object.entries(byType).map(([name, manifest]) => ({

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

@@ -0,0 +1,126 @@
+/**
+ * admin/src/agent-specialty-backfill.integration.test.ts
+ * Migration-ordering test for the typeName -> specialty rename
+ * (AGR-6.1 ADD, AGR-6.3 REMOVE).
+ *
+ * After AGR-6.3 the live test database no longer has an "Agent"."typeName"
+ * column, so this test cannot seed the pre-drop state through Prisma. Instead
+ * it replays the real migration files, in order, against a skeleton "Agent"
+ * table inside a throwaway Postgres schema:
+ *
+ *   20260724000000_add_agent_type_name   adds typeName NOT NULL DEFAULT 'coding'
+ *   20261029000000_add_agent_specialty   adds nullable specialty + backfill
+ *   20261030000000_drop_agent_type_name  backfills stragglers, specialty NOT NULL,
+ *                                        drops typeName
+ *
+ * Seeded from the live distinct values (admin API, 2026-10-27): coding
+ * (11 agents) and specialist (1 agent). A row written between the AGR-6.1
+ * backfill and the AGR-6.3 migration (specialty still NULL) must be
+ * backfilled from typeName by the drop migration.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { Client } from "pg";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+const LIVE_SPECIALTIES = ["coding", "specialist"] as const;
+
+function migrationSql(dir: string): string {
+  return readFileSync(
+    new URL(`../prisma/migrations/${dir}/migration.sql`, import.meta.url),
+    "utf8",
+  );
+}
+
+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");
+
+describeOrSkip("typeName -> specialty migrations (AGR-6.1 / AGR-6.3)", () => {
+  const schema = `agr63_${process.pid}_${Date.now()}`;
+  let client: Client;
+
+  const columns = async (): Promise<string[]> =>
+    (
+      await client.query<{ column_name: string }>(
+        `SELECT column_name FROM information_schema.columns
+         WHERE table_schema = $1 AND table_name = 'Agent'`,
+        [schema],
+      )
+    ).rows.map((r) => r.column_name);
+
+  beforeEach(async () => {
+    client = new Client({ connectionString: TEST_DB as string });
+    await client.connect();
+    await client.query(`CREATE SCHEMA "${schema}"`);
+    await client.query(`SET search_path TO "${schema}"`);
+    await client.query(
+      `CREATE TABLE "Agent" ("id" TEXT PRIMARY KEY, "name" TEXT NOT NULL)`,
+    );
+  });
+
+  afterEach(async () => {
+    await client.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`);
+    await client.end();
+  });
+
+  it("add_agent_specialty backfills specialty from typeName and leaves it nullable", async () => {
+    await client.query(ADD_TYPE_NAME);
+    for (const [i, s] of LIVE_SPECIALTIES.entries()) {
+      await client.query(
+        `INSERT INTO "Agent" ("id","name","typeName") VALUES ($1,$2,$3)`,
+        [`a${i}`, `agent-${i}`, s],
+      );
+    }
+    await client.query(ADD_SPECIALTY);
+
+    const { rows } = await client.query<{ specialty: string | null }>(
+      `SELECT "specialty" FROM "Agent" ORDER BY "id"`,
+    );
+    expect(rows.map((r) => r.specialty)).toEqual([...LIVE_SPECIALTIES]);
+  });
+
+  it("drop_agent_type_name backfills NULL specialty, makes it required and drops typeName", async () => {
+    await client.query(ADD_TYPE_NAME);
+    await client.query(ADD_SPECIALTY);
+    // Rows written after the AGR-6.1 backfill: one with specialty set, one
+    // straggler with specialty NULL and a non-default typeName.
+    await client.query(
+      `INSERT INTO "Agent" ("id","name","typeName","specialty")
+       VALUES ('a0','agent-0','coding','coding')`,
+    );
+    await client.query(
+      `INSERT INTO "Agent" ("id","name","typeName") VALUES ('a1','agent-1','specialist')`,
+    );
+
+    await client.query(DROP_TYPE_NAME);
+
+    expect(await columns()).not.toContain("typeName");
+    const { rows } = await client.query<{ id: string; specialty: string }>(
+      `SELECT "id","specialty" FROM "Agent" ORDER BY "id"`,
+    );
+    expect(rows).toEqual([
+      { id: "a0", specialty: "coding" },
+      { id: "a1", specialty: "specialist" },
+    ]);
+
+    // specialty is now NOT NULL with a 'coding' default.
+    await expect(
+      client.query(
+        `INSERT INTO "Agent" ("id","name","specialty") VALUES ('a2','agent-2',NULL)`,
+      ),
+    ).rejects.toThrow();
+    await client.query(
+      `INSERT INTO "Agent" ("id","name") VALUES ('a3','agent-3')`,
+    );
+    const def = await client.query<{ specialty: string }>(
+      `SELECT "specialty" FROM "Agent" WHERE "id" = 'a3'`,
+    );
+    expect(def.rows[0]?.specialty).toBe("coding");
+  });
+});

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

@@ -104,18 +104,18 @@ const CODING_MANIFEST: SpecialtyManifest = {
 
 /**
  * Fake SpecialtyManifestResolver — resolves a fixed map of manifests by
- * typeName. tryGetManifest() returns undefined (no fallback) for anything
+ * specialty. tryGetManifest() returns undefined (no fallback) for anything
  * not in the map, mirroring SpecialtyRegistry's real contract.
  */
 function fakeSpecialtyRegistry(
   byType: Record<string, SpecialtyManifest> = { coding: CODING_MANIFEST },
 ): SpecialtyManifestResolver {
   return {
-    getManifest(typeName: string): SpecialtyManifest {
-      return byType[typeName] ?? (byType.coding as SpecialtyManifest);
+    getManifest(specialty: string): SpecialtyManifest {
+      return byType[specialty] ?? (byType.coding as SpecialtyManifest);
     },
-    tryGetManifest(typeName: string): SpecialtyManifest | undefined {
-      return byType[typeName];
+    tryGetManifest(specialty: string): SpecialtyManifest | undefined {
+      return byType[specialty];
     },
     listTypes() {
       return Object.entries(byType).map(([name, manifest]) => ({
@@ -309,9 +309,9 @@ describeOrSkip("admin CRUD API (integration)", () => {
     expect(listedToken.id).toBe(dbRecord?.id);
   });
 
-  // ─── typeName field ─────────────────────────────────────────────────────────
+  // ─── specialty field ─────────────────────────────────────────────────────────
 
-  it("GET /agents includes typeName:'coding' for an agent created before typeName existed", async () => {
+  it("GET /agents includes specialty:'coding' for an agent created before specialty existed", async () => {
     const res = await app.request("/agents", {
       headers: { Cookie: `admin_session=${cookie}` },
     });
@@ -319,30 +319,30 @@ 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.typeName).toBe("coding");
+    expect(entry.specialty).toBe("coding");
   });
 
-  it("GET /agents/:id includes typeName:'coding' by default", async () => {
+  it("GET /agents/:id includes specialty:'coding' 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.typeName).toBe("coding");
+    expect(body.specialty).toBe("coding");
   });
 
   // ─── 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 typeName column was
-  // added (never received an explicit value) must read back typeName="coding"
+  // migration must handle: rows that existed *before* the specialty column was
+  // added (never received an explicit value) must read back specialty="coding"
   // 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 typeName='coding' and child rows (cron/plugin/tool/env/member) are untouched", async () => {
+  it("migration backfill: pre-existing agent rows read back specialty='coding' 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 typeName migration landing.
+    // simulating data that existed prior to the specialty migration landing.
     const preExisting = await prisma.agent.create({
       data: { name: "Pre-Existing Agent" },
     });
@@ -379,11 +379,11 @@ describeOrSkip("admin CRUD API (integration)", () => {
 
     // Read back via the raw Agent row (bypasses the API layer entirely) —
     // this is the direct DB-level assertion that the column DEFAULT applies
-    // to a row that never set typeName explicitly.
+    // to a row that never set specialty explicitly.
     const rawAgent = await prisma.agent.findUniqueOrThrow({
       where: { id: preExisting.id },
     });
-    expect(rawAgent.typeName).toBe("coding");
+    expect(rawAgent.specialty).toBe("coding");
 
     // 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.typeName).toBe("coding");
+    expect(body.specialty).toBe("coding");
 
     // Child row counts are unchanged — exactly one of each, still linked to
     // the same agent.
@@ -411,7 +411,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
       await prisma.agentMember.count({ where: { agentId: preExisting.id } }),
     ).toBe(1);
 
-    // Child row updatedAt values are unchanged — the typeName column only
+    // Child row updatedAt values are unchanged — the specialty column only
     // touches the Agent table, so nothing here should have been rewritten.
     const cronAfter = await prisma.agentCronJob.findUniqueOrThrow({
       where: { id: cron.id },
@@ -438,7 +438,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
     expect(memberAfter.createdAt.getTime()).toBe(member.createdAt.getTime());
   });
 
-  it("prisma migrate deploy is idempotent — running it twice does not error or duplicate the typeName column", async () => {
+  it("prisma migrate deploy is idempotent — running it twice does not error or duplicate the specialty column", async () => {
     // The migration has already been applied once (this test DB was
     // provisioned via `prisma migrate deploy` before the suite ran). Re-run
     // deploy here and confirm the column is still readable with a single,
@@ -455,7 +455,7 @@ describeOrSkip("admin CRUD API (integration)", () => {
     const rawAgent = await prisma.agent.findUniqueOrThrow({
       where: { id: agentId },
     });
-    expect(rawAgent.typeName).toBe("coding");
+    expect(rawAgent.specialty).toBe("coding");
   });
 
   // ─── repos field round-trip ───────────────────────────────────────────────────