@agent-native/core 0.134.0 → 0.135.0

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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,

package/corpus/core/src/server/action-discovery.ts

@@ -625,6 +625,10 @@ export async function mergeCoreSharingActions(
       "manage-recurring-job",
       () => import("../jobs/actions/manage-recurring-job.js"),
     ],
+    [
+      "list-automation-runs",
+      () => import("../jobs/actions/list-automation-runs.js"),
+    ],
     [
       "list-automations",
       () => import("../triggers/actions/list-automations.js"),

package/corpus/core/src/server/activity-notifications.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared plumbing for collaboration emails (comments, replies, reactions,
+ * mentions).
+ *
+ * Two things every app was about to reimplement live here: resolving who
+ * should receive an activity email, and reporting delivery honestly. A
+ * workspace with no email provider is a *different* outcome from "nobody
+ * wanted this email" — collapsing both into an empty success is what let a
+ * dead notification toggle ship unnoticed.
+ */
+
+import { getUserSetting } from "../settings/user-settings.js";
+import { isEmailConfigured } from "./email.js";
+
+export type ActivityDeliveryFailure = { email: string; error: string };
+
+export type ActivityNotificationStatus =
+  | "delivered"
+  | "delivery-failed"
+  | "email-not-configured"
+  | "no-recipients"
+  | "notification-error";
+
+export type ActivityNotificationResult = {
+  status: ActivityNotificationStatus;
+  sent: string[];
+  failed: ActivityDeliveryFailure[];
+  /** Set only on `notification-error`: why recipients could not be resolved. */
+  error?: string;
+};
+
+/** Default field read from an app's per-user preference blob. */
+const DEFAULT_PREFERENCE_FIELD = "emailNotifications";
+
+export interface ResolveActivityRecipientsInput {
+  /** Owner, thread participants, mentions — duplicates and blanks are fine. */
+  candidates: (string | null | undefined)[];
+  /** The person who caused the activity. Never emailed about their own action. */
+  actorEmail?: string | null;
+  /** App-owned user settings key, e.g. `clips-user-prefs`. */
+  preferenceKey: string;
+  /** Field inside that blob. Absent or non-`false` means opted in. */
+  preferenceField?: string;
+}
+
+function normalizeEmail(value: string | null | undefined): string {
+  return (value ?? "").trim().toLowerCase();
+}
+
+async function wantsActivityEmail(
+  email: string,
+  preferenceKey: string,
+  preferenceField: string,
+): Promise<boolean> {
+  const prefs = await getUserSetting(email, preferenceKey);
+  // A user who never opened settings has no stored blob; treat that as opted
+  // in rather than silently dropping their notifications.
+  return prefs?.[preferenceField] !== false;
+}
+
+/**
+ * Normalize, dedupe, drop the actor, and filter by each recipient's stored
+ * preference. Order follows first appearance in `candidates`.
+ */
+export async function resolveActivityRecipients({
+  candidates,
+  actorEmail,
+  preferenceKey,
+  preferenceField = DEFAULT_PREFERENCE_FIELD,
+}: ResolveActivityRecipientsInput): Promise<string[]> {
+  const actor = normalizeEmail(actorEmail);
+  const unique = new Set<string>();
+  for (const candidate of candidates) {
+    const email = normalizeEmail(candidate);
+    if (!email || email === actor || !email.includes("@")) continue;
+    unique.add(email);
+  }
+
+  const decisions = await Promise.all(
+    [...unique].map(async (email) =>
+      (await wantsActivityEmail(email, preferenceKey, preferenceField))
+        ? email
+        : null,
+    ),
+  );
+  return decisions.filter((email): email is string => email !== null);
+}
+
+export interface NotifyActivityInput extends ResolveActivityRecipientsInput {
+  /** Sends one email. Throwing marks that recipient failed, not the batch. */
+  send: (to: string) => Promise<unknown>;
+  /** Prefix for the delivery-failure log line, e.g. `[slides]`. */
+  logLabel?: string;
+}
+
+/**
+ * Resolve recipients and deliver one email each. Returns a status that
+ * distinguishes "no email provider" from "nobody to email" from a real send.
+ */
+export async function notifyActivity({
+  send,
+  logLabel,
+  ...resolve
+}: NotifyActivityInput): Promise<ActivityNotificationResult> {
+  if (!(await isEmailConfigured())) {
+    return { status: "email-not-configured", sent: [], failed: [] };
+  }
+
+  const recipients = await resolveActivityRecipients(resolve);
+  if (recipients.length === 0) {
+    return { status: "no-recipients", sent: [], failed: [] };
+  }
+
+  const sent: string[] = [];
+  const failed: ActivityDeliveryFailure[] = [];
+  for (const to of recipients) {
+    try {
+      await send(to);
+      sent.push(to);
+    } catch (error) {
+      failed.push({
+        email: to,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  if (failed.length > 0) {
+    console.error(
+      `${logLabel ?? "[activity-notifications]"} delivery failed for ${failed
+        .map((failure) => `${failure.email} (${failure.error})`)
+        .join(", ")}`,
+    );
+  }
+
+  // Every recipient failing is an outage, not a delivery. Callers that log or
+  // surface this must not see it as the same outcome as a successful send.
+  return {
+    status: sent.length === 0 ? "delivery-failed" : "delivered",
+    sent,
+    failed,
+  };
+}
+
+/**
+ * Run an activity notification without letting it fail the write that caused
+ * it. The comment/reaction is already persisted by the time notification runs;
+ * rejecting here makes the client roll back and retry, which duplicates the
+ * row. The error still surfaces — as a distinct `notification-error` status,
+ * never as a silent success.
+ */
+export async function runActivityNotification<
+  T extends {
+    status: string;
+    sent: string[];
+    failed: ActivityDeliveryFailure[];
+  },
+>(
+  logLabel: string,
+  resolve: () => Promise<T>,
+): Promise<T | ActivityNotificationResult> {
+  try {
+    return await resolve();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${logLabel} could not be resolved: ${message}`);
+    return {
+      status: "notification-error",
+      error: message,
+      sent: [],
+      failed: [],
+    };
+  }
+}

package/corpus/core/src/server/app-name.ts

@@ -51,3 +51,34 @@ export function getAppName(): string | undefined {
   cachedFromPkg = name ?? undefined;
   return name;
 }
+
+/**
+ * Resolve the app's slug — the machine-readable identifier used for the
+ * per-app transactional email sender (e.g. `clips@agent-native.com`).
+ *
+ * Only a first-party template name matched by package.json qualifies. A slug
+ * derived from an arbitrary `APP_NAME` must not mint a mailbox on the
+ * agent-native.com domain: a custom app would then send as
+ * `<its-name>@agent-native.com` and route replies to the Builder mailbox.
+ * Returns `undefined` for anything unrecognized, which leaves the deployment's
+ * configured sender in place.
+ */
+export function getAppSlug(): string | undefined {
+  const pkg = readPkg();
+  if (!pkg?.name) return undefined;
+  return TEMPLATES.find((t) => t.name === pkg.name)?.name;
+}
+
+/**
+ * One-line description of the app, used to tailor transactional email bodies
+ * so recipients recognize which app they signed up for. Sourced from the
+ * first-party template metadata; `undefined` for unknown apps.
+ */
+export function getAppDescription(): string | undefined {
+  const pkg = readPkg();
+  if (pkg?.name) {
+    const tmpl = TEMPLATES.find((t) => t.name === pkg.name);
+    if (tmpl) return tmpl.hint;
+  }
+  return undefined;
+}

package/corpus/core/src/server/better-auth-instance.ts

@@ -933,11 +933,11 @@ async function createBetterAuthInstance(
           ""
         ).replace(/\/$/, "");
         const resetUrl = `${appUrl}${appBasePath}/_agent-native/auth/reset?token=${encodeURIComponent(token)}`;
-        const { subject, html, text } = renderResetPasswordEmail({
+        const { subject, html, text, appSender } = renderResetPasswordEmail({
           email: user.email,
           resetUrl,
         });
-        await sendEmail({ to: user.email, subject, html, text });
+        await sendEmail({ to: user.email, subject, html, text, appSender });
       },
     },
     emailVerification: {
@@ -960,11 +960,11 @@ async function createBetterAuthInstance(
         const verifyUrl = verifyBasePath
           ? url.replace(/(\/\/[^/]+)(\/)/, `$1${verifyBasePath}$2`)
           : url;
-        const { subject, html, text } = renderVerifySignupEmail({
+        const { subject, html, text, appSender } = renderVerifySignupEmail({
           email: user.email,
           verifyUrl,
         });
-        await sendEmail({ to: user.email, subject, html, text });
+        await sendEmail({ to: user.email, subject, html, text, appSender });
       },
     },
     socialProviders,