@agent-native/core 0.134.1 → 0.135.1

package/src/jobs/tools.ts

@@ -1,5 +1,6 @@
 import type { ActionEntry } from "../agent/production-agent.js";
 import { getDbExec } from "../db/client.js";
+import { resolveUserSchedulingTimezone } from "../localization/user-timezone.js";
 import {
   resourcePut,
   resourceGetByPath,
@@ -14,7 +15,13 @@ import {
   getRequestOrgId,
   getIntegrationRequestContext,
 } from "../server/request-context.js";
-import { isValidCron, nextOccurrence, describeCron } from "./cron.js";
+import {
+  isValidCron,
+  nextOccurrence,
+  describeCron,
+  effectiveTimezone,
+  isValidTimezone,
+} from "./cron.js";
 import { classifyJobResource } from "./frontmatter.js";
 import {
   parseJobFrontmatter,
@@ -95,6 +102,7 @@ export async function authorizeJobMutation(
 
 async function runCreate(args: Record<string, any>): Promise<string> {
   const { name, schedule, instructions, scope, runAs, model } = args;
+  const requestedTimezone = args.timezone;
 
   if (!name || !schedule || !instructions) {
     return JSON.stringify({
@@ -118,13 +126,24 @@ async function runCreate(args: Record<string, any>): Promise<string> {
   const owner = scope === "personal" ? getOwner() : getSharedOwner();
   const path = `jobs/${name}.md`;
   const now = new Date();
-  const next = nextOccurrence(schedule, now);
+  // A cron time with no zone silently means the host's zone, which is how an
+  // "8am" job ends up firing at 4am for the person who asked for it.
+  if (requestedTimezone && !isValidTimezone(requestedTimezone)) {
+    return JSON.stringify({
+      error: `Unknown timezone: "${requestedTimezone}". Use an IANA zone such as America/New_York.`,
+    });
+  }
+  const timezone =
+    requestedTimezone ||
+    (await resolveUserSchedulingTimezone(getRequestUserEmail()));
+  const next = nextOccurrence(schedule, now, timezone);
   const integration = getIntegrationRequestContext();
   const channelId = integration?.incoming.platformContext.channelId;
   const threadRef = integration?.incoming.threadRef;
 
   const meta: JobFrontmatter = {
     schedule,
+    timezone,
     enabled: true,
     createdBy: getOwner(),
     orgId: getRequestOrgId() || undefined,
@@ -155,7 +174,8 @@ async function runCreate(args: Record<string, any>): Promise<string> {
     name,
     path,
     schedule,
-    scheduleDescription: describeCron(schedule),
+    timezone,
+    scheduleDescription: describeCron(schedule, timezone),
     nextRun: next.toISOString(),
     scope: scope || "shared",
     ...(mcpTools?.length ? { mcpTools } : {}),
@@ -187,7 +207,10 @@ async function runList(args: Record<string, any>): Promise<string> {
         path: r.path,
         scope: r.owner === sharedOwner ? "shared" : "personal",
         schedule: meta.schedule,
-        scheduleDescription: meta.schedule ? describeCron(meta.schedule) : "",
+        timezone: effectiveTimezone(meta.timezone),
+        scheduleDescription: meta.schedule
+          ? describeCron(meta.schedule, effectiveTimezone(meta.timezone))
+          : "",
         enabled: meta.enabled,
         lastRun: meta.lastRun || null,
         lastStatus: meta.lastStatus || null,
@@ -248,7 +271,23 @@ async function runUpdate(args: Record<string, any>): Promise<string> {
       });
     }
     meta.schedule = schedule;
-    meta.nextRun = nextOccurrence(schedule).toISOString();
+  }
+
+  if (args.timezone !== undefined) {
+    if (!isValidTimezone(args.timezone)) {
+      return JSON.stringify({
+        error: `Unknown timezone: "${args.timezone}".`,
+      });
+    }
+    meta.timezone = args.timezone;
+  }
+
+  if (schedule || args.timezone !== undefined) {
+    meta.nextRun = nextOccurrence(
+      meta.schedule,
+      undefined,
+      meta.timezone,
+    ).toISOString();
   }
 
   if (enabled !== undefined) {
@@ -281,7 +320,11 @@ async function runUpdate(args: Record<string, any>): Promise<string> {
     updated: true,
     name,
     schedule: meta.schedule,
-    scheduleDescription: describeCron(meta.schedule),
+    timezone: effectiveTimezone(meta.timezone),
+    scheduleDescription: describeCron(
+      meta.schedule,
+      effectiveTimezone(meta.timezone),
+    ),
     enabled: meta.enabled,
     nextRun: meta.nextRun,
     mcpTools: meta.mcpTools || [],
@@ -347,6 +390,11 @@ For jobs that use a connected MCP, pass the exact tool names in mcpTools. This b
               description:
                 "Job name (hyphen-case, e.g. 'daily-scorecard-check'). Required for create and update.",
             },
+            timezone: {
+              type: "string",
+              description:
+                "IANA timezone the schedule's clock time is read in, e.g. 'America/New_York'. Optional; defaults to the user's saved scheduling timezone, then the caller's browser zone. Always pass this when the user names a time of day, so '8am' means 8am where they are rather than on the server.",
+            },
             schedule: {
               type: "string",
               description:

package/src/localization/actions/get-localization-preference.ts

@@ -5,7 +5,7 @@ import { getUserSetting } from "../../settings/user-settings.js";
 import {
   LOCALIZATION_SETTING_KEY,
   normalizeLocalizationPreference,
-  type LocalizationPreference,
+  type ResolvedLocalizationPreference,
 } from "../shared.js";
 
 export default defineAction({
@@ -13,7 +13,7 @@ export default defineAction({
     "Get the current user's interface language preference. Returns { locale }, where locale is 'system' or a supported BCP-47 locale.",
   schema: z.object({}),
   http: { method: "GET" },
-  run: async (_args, ctx): Promise<LocalizationPreference> => {
+  run: async (_args, ctx): Promise<ResolvedLocalizationPreference> => {
     if (!ctx?.userEmail) throw new Error("Not authenticated.");
     const stored = await getUserSetting(
       ctx.userEmail,

package/src/localization/actions/set-localization-preference.ts

@@ -1,31 +1,69 @@
 import { z } from "zod";
 
 import { defineAction } from "../../action.js";
-import { putUserSetting } from "../../settings/user-settings.js";
+import {
+  getUserSetting,
+  putUserSetting,
+} from "../../settings/user-settings.js";
 import {
   LOCALIZATION_SETTING_KEY,
   SUPPORTED_LOCALES,
   normalizeLocalePreference,
-  type LocalizationPreference,
+  normalizeLocalizationPreference,
+  normalizeTimezonePreference,
+  type ResolvedLocalizationPreference,
 } from "../shared.js";
 
 export default defineAction({
   description:
-    "Set the current user's interface language preference to 'system' or a supported BCP-47 locale.",
+    "Set the current user's interface language and scheduling timezone. Locale is 'system' or a supported BCP-47 locale; timezone is 'system' or an IANA zone such as America/New_York.",
   schema: z.object({
     locale: z
       .string()
-      .describe("Language preference: 'system' or a supported BCP-47 locale."),
+      .describe("Language preference: 'system' or a supported BCP-47 locale.")
+      .optional(),
+    timezone: z
+      .string()
+      .describe("Scheduling timezone: 'system' or an IANA zone name.")
+      .optional(),
   }),
-  run: async (args, ctx): Promise<LocalizationPreference> => {
+  run: async (args, ctx): Promise<ResolvedLocalizationPreference> => {
     if (!ctx?.userEmail) throw new Error("Not authenticated.");
-    const locale = normalizeLocalePreference(args.locale);
-    if (!locale) {
-      throw new Error(
-        `Unsupported locale. Use system, ${SUPPORTED_LOCALES.join(", ")}.`,
-      );
+
+    // Each field is optional, so merge onto what is stored instead of
+    // writing a partial record that silently resets the other one.
+    const current = normalizeLocalizationPreference(
+      await getUserSetting(ctx.userEmail, LOCALIZATION_SETTING_KEY),
+    );
+
+    let locale = current.locale;
+    if (args.locale !== undefined) {
+      const parsed = normalizeLocalePreference(args.locale);
+      if (!parsed) {
+        throw new Error(
+          `Unsupported locale. Use system, ${SUPPORTED_LOCALES.join(", ")}.`,
+        );
+      }
+      locale = parsed;
     }
-    const value: LocalizationPreference & Record<string, unknown> = { locale };
+
+    let timezone = current.timezone;
+    if (args.timezone !== undefined) {
+      const parsed = normalizeTimezonePreference(args.timezone);
+      // Normalizing an unusable zone to "system" would quietly schedule the
+      // user in the host zone, which is the failure this field exists to fix.
+      if (parsed === "system" && args.timezone.trim() !== "system") {
+        throw new Error(
+          `Unknown timezone "${args.timezone}". Use system or an IANA zone such as America/New_York.`,
+        );
+      }
+      timezone = parsed;
+    }
+
+    const value: ResolvedLocalizationPreference & Record<string, unknown> = {
+      locale,
+      timezone,
+    };
     await putUserSetting(ctx.userEmail, LOCALIZATION_SETTING_KEY, value);
     return value;
   },

package/src/localization/default-messages.ts

@@ -57,6 +57,10 @@ const messages = {
     profileSaved: "Profile updated",
     profileSaveError: "Could not update profile",
     profileMenuItem: "Profile",
+    manageAgentMenuItem: "Manage agent",
+    timezoneLabel: "Timezone",
+    timezoneSystem: "Follow this browser ({{zone}})",
+    timezoneHint: "Used for timestamps and scheduled automations.",
   },
   secrets: {
     scopeLabel: "Scope",
@@ -563,6 +567,7 @@ const messages = {
     systemOrdered: "System · ordered, not evictable",
   },
   jobs: {
+    timezone: "Timezone",
     pageTitle: "Automations",
     pageDescription:
       "Manage agent tasks that run on a schedule or in response to events.",
@@ -582,6 +587,28 @@ const messages = {
     paused: "Paused",
     nextRun: "Next run",
     lastRun: "Last run",
+    lastChecked: "Last checked",
+    lastStatus: "Last status",
+    neverRan: "Never",
+    notSet: "—",
+    status: "Status",
+    trigger: "Trigger",
+    scope: "Scope",
+    createdBy: "Created by",
+    model: "Model",
+    blockedTitle: "This automation is not running",
+    pastRuns: "Past runs",
+    runsLoadError: "Could not load run history.",
+    noRuns:
+      "This automation has not executed yet. Only real executions are recorded here.",
+    edit: "Edit",
+    editScheduleTitle: "Edit schedule — {{name}}",
+    editScheduleDescription:
+      "The clock time below is read in the timezone you pick, so 8:00 means 8:00 there.",
+    cronExpression: "Cron expression",
+    cronFormatHint: "minute hour day-of-month month day-of-week",
+    cronFieldCount: "A cron expression needs exactly 5 fields.",
+    saveSchedule: "Save schedule",
     details: "Details",
     pause: "Pause",
     resume: "Resume",

package/src/localization/shared.ts

@@ -24,8 +24,24 @@ export interface LocaleMetadata {
 
 export interface LocalizationPreference {
   locale: LocalePreference;
+  /**
+   * IANA zone used for the user's scheduled work. 'system' defers to the
+   * requesting browser, which is unavailable to headless callers (cron,
+   * chat integrations), so pinning a zone here is what makes a schedule
+   * mean the same thing no matter what created it.
+   *
+   * Optional because a record written before this field existed, or by a
+   * caller that only cares about language, is still a valid preference.
+   * Read it through normalizeLocalizationPreference to get a concrete value.
+   */
+  timezone?: TimezonePreference;
 }
 
+/** A preference that has been through normalization: both fields resolved. */
+export type ResolvedLocalizationPreference = Required<LocalizationPreference>;
+
+export type TimezonePreference = "system" | (string & {});
+
 export const DEFAULT_LOCALE: LocaleCode = "en-US";
 export const LOCALIZATION_SETTING_KEY = "localization";
 export const LOCALE_STORAGE_KEY = "agent-native:locale-preference";
@@ -168,17 +184,34 @@ export function normalizeLocalePreference(
   return normalizeLocaleCode(value);
 }
 
+export function normalizeTimezonePreference(
+  value: unknown,
+): TimezonePreference {
+  if (typeof value !== "string") return "system";
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === "system") return "system";
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: trimmed });
+  } catch {
+    return "system";
+  }
+  return trimmed;
+}
+
 export function normalizeLocalizationPreference(
   value: unknown,
-): LocalizationPreference {
+): ResolvedLocalizationPreference {
   if (value && typeof value === "object" && !Array.isArray(value)) {
-    const locale = normalizeLocalePreference(
-      (value as { locale?: unknown }).locale,
-    );
-    if (locale) return { locale };
+    const record = value as { locale?: unknown; timezone?: unknown };
+    // The two fields are independent: setting a timezone must not require
+    // also picking a language, which is the usual case.
+    return {
+      locale: normalizeLocalePreference(record.locale) ?? "system",
+      timezone: normalizeTimezonePreference(record.timezone),
+    };
   }
   const locale = normalizeLocalePreference(value);
-  return { locale: locale ?? "system" };
+  return { locale: locale ?? "system", timezone: "system" };
 }
 
 export function localeDirection(locale: LocaleCode): "ltr" | "rtl" {

package/src/localization/user-timezone.ts

@@ -0,0 +1,36 @@
+import { isValidTimezone, serverTimezone } from "../jobs/cron.js";
+import { getRequestTimezone } from "../server/request-context.js";
+import { getUserSetting } from "../settings/user-settings.js";
+import {
+  LOCALIZATION_SETTING_KEY,
+  normalizeLocalizationPreference,
+} from "./shared.js";
+
+/**
+ * Resolve the IANA zone a user's scheduled work should be interpreted in.
+ *
+ * Order matters. A zone the user pinned in settings wins over the requesting
+ * browser: someone who set America/New_York expects an 8am job to stay 8am
+ * Eastern while they are travelling. The request header is only a fallback for
+ * users who never pinned one, and it is absent entirely for headless callers
+ * (cron, chat integrations, A2A) — which is why the stored preference exists.
+ */
+export async function resolveUserSchedulingTimezone(
+  userEmail?: string | null,
+): Promise<string> {
+  if (userEmail) {
+    // Deliberately unguarded. The resolved zone is persisted into the
+    // schedule, so swallowing a read failure here would silently pin the job
+    // to the host zone and fire it at the wrong wall-clock time for its whole
+    // life. Failing the write is recoverable; a silently wrong schedule is not.
+    const preference = normalizeLocalizationPreference(
+      await getUserSetting(userEmail, LOCALIZATION_SETTING_KEY),
+    );
+    if (preference.timezone !== "system") return preference.timezone;
+  }
+  // Headers come from the client, so an unusable value must not reach
+  // frontmatter, where cron evaluation would quietly swap in the host zone.
+  const requested = getRequestTimezone();
+  if (requested && isValidTimezone(requested)) return requested;
+  return serverTimezone();
+}

package/src/org/app-roles-handlers.ts

@@ -5,7 +5,6 @@ import {
   type H3Event,
 } from "h3";
 
-import { getDbExec } from "../db/client.js";
 import { readBody } from "../server/h3-helpers.js";
 import {
   getRegisteredAppRoles,
@@ -14,6 +13,7 @@ import {
   type AppRolesDescriptor,
 } from "./app-roles.js";
 import { getOrgContext } from "./context.js";
+import { isOrgMember } from "./membership.js";
 import { canManageOrg } from "./permissions.js";
 
 /**
@@ -46,14 +46,6 @@ function extractMemberEmail(event: H3Event): string | undefined {
   return match?.[1] ? decodeURIComponent(match[1]) : undefined;
 }
 
-async function isOrgMember(orgId: string, email: string): Promise<boolean> {
-  const { rows } = await getDbExec().execute({
-    sql: `SELECT 1 FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
-    args: [orgId, email.trim().toLowerCase()],
-  });
-  return rows.length > 0;
-}
-
 /**
  * GET /_agent-native/org/app-roles?appId=X — the app's vocabulary plus every
  * assignment in the active org, and the caller's own resolved role.

package/src/org/index.ts

@@ -92,3 +92,5 @@ export {
 } from "./app-roles-handlers.js";
 
 export { isFreeEmailProvider } from "./free-email-providers.js";
+
+export { isOrgMember } from "./membership.js";

package/src/org/membership.ts

@@ -0,0 +1,18 @@
+import { getDbExec } from "../db/client.js";
+
+/**
+ * One resolver for "is this email in this org". Two private copies of this
+ * query already existed; a third would be the one that drifts.
+ */
+export async function isOrgMember(
+  orgId: string,
+  email: string,
+): Promise<boolean> {
+  const normalized = email.trim().toLowerCase();
+  if (!orgId || !normalized) return false;
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT 1 FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+    args: [orgId, normalized],
+  });
+  return rows.length > 0;
+}

package/src/review/actions/create-review-comment.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { defineAction } from "../../action.js";
 import { reviewAuthorNameFromContext } from "../identity.js";
 import { extractReviewMentions, normalizeReviewMentions } from "../mentions.js";
+import { notifyReviewComment } from "../notifications.js";
 import {
   assertReviewableResourceAccess,
   normalizeReviewVisibility,
@@ -61,7 +62,7 @@ export default defineAction({
     const resolutionTarget =
       args.resolutionTarget ?? (mentions.length > 0 ? "human" : "agent");
 
-    return insertReviewComment({
+    const comment = await insertReviewComment({
       resourceType: args.resourceType,
       resourceId: args.resourceId,
       targetId: args.targetId ?? null,
@@ -78,6 +79,8 @@ export default defineAction({
       visibility: normalizeReviewVisibility(access.visibility),
       metadata: args.metadata,
     });
+
+    return { ...comment, notified: await notifyReviewComment(comment) };
   },
   audit: {
     target: (args, result) => {

package/src/review/actions/reply-review-comment.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { defineAction } from "../../action.js";
 import { reviewAuthorNameFromContext } from "../identity.js";
 import { extractReviewMentions, normalizeReviewMentions } from "../mentions.js";
+import { notifyReviewComment } from "../notifications.js";
 import {
   assertReviewableResourceAccess,
   normalizeReviewVisibility,
@@ -62,7 +63,7 @@ export default defineAction({
 
     const routeTarget =
       args.resolutionTarget ?? (mentions.length > 0 ? "human" : null);
-    return insertReviewReply(
+    const reply = await insertReviewReply(
       {
         resourceType: args.resourceType,
         resourceId: args.resourceId,
@@ -88,6 +89,8 @@ export default defineAction({
         resourceId: args.resourceId,
       },
     );
+
+    return { ...reply, notified: await notifyReviewComment(reply) };
   },
   audit: {
     target: (args, result) => {

package/src/review/index.ts

@@ -20,6 +20,11 @@ export {
   shouldRedactReviewIdentity,
 } from "./identity.js";
 export { extractReviewMentions, normalizeReviewMentions } from "./mentions.js";
+export {
+  notifyReviewComment,
+  REVIEW_NOTIFICATION_PREFS_KEY,
+  type ReviewNotificationResult,
+} from "./notifications.js";
 export {
   __resetReviewableResourcesForTests,
   assertReviewableResourceAccess,

package/src/review/notifications.ts

@@ -0,0 +1,163 @@
+/**
+ * Email notifications for review threads.
+ *
+ * Implemented here rather than in one app so every surface built on review
+ * comments (Design's review threads today) gets the same behavior. Recipient
+ * resolution, preference filtering, and delivery reporting come from the
+ * shared activity-notification helpers.
+ */
+
+import {
+  notifyActivity,
+  runActivityNotification,
+  type ActivityNotificationResult,
+} from "../server/activity-notifications.js";
+import { getAppProductionUrl } from "../server/app-url.js";
+import { emailStrong, renderEmail } from "../server/email-template.js";
+import { sendEmail } from "../server/email.js";
+import { filterRecipientsByResourceAccess } from "../sharing/recipients.js";
+import {
+  getReviewableResource,
+  resolveReviewableResourceAccess,
+} from "./registry.js";
+import { queryReviewComments } from "./store.js";
+import type { ReviewComment } from "./types.js";
+
+/**
+ * Shared across every review surface. Apps that want a user-facing toggle
+ * write `{ emailNotifications: boolean }` under this key; an absent value
+ * means opted in.
+ */
+export const REVIEW_NOTIFICATION_PREFS_KEY = "activity-notification-prefs";
+
+const LOG_LABEL = "[review] comment notification";
+const EXCERPT_LIMIT = 240;
+
+function excerpt(body: string): string {
+  const collapsed = body.replace(/\s+/g, " ").trim();
+  return collapsed.length > EXCERPT_LIMIT
+    ? `${collapsed.slice(0, EXCERPT_LIMIT - 1)}…`
+    : collapsed;
+}
+
+async function resourceUrl(comment: ReviewComment): Promise<string> {
+  const registration = getReviewableResource(comment.resourceType);
+  const resolved = await registration?.resolveUrl?.(comment.resourceId);
+  return resolved?.trim() || getAppProductionUrl();
+}
+
+function resourceLabel(comment: ReviewComment): string {
+  return (
+    getReviewableResource(comment.resourceType)?.displayName?.trim() ||
+    comment.resourceType
+  );
+}
+
+async function threadParticipants(comment: ReviewComment): Promise<string[]> {
+  // Scope is already established by the action that inserted the comment;
+  // participants are read unscoped so a viewer's narrower scope cannot hide a
+  // person who is genuinely in the thread.
+  const comments = await queryReviewComments({
+    resourceType: comment.resourceType,
+    resourceId: comment.resourceId,
+    scope: { userEmail: null, orgId: null },
+    bypassScope: true,
+    includeResolved: true,
+  });
+  return comments
+    .filter((entry) => entry.threadId === comment.threadId)
+    .map((entry) => entry.authorEmail)
+    .filter((email): email is string => Boolean(email));
+}
+
+export type ReviewNotificationResult = ActivityNotificationResult;
+
+/**
+ * Email the resource owner, mentioned people, and — on a reply — everyone else
+ * already in the thread. Never throws: the comment is already persisted, and a
+ * rejection here would make the client retry and duplicate it.
+ */
+export async function notifyReviewComment(
+  comment: ReviewComment,
+): Promise<ReviewNotificationResult> {
+  return runActivityNotification(LOG_LABEL, () =>
+    deliverReviewCommentEmails(comment),
+  );
+}
+
+async function deliverReviewCommentEmails(
+  comment: ReviewComment,
+): Promise<ActivityNotificationResult> {
+  const mentioned = new Set(
+    comment.mentions
+      .map((mention) => mention.email?.trim().toLowerCase())
+      .filter((email): email is string => Boolean(email)),
+  );
+
+  const candidates = [comment.ownerEmail, ...mentioned];
+  const isReply = Boolean(comment.parentCommentId);
+  if (isReply) {
+    candidates.push(...(await threadParticipants(comment)));
+  }
+
+  // Mentions are caller-supplied and thread rows are historical; neither is an
+  // access grant. Re-check every address against the resource's current ACL
+  // before it can receive the comment body.
+  const allowed = await filterRecipientsByResourceAccess({
+    resourceType: comment.resourceType,
+    resourceId: comment.resourceId,
+    emails: candidates.filter((email): email is string => Boolean(email)),
+    orgId: comment.orgId,
+    // The review registry owns access for its types; unregistered ones resolve
+    // to null there, so nobody is notified rather than everybody.
+    resolveRole: (ctx) =>
+      resolveReviewableResourceAccess(
+        comment.resourceType,
+        comment.resourceId,
+        ctx,
+      ),
+  });
+
+  const actor = comment.authorName?.trim() || comment.authorEmail || "Someone";
+  const label = resourceLabel(comment);
+  const url = await resourceUrl(comment);
+
+  return notifyActivity({
+    candidates: allowed,
+    actorEmail: comment.authorEmail,
+    preferenceKey: REVIEW_NOTIFICATION_PREFS_KEY,
+    logLabel: LOG_LABEL,
+    send: async (to) => {
+      const wasMentioned = mentioned.has(to);
+      const lead = wasMentioned
+        ? `${emailStrong(actor)} mentioned you in a review comment on this ${label}.`
+        : isReply
+          ? `${emailStrong(actor)} replied in a review thread on this ${label}.`
+          : `${emailStrong(actor)} left a review comment on this ${label}.`;
+
+      const { html, text } = renderEmail({
+        preheader: `${actor} commented on this ${label}.`,
+        heading: wasMentioned
+          ? "You were mentioned in a review"
+          : isReply
+            ? "New reply in a review thread"
+            : "New review comment",
+        paragraphs: [lead, `"${excerpt(comment.body)}"`],
+        cta: { label: "Open review", url },
+        footer:
+          "You received this because you own, were mentioned in, or participated in this review thread.",
+      });
+
+      await sendEmail({
+        to,
+        subject: wasMentioned
+          ? `${actor} mentioned you in a review comment`
+          : isReply
+            ? `${actor} replied to a review thread`
+            : `${actor} left a review comment`,
+        html,
+        text,
+      });
+    },
+  });
+}

package/src/review/types.ts

@@ -36,6 +36,13 @@ export interface ReviewResourceContext {
 export interface ReviewableResourceRegistration {
   type: string;
   displayName?: string;
+  /**
+   * Deep link to the resource, used by review notification emails. Without it
+   * an email can only link to the app root.
+   */
+  resolveUrl?: (
+    resourceId: string,
+  ) => Promise<string | null | undefined> | string | null | undefined;
   resolveAccess?: (
     resourceId: string,
     ctx?: ReviewResourceContext,