@agent-native/core 0.113.0 → 0.114.0

package/src/notifications/routes.ts

@@ -0,0 +1,106 @@
+/**
+ * H3 event handlers for the notifications inbox.
+ *
+ * Mounted under `/_agent-native/notifications/*` by `core-routes-plugin`.
+ *
+ *   GET  /_agent-native/notifications?unread=true&limit=50&before=ISO
+ *                                                   — list for the session owner
+ *   GET  /_agent-native/notifications/count         — unread count
+ *   POST /_agent-native/notifications/:id/read      — mark as read
+ *   POST /_agent-native/notifications/read-all      — mark all read
+ *   DELETE /_agent-native/notifications/:id         — delete
+ */
+
+import {
+  defineEventHandler,
+  getMethod,
+  getQuery,
+  setResponseStatus,
+  type H3Event,
+} from "h3";
+
+import { getSession } from "../server/auth.js";
+import {
+  listNotifications,
+  countUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  deleteNotification,
+} from "./store.js";
+
+function parseLimit(value: unknown, fallback = 50): number {
+  if (typeof value !== "string" || value.length === 0) return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.min(Math.floor(n), 200);
+}
+
+async function resolveOwner(event: H3Event): Promise<string> {
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) {
+    const { createError } = await import("h3");
+    throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
+  }
+  return session.email;
+}
+
+export function createNotificationsHandler() {
+  return defineEventHandler(async (event: H3Event) => {
+    const rawMethod = getMethod(event);
+    const method = rawMethod === "HEAD" ? "GET" : rawMethod;
+    if (rawMethod === "OPTIONS") {
+      setResponseStatus(event, 204);
+      return "";
+    }
+    const pathname = (event.url?.pathname || "")
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "");
+    const parts = pathname ? pathname.split("/") : [];
+    const owner = await resolveOwner(event);
+
+    // GET /  — list
+    if (method === "GET" && parts.length === 0) {
+      const q = getQuery(event);
+      return listNotifications(owner, {
+        unreadOnly: q.unread === "true" || q.unread === "1",
+        limit: parseLimit(q.limit),
+        before: typeof q.before === "string" ? q.before : undefined,
+      });
+    }
+
+    // GET /count
+    if (method === "GET" && parts.length === 1 && parts[0] === "count") {
+      const count = await countUnread(owner);
+      return { count };
+    }
+
+    // POST /read-all
+    if (method === "POST" && parts.length === 1 && parts[0] === "read-all") {
+      const updated = await markAllNotificationsRead(owner);
+      return { updated };
+    }
+
+    // POST /:id/read
+    if (method === "POST" && parts.length === 2 && parts[1] === "read") {
+      const ok = await markNotificationRead(parts[0], owner);
+      if (!ok) {
+        setResponseStatus(event, 404);
+        return { error: "Not found or already read" };
+      }
+      return { ok: true };
+    }
+
+    // DELETE /:id
+    if (method === "DELETE" && parts.length === 1) {
+      const ok = await deleteNotification(parts[0], owner);
+      if (!ok) {
+        setResponseStatus(event, 404);
+        return { error: "Not found" };
+      }
+      return { ok: true };
+    }
+
+    setResponseStatus(event, 404);
+    return { error: "Not found" };
+  });
+}

package/src/notifications/store.ts

@@ -0,0 +1,236 @@
+import { randomUUID } from "node:crypto";
+
+import {
+  getDbExec,
+  intType,
+  isPostgres,
+  retryOnDdlRace,
+  safeJsonParse,
+} from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+import { recordChange } from "../server/poll.js";
+import type { Notification, NotificationSeverity } from "./types.js";
+
+function bumpPoll(owner: string): void {
+  recordChange({ source: "notifications", type: "change", key: owner });
+}
+
+let _initPromise: Promise<void> | undefined;
+
+function normalizeLimit(value: number | undefined, fallback = 50): number {
+  if (!Number.isFinite(value) || value == null || value <= 0) return fallback;
+  return Math.min(Math.floor(value), 200);
+}
+
+async function ensureTable(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const client = getDbExec();
+      const createSql = `
+          CREATE TABLE IF NOT EXISTS notifications (
+            id TEXT PRIMARY KEY,
+            owner TEXT NOT NULL,
+            severity TEXT NOT NULL,
+            title TEXT NOT NULL,
+            body TEXT,
+            metadata TEXT,
+            delivered_channels TEXT NOT NULL DEFAULT '[]',
+            created_at ${intType()} NOT NULL,
+            read_at ${intType()}
+          )
+        `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema / pg_indexes first (no lock) and
+        // only issue DDL when the table/index is actually missing, wrapped in
+        // a transaction-scoped lock_timeout so a contended lock fails fast.
+        await ensureTableExists("notifications", createSql);
+        await ensureIndexExists(
+          "idx_notifications_owner_unread",
+          `CREATE INDEX IF NOT EXISTS idx_notifications_owner_unread ON notifications (owner, read_at)`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no ACCESS EXCLUSIVE lock problem — keep existing
+      // retryOnDdlRace behaviour.
+      await retryOnDdlRace(() => client.execute(createSql));
+      await retryOnDdlRace(() =>
+        client.execute(
+          `CREATE INDEX IF NOT EXISTS idx_notifications_owner_unread ON notifications (owner, read_at)`,
+        ),
+      );
+    })().catch((err) => {
+      // Reset on failure so a transient DB outage doesn't poison the cached
+      // promise and reject every future insert/list call for the lifetime of
+      // the process.
+      _initPromise = undefined;
+      throw err;
+    });
+  }
+  return _initPromise;
+}
+
+function parseRow(row: Record<string, unknown>): Notification {
+  return {
+    id: String(row.id),
+    owner: String(row.owner),
+    severity: String(row.severity) as NotificationSeverity,
+    title: String(row.title),
+    body: row.body == null ? undefined : String(row.body),
+    metadata: row.metadata
+      ? safeJsonParse<Record<string, unknown> | undefined>(
+          row.metadata,
+          undefined,
+        )
+      : undefined,
+    deliveredChannels: safeJsonParse<string[]>(row.delivered_channels, []),
+    createdAt: new Date(Number(row.created_at)).toISOString(),
+    readAt:
+      row.read_at == null ? null : new Date(Number(row.read_at)).toISOString(),
+  };
+}
+
+export interface InsertNotificationInput {
+  owner: string;
+  severity: NotificationSeverity;
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  deliveredChannels?: string[];
+}
+
+export async function insertNotification(
+  input: InsertNotificationInput,
+): Promise<Notification> {
+  await ensureTable();
+  const client = getDbExec();
+  const id = randomUUID();
+  const createdAt = Date.now();
+  await client.execute({
+    sql: `INSERT INTO notifications
+      (id, owner, severity, title, body, metadata, delivered_channels, created_at, read_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)`,
+    args: [
+      id,
+      input.owner,
+      input.severity,
+      input.title,
+      input.body ?? null,
+      input.metadata ? JSON.stringify(input.metadata) : null,
+      JSON.stringify(input.deliveredChannels ?? []),
+      createdAt,
+    ],
+  });
+  bumpPoll(input.owner);
+  return {
+    id,
+    owner: input.owner,
+    severity: input.severity,
+    title: input.title,
+    body: input.body,
+    metadata: input.metadata,
+    deliveredChannels: input.deliveredChannels ?? [],
+    createdAt: new Date(createdAt).toISOString(),
+    readAt: null,
+  };
+}
+
+export async function updateDeliveredChannels(
+  id: string,
+  channels: string[],
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  await client.execute({
+    sql: `UPDATE notifications SET delivered_channels = ? WHERE id = ?`,
+    args: [JSON.stringify(channels), id],
+  });
+}
+
+export interface ListNotificationsOptions {
+  /** When true, only return unread (read_at IS NULL). */
+  unreadOnly?: boolean;
+  /** Max rows to return. Default 50. */
+  limit?: number;
+  /** ISO timestamp cursor — returns rows with created_at < cursor. */
+  before?: string;
+}
+
+export async function listNotifications(
+  owner: string,
+  options: ListNotificationsOptions = {},
+): Promise<Notification[]> {
+  await ensureTable();
+  const client = getDbExec();
+  const limit = normalizeLimit(options.limit);
+  const args: Array<string | number> = [owner];
+  let where = `owner = ?`;
+  if (options.unreadOnly) where += ` AND read_at IS NULL`;
+  if (options.before) {
+    where += ` AND created_at < ?`;
+    args.push(new Date(options.before).getTime());
+  }
+  args.push(limit);
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM notifications WHERE ${where} ORDER BY created_at DESC LIMIT ?`,
+    args,
+  });
+  return rows.map((r) => parseRow(r as Record<string, unknown>));
+}
+
+export async function countUnread(owner: string): Promise<number> {
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT COUNT(*) as c FROM notifications WHERE owner = ? AND read_at IS NULL`,
+    args: [owner],
+  });
+  return Number(rows[0]?.c ?? 0);
+}
+
+export async function markNotificationRead(
+  id: string,
+  owner: string,
+): Promise<boolean> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  const res = await client.execute({
+    sql: `UPDATE notifications SET read_at = ? WHERE id = ? AND owner = ? AND read_at IS NULL`,
+    args: [now, id, owner],
+  });
+  const updated =
+    (res as unknown as { rowsAffected?: number }).rowsAffected !== 0;
+  if (updated) bumpPoll(owner);
+  return updated;
+}
+
+export async function markAllNotificationsRead(owner: string): Promise<number> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  const res = await client.execute({
+    sql: `UPDATE notifications SET read_at = ? WHERE owner = ? AND read_at IS NULL`,
+    args: [now, owner],
+  });
+  const count = (res as unknown as { rowsAffected?: number }).rowsAffected ?? 0;
+  if (count > 0) bumpPoll(owner);
+  return count;
+}
+
+export async function deleteNotification(
+  id: string,
+  owner: string,
+): Promise<boolean> {
+  await ensureTable();
+  const client = getDbExec();
+  const res = await client.execute({
+    sql: `DELETE FROM notifications WHERE id = ? AND owner = ?`,
+    args: [id, owner],
+  });
+  const deleted =
+    (res as unknown as { rowsAffected?: number }).rowsAffected !== 0;
+  if (deleted) bumpPoll(owner);
+  return deleted;
+}

package/src/notifications/types.ts

@@ -0,0 +1,52 @@
+export const NOTIFICATION_SEVERITIES = ["info", "warning", "critical"] as const;
+export type NotificationSeverity = (typeof NOTIFICATION_SEVERITIES)[number];
+
+export interface Notification {
+  id: string;
+  owner: string;
+  severity: NotificationSeverity;
+  title: string;
+  body?: string;
+  /** Arbitrary JSON metadata — URLs, entity ids, the agent turn that produced it. */
+  metadata?: Record<string, unknown>;
+  /** ISO timestamp */
+  createdAt: string;
+  /** ISO timestamp — null while unread */
+  readAt: string | null;
+  /** Channels that delivered (or attempted delivery of) this notification. */
+  deliveredChannels: string[];
+}
+
+export interface NotificationInput {
+  severity: NotificationSeverity;
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Explicit channel allowlist for this emission. When omitted, every
+   * registered channel runs. Use to scope a single `notify()` call to a
+   * subset (e.g. `["inbox"]` to skip webhooks).
+   */
+  channels?: string[];
+}
+
+export interface NotificationMeta {
+  /** Owner email — scopes the notification in the inbox. */
+  owner: string;
+}
+
+export interface NotificationChannel {
+  /** Unique channel name, e.g. `"inbox"`, `"webhook"`, `"slack"`. */
+  name: string;
+  /**
+   * Deliver the notification. Must be best-effort — throwing will be logged
+   * but will not block other channels from running.
+   *
+   * Return `false` to skip (e.g. no URL / no recipients configured) so the
+   * channel is not recorded in `deliveredChannels`.
+   */
+  deliver(
+    input: NotificationInput,
+    meta: NotificationMeta,
+  ): void | boolean | Promise<void | boolean>;
+}

package/src/oauth-tokens/google-refresh.ts

@@ -0,0 +1,175 @@
+/**
+ * Proactive Google OAuth token refresh.
+ *
+ * Templates already refresh tokens reactively in their `getValidAccessToken`
+ * helpers — but that only runs when an action makes an API call. If the user
+ * is idle for an hour, the next call pays the refresh latency, and any error
+ * surfaces as a user-facing failure.
+ *
+ * This module scans the `oauth_tokens` table on a timer and refreshes any
+ * token that's within `expiryBufferMs` of expiring. Templates opt in via a
+ * server plugin (see `templates/mail/server/plugins/oauth-refresh.ts`).
+ */
+
+import { resolveGoogleProviderCredentialCandidates } from "../server/google-oauth-credentials.js";
+import { listOAuthAccounts, saveOAuthTokens } from "./store.js";
+
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+interface GoogleTokens {
+  access_token?: string;
+  refresh_token?: string;
+  expiry_date?: number;
+  token_type?: string;
+  scope?: string;
+}
+
+interface RefreshResponse {
+  access_token: string;
+  expires_in: number;
+  token_type: string;
+  scope?: string;
+}
+
+async function refreshOne(refreshToken: string): Promise<RefreshResponse> {
+  const credentialCandidates = resolveGoogleProviderCredentialCandidates();
+  if (!credentialCandidates.length) {
+    throw new Error("GOOGLE_CLIENT_ID/SECRET not set");
+  }
+
+  let data: Record<string, unknown> | null = null;
+  let lastStatusText = "refresh failed";
+  for (const credentials of credentialCandidates) {
+    const res = await fetch(GOOGLE_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        refresh_token: refreshToken,
+        client_id: credentials.clientId,
+        client_secret: credentials.clientSecret,
+        grant_type: "refresh_token",
+      }),
+    });
+    lastStatusText = res.statusText;
+    data = (await res.json()) as Record<string, unknown>;
+    if (res.ok) return data as unknown as RefreshResponse;
+    if (
+      data.error !== "invalid_grant" &&
+      data.error !== "unauthorized_client" &&
+      data.error !== "invalid_client"
+    ) {
+      break;
+    }
+  }
+
+  if (data) {
+    const err = (data.error_description ||
+      data.error ||
+      lastStatusText) as string;
+    throw new Error(err);
+  }
+  throw new Error(lastStatusText);
+}
+
+/**
+ * Scan all stored Google tokens and refresh any expiring within `bufferMs`.
+ * Errors per-account are logged and swallowed so one bad token doesn't block
+ * the rest.
+ */
+export async function refreshExpiringGoogleTokens(
+  opts: {
+    bufferMs?: number;
+  } = {},
+): Promise<void> {
+  const bufferMs = opts.bufferMs ?? 15 * 60 * 1000;
+  let accounts: Awaited<ReturnType<typeof listOAuthAccounts>>;
+  try {
+    accounts = await listOAuthAccounts("google");
+  } catch (err) {
+    console.error("[google-refresh] failed to list accounts:", err);
+    return;
+  }
+  const now = Date.now();
+  for (const acct of accounts) {
+    const tokens = acct.tokens as GoogleTokens;
+    if (!tokens?.refresh_token) continue;
+    if (tokens.expiry_date && tokens.expiry_date > now + bufferMs) continue;
+    try {
+      const refreshed = await refreshOne(tokens.refresh_token);
+      const merged: GoogleTokens = {
+        ...tokens,
+        access_token: refreshed.access_token,
+        expiry_date: now + refreshed.expires_in * 1000,
+        token_type: refreshed.token_type,
+        scope: refreshed.scope ?? tokens.scope,
+      };
+      await saveOAuthTokens(
+        "google",
+        acct.accountId,
+        merged as unknown as Record<string, unknown>,
+      );
+    } catch (err) {
+      // Common case: invalid_grant when the user revoked access or changed
+      // their Google password. Leave the row in place so the UI shows the
+      // account and the user can re-OAuth — don't auto-delete.
+      console.warn(
+        `[google-refresh] refresh failed for ${acct.accountId}:`,
+        (err as Error).message,
+      );
+    }
+  }
+}
+
+let _started = false;
+let _timer: ReturnType<typeof setInterval> | undefined;
+
+/**
+ * Start the refresh loop. Idempotent — calling more than once is a no-op,
+ * so multiple plugins/templates loading this in the same process are safe.
+ */
+export function startGoogleTokenRefreshLoop(
+  opts: {
+    /** How often to scan. Default: 20 minutes. */
+    intervalMs?: number;
+    /** Refresh tokens expiring within this window. Default: 15 minutes. */
+    bufferMs?: number;
+  } = {},
+): void {
+  if (_started) return;
+  _started = true;
+
+  // In dev mode the local DB is usually the shared prod DB. Proactively
+  // refreshing every user's token with local OAuth credentials always fails
+  // (wrong client_id/secret). Tokens still refresh reactively on-demand.
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  const intervalMs = opts.intervalMs ?? 20 * 60 * 1000;
+  const bufferMs = opts.bufferMs ?? 15 * 60 * 1000;
+
+  // Kick off an initial pass shortly after startup (not immediately — the DB
+  // may still be initializing).
+  const initialTimer = setTimeout(() => {
+    refreshExpiringGoogleTokens({ bufferMs }).catch((err) => {
+      console.error("[google-refresh] initial pass failed:", err);
+    });
+  }, 30_000);
+
+  _timer = setInterval(() => {
+    refreshExpiringGoogleTokens({ bufferMs }).catch((err) => {
+      console.error("[google-refresh] interval pass failed:", err);
+    });
+  }, intervalMs);
+
+  // Don't let either timer keep the process alive on its own.
+  if (
+    typeof initialTimer === "object" &&
+    initialTimer &&
+    "unref" in initialTimer
+  ) {
+    (initialTimer as { unref: () => void }).unref();
+  }
+  if (typeof _timer === "object" && _timer && "unref" in _timer) {
+    (_timer as { unref: () => void }).unref();
+  }
+}

package/src/oauth-tokens/index.ts

@@ -0,0 +1,15 @@
+export {
+  getOAuthTokens,
+  OAuthAccountOwnedByOtherUserError,
+  saveOAuthTokens,
+  deleteOAuthTokens,
+  listOAuthAccounts,
+  listOAuthAccountsByOwner,
+  hasOAuthTokens,
+  setOAuthDisplayName,
+} from "./store.js";
+
+export {
+  refreshExpiringGoogleTokens,
+  startGoogleTokenRefreshLoop,
+} from "./google-refresh.js";