@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/account-lifecycle.ts

@@ -0,0 +1,206 @@
+/**
+ * admin/src/account-lifecycle.ts
+ *
+ * AccountLifecycle (SSP-8.2) — the one place an account's status transition
+ * turns into cron side effects, shared by the admin PATCH /accounts/:id
+ * handler (accounts-api.ts), the admin UI suspend/reactivate actions
+ * (admin-ui-accounts.ts) and the account trial-expiry sweeper
+ * (account-trial-expiry-sweeper.ts).
+ *
+ *   - active → suspended | trial_expired: lock down — every *enabled* cron of
+ *     the account's agents is disabled via AgentCronJobService.setEnabled()
+ *     with `{ lockdown: true }`, stamping lockdownDisabledAt (SSP-8.1). Crons
+ *     the user had already disabled stay unmarked.
+ *   - suspended | trial_expired → active: restore — restoreLockdownDisabled()
+ *     re-enables exactly the marked crons. Agents whose *own* per-agent
+ *     trialExpiresAt has lapsed are skipped, so the per-agent lockdown
+ *     (trial-expiry-sweeper.ts) keeps its crons off. Reactivation requires
+ *     the account's trialExpiresAt to be cleared or in the future (422
+ *     otherwise — the expiry sweeper would just flip it straight back), and
+ *     resets trialExpiryWarnedAt so a new trial gets its own warning.
+ *
+ * Nothing is ever deleted — no deleteAgentFully call, no workload changes. Both
+ * directions are idempotent: lockdown only touches enabled crons, restore
+ * only touches marked ones.
+ */
+
+import type {
+  Account,
+  AccountService,
+  UpdateAccountInput,
+} from "./accounts.ts";
+import type { AgentCronJobService } from "./agent-cron-jobs.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { NotFoundError, UnprocessableEntityError } from "./errors.ts";
+import {
+  DEFAULT_TRIAL_EXPIRY_WARNING_DAYS,
+  isDueForWarning,
+} from "./trial-expiry-warning-sweeper.ts";
+
+// ─── Pure helpers ───────────────────────────────────────────────────────────
+
+const LOCKED_STATUSES: ReadonlySet<string> = new Set([
+  "suspended",
+  "trial_expired",
+]);
+
+/** Whether an account status means its agents are locked down. */
+export function isLockedStatus(status: string): boolean {
+  return LOCKED_STATUSES.has(status);
+}
+
+type LockdownAction = "lockdown" | "restore" | "none";
+
+/** Cron side effect implied by moving an account from `prev` to `next`. */
+export function resolveLockdownAction(
+  prev: string,
+  next: string,
+): LockdownAction {
+  if (prev === next) return "none";
+  if (isLockedStatus(next)) return "lockdown";
+  if (isLockedStatus(prev) && next === "active") return "restore";
+  return "none";
+}
+
+/**
+ * Whether a trial has lapsed — strictly before `now`, matching the per-agent
+ * sweeper's `lt` (a trial expiring at exactly `now` is not yet expired).
+ */
+export function isTrialLapsed(trialExpiresAt: Date | null, now: Date): boolean {
+  return trialExpiresAt !== null && trialExpiresAt.getTime() < now.getTime();
+}
+
+/**
+ * Account-level warning window — the same comparison the per-agent warning
+ * sweeper uses (isDueForWarning), applied to the account's fields.
+ */
+export function isAccountTrialWarningDue(
+  trialExpiresAt: Date | null,
+  trialExpiryWarnedAt: Date | null,
+  now: Date,
+  windowDays: number = DEFAULT_TRIAL_EXPIRY_WARNING_DAYS,
+  graceDays: number = windowDays,
+): boolean {
+  return isDueForWarning(
+    trialExpiresAt,
+    trialExpiryWarnedAt,
+    now,
+    windowDays,
+    graceDays,
+  );
+}
+
+// ─── Service ────────────────────────────────────────────────────────────────
+
+interface AccountLifecycleDeps {
+  accounts: Pick<AccountService, "getById" | "update" | "listAgentTrialStates">;
+  cronJobs: Pick<
+    AgentCronJobService,
+    "listEnabledInLockedAccounts" | "setEnabled" | "restoreLockdownDisabled"
+  >;
+  clock?: Clock;
+  log?: (line: string) => void;
+}
+
+export class AccountLifecycle {
+  private readonly clock: Clock;
+  private readonly log: (line: string) => void;
+
+  constructor(private readonly deps: AccountLifecycleDeps) {
+    this.clock = deps.clock ?? SystemClock();
+    this.log = deps.log ?? ((line) => console.log(line));
+  }
+
+  /**
+   * Apply an admin edit to an account and run the cron side effect its
+   * status transition implies. Throws NotFoundError for an unknown account
+   * and UnprocessableEntityError for a reactivation with a lapsed trial
+   * (nothing is written in either case).
+   */
+  async update(id: string, data: UpdateAccountInput): Promise<Account> {
+    const current = await this.deps.accounts.getById(id);
+    if (!current) throw new NotFoundError(`account ${id} not found`);
+
+    const now = this.clock.now();
+    const nextStatus = data.status ?? current.status;
+    const action = resolveLockdownAction(current.status, nextStatus);
+    const nextTrial =
+      data.trialExpiresAt !== undefined
+        ? data.trialExpiresAt
+        : current.trialExpiresAt;
+
+    if (action === "restore" && isTrialLapsed(nextTrial, now)) {
+      throw new UnprocessableEntityError(
+        "Clear or extend trialExpiresAt before reactivating the account.",
+      );
+    }
+
+    const trialChanged =
+      data.trialExpiresAt !== undefined &&
+      (data.trialExpiresAt?.getTime() ?? null) !==
+        (current.trialExpiresAt?.getTime() ?? null);
+    const write: UpdateAccountInput = { ...data };
+    if (
+      (action === "restore" || trialChanged) &&
+      data.trialExpiryWarnedAt === undefined
+    ) {
+      write.trialExpiryWarnedAt = null;
+    }
+
+    const updated = await this.deps.accounts.update(id, write);
+
+    if (action === "lockdown") await this.lockDown(id);
+    if (action === "restore") await this.restore(id);
+    return updated;
+  }
+
+  /**
+   * Disable (with the lockdown marker) every enabled cron of an agent in a
+   * locked account — one account, or all of them when `accountId` is
+   * omitted (the sweeper's self-healing pass). Per-row failures are logged
+   * and skipped. Returns the number disabled.
+   */
+  async lockDown(accountId?: string): Promise<number> {
+    const rows =
+      await this.deps.cronJobs.listEnabledInLockedAccounts(accountId);
+    let disabled = 0;
+    for (const row of rows) {
+      try {
+        await this.deps.cronJobs.setEnabled(row.agentId, row.id, false, {
+          lockdown: true,
+        });
+        disabled++;
+      } catch (err) {
+        console.error(
+          `[account-lifecycle] disable cron ${row.id} (agent ${row.agentId}) failed:`,
+          err,
+        );
+      }
+    }
+    if (disabled > 0) {
+      this.log(
+        `[account-lifecycle] lockdown${accountId ? ` ${accountId}` : ""}: disabled=${disabled}`,
+      );
+    }
+    return disabled;
+  }
+
+  /**
+   * Re-enable the lockdown-disabled crons of the account's agents, skipping
+   * agents whose own per-agent trial has lapsed. Returns the number restored.
+   */
+  async restore(accountId: string): Promise<number> {
+    const now = this.clock.now();
+    const agents = await this.deps.accounts.listAgentTrialStates(accountId);
+    const ids = agents
+      .filter((a) => !isTrialLapsed(a.trialExpiresAt, now))
+      .map((a) => a.id);
+    const restored = await this.deps.cronJobs.restoreLockdownDisabled(ids);
+    if (restored > 0) {
+      this.log(
+        `[account-lifecycle] restore ${accountId}: restored=${restored}`,
+      );
+    }
+    return restored;
+  }
+}

package/src/account-lifecycle.unit.test.ts

@@ -0,0 +1,108 @@
+/**
+ * admin/src/account-lifecycle.unit.test.ts
+ * Pure helpers behind the account lockdown lifecycle (SSP-8.2): which status
+ * transitions lock down / restore, the trial-lapsed comparison, and the
+ * account-level warning window (reusing isDueForWarning). Also a static guard
+ * that none of the account lifecycle modules ever reach for deleteAgentFully.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  isAccountTrialWarningDue,
+  isLockedStatus,
+  isTrialLapsed,
+  resolveLockdownAction,
+} from "./account-lifecycle.ts";
+
+const DAY = 24 * 60 * 60 * 1000;
+const NOW = new Date("2026-10-08T12:00:00.000Z");
+const days = (n: number) => new Date(NOW.getTime() + n * DAY);
+
+describe("isLockedStatus", () => {
+  it("suspended and trial_expired are locked; active is not", () => {
+    expect(isLockedStatus("suspended")).toBe(true);
+    expect(isLockedStatus("trial_expired")).toBe(true);
+    expect(isLockedStatus("active")).toBe(false);
+  });
+});
+
+describe("resolveLockdownAction", () => {
+  it("active -> suspended / trial_expired locks down", () => {
+    expect(resolveLockdownAction("active", "suspended")).toBe("lockdown");
+    expect(resolveLockdownAction("active", "trial_expired")).toBe("lockdown");
+  });
+
+  it("locked -> active restores", () => {
+    expect(resolveLockdownAction("suspended", "active")).toBe("restore");
+    expect(resolveLockdownAction("trial_expired", "active")).toBe("restore");
+  });
+
+  it("locked -> other locked status re-applies the (idempotent) lockdown", () => {
+    expect(resolveLockdownAction("trial_expired", "suspended")).toBe(
+      "lockdown",
+    );
+  });
+
+  it("no status change does nothing", () => {
+    expect(resolveLockdownAction("active", "active")).toBe("none");
+    expect(resolveLockdownAction("suspended", "suspended")).toBe("none");
+  });
+});
+
+describe("isTrialLapsed", () => {
+  it("null never lapses", () => {
+    expect(isTrialLapsed(null, NOW)).toBe(false);
+  });
+
+  it("strictly-past lapses; now and future do not", () => {
+    expect(isTrialLapsed(days(-1), NOW)).toBe(true);
+    expect(isTrialLapsed(new Date(NOW.getTime() - 1), NOW)).toBe(true);
+    expect(isTrialLapsed(NOW, NOW)).toBe(false);
+    expect(isTrialLapsed(days(1), NOW)).toBe(false);
+  });
+});
+
+describe("isAccountTrialWarningDue (window comparison)", () => {
+  it("2 days away with a 3-day window is due", () => {
+    expect(isAccountTrialWarningDue(days(2), null, NOW, 3)).toBe(true);
+  });
+
+  it("exactly at the window edge is due; just past it is not", () => {
+    expect(isAccountTrialWarningDue(days(3), null, NOW, 3)).toBe(true);
+    expect(
+      isAccountTrialWarningDue(new Date(days(3).getTime() + 1), null, NOW, 3),
+    ).toBe(false);
+  });
+
+  it("5 days away with a 3-day window is not due", () => {
+    expect(isAccountTrialWarningDue(days(5), null, NOW, 3)).toBe(false);
+  });
+
+  it("already warned is never due", () => {
+    expect(isAccountTrialWarningDue(days(2), days(-1), NOW, 3)).toBe(false);
+  });
+
+  it("no trial is never due", () => {
+    expect(isAccountTrialWarningDue(null, null, NOW, 3)).toBe(false);
+  });
+
+  it("defaults to the 3-day window", () => {
+    expect(isAccountTrialWarningDue(days(2), null, NOW)).toBe(true);
+    expect(isAccountTrialWarningDue(days(4), null, NOW)).toBe(false);
+  });
+});
+
+describe("no deprovisioning in account lifecycle flows", () => {
+  it("none of the SSP-8.2 modules reference deleteAgentFully", () => {
+    for (const file of [
+      "account-lifecycle.ts",
+      "account-trial-expiry-sweeper.ts",
+      "account-trial-warning-sweeper.ts",
+    ]) {
+      const src = readFileSync(join(import.meta.dir, file), "utf8");
+      expect(src).not.toContain("deleteAgentFully(");
+    }
+  });
+});

package/src/account-members.ts

@@ -0,0 +1,128 @@
+/**
+ * admin/src/account-members.ts
+ * AccountMemberService — email-keyed members of an account (SSP-1.2).
+ *
+ * UNIQUE(email) means an email belongs to at most one account in Phase 1.
+ * The last owner of an account can never be removed or demoted.
+ */
+
+import type { AccountMember, PrismaClient } from "../prisma/client/client.ts";
+import { normalizeEmail } from "./account-email.ts";
+import type { PrismaTransactionClient } from "./prisma-tx.ts";
+
+export type { AccountMember };
+
+type AccountRole = "owner" | "member";
+
+export class LastOwnerError extends Error {
+  constructor(public readonly accountId: string) {
+    super(`Cannot remove or demote the last owner of account ${accountId}`);
+    this.name = "LastOwnerError";
+  }
+}
+
+export class AccountMemberNotFoundError extends Error {
+  constructor(accountId: string, email: string) {
+    super(`No member ${email} in account ${accountId}`);
+    this.name = "AccountMemberNotFoundError";
+  }
+}
+
+export class AccountMemberService {
+  constructor(private prisma: PrismaClient) {}
+
+  async listByAccount(accountId: string): Promise<AccountMember[]> {
+    return this.prisma.accountMember.findMany({
+      where: { accountId },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  async getByEmail(email: string): Promise<AccountMember | null> {
+    return this.prisma.accountMember.findUnique({
+      where: { email: normalizeEmail(email) },
+    });
+  }
+
+  /**
+   * Add a member. Throws (unique-constraint violation) if the email already
+   * belongs to any account.
+   *
+   * @param client - pass a `tx` from `prisma.$transaction` to participate in it.
+   */
+  async add(
+    accountId: string,
+    email: string,
+    role: AccountRole = "member",
+    client: PrismaTransactionClient = this.prisma,
+  ): Promise<AccountMember> {
+    return client.accountMember.create({
+      data: { accountId, email: normalizeEmail(email), role },
+    });
+  }
+
+  async remove(accountId: string, email: string): Promise<void> {
+    await this.guardedChange(accountId, email, async (tx, member) => {
+      await tx.accountMember.delete({ where: { id: member.id } });
+    });
+  }
+
+  async promote(accountId: string, email: string): Promise<AccountMember> {
+    return this.setRole(accountId, email, "owner");
+  }
+
+  async demote(accountId: string, email: string): Promise<AccountMember> {
+    return this.setRole(accountId, email, "member");
+  }
+
+  private async setRole(
+    accountId: string,
+    email: string,
+    role: AccountRole,
+  ): Promise<AccountMember> {
+    let updated: AccountMember | undefined;
+    await this.guardedChange(
+      accountId,
+      email,
+      async (tx, member) => {
+        updated = await tx.accountMember.update({
+          where: { id: member.id },
+          data: { role },
+        });
+      },
+      role === "member",
+    );
+    return updated as AccountMember;
+  }
+
+  /**
+   * Runs `change` in a transaction after verifying the member exists and, when
+   * the change would remove an owner, that they are not the last one. The
+   * account row is locked first so concurrent removals/demotions serialize.
+   */
+  private async guardedChange(
+    accountId: string,
+    rawEmail: string,
+    change: (
+      tx: PrismaTransactionClient,
+      member: AccountMember,
+    ) => Promise<void>,
+    removesOwnerRole = true,
+  ): Promise<void> {
+    const email = normalizeEmail(rawEmail);
+    await this.prisma.$transaction(async (tx) => {
+      await tx.$queryRaw`SELECT id FROM "Account" WHERE id = ${accountId} FOR UPDATE`;
+      const member = await tx.accountMember.findUnique({
+        where: { accountId_email: { accountId, email } },
+      });
+      if (!member) throw new AccountMemberNotFoundError(accountId, email);
+      if (removesOwnerRole && member.role === "owner") {
+        const owners = await tx.accountMember.count({
+          where: { accountId, role: "owner" },
+        });
+        if (owners <= 1) throw new LastOwnerError(accountId);
+      }
+      await change(tx, member);
+    });
+  }
+}

package/src/account-onboarding.integration.test.ts

@@ -0,0 +1,101 @@
+/**
+ * admin/src/account-onboarding.integration.test.ts
+ * Integration tests for AccountOnboardingService (SSP-3.1) against real Postgres.
+ *
+ * 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 { AccountInviteService } from "./account-invites.ts";
+import { AccountOnboardingService } from "./account-onboarding.ts";
+import { AccountService } from "./accounts.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+describeOrSkip("AccountOnboardingService (integration)", () => {
+  let prisma: PrismaClient;
+  let onboarding: AccountOnboardingService;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.accountInvite.deleteMany();
+    await prisma.accountMember.deleteMany();
+    await prisma.agent.deleteMany();
+    await prisma.account.deleteMany();
+    onboarding = new AccountOnboardingService(prisma, 3);
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("creates an account with the owner row, default quota and local-part name", async () => {
+    const result = await onboarding.provisionForEmail("New.User@Example.com");
+    expect(result.kind).toBe("created");
+    const account = await prisma.account.findUniqueOrThrow({
+      where: { id: result.accountId },
+    });
+    expect(account.name).toBe("new.user");
+    expect(account.status).toBe("active");
+    expect(account.maxAgents).toBe(3);
+    const members = await prisma.accountMember.findMany();
+    expect(members.map((m) => [m.email, m.role])).toEqual([
+      ["new.user@example.com", "owner"],
+    ]);
+  });
+
+  it("joins the invited account as member and marks the invite accepted", async () => {
+    const owner = await new AccountService(prisma).create("Acme", "o@acme.com");
+    await new AccountInviteService(prisma).create(
+      owner.id,
+      "Invitee@Acme.com",
+      "o@acme.com",
+    );
+    const result = await onboarding.provisionForEmail("invitee@acme.com");
+    expect(result).toEqual({ kind: "joined", accountId: owner.id });
+    expect(await prisma.account.count()).toBe(1);
+    const member = await prisma.accountMember.findUniqueOrThrow({
+      where: { email: "invitee@acme.com" },
+    });
+    expect(member.role).toBe("member");
+    const invite = await prisma.accountInvite.findFirstOrThrow({
+      where: { email: "invitee@acme.com" },
+    });
+    expect(invite.acceptedAt).not.toBeNull();
+  });
+
+  it("returns existing for an email that already has an account", async () => {
+    const first = await onboarding.provisionForEmail("a@x.com");
+    const second = await onboarding.provisionForEmail("A@x.com");
+    expect(second).toEqual({ kind: "existing", accountId: first.accountId });
+    expect(await prisma.account.count()).toBe(1);
+  });
+
+  it("concurrent first logins for one email yield exactly one account", async () => {
+    const results = await Promise.all(
+      Array.from({ length: 8 }, () =>
+        onboarding.provisionForEmail("race@x.com"),
+      ),
+    );
+    expect(await prisma.account.count()).toBe(1);
+    expect(await prisma.accountMember.count()).toBe(1);
+    expect(new Set(results.map((r) => r.accountId)).size).toBe(1);
+    expect(results.filter((r) => r.kind === "created")).toHaveLength(1);
+  });
+
+  it("concurrent first logins with a pending invite join once and create no account", async () => {
+    const owner = await new AccountService(prisma).create("Acme", "o@acme.com");
+    await new AccountInviteService(prisma).create(owner.id, "r@acme.com", "o");
+    const results = await Promise.all(
+      Array.from({ length: 6 }, () =>
+        onboarding.provisionForEmail("r@acme.com"),
+      ),
+    );
+    expect(await prisma.account.count()).toBe(1);
+    expect(results.every((r) => r.accountId === owner.id)).toBe(true);
+    expect(results.filter((r) => r.kind === "joined")).toHaveLength(1);
+  });
+});

package/src/account-onboarding.ts

@@ -0,0 +1,95 @@
+/**
+ * admin/src/account-onboarding.ts
+ * AccountOnboardingService — first-login account provisioning for self-serve
+ * agent provisioning (SSP-3.1).
+ *
+ * A verified email with no account yet either joins the account that invited
+ * it (as 'member') or gets a brand-new account (as 'owner'). Everything runs
+ * in one transaction, and concurrent first logins for the same email are made
+ * idempotent by UNIQUE(AccountMember.email): the losing transaction rolls back
+ * entirely (including any account it created) and re-reads the winner's row.
+ */
+
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { normalizeEmail } from "./account-email.ts";
+
+type OnboardingResult =
+  | { kind: "created"; accountId: string }
+  | { kind: "joined"; accountId: string }
+  | { kind: "existing"; accountId: string };
+
+const MAX_ATTEMPTS = 3;
+const UNIQUE_VIOLATION = "P2002";
+
+function isUniqueViolation(err: unknown): boolean {
+  return (err as { code?: unknown } | null)?.code === UNIQUE_VIOLATION;
+}
+
+export class AccountOnboardingService {
+  constructor(
+    private prisma: PrismaClient,
+    private defaultMaxAgents: number,
+  ) {}
+
+  /**
+   * Ensure the email belongs to an account: no-op ("existing") if it already
+   * does, else join via pending invite ("joined"), else create ("created").
+   */
+  async provisionForEmail(rawEmail: string): Promise<OnboardingResult> {
+    const email = normalizeEmail(rawEmail);
+    let lastErr: unknown;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      try {
+        return await this.prisma.$transaction((tx) =>
+          this.provisionInTx(tx, email),
+        );
+      } catch (err) {
+        if (!isUniqueViolation(err)) throw err;
+        // A concurrent first login won the race — read-after-conflict.
+        lastErr = err;
+        const member = await this.prisma.accountMember.findUnique({
+          where: { email },
+        });
+        if (member) return { kind: "existing", accountId: member.accountId };
+      }
+    }
+    throw lastErr;
+  }
+
+  private async provisionInTx(
+    tx: Parameters<Parameters<PrismaClient["$transaction"]>[0]>[0],
+    email: string,
+  ): Promise<OnboardingResult> {
+    const existing = await tx.accountMember.findUnique({ where: { email } });
+    if (existing) return { kind: "existing", accountId: existing.accountId };
+
+    const invite = await tx.accountInvite.findFirst({
+      where: { email, acceptedAt: null },
+      orderBy: { createdAt: "asc" },
+    });
+    if (invite) {
+      const claimed = await tx.accountInvite.updateMany({
+        where: { id: invite.id, acceptedAt: null },
+        data: { acceptedAt: new Date() },
+      });
+      if (claimed.count === 1) {
+        await tx.accountMember.create({
+          data: { accountId: invite.accountId, email, role: "member" },
+        });
+        return { kind: "joined", accountId: invite.accountId };
+      }
+    }
+
+    const account = await tx.account.create({
+      data: {
+        name: email.split("@")[0] || email,
+        status: "active",
+        maxAgents: this.defaultMaxAgents,
+      },
+    });
+    await tx.accountMember.create({
+      data: { accountId: account.id, email, role: "owner" },
+    });
+    return { kind: "created", accountId: account.id };
+  }
+}