@app-vitals/agent-admin 1.14.0 → 1.16.0

package/src/agent-github-username.integration.test.ts

@@ -0,0 +1,202 @@
+/**
+ * admin/src/agent-github-username.integration.test.ts
+ * Integration tests for the Agent.githubUsername column (GHE-2.1) 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 { 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 type {
+  SpecialtyType,
+  SpecialtyTypeResolver,
+} 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",
+  );
+}
+
+function makePrisma(): PrismaClient {
+  // TEST_DB is guaranteed set — the describe block is skipped otherwise.
+  return createAdminPrismaClient(TEST_DB as string);
+}
+
+const CODING_TYPE: SpecialtyType = {
+  name: "coding",
+  displayName: "Coding Agent",
+  templatesDir: "workspace/",
+  tools: ["Read", "Write", "Edit"],
+  requiredEnv: [],
+};
+
+function fakeSpecialtyTypes(): SpecialtyTypeResolver {
+  const byType: Record<string, SpecialtyType> = { coding: CODING_TYPE };
+  return {
+    getType(specialty: string): SpecialtyType {
+      return byType[specialty] ?? (byType.coding as SpecialtyType);
+    },
+    tryGetType(specialty: string): SpecialtyType | undefined {
+      return byType[specialty];
+    },
+    listTypes() {
+      return Object.entries(byType).map(([name, manifest]) => ({
+        name,
+        displayName: manifest.displayName,
+      }));
+    },
+  };
+}
+
+function makeDeps(prisma: PrismaClient): AdminDeps {
+  const savedKey = process.env.SHIPWRIGHT_ENCRYPTION_KEY;
+  process.env.SHIPWRIGHT_ENCRYPTION_KEY = REAL_KEY;
+  const crypto = makeTokenCrypto();
+  if (savedKey === undefined) {
+    delete process.env.SHIPWRIGHT_ENCRYPTION_KEY;
+  } else {
+    process.env.SHIPWRIGHT_ENCRYPTION_KEY = savedKey;
+  }
+
+  return {
+    agentService: new AgentService(prisma),
+    agentEnvService: new AgentEnvService(prisma, crypto),
+    agentCronJobService: new AgentCronJobService(prisma),
+    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: fakeSpecialtyTypes(),
+    agentChatTokenService: new AgentChatTokenService(prisma),
+    agentGitHubInstallationsService: new AgentGitHubInstallationsService(
+      prisma,
+    ),
+    prisma,
+    provisioner: new NoopAgentProvisioner(),
+    serviceIntegrations: [
+      {
+        name: "task-store",
+        listTokensForAgent: async () => [],
+        revokeToken: async () => {},
+      },
+    ],
+    chatService: new NoopChatServiceProvisioningClient(),
+    slack: {
+      deleteApp: async () => {},
+    },
+    decrypt: (value: string) => crypto.decrypt(value),
+    sessionSecret: SESSION_SECRET,
+  };
+}
+
+describeOrSkip("Agent.githubUsername (integration)", () => {
+  let prisma: PrismaClient;
+
+  beforeEach(async () => {
+    prisma = makePrisma();
+    await prisma.agentWorkQueueSnapshot.deleteMany();
+    await prisma.agentPlugin.deleteMany();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agentMember.deleteMany();
+    await prisma.agent.deleteMany();
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("migration adds exactly one nullable, non-unique text column; existing rows are NULL", async () => {
+    const cols = await prisma.$queryRaw<
+      Array<{ data_type: string; is_nullable: string }>
+    >`SELECT data_type, is_nullable FROM information_schema.columns WHERE table_name = 'Agent' AND column_name = 'githubUsername'`;
+    expect(cols).toEqual([{ data_type: "text", is_nullable: "YES" }]);
+    const idx = await prisma.$queryRaw<Array<{ indexdef: string }>>`
+      SELECT indexdef FROM pg_indexes WHERE tablename = 'Agent' AND indexdef LIKE '%githubUsername%'`;
+    expect(idx).toEqual([]);
+    const agent = await prisma.agent.create({ data: { name: "Legacy" } });
+    expect(agent.githubUsername).toBeNull();
+  });
+
+  it("set, get, and clear round-trip via PATCH/GET, lower-cased, duplicates allowed", async () => {
+    const a = await prisma.agent.create({ data: { name: "A" } });
+    const b = await prisma.agent.create({ data: { name: "B" } });
+    const cookie = await makeSessionCookie();
+    const app = createAdminApp(makeDeps(prisma));
+    const send = (id: string, method: string, body?: unknown) =>
+      app.request(`/agents/${id}`, {
+        method,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        headers: {
+          "Content-Type": "application/json",
+          Cookie: `admin_session=${cookie}`,
+        },
+      });
+
+    const set = await send(a.id, "PATCH", { githubUsername: "Octo-Cat" });
+    expect(set.status).toBe(200);
+    expect((await set.json()).githubUsername).toBe("octo-cat");
+    expect((await (await send(a.id, "GET")).json()).githubUsername).toBe(
+      "octo-cat",
+    );
+
+    // No uniqueness: a second agent may use the same login.
+    const dup = await send(b.id, "PATCH", { githubUsername: "octo-cat" });
+    expect(dup.status).toBe(200);
+
+    // Unrelated PATCH leaves it unchanged.
+    await send(a.id, "PATCH", { selfHosted: false });
+    expect((await (await send(a.id, "GET")).json()).githubUsername).toBe(
+      "octo-cat",
+    );
+
+    const bad = await send(a.id, "PATCH", { githubUsername: "a--b" });
+    expect(bad.status).toBe(422);
+
+    const cleared = await send(a.id, "PATCH", { githubUsername: null });
+    expect(cleared.status).toBe(200);
+    expect((await cleared.json()).githubUsername).toBeNull();
+    const row = await prisma.agent.findUnique({ where: { id: a.id } });
+    expect(row?.githubUsername).toBeNull();
+  });
+});

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

@@ -6599,3 +6599,160 @@ describe("admin API — baked marketplaces report", () => {
     expect(stored()).toEqual([]);
   });
 });
+
+// ─── GHE-2.1: PATCH /agents/:id githubUsername ───────────────────────────────
+
+describe("admin API — PATCH /agents/:id githubUsername (GHE-2.1)", () => {
+  const OPS = "ghe-ops-token";
+  const AGENT_KEY = "ghe-agent-token";
+
+  function setup() {
+    const updated: Array<Record<string, unknown>> = [];
+    const base = makeMockDeps();
+    const deps: AdminDeps = {
+      ...base,
+      adminApiKeys: parseAdminApiKeys(
+        `root:${ADMIN_API_KEY}:*,operator:${OPS}:platform.ops`,
+      ),
+      agentTokenService: {
+        ...base.agentTokenService,
+        validate: async (t: string) =>
+          t === AGENT_KEY ? { agentId: AGENT_ID } : null,
+      },
+      agentService: {
+        ...base.agentService,
+        updateSelfHosted: async (id, input) => {
+          updated.push(input as Record<string, unknown>);
+          return {
+            ...(await base.agentService.updateSelfHosted(id, input)),
+            githubUsername:
+              (input as { githubUsername?: string | null }).githubUsername ??
+              null,
+          };
+        },
+      },
+    };
+    return { app: createAdminApp(deps), updated };
+  }
+
+  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 },
+    });
+
+  it("platform admin sets it: 200, lower-cased, returned", async () => {
+    const { app, updated } = setup();
+    const res = await patch(
+      app,
+      { githubUsername: "Octo-Cat" },
+      { Authorization: `Bearer ${ADMIN_API_KEY}` },
+    );
+    expect(res.status).toBe(200);
+    expect(
+      ((await res.json()) as { githubUsername: string }).githubUsername,
+    ).toBe("octo-cat");
+    expect(updated[0]).toMatchObject({ githubUsername: "octo-cat" });
+  });
+
+  it("platform admin clears it with null", async () => {
+    const { app, updated } = setup();
+    const res = await patch(
+      app,
+      { githubUsername: null },
+      { Authorization: `Bearer ${ADMIN_API_KEY}` },
+    );
+    expect(res.status).toBe(200);
+    expect(updated[0]).toMatchObject({ githubUsername: null });
+  });
+
+  it("403 for a non-admin session member", async () => {
+    const base = makeMockDeps();
+    const memberApp = createAdminApp({
+      ...base,
+      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(
+      memberApp,
+      { githubUsername: "octocat" },
+      { Cookie: `admin_session=${cookie}` },
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it("403 for a platform.ops key", async () => {
+    const { app, updated } = setup();
+    const res = await patch(
+      app,
+      { githubUsername: "octocat" },
+      { Authorization: `Bearer ${OPS}` },
+    );
+    expect(res.status).toBe(403);
+    expect(updated).toEqual([]);
+  });
+
+  it("403 for an agent-scoped key", async () => {
+    const { app, updated } = setup();
+    const res = await patch(
+      app,
+      { githubUsername: "octocat" },
+      { Authorization: `Bearer ${AGENT_KEY}` },
+    );
+    expect(res.status).toBe(403);
+    expect(updated).toEqual([]);
+  });
+
+  it("422 for invalid GitHub login syntax; nothing written", async () => {
+    const { app, updated } = setup();
+    for (const bad of ["-lead", "trail-", "a--b", "a".repeat(40), "", "a b"]) {
+      const res = await patch(
+        app,
+        { githubUsername: bad },
+        { Authorization: `Bearer ${ADMIN_API_KEY}` },
+      );
+      expect(res.status).toBe(422);
+    }
+    expect(updated).toEqual([]);
+  });
+
+  it("logs the caller name and agent id but never the username or key", async () => {
+    const { app } = setup();
+    const spy = spyOn(console, "info").mockImplementation(() => {});
+    try {
+      const res = await patch(
+        app,
+        { githubUsername: "secret-login" },
+        { Authorization: `Bearer ${ADMIN_API_KEY}` },
+      );
+      expect(res.status).toBe(200);
+      const lines = spy.mock.calls.map((c) => String(c[0]));
+      const line = lines.find((l) => l.includes("githubUsername"));
+      expect(line).toContain(AGENT_ID);
+      expect(line).toContain("root");
+      expect(lines.join("\n")).not.toContain("secret-login");
+      expect(lines.join("\n")).not.toContain(ADMIN_API_KEY);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/agents-api.ts

@@ -107,6 +107,7 @@ import {
   NotFoundError,
   UnprocessableEntityError,
 } from "./errors.ts";
+import { normalizeGithubUsername } from "./github-username.ts";
 import {
   AddAgentReposBodySchema,
   AgentChatTokenUsageDailySchema,
@@ -458,6 +459,12 @@ const GetAgentResultSchema = z
      */
     trialExpiresAt: z.string().datetime().nullable().optional(),
     trialExpiryWarnedAt: z.string().datetime().nullable().optional(),
+    /** GHE-2.1: lower-cased GitHub login; null when unset. */
+    githubUsername: z
+      .string()
+      .nullable()
+      .optional()
+      .openapi({ example: "octocat" }),
     /**
      * PMK-1.4: names of the marketplaces baked into the agent's image, as last
      * reported by the runtime at boot. Read-only: only the runtime-authenticated
@@ -658,7 +665,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` (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.",
+    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, `githubUsername` (platform admin only — 403 otherwise; `null` clears it; lower-cased on save; 422 for invalid GitHub login syntax; no GitHub call), `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: {
@@ -1806,6 +1813,27 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
         throw new ForbiddenError("Admin access required to change accountId");
       }
     }
+    // GHE-2.1: githubUsername — platform-admin only; syntax check only (no
+    // GitHub call). Stored lower-cased.
+    let githubUsername: string | null | undefined;
+    if (body.githubUsername !== undefined) {
+      if (c.get("isAdmin") !== true) {
+        throw new ForbiddenError(
+          "Admin access required to change githubUsername",
+        );
+      }
+      if (body.githubUsername === null) {
+        githubUsername = null;
+      } else {
+        const normalized = normalizeGithubUsername(body.githubUsername);
+        if (normalized === null) {
+          throw new UnprocessableEntityError(
+            "githubUsername must be a valid GitHub login (alphanumerics and single hyphens, no leading or trailing hyphen, max 39 characters)",
+          );
+        }
+        githubUsername = normalized;
+      }
+    }
     // SAL-1.2: specialty change — platform-admin only, known type only.
     let previousSpecialty: string | undefined;
     if (body.specialty !== undefined) {
@@ -1884,6 +1912,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
           ? { restrictSlackToMembers: body.restrictSlackToMembers }
           : {}),
         ...(body.slackId !== undefined ? { slackId: body.slackId } : {}),
+        ...(githubUsername !== undefined ? { githubUsername } : {}),
         ...(body.trialExpiresAt !== undefined
           ? {
               trialExpiresAt: body.trialExpiresAt
@@ -1926,6 +1955,12 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
       body.accountId !== undefined
         ? await reconcileAgentAfterAccountChange(provisioner, agent)
         : undefined;
+    if (githubUsername !== undefined) {
+      // Audit: caller name and agent id only — never the username value.
+      console.info(
+        `[agents-api] githubUsername changed: agent=${agentId} caller=${c.get("caller")?.name ?? "anonymous"}`,
+      );
+    }
     let specialtyWarning: string | undefined;
     if (previousSpecialty !== undefined) {
       // Audit: ids and names only — never the caller's key.
@@ -3057,6 +3092,7 @@ function serializeAgent(
     missingRequiredEnv?: string[];
     trialExpiresAt?: Date | null;
     trialExpiryWarnedAt?: Date | null;
+    githubUsername?: string | null;
     bakedMarketplaces?: string[];
     autoPostReviews?: boolean;
     allowSelfReview?: boolean;
@@ -3092,6 +3128,7 @@ function serializeAgent(
     trialExpiryWarnedAt: agent.trialExpiryWarnedAt
       ? agent.trialExpiryWarnedAt.toISOString()
       : null,
+    githubUsername: agent.githubUsername ?? null,
     bakedMarketplaces: agent.bakedMarketplaces ?? [],
     autoPostReviews: agent.autoPostReviews ?? true,
     allowSelfReview: agent.allowSelfReview ?? false,

package/src/agents.ts

@@ -126,6 +126,8 @@ export interface AgentDetail extends Partial<AgentAnthropicIdentity> {
    */
   trialExpiresAt?: Date | null;
   trialExpiryWarnedAt?: Date | null;
+  /** GHE-2.1: nullable GitHub login (lower-cased). Optional for fixture compat. */
+  githubUsername?: string | null;
   /**
    * PMK-1.4: marketplace names baked into the agent's image, as last reported
    * by the runtime. Read-only here; written only by setBakedMarketplaces().
@@ -174,6 +176,8 @@ interface UpdateSelfHostedInput {
    * PATCH /agents/:id (omitted entirely means "leave unchanged").
    */
   trialExpiresAt?: Date | null;
+  /** GHE-2.1: null clears; omitted leaves unchanged. Already lower-cased. */
+  githubUsername?: string | null;
   /** APM-1.3: see AgentDetail's doc comment for these six fields. */
   autoPostReviews?: boolean;
   allowSelfReview?: boolean;
@@ -288,6 +292,7 @@ const DETAIL_SELECT = {
   updatedAt: true,
   trialExpiresAt: true,
   trialExpiryWarnedAt: true,
+  githubUsername: true,
   bakedMarketplaces: true,
   autoPostReviews: true,
   allowSelfReview: true,
@@ -525,6 +530,9 @@ export class AgentService {
         ...(input.trialExpiresAt !== undefined
           ? { trialExpiresAt: input.trialExpiresAt }
           : {}),
+        ...(input.githubUsername !== undefined
+          ? { githubUsername: input.githubUsername }
+          : {}),
         ...(input.autoPostReviews !== undefined
           ? { autoPostReviews: input.autoPostReviews }
           : {}),

package/src/github-username.ts

@@ -0,0 +1,20 @@
+/**
+ * GHE-2.1: GitHub login syntax validation. Syntax only — never calls GitHub.
+ * A login is 1-39 chars of alphanumerics and single hyphens, with no leading
+ * or trailing hyphen (consecutive hyphens are invalid).
+ */
+const GITHUB_LOGIN_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/i;
+const GITHUB_LOGIN_MAX_LENGTH = 39;
+
+export function isValidGithubUsername(value: string): boolean {
+  return (
+    value.length > 0 &&
+    value.length <= GITHUB_LOGIN_MAX_LENGTH &&
+    GITHUB_LOGIN_PATTERN.test(value)
+  );
+}
+
+/** Returns the lower-cased login, or null when the syntax is invalid. */
+export function normalizeGithubUsername(value: string): string | null {
+  return isValidGithubUsername(value) ? value.toLowerCase() : null;
+}

package/src/github-username.unit.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+import {
+  isValidGithubUsername,
+  normalizeGithubUsername,
+} from "./github-username.ts";
+
+describe("github username syntax (GHE-2.1)", () => {
+  it("accepts valid logins", () => {
+    for (const ok of [
+      "a",
+      "octocat",
+      "Octo-Cat",
+      "a-b-c",
+      "a1",
+      "a".repeat(39),
+    ])
+      expect(isValidGithubUsername(ok)).toBe(true);
+  });
+
+  it("rejects leading/trailing/consecutive hyphens", () => {
+    for (const bad of ["-a", "a-", "a--b", "-"])
+      expect(isValidGithubUsername(bad)).toBe(false);
+  });
+
+  it("rejects too long, empty and illegal characters", () => {
+    for (const bad of ["a".repeat(40), "", "a_b", "a b", "a.b", "é"])
+      expect(isValidGithubUsername(bad)).toBe(false);
+  });
+
+  it("normalize lower-cases valid input and returns null otherwise", () => {
+    expect(normalizeGithubUsername("Octo-Cat")).toBe("octo-cat");
+    expect(normalizeGithubUsername("-bad")).toBeNull();
+  });
+});

package/src/openapi-schemas.ts

@@ -114,6 +114,16 @@ export const PatchAgentBodySchema = z
       .nullable()
       .optional()
       .openapi({ example: "agent-pod-sa" }),
+    /**
+     * GHE-2.1: GitHub account whose repo access caps the agent (cap applied
+     * later). Platform admin only; `null` clears it. Lower-cased on save;
+     * syntax-checked (422) with no GitHub call.
+     */
+    githubUsername: z
+      .string()
+      .nullable()
+      .optional()
+      .openapi({ example: "octocat" }),
     /**
      * ATE-1.1: trial expiry timestamp. Nullable so it can also be explicitly
      * cleared. trialExpiryWarnedAt is intentionally NOT part of this schema —