@app-vitals/agent-admin 0.1.2 → 0.2.0

package/src/agent-manifest.ts

@@ -318,6 +318,24 @@ export interface AgentDeploymentOpts {
    * federation). Omit for an unchanged manifest.
    */
   anthropicFederation?: AgentAnthropicFederation;
+  /**
+   * Per-agent pod ServiceAccount (COS-48.1). When set (and `anthropicFederation`
+   * is absent) the pod runs as this ServiceAccount. Mutually exclusive with
+   * `anthropicFederation`: federation's projected token subject must stay its
+   * own ServiceAccount, so supplying both throws
+   * PodServiceAccountConflictError. Omit for an unchanged manifest.
+   */
+  podServiceAccountName?: string;
+}
+
+/** Both a pod ServiceAccount and Anthropic federation were supplied. */
+export class PodServiceAccountConflictError extends Error {
+  constructor(agentId: string) {
+    super(
+      `agent ${agentId}: podServiceAccountName cannot be combined with anthropicFederation (the federation token subject must stay its own ServiceAccount)`,
+    );
+    this.name = "PodServiceAccountConflictError";
+  }
 }
 
 /**
@@ -479,6 +497,9 @@ export function buildAgentDeploymentManifest(
 
   const policy = opts.claudePolicy;
   const federation = opts.anthropicFederation;
+  if (federation && opts.podServiceAccountName) {
+    throw new PodServiceAccountConflictError(opts.agentId);
+  }
 
   return {
     apiVersion: "apps/v1",
@@ -507,7 +528,9 @@ export function buildAgentDeploymentManifest(
           // Federation: the projected token's subject is this ServiceAccount.
           ...(federation
             ? { serviceAccountName: federation.serviceAccountName }
-            : {}),
+            : opts.podServiceAccountName
+              ? { serviceAccountName: opts.podServiceAccountName }
+              : {}),
           securityContext: {
             fsGroup: AGENT_RUN_AS,
             fsGroupChangePolicy: "OnRootMismatch",

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

@@ -17,6 +17,7 @@ import {
   buildAgentSecretManifest,
   resolveAgentContainerResources,
   sanitizeAgentName,
+  PodServiceAccountConflictError,
   TENANT_LABEL,
 } from "./agent-manifest.ts";
 
@@ -868,3 +869,59 @@ describe("buildAgentDeploymentManifest — anthropic federation", () => {
     expect(base).not.toContain("ANTHROPIC_");
   });
 });
+
+describe("buildAgentDeploymentManifest — pod service account", () => {
+  const anthropicFederation = {
+    serviceAccountName: "shipwright-agent",
+    ruleId: "fdrl_123",
+    organizationId: "org-uuid",
+    serviceAccountId: "svac_456",
+    audience: "https://api.anthropic.com",
+    expirationSeconds: 600,
+  };
+
+  it("sets spec.template.spec.serviceAccountName from the option", () => {
+    const d = buildAgentDeploymentManifest({
+      ...deployOpts,
+      podServiceAccountName: "agent-sa",
+    });
+    expect(d.spec.template.spec.serviceAccountName).toBe("agent-sa");
+  });
+
+  it("omits serviceAccountName entirely when undefined", () => {
+    const d = buildAgentDeploymentManifest({
+      ...deployOpts,
+      podServiceAccountName: undefined,
+    });
+    expect("serviceAccountName" in d.spec.template.spec).toBe(false);
+  });
+
+  it("leaves the base manifest byte-identical when the option is absent", () => {
+    expect(
+      JSON.stringify(
+        buildAgentDeploymentManifest({
+          ...deployOpts,
+          podServiceAccountName: undefined,
+        }),
+      ),
+    ).toBe(JSON.stringify(buildAgentDeploymentManifest(deployOpts)));
+  });
+
+  it("throws a typed error when federation is also supplied", () => {
+    expect(() =>
+      buildAgentDeploymentManifest({
+        ...deployOpts,
+        podServiceAccountName: "agent-sa",
+        anthropicFederation,
+      }),
+    ).toThrow(PodServiceAccountConflictError);
+  });
+
+  it("keeps the federation service account when only federation is set", () => {
+    const d = buildAgentDeploymentManifest({
+      ...deployOpts,
+      anthropicFederation,
+    });
+    expect(d.spec.template.spec.serviceAccountName).toBe("shipwright-agent");
+  });
+});

package/src/agent-pod-service-account.integration.test.ts

@@ -0,0 +1,47 @@
+/**
+ * admin/src/agent-pod-service-account.integration.test.ts
+ * COS-48.1: the Agent.podServiceAccountName column exists, is nullable and is
+ * independent of k8sServiceAccountName. Requires DATABASE_URL_ADMIN_TEST;
+ * skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+describeOrSkip("Agent.podServiceAccountName (integration)", () => {
+  let prisma: PrismaClient;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.agentPhaseMethodology.deleteMany();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agent.deleteMany();
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("defaults to null for a new agent", async () => {
+    const agent = await prisma.agent.create({ data: { name: "A" } });
+    expect(agent.podServiceAccountName).toBeNull();
+  });
+
+  it("round-trips without touching k8sServiceAccountName", async () => {
+    const agent = await prisma.agent.create({
+      data: { name: "A", podServiceAccountName: "agent-a-sa" },
+    });
+    const row = await prisma.agent.findUniqueOrThrow({
+      where: { id: agent.id },
+    });
+    expect(row.podServiceAccountName).toBe("agent-a-sa");
+    expect(row.k8sServiceAccountName).toBeNull();
+  });
+});

package/src/agent-provisioner.ts

@@ -80,6 +80,7 @@ import type {
   PvcSpec,
   SecretSpec,
 } from "./kubernetes-client.ts";
+import type { PodServiceAccountConfig } from "./pod-service-account-config.ts";
 import {
   provisionableIntegrations,
   type ServiceIntegration,
@@ -148,6 +149,8 @@ export interface ReconcileTarget extends Partial<AgentAnthropicIdentity> {
   id: string;
   slug?: string;
   accountId?: string | null;
+  /** The Agent row's pod ServiceAccount (COS-48.1); rendered only when the flag is on. */
+  podServiceAccountName?: string | null;
 }
 
 export interface AgentProvisioner {
@@ -163,7 +166,11 @@ export interface AgentProvisioner {
   /** Mint a token and create the agent's Secret + Deployment. Idempotent. */
   provision(
     agentId: string,
-    opts?: { slug?: string; accountId?: string | null },
+    opts?: {
+      slug?: string;
+      accountId?: string | null;
+      podServiceAccountName?: string | null;
+    },
   ): Promise<ProvisionResult>;
   /**
    * Delete the agent's Deployment, Secret, and PVC. Tolerates already-absent
@@ -304,6 +311,12 @@ export interface KubernetesAgentProvisionerConfig {
    * exclusive with `anthropicFederation` (shared mode).
    */
   perAgentIdentity?: PerAgentIdentityConfig;
+  /**
+   * Per-agent pod ServiceAccount flag (COS-48.1). Only when `enabled` is the
+   * Agent row's podServiceAccountName passed to the manifest; absent or off
+   * means the value is never rendered, even if set in the DB.
+   */
+  podServiceAccount?: PodServiceAccountConfig;
 }
 
 // ─── perAgent identity ──────────────────────────────────────────────────────
@@ -841,6 +854,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
     slug: string | undefined,
     accountId: string | null | undefined,
     federation: AgentAnthropicFederation | undefined,
+    podServiceAccountName?: string | null,
   ) {
     const resourceName = this.resourceName(agentId);
     return buildAgentDeploymentManifest({
@@ -862,12 +876,19 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
       claudePolicy: this.config.claudePolicy,
       anthropicFederation: federation,
       accountId,
+      ...(this.config.podServiceAccount?.enabled && podServiceAccountName
+        ? { podServiceAccountName }
+        : {}),
     });
   }
 
   async provision(
     agentId: string,
-    opts?: { slug?: string; accountId?: string | null },
+    opts?: {
+      slug?: string;
+      accountId?: string | null;
+      podServiceAccountName?: string | null;
+    },
   ): Promise<ProvisionResult> {
     const resourceName = this.resourceName(agentId);
     const secretName = this.secretNameFor(resourceName);
@@ -1074,7 +1095,13 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
   /** Steps 2–4: token(s) → Secret → Deployment (the original provision flow). */
   private async provisionSecretAndDeployment(
     agentId: string,
-    opts: { slug?: string; accountId?: string | null } | undefined,
+    opts:
+      | {
+          slug?: string;
+          accountId?: string | null;
+          podServiceAccountName?: string | null;
+        }
+      | undefined,
     result: ProvisionResult,
     federation: AgentAnthropicFederation | undefined,
   ): Promise<ProvisionResult> {
@@ -1166,6 +1193,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
           opts?.slug,
           opts?.accountId,
           federation,
+          opts?.podServiceAccountName,
         ),
       );
     } catch (err) {
@@ -1312,6 +1340,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
             await this.provision(agent.id, {
               slug: agent.slug,
               accountId: agent.accountId,
+              podServiceAccountName: agent.podServiceAccountName,
             });
           }
           recreated.push(agent.id);
@@ -1376,6 +1405,7 @@ export class KubernetesAgentProvisioner implements AgentProvisioner {
             agent.slug,
             agent.accountId,
             desiredFederation,
+            agent.podServiceAccountName,
           );
           const desired = desiredDeployment.spec.template.spec.containers[0];
           const desiredLabels = desiredDeployment.spec.template.metadata.labels;

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

@@ -1850,3 +1850,51 @@ describe("perAgentFederation()", () => {
     ).toBe(false);
   });
 });
+
+describe("KubernetesAgentProvisioner — pod service account (COS-48.1)", () => {
+  const agentId = "cmqalfjcm000m4101iharq28k";
+  const resourceName = sanitizeAgentName(agentId);
+
+  async function desiredSa(
+    config: KubernetesAgentProvisionerConfig,
+    target: { podServiceAccountName?: string | null },
+  ) {
+    const k8s = new RecordedKubernetesClient({
+      deployments: {},
+      secrets: {},
+      pvcs: {},
+    });
+    const provisioner = new KubernetesAgentProvisioner(
+      k8s,
+      stubTokens() as AgentTokenService,
+      config,
+    );
+    await provisioner.reconcile([{ id: agentId, ...target }]);
+    const dep = await k8s.getDeployment(NAMESPACE, resourceName);
+    return dep.spec.template.spec.serviceAccountName;
+  }
+
+  it("renders the Agent row value when the flag is on", async () => {
+    expect(
+      await desiredSa(
+        { ...BASE_CONFIG, podServiceAccount: { enabled: true } },
+        { podServiceAccountName: "agent-sa" },
+      ),
+    ).toBe("agent-sa");
+  });
+
+  it("never renders the Agent row value when the flag is off", async () => {
+    expect(
+      await desiredSa(
+        { ...BASE_CONFIG, podServiceAccount: { enabled: false } },
+        { podServiceAccountName: "agent-sa" },
+      ),
+    ).toBeUndefined();
+  });
+
+  it("never renders the value when no flag config is supplied", async () => {
+    expect(
+      await desiredSa(BASE_CONFIG, { podServiceAccountName: "agent-sa" }),
+    ).toBeUndefined();
+  });
+});

package/src/agents.ts

@@ -76,6 +76,8 @@ export interface AgentRecord {
  * strips them from its response.
  */
 export interface AgentSummary extends Partial<AgentAnthropicIdentity> {
+  /** COS-48.1 pod ServiceAccount (read by reconcile when the flag is on). */
+  podServiceAccountName?: string | null;
   id: string;
   name: string;
   selfHosted: boolean;
@@ -255,6 +257,7 @@ const SUMMARY_SELECT = {
   anthropicServiceAccountId: true,
   anthropicFederationRuleId: true,
   k8sServiceAccountName: true,
+  podServiceAccountName: true,
 } as const;
 
 const DETAIL_SELECT = {
@@ -287,6 +290,7 @@ const DETAIL_SELECT = {
   anthropicServiceAccountId: true,
   anthropicFederationRuleId: true,
   k8sServiceAccountName: true,
+  podServiceAccountName: true,
 } as const;
 
 // ─── Service ──────────────────────────────────────────────────────────────────

package/src/main.unit.test.ts

@@ -79,6 +79,25 @@ describe("resolvePublicRepo", () => {
 // ─── buildProvisioner ───────────────────────────────────────────────────────
 
 describe("buildProvisioner", () => {
+  it("wires the pod ServiceAccount flag into the provisioner config", () => {
+    const on = buildProvisioner(
+      {
+        SHIPWRIGHT_K8S_PROVISIONING: "enabled",
+        SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED: "enabled",
+      },
+      stubAgentTokenService(),
+    );
+    expect(configOf(on).podServiceAccount).toEqual({ enabled: true });
+  });
+
+  it("leaves the pod ServiceAccount flag off by default", () => {
+    const off = buildProvisioner(
+      { SHIPWRIGHT_K8S_PROVISIONING: "enabled" },
+      stubAgentTokenService(),
+    );
+    expect(configOf(off).podServiceAccount).toEqual({ enabled: false });
+  });
+
   it("returns a NoopAgentProvisioner when SHIPWRIGHT_K8S_PROVISIONING is unset", () => {
     const provisioner = buildProvisioner({}, stubAgentTokenService());
     expect(provisioner).toBeInstanceOf(NoopAgentProvisioner);

package/src/pod-service-account-config.ts

@@ -0,0 +1,24 @@
+/**
+ * admin/src/pod-service-account-config.ts
+ *
+ * Pure parser for the per-agent pod ServiceAccount flag (COS-48.1). Takes an
+ * injected env object (no process.env reads) so it is deterministically
+ * unit-testable; admin-boot-config threads the resolved config into the
+ * provisioner. Same "enabled" convention as agent-ask-config.ts.
+ */
+
+/** Structural env shape — accepts `process.env` or a plain test object. */
+type PodServiceAccountEnv = Readonly<Record<string, string | undefined>>;
+
+export interface PodServiceAccountConfig {
+  /** True only when SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED === "enabled". */
+  enabled: boolean;
+}
+
+export function parsePodServiceAccountConfig(
+  env: PodServiceAccountEnv,
+): PodServiceAccountConfig {
+  return {
+    enabled: env.SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED === "enabled",
+  };
+}

package/src/pod-service-account-config.unit.test.ts

@@ -0,0 +1,28 @@
+/**
+ * admin/src/pod-service-account-config.unit.test.ts
+ * Pure parser tests for the per-agent pod ServiceAccount flag (COS-48.1).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { parsePodServiceAccountConfig } from "./pod-service-account-config.ts";
+
+describe("parsePodServiceAccountConfig", () => {
+  it('is on only for the literal "enabled"', () => {
+    expect(
+      parsePodServiceAccountConfig({
+        SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED: "enabled",
+      }).enabled,
+    ).toBe(true);
+  });
+
+  it('"true", "1", "Enabled", padded, empty and absent are off', () => {
+    for (const value of ["true", "1", "Enabled", " enabled", "", undefined]) {
+      expect(
+        parsePodServiceAccountConfig({
+          SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED: value,
+        }).enabled,
+      ).toBe(false);
+    }
+    expect(parsePodServiceAccountConfig({}).enabled).toBe(false);
+  });
+});

package/src/startup-policy-reconcile.ts

@@ -50,6 +50,7 @@ export function managedReconcileTargets(
       anthropicServiceAccountId: a.anthropicServiceAccountId,
       anthropicFederationRuleId: a.anthropicFederationRuleId,
       k8sServiceAccountName: a.k8sServiceAccountName,
+      podServiceAccountName: a.podServiceAccountName,
     }));
 }