@app-vitals/agent-admin 0.0.0-stage → 0.1.0

package/src/prisma-client.integration.test.ts

@@ -0,0 +1,57 @@
+/**
+ * admin/src/prisma-client.integration.test.ts
+ * Integration tests for the Prisma 7 driver-adapter client factory against a
+ * real PostgreSQL DB.
+ *
+ * The rest of the admin integration suite is the regression check for query
+ * *behavior* across the v6→v7 upgrade. This file covers the one thing that is
+ * genuinely new: client construction now goes through a `PrismaPg` driver
+ * adapter over a `pg.Pool` instead of Prisma's built-in query engine, so the
+ * boot path itself needs a live-DB assertion that it connects and round-trips.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, 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("createAdminPrismaClient (integration)", () => {
+  let prisma: PrismaClient | undefined;
+
+  afterEach(async () => {
+    await prisma?.$disconnect();
+    prisma = undefined;
+  });
+
+  it("boots an adapter-backed client that executes a raw round-trip query", async () => {
+    // TEST_DB is guaranteed set — the describe block is skipped otherwise.
+    prisma = createAdminPrismaClient(TEST_DB as string);
+
+    const rows = await prisma.$queryRaw<
+      Array<{ one: number }>
+    >`SELECT 1 AS one`;
+
+    expect(rows).toEqual([{ one: 1 }]);
+  });
+
+  it("round-trips a model write and read back through the adapter", async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+
+    const created = await prisma.agent.create({
+      data: { name: "Adapter Boot Agent" },
+    });
+    try {
+      const found = await prisma.agent.findUnique({
+        where: { id: created.id },
+      });
+      expect(found?.name).toBe("Adapter Boot Agent");
+    } finally {
+      await prisma.agent.delete({ where: { id: created.id } });
+    }
+  });
+});

package/src/prisma-client.ts

@@ -0,0 +1,187 @@
+/**
+ * admin/src/prisma-client.ts
+ *
+ * Single place the admin service builds a PrismaClient.
+ *
+ * Prisma 7 removed the bundled query engine: a client no longer connects off
+ * `datasource.url` by itself, it needs a driver adapter. Admin talks to
+ * Postgres, so every client is a `PrismaPg` adapter wrapping a `pg.Pool`.
+ * Keeping that in one factory means the runtime (main.ts), the dev/CI scripts,
+ * and the integration suites all get the same pool tuning instead of each
+ * re-deriving it.
+ */
+
+import { pinPgSslMode } from "@app-vitals/agent-lib/pg-sslmode";
+import {
+  type CheckoutPool,
+  type Clock,
+  type PoolLog,
+  startPoolMonitor,
+  trackConnectionHold,
+} from "@app-vitals/agent-lib/pool-observability";
+import { PrismaPg } from "@prisma/adapter-pg";
+import pg from "pg";
+import { PrismaClient } from "../prisma/client/client.ts";
+
+/**
+ * Connect timeout for a pooled Postgres connection.
+ *
+ * Prisma 6 applied an implicit 5s connect timeout for Postgres; Prisma 7's
+ * driver adapters do not, and `pg.Pool` defaults to waiting forever. Without an
+ * explicit value an unreachable database would hang the boot preflight (and
+ * every request) instead of failing fast, so this restores bounded behavior.
+ * Slightly above the old 5s to stay tolerant of a cold Cloud SQL connection.
+ */
+export const DB_CONNECT_TIMEOUT_MS = 10_000;
+
+/**
+ * Build the `pg.Pool` the admin service's Prisma client runs on.
+ *
+ * Split out of `createAdminPrismaClient` so the pool's own configuration — the
+ * connect timeout and the mandatory `error` listener — is assertable without a
+ * live database.
+ */
+export function createAdminPgPool(databaseUrl: string): pg.Pool {
+  // Fail loudly on a missing connection string rather than booting against an
+  // unintended database. `pg` only parses `connectionString` when it is truthy
+  // (`if (config.connectionString) { ... }` in its ConnectionParameters), so a
+  // blank value is silently dropped and `pg.Pool` falls back to
+  // PGHOST/PGUSER/PGPASSWORD/PGDATABASE — or localhost:5432 as the OS user.
+  // The process would then either talk to the wrong database or die later with
+  // a bare `ECONNREFUSED 127.0.0.1:5432` that names no env var. Prisma 6's
+  // `new PrismaClient()` threw `Environment variable not found:
+  // DATABASE_URL_SHIPWRIGHT_ADMIN` immediately; this restores that.
+  if (databaseUrl.trim() === "") {
+    throw new Error(
+      "DATABASE_URL_SHIPWRIGHT_ADMIN is not set — the admin service requires a Postgres connection string (postgresql://user:password@host:5432/database)",
+    );
+  }
+
+  const pool = new pg.Pool({
+    // Legacy sslmode aliases are pinned to verify-full so a future pg major
+    // cannot silently drop certificate verification — see lib/pg-sslmode.ts.
+    connectionString: pinPgSslMode(databaseUrl),
+    connectionTimeoutMillis: DB_CONNECT_TIMEOUT_MS,
+  });
+
+  // Required, not diagnostic logging: `pg.Pool` re-emits backend/network errors
+  // hit by *idle* clients as its own `error` event, and `Pool` is an
+  // `EventEmitter` — an `error` event with no listener is rethrown as an
+  // uncaught exception that kills the process. Prisma 6's Rust query engine
+  // owned the pool and absorbed these; under Prisma 7 the pool is plain
+  // application code, so admin now has to own it. The service sits behind Cloud
+  // SQL / a proxy sidecar that drops idle connections, and `pg`'s default
+  // `idleTimeoutMillis` keeps idle clients around long enough to be hit. The
+  // pool discards the broken client on its own, so logging is the correct
+  // response — the next checkout just opens a fresh connection.
+  pool.on("error", (err) => {
+    console.error("[admin] idle pg pool client error:", err);
+  });
+
+  return pool;
+}
+
+/** Positive-integer env parse; anything else (unset, blank, junk, <=0) means "use the default". */
+function parsePositiveInt(raw: string | undefined): number | undefined {
+  if (raw === undefined || !/^\s*\d+\s*$/.test(raw)) return undefined;
+  const n = Number(raw);
+  return n > 0 ? n : undefined;
+}
+
+export interface AdminPoolObservabilityConfig {
+  holdThresholdMs: number | undefined;
+  monitorIntervalMs: number | undefined;
+}
+
+/**
+ * Resolve the pool-observability env overrides
+ * (SHIPWRIGHT_ADMIN_POOL_HOLD_THRESHOLD_MS / SHIPWRIGHT_ADMIN_POOL_MONITOR_INTERVAL_MS).
+ * Invalid values yield `undefined` so lib/pool-observability.ts defaults apply.
+ */
+export function resolveAdminPoolObservabilityConfig(
+  env: Record<string, string | undefined>,
+): AdminPoolObservabilityConfig {
+  return {
+    holdThresholdMs: parsePositiveInt(
+      env.SHIPWRIGHT_ADMIN_POOL_HOLD_THRESHOLD_MS,
+    ),
+    monitorIntervalMs: parsePositiveInt(
+      env.SHIPWRIGHT_ADMIN_POOL_MONITOR_INTERVAL_MS,
+    ),
+  };
+}
+
+/** Injection seams for tests. */
+export interface ObserveAdminPoolDeps {
+  log?: PoolLog;
+  clock?: Clock;
+  setInterval?: (fn: () => void, ms: number) => unknown;
+  clearInterval?: (handle: unknown) => void;
+}
+
+/**
+ * Wire hold tracking and the waiting-clients monitor onto the admin pool.
+ * Observability only — no pool size or query behavior changes. Returns a
+ * single stop fn (stops the monitor, restores `pool.connect`) for shutdown.
+ */
+export function observeAdminPool(
+  pool: CheckoutPool,
+  env: Record<string, string | undefined> = process.env,
+  deps: ObserveAdminPoolDeps = {},
+): () => void {
+  const { holdThresholdMs, monitorIntervalMs } =
+    resolveAdminPoolObservabilityConfig(env);
+  const log: PoolLog = deps.log ?? ((m, d) => console.warn(`[admin] ${m}`, d));
+  const stopHold = trackConnectionHold(pool, {
+    thresholdMs: holdThresholdMs,
+    log,
+    clock: deps.clock,
+  });
+  const stopMonitor = startPoolMonitor(pool, {
+    intervalMs: monitorIntervalMs,
+    log,
+    setInterval: deps.setInterval,
+    clearInterval: deps.clearInterval,
+  });
+  return () => {
+    stopMonitor();
+    stopHold();
+  };
+}
+
+export interface CreateAdminPrismaClientOptions {
+  /**
+   * When set, the pool is instrumented via `observeAdminPool` and this
+   * callback receives the pool plus the stop fn (call on shutdown).
+   */
+  onPoolObserved?: (observed: { pool: pg.Pool; stop: () => void }) => void;
+}
+
+/**
+ * Build an adapter-backed PrismaClient for the given Postgres connection string.
+ *
+ * `disposeExternalPool: true` is required, not cosmetic: the adapter leaves an
+ * externally supplied pool open on dispose by default, so without it every
+ * `prisma.$disconnect()` would leak its pool's sockets — which the integration
+ * suites (a fresh client per `beforeEach`) would turn into connection
+ * exhaustion within a single run.
+ *
+ * Note for BYO-Postgres operators: the connection string is parsed by `pg`, not
+ * by Prisma's old query engine, so Prisma-only query params (`schema`,
+ * `connection_limit`, `pool_timeout`, `pgbouncer`) are ignored at runtime and
+ * `sslmode=require` now verifies the server certificate (pinned explicitly to
+ * `verify-full` by `pinPgSslMode`, so a pg upgrade cannot weaken it). See
+ * `docs/migration.md` ("Breaking: admin's `DATABASE_URL_SHIPWRIGHT_ADMIN` is
+ * now parsed by `pg`, not Prisma").
+ */
+export function createAdminPrismaClient(
+  databaseUrl: string,
+  opts: CreateAdminPrismaClientOptions = {},
+): PrismaClient {
+  const pool = createAdminPgPool(databaseUrl);
+  if (opts.onPoolObserved) {
+    opts.onPoolObserved({ pool, stop: observeAdminPool(pool) });
+  }
+  const adapter = new PrismaPg(pool, { disposeExternalPool: true });
+  return new PrismaClient({ adapter });
+}

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

@@ -0,0 +1,178 @@
+/**
+ * admin/src/prisma-client.unit.test.ts
+ *
+ * Unit coverage for the parts of the client factory that do no I/O.
+ *
+ * Under Prisma 7 the client is built on a `pg.Pool` that admin now owns, so two
+ * things have to be right before anything connects:
+ *   - a blank `connectionString` must fail loudly — `pg` silently ignores a
+ *     falsy one (falling back to PGHOST/PGUSER/... or localhost), which would
+ *     boot the service against an unintended database;
+ *   - the pool must carry an `error` listener — `Pool` is an `EventEmitter`, and
+ *     an idle-client `error` with no listener is rethrown as an uncaught
+ *     exception that kills the process.
+ *
+ * `pg.Pool` does not connect on construction, so both are assertable here. The
+ * connecting paths live in prisma-client.integration.test.ts (real DB).
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  createAdminPgPool,
+  createAdminPrismaClient,
+  DB_CONNECT_TIMEOUT_MS,
+  observeAdminPool,
+  resolveAdminPoolObservabilityConfig,
+} from "./prisma-client.ts";
+
+/** A syntactically valid URL. `pg.Pool` does not connect on construction. */
+const DUMMY_URL = "postgresql://user:password@localhost:5432/shipwright_admin";
+
+describe("createAdminPgPool", () => {
+  it("attaches an 'error' listener so an idle-client error cannot crash the process", async () => {
+    const pool = createAdminPgPool(DUMMY_URL);
+    try {
+      // `Pool` is an EventEmitter: an 'error' event with no listener is
+      // rethrown as an uncaught exception. Prisma 6's engine owned the pool and
+      // absorbed these; under Prisma 7 the pool is ours, so the listener is
+      // load-bearing rather than cosmetic.
+      expect(pool.listenerCount("error")).toBeGreaterThan(0);
+    } finally {
+      await pool.end();
+    }
+  });
+
+  it("does not rethrow when the pool emits an idle-client 'error'", async () => {
+    const pool = createAdminPgPool(DUMMY_URL);
+    try {
+      expect(() => {
+        pool.emit("error", new Error("Connection terminated unexpectedly"));
+      }).not.toThrow();
+    } finally {
+      await pool.end();
+    }
+  });
+
+  it("pins a legacy sslmode=require to verify-full for pg", async () => {
+    const pool = createAdminPgPool(`${DUMMY_URL}?sslmode=require`);
+    try {
+      expect(pool.options.connectionString).toBe(
+        `${DUMMY_URL}?sslmode=verify-full`,
+      );
+    } finally {
+      await pool.end();
+    }
+  });
+
+  it("bounds the connect timeout instead of waiting forever", async () => {
+    const pool = createAdminPgPool(DUMMY_URL);
+    try {
+      expect(pool.options.connectionTimeoutMillis).toBe(DB_CONNECT_TIMEOUT_MS);
+    } finally {
+      await pool.end();
+    }
+  });
+
+  it("throws on a blank connection string before constructing a pool", () => {
+    expect(() => createAdminPgPool("")).toThrow(
+      /DATABASE_URL_SHIPWRIGHT_ADMIN is not set/,
+    );
+  });
+});
+
+describe("createAdminPrismaClient — missing connection string", () => {
+  it("throws when the connection string is empty", () => {
+    expect(() => createAdminPrismaClient("")).toThrow(
+      /DATABASE_URL_SHIPWRIGHT_ADMIN is not set/,
+    );
+  });
+
+  it("throws when the connection string is only whitespace", () => {
+    expect(() => createAdminPrismaClient("   ")).toThrow(
+      /DATABASE_URL_SHIPWRIGHT_ADMIN is not set/,
+    );
+  });
+
+  it("names the env var and the expected format in the error message", () => {
+    let message = "";
+    try {
+      createAdminPrismaClient("");
+    } catch (err) {
+      message = (err as Error).message;
+    }
+
+    expect(message).toContain("DATABASE_URL_SHIPWRIGHT_ADMIN");
+    expect(message).toContain("postgresql://");
+  });
+});
+
+describe("resolveAdminPoolObservabilityConfig", () => {
+  it("returns undefined overrides when env vars are unset", () => {
+    expect(resolveAdminPoolObservabilityConfig({})).toEqual({
+      holdThresholdMs: undefined,
+      monitorIntervalMs: undefined,
+    });
+  });
+
+  it("parses positive integer overrides", () => {
+    expect(
+      resolveAdminPoolObservabilityConfig({
+        SHIPWRIGHT_ADMIN_POOL_HOLD_THRESHOLD_MS: "500",
+        SHIPWRIGHT_ADMIN_POOL_MONITOR_INTERVAL_MS: "1000",
+      }),
+    ).toEqual({ holdThresholdMs: 500, monitorIntervalMs: 1000 });
+  });
+
+  it("falls back to defaults for blank, non-numeric, zero, or negative values", () => {
+    for (const bad of ["", "  ", "abc", "0", "-5", "1.5", "NaN"]) {
+      expect(
+        resolveAdminPoolObservabilityConfig({
+          SHIPWRIGHT_ADMIN_POOL_HOLD_THRESHOLD_MS: bad,
+          SHIPWRIGHT_ADMIN_POOL_MONITOR_INTERVAL_MS: bad,
+        }),
+      ).toEqual({ holdThresholdMs: undefined, monitorIntervalMs: undefined });
+    }
+  });
+});
+
+describe("observeAdminPool", () => {
+  it("logs holds over the env threshold and stops the monitor on stop()", async () => {
+    let now = 0;
+    const logs: Array<[string, unknown]> = [];
+    const cleared: unknown[] = [];
+    const intervals: number[] = [];
+    const released: unknown[] = [];
+    const pool = {
+      totalCount: 1,
+      idleCount: 0,
+      waitingCount: 0,
+      options: { max: 10 },
+      connect: async () => ({ release: (e?: unknown) => released.push(e) }),
+    };
+    const stop = observeAdminPool(
+      pool,
+      {
+        SHIPWRIGHT_ADMIN_POOL_HOLD_THRESHOLD_MS: "100",
+        SHIPWRIGHT_ADMIN_POOL_MONITOR_INTERVAL_MS: "250",
+      },
+      {
+        log: (m, d) => logs.push([m, d]),
+        clock: { now: () => new Date(now) },
+        setInterval: (_fn, ms) => {
+          intervals.push(ms);
+          return "h";
+        },
+        clearInterval: (h) => cleared.push(h),
+      },
+    );
+    expect(intervals).toEqual([250]);
+    const client = await pool.connect();
+    now = 150;
+    client.release();
+    expect(logs.length).toBe(1);
+    expect(logs[0]?.[0]).toBe("pg connection held past threshold");
+    expect(logs[0]?.[1]).toMatchObject({ heldMs: 150 });
+    stop();
+    expect(cleared).toEqual(["h"]);
+  });
+});

package/src/prisma-tx.ts

@@ -0,0 +1,23 @@
+/**
+ * agent/src/prisma-tx.ts
+ * Shared type for service methods that can optionally participate in a
+ * caller-supplied interactive Prisma transaction (APA-1.1).
+ *
+ * A method that normally writes via `this.prisma` (the top-level PrismaClient)
+ * accepts this as an optional trailing parameter, defaulting to `this.prisma`
+ * when omitted. Passing the `tx` argument from `prisma.$transaction(async
+ * (tx) => ...)` instead makes that write participate in the caller's
+ * transaction — see AgentService.runTransaction() and createAgent() in
+ * agents.ts for the orchestrator that drives this.
+ *
+ * A real `PrismaClient` structurally satisfies this type (it merely omits a
+ * handful of methods Prisma disallows inside an interactive transaction —
+ * $connect/$disconnect/$on/$use/$extends), so both the top-level client and
+ * the `tx` callback argument are valid arguments wherever this type is used.
+ */
+import type { PrismaClient } from "../prisma/client/client.ts";
+
+export type PrismaTransactionClient = Omit<
+  PrismaClient,
+  "$connect" | "$disconnect" | "$on" | "$use" | "$extends"
+>;

package/src/push-content.ts

@@ -0,0 +1,177 @@
+/**
+ * admin/src/push-content.ts
+ * The notification-content POLICY, as pure functions.
+ *
+ * A notification renders on a LOCKED phone, possibly in public. So the visible
+ * fields are deliberately austere:
+ *   - generic : title "Your agent replied", no body.       (default, safest)
+ *   - title   : + the thread's title in the body.
+ *   - preview : + up to 120 chars of the reply preview.
+ *
+ * NEVER included at ANY level, in ANY visible field: agent name (agent names
+ * are frequently client-shaped), ids, repo names, file paths, costs. The thread
+ * title and preview are USER-authored free text, so they could themselves
+ * contain such tokens — sanitizePublic() scrubs id/repo/path shapes before they
+ * reach a lock screen. The deep-link `url` is the ONLY field allowed to carry a
+ * threadId (the phone consumes it, it isn't rendered on the lock screen).
+ */
+
+export type PushDetailLevel = "generic" | "title" | "preview";
+
+const LEVELS: PushDetailLevel[] = ["generic", "title", "preview"];
+const LEVEL_RANK: Record<PushDetailLevel, number> = {
+  generic: 0,
+  title: 1,
+  preview: 2,
+};
+
+/** Operator ceiling default per the brief. */
+export const DEFAULT_MAX_DETAIL: PushDetailLevel = "title";
+/** Safest per-subscription default. */
+const DEFAULT_OPT_IN: PushDetailLevel = "generic";
+
+const GENERIC_TITLE = "Your agent replied";
+const PREVIEW_MAX = 120;
+
+function isLevel(v: unknown): v is PushDetailLevel {
+  return typeof v === "string" && (LEVELS as string[]).includes(v);
+}
+
+/**
+ * Effective detail level = min(operator ceiling, user opt-in). An unknown/unset
+ * ceiling falls back to the operator default (title); an unknown/unset opt-in
+ * falls back to the safest level (generic).
+ */
+export function resolveDetailLevel(
+  ceiling: PushDetailLevel | string | undefined,
+  optIn: PushDetailLevel | string | undefined,
+): PushDetailLevel {
+  const c = isLevel(ceiling) ? ceiling : DEFAULT_MAX_DETAIL;
+  const o = isLevel(optIn) ? optIn : DEFAULT_OPT_IN;
+  return LEVEL_RANK[c] <= LEVEL_RANK[o] ? c : o;
+}
+
+export interface NotificationThread {
+  threadId: string;
+  agentId: string;
+  title?: string | null;
+  /** The reply text (or a slice of it) used to build a preview. */
+  preview?: string | null;
+}
+
+interface NotificationPayload {
+  title: string;
+  body: string;
+  /** Deep link to the thread — consumed by the SW, not shown on the lock screen. */
+  url: string;
+}
+
+// Token shapes that must never surface on a lock screen. Applied to any
+// user-authored free text (thread title / preview) before it is rendered.
+const ID_SHAPE = /\b[a-z]{2,}[_-][A-Za-z0-9_-]{4,}\b/g; // agt_..., thr_..., WLS-2.2-ish
+const CUID_SHAPE = /\bc[a-z0-9]{24}\b/g; // prisma cuid
+const REPO_SHAPE = /\b[\w.-]+\/[\w.-]+(?:\/[\w.-]+)*\b/g; // owner/repo, src/foo/bar.ts
+const COST_SHAPE = /\$\s?\d[\d,]*(?:\.\d+)?/g; // $4.20
+
+/**
+ * Scrubs id/repo/path/cost shapes out of user-authored free text so nothing
+ * client-shaped reaches a lock screen. Conservative by design: a false-positive
+ * redaction (an innocuous slash-word) is strictly safer than a leak.
+ */
+function sanitizePublic(text: string): string {
+  return text
+    .replace(CUID_SHAPE, "…")
+    .replace(REPO_SHAPE, "…")
+    .replace(ID_SHAPE, "…")
+    .replace(COST_SHAPE, "…")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Truncates already-sanitized preview text to the shared lock-screen cap. */
+function truncateForPreview(text: string): string {
+  return text.length > PREVIEW_MAX ? text.slice(0, PREVIEW_MAX) : text;
+}
+
+/** Builds the notification payload for a resolved detail level. */
+export function buildNotificationPayload(
+  level: PushDetailLevel,
+  thread: NotificationThread,
+): NotificationPayload {
+  const url = `/admin/chat/${encodeURIComponent(
+    thread.agentId,
+  )}/threads/${encodeURIComponent(thread.threadId)}`;
+
+  if (level === "generic") {
+    return { title: GENERIC_TITLE, body: "", url };
+  }
+
+  if (level === "title") {
+    const safeTitle = sanitizePublic(thread.title ?? "");
+    return { title: GENERIC_TITLE, body: safeTitle, url };
+  }
+
+  // preview
+  const raw = sanitizePublic(thread.preview ?? thread.title ?? "");
+  return { title: GENERIC_TITLE, body: truncateForPreview(raw), url };
+}
+
+/**
+ * admin/src/push-content.ts — session notification policy.
+ *
+ * A sibling to the chat-thread notification path above, for the separate
+ * "session needs attention / completed" surface. Same lock-screen austerity
+ * policy applies: user-authored free text (session title / reason) is
+ * sanitized before it reaches a visible field. The deep-link `url` is the
+ * only field allowed to carry the session slug (consumed by the SW, not
+ * rendered on the lock screen); `tag` also carries the slug, per spec, so
+ * the OS can coalesce repeat notifications for the same session.
+ */
+
+export type SessionNotificationKind = "immediate" | "reminder" | "completed";
+
+export interface NotificationSession {
+  slug: string;
+  title?: string | null;
+  /** User-authored free text explaining why the session needs attention. */
+  reason?: string | null;
+}
+
+interface SessionNotificationPayload {
+  title: string;
+  body: string;
+  /** Deep link to the session — consumed by the SW, not shown on the lock screen. */
+  url: string;
+  tag: string;
+  kind: SessionNotificationKind;
+}
+
+const SESSION_KIND_TITLES: Record<SessionNotificationKind, string> = {
+  immediate: "A session needs you",
+  reminder: "Still waiting on you",
+  completed: "Session completed",
+};
+
+/** Builds the notification payload for a session, per kind and detail level. */
+export function buildSessionNotificationPayload(
+  level: PushDetailLevel,
+  kind: SessionNotificationKind,
+  session: NotificationSession,
+): SessionNotificationPayload {
+  const title = SESSION_KIND_TITLES[kind];
+  const url = `/admin/sessions/${encodeURIComponent(session.slug)}`;
+  const tag = `shipwright-session-${session.slug}`;
+
+  if (level === "generic") {
+    return { title, body: "", url, tag, kind };
+  }
+
+  if (level === "title") {
+    const safeTitle = sanitizePublic(session.title ?? "");
+    return { title, body: safeTitle, url, tag, kind };
+  }
+
+  // preview
+  const raw = sanitizePublic(session.reason ?? session.title ?? "");
+  return { title, body: truncateForPreview(raw), url, tag, kind };
+}