@dbx-tools/email 0.3.29 → 0.3.30

package/src/defaults.ts

@@ -0,0 +1,95 @@
+/**
+ * Interceptor defaults and hard payload caps for the email plugin.
+ *
+ * The execution settings are what the runtime's executor hands
+ * `Plugin.execute()`, kept here rather than at the call sites so the
+ * caching / retry / timeout posture of every outbound operation is
+ * reviewable in one place. The caps bound the one unbounded input the
+ * plugin accepts: a model-drafted message with attachments.
+ *
+ * @module
+ */
+
+/**
+ * The `PluginExecuteConfig` slice this package sets. Mirrored structurally
+ * because AppKit's `PluginExecuteConfig` lives behind a subpath its `exports`
+ * map does not publish, so the nominal type cannot be imported. Written as a
+ * type alias rather than an interface so it stays assignable to the nominal
+ * type's index signature.
+ */
+export type EmailExecuteConfig = {
+  cache?: { enabled?: boolean; ttl?: number; cacheKey?: (string | number | object)[] };
+  retry?: { enabled?: boolean; attempts?: number; initialDelay?: number; maxDelay?: number };
+  timeout?: number;
+};
+
+/**
+ * The `PluginExecutionSettings` shape accepted by AppKit's `Plugin.execute()`.
+ * Mirrored structurally for the same reason as {@link EmailExecuteConfig}.
+ */
+export type EmailExecutionSettings = {
+  default: EmailExecuteConfig;
+  user?: EmailExecuteConfig;
+};
+
+/** Ceiling on how long a single SMTP conversation may take. */
+export const SEND_TIMEOUT_MS = 30_000;
+
+/** Ceiling on the SMTP handshake performed at plugin setup. */
+export const VERIFY_TIMEOUT_MS = 15_000;
+
+/** Attempts allowed for the setup-time SMTP handshake, including the first. */
+export const VERIFY_ATTEMPTS = 3;
+
+/** Largest single attachment accepted, in decoded bytes (10 MiB). */
+export const MAX_ATTACHMENT_BYTES = 10_485_760;
+
+/** Largest combined attachment payload accepted, in decoded bytes (20 MiB). */
+export const MAX_ATTACHMENTS_TOTAL_BYTES = 20_971_520;
+
+/** Largest number of attachments accepted on one message. */
+export const MAX_ATTACHMENT_COUNT = 20;
+
+/** Largest markdown body accepted, in characters. */
+export const MAX_BODY_CHARS = 200_000;
+
+/** Execution settings for a send (SMTP dispatch or an outbox write). */
+export const EMAIL_SEND_SETTINGS: EmailExecutionSettings = {
+  default: {
+    // Cache disabled: a send is a side effect, not a value. Replaying a
+    // cached result would report success for a message never handed to SMTP.
+    cache: { enabled: false },
+    // Retry disabled: SMTP delivery is not idempotent. A `sendMail` that
+    // times out may already have queued the message, so a second attempt
+    // risks delivering the mail twice.
+    retry: { enabled: false },
+    timeout: SEND_TIMEOUT_MS,
+  },
+};
+
+/** Execution settings for the setup-time SMTP connectivity check. */
+export const EMAIL_VERIFY_SETTINGS: EmailExecutionSettings = {
+  default: {
+    // Cache disabled: connectivity is a point-in-time fact about the server,
+    // and this runs once per boot, so there is nothing to reuse.
+    cache: { enabled: false },
+    // Retry enabled: the handshake has no side effect, and a cold SMTP relay
+    // or a slow DNS answer at boot is exactly the transient failure that
+    // should not take the app down.
+    retry: { enabled: true, attempts: VERIFY_ATTEMPTS },
+    timeout: VERIFY_TIMEOUT_MS,
+  },
+};
+
+/** Execution settings for the sender-options lookup. */
+export const EMAIL_SENDERS_SETTINGS: EmailExecutionSettings = {
+  default: {
+    // Cache disabled: the options are computed from already-resolved config
+    // and the caller's own address, so a cache would add a cross-identity
+    // leak risk for no measurable saving.
+    cache: { enabled: false },
+    // Retry disabled: the lookup performs no I/O, so a failure is
+    // deterministic and a second attempt would fail identically.
+    retry: { enabled: false },
+  },
+};

package/src/email-html.ts

@@ -25,6 +25,12 @@ import juice from "juice";
 import type { EmailBrand } from "./brand";
 import { markdownToHtml } from "./markdown";
 
+/**
+ * Rendered height of the header logo. Fixed rather than intrinsic because
+ * mail clients ignore CSS sizing on an image without an `height` attribute.
+ */
+const LOGO_HEIGHT_PX = 28;
+
 /** Neutral fallback styling when no brand is supplied. */
 const DEFAULT_BRAND: Required<Pick<EmailBrand, "accent" | "onAccent" | "fontFamily">> = {
   accent: "#0b6bcb",
@@ -32,7 +38,7 @@ const DEFAULT_BRAND: Required<Pick<EmailBrand, "accent" | "onAccent" | "fontFami
   fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
 };
 
-/** Escape HTML-significant characters (re-exported from `@dbx-tools/shared`). */
+/** Escape HTML-significant characters (re-exported from `@dbx-tools/shared-core`). */
 export const escapeHtml = string.escapeHtml;
 
 /**
@@ -110,12 +116,12 @@ function footerRow(footer: string | undefined): string {
 /**
  * Render the header-band content: the brand logo (when the brand supplies a
  * renderable image) above the title, or just the title. The logo is capped
- * at 28px tall and tinted implicitly by its own artwork; the title always
- * shows so the band is never empty.
+ * at {@link LOGO_HEIGHT_PX} and tinted implicitly by its own artwork; the
+ * title always shows so the band is never empty.
  */
 function headerBand(title: string, brand: EmailBrand, onAccent: string): string {
   const logo = brand.logoUrl
-    ? `<img src="${escapeHtml(brand.logoUrl)}" alt="${escapeHtml(brand.name ?? title)}" height="28" style="height: 28px; width: auto; display: block; margin-bottom: 8px;" />`
+    ? `<img src="${escapeHtml(brand.logoUrl)}" alt="${escapeHtml(brand.name ?? title)}" height="${LOGO_HEIGHT_PX}" style="height: ${LOGO_HEIGHT_PX}px; width: auto; display: block; margin-bottom: 8px;" />`
     : "";
   return `${logo}<span style="color: ${onAccent}; font-size: 18px; font-weight: 700; line-height: 1.3;">${escapeHtml(title)}</span>`;
 }

package/src/outbox.ts

@@ -20,9 +20,15 @@ import type { EmailMessage } from "@dbx-tools/shared-email";
 import type { EmailBrand } from "./brand";
 import { renderEmailHtml } from "./email-html";
 
+/**
+ * Longest subject slug kept in an outbox file name, leaving room for the
+ * timestamp prefix and extension inside common filesystem name limits.
+ */
+const SUBJECT_SLUG_MAX_LENGTH = 48;
+
 /** Filesystem-safe slug of the subject for the file name. */
 function subjectSlug(subject: string): string {
-  return string.toSlugWithOptions({ maxLength: 48 }, subject) || "email";
+  return string.toSlugWithOptions({ maxLength: SUBJECT_SLUG_MAX_LENGTH }, subject) || "email";
 }
 
 /** The envelope rows shown above the body in the preview file. */

package/src/plugin.ts

@@ -2,16 +2,19 @@
  * AppKit plugin (registered name: `email`) that owns the SMTP runtime
  * for outbound mail. Registering it validates the SMTP configuration
  * and verifies connectivity at startup, so a bad host / credential
- * surfaces in the boot logs instead of on the first approved send. The
- * actual send happens through the approval-gated {@link emailTool}
- * spread into an agent; this plugin primes the shared transport the
- * tool reuses and exposes a direct {@link sendEmail} for non-agent
- * callers.
+ * surfaces in the boot logs instead of on the first approved send, and
+ * installs this plugin's `execute()` as the runtime's executor so every
+ * send picks up AppKit's retry / timeout / telemetry chain.
+ *
+ * The plugin is also a `ToolProvider`, so an AppKit agent can reach an
+ * `email.send` tool directly; the {@link emailTool} export is the same
+ * capability for a Mastra agent. Both share the transport primed here,
+ * and {@link sendEmail} is available to non-agent callers.
  *
  * Configuration is the manifest-published {@link EmailPluginConfig}
- * (SMTP host/port/credentials, sender domain or explicit `from`, and an
- * optional `allowedSenders` restriction), with unprefixed `SMTP_*` /
- * `EMAIL_*` environment fallbacks.
+ * (SMTP host/port/credentials, sender domain or explicit `from`, the
+ * sender policy, and an optional `allowedSenders` restriction), with
+ * unprefixed `SMTP_*` / `EMAIL_*` environment fallbacks.
  *
  * The plugin mounts one route under its base path (`/api/email`):
  * `GET /senders` returns the permitted `From` options for the calling
@@ -21,27 +24,75 @@
  */
 
 import {
+  AuthenticationError,
+  ConfigurationError,
+  ConnectionError,
+  ExecutionError,
   getExecutionContext,
   Plugin,
   toPlugin,
+  ValidationError,
+  type AppKitError,
+  type ExecutionResult,
   type IAppRouter,
   type PluginManifest,
 } from "@databricks/appkit";
-import { error, log } from "@dbx-tools/shared-core";
-import type { EmailMessage, EmailResult, EmailSenders } from "@dbx-tools/shared-email";
-import type express from "express";
+import {
+  defineTool,
+  executeFromRegistry,
+  toolsFromRegistry,
+  type AgentToolDefinition,
+  type ToolProvider,
+  type ToolRegistry,
+} from "@databricks/appkit/beta";
+import { log } from "@dbx-tools/shared-core";
+import {
+  email as emailWire,
+  type EmailMessage,
+  type EmailResult,
+  type EmailSenders,
+} from "@dbx-tools/shared-email";
 import { EMAIL_CONFIG_SCHEMA, type EmailPluginConfig } from "./config";
+import { EMAIL_SENDERS_SETTINGS, EMAIL_VERIFY_SETTINGS } from "./defaults";
 import { isSenderAllowed, listSenderOptions, resolveSenderAddress } from "./sender";
-import { getEmailRuntime, sendEmail } from "./transport";
+import { SEND_EMAIL_DESCRIPTION } from "./tool";
+import {
+  getEmailRuntime,
+  resetEmailRuntime,
+  sendEmail,
+  setEmailExecutor,
+  verifyEmailTransport,
+} from "./transport";
 
 /** Mount-relative route (under `/api/email`) for the sender-options lookup. */
 const SENDERS_ROUTE = "/senders";
 
+/** Registry key of the agent tool, which agents address as `email.send`. */
+const SEND_TOOL = "send";
+
+const logger = log.logger("email");
+
 /**
  * AppKit plugin that configures and verifies the SMTP transport used by
- * the `send_email` tool.
+ * the `send_email` tool, and exposes sending as an AppKit agent tool.
+ *
+ * @example
+ * ```ts
+ * import { createApp, server } from "@databricks/appkit";
+ * import { plugin as emailPlugin } from "@dbx-tools/email";
+ *
+ * await createApp({
+ *   plugins: [
+ *     server(),
+ *     emailPlugin.email({
+ *       smtp: { host: "smtp.example.com", user: "apikey", password: process.env.SMTP_KEY },
+ *       domain: "mail.example.com",
+ *     }),
+ *   ],
+ * });
+ * ```
  */
-export class EmailPlugin extends Plugin<EmailPluginConfig> {
+export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvider {
   static manifest = {
     name: "email",
     displayName: "Email",
@@ -56,36 +107,94 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> {
     config: { schema: EMAIL_CONFIG_SCHEMA },
   } satisfies PluginManifest<"email">;
 
-  private logger = log.logger(this);
+  /**
+   * The tool this plugin offers to an AppKit agent.
+   *
+   * Not `autoInheritable`: a send is irreversible and leaves the workspace,
+   * so it must only appear in an agent that asked for it and accepted the
+   * sender policy that comes with it.
+   *
+   * `execute` re-parses its arguments with the local schema: AppKit validates
+   * against the same schema first, but re-parsing is what gives the body typed
+   * arguments instead of `unknown`.
+   */
+  private readonly tools: ToolRegistry = {
+    [SEND_TOOL]: defineTool({
+      description: SEND_EMAIL_DESCRIPTION,
+      schema: emailWire.emailMessageSchema,
+      annotations: { effect: "write", requiresUserContext: true },
+      autoInheritable: false,
+      execute: async (args, signal) =>
+        this.send(emailWire.emailMessageSchema.parse(args), undefined, signal),
+    }),
+  };
 
   /**
-   * Prime the shared runtime from this plugin's config (over env). In
-   * SMTP mode, verify connectivity - a failed verify is logged as a
-   * warning rather than thrown, so the app still boots and the first
-   * send surfaces the real error via the approval flow. With no SMTP
+   * Prime the shared runtime from this plugin's config (over env), route the
+   * tools' sends through this plugin's interceptor chain, and log the
+   * effective sender policy so an active restriction is obvious at boot. In
+   * SMTP mode, fail setup when the transport cannot be verified: a bad host
+   * or credential is a deploy-time mistake and should stop the app rather
+   * than wait for a user to approve a send that cannot work. With no SMTP
    * credentials the runtime is in file/outbox mode (only when
-   * `EMAIL_OUTBOX_MODE` is set), logged here so it's obvious mail is
-   * being written to disk rather than sent.
+   * `EMAIL_OUTBOX_MODE` is set), logged loudly here so it is obvious mail
+   * is being written to disk rather than sent.
    */
   override async setup(): Promise<void> {
     const { transporter, config } = getEmailRuntime(this.config);
+    setEmailExecutor((fn, settings) => this.execute(fn, settings));
+    const policy = {
+      mode: config.mode,
+      senderPolicy: config.senderPolicy,
+      restricted: config.allowedSenders.length > 0,
+      ...(config.allowedSenders.length > 0 ? { allowedSenders: config.allowedSenders } : {}),
+    };
     if (config.mode === "file") {
-      this.logger.warn("outbox:enabled", {
+      logger.warn("outbox:enabled", {
         dir: config.outDir,
         reason: "no SMTP credentials configured; emails are written to disk instead of sent",
       });
+      logger.info("ready", policy);
       return;
     }
-    try {
-      await transporter?.verify();
-      this.logger.info("smtp:ready", {
+    const verified = await this.execute(
+      async (signal) => verifyEmailTransport(transporter, signal),
+      EMAIL_VERIFY_SETTINGS,
+    );
+    if (!verified.ok) {
+      logger.error("smtp:unverified", {
         host: config.host,
         port: config.port,
-        secure: config.secure,
+        status: verified.status,
+        error: verified.message,
       });
-    } catch (err) {
-      this.logger.warn("smtp:unverified", { error: error.errorMessage(err) });
+      throw ConfigurationError.invalidConnection(
+        "SMTP",
+        `Could not verify ${config.host}:${config.port}. Check SMTP_HOST, SMTP_PORT, SMTP_SECURE, and the credentials, or set EMAIL_OUTBOX_MODE=1 for local outbox testing.`,
+      );
     }
+    logger.info("ready", {
+      ...policy,
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+    });
+  }
+
+  /** Close the SMTP connection pool. Idempotent. */
+  async shutdown(): Promise<void> {
+    resetEmailRuntime();
+  }
+
+  /**
+   * Abort in-flight work. AppKit's graceful shutdown only invokes this hook -
+   * it never calls {@link shutdown} - so the SMTP pool is closed from here or
+   * it leaks at SIGTERM. The teardown is synchronous and idempotent, so the
+   * un-awaited call costs nothing.
+   */
+  override abortActiveOperations(): void {
+    super.abortActiveOperations();
+    void this.shutdown();
   }
 
   /**
@@ -96,11 +205,18 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> {
    * local part.
    */
   override injectRoutes(router: IAppRouter): void {
-    router.get(SENDERS_ROUTE, (req, res, next) => {
-      this.userScopedSelf(req)
-        .listSenders()
-        .then((senders) => res.json(senders))
-        .catch(next);
+    this.route(router, {
+      name: "listSenders",
+      method: "get",
+      path: SENDERS_ROUTE,
+      handler: async (req, res) => {
+        const result = await this.asUser(req).executeListSenders();
+        if (!result.ok) {
+          res.status(result.status).json({ error: result.message });
+          return;
+        }
+        res.json(result.data);
+      },
     });
   }
 
@@ -111,33 +227,67 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> {
        * transport, bypassing the approval flow. For agent-driven sends
        * use {@link emailTool} instead.
        */
-      sendEmail: (message: EmailMessage, from: string): Promise<EmailResult> =>
-        sendEmail(message, from),
+      sendEmail: (
+        message: EmailMessage,
+        from: string,
+        signal?: AbortSignal,
+      ): Promise<EmailResult> => this.send(message, from, signal),
       /**
        * Sender options for the current user (the `GET /senders` payload).
        * AppKit wraps this with `asUser(req)` for OBO scoping.
        */
-      listSenders: (): Promise<EmailSenders> => this.listSenders(),
+      listSenders: async (): Promise<EmailSenders> => unwrap(await this.executeListSenders()),
     };
   }
 
+  /** AppKit `ToolProvider`: the tool definitions offered to an agent. */
+  getAgentTools(): AgentToolDefinition[] {
+    return toolsFromRegistry(this.tools);
+  }
+
+  /**
+   * AppKit `ToolProvider`: run one tool call. Arguments are validated against
+   * the tool's schema first, and a validation failure comes back as an
+   * LLM-friendly string so the model can correct itself on the next turn.
+   */
+  async executeAgentTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown> {
+    return executeFromRegistry(this.tools, name, args, signal);
+  }
+
+  /**
+   * Send one message, resolving the sender for the caller in scope when
+   * `from` is not pinned. The interceptor chain is applied inside
+   * {@link sendEmail} through the executor installed at setup, so this must
+   * not wrap it again.
+   */
+  private async send(
+    message: EmailMessage,
+    from: string | undefined,
+    signal?: AbortSignal,
+  ): Promise<EmailResult> {
+    return sendEmail(message, from ?? this.resolveSender(), signal);
+  }
+
+  /** Run the sender-options lookup through the plugin's interceptor chain. */
+  private async executeListSenders(): Promise<ExecutionResult<EmailSenders>> {
+    return this.execute(async () => this.listSenders(), EMAIL_SENDERS_SETTINGS);
+  }
+
   /**
    * Compute the `From` options offered to the current user: the concrete
-   * addresses the configured allow-list permits (domain wildcards
-   * expanded against the OBO user's local part), the default among them,
-   * and whether the list is an enforced restriction. See
+   * addresses the effective allow-list permits (domain wildcards expanded
+   * against the OBO user's local part), the default among them, and
+   * whether the list is an enforced restriction. See
    * {@link listSenderOptions}.
    */
   private async listSenders(): Promise<EmailSenders> {
     const { config } = getEmailRuntime();
-    const ctx = getExecutionContext();
-    const userEmail = "isUserContext" in ctx ? ctx.userEmail : undefined;
-    const senders = listSenderOptions(config, userEmail);
+    const senders = listSenderOptions(config, currentUserEmail());
     // Prefer the address a send would actually default to; fall back to
     // the first offered option when that can't be resolved / permitted.
     let defaultSender = senders[0];
     try {
-      const resolved = resolveSenderAddress(config, userEmail).toLowerCase();
+      const resolved = this.resolveSender().toLowerCase();
       if (isSenderAllowed(resolved, config.allowedSenders)) defaultSender = resolved;
     } catch {
       // Keep the first offered option (or none) as the default.
@@ -149,15 +299,57 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> {
     };
   }
 
-  /**
-   * Return `this.asUser(req)` when the request carries an OBO token,
-   * otherwise `this`. Avoids the noisy AppKit "asUser without token"
-   * warning on every request in local dev; behavior is unchanged in
-   * production where a missing token means a real OBO call.
-   */
-  private userScopedSelf(req: express.Request): this {
-    return req.header("x-forwarded-access-token") ? (this.asUser(req) as this) : this;
+  /** The `From` a send defaults to for the caller in scope. */
+  private resolveSender(): string {
+    return resolveSenderAddress(getEmailRuntime().config, currentUserEmail());
   }
 }
 
+/** The OBO user's address, or undefined outside a user context. */
+function currentUserEmail(): string | undefined {
+  const ctx = getExecutionContext();
+  return "isUserContext" in ctx ? ctx.userEmail : undefined;
+}
+
+/**
+ * Re-raise a failed execution as the AppKit error class that already carries
+ * the status AppKit resolved, so a programmatic caller sees the same 400 /
+ * 401 / 503 an HTTP caller would.
+ */
+function toAppKitError(status: number, message: string): AppKitError {
+  if (status === 400) return new ValidationError(message);
+  if (status === 401) return new AuthenticationError(message);
+  if (status === 503) return new ConnectionError(message);
+  return new ExecutionError(message);
+}
+
+/**
+ * Surface a failed {@link ExecutionResult} to a programmatic caller as a
+ * throw. HTTP handlers map `status` onto the response instead.
+ */
+function unwrap<T>(result: ExecutionResult<T>): T {
+  if (result.ok) return result.data;
+  throw toAppKitError(result.status, result.message);
+}
+
+/**
+ * Register the email plugin.
+ *
+ * @example
+ * ```ts
+ * import { createApp, server } from "@databricks/appkit";
+ * import { brand, plugin as emailPlugin } from "@dbx-tools/email";
+ *
+ * await createApp({
+ *   plugins: [
+ *     server(),
+ *     emailPlugin.email({
+ *       domain: "mail.example.com",
+ *       allowedSenders: ["*@mail.example.com"],
+ *       brand: brand.defaultEmailBrand,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 export const email = toPlugin(EmailPlugin);

package/src/sender.ts

@@ -9,20 +9,25 @@
  * file/outbox fallback (no domain) keeps the user's address verbatim so
  * test artifacts land under a recognizable folder.
  *
- * When an allow-list is configured (see {@link parseAllowedSenders}) the
- * resolved `From` is constrained to it: a pattern is either an exact
- * address (`user@domain.com`), a domain wildcard (`*@domain.com` or the
- * bare `domain.com`, matching any local part on that domain), or `*`
- * (any). {@link listSenderOptions} expands the allow-list into the
- * concrete addresses a UI dropdown can offer for the current user.
+ * The resolved `From` is then constrained to the effective allow-list: a
+ * pattern is either an exact address (`user@domain.com`), a domain wildcard
+ * (`*@domain.com` or the bare `domain.com`, matching any local part on that
+ * domain), or `*` (any). This module only matches patterns; which patterns
+ * apply is decided by the configured sender policy in `./config`, which
+ * under the default `"allowlist"` mode fills an empty list in from the
+ * sender source. {@link listSenderOptions} expands the effective list into
+ * the concrete addresses a UI dropdown can offer for the current user.
  *
  * @module
  */
 
-import { net } from "@dbx-tools/shared-core";
+import { ConfigurationError, ValidationError } from "@databricks/appkit";
+import { log, net } from "@dbx-tools/shared-core";
 
 import type { ResolvedEmailConfig } from "./config";
 
+const logger = log.logger("email/sender");
+
 /**
  * Re-home the OBO user's local part on `domain`. Throws when no usable
  * local part is available (e.g. a service-context call with no user).
@@ -30,8 +35,9 @@ import type { ResolvedEmailConfig } from "./config";
 export function deriveSenderAddress(userEmail: string | undefined, domain: string): string {
   const local = userEmail?.split("@")[0]?.trim();
   if (!local) {
-    throw new Error(
-      "email: cannot derive sender address - no on-behalf-of user email is available; set `from` / EMAIL_FROM to send from a fixed address",
+    throw ConfigurationError.resourceNotFound(
+      "On-behalf-of user email",
+      "Set `from` / EMAIL_FROM to send from a fixed address instead of deriving one.",
     );
   }
   return `${local}@${domain}`;
@@ -67,7 +73,9 @@ function matchesPattern(address: string, pattern: string): boolean {
 
 /**
  * Whether `from` is permitted by the allow-list. An empty (or absent)
- * allow-list permits everything.
+ * allow-list permits everything: {@link resolveEmailConfig} is what turns
+ * the configured {@link SenderPolicy} into concrete patterns, so an empty
+ * list here means the policy had nothing to narrow to.
  */
 export function isSenderAllowed(from: string, patterns: string[]): boolean {
   if (patterns.length === 0) return true;
@@ -82,11 +90,15 @@ export function isSenderAllowed(from: string, patterns: string[]): boolean {
  * the address was derived server-side or chosen in a UI.
  */
 export function assertSenderAllowed(from: string, patterns: string[]): void {
-  if (!isSenderAllowed(from, patterns)) {
-    throw new Error(
-      `email: sender "${from}" is not permitted by the configured allow-list (${patterns.join(", ")})`,
-    );
-  }
+  if (isSenderAllowed(from, patterns)) return;
+  // The thrown message names the field only; the patterns are policy detail
+  // that belongs in the operator's logs, not in a client or model response.
+  logger.warn("sender:denied", { from, allowedSenders: patterns });
+  throw ValidationError.invalidValue(
+    "from",
+    from,
+    "an address permitted by the configured sender allow-list",
+  );
 }
 
 /**
@@ -103,8 +115,9 @@ export function resolveSenderAddress(
   if (config.domain) return deriveSenderAddress(userEmail, config.domain);
   const email = userEmail?.trim();
   if (!email) {
-    throw new Error(
-      "email: no sender address available - set `from` / EMAIL_FROM, `domain` / EMAIL_DOMAIN, or run on behalf of a user",
+    throw ConfigurationError.resourceNotFound(
+      "Email sender address",
+      "Set `from` / EMAIL_FROM, set `domain` / EMAIL_DOMAIN, or run on behalf of a user.",
     );
   }
   return email;