@app-vitals/agent-lib 0.0.1 → 0.1.1

package/pg-sslmode.ts

@@ -0,0 +1,66 @@
+/**
+ * lib/pg-sslmode.ts
+ *
+ * Pins node-postgres's TLS behavior for a Postgres connection string.
+ *
+ * `pg` 8.x (via pg-connection-string 2.x) treats `sslmode=prefer`, `require`,
+ * and `verify-ca` as aliases for `verify-full` — the server certificate chain
+ * and hostname are both verified — and logs a SECURITY WARNING saying the next
+ * major (pg 9 / pg-connection-string 3) will switch them to libpq semantics,
+ * where `require` means "encrypt, verify nothing". Upgrading `pg` would then
+ * silently drop certificate verification for every deployment whose URL says
+ * `sslmode=require`.
+ *
+ * Rewriting those modes to `verify-full` in the string handed to `pg` keeps
+ * today's (verifying) behavior across that upgrade and silences the warning.
+ * It is applied only to the `pg.Pool` connection string — never to the env var
+ * itself — because the same URL is also read by the Prisma CLI
+ * (`prisma migrate deploy` via prisma.config.ts), whose engine recognises only
+ * `disable|prefer|require` and would read `verify-full` as `prefer`.
+ *
+ * Left untouched:
+ *   - URLs with no `sslmode`, or `disable` / `verify-full` / `no-verify`
+ *     (none of them warn, and none change meaning in pg 9);
+ *   - URLs that set `uselibpqcompat=true`: that is an explicit opt-in to libpq
+ *     semantics, which this must not override;
+ *   - strings that are not parseable as a URL (pg accepts other forms; pass
+ *     them through for pg to handle or reject).
+ */
+
+/** The sslmode values pg 8 aliases to `verify-full` (and warns about). */
+const LEGACY_VERIFY_FULL_ALIASES = new Set(["prefer", "require", "verify-ca"]);
+
+/**
+ * Returns `connectionString` with a legacy `sslmode` alias replaced by
+ * `verify-full`, or the input unchanged when no rewrite applies.
+ */
+export function pinPgSslMode(connectionString: string): string {
+  let url: URL;
+  try {
+    url = new URL(connectionString);
+  } catch {
+    return connectionString;
+  }
+
+  // Resolve the effective `sslmode` the same way pg-connection-string's
+  // parse() does: iterate every query param in document order and let later
+  // entries overwrite earlier ones (`config[entry[0]] = entry[1]`). A
+  // duplicate `sslmode` therefore resolves to its LAST occurrence — not the
+  // first, which is what `URLSearchParams#get()` would return — so this must
+  // not use `.get()` here.
+  let sslmode: string | null = null;
+  for (const [key, value] of url.searchParams) {
+    if (key === "sslmode") {
+      sslmode = value;
+    }
+  }
+  if (sslmode === null || !LEGACY_VERIFY_FULL_ALIASES.has(sslmode)) {
+    return connectionString;
+  }
+  if (url.searchParams.get("uselibpqcompat") === "true") {
+    return connectionString;
+  }
+
+  url.searchParams.set("sslmode", "verify-full");
+  return url.toString();
+}

package/pg-sslmode.unit.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { pinPgSslMode } from "./pg-sslmode.ts";
+
+const BASE = "postgresql://user:pass@db.example.test:5432/app";
+
+describe("pinPgSslMode — legacy aliases are pinned to verify-full", () => {
+  for (const mode of ["prefer", "require", "verify-ca"]) {
+    test(`rewrites sslmode=${mode} to sslmode=verify-full`, () => {
+      const pinned = new URL(pinPgSslMode(`${BASE}?sslmode=${mode}`));
+      expect(pinned.searchParams.get("sslmode")).toBe("verify-full");
+    });
+  }
+
+  test("preserves credentials, host, database, and other params", () => {
+    const pinned = new URL(
+      pinPgSslMode(`${BASE}?connection_limit=5&sslmode=require&schema=public`),
+    );
+    expect(pinned.username).toBe("user");
+    expect(pinned.password).toBe("pass");
+    expect(pinned.host).toBe("db.example.test:5432");
+    expect(pinned.pathname).toBe("/app");
+    expect(pinned.searchParams.get("connection_limit")).toBe("5");
+    expect(pinned.searchParams.get("schema")).toBe("public");
+  });
+
+  test("keeps a URL-encoded password byte-for-byte when rewriting", () => {
+    const pinned = pinPgSslMode(
+      "postgresql://user:p%40ss%2Fw@localhost:5432/app?sslmode=require",
+    );
+    expect(pinned).toBe(
+      "postgresql://user:p%40ss%2Fw@localhost:5432/app?sslmode=verify-full",
+    );
+  });
+
+  test("a duplicate sslmode resolves to the LAST occurrence, like pg-connection-string", () => {
+    // pg-connection-string's parse() iterates every query param and lets
+    // later entries overwrite earlier ones, so `pg` itself connects using
+    // the second `sslmode` here ("require"), not the first ("verify-full").
+    // Using URLSearchParams#get() (first-match) would wrongly see
+    // "verify-full" and skip the rewrite, leaving the string's final
+    // sslmode as the unrewritten legacy "require".
+    const pinned = new URL(
+      pinPgSslMode(`${BASE}?sslmode=verify-full&sslmode=require`),
+    );
+    expect(pinned.searchParams.getAll("sslmode")).toEqual(["verify-full"]);
+  });
+});
+
+describe("pinPgSslMode — inputs left untouched", () => {
+  test("a URL with no sslmode", () => {
+    expect(pinPgSslMode(BASE)).toBe(BASE);
+  });
+
+  for (const mode of ["disable", "verify-full", "no-verify"]) {
+    test(`sslmode=${mode}`, () => {
+      const input = `${BASE}?sslmode=${mode}`;
+      expect(pinPgSslMode(input)).toBe(input);
+    });
+  }
+
+  test("an explicit uselibpqcompat=true opt-in", () => {
+    const input = `${BASE}?uselibpqcompat=true&sslmode=require`;
+    expect(pinPgSslMode(input)).toBe(input);
+  });
+
+  test("a string that is not a URL", () => {
+    expect(pinPgSslMode("not a url")).toBe("not a url");
+  });
+
+  test("a URL-encoded password survives unchanged when no rewrite applies", () => {
+    const input = "postgresql://user:p%40ss%2Fw@localhost:5432/app";
+    expect(pinPgSslMode(input)).toBe(input);
+  });
+});

package/pool-observability.ts

@@ -0,0 +1,209 @@
+/**
+ * lib/pool-observability.ts
+ * Observability helpers for diagnosing pg pool starvation (Sentry SENTRY-5T).
+ *
+ * Observability only: nothing here changes pool or client behavior. Types are
+ * structural so this module needs no direct dependency on `pg` or `hono`.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Minimal Clock (matches the Clock interface used across services). */
+export interface Clock {
+  now(): Date;
+}
+
+export interface PoolLike {
+  totalCount: number;
+  idleCount: number;
+  waitingCount: number;
+  options?: { max?: number };
+}
+
+export interface PoolSnapshot {
+  total: number;
+  idle: number;
+  waiting: number;
+  max: number | null;
+}
+
+export type PoolLog = (message: string, data?: Record<string, unknown>) => void;
+
+type ReleaseFn = (err?: Error | boolean) => void;
+
+export interface CheckoutPool extends PoolLike {
+  // biome-ignore lint/suspicious/noExplicitAny: matches pg's overloaded connect()
+  connect: (...args: any[]) => any;
+}
+
+const systemClock: Clock = { now: () => new Date() };
+
+// ─── Snapshot / error detection ───────────────────────────────────────────────
+
+export function snapshotPool(pool: PoolLike): PoolSnapshot {
+  return {
+    total: pool.totalCount,
+    idle: pool.idleCount,
+    waiting: pool.waitingCount,
+    max: pool.options?.max ?? null,
+  };
+}
+
+/** True for Prisma P2028, "Unable to start a transaction", or pg connection timeouts. */
+export function isPoolTimeoutError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const { code, message } = err as { code?: unknown; message?: unknown };
+  if (code === "P2028") return true;
+  if (typeof message !== "string") return false;
+  return (
+    message.includes("Unable to start a transaction") ||
+    /timeout exceeded when trying to connect/i.test(message) ||
+    /connection timeout/i.test(message)
+  );
+}
+
+// ─── Monitor ──────────────────────────────────────────────────────────────────
+
+export interface PoolMonitorOptions {
+  intervalMs?: number;
+  log?: PoolLog;
+  setInterval?: (fn: () => void, ms: number) => unknown;
+  clearInterval?: (handle: unknown) => void;
+}
+
+/** Periodically logs the pool snapshot, only while clients are waiting. Returns a stop fn. */
+export function startPoolMonitor(
+  pool: PoolLike,
+  opts: PoolMonitorOptions = {},
+): () => void {
+  const {
+    intervalMs = 30_000,
+    log = (m, d) => console.warn(m, d),
+    setInterval: setIntervalFn = (fn, ms) => setInterval(fn, ms),
+    clearInterval: clearIntervalFn = (h) =>
+      clearInterval(h as ReturnType<typeof setInterval>),
+  } = opts;
+  const handle = setIntervalFn(() => {
+    const snap = snapshotPool(pool);
+    if (snap.waiting > 0) log("pg pool has waiting clients", { ...snap });
+  }, intervalMs);
+  return () => clearIntervalFn(handle);
+}
+
+// ─── Route context ────────────────────────────────────────────────────────────
+
+export interface RouteContext {
+  method: string;
+  route: string;
+}
+
+const routeStorage = new AsyncLocalStorage<RouteContext>();
+
+export function runWithRouteContext<T>(ctx: RouteContext, fn: () => T): T {
+  return routeStorage.run(ctx, fn);
+}
+
+export function currentRouteContext(): RouteContext | undefined {
+  return routeStorage.getStore();
+}
+
+interface HonoLikeContext {
+  req: {
+    method: string;
+    path: string;
+    matchedRoutes?: { path: string }[];
+  };
+}
+
+/**
+ * Hono middleware factory recording the request method and matched route
+ * pattern. The pattern is resolved lazily (at read time) so it reflects the
+ * handler route rather than the wildcard this middleware is mounted on.
+ */
+export function routeContextMiddleware() {
+  return async (c: HonoLikeContext, next: () => Promise<void>) => {
+    const ctx: RouteContext = {
+      method: c.req.method,
+      get route() {
+        const matched = c.req.matchedRoutes;
+        return matched?.length
+          ? (matched[matched.length - 1] as { path: string }).path
+          : c.req.path;
+      },
+    };
+    await runWithRouteContext(ctx, next);
+  };
+}
+
+// ─── Connection hold tracking ─────────────────────────────────────────────────
+
+export interface TrackHoldOptions {
+  thresholdMs?: number;
+  log?: PoolLog;
+  clock?: Clock;
+}
+
+/**
+ * Wraps `pool.connect()` so each checked-out client's `release` logs when the
+ * connection was held longer than `thresholdMs`. Release semantics are
+ * preserved exactly: args are forwarded untouched and the underlying release
+ * is invoked on every call (so pg's own double-release error still surfaces).
+ * Returns a function restoring the original `connect`.
+ */
+export function trackConnectionHold(
+  pool: CheckoutPool,
+  opts: TrackHoldOptions = {},
+): () => void {
+  const {
+    thresholdMs = 2000,
+    log = (m, d) => console.warn(m, d),
+    clock = systemClock,
+  } = opts;
+  const originalConnect = pool.connect;
+
+  const wrap = (client: { release: ReleaseFn }) => {
+    const checkedOutAt = clock.now().getTime();
+    const route = currentRouteContext();
+    const originalRelease = client.release;
+    let reported = false;
+    client.release = function (this: unknown, ...args: [(Error | boolean)?]) {
+      if (!reported) {
+        reported = true;
+        const heldMs = clock.now().getTime() - checkedOutAt;
+        if (heldMs > thresholdMs) {
+          log("pg connection held past threshold", {
+            route: route ? `${route.method} ${route.route}` : null,
+            heldMs,
+            pool: snapshotPool(pool),
+          });
+        }
+      }
+      return originalRelease.apply(client, args);
+    } as ReleaseFn;
+    return client;
+  };
+
+  pool.connect = function (this: unknown, ...args: unknown[]) {
+    const result = originalConnect.apply(pool, args);
+    // Callback-style connect(cb) is passed through untracked.
+    if (typeof args[0] === "function") return result;
+    return (result as Promise<{ release: ReleaseFn }>).then(wrap);
+  };
+
+  return () => {
+    pool.connect = originalConnect;
+  };
+}
+
+// ─── Sentry context ───────────────────────────────────────────────────────────
+
+/** Object to attach to Sentry events (e.g. `scope.setContext("pg_pool", ...)`). */
+export function poolErrorContext(pool: PoolLike): Record<string, unknown> {
+  const route = currentRouteContext();
+  return {
+    ...snapshotPool(pool),
+    route: route ? `${route.method} ${route.route}` : null,
+  };
+}

package/pool-observability.unit.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type CheckoutPool,
+  type Clock,
+  isPoolTimeoutError,
+  poolErrorContext,
+  routeContextMiddleware,
+  runWithRouteContext,
+  snapshotPool,
+  startPoolMonitor,
+  trackConnectionHold,
+} from "./pool-observability.ts";
+
+function makePool(over: Partial<CheckoutPool> = {}) {
+  const released: unknown[][] = [];
+  const pool: CheckoutPool = {
+    totalCount: 3,
+    idleCount: 1,
+    waitingCount: 0,
+    options: { max: 10 },
+    connect: async () => ({
+      release: (...args: unknown[]) => {
+        released.push(args);
+      },
+    }),
+    ...over,
+  };
+  return { pool, released };
+}
+
+function makeClock(startMs = 0) {
+  let t = startMs;
+  const clock: Clock = { now: () => new Date(t) };
+  return {
+    clock,
+    advance: (ms: number) => {
+      t += ms;
+    },
+  };
+}
+
+describe("snapshotPool", () => {
+  test("maps pool counts and max", () => {
+    expect(snapshotPool(makePool().pool)).toEqual({
+      total: 3,
+      idle: 1,
+      waiting: 0,
+      max: 10,
+    });
+  });
+});
+
+describe("isPoolTimeoutError", () => {
+  test("matches Prisma P2028", () => {
+    expect(isPoolTimeoutError({ code: "P2028", message: "x" })).toBe(true);
+  });
+  test("matches message variants", () => {
+    expect(
+      isPoolTimeoutError(
+        new Error("Unable to start a transaction in the given time."),
+      ),
+    ).toBe(true);
+    expect(
+      isPoolTimeoutError(new Error("timeout exceeded when trying to connect")),
+    ).toBe(true);
+    expect(
+      isPoolTimeoutError(
+        new Error("Connection terminated due to connection timeout"),
+      ),
+    ).toBe(true);
+  });
+  test("rejects unrelated errors", () => {
+    expect(isPoolTimeoutError(new Error("syntax error"))).toBe(false);
+    expect(isPoolTimeoutError({ code: "P2002" })).toBe(false);
+    expect(isPoolTimeoutError(null)).toBe(false);
+    expect(isPoolTimeoutError("timeout")).toBe(false);
+  });
+});
+
+describe("startPoolMonitor", () => {
+  function harness(pool: CheckoutPool) {
+    let tick: () => void = () => {};
+    let cleared: unknown;
+    const logs: unknown[][] = [];
+    const stop = startPoolMonitor(pool, {
+      intervalMs: 5,
+      log: (...a) => void logs.push(a),
+      setInterval: (fn, ms) => {
+        expect(ms).toBe(5);
+        tick = fn;
+        return "h";
+      },
+      clearInterval: (h) => {
+        cleared = h;
+      },
+    });
+    return { tick: () => tick(), stop, logs, cleared: () => cleared };
+  }
+
+  test("does not log when nobody is waiting", () => {
+    const h = harness(makePool().pool);
+    h.tick();
+    expect(h.logs).toHaveLength(0);
+  });
+
+  test("logs a snapshot when waiting > 0", () => {
+    const h = harness(makePool({ waitingCount: 4 }).pool);
+    h.tick();
+    expect(h.logs).toHaveLength(1);
+    expect(h.logs[0]?.[1]).toMatchObject({ waiting: 4, total: 3, max: 10 });
+  });
+
+  test("stop fn clears the interval", () => {
+    const h = harness(makePool().pool);
+    h.stop();
+    expect(h.cleared()).toBe("h");
+  });
+});
+
+describe("trackConnectionHold", () => {
+  async function run(
+    holdMs: number,
+    route?: { method: string; route: string },
+  ) {
+    const { pool, released } = makePool({ waitingCount: 2 });
+    const { clock, advance } = makeClock();
+    const logs: unknown[][] = [];
+    trackConnectionHold(pool, {
+      thresholdMs: 2000,
+      clock,
+      log: (...a) => void logs.push(a),
+    });
+    const exec = async () => {
+      const client = await pool.connect();
+      advance(holdMs);
+      client.release();
+      return client;
+    };
+    const client = route
+      ? await runWithRouteContext(route, exec)
+      : await exec();
+    return { client, logs, released };
+  }
+
+  test("does not log under the threshold", async () => {
+    const { logs, released } = await run(1500);
+    expect(logs).toHaveLength(0);
+    expect(released).toHaveLength(1);
+  });
+
+  test("logs route, heldMs and pool snapshot over the threshold", async () => {
+    const { logs } = await run(2500, { method: "GET", route: "/tasks/:id" });
+    expect(logs).toHaveLength(1);
+    expect(logs[0]?.[1]).toMatchObject({
+      route: "GET /tasks/:id",
+      heldMs: 2500,
+      pool: { total: 3, waiting: 2 },
+    });
+  });
+
+  test("route is null outside a request", async () => {
+    const { logs } = await run(2500);
+    expect(logs[0]?.[1]).toMatchObject({ route: null });
+  });
+
+  test("release is called once per call, error arg forwarded", async () => {
+    const { pool, released } = makePool();
+    trackConnectionHold(pool);
+    const client = await pool.connect();
+    const err = new Error("boom");
+    client.release(err);
+    expect(released).toEqual([[err]]);
+  });
+
+  test("double release behaves as unwrapped (underlying called each time)", async () => {
+    const { pool, released } = makePool();
+    const { clock, advance } = makeClock();
+    const logs: unknown[][] = [];
+    trackConnectionHold(pool, { clock, log: (...a) => void logs.push(a) });
+    const client = await pool.connect();
+    advance(5000);
+    client.release();
+    client.release(true);
+    expect(released).toEqual([[], [true]]);
+    expect(logs).toHaveLength(1);
+  });
+
+  test("restore fn reinstates original connect", async () => {
+    const { pool } = makePool();
+    const original = pool.connect;
+    const restore = trackConnectionHold(pool);
+    expect(pool.connect).not.toBe(original);
+    restore();
+    expect(pool.connect).toBe(original);
+  });
+});
+
+describe("routeContextMiddleware", () => {
+  test("records method and matched route pattern for poolErrorContext", async () => {
+    const { pool } = makePool();
+    let seen: Record<string, unknown> | undefined;
+    const c = {
+      req: {
+        method: "GET",
+        path: "/tasks/42",
+        matchedRoutes: [{ path: "/*" }, { path: "/tasks/:id" }],
+      },
+    };
+    await routeContextMiddleware()(c, async () => {
+      seen = poolErrorContext(pool);
+    });
+    expect(seen).toEqual({
+      total: 3,
+      idle: 1,
+      waiting: 0,
+      max: 10,
+      route: "GET /tasks/:id",
+    });
+  });
+
+  test("falls back to the request path without matchedRoutes", async () => {
+    let seen: Record<string, unknown> | undefined;
+    const c = { req: { method: "POST", path: "/x" } };
+    await routeContextMiddleware()(c, async () => {
+      seen = poolErrorContext(makePool().pool);
+    });
+    expect(seen?.route).toBe("POST /x");
+  });
+
+  test("poolErrorContext has null route outside a request", () => {
+    expect(poolErrorContext(makePool().pool).route).toBeNull();
+  });
+});

package/pricing.ts

@@ -0,0 +1,98 @@
+export interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_creation_input_tokens: number;
+}
+
+interface ModelRates {
+  input: number;
+  output: number;
+}
+
+export const OPUS_MODEL = "claude-opus-4-8";
+
+export const RATES: Record<string, ModelRates> = {
+  "claude-fable-5-1": { input: 10.0, output: 50.0 },
+  "claude-fable-5": { input: 10.0, output: 50.0 },
+  "claude-opus-5-5": { input: 4.0, output: 20.0 },
+  "claude-opus-4-8": { input: 5.0, output: 25.0 },
+  "claude-opus-4-7": { input: 5.0, output: 25.0 },
+  "claude-opus-4-6": { input: 5.0, output: 25.0 },
+  "claude-sonnet-5-5": { input: 2.0, output: 10.0 },
+  "claude-sonnet-4-6": { input: 3.0, output: 15.0 },
+  "claude-haiku-5-5": { input: 0.1, output: 0.5 },
+  "claude-haiku-4-5": { input: 1.0, output: 5.0 },
+  "claude-haiku-4-6": { input: 1.0, output: 5.0 },
+};
+
+/**
+ * Context window (input tokens) per rate key. Used by the prompt-audit
+ * tooling to express always-loaded context as a share of the window and to
+ * size the skill-listing budget (Claude Code reserves 1% of the window for
+ * the skill listing). Keys mirror RATES.
+ */
+export const CONTEXT_WINDOW: Record<string, number> = {
+  "claude-fable-5-1": 1_000_000,
+  "claude-fable-5": 1_000_000,
+  "claude-opus-5-5": 1_000_000,
+  "claude-opus-4-8": 1_000_000,
+  "claude-opus-4-7": 1_000_000,
+  "claude-opus-4-6": 1_000_000,
+  "claude-sonnet-5-5": 1_000_000,
+  "claude-sonnet-4-6": 1_000_000,
+  "claude-haiku-5-5": 1_000_000,
+  "claude-haiku-4-5": 200_000,
+  "claude-haiku-4-6": 200_000,
+};
+
+export function calculateCost(usage: TokenUsage, model: string): number {
+  const rates = RATES[model];
+  if (!rates) return 0;
+
+  const { input, output } = rates;
+  const cost =
+    usage.input_tokens * input +
+    usage.output_tokens * output +
+    usage.cache_creation_input_tokens * input * 1.25 +
+    usage.cache_read_input_tokens * input * 0.1;
+
+  return cost / 1_000_000;
+}
+
+export function normalizeModelToRateKey(model: string): string | null {
+  const bareModel = model.replace(/-\d{8}$/, "");
+  // Current-generation ids price as themselves. The bare "sonnet"/"opus"/
+  // "haiku" aliases resolve to the 5.5 keys; 4.x ids keep their own mapping.
+  if (
+    bareModel === "claude-fable-5-1" ||
+    bareModel === "claude-opus-5-5" ||
+    bareModel === "claude-sonnet-5-5" ||
+    bareModel === "claude-haiku-5-5"
+  ) {
+    return bareModel;
+  }
+  if (bareModel === "haiku") return "claude-haiku-5-5";
+  if (bareModel === "opus") return "claude-opus-5-5";
+  if (bareModel === "sonnet") return "claude-sonnet-5-5";
+  if (
+    bareModel === "claude-haiku-4-5" ||
+    bareModel === "claude-haiku-4-6"
+  ) {
+    return "claude-haiku-4-5";
+  }
+  if (bareModel === "claude-sonnet-4-6") {
+    return "claude-sonnet-4-6";
+  }
+  if (
+    bareModel === "claude-opus-4-8" ||
+    bareModel === "claude-opus-4-7" ||
+    bareModel === "claude-opus-4-6"
+  ) {
+    return "claude-opus-4-8";
+  }
+  if (bareModel === "fable" || bareModel === "claude-fable-5") {
+    return "claude-fable-5";
+  }
+  return null;
+}