@app-vitals/agent-admin 0.13.1 → 0.14.0

package/package.json

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

package/src/admin-boot-config.ts

@@ -12,6 +12,7 @@
 import { join } from "node:path";
 import type { PrismaClient } from "../prisma/client/client.ts";
 import { AgentAnthropicIdentityService } from "./agent-anthropic-identity.ts";
+import { parseAgentImageMap } from "./agent-image-map.ts";
 import type { AgentAnthropicFederation } from "./agent-manifest.ts";
 import type {
   AgentProvisioner,
@@ -120,6 +121,8 @@ export function buildProvisioner(
   const namespace = env.SHIPWRIGHT_K8S_NAMESPACE ?? "default";
   const image = env.SHIPWRIGHT_AGENT_IMAGE ?? "";
   const imageTag = env.SHIPWRIGHT_AGENT_IMAGE_TAG ?? "latest";
+  // Malformed → throws here, so admin boot fails rather than falling back.
+  const images = parseAgentImageMap(env.SHIPWRIGHT_AGENT_IMAGES);
   const apiUrl = env.SHIPWRIGHT_API_URL ?? "";
   const replicasRaw = env.SHIPWRIGHT_AGENT_REPLICAS;
   const replicas = replicasRaw ? Number(replicasRaw) : undefined;
@@ -201,6 +204,7 @@ export function buildProvisioner(
     namespace,
     image,
     imageTag,
+    ...(images ? { images } : {}),
     apiUrl,
     ...(replicas !== undefined && Number.isFinite(replicas)
       ? { replicas }

package/src/agent-account-assignment.ts

@@ -21,6 +21,7 @@ type ReconcilableAgent = Partial<AgentAnthropicIdentity> & {
   selfHosted: boolean;
   accountId?: string | null;
   podServiceAccountName?: string | null;
+  specialty?: string;
 };
 
 export function reconcileAgentAfterAccountChange(
@@ -60,6 +61,9 @@ async function reconcileAgentWorkload(
       {
         id: agent.id,
         slug: agent.name,
+        ...(agent.specialty !== undefined
+          ? { specialty: agent.specialty }
+          : {}),
         accountId: agent.accountId ?? null,
         ownerEmail: agent.ownerEmail,
         anthropicIdentityName: agent.anthropicIdentityName,

package/src/agent-image-map.ts

@@ -0,0 +1,74 @@
+/**
+ * admin/src/agent-image-map.ts
+ *
+ * Per-specialty agent image resolution (SPI-1.1). SHIPWRIGHT_AGENT_IMAGES is an
+ * optional JSON object keyed by specialty whose values are `{repository, tag}`.
+ * An agent whose specialty is unmapped (or has no specialty) runs the
+ * single-image default (SHIPWRIGHT_AGENT_IMAGE / _TAG); a `default` key in the
+ * map overrides that default. A malformed map throws, so admin boot fails
+ * instead of silently falling back to the wrong image.
+ */
+
+export interface AgentImageRef {
+  repository: string;
+  tag: string;
+}
+
+export type AgentImageMap = Readonly<Record<string, AgentImageRef>>;
+
+export const DEFAULT_IMAGE_KEY = "default";
+
+function fail(reason: string): never {
+  throw new Error(`SHIPWRIGHT_AGENT_IMAGES is malformed: ${reason}`);
+}
+
+/** Parse SHIPWRIGHT_AGENT_IMAGES. Unset/blank → undefined (single-image mode). */
+export function parseAgentImageMap(
+  raw: string | undefined,
+): AgentImageMap | undefined {
+  if (raw === undefined || raw.trim() === "") return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return fail("expected a JSON object keyed by specialty");
+  }
+  const map: Record<string, AgentImageRef> = {};
+  for (const [specialty, value] of Object.entries(parsed)) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return fail(`"${specialty}" must be an object {repository, tag}`);
+    }
+    const { repository, tag } = value as Record<string, unknown>;
+    if (typeof repository !== "string" || repository.trim() === "") {
+      return fail(`"${specialty}".repository must be a non-empty string`);
+    }
+    if (typeof tag !== "string" || tag.trim() === "") {
+      return fail(`"${specialty}".tag must be a non-empty string`);
+    }
+    map[specialty] = { repository, tag };
+  }
+  return Object.keys(map).length > 0 ? map : undefined;
+}
+
+/**
+ * The image an agent of `specialty` runs: its own map entry, else the map's
+ * `default` entry, else the single-image fallback.
+ */
+export function resolveImage(
+  fallback: AgentImageRef,
+  images: AgentImageMap | undefined,
+  specialty?: string | null,
+): AgentImageRef {
+  if (!images) return fallback;
+  const own =
+    specialty && Object.hasOwn(images, specialty)
+      ? images[specialty]
+      : undefined;
+  if (own) return own;
+  return Object.hasOwn(images, DEFAULT_IMAGE_KEY)
+    ? (images[DEFAULT_IMAGE_KEY] as AgentImageRef)
+    : fallback;
+}

package/src/agent-image-map.unit.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "bun:test";
+import { parseAgentImageMap, resolveImage } from "./agent-image-map.ts";
+
+const fallback = { repository: "ghcr.io/x/agent", tag: "1.0.0" };
+const json = JSON.stringify({
+  reviewer: { repository: "ghcr.io/x/reviewer", tag: "2.0.0" },
+});
+
+describe("parseAgentImageMap", () => {
+  it("returns undefined when unset, empty or blank", () => {
+    expect(parseAgentImageMap(undefined)).toBeUndefined();
+    expect(parseAgentImageMap("")).toBeUndefined();
+    expect(parseAgentImageMap("  ")).toBeUndefined();
+    expect(parseAgentImageMap("{}")).toBeUndefined();
+  });
+
+  it("parses a valid map", () => {
+    expect(parseAgentImageMap(json)).toEqual({
+      reviewer: { repository: "ghcr.io/x/reviewer", tag: "2.0.0" },
+    });
+  });
+
+  it.each([
+    ["invalid JSON", "{nope"],
+    ["an array", "[]"],
+    ["null", "null"],
+    ["a string", '"x"'],
+    ["a non-object entry", '{"a":"img:1"}'],
+    ["a null entry", '{"a":null}'],
+    ["a missing tag", '{"a":{"repository":"r"}}'],
+    ["an empty repository", '{"a":{"repository":"","tag":"t"}}'],
+    ["a non-string tag", '{"a":{"repository":"r","tag":1}}'],
+  ])("throws on %s", (_name, raw) => {
+    expect(() => parseAgentImageMap(raw)).toThrow(/SHIPWRIGHT_AGENT_IMAGES/);
+  });
+});
+
+describe("resolveImage", () => {
+  it("uses the fallback when no map is set", () => {
+    expect(resolveImage(fallback, undefined, "reviewer")).toEqual(fallback);
+    expect(resolveImage(fallback, undefined)).toEqual(fallback);
+  });
+
+  it("uses the mapped entry for a mapped specialty", () => {
+    const map = parseAgentImageMap(json);
+    expect(resolveImage(fallback, map, "reviewer")).toEqual({
+      repository: "ghcr.io/x/reviewer",
+      tag: "2.0.0",
+    });
+  });
+
+  it("falls back for an unmapped or absent specialty", () => {
+    const map = parseAgentImageMap(json);
+    expect(resolveImage(fallback, map, "other")).toEqual(fallback);
+    expect(resolveImage(fallback, map, undefined)).toEqual(fallback);
+    expect(resolveImage(fallback, map, "toString")).toEqual(fallback);
+  });
+
+  it("uses the default key for unmapped specialties", () => {
+    const map = parseAgentImageMap(
+      JSON.stringify({ default: { repository: "d", tag: "9" } }),
+    );
+    expect(resolveImage(fallback, map, "other")).toEqual({
+      repository: "d",
+      tag: "9",
+    });
+  });
+});

package/src/agent-provisioner.integration.test.ts

@@ -1243,3 +1243,114 @@ describe("KubernetesAgentProvisioner.reconcile() — anthropic federation (casse
     expect(patches).toEqual([]);
   });
 });
+
+// ─── Per-specialty images (SPI-1.1) ─────────────────────────────────────────
+// Not DB-backed: a stub token service stands in for the minting path, and the
+// in-memory RecordedKubernetesClient for the cluster. The single-image tests
+// above are the unset-map regression guard.
+
+describe("KubernetesAgentProvisioner — per-specialty images", () => {
+  const stubTokens = {
+    create: async () => ({ rawToken: "raw-token" }),
+  } as unknown as AgentTokenService;
+  const REVIEWER = "ghcr.io/app-vitals/shipwright-agent-reviewer:v2.0.0";
+  const SINGLE = `${CONFIG.image}:${CONFIG.imageTag}`;
+  const MAPPED: KubernetesAgentProvisionerConfig = {
+    ...CONFIG,
+    images: {
+      reviewer: {
+        repository: "ghcr.io/app-vitals/shipwright-agent-reviewer",
+        tag: "v2.0.0",
+      },
+    },
+  };
+
+  async function imageOf(
+    k8s: RecordedKubernetesClient,
+    agentId: string,
+  ): Promise<string | undefined> {
+    const dep = await k8s.getDeployment(NAMESPACE, sanitizeAgentName(agentId));
+    return dep.spec.template.spec.containers[0]?.image;
+  }
+
+  it("provision() applies the mapped image for a mapped specialty and the single image otherwise", async () => {
+    const k8s = emptyClient();
+    const provisioner = new KubernetesAgentProvisioner(k8s, stubTokens, MAPPED);
+
+    await provisioner.provision("agent-rev", { specialty: "reviewer" });
+    await provisioner.provision("agent-dev", { specialty: "developer" });
+    await provisioner.provision("agent-none");
+
+    expect(await imageOf(k8s, "agent-rev")).toBe(REVIEWER);
+    expect(await imageOf(k8s, "agent-dev")).toBe(SINGLE);
+    expect(await imageOf(k8s, "agent-none")).toBe(SINGLE);
+  });
+
+  it("provision() ignores specialty when no map is configured", async () => {
+    const k8s = emptyClient();
+    const provisioner = new KubernetesAgentProvisioner(k8s, stubTokens, CONFIG);
+
+    await provisioner.provision("agent-rev", { specialty: "reviewer" });
+
+    expect(await imageOf(k8s, "agent-rev")).toBe(SINGLE);
+  });
+
+  it("reconcile() patches only the Deployments whose resolved image differs", async () => {
+    const k8s = emptyClient();
+    const patched: string[] = [];
+    const spy: KubernetesClient = {
+      createSecret: (ns, s) => k8s.createSecret(ns, s),
+      createDeploymentManifest: (ns, d) => k8s.createDeploymentManifest(ns, d),
+      createPvc: (ns, p) => k8s.createPvc(ns, p),
+      getSecret: (ns, n) => k8s.getSecret(ns, n),
+      getDeployment: (ns, n) => k8s.getDeployment(ns, n),
+      listDeployments: (ns, l) => k8s.listDeployments(ns, l),
+      deleteDeployment: (ns, n) => k8s.deleteDeployment(ns, n),
+      deleteSecret: (ns, n) => k8s.deleteSecret(ns, n),
+      deletePvc: (ns, n) => k8s.deletePvc(ns, n),
+      patchDeployment: (ns, n, p) => {
+        patched.push(n);
+        return k8s.patchDeployment(ns, n, p);
+      },
+    } as KubernetesClient;
+
+    // Both agents were provisioned under the single-image config.
+    const before = new KubernetesAgentProvisioner(spy, stubTokens, CONFIG);
+    await before.provision("agent-rev", { specialty: "reviewer" });
+    await before.provision("agent-dev", { specialty: "developer" });
+
+    // The map is introduced: only the reviewer's resolved image changes.
+    const after = new KubernetesAgentProvisioner(spy, stubTokens, MAPPED);
+    const result = await after.reconcile([
+      { id: "agent-rev", specialty: "reviewer" },
+      { id: "agent-dev", specialty: "developer" },
+    ]);
+
+    expect(result.updated).toEqual(["agent-rev"]);
+    expect(result.failed).toEqual([]);
+    expect(patched).toEqual([sanitizeAgentName("agent-rev")]);
+    expect(await imageOf(k8s, "agent-rev")).toBe(REVIEWER);
+    expect(await imageOf(k8s, "agent-dev")).toBe(SINGLE);
+
+    // A second pass is a no-op.
+    patched.length = 0;
+    const again = await after.reconcile([
+      { id: "agent-rev", specialty: "reviewer" },
+      { id: "agent-dev", specialty: "developer" },
+    ]);
+    expect(again.updated).toEqual([]);
+    expect(patched).toEqual([]);
+  });
+
+  it("reconcile() recreates a missing Deployment with its specialty's image", async () => {
+    const k8s = emptyClient();
+    const provisioner = new KubernetesAgentProvisioner(k8s, stubTokens, MAPPED);
+
+    const result = await provisioner.reconcile([
+      { id: "agent-rev", specialty: "reviewer" },
+    ]);
+
+    expect(result.recreated).toEqual(["agent-rev"]);
+    expect(await imageOf(k8s, "agent-rev")).toBe(REVIEWER);
+  });
+});

package/src/agent-provisioner.ts

@@ -44,6 +44,11 @@ import type {
   AgentAnthropicIdentity,
   AgentAnthropicIdentityService,
 } from "./agent-anthropic-identity.ts";
+import {
+  type AgentImageMap,
+  type AgentImageRef,
+  resolveImage,
+} from "./agent-image-map.ts";
 import {
   type AgentAnthropicFederation,
   type AgentContainerResourceOverrides,
@@ -151,6 +156,8 @@ export interface ReconcileTarget extends Partial<AgentAnthropicIdentity> {
   accountId?: string | null;
   /** The Agent row's pod ServiceAccount (COS-48.1); rendered only when the flag is on. */
   podServiceAccountName?: string | null;
+  /** The agent's specialty; selects its image (SHIPWRIGHT_AGENT_IMAGES). */
+  specialty?: string;
   /**
    * The pod ServiceAccount this agent had before the change being reconciled
    * (COS-49.1). Only used to clear: when `podServiceAccountName` is now unset,
@@ -179,6 +186,8 @@ export interface AgentProvisioner {
       slug?: string;
       accountId?: string | null;
       podServiceAccountName?: string | null;
+      /** Selects the agent's image (SHIPWRIGHT_AGENT_IMAGES). */
+      specialty?: string;
     },
   ): Promise<ProvisionResult>;
   /**
@@ -236,6 +245,11 @@ export interface KubernetesAgentProvisionerConfig {
   image: string;
   /** Image tag, joined as `image:tag`. */
   imageTag: string;
+  /**
+   * Optional per-specialty image map (SHIPWRIGHT_AGENT_IMAGES). A specialty
+   * without an entry (and no `default` key) uses `image`/`imageTag`.
+   */
+  images?: AgentImageMap;
   /** In-cluster admin/API base URL the agent calls home to. */
   apiUrl: string;
   /**
@@ -833,6 +847,15 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
       : `${resourceName}-token`;
   }
 
+  /** The image an agent of `specialty` runs (see resolveImage). */
+  private resolveImage(specialty?: string | null): AgentImageRef {
+    return resolveImage(
+      { repository: this.config.image, tag: this.config.imageTag },
+      this.config.images,
+      specialty,
+    );
+  }
+
   private pvcNameFor(resourceName: string, slug?: string): string {
     return this.config.pvcName
       ? this.config.pvcName(slug ? sanitizeAgentName(slug) : resourceName)
@@ -902,13 +925,15 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
     accountId: string | null | undefined,
     federation: AgentAnthropicFederation | undefined,
     podServiceAccountName?: string | null,
+    specialty?: string,
   ) {
     const resourceName = this.resourceName(agentId);
+    const { repository, tag } = this.resolveImage(specialty);
     return buildAgentDeploymentManifest({
       agentId,
       namespace: this.config.namespace,
-      image: this.config.image,
-      imageTag: this.config.imageTag,
+      image: repository,
+      imageTag: tag,
       apiUrl: this.config.apiUrl,
       pvcName: this.pvcNameFor(resourceName, slug),
       secretName: this.secretNameFor(resourceName),
@@ -935,6 +960,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
       slug?: string;
       accountId?: string | null;
       podServiceAccountName?: string | null;
+      specialty?: string;
     },
   ): Promise<ProvisionResult> {
     const resourceName = this.resourceName(agentId);
@@ -1147,6 +1173,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
           slug?: string;
           accountId?: string | null;
           podServiceAccountName?: string | null;
+          specialty?: string;
         }
       | undefined,
     result: ProvisionResult,
@@ -1241,6 +1268,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
           opts?.accountId,
           federation,
           opts?.podServiceAccountName,
+          opts?.specialty,
         ),
       );
     } catch (err) {
@@ -1388,6 +1416,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
               slug: agent.slug,
               accountId: agent.accountId,
               podServiceAccountName: agent.podServiceAccountName,
+              specialty: agent.specialty,
             });
           }
           recreated.push(agent.id);
@@ -1453,6 +1482,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
             agent.accountId,
             desiredFederation,
             agent.podServiceAccountName,
+            agent.specialty,
           );
           const desired = desiredDeployment.spec.template.spec.containers[0];
           const desiredLabels = desiredDeployment.spec.template.metadata.labels;

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

@@ -2293,6 +2293,7 @@ describe("admin API — POST /agents/reconcile", () => {
         anthropicServiceAccountId: null,
         anthropicFederationRuleId: null,
         k8sServiceAccountName: null,
+        specialty: "coding",
       },
     ]);
   });
@@ -5407,7 +5408,12 @@ describe("admin API — PATCH /agents/:id accountId (SSP-5.3)", () => {
       "acct-b",
     );
     expect(provisioner.reconciled).toEqual([
-      { id: AGENT_ID, slug: "Existing Agent", accountId: "acct-b" },
+      {
+        id: AGENT_ID,
+        slug: "Existing Agent",
+        accountId: "acct-b",
+        specialty: "coding",
+      },
     ]);
   });
 
@@ -5423,7 +5429,12 @@ describe("admin API — PATCH /agents/:id accountId (SSP-5.3)", () => {
     expect(res.status).toBe(200);
     expect(((await res.json()) as { accountId: unknown }).accountId).toBeNull();
     expect(provisioner.reconciled).toEqual([
-      { id: AGENT_ID, slug: "Existing Agent", accountId: null },
+      {
+        id: AGENT_ID,
+        slug: "Existing Agent",
+        accountId: null,
+        specialty: "coding",
+      },
     ]);
   });
 

package/src/agents-api.ts

@@ -1645,6 +1645,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       await provisioner.provision(agent.id, {
         slug: agent.name,
         accountId: agent.accountId,
+        specialty: agent.specialty,
       });
     return c.json({ resourceName, secretName, deploymentName }, 200);
   });

package/src/agents.ts

@@ -1087,6 +1087,7 @@ export async function createAgent(
       await deps.provisioner.provision(agent.id, {
         slug: agent.name,
         accountId: agent.accountId,
+        specialty: agent.specialty,
       });
     } catch (err) {
       console.error(

package/src/main.unit.test.ts

@@ -98,6 +98,35 @@ describe("buildProvisioner", () => {
     expect(configOf(off).podServiceAccount).toEqual({ enabled: false });
   });
 
+  it("parses SHIPWRIGHT_AGENT_IMAGES into the config, and omits it when unset", () => {
+    const env = { SHIPWRIGHT_K8S_PROVISIONING: "enabled" };
+    expect(
+      configOf(buildProvisioner(env, stubAgentTokenService())).images,
+    ).toBe(undefined);
+    const mapped = buildProvisioner(
+      {
+        ...env,
+        SHIPWRIGHT_AGENT_IMAGES: '{"reviewer":{"repository":"r","tag":"1"}}',
+      },
+      stubAgentTokenService(),
+    );
+    expect(configOf(mapped).images).toEqual({
+      reviewer: { repository: "r", tag: "1" },
+    });
+  });
+
+  it("throws at boot on a malformed SHIPWRIGHT_AGENT_IMAGES", () => {
+    expect(() =>
+      buildProvisioner(
+        {
+          SHIPWRIGHT_K8S_PROVISIONING: "enabled",
+          SHIPWRIGHT_AGENT_IMAGES: "{oops",
+        },
+        stubAgentTokenService(),
+      ),
+    ).toThrow(/SHIPWRIGHT_AGENT_IMAGES/);
+  });
+
   it("returns a NoopAgentProvisioner when SHIPWRIGHT_K8S_PROVISIONING is unset", () => {
     const provisioner = buildProvisioner({}, stubAgentTokenService());
     expect(provisioner).toBeInstanceOf(NoopAgentProvisioner);

package/src/startup-policy-reconcile.ts

@@ -44,6 +44,7 @@ export function managedReconcileTargets(
     .map((a) => ({
       id: a.id,
       slug: a.name,
+      specialty: a.specialty,
       accountId: a.accountId,
       ownerEmail: a.ownerEmail,
       anthropicIdentityName: a.anthropicIdentityName,

package/src/startup-policy-reconcile.unit.test.ts

@@ -97,8 +97,8 @@ describe("managedReconcileTargets", () => {
         agent({ id: "a3", name: "gamma" }),
       ]),
     ).toEqual([
-      { id: "a1", slug: "alpha", accountId: "acct-1" },
-      { id: "a3", slug: "gamma", accountId: null },
+      { id: "a1", slug: "alpha", accountId: "acct-1", specialty: "dev" },
+      { id: "a3", slug: "gamma", accountId: null, specialty: "dev" },
     ]);
   });
 });
@@ -128,8 +128,15 @@ describe("managedReconcileTargets identity fields", () => {
         anthropicServiceAccountId: "svac_1",
         anthropicFederationRuleId: "fdrl_1",
         k8sServiceAccountName: "a1",
+        specialty: "dev",
+      },
+      {
+        id: "a2",
+        slug: "beta",
+        accountId: null,
+        ownerEmail: null,
+        specialty: "dev",
       },
-      { id: "a2", slug: "beta", accountId: null, ownerEmail: null },
     ]);
   });
 });
@@ -151,8 +158,13 @@ describe("runStartupPolicyReconcile", () => {
     expect(calls).toEqual([
       {
         agents: [
-          { id: "a1", slug: "alpha", accountId: null },
-          { id: "a3", slug: "gamma", accountId: "acct-3" },
+          { id: "a1", slug: "alpha", accountId: null, specialty: "dev" },
+          {
+            id: "a3",
+            slug: "gamma",
+            accountId: "acct-3",
+            specialty: "dev",
+          },
         ],
         opts: { policyOnly: true },
       },