@app-vitals/agent-admin 0.4.0 → 0.6.0

package/src/agents-api.ts

@@ -39,7 +39,10 @@ import {
   getSelfServeSpecialty,
   isAccountCreateErrorCode,
 } from "./account-agent-create.ts";
-import { reconcileAgentAfterAccountChange } from "./agent-account-assignment.ts";
+import {
+  reconcileAgentAfterAccountChange,
+  reconcileAgentAfterPodServiceAccountChange,
+} from "./agent-account-assignment.ts";
 import {
   type AgentAskDeps,
   type AskChatClient,
@@ -62,7 +65,10 @@ import type { AgentEnvService } from "./agent-envs.ts";
 import type { AgentGitHubInstallationsService } from "./agent-github-installations.ts";
 import type { AgentMemberService } from "./agent-members.ts";
 import type { AgentPluginService } from "./agent-plugins.ts";
-import type { AgentProvisioner } from "./agent-provisioner.ts";
+import {
+  type AgentProvisioner,
+  hasPerAgentIdentity,
+} from "./agent-provisioner.ts";
 import type { AgentTokenService } from "./agent-tokens.ts";
 import type { AgentToolService } from "./agent-tools.ts";
 import type { AgentService } from "./agents.ts";
@@ -94,8 +100,10 @@ import {
 import {
   ApiError,
   BadRequestError,
+  ConflictError,
   ForbiddenError,
   NotFoundError,
+  UnprocessableEntityError,
 } from "./errors.ts";
 import {
   AddAgentReposBodySchema,
@@ -287,6 +295,12 @@ export interface AdminDeps {
   >;
   /** WIF-2.1: Anthropic federation is enabled; defaults to false. */
   anthropicFederationEnabled?: boolean;
+  /**
+   * COS-49.1: per-agent pod ServiceAccount flag
+   * (SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED). Off (default) -> PATCH
+   * /agents/:id with podServiceAccountName returns 409.
+   */
+  podServiceAccountEnabled?: boolean;
   /**
    * Agent-to-agent ask (COS-31.1): flag + allowlist config, the AgentAsk
    * audit store and an injectable clock. Absent or flag off → the ask routes
@@ -397,6 +411,8 @@ const GetAgentResultSchema = z
     patchAuthorAllowlist: z.array(z.string()),
     restrictSlackToMembers: z.boolean(),
     typeName: z.string(),
+    /** COS-49.1: the pod ServiceAccount; null when unset. */
+    podServiceAccountName: z.string().nullable(),
     /** Owning account; null for unassigned agents (task-store maps null to its 'default' account). */
     accountId: z.string().nullable(),
     createdAt: z.string().datetime(),
@@ -604,7 +620,7 @@ const patchAgentRoute = createRoute({
   path: "/agents/{id}",
   summary: "Update an agent",
   description:
-    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, and/or `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). `typeName` 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). `typeName` 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.",
   request: {
     params: AgentIdParamSchema,
     body: {
@@ -619,6 +635,16 @@ const patchAgentRoute = createRoute({
     400: { description: "Bad request", ...jsonError },
     403: { description: "Forbidden", ...jsonError },
     404: { description: "Agent not found", ...jsonError },
+    409: {
+      description:
+        "podServiceAccountName supplied while the pod ServiceAccount flag is off",
+      ...jsonError,
+    },
+    422: {
+      description:
+        "podServiceAccountName supplied for an agent with a per-agent federated identity",
+      ...jsonError,
+    },
   },
 });
 
@@ -1657,6 +1683,39 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
         throw new ForbiddenError("Admin access required to change accountId");
       }
     }
+    // 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;
+    if (body.podServiceAccountName !== undefined) {
+      if (c.get("isAdmin") !== true) {
+        throw new ForbiddenError(
+          "Admin access required to change podServiceAccountName",
+        );
+      }
+      if (deps.podServiceAccountEnabled !== true) {
+        throw new ConflictError(
+          "podServiceAccountName cannot be changed: SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is not enabled",
+        );
+      }
+      const current = await agentService.getDetail(agentId);
+      if (!current) {
+        throw new NotFoundError(`agent ${agentId} not found`);
+      }
+      if (
+        hasPerAgentIdentity({
+          ownerEmail: current.ownerEmail ?? null,
+          anthropicIdentityName: current.anthropicIdentityName ?? null,
+          anthropicServiceAccountId: current.anthropicServiceAccountId ?? null,
+          anthropicFederationRuleId: current.anthropicFederationRuleId ?? null,
+          k8sServiceAccountName: current.k8sServiceAccountName ?? null,
+        })
+      ) {
+        throw new UnprocessableEntityError(
+          "podServiceAccountName cannot be set on an agent with a per-agent federated identity (federation owns its ServiceAccount)",
+        );
+      }
+      previousPodServiceAccountName = current.podServiceAccountName ?? null;
+    }
     const collision =
       body.repos !== undefined ? describeRepoNameCollision(body.repos) : null;
     if (collision) {
@@ -1665,6 +1724,9 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
     const agent = await agentService
       .updateSelfHosted(agentId, {
         selfHosted: body.selfHosted,
+        ...(body.podServiceAccountName !== undefined
+          ? { podServiceAccountName: body.podServiceAccountName }
+          : {}),
         ...(body.accountId !== undefined ? { accountId: body.accountId } : {}),
         ...(body.repos !== undefined ? { repos: body.repos } : {}),
         ...(body.reviewAuthorAllowlist !== undefined
@@ -1719,8 +1781,24 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       body.accountId !== undefined
         ? await reconcileAgentAfterAccountChange(provisioner, agent)
         : undefined;
+    let podSaWarning: string | undefined;
+    if (body.podServiceAccountName !== undefined) {
+      // Audit: ids and names only — never the caller's key.
+      console.info(
+        `[agents-api] podServiceAccountName changed: agent=${agentId} old=${previousPodServiceAccountName ?? "null"} new=${body.podServiceAccountName ?? "null"} caller=${c.get("caller")?.name ?? "anonymous"}`,
+      );
+      if (body.podServiceAccountName !== previousPodServiceAccountName) {
+        podSaWarning = await reconcileAgentAfterPodServiceAccountChange(
+          provisioner,
+          agent,
+          previousPodServiceAccountName,
+        );
+      }
+    }
     const warning =
-      [slackWarning, reconcileWarning].filter(Boolean).join("; ") || undefined;
+      [slackWarning, reconcileWarning, podSaWarning]
+        .filter(Boolean)
+        .join("; ") || undefined;
     return c.json(serializeAgent(agent, warning), 200);
   });
 
@@ -2510,6 +2588,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
     const snapshot = await agentGitHubInstallationsService.push(agentId, {
       reportedAt: new Date(body.reportedAt),
       installations: body.installations,
+      repoAccess: body.repos,
     });
     return c.json(
       { snapshot: serializeGitHubInstallationsSnapshot(snapshot) },
@@ -2738,6 +2817,7 @@ function serializeAgent(
     restrictSlackToMembers?: boolean;
     typeName: string;
     accountId?: string | null;
+    podServiceAccountName?: string | null;
     createdAt: Date;
     updatedAt: Date;
     missingRequiredEnv?: string[];
@@ -2767,6 +2847,7 @@ function serializeAgent(
     restrictSlackToMembers: agent.restrictSlackToMembers ?? false,
     typeName: agent.typeName,
     accountId: agent.accountId ?? null,
+    podServiceAccountName: agent.podServiceAccountName ?? null,
     createdAt: agent.createdAt.toISOString(),
     updatedAt: agent.updatedAt.toISOString(),
     missingRequiredEnv: agent.missingRequiredEnv ?? [],
@@ -2814,6 +2895,7 @@ function serializeGitHubInstallationsSnapshot(snapshot: {
   agentId: string;
   reportedAt: Date;
   installations: unknown;
+  repoAccess: unknown;
   createdAt: Date;
 }): z.infer<typeof AgentGitHubInstallationsSnapshotSchema> {
   return {
@@ -2823,6 +2905,9 @@ function serializeGitHubInstallationsSnapshot(snapshot: {
     installations: snapshot.installations as z.infer<
       typeof AgentGitHubInstallationsSnapshotSchema
     >["installations"],
+    repoAccess: (snapshot.repoAccess ?? null) as z.infer<
+      typeof AgentGitHubInstallationsSnapshotSchema
+    >["repoAccess"],
     createdAt: snapshot.createdAt.toISOString(),
   };
 }

package/src/agents.ts

@@ -87,6 +87,8 @@ export interface AgentSummary extends Partial<AgentAnthropicIdentity> {
 }
 
 export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
+  /** COS-49.1 pod ServiceAccount; null when unset. */
+  podServiceAccountName?: string | null;
   id: string;
   name: string;
   slackId: string | null;
@@ -137,6 +139,8 @@ export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
 }
 
 interface UpdateSelfHostedInput {
+  /** COS-49.1: pod ServiceAccount; null clears it. */
+  podServiceAccountName?: string | null;
   /** SSP-5.3: owning account; null clears it (unassigned/platform agent). */
   accountId?: string | null;
   /**
@@ -472,6 +476,9 @@ export class AgentService {
         ...(input.accountId !== undefined
           ? { accountId: input.accountId }
           : {}),
+        ...(input.podServiceAccountName !== undefined
+          ? { podServiceAccountName: input.podServiceAccountName }
+          : {}),
         ...(input.repos !== undefined ? { repos: input.repos } : {}),
         ...(input.reviewAuthorAllowlist !== undefined
           ? { reviewAuthorAllowlist: input.reviewAuthorAllowlist }

package/src/api.smoke.test.ts

@@ -239,6 +239,7 @@ function buildApp(opts?: {
   cleanupMergedWorktrees?: boolean;
   cleanupAfterDays?: number;
   transcriptUploadEnabled?: boolean;
+  repoAccessCheckEnabled?: boolean;
 }) {
   const hasAgent = opts?.hasAgent ?? true;
   const bundle: AgentEnvBundle | null =
@@ -312,6 +313,7 @@ function buildApp(opts?: {
     sessionSecret: SESSION_SECRET,
     anthropicFederationEnabled: opts?.anthropicFederationEnabled,
     transcriptUploadEnabled: opts?.transcriptUploadEnabled,
+    repoAccessCheckEnabled: opts?.repoAccessCheckEnabled,
   });
 }
 
@@ -355,6 +357,19 @@ describe("GET /:id/config features (COS-43.1)", () => {
   });
 });
 
+describe("GET /:id/config features.repoAccessCheck (COS-44.1)", () => {
+  test("follows the repo-access flag", async () => {
+    const app = buildApp({ repoAccessCheckEnabled: true });
+    const res = await app.request(`/${KNOWN_AGENT_ID}/config`, {
+      headers: { Authorization: `Bearer ${VALID_ADMIN_KEY}` },
+    });
+    expect((await res.json()).features).toEqual({
+      transcriptUpload: false,
+      repoAccessCheck: true,
+    });
+  });
+});
+
 describe("GET /:id/config (mounted as GET /agents/:id/config from root)", () => {
   test("200 with full bundle when agent exists with env vars, tools, plugins", async () => {
     const app = buildApp();

package/src/api.ts

@@ -179,6 +179,11 @@ export interface AgentRuntimeDeps {
    * as `features.transcriptUpload` in the config bundle. Defaults to false.
    */
   transcriptUploadEnabled?: boolean;
+  /**
+   * COS-44.1: SHIPWRIGHT_AGENT_REPO_ACCESS_CHECK_ENABLED is on — surfaced to the
+   * runtime as `features.repoAccessCheck` in the config bundle. Defaults to false.
+   */
+  repoAccessCheckEnabled?: boolean;
 }
 
 // ─── Route definitions ────────────────────────────────────────────────────────
@@ -352,10 +357,9 @@ export function createAgentRuntimeApp(deps: AgentRuntimeDeps): OpenAPIHono {
       maxFindings: agent.maxFindings,
       cleanupMergedWorktrees: agent.cleanupMergedWorktrees,
       cleanupAfterDays: agent.cleanupAfterDays,
-      // COS-43.1: repoAccessCheck is wired by COS-44.1; false until then.
       features: {
         transcriptUpload: deps.transcriptUploadEnabled === true,
-        repoAccessCheck: false,
+        repoAccessCheck: deps.repoAccessCheckEnabled === true,
       },
     };
 

package/src/kubernetes-client.unit.test.ts

@@ -510,6 +510,28 @@ describe("RecordedKubernetesClient.patchDeployment()", () => {
     );
   });
 
+  it("strategic-merges serviceAccountName: a string sets, null clears (with the alias)", async () => {
+    const rec = new RecordedKubernetesClient({
+      deployments: { "shipwright/agent-abc": makeDeployment("img:v1") },
+      secrets: {},
+    });
+    const patchSa = (podSpec: object) =>
+      rec.patchDeployment("shipwright", "agent-abc", {
+        spec: { template: { spec: podSpec } },
+      });
+    const podSpec = async () =>
+      (await rec.getDeployment("shipwright", "agent-abc")).spec.template.spec;
+
+    await patchSa({ serviceAccountName: "agent-sa" });
+    expect((await podSpec()).serviceAccountName).toBe("agent-sa");
+    // Untouched containers survive a pod-level-only patch.
+    expect((await podSpec()).containers[0]?.image).toBe("img:v1");
+
+    await patchSa({ serviceAccountName: null, serviceAccount: null });
+    expect((await podSpec()).serviceAccountName).toBeUndefined();
+    expect((await podSpec()).serviceAccount).toBeUndefined();
+  });
+
   it("throws NotFoundError when the deployment does not exist", async () => {
     const rec = new RecordedKubernetesClient({ deployments: {}, secrets: {} });
 

package/src/openapi-schemas.ts

@@ -94,6 +94,22 @@ export const PatchAgentBodySchema = z
       .nullable()
       .optional()
       .openapi({ example: "acct_123" }),
+    /**
+     * COS-49.1: the Kubernetes ServiceAccount the agent's pod runs as
+     * (RFC 1123 label). Platform admin only; `null` clears it. Rejected 409
+     * unless SHIPWRIGHT_K8S_AGENT_POD_SERVICE_ACCOUNT_ENABLED is on, and 422
+     * for agents with a per-agent federated identity.
+     */
+    podServiceAccountName: z
+      .string()
+      .max(63)
+      .regex(
+        /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/,
+        "must be an RFC 1123 label (lowercase alphanumerics and '-', start and end alphanumeric)",
+      )
+      .nullable()
+      .optional()
+      .openapi({ example: "agent-pod-sa" }),
     /**
      * ATE-1.1: trial expiry timestamp. Nullable so it can also be explicitly
      * cleared. trialExpiryWarnedAt is intentionally NOT part of this schema —
@@ -953,6 +969,33 @@ const GitHubInstallationSchema = z
   .strict()
   .openapi("GitHubInstallation");
 
+/**
+ * One per-repo access probe result (COS-44.1). CLOSED (.strict()) like the
+ * installation schema: tokens and other credentials are rejected, never stored.
+ * `error` is a fixed class, not free text.
+ */
+const RepoAccessEntrySchema = z
+  .object({
+    repo: z.string().min(1).max(200).openapi({ example: "agent" }),
+    owner: z.string().min(1).max(200).openapi({ example: "app-vitals" }),
+    read: z.boolean().openapi({ example: true }),
+    write: z.boolean().openapi({ example: false }),
+    checkedAt: z
+      .string()
+      .datetime()
+      .openapi({ example: "2026-01-01T00:00:00.000Z" }),
+    error: z
+      .enum(["not_found", "forbidden", "rate_limited", "network"])
+      .optional()
+      .openapi({
+        description:
+          "Why the probe could not read the repo; absent when the probe succeeded.",
+        example: "not_found",
+      }),
+  })
+  .strict()
+  .openapi("RepoAccessEntry");
+
 /**
  * PUT /agents/:id/github-installations body. Replace-all: the installations
  * array overwrites whatever was previously stored.
@@ -964,6 +1007,10 @@ export const PutGitHubInstallationsBodySchema = z
       .datetime()
       .openapi({ example: "2026-01-01T00:00:00.000Z" }),
     installations: z.array(GitHubInstallationSchema),
+    repos: z.array(RepoAccessEntrySchema).optional().openapi({
+      description:
+        "Per-repo access probe result (COS-44.1). Omit to leave the stored result unchanged; send [] to clear it.",
+    }),
   })
   .strict()
   .openapi("PutGitHubInstallationsBody");
@@ -977,6 +1024,10 @@ export const AgentGitHubInstallationsSnapshotSchema = z
       .datetime()
       .openapi({ example: "2026-01-01T00:00:00.000Z" }),
     installations: z.array(GitHubInstallationSchema),
+    repoAccess: z.array(RepoAccessEntrySchema).nullable().openapi({
+      description:
+        "Latest per-repo access probe result; null until a runtime with the repo-access check enabled reports one.",
+    }),
     createdAt: z
       .string()
       .datetime()

package/src/openapi-schemas.unit.test.ts

@@ -17,6 +17,7 @@ import {
   type AgentTool,
   AgentToolSchema,
   ErrorSchema,
+  PatchAgentBodySchema,
 } from "./openapi-schemas.ts";
 
 // ─── Fixtures ─────────────────────────────────────────────────────────────────
@@ -350,3 +351,33 @@ describe("OpenAPI route metadata", () => {
     expect(issues).toEqual([]);
   });
 });
+
+describe("PatchAgentBodySchema.podServiceAccountName (COS-49.1)", () => {
+  const parse = (v: unknown) =>
+    PatchAgentBodySchema.safeParse({ podServiceAccountName: v });
+
+  test("accepts RFC 1123 labels", () => {
+    for (const ok of ["a", "agent-sa", "sa1", "a".repeat(63)]) {
+      expect(parse(ok).success).toBe(true);
+    }
+  });
+
+  test("accepts null (clear) and omission", () => {
+    expect(parse(null).success).toBe(true);
+    expect(PatchAgentBodySchema.safeParse({}).success).toBe(true);
+  });
+
+  test("rejects non-labels and values over 63 characters", () => {
+    for (const bad of [
+      "",
+      "Upper",
+      "under_score",
+      "-lead",
+      "trail-",
+      "dot.ted",
+      "a".repeat(64),
+    ]) {
+      expect(parse(bad).success).toBe(false);
+    }
+  });
+});

package/src/repo-access-config.ts

@@ -0,0 +1,22 @@
+/**
+ * admin/src/repo-access-config.ts
+ *
+ * Pure parser for the per-repo GitHub access check flag (COS-44.1). Takes an
+ * injected env object (no process.env reads) so it is deterministically
+ * unit-testable; admin-boot reads it once at startup and feeds it into the
+ * config bundle as `features.repoAccessCheck`. Same "enabled" convention as
+ * transcript-config.ts.
+ */
+
+type RepoAccessEnv = Readonly<Record<string, string | undefined>>;
+
+export interface RepoAccessConfig {
+  /** True only when SHIPWRIGHT_AGENT_REPO_ACCESS_CHECK_ENABLED === "enabled". */
+  enabled: boolean;
+}
+
+export function parseRepoAccessConfig(env: RepoAccessEnv): RepoAccessConfig {
+  return {
+    enabled: env.SHIPWRIGHT_AGENT_REPO_ACCESS_CHECK_ENABLED === "enabled",
+  };
+}

package/src/repo-access-config.unit.test.ts

@@ -0,0 +1,34 @@
+/**
+ * admin/src/repo-access-config.unit.test.ts
+ * Pure flag parser for the per-repo GitHub access check (COS-44.1).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { parseRepoAccessConfig } from "./repo-access-config.ts";
+
+describe("parseRepoAccessConfig", () => {
+  it('is on only for the literal "enabled"', () => {
+    expect(
+      parseRepoAccessConfig({
+        SHIPWRIGHT_AGENT_REPO_ACCESS_CHECK_ENABLED: "enabled",
+      }).enabled,
+    ).toBe(true);
+  });
+
+  it("every other value is off", () => {
+    for (const v of [
+      "true",
+      "",
+      "Enabled",
+      " enabled",
+      "disabled",
+      undefined,
+    ]) {
+      expect(
+        parseRepoAccessConfig({ SHIPWRIGHT_AGENT_REPO_ACCESS_CHECK_ENABLED: v })
+          .enabled,
+      ).toBe(false);
+    }
+    expect(parseRepoAccessConfig({}).enabled).toBe(false);
+  });
+});