@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/anthropic-identity-name.integration.test.ts

@@ -0,0 +1,83 @@
+/**
+ * admin/src/anthropic-identity-name.integration.test.ts
+ * Integration tests for AnthropicIdentityNameAllocator (PAI-1.3) against a
+ * real PostgreSQL DB — sequential numbering and concurrent uniqueness.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { AnthropicIdentityNameAllocator } from "./anthropic-identity-name.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+function makePrisma(): PrismaClient {
+  // TEST_DB is guaranteed set — the describe block is skipped otherwise.
+  return createAdminPrismaClient(TEST_DB as string);
+}
+
+describeOrSkip("AnthropicIdentityNameAllocator (integration)", () => {
+  let prisma: PrismaClient;
+  let allocator: AnthropicIdentityNameAllocator;
+  const email = "jane.doe@example.com";
+
+  beforeEach(async () => {
+    prisma = makePrisma();
+    await prisma.agentPhaseMethodology.deleteMany();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agent.deleteMany();
+    allocator = new AnthropicIdentityNameAllocator(prisma);
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("allocates a1 then a2 for the same owner and persists them", async () => {
+    const a = await prisma.agent.create({ data: { name: "A" } });
+    const b = await prisma.agent.create({ data: { name: "B" } });
+    expect(await allocator.allocate(a.id, email)).toBe("jane-doe-a1");
+    expect(await allocator.allocate(b.id, email)).toBe("jane-doe-a2");
+    const row = await prisma.agent.findUnique({ where: { id: b.id } });
+    expect(row?.anthropicIdentityName).toBe("jane-doe-a2");
+  });
+
+  it("applies the configured suffix", async () => {
+    const a = await prisma.agent.create({ data: { name: "A" } });
+    const suffixed = new AnthropicIdentityNameAllocator(prisma, {
+      suffix: "dev",
+    });
+    expect(await suffixed.allocate(a.id, email)).toBe("jane-doe-a1-dev");
+  });
+
+  it("gives concurrent allocations different names", async () => {
+    const agents = await Promise.all(
+      ["A", "B", "C", "D"].map((name) =>
+        prisma.agent.create({ data: { name } }),
+      ),
+    );
+    const names = await Promise.all(
+      agents.map((a) => allocator.allocate(a.id, email)),
+    );
+    expect(new Set(names).size).toBe(agents.length);
+    for (const n of names) expect(n).toMatch(/^jane-doe-a\d+$/);
+  });
+
+  it("concurrent allocations for the same agent agree on one name", async () => {
+    const a = await prisma.agent.create({ data: { name: "A" } });
+    const names = await Promise.all([
+      allocator.allocate(a.id, email),
+      allocator.allocate(a.id, email),
+    ]);
+    expect(names[0]).toBe(names[1]);
+    const row = await prisma.agent.findUnique({ where: { id: a.id } });
+    expect(row?.anthropicIdentityName).toBe(names[0]);
+  });
+});

package/src/anthropic-identity-name.ts

@@ -0,0 +1,163 @@
+/**
+ * admin/src/anthropic-identity-name.ts
+ * Anthropic identity name allocator (PAI-1.3). Names are built from the
+ * owner's email: jane.doe@example.com becomes jane-doe, then -a{n} with the
+ * next free number for that owner, then an optional per-environment suffix.
+ * Names match ^[a-z0-9-]+$, are at most 255 characters, and are unique
+ * (Agent.anthropicIdentityName unique index).
+ */
+
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { BadRequestError, ConflictError, NotFoundError } from "./errors.ts";
+
+export const MAX_IDENTITY_NAME_LENGTH = 255;
+
+const NAME_PATTERN = /^[a-z0-9-]+$/;
+const MAX_N_DIGITS = 10;
+const MAX_N = 10 ** MAX_N_DIGITS - 1;
+/** Maximum unique-conflict retries before giving up. */
+const MAX_ATTEMPTS = 10;
+
+function normalizeSuffix(suffix: string | undefined): string {
+  if (suffix === undefined || suffix === "") return "";
+  if (!NAME_PATTERN.test(suffix)) {
+    throw new BadRequestError(
+      "Anthropic identity name suffix must match ^[a-z0-9-]+$",
+    );
+  }
+  return suffix;
+}
+
+/** Length of everything the name needs besides the base: -a{n}[-suffix]. */
+function reservedLength(suffix: string): number {
+  return "-a".length + MAX_N_DIGITS + (suffix ? `-${suffix}`.length : 0);
+}
+
+/**
+ * Base name from an owner email: local part (before the last @) without a
+ * +tag, lowercased, anything outside [a-z0-9] mapped to `-`, repeated `-`
+ * collapsed and ends trimmed. Truncated (independently of n) so that
+ * `identityName(base, n, suffix)` always fits in 255 characters.
+ * @throws BadRequestError for a malformed email, an empty result or a bad suffix
+ */
+export function identityBaseName(email: string, suffix?: string): string {
+  const sfx = normalizeSuffix(suffix);
+  const at = email.lastIndexOf("@");
+  if (at <= 0 || at === email.length - 1) {
+    throw new BadRequestError("Owner email is malformed");
+  }
+  const maxBase = MAX_IDENTITY_NAME_LENGTH - reservedLength(sfx);
+  if (maxBase < 1) {
+    throw new BadRequestError("Anthropic identity name suffix is too long");
+  }
+  const local = (email.slice(0, at).split("+")[0] ?? "").toLowerCase();
+  const base = local
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, maxBase)
+    .replace(/-+$/, "");
+  if (!base) {
+    throw new BadRequestError("Owner email has no usable local part");
+  }
+  return base;
+}
+
+/**
+ * `${base}-a${n}` plus `-${suffix}` when given.
+ * @throws BadRequestError if n, base or suffix is invalid or the name is too long
+ */
+export function identityName(base: string, n: number, suffix?: string): string {
+  const sfx = normalizeSuffix(suffix);
+  if (!Number.isInteger(n) || n < 1 || n > MAX_N) {
+    throw new BadRequestError("Identity number must be a positive integer");
+  }
+  const name = `${base}-a${n}${sfx ? `-${sfx}` : ""}`;
+  if (!NAME_PATTERN.test(name) || name.length > MAX_IDENTITY_NAME_LENGTH) {
+    throw new BadRequestError("Invalid Anthropic identity name");
+  }
+  return name;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function prismaCode(err: unknown): unknown {
+  return (err as { code?: unknown } | null)?.code;
+}
+
+export interface AnthropicIdentityNameAllocatorOptions {
+  /** Per-environment suffix appended to every allocated name. */
+  suffix?: string | undefined;
+}
+
+export class AnthropicIdentityNameAllocator {
+  private readonly suffix: string;
+
+  constructor(
+    private prisma: PrismaClient,
+    options: AnthropicIdentityNameAllocatorOptions = {},
+  ) {
+    this.suffix = normalizeSuffix(options.suffix);
+  }
+
+  /**
+   * Allocate the next free `-a{n}` name for the owner and save it on the
+   * agent. Idempotent: an agent that already has a name keeps it.
+   * Concurrent allocations are serialized by the unique index — the loser
+   * of a race rescans and retries with the next number.
+   * @throws NotFoundError if the agent does not exist
+   * @throws BadRequestError if the email is malformed
+   * @throws ConflictError if retries are exhausted
+   */
+  async allocate(agentId: string, ownerEmail: string): Promise<string> {
+    const base = identityBaseName(ownerEmail, this.suffix);
+    const agent = await this.prisma.agent.findUnique({
+      where: { id: agentId },
+      select: { anthropicIdentityName: true },
+    });
+    if (!agent) throw new NotFoundError(`Agent ${agentId} not found`);
+    if (agent.anthropicIdentityName) return agent.anthropicIdentityName;
+
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const name = identityName(base, await this.nextNumber(base), this.suffix);
+      try {
+        // Only write while the agent has no name, so a concurrent allocate
+        // for the same agent cannot overwrite a name that is already taken.
+        const { count } = await this.prisma.agent.updateMany({
+          where: { id: agentId, anthropicIdentityName: null },
+          data: { anthropicIdentityName: name },
+        });
+        if (count === 1) return name;
+      } catch (err) {
+        if (prismaCode(err) !== "P2002") throw err;
+        continue;
+      }
+      const current = await this.prisma.agent.findUnique({
+        where: { id: agentId },
+        select: { anthropicIdentityName: true },
+      });
+      if (!current) throw new NotFoundError(`Agent ${agentId} not found`);
+      if (current.anthropicIdentityName) return current.anthropicIdentityName;
+    }
+    throw new ConflictError("Could not allocate a unique identity name");
+  }
+
+  /** max(n) + 1 over this owner's existing names (1 if none). */
+  private async nextNumber(base: string): Promise<number> {
+    const rows = await this.prisma.agent.findMany({
+      where: { anthropicIdentityName: { startsWith: `${base}-a` } },
+      select: { anthropicIdentityName: true },
+    });
+    const sfx = this.suffix ? `-${escapeRegExp(this.suffix)}` : "";
+    const pattern = new RegExp(
+      `^${escapeRegExp(base)}-a([1-9][0-9]{0,${MAX_N_DIGITS - 1}})${sfx}$`,
+    );
+    let max = 0;
+    for (const row of rows) {
+      const m = pattern.exec(row.anthropicIdentityName ?? "");
+      if (m?.[1]) max = Math.max(max, Number(m[1]));
+    }
+    return max + 1;
+  }
+}

package/src/anthropic-identity-name.unit.test.ts

@@ -0,0 +1,345 @@
+/**
+ * admin/src/anthropic-identity-name.unit.test.ts
+ * Unit tests for the pure Anthropic identity name functions and the
+ * allocator logic (PAI-1.3) against an injected prisma test double.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  AnthropicIdentityNameAllocator,
+  identityBaseName,
+  identityName,
+  MAX_IDENTITY_NAME_LENGTH,
+} from "./anthropic-identity-name.ts";
+import { BadRequestError, ConflictError, NotFoundError } from "./errors.ts";
+
+const VALID = /^[a-z0-9-]+$/;
+
+describe("identityBaseName", () => {
+  it("maps dots to dashes", () => {
+    expect(identityBaseName("jane.doe@example.com")).toBe("jane-doe");
+  });
+
+  it("drops a +tag", () => {
+    expect(identityBaseName("jane.doe+agents@example.com")).toBe("jane-doe");
+  });
+
+  it("lowercases", () => {
+    expect(identityBaseName("Jane.DOE@Example.COM")).toBe("jane-doe");
+  });
+
+  it("replaces invalid chars, collapses and trims dashes", () => {
+    expect(identityBaseName("_a..b__c_@x.io")).toBe("a-b-c");
+  });
+
+  it("uses the part before the last @", () => {
+    expect(identityBaseName('"a@b"@x.io')).toBe("a-b");
+  });
+
+  it("truncates a very long local part so the final name fits", () => {
+    const email = `${"a".repeat(400)}@x.io`;
+    const base = identityBaseName(email);
+    expect(base.length).toBeLessThan(MAX_IDENTITY_NAME_LENGTH);
+    const name = identityName(base, 9_999_999_999);
+    expect(name.length).toBeLessThanOrEqual(MAX_IDENTITY_NAME_LENGTH);
+    expect(name).toMatch(VALID);
+  });
+
+  it("truncation leaves room for the suffix and re-trims dashes", () => {
+    const email = `${"a".repeat(300)}.${"b".repeat(300)}@x.io`;
+    const suffix = "s".repeat(30);
+    const base = identityBaseName(email, suffix);
+    expect(base.endsWith("-")).toBe(false);
+    const name = identityName(base, 9_999_999_999, suffix);
+    expect(name.length).toBeLessThanOrEqual(MAX_IDENTITY_NAME_LENGTH);
+    expect(name.endsWith(`-a9999999999-${suffix}`)).toBe(true);
+  });
+
+  it("re-trims a dash exposed by truncation", () => {
+    const email = `${"a".repeat(230)}.bbb@x.io`;
+    for (let i = 0; i < 40; i++) {
+      const base = identityBaseName(`${"a".repeat(i)}.${email}`);
+      expect(base.endsWith("-")).toBe(false);
+    }
+  });
+
+  it.each([
+    "",
+    "nope",
+    "@example.com",
+    "jane@",
+    "+tag@example.com",
+    "...@example.com",
+    "___@example.com",
+  ])("rejects malformed or empty-result email %p", (email) => {
+    expect(() => identityBaseName(email)).toThrow(BadRequestError);
+  });
+
+  it("rejects an invalid suffix", () => {
+    expect(() => identityBaseName("a@x.io", "Bad_Suffix")).toThrow(
+      BadRequestError,
+    );
+  });
+
+  it("rejects a suffix too long to leave room for a base", () => {
+    expect(() => identityBaseName("a@x.io", "s".repeat(300))).toThrow(
+      BadRequestError,
+    );
+  });
+});
+
+describe("identityName", () => {
+  it("builds base-a{n}", () => {
+    expect(identityName("jane-doe", 3)).toBe("jane-doe-a3");
+  });
+
+  it("appends the suffix", () => {
+    expect(identityName("jane-doe", 1, "prod")).toBe("jane-doe-a1-prod");
+  });
+
+  it("treats an empty suffix as none", () => {
+    expect(identityName("jane", 2, "")).toBe("jane-a2");
+  });
+
+  it.each([0, -1, 1.5, Number.NaN, 1e10])("rejects n=%p", (n) => {
+    expect(() => identityName("jane", n)).toThrow(BadRequestError);
+  });
+
+  it("rejects an invalid suffix", () => {
+    expect(() => identityName("jane", 1, "UP")).toThrow(BadRequestError);
+  });
+
+  it("rejects an invalid base", () => {
+    expect(() => identityName("Jane!", 1)).toThrow(BadRequestError);
+  });
+
+  it("rejects a name over the length limit", () => {
+    expect(() => identityName("a".repeat(255), 1)).toThrow(BadRequestError);
+  });
+});
+
+type Row = { id: string; anthropicIdentityName: string | null };
+
+/** Minimal in-memory prisma double; update enforces the unique index. */
+function makeFakePrisma(
+  rows: Row[],
+  opts: { conflictsBeforeSuccess?: number } = {},
+) {
+  let conflicts = opts.conflictsBeforeSuccess ?? 0;
+  const calls = { findMany: 0, update: 0 };
+  const agent = {
+    async findUnique({ where }: { where: { id: string } }) {
+      return rows.find((r) => r.id === where.id) ?? null;
+    },
+    async findMany({
+      where,
+    }: {
+      where: { anthropicIdentityName: { startsWith: string } };
+    }) {
+      calls.findMany++;
+      const prefix = where.anthropicIdentityName.startsWith;
+      return rows
+        .filter((r) => r.anthropicIdentityName?.startsWith(prefix))
+        .map((r) => ({ anthropicIdentityName: r.anthropicIdentityName }));
+    },
+    async updateMany({
+      where,
+      data,
+    }: {
+      where: { id: string; anthropicIdentityName: null };
+      data: { anthropicIdentityName: string };
+    }) {
+      calls.update++;
+      if (conflicts > 0) {
+        conflicts--;
+        // Simulate a concurrent writer grabbing the name we computed.
+        rows.push({ id: `other${calls.update}`, ...data });
+        throw { code: "P2002" };
+      }
+      if (
+        rows.some((r) => r.anthropicIdentityName === data.anthropicIdentityName)
+      )
+        throw { code: "P2002" };
+      const row = rows.find(
+        (r) => r.id === where.id && r.anthropicIdentityName === null,
+      );
+      if (!row) return { count: 0 };
+      row.anthropicIdentityName = data.anthropicIdentityName;
+      return { count: 1 };
+    },
+  };
+  // biome-ignore lint/suspicious/noExplicitAny: minimal prisma double
+  return { prisma: { agent } as any, calls, rows };
+}
+
+describe("AnthropicIdentityNameAllocator", () => {
+  const email = "jane.doe@example.com";
+
+  it("starts at a1", async () => {
+    const { prisma } = makeFakePrisma([
+      { id: "x", anthropicIdentityName: null },
+    ]);
+    const name = await new AnthropicIdentityNameAllocator(prisma).allocate(
+      "x",
+      email,
+    );
+    expect(name).toBe("jane-doe-a1");
+  });
+
+  it("picks max+1, ignoring gaps", async () => {
+    const { prisma } = makeFakePrisma([
+      { id: "x", anthropicIdentityName: null },
+      { id: "p", anthropicIdentityName: "jane-doe-a1" },
+      { id: "q", anthropicIdentityName: "jane-doe-a7" },
+    ]);
+    expect(
+      await new AnthropicIdentityNameAllocator(prisma).allocate("x", email),
+    ).toBe("jane-doe-a8");
+  });
+
+  it("does not count other owners sharing a prefix", async () => {
+    const { prisma } = makeFakePrisma([
+      { id: "x", anthropicIdentityName: null },
+      { id: "p", anthropicIdentityName: "jane-doe-a3" },
+      { id: "q", anthropicIdentityName: "jane-doe-a3-prod" },
+      { id: "r", anthropicIdentityName: "jane-doe-alpha" },
+    ]);
+    expect(
+      await new AnthropicIdentityNameAllocator(prisma).allocate(
+        "x",
+        "jane@example.com",
+      ),
+    ).toBe("jane-a1");
+    const second = makeFakePrisma([
+      { id: "x", anthropicIdentityName: null },
+      { id: "p", anthropicIdentityName: "jane-doe-a3-prod" },
+      { id: "q", anthropicIdentityName: "jane-doe-a9" },
+    ]);
+    expect(
+      await new AnthropicIdentityNameAllocator(second.prisma).allocate(
+        "x",
+        email,
+      ),
+    ).toBe("jane-doe-a10");
+  });
+
+  it("applies the suffix and only counts same-suffix names", async () => {
+    const { prisma } = makeFakePrisma([
+      { id: "x", anthropicIdentityName: null },
+      { id: "p", anthropicIdentityName: "jane-doe-a5" },
+      { id: "q", anthropicIdentityName: "jane-doe-a2-prod" },
+      { id: "r", anthropicIdentityName: "jane-doe-a4-dev" },
+    ]);
+    expect(
+      await new AnthropicIdentityNameAllocator(prisma, {
+        suffix: "prod",
+      }).allocate("x", email),
+    ).toBe("jane-doe-a3-prod");
+  });
+
+  it("persists the name on the agent row", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: null }]);
+    await new AnthropicIdentityNameAllocator(f.prisma).allocate("x", email);
+    expect(f.rows[0]?.anthropicIdentityName).toBe("jane-doe-a1");
+  });
+
+  it("is idempotent: returns an existing name unchanged", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: "custom-a1" }]);
+    const name = await new AnthropicIdentityNameAllocator(f.prisma).allocate(
+      "x",
+      email,
+    );
+    expect(name).toBe("custom-a1");
+    expect(f.calls.update).toBe(0);
+  });
+
+  it("throws NotFoundError for an unknown agent", async () => {
+    const { prisma } = makeFakePrisma([]);
+    await expect(
+      new AnthropicIdentityNameAllocator(prisma).allocate("nope", email),
+    ).rejects.toBeInstanceOf(NotFoundError);
+  });
+
+  it("rejects a malformed email before touching the db", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: null }]);
+    await expect(
+      new AnthropicIdentityNameAllocator(f.prisma).allocate("x", "bad"),
+    ).rejects.toBeInstanceOf(BadRequestError);
+    expect(f.calls.findMany).toBe(0);
+  });
+
+  it("rejects an invalid suffix at construction", () => {
+    const { prisma } = makeFakePrisma([]);
+    expect(
+      () => new AnthropicIdentityNameAllocator(prisma, { suffix: "No!" }),
+    ).toThrow(BadRequestError);
+  });
+
+  it("retries with a fresh scan after a unique conflict", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: null }], {
+      conflictsBeforeSuccess: 2,
+    });
+    const name = await new AnthropicIdentityNameAllocator(f.prisma).allocate(
+      "x",
+      email,
+    );
+    expect(name).toBe("jane-doe-a3");
+    expect(f.calls.findMany).toBe(3);
+  });
+
+  it("throws ConflictError once retries are exhausted", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: null }], {
+      conflictsBeforeSuccess: 100,
+    });
+    await expect(
+      new AnthropicIdentityNameAllocator(f.prisma).allocate("x", email),
+    ).rejects.toBeInstanceOf(ConflictError);
+  });
+
+  it("throws NotFoundError if the agent is deleted mid-allocation", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: null }]);
+    const findUnique = f.prisma.agent.findUnique;
+    f.prisma.agent.findUnique = async (args: { where: { id: string } }) => {
+      const row = await findUnique(args);
+      f.rows.splice(0, f.rows.length);
+      return row;
+    };
+    await expect(
+      new AnthropicIdentityNameAllocator(f.prisma).allocate("x", email),
+    ).rejects.toBeInstanceOf(NotFoundError);
+  });
+
+  it("keeps a name written concurrently for the same agent", async () => {
+    const f = makeFakePrisma([{ id: "x", anthropicIdentityName: null }]);
+    const findUnique = f.prisma.agent.findUnique;
+    let first = true;
+    f.prisma.agent.findUnique = async (args: { where: { id: string } }) => {
+      const row = await findUnique(args);
+      const snapshot = row && { ...row };
+      if (first && f.rows[0]) {
+        // Another allocate for this agent wins the race after our read.
+        f.rows[0].anthropicIdentityName = "jane-doe-a1";
+        first = false;
+      }
+      return snapshot;
+    };
+    const name = await new AnthropicIdentityNameAllocator(f.prisma).allocate(
+      "x",
+      email,
+    );
+    expect(name).toBe("jane-doe-a1");
+    expect(f.rows[0]?.anthropicIdentityName).toBe("jane-doe-a1");
+  });
+
+  it("rethrows unexpected db errors", async () => {
+    const { prisma } = makeFakePrisma([
+      { id: "x", anthropicIdentityName: null },
+    ]);
+    prisma.agent.updateMany = async () => {
+      throw new Error("boom");
+    };
+    await expect(
+      new AnthropicIdentityNameAllocator(prisma).allocate("x", email),
+    ).rejects.toThrow("boom");
+  });
+});