@app-vitals/agent-admin 1.2.7 → 1.3.0

package/openapi.json

@@ -340,6 +340,11 @@
             "type": "boolean",
             "example": false
           },
+          "specialty": {
+            "type": "string",
+            "minLength": 1,
+            "example": "specialist"
+          },
           "repos": {
             "type": "array",
             "items": {
@@ -3568,7 +3573,7 @@
       },
       "patch": {
         "summary": "Update an agent",
-        "description": "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` and `trialExpiryWarnedAt` are not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
+        "description": "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` (platform admin only — 403 otherwise; 422 when the type is unknown; a no-op when unchanged; otherwise persists the new type, reconciles the agent's system crons against it — system crons the new type does not declare are deleted, user crons survive — and reconciles the workload of in-cluster agents so the pod runs the image mapped to the new specialty). `trialExpiryWarnedAt` is not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
         "parameters": [
           {
             "schema": {
@@ -3641,7 +3646,7 @@
             }
           },
           "422": {
-            "description": "podServiceAccountName supplied for an agent with a per-agent federated identity",
+            "description": "podServiceAccountName supplied for an agent with a per-agent federated identity, or `specialty` naming an unknown type",
             "content": {
               "application/json": {
                 "schema": {

package/openapi.platform.json

@@ -340,6 +340,11 @@
             "type": "boolean",
             "example": false
           },
+          "specialty": {
+            "type": "string",
+            "minLength": 1,
+            "example": "specialist"
+          },
           "repos": {
             "type": "array",
             "items": {
@@ -3396,7 +3401,7 @@
       },
       "patch": {
         "summary": "Update an agent",
-        "description": "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` and `trialExpiryWarnedAt` are not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
+        "description": "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` (platform admin only — 403 otherwise; 422 when the type is unknown; a no-op when unchanged; otherwise persists the new type, reconciles the agent's system crons against it — system crons the new type does not declare are deleted, user crons survive — and reconciles the workload of in-cluster agents so the pod runs the image mapped to the new specialty). `trialExpiryWarnedAt` is not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
         "parameters": [
           {
             "schema": {
@@ -3469,7 +3474,7 @@
             }
           },
           "422": {
-            "description": "podServiceAccountName supplied for an agent with a per-agent federated identity",
+            "description": "podServiceAccountName supplied for an agent with a per-agent federated identity, or `specialty` naming an unknown type",
             "content": {
               "application/json": {
                 "schema": {

package/package.json

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

package/src/agent-account-assignment.ts

@@ -31,6 +31,18 @@ export function reconcileAgentAfterAccountChange(
   return reconcileAgentWorkload(provisioner, agent, "account updated");
 }
 
+/**
+ * SAL-1.2: reconciles the workload after the agent's specialty changed, so the
+ * pod is recreated on the image mapped to the new specialty (the target
+ * carries `agent.specialty`, which must be the post-update value).
+ */
+export function reconcileAgentAfterSpecialtyChange(
+  provisioner: Pick<AgentProvisioner, "reconcile">,
+  agent: ReconcilableAgent,
+): Promise<string | undefined> {
+  return reconcileAgentWorkload(provisioner, agent, "specialty updated");
+}
+
 /**
  * COS-49.1: reconciles the workload after podServiceAccountName changed.
  * `previous` is the column value before the update; the provisioner uses it to

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

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "bun:test";
-import { reconcileAgentAfterAccountChange } from "./agent-account-assignment.ts";
+import {
+  reconcileAgentAfterAccountChange,
+  reconcileAgentAfterSpecialtyChange,
+} from "./agent-account-assignment.ts";
 
 interface Result {
   recreated: string[];
@@ -97,3 +100,34 @@ describe("reconcileAgentAfterAccountChange", () => {
     expect(await reconcileAgentAfterAccountChange(p, agent)).toContain("boom");
   });
 });
+
+describe("reconcileAgentAfterSpecialtyChange", () => {
+  it("reconciles the workload with the new specialty", async () => {
+    const p = makeProvisioner();
+    expect(
+      await reconcileAgentAfterSpecialtyChange(p, {
+        ...agent,
+        specialty: "specialist",
+      }),
+    ).toBeUndefined();
+    expect(p.calls[0]?.[0]).toMatchObject({
+      id: "a1",
+      specialty: "specialist",
+    });
+  });
+
+  it("skips self-hosted agents", async () => {
+    const p = makeProvisioner();
+    await reconcileAgentAfterSpecialtyChange(p, { ...agent, selfHosted: true });
+    expect(p.calls).toEqual([]);
+  });
+
+  it("returns a warning when the reconcile throws", async () => {
+    const p = makeProvisioner(async () => {
+      throw new Error("boom");
+    });
+    expect(await reconcileAgentAfterSpecialtyChange(p, agent)).toContain(
+      "specialty updated",
+    );
+  });
+});

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

@@ -6287,3 +6287,201 @@ describe("chat-credentials routes", () => {
     expect(minted).toEqual([]);
   });
 });
+
+// ─── SAL-1.2: PATCH /agents/:id specialty ────────────────────────────────────
+
+describe("admin API — PATCH /agents/:id specialty (SAL-1.2)", () => {
+  const patch = (
+    app: ReturnType<typeof createAdminApp>,
+    body: unknown,
+    headers: Record<string, string>,
+  ) =>
+    app.request(`/agents/${AGENT_ID}`, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+      headers: { "Content-Type": "application/json", ...headers },
+    });
+
+  function depsFor(opts: {
+    provisioner: RecordingProvisioner;
+    events: string[];
+    failCrons?: boolean;
+  }): AdminDeps {
+    const base = makeMockDeps();
+    return {
+      ...base,
+      provisioner: opts.provisioner,
+      specialtyRegistry: fakeSpecialtyTypes({
+        coding: CODING_TYPE,
+        specialist: CODING_TYPE,
+      }),
+      agentService: {
+        ...base.agentService,
+        updateSelfHosted: async (id, input) => {
+          opts.events.push("write");
+          return {
+            ...(await base.agentService.updateSelfHosted(id, input)),
+            specialty: (input as { specialty?: string }).specialty ?? "coding",
+          };
+        },
+      },
+      agentCronJobService: {
+        ...base.agentCronJobService,
+        reconcileSystemCrons: async () => {
+          opts.events.push("crons");
+          if (opts.failCrons) throw new Error("cron boom");
+          return { created: 0, updated: 0, deleted: 0 };
+        },
+      },
+    };
+  }
+
+  it("platform admin changes specialty: write, then crons, then workload reconcile", async () => {
+    const events: string[] = [];
+    const provisioner = new RecordingProvisioner();
+    const origReconcile = provisioner.reconcile.bind(provisioner);
+    provisioner.reconcile = async (agents, o) => {
+      events.push("workload");
+      return origReconcile(agents, o);
+    };
+    const app = createAdminApp(depsFor({ provisioner, events }));
+    const cookie = await makeSessionCookie();
+    const infos: string[] = [];
+    const origInfo = console.info;
+    console.info = (...a: unknown[]) => {
+      infos.push(a.join(" "));
+    };
+    let res: Response;
+    try {
+      res = await patch(
+        app,
+        { specialty: "specialist" },
+        { Cookie: `admin_session=${cookie}` },
+      );
+    } finally {
+      console.info = origInfo;
+    }
+    expect(res.status).toBe(200);
+    expect((await res.json()).specialty).toBe("specialist");
+    expect(events).toEqual(["write", "crons", "workload"]);
+    expect(provisioner.reconciled.map((r) => r.specialty)).toEqual([
+      "specialist",
+    ]);
+    const audit = infos.filter((l) => l.includes("specialty changed"));
+    expect(audit).toHaveLength(1);
+    expect(audit[0]).toContain(AGENT_ID);
+    expect(audit[0]).toContain("old=coding");
+    expect(audit[0]).toContain("new=specialist");
+    expect(audit[0]).toContain("caller=");
+  });
+
+  it("returns 403 for a non-admin session member and changes nothing", async () => {
+    const events: string[] = [];
+    const provisioner = new RecordingProvisioner();
+    const app = createAdminApp({
+      ...depsFor({ provisioner, events }),
+      callerScopeResolver: async () => ({
+        kind: "scoped",
+        accountId: "acct-a",
+        agentIds: [AGENT_ID],
+      }),
+    });
+    const cookie = await sign(
+      {
+        isAdmin: false,
+        userId: "user-acct",
+        email: "owner@acct-a.example.com",
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+      },
+      SESSION_SECRET,
+      "HS256",
+    );
+    const res = await patch(
+      app,
+      { specialty: "specialist" },
+      { Cookie: `admin_session=${cookie}` },
+    );
+    expect(res.status).toBe(403);
+    expect(events).toEqual([]);
+    expect(provisioner.reconciled).toEqual([]);
+  });
+
+  it("returns 422 for an unknown specialty and changes nothing", async () => {
+    const events: string[] = [];
+    const provisioner = new RecordingProvisioner();
+    const app = createAdminApp(depsFor({ provisioner, events }));
+    const cookie = await makeSessionCookie();
+    const res = await patch(
+      app,
+      { specialty: "no-such-type" },
+      { Cookie: `admin_session=${cookie}` },
+    );
+    expect(res.status).toBe(422);
+    expect(events).toEqual([]);
+    expect(provisioner.reconciled).toEqual([]);
+  });
+
+  it("is a no-op for the current specialty: 200, no reconcile, no log", async () => {
+    const events: string[] = [];
+    const provisioner = new RecordingProvisioner();
+    const app = createAdminApp(depsFor({ provisioner, events }));
+    const cookie = await makeSessionCookie();
+    const infos: string[] = [];
+    const origInfo = console.info;
+    console.info = (...a: unknown[]) => {
+      infos.push(a.join(" "));
+    };
+    let res: Response;
+    try {
+      res = await patch(
+        app,
+        { specialty: "coding" },
+        { Cookie: `admin_session=${cookie}` },
+      );
+    } finally {
+      console.info = origInfo;
+    }
+    expect(res.status).toBe(200);
+    expect(events).not.toContain("crons");
+    expect(provisioner.reconciled).toEqual([]);
+    expect(infos.filter((l) => l.includes("specialty changed"))).toEqual([]);
+  });
+
+  it("returns a reconcile failure in `warning` instead of a 5xx", async () => {
+    const events: string[] = [];
+    const provisioner = new RecordingProvisioner();
+    const app = createAdminApp(depsFor({ provisioner, events }));
+    const cookie = await makeSessionCookie();
+    provisioner.reconcileResult = {
+      ...provisioner.reconcileResult,
+      failed: [{ agentId: AGENT_ID, error: "k8s down" }],
+    };
+    const res = await patch(
+      app,
+      { specialty: "specialist" },
+      { Cookie: `admin_session=${cookie}` },
+    );
+    expect(res.status).toBe(200);
+    expect((await res.json()).warning).toContain("k8s down");
+  });
+
+  it("returns a cron reconcile failure in `warning` and still reconciles the workload", async () => {
+    const events: string[] = [];
+    const provisioner = new RecordingProvisioner();
+    const app = createAdminApp(
+      depsFor({ provisioner, events, failCrons: true }),
+    );
+    const cookie = await makeSessionCookie();
+    const res = await patch(
+      app,
+      { specialty: "specialist" },
+      { Cookie: `admin_session=${cookie}` },
+    );
+    expect(res.status).toBe(200);
+    expect((await res.json()).warning).toContain("cron boom");
+    expect(provisioner.reconciled.map((r) => r.specialty)).toEqual([
+      "specialist",
+    ]);
+  });
+});

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

@@ -0,0 +1,217 @@
+/**
+ * admin/src/agents-api.specialty.integration.test.ts
+ * SAL-1.2: PATCH /agents/:id { specialty } against a real PostgreSQL DB.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { sign } from "hono/jwt";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { AgentChatTokenService } from "./agent-chat-tokens.ts";
+import { AgentCronJobService } from "./agent-cron-jobs.ts";
+import { AgentCronRunStatsService } from "./agent-cron-run-stats.ts";
+import { AgentCronRunService } from "./agent-cron-runs.ts";
+import { AgentEnvService } from "./agent-envs.ts";
+import { AgentGitHubInstallationsService } from "./agent-github-installations.ts";
+import { AgentMemberService } from "./agent-members.ts";
+import { AgentPluginService } from "./agent-plugins.ts";
+import type {
+  AgentProvisioner,
+  ReconcileResult,
+  ReconcileTarget,
+} from "./agent-provisioner.ts";
+import { NoopAgentProvisioner } from "./agent-provisioner.ts";
+import { AgentTokenService } from "./agent-tokens.ts";
+import { AgentToolService } from "./agent-tools.ts";
+import { AgentService } from "./agents.ts";
+import type { AdminDeps } from "./agents-api.ts";
+import { createAdminApp } from "./agents-api.ts";
+import { NoopChatServiceProvisioningClient } from "./chat-service-provisioning-client.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+import { SpecialtyTypes } from "./specialty-types.ts";
+import { makeTokenCrypto } from "./token-crypto.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+const SESSION_SECRET = "test-admin-session-secret-32-bytes!";
+const REAL_KEY =
+  "0000000000000000000000000000000000000000000000000000000000000001";
+
+async function makeSessionCookie(): Promise<string> {
+  return sign(
+    {
+      isAdmin: true,
+      userId: "user-123",
+      email: "admin@example.com",
+      name: "Admin User",
+      iat: Math.floor(Date.now() / 1000),
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    },
+    SESSION_SECRET,
+    "HS256",
+  );
+}
+
+/** Injected provisioner double that records every reconcile target. */
+class RecordingProvisioner extends NoopAgentProvisioner {
+  readonly reconciled: ReconcileTarget[] = [];
+  override async reconcile(
+    agents: ReconcileTarget[],
+  ): Promise<ReconcileResult> {
+    this.reconciled.push(...agents);
+    return {
+      recreated: [],
+      migrated: [],
+      noOwner: [],
+      dryRun: false,
+      updated: [],
+      orphans: [],
+      failed: [],
+    };
+  }
+}
+
+function makeDeps(
+  prisma: PrismaClient,
+  provisioner: AgentProvisioner,
+): AdminDeps {
+  const saved = process.env.SHIPWRIGHT_ENCRYPTION_KEY;
+  process.env.SHIPWRIGHT_ENCRYPTION_KEY = REAL_KEY;
+  const crypto = makeTokenCrypto();
+  if (saved === undefined) delete process.env.SHIPWRIGHT_ENCRYPTION_KEY;
+  else process.env.SHIPWRIGHT_ENCRYPTION_KEY = saved;
+  const specialtyRegistry = new SpecialtyTypes();
+  return {
+    agentService: new AgentService(prisma),
+    agentEnvService: new AgentEnvService(prisma, crypto),
+    agentCronJobService: new AgentCronJobService(
+      prisma,
+      undefined,
+      specialtyRegistry,
+    ),
+    agentCronRunService: new AgentCronRunService(prisma),
+    agentCronRunStatsService: new AgentCronRunStatsService(prisma),
+    agentToolService: new AgentToolService(prisma),
+    agentTokenService: new AgentTokenService(prisma),
+    agentPluginService: new AgentPluginService(prisma),
+    agentMemberService: new AgentMemberService(prisma),
+    specialtyRegistry,
+    agentChatTokenService: new AgentChatTokenService(prisma),
+    agentGitHubInstallationsService: new AgentGitHubInstallationsService(
+      prisma,
+    ),
+    prisma,
+    provisioner,
+    serviceIntegrations: [
+      {
+        name: "task-store",
+        listTokensForAgent: async () => [],
+        revokeToken: async () => {},
+      },
+    ],
+    chatService: new NoopChatServiceProvisioningClient(),
+    slack: { deleteApp: async () => {} },
+    decrypt: (value: string) => crypto.decrypt(value),
+    sessionSecret: SESSION_SECRET,
+  };
+}
+
+describeOrSkip("PATCH /agents/:id specialty (integration)", () => {
+  let prisma: PrismaClient;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agent.deleteMany();
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("flips Agent.specialty and reconciles a Saul-shaped cron set against the specialist type", async () => {
+    const agent = await prisma.agent.create({
+      data: { name: "Saul", specialty: "saul" },
+    });
+    const systemNames = [
+      "shipwright-dev-loop",
+      "shipwright-dev-task",
+      "shipwright-review",
+      "shipwright-patch",
+      "shipwright-deploy",
+      "shipwright-entropy-scan",
+      "shipwright-security-scan",
+      "shipwright-error-scan",
+      "shipwright-learn-dream-sys",
+    ];
+    for (const name of systemNames) {
+      await prisma.agentCronJob.create({
+        data: {
+          agentId: agent.id,
+          name,
+          system: true,
+          schedule: "0 * * * *",
+          prompt: `/${name}`,
+          enabled: false,
+        },
+      });
+    }
+    const userCron = await prisma.agentCronJob.create({
+      data: {
+        agentId: agent.id,
+        name: "learn-dream",
+        system: false,
+        schedule: "0 3 * * *",
+        prompt: "/learn-dream",
+        enabled: true,
+      },
+    });
+    for (let i = 0; i < 2; i++) {
+      await prisma.agentCronRun.create({
+        data: {
+          cronId: userCron.id,
+          agentId: agent.id,
+          startedAt: new Date(Date.now() - i * 60_000),
+        },
+      });
+    }
+
+    const provisioner = new RecordingProvisioner();
+    const app = createAdminApp(makeDeps(prisma, provisioner));
+    const cookie = await makeSessionCookie();
+    const res = await app.request(`/agents/${agent.id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ specialty: "specialist" }),
+      headers: {
+        "Content-Type": "application/json",
+        Cookie: `admin_session=${cookie}`,
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect((await res.json()).specialty).toBe("specialist");
+    const row = await prisma.agent.findUniqueOrThrow({
+      where: { id: agent.id },
+    });
+    expect(row.specialty).toBe("specialist");
+    expect(
+      await prisma.agentCronJob.count({
+        where: { agentId: agent.id, system: true },
+      }),
+    ).toBe(0);
+    const survivors = await prisma.agentCronJob.findMany({
+      where: { agentId: agent.id },
+    });
+    expect(survivors.map((c) => c.id)).toEqual([userCron.id]);
+    expect(survivors[0]?.system).toBe(false);
+    expect(
+      await prisma.agentCronRun.count({ where: { cronId: userCron.id } }),
+    ).toBe(2);
+    // selfHosted defaults false, so the workload reconcile ran once.
+    expect(provisioner.reconciled).toHaveLength(1);
+    expect(provisioner.reconciled[0]?.id).toBe(agent.id);
+    expect(provisioner.reconciled[0]?.specialty).toBe("specialist");
+  });
+});

package/src/agents-api.ts

@@ -41,6 +41,7 @@ import {
 } from "./account-agent-create.ts";
 import {
   reconcileAgentAfterAccountChange,
+  reconcileAgentAfterSpecialtyChange,
   reconcileAgentAfterPodServiceAccountChange,
 } from "./agent-account-assignment.ts";
 import {
@@ -623,7 +624,7 @@ const patchAgentRoute = createRoute({
   path: "/agents/{id}",
   summary: "Update an agent",
   description:
-    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` and `trialExpiryWarnedAt` are not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
+    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows), and/or `podServiceAccountName` (platform admin only — 403 otherwise; `null` clears it; 409 unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on; 422 for agents with a per-agent federated identity; reconciles the workload so the pod is recreated under the new ServiceAccount). `specialty` (platform admin only — 403 otherwise; 422 when the type is unknown; a no-op when unchanged; otherwise persists the new type, reconciles the agent's system crons against it — system crons the new type does not declare are deleted, user crons survive — and reconciles the workload of in-cluster agents so the pod runs the image mapped to the new specialty). `trialExpiryWarnedAt` is not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
   request: {
     params: AgentIdParamSchema,
     body: {
@@ -645,7 +646,7 @@ const patchAgentRoute = createRoute({
     },
     422: {
       description:
-        "podServiceAccountName supplied for an agent with a per-agent federated identity",
+        "podServiceAccountName supplied for an agent with a per-agent federated identity, or `specialty` naming an unknown type",
       ...jsonError,
     },
   },
@@ -1688,6 +1689,25 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
         throw new ForbiddenError("Admin access required to change accountId");
       }
     }
+    // SAL-1.2: specialty change — platform-admin only, known type only.
+    let previousSpecialty: string | undefined;
+    if (body.specialty !== undefined) {
+      if (c.get("isAdmin") !== true) {
+        throw new ForbiddenError("Admin access required to change specialty");
+      }
+      if (!specialtyRegistry.tryGetType(body.specialty)) {
+        throw new UnprocessableEntityError(
+          `unknown specialty "${body.specialty}"`,
+        );
+      }
+      const current = await agentService.getDetail(agentId);
+      if (!current) {
+        throw new NotFoundError(`agent ${agentId} not found`);
+      }
+      if (current.specialty !== body.specialty) {
+        previousSpecialty = current.specialty;
+      }
+    }
     // COS-49.1: pod ServiceAccount — platform-admin only, flag-gated, and not
     // for agents whose federated identity owns the ServiceAccount.
     let previousPodServiceAccountName: string | null = null;
@@ -1733,6 +1753,9 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
           ? { podServiceAccountName: body.podServiceAccountName }
           : {}),
         ...(body.accountId !== undefined ? { accountId: body.accountId } : {}),
+        ...(previousSpecialty !== undefined
+          ? { specialty: body.specialty }
+          : {}),
         ...(body.repos !== undefined ? { repos: body.repos } : {}),
         ...(body.reviewAuthorAllowlist !== undefined
           ? { reviewAuthorAllowlist: body.reviewAuthorAllowlist }
@@ -1786,6 +1809,28 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       body.accountId !== undefined
         ? await reconcileAgentAfterAccountChange(provisioner, agent)
         : undefined;
+    let specialtyWarning: string | undefined;
+    if (previousSpecialty !== undefined) {
+      // Audit: ids and names only — never the caller's key.
+      console.info(
+        `[agents-api] specialty changed: agent=${agentId} old=${previousSpecialty} new=${agent.specialty} caller=${c.get("caller")?.name ?? "anonymous"}`,
+      );
+      const warnings: string[] = [];
+      try {
+        await agentCronJobService.reconcileSystemCrons(agentId);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(
+          `specialty updated, but reconciling system crons failed: ${message}`,
+        );
+      }
+      const workloadWarning = await reconcileAgentAfterSpecialtyChange(
+        provisioner,
+        agent,
+      );
+      if (workloadWarning) warnings.push(workloadWarning);
+      specialtyWarning = warnings.join("; ") || undefined;
+    }
     let podSaWarning: string | undefined;
     if (body.podServiceAccountName !== undefined) {
       // Audit: ids and names only — never the caller's key.
@@ -1801,7 +1846,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       }
     }
     const warning =
-      [slackWarning, reconcileWarning, podSaWarning]
+      [slackWarning, reconcileWarning, specialtyWarning, podSaWarning]
         .filter(Boolean)
         .join("; ") || undefined;
     return c.json(serializeAgent(agent, warning), 200);

package/src/agents.ts

@@ -140,6 +140,8 @@ export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
 }
 
 interface UpdateSelfHostedInput {
+  /** SAL-1.2: the agent's specialty; callers validate it against the registry. */
+  specialty?: string;
   /** COS-49.1: pod ServiceAccount; null clears it. */
   podServiceAccountName?: string | null;
   /** SSP-5.3: owning account; null clears it (unassigned/platform agent). */
@@ -475,6 +477,9 @@ export class AgentService {
       where: { id },
       data: {
         selfHosted: input.selfHosted,
+        ...(input.specialty !== undefined
+          ? { specialty: input.specialty }
+          : {}),
         ...(input.accountId !== undefined
           ? { accountId: input.accountId }
           : {}),

package/src/openapi-schemas.ts

@@ -52,6 +52,10 @@ export const PatchAgentBodySchema = z
       .optional()
       .openapi({ example: "U0AALR8M69X" }),
     selfHosted: z.boolean().optional().openapi({ example: false }),
+    /**
+     * SAL-1.2: platform-admin only. Must name a known specialty type.
+     */
+    specialty: z.string().min(1).optional().openapi({ example: "specialist" }),
     repos: z
       .array(
         z.string().refine(isOrgRepo, {