@app-vitals/agent-admin 1.0.0 → 1.2.0

package/e2e/agents-page.e2e.ts

@@ -239,7 +239,7 @@ test.describe("GET /admin/agents/:id — authenticated", () => {
     context,
   }) => {
     await loadAgentDetailPage(page, context);
-    await expect(page.locator("body")).toContainText("coding");
+    await expect(page.locator("body")).toContainText("specialist");
   });
 
   // CFB-3.1: .data-table .btn must stay at its current ~36px height at mobile
@@ -304,16 +304,16 @@ test.describe("GET /admin/agents/new — type picker", () => {
     await expect(typeSelect).toHaveAttribute("required", "");
   });
 
-  test('the select lists the configured default type "coding"', async ({
+  test('the select lists the configured default type "specialist"', async ({
     page,
     context,
   }) => {
     await loadNewAgentPage(page, context);
-    const codingOption = page.locator(
-      'select[name="type"] option[value="coding"]',
+    const specialistOption = page.locator(
+      'select[name="type"] option[value="specialist"]',
     );
-    await expect(codingOption).toBeAttached();
-    await expect(codingOption).toHaveText("coding");
+    await expect(specialistOption).toBeAttached();
+    await expect(specialistOption).toHaveText("Specialist Agent");
   });
 });
 
@@ -324,8 +324,8 @@ test.describe("POST /admin/agents — create-with-type journey", () => {
   }) => {
     await loadNewAgentPage(page, context);
 
-    await page.fill('input[name="name"]', "My New Coding Agent");
-    await page.selectOption('select[name="type"]', "coding");
+    await page.fill('input[name="name"]', "My New Specialist Agent");
+    await page.selectOption('select[name="type"]', "specialist");
     // Scoped to the new-agent form specifically — the page also has a
     // "Sign out" button[type="submit"] in the toolbar, and an unscoped
     // selector matches that one first (it's earlier in the DOM), which
@@ -333,6 +333,6 @@ test.describe("POST /admin/agents — create-with-type journey", () => {
     await page.click('form[action="/admin/agents"] button[type="submit"]');
 
     await page.waitForURL(/\/admin\/agents\/[^/]+$/);
-    await expect(page.locator("body")).toContainText("coding");
+    await expect(page.locator("body")).toContainText("specialist");
   });
 });

package/e2e/test-server.ts

@@ -30,13 +30,13 @@ import type {
 // ─── Config ───────────────────────────────────────────────────────────────────
 
 // The suite runs without a product specialty: point the specialty lookup at the
-// minimal "coding" fixture next to this file (values already set win).
+// minimal "specialist" fixture next to this file (values already set win).
 process.env.SHIPWRIGHT_SPECIALTIES_DIR ||= resolve(
   import.meta.dir,
   "fixtures",
   "specialties",
 );
-process.env.SHIPWRIGHT_DEFAULT_AGENT_TYPE ||= "coding";
+process.env.SHIPWRIGHT_DEFAULT_AGENT_TYPE ||= "specialist";
 
 const ADMIN_E2E_PORT = 3490;
 const ADMIN_E2E_SESSION_SECRET =
@@ -324,7 +324,7 @@ function buildMockDeps(chatClient: ChatClient | undefined): AdminUIDeps {
           name: ADMIN_E2E_AGENT.name,
           slackId: ADMIN_E2E_AGENT.slackId,
           selfHosted: false,
-          specialty: "coding",
+          specialty: "specialist",
           createdAt: new Date("2024-01-01"),
           updatedAt: new Date("2024-01-01"),
         },
@@ -339,7 +339,7 @@ function buildMockDeps(chatClient: ChatClient | undefined): AdminUIDeps {
         name: input.name ?? ADMIN_E2E_AGENT.name,
         slackId: ADMIN_E2E_AGENT.slackId,
         selfHosted: false,
-        specialty: input.specialty ?? "coding",
+        specialty: input.specialty ?? "specialist",
         createdAt: new Date("2024-01-01"),
         updatedAt: new Date("2024-01-01"),
       }),
@@ -349,7 +349,7 @@ function buildMockDeps(chatClient: ChatClient | undefined): AdminUIDeps {
         name: ADMIN_E2E_AGENT.name,
         slackId: ADMIN_E2E_AGENT.slackId,
         selfHosted: false,
-        specialty: "coding",
+        specialty: "specialist",
         createdAt: new Date("2024-01-01"),
         updatedAt: new Date("2024-01-01"),
         repos: [],
@@ -361,7 +361,7 @@ function buildMockDeps(chatClient: ChatClient | undefined): AdminUIDeps {
         name: ADMIN_E2E_AGENT.name,
         slackId: ADMIN_E2E_AGENT.slackId,
         selfHosted: false,
-        specialty: "coding",
+        specialty: "specialist",
         createdAt: new Date("2024-01-01"),
         updatedAt: new Date("2024-01-01"),
         repos: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-admin",
-  "version": "1.0.0",
+  "version": "1.2.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.0.0",
+    "@app-vitals/agent-lib": "1.2.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 { parseAgentPodLabels } from "./agent-pod-labels.ts";
 import { parseAgentImageMap } from "./agent-image-map.ts";
 import type { AgentAnthropicFederation } from "./agent-manifest.ts";
 import type {
@@ -123,6 +124,7 @@ export function buildProvisioner(
   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 podLabels = parseAgentPodLabels(env.SHIPWRIGHT_K8S_AGENT_POD_LABELS);
   const apiUrl = env.SHIPWRIGHT_API_URL ?? "";
   const replicasRaw = env.SHIPWRIGHT_AGENT_REPLICAS;
   const replicas = replicasRaw ? Number(replicasRaw) : undefined;
@@ -205,6 +207,7 @@ export function buildProvisioner(
     image,
     imageTag,
     ...(images ? { images } : {}),
+    ...(podLabels ? { podLabels } : {}),
     apiUrl,
     ...(replicas !== undefined && Number.isFinite(replicas)
       ? { replicas }

package/src/admin-boot-config.unit.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { buildDeletionClients } from "./admin-boot-config.ts";
+import type { AgentTokenService } from "./agent-tokens.ts";
+import { buildProvisioner, buildDeletionClients } from "./admin-boot-config.ts";
 import {
   HttpChatServiceProvisioningClient,
   NoopChatServiceProvisioningClient,
@@ -26,3 +27,17 @@ describe("buildDeletionClients", () => {
     expect(chatService).toBeInstanceOf(HttpChatServiceProvisioningClient);
   });
 });
+
+describe("buildProvisioner pod label configuration", () => {
+  it("rejects invalid labels during admin boot when provisioning is enabled", () => {
+    expect(() =>
+      buildProvisioner(
+        {
+          SHIPWRIGHT_K8S_PROVISIONING: "enabled",
+          SHIPWRIGHT_K8S_AGENT_POD_LABELS: '{"app.kubernetes.io/name":"wrong"}',
+        },
+        {} as AgentTokenService,
+      ),
+    ).toThrow("reserved key");
+  });
+});

package/src/agent-manifest.ts

@@ -12,6 +12,7 @@
  */
 
 import { createHash } from "node:crypto";
+import { validateAgentPodLabels } from "./agent-pod-labels.ts";
 import type {
   KubernetesDeployment,
   KubernetesEnvVar,
@@ -239,6 +240,8 @@ export function buildAgentPvcManifest(opts: AgentPvcOpts): KubernetesPvc {
 // ─── Deployment builder ─────────────────────────────────────────────────────
 
 export interface AgentDeploymentOpts {
+  /** Additional pod labels; reserved identity labels cannot be overridden. */
+  podLabels?: Record<string, string>;
   /** Original agent id (used verbatim in env + label, sanitized for the name). */
   agentId: string;
   namespace: string;
@@ -471,6 +474,7 @@ export function buildAgentDeploymentManifest(
   opts: AgentDeploymentOpts,
 ): KubernetesDeployment {
   const name = sanitizeAgentName(opts.agentId);
+  const podLabels = validateAgentPodLabels(opts.podLabels ?? {});
   const tokenKey = opts.tokenSecretKey ?? "token";
   const volumeName = "agent-home";
 
@@ -513,9 +517,11 @@ export function buildAgentDeploymentManifest(
       selector: { matchLabels: selectorLabels },
       template: {
         metadata: {
-          labels: tenant
-            ? { ...selectorLabels, [TENANT_LABEL]: "true" }
-            : selectorLabels,
+          labels: {
+            ...selectorLabels,
+            ...podLabels,
+            ...(tenant ? { [TENANT_LABEL]: "true" } : {}),
+          },
           ...(policy?.hash
             ? { annotations: { [CLAUDE_POLICY_HASH_ANNOTATION]: policy.hash } }
             : {}),

package/src/agent-manifest.unit.test.ts

@@ -75,6 +75,35 @@ describe("buildAgentDeploymentManifest", () => {
     });
   });
 
+  it("adds configured pod labels without changing immutable selectors or identity labels", () => {
+    const base = buildAgentDeploymentManifest(deployOpts);
+    const podLabels = {
+      "vgs.io/service": "shipwright",
+      "vgs.io/team": "team-infrastructure",
+    };
+    const labeled = buildAgentDeploymentManifest({
+      ...deployOpts,
+      podLabels,
+      accountId: "account-1",
+    });
+    expect(labeled.spec.selector).toEqual(base.spec.selector);
+    expect(labeled.metadata).toEqual({
+      ...base.metadata,
+      labels: { ...base.metadata.labels, [TENANT_LABEL]: "true" },
+    });
+    expect(labeled.spec.template.metadata.labels).toEqual({
+      ...base.spec.template.metadata.labels,
+      ...podLabels,
+      [TENANT_LABEL]: "true",
+    });
+    expect(() =>
+      buildAgentDeploymentManifest({
+        ...deployOpts,
+        podLabels: { "app.kubernetes.io/instance": "other" },
+      }),
+    ).toThrow();
+  });
+
   it("sets the required env vars including a secretKeyRef token", () => {
     const d = buildAgentDeploymentManifest(deployOpts);
     const env = d.spec.template.spec.containers[0].env ?? [];

package/src/agent-pod-labels.ts

@@ -0,0 +1,53 @@
+/** Optional labels for agent pod templates; identity selectors stay platform-owned. */
+const RESERVED = new Set([
+  "app.kubernetes.io/name",
+  "app.kubernetes.io/instance",
+  "app.kubernetes.io/managed-by",
+  "shipwright.dev/agent-id",
+  "shipwright.dev/tenant",
+]);
+const NAME = /^[A-Za-z0-9]([A-Za-z0-9_.-]*[A-Za-z0-9])?$/;
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+export function validateAgentPodLabels(value: unknown): Record<string, string> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("SHIPWRIGHT_K8S_AGENT_POD_LABELS must be a JSON object");
+  }
+  for (const [key, label] of Object.entries(value)) {
+    const parts = key.split("/");
+    const name = parts.at(-1) ?? "";
+    const prefix = parts.length === 2 ? parts[0] : undefined;
+    if (
+      parts.length > 2 ||
+      name.length > 63 ||
+      !NAME.test(name) ||
+      (prefix !== undefined &&
+        (prefix.length > 253 ||
+          prefix
+            .split(".")
+            .some((part) => part.length > 63 || !DNS_LABEL.test(part)))) ||
+      RESERVED.has(key)
+    ) {
+      throw new Error(
+        `SHIPWRIGHT_K8S_AGENT_POD_LABELS has an invalid or reserved key: ${key}`,
+      );
+    }
+    if (
+      typeof label !== "string" ||
+      label.length > 63 ||
+      (label !== "" && !NAME.test(label))
+    ) {
+      throw new Error(
+        `SHIPWRIGHT_K8S_AGENT_POD_LABELS has an invalid value for ${key}`,
+      );
+    }
+  }
+  return { ...value } as Record<string, string>;
+}
+
+export function parseAgentPodLabels(
+  raw: string | undefined,
+): Record<string, string> | undefined {
+  if (raw === undefined || raw.trim() === "") return undefined;
+  return validateAgentPodLabels(JSON.parse(raw));
+}

package/src/agent-pod-labels.unit.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "bun:test";
+import {
+  parseAgentPodLabels,
+  validateAgentPodLabels,
+} from "./agent-pod-labels.ts";
+
+describe("agent pod label configuration", () => {
+  it("leaves unconfigured labels absent", () => {
+    expect(parseAgentPodLabels(undefined)).toBeUndefined();
+    expect(parseAgentPodLabels("  ")).toBeUndefined();
+    expect(parseAgentPodLabels("{}")).toEqual({});
+  });
+  it("accepts qualified keys, plain keys and Kubernetes label values", () => {
+    expect(
+      parseAgentPodLabels(
+        '{"vgs.io/team":"team-infrastructure","app":"shipwright","empty":""}',
+      ),
+    ).toEqual({
+      "vgs.io/team": "team-infrastructure",
+      app: "shipwright",
+      empty: "",
+    });
+  });
+  for (const raw of [
+    "null",
+    "[]",
+    "false",
+    "1",
+    "invalid",
+    '{"app":1}',
+    '{"app":null}',
+  ]) {
+    it(`rejects malformed config ${raw}`, () =>
+      expect(() => parseAgentPodLabels(raw)).toThrow());
+  }
+  for (const key of [
+    "",
+    "/app",
+    "UPPER.io/app",
+    "bad..io/app",
+    "a/b/c",
+    "a".repeat(64),
+    "app.kubernetes.io/name",
+    "app.kubernetes.io/instance",
+    "app.kubernetes.io/managed-by",
+    "shipwright.dev/agent-id",
+    "shipwright.dev/tenant",
+  ]) {
+    it(`rejects invalid or reserved key ${key}`, () =>
+      expect(() => validateAgentPodLabels({ [key]: "x" })).toThrow());
+  }
+  for (const value of [
+    "bad/value",
+    "bad value",
+    "-bad",
+    "bad-",
+    "x".repeat(64),
+  ]) {
+    it(`rejects invalid value ${value}`, () =>
+      expect(() => validateAgentPodLabels({ app: value })).toThrow());
+  }
+});

package/src/agent-provisioner.ts

@@ -239,6 +239,8 @@ export interface AgentProvisioner {
 // ─── Configuration ──────────────────────────────────────────────────────────
 
 export interface KubernetesAgentProvisionerConfig {
+  /** Additional labels managed on new and existing agent pod templates. */
+  podLabels?: Record<string, string>;
   /** Namespace the agent resources live in. */
   namespace: string;
   /** Agent container image (without tag). */
@@ -940,6 +942,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
       tokenSecretKey: this.tokenKey,
       replicas: this.config.replicas,
       resources: this.config.resources,
+      podLabels: this.config.podLabels,
       voice: this.config.voice,
       serviceIntegrations: provisionableIntegrations(
         this.config.serviceIntegrations,
@@ -1486,11 +1489,18 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
           );
           const desired = desiredDeployment.spec.template.spec.containers[0];
           const desiredLabels = desiredDeployment.spec.template.metadata.labels;
-          const labelsDrifted =
-            !policyOnly &&
-            desiredLabels[TENANT_LABEL] !== undefined &&
-            deployment.spec.template.metadata?.labels?.[TENANT_LABEL] !==
-              desiredLabels[TENANT_LABEL];
+          // Manage only configured keys; preserve labels owned by other actors.
+          // Startup policy reconciliation also propagates ownership labels.
+          const managedLabels = {
+            ...(this.config.podLabels ?? {}),
+            ...(!policyOnly && desiredLabels[TENANT_LABEL] !== undefined
+              ? { [TENANT_LABEL]: desiredLabels[TENANT_LABEL] }
+              : {}),
+          };
+          const labelsDrifted = Object.entries(managedLabels).some(
+            ([key, value]) =>
+              deployment.spec.template.metadata?.labels?.[key] !== value,
+          );
           const policy = policyPatch(deployment, desiredDeployment);
           // Unmanaged federation (see reconcileFederationFor): no patch, so
           // the live ServiceAccount, token volume and env are left alone.
@@ -1571,9 +1581,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
                   }
                 : {};
             const podMetadata = {
-              ...(labelsDrifted
-                ? { labels: { [TENANT_LABEL]: desiredLabels[TENANT_LABEL] } }
-                : {}),
+              ...(labelsDrifted ? { labels: managedLabels } : {}),
               ...(policy?.annotations
                 ? { annotations: policy.annotations }
                 : {}),
@@ -1583,7 +1591,9 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
                 this.config.namespace,
                 resourceName,
                 {
-                  ...(labelsDrifted
+                  ...(labelsDrifted &&
+                  !policyOnly &&
+                  desiredLabels[TENANT_LABEL] !== undefined
                     ? {
                         metadata: {
                           labels: {

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

@@ -2034,3 +2034,75 @@ describe("KubernetesAgentProvisioner.reconcile() — pod ServiceAccount drift (C
     expect(patches).toHaveLength(0);
   });
 });
+
+describe("KubernetesAgentProvisioner configured pod labels", () => {
+  const agentId = "agent-label-example";
+  const podLabels = {
+    "vgs.io/service": "shipwright",
+    "vgs.io/team": "team-infrastructure",
+  };
+  for (const policyOnly of [false, true]) {
+    it(`updates existing templates and preserves selectors/unrelated labels (policyOnly=${policyOnly})`, async () => {
+      const client = emptyClient();
+      const original = new KubernetesAgentProvisioner(
+        client,
+        stubTokens() as AgentTokenService,
+        BASE_CONFIG,
+      );
+      await original.provision(agentId);
+      const name = sanitizeAgentName(agentId);
+      const before = await client.getDeployment(NAMESPACE, name);
+      const selector = structuredClone(before.spec.selector);
+      await client.patchDeployment(NAMESPACE, name, {
+        spec: {
+          template: {
+            metadata: {
+              labels: {
+                "other.io/label": "preserved",
+                "vgs.io/team": "NOT_SET",
+              },
+            },
+          },
+        },
+      });
+      const next = new KubernetesAgentProvisioner(
+        client,
+        stubTokens() as AgentTokenService,
+        { ...BASE_CONFIG, podLabels },
+      );
+      const preview = await next.reconcile([{ id: agentId }], {
+        policyOnly,
+        dryRun: true,
+      });
+      expect(preview.updated).toEqual([agentId]);
+      expect(
+        (await client.getDeployment(NAMESPACE, name)).spec.template.metadata
+          .labels["vgs.io/team"],
+      ).toBe("NOT_SET");
+      expect(
+        (await next.reconcile([{ id: agentId }], { policyOnly })).updated,
+      ).toEqual([agentId]);
+      const after = await client.getDeployment(NAMESPACE, name);
+      expect(after.spec.selector).toEqual(selector);
+      expect(after.spec.template.metadata.labels).toMatchObject({
+        ...podLabels,
+        "other.io/label": "preserved",
+      });
+      expect(
+        (await next.reconcile([{ id: agentId }], { policyOnly })).updated,
+      ).toEqual([]);
+    });
+  }
+  it("gives newly provisioned agents the configured labels", async () => {
+    const client = emptyClient();
+    await new KubernetesAgentProvisioner(
+      client,
+      stubTokens() as AgentTokenService,
+      { ...BASE_CONFIG, podLabels },
+    ).provision(agentId);
+    expect(
+      (await client.getDeployment(NAMESPACE, sanitizeAgentName(agentId))).spec
+        .template.metadata.labels,
+    ).toMatchObject(podLabels);
+  });
+});

package/src/api.ts

@@ -66,7 +66,7 @@ export interface AgentConfigResponse {
    */
   accountStatus?: string | null;
   /**
-   * ARD-6.1: the agent's Specialty name (e.g. "coding"), read by the agent
+   * ARD-6.1: the agent's Specialty name (e.g. "specialist"), read by the agent
    * runtime to pick its workspace template directory.
    */
   specialty: string;

package/src/startup-policy-reconcile.ts

@@ -11,7 +11,9 @@
  * agents lose the mount after the policy is disabled. The same pass applies
  * the Anthropic workload identity federation wiring (ServiceAccount, projected
  * token volume, mount, federation env), so turning federation on or off and
- * restarting admin corrects existing agents.
+ * restarting admin corrects existing agents. Configured pod labels are also
+ * reconciled, preserving selectors and labels owned by other actors; changing
+ * a configured label rolls the affected agent through its Recreate strategy.
  *
  * The startup pass never moves agents onto their own per-agent identity: that
  * creates Anthropic and Kubernetes resources, which should not happen as a side