@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/cli/commands/email.ts

@@ -14,10 +14,13 @@ import {
   cliIpcCallStream,
   exitFromIpcResult,
 } from "../../ipc/cli-client.js";
+import { guessMimeType } from "../../util/mime-type.js";
 import { readStdinSync } from "../../util/read-stdin.js";
+import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { getCliLogger } from "../logger.js";
 import { shouldOutputJson, writeOutput } from "../output.js";
+import { emailHelp } from "./email.help.js";
 
 const loadModule = createRequire(import.meta.url);
 
@@ -65,34 +68,16 @@ function assistantDomain(): string {
 
 export function registerEmailCommand(program: Command): void {
   registerCommand(program, {
-    name: "email",
+    name: emailHelp.name,
     transport: "ipc",
-    description:
-      "Get your own email address — register, send, receive, and manage email natively",
+    description: emailHelp.description,
     build: (email) => {
-      // Keep the --json option at the email namespace level
-      email.option("--json", "Machine-readable compact JSON output");
+      applyCommandHelp(email, emailHelp);
 
-      email.addHelpText(
-        "after",
-        `
-Set up and manage this assistant's native email address on the Vellum
-platform. No third-party email provider or browser sign-up needed.
-
-Examples:
-  $ assistant email register mybot
-  $ assistant email unregister --confirm
-  $ assistant email send user@example.com -s "Hello" -b "Hi there"
-  $ assistant email status
-  $ assistant email list
-  $ assistant email attachment msg_abc1 --list
-  $ assistant email attachment msg_abc1 att_xyz1
-  $ assistant email register mybot --json`,
-      );
-
-      email
-        .command("register <username>")
-        .description("Register an email address for this assistant")
+      // The per-subcommand help texts that interpolate the assistant domain
+      // are runtime-computed (lazy config load), so they stay imperative
+      // here rather than in the declarative help module.
+      subcommand(email, "register")
         .addHelpText(
           "after",
           () => `
@@ -129,10 +114,7 @@ Examples:
           }
         });
 
-      email
-        .command("unregister")
-        .description("Remove the email address registered for this assistant")
-        .option("--confirm", "Skip confirmation prompt")
+      subcommand(email, "unregister")
         .addHelpText(
           "after",
           () => `
@@ -190,9 +172,7 @@ Examples:
           }
         });
 
-      email
-        .command("status")
-        .description("Show email address info and usage for this assistant")
+      subcommand(email, "status")
         .addHelpText(
           "after",
           () => `
@@ -249,100 +229,68 @@ Examples:
           }
         });
 
-      email
-        .command("list")
-        .description("List received and sent emails for this assistant")
-        .option(
-          "-d, --direction <direction>",
-          "Filter by direction: inbound, outbound, or all",
-          "all",
-        )
-        .option("-l, --limit <count>", "Maximum number of results", "20")
-        .option(
-          "--since <date>",
-          "Only show messages since this date (ISO 8601)",
-        )
-        .addHelpText(
-          "after",
-          `
-Lists email messages for this assistant. Shows subject, from, to,
-direction, and timestamp for each message.
-
-Examples:
-  $ assistant email list
-  $ assistant email list --direction inbound --limit 5
-  $ assistant email list --since 2026-04-01 --json`,
-        )
-        .action(
-          async (
-            opts: {
-              direction?: string;
-              limit?: string;
-              since?: string;
-            },
-            cmd: Command,
-          ) => {
-            const params: Record<string, string> = {};
-            if (opts.direction && opts.direction !== "all") {
-              params.direction = opts.direction;
-            }
-            if (opts.limit) {
-              params.limit = opts.limit;
-            }
-            if (opts.since) {
-              params.since = opts.since;
-            }
+      subcommand(email, "list").action(
+        async (
+          opts: {
+            direction?: string;
+            limit?: string;
+            since?: string;
+          },
+          cmd: Command,
+        ) => {
+          const params: Record<string, string> = {};
+          if (opts.direction && opts.direction !== "all") {
+            params.direction = opts.direction;
+          }
+          if (opts.limit) {
+            params.limit = opts.limit;
+          }
+          if (opts.since) {
+            params.since = opts.since;
+          }
 
-            const r = await cliIpcCall<{
-              results: {
-                id: string;
-                direction: string;
-                from_address: string;
-                to_addresses: string[];
-                subject: string;
-                created_at: string;
-              }[];
-              count: number;
-            }>("email_list", { queryParams: params });
-            if (!r.ok) {
-              return handleEmailIpcError(
-                { ok: false, error: r.error, statusCode: r.statusCode },
-                cmd,
-              );
-            }
-            const data = r.result!;
-            if (shouldOutputJson(cmd)) {
-              writeOutput(cmd, data);
+          const r = await cliIpcCall<{
+            results: {
+              id: string;
+              direction: string;
+              from_address: string;
+              to_addresses: string[];
+              subject: string;
+              created_at: string;
+            }[];
+            count: number;
+          }>("email_list", { queryParams: params });
+          if (!r.ok) {
+            return handleEmailIpcError(
+              { ok: false, error: r.error, statusCode: r.statusCode },
+              cmd,
+            );
+          }
+          const data = r.result!;
+          if (shouldOutputJson(cmd)) {
+            writeOutput(cmd, data);
+          } else {
+            const messages = data.results ?? [];
+            if (messages.length === 0) {
+              log.info("No email messages found.");
             } else {
-              const messages = data.results ?? [];
-              if (messages.length === 0) {
-                log.info("No email messages found.");
-              } else {
-                for (const msg of messages) {
-                  const dir = msg.direction === "inbound" ? "←" : "→";
-                  const to = Array.isArray(msg.to_addresses)
-                    ? msg.to_addresses.join(", ")
-                    : "";
-                  const date = new Date(msg.created_at).toLocaleString();
-                  log.info(
-                    `${dir} ${date}  ${msg.from_address} → ${to}  "${msg.subject || "(no subject)"}"`,
-                  );
-                }
-                log.info(`\n${data.count} total message(s)`);
+              for (const msg of messages) {
+                const dir = msg.direction === "inbound" ? "←" : "→";
+                const to = Array.isArray(msg.to_addresses)
+                  ? msg.to_addresses.join(", ")
+                  : "";
+                const date = new Date(msg.created_at).toLocaleString();
+                log.info(
+                  `${dir} ${date}  ${msg.from_address} → ${to}  "${msg.subject || "(no subject)"}"`,
+                );
               }
+              log.info(`\n${data.count} total message(s)`);
             }
-          },
-        );
+          }
+        },
+      );
 
-      email
-        .command("download <message-id>")
-        .description("Download a specific email message")
-        .option(
-          "--format <type>",
-          "Output format: text, html, json (default: text)",
-          "text",
-        )
-        .option("-o, --output <path>", "Write to file instead of stdout")
+      subcommand(email, "download")
         .addHelpText(
           "after",
           () => `
@@ -449,141 +397,169 @@ Examples:
           },
         );
 
-      email
-        .command("send <to...>")
-        .description("Send an email from this assistant")
-        .option("-s, --subject <text>", "Subject line")
-        .option("-b, --body <text>", "Email body (plain text)")
-        .option("-f, --file <path>", "Read body from file")
-        .option("--html <path>", "HTML body file (optional)")
-        .option(
-          "--cc <address>",
-          "CC recipient (repeatable)",
-          (val: string, prev: string[]) => [...prev, val],
-          [] as string[],
-        )
-        .option(
-          "--bcc <address>",
-          "BCC recipient (repeatable)",
-          (val: string, prev: string[]) => [...prev, val],
-          [] as string[],
-        )
-        .option(
-          "--reply-to <email_id>",
-          "Reply to an email by its ID (auto-resolves threading headers and subject)",
-        )
-        .addHelpText(
-          "after",
-          `
-Arguments:
-  to   Recipient email address(es) — one or more
-
-Sends an email from the assistant's registered email address via the
-Vellum runtime proxy. The "from" address is automatically resolved
-from the assistant's registered email address.
-
-Body source priority: --body flag > --file flag > stdin (if not a TTY).
-
-When --reply-to is provided, the platform auto-resolves In-Reply-To,
-References, and Subject headers from the referenced email. You can
-still override subject with -s.
-
-Examples:
-  $ assistant email send user@example.com -s "Hello" -b "Hi there"
-  ✓ Sent to user@example.com (delivery_id: abc123)
-
-  $ assistant email send a@example.com b@example.com --cc c@example.com -s "Team" -b "Hi all"
-  ✓ Sent to a@example.com, b@example.com (delivery_id: abc123)
-
-  $ assistant email send user@example.com --bcc boss@example.com -s "FYI" -b "See below"
-  ✓ Sent to user@example.com (delivery_id: def456)
-
-  $ assistant email send user@example.com -b "Thanks!" --reply-to 019d96e4-e5d2-7201-890e-04a21e8f95bb
-  ✓ Sent to user@example.com (delivery_id: ghi789)
-
-  $ assistant email send user@example.com -s "Hello" -b "Hi" --json
-  {"delivery_id":"abc123","status":"accepted"}`,
-        )
-        .action(
-          async (
-            to: string[],
-            opts: {
-              subject?: string;
-              body?: string;
-              file?: string;
-              html?: string;
-              cc?: string[];
-              bcc?: string[];
-              replyTo?: string;
-            },
-            cmd: Command,
-          ) => {
-            // Resolve body text: --body > --file > stdin
-            let text = opts.body;
-            if (!text && opts.file) {
-              try {
-                text = readFileSync(opts.file, "utf-8");
-              } catch (err) {
-                log.error(
-                  `Failed to read --file ${opts.file}: ${err instanceof Error ? err.message : String(err)}`,
-                );
-                process.exitCode = 1;
-                return;
-              }
+      // --cc / --bcc accumulate repeated flags into an array with an `[]`
+      // default. CliOptionHelp can only express scalar defaults and no parse
+      // functions, so the accumulator parser and array default are attached
+      // imperatively to the declaratively-registered options.
+      const send = subcommand(email, "send");
+      const collect = (val: string, prev: string[]) => [...prev, val];
+      for (const flags of [
+        "--cc <address>",
+        "--bcc <address>",
+        "--attach <path>",
+      ]) {
+        const option = send.options.find((o) => o.flags === flags);
+        if (!option) {
+          throw new Error(
+            `Option "${flags}" not found on "email send" — is it declared in email.help.ts?`,
+          );
+        }
+        option.argParser(collect).default([] as string[]);
+        send.setOptionValueWithSource(option.attributeName(), [], "default");
+      }
+      send.action(
+        async (
+          to: string[],
+          opts: {
+            subject?: string;
+            body?: string;
+            file?: string;
+            html?: string;
+            cc?: string[];
+            bcc?: string[];
+            attach?: string[];
+            replyTo?: string;
+          },
+          cmd: Command,
+        ) => {
+          // Resolve body text: --body > --file > stdin
+          let text = opts.body;
+          if (!text && opts.file) {
+            try {
+              text = readFileSync(opts.file, "utf-8");
+            } catch (err) {
+              log.error(
+                `Failed to read --file ${opts.file}: ${err instanceof Error ? err.message : String(err)}`,
+              );
+              process.exitCode = 1;
+              return;
             }
-            if (!text && !process.stdin.isTTY) {
-              try {
-                text = readStdinSync();
-              } catch (err) {
-                log.error(
-                  `Failed to read body from stdin: ${err instanceof Error ? err.message : String(err)}`,
-                );
-                process.exitCode = 1;
-                return;
-              }
+          }
+          if (!text && !process.stdin.isTTY) {
+            try {
+              text = readStdinSync();
+            } catch (err) {
+              log.error(
+                `Failed to read body from stdin: ${err instanceof Error ? err.message : String(err)}`,
+              );
+              process.exitCode = 1;
+              return;
             }
-            if (!text) {
+          }
+          if (!text) {
+            log.error(
+              "Email body is required. Use --body, --file, or pipe via stdin.",
+            );
+            process.exitCode = 1;
+            return;
+          }
+
+          // Read HTML file if --html given; pass raw content to route
+          let html: string | undefined;
+          if (opts.html) {
+            try {
+              html = readFileSync(opts.html, "utf-8");
+            } catch (err) {
               log.error(
-                "Email body is required. Use --body, --file, or pipe via stdin.",
+                `Failed to read --html ${opts.html}: ${err instanceof Error ? err.message : String(err)}`,
               );
               process.exitCode = 1;
               return;
             }
+          }
 
-            // Read HTML file if --html given; pass raw content to route
-            let html: string | undefined;
-            if (opts.html) {
+          // Read attachments and base64-encode their content for the JSON
+          // wire to the platform proxy.
+          let attachments:
+            | { filename: string; content_type: string; content: string }[]
+            | undefined;
+          if (opts.attach && opts.attach.length > 0) {
+            attachments = [];
+            for (const path of opts.attach) {
               try {
-                html = readFileSync(opts.html, "utf-8");
+                const data = readFileSync(path);
+                attachments.push({
+                  filename: basename(path),
+                  content_type: guessMimeType(path),
+                  content: data.toString("base64"),
+                });
               } catch (err) {
                 log.error(
-                  `Failed to read --html ${opts.html}: ${err instanceof Error ? err.message : String(err)}`,
+                  `Failed to read --attach ${path}: ${err instanceof Error ? err.message : String(err)}`,
                 );
                 process.exitCode = 1;
                 return;
               }
             }
+          }
 
-            const params: Record<string, unknown> = { to, text };
-            if (opts.subject) {
-              params.subject = opts.subject;
-            }
-            if (html) {
-              params.html = html;
-            }
-            if (opts.cc && opts.cc.length > 0) {
-              params.cc = opts.cc;
-            }
-            if (opts.bcc && opts.bcc.length > 0) {
-              params.bcc = opts.bcc;
-            }
-            if (opts.replyTo) {
-              params.reply_to = opts.replyTo;
-            }
+          const params: Record<string, unknown> = { to, text };
+          if (opts.subject) {
+            params.subject = opts.subject;
+          }
+          if (html) {
+            params.html = html;
+          }
+          if (opts.cc && opts.cc.length > 0) {
+            params.cc = opts.cc;
+          }
+          if (opts.bcc && opts.bcc.length > 0) {
+            params.bcc = opts.bcc;
+          }
+          if (attachments && attachments.length > 0) {
+            params.attachments = attachments;
+          }
+          if (opts.replyTo) {
+            params.reply_to = opts.replyTo;
+          }
 
-            const r = await cliIpcCall<{ delivery_id: string; status: string }>(
-              "email_send",
-              { body: params },
+          const r = await cliIpcCall<{ delivery_id: string; status: string }>(
+            "email_send",
+            { body: params },
+          );
+          if (!r.ok) {
+            return handleEmailIpcError(
+              { ok: false, error: r.error, statusCode: r.statusCode },
+              cmd,
+            );
+          }
+          const data = r.result!;
+          if (shouldOutputJson(cmd)) {
+            writeOutput(cmd, data);
+          } else {
+            log.info(
+              `✓ Sent to ${to.join(", ")} (delivery_id: ${data.delivery_id})`,
+            );
+          }
+        },
+      );
+
+      subcommand(email, "attachment").action(
+        async (
+          messageId: string,
+          attachmentId: string | undefined,
+          opts: {
+            all?: boolean;
+            output?: string;
+            list?: boolean;
+          },
+          cmd: Command,
+        ) => {
+          if (opts.list) {
+            // List mode — show attachment metadata without downloading
+            const r = await cliIpcCall<{ results: AttachmentMeta[] }>(
+              "email_attachment_list",
+              { queryParams: { messageId } },
             );
             if (!r.ok) {
               return handleEmailIpcError(
@@ -595,202 +571,137 @@ Examples:
             if (shouldOutputJson(cmd)) {
               writeOutput(cmd, data);
             } else {
-              log.info(
-                `✓ Sent to ${to.join(", ")} (delivery_id: ${data.delivery_id})`,
-              );
+              const attachments = data.results ?? [];
+              if (attachments.length === 0) {
+                log.info("No attachments for this message.");
+              } else {
+                for (const att of attachments) {
+                  log.info(
+                    `  ${att.id}  ${att.filename}  (${att.content_type}, ${formatBytes(att.size_bytes)})`,
+                  );
+                }
+                log.info(`\n${attachments.length} attachment(s)`);
+              }
             }
-          },
-        );
+            return;
+          }
 
-      email
-        .command("attachment <message-id> [attachment-id]")
-        .description("Download email attachments")
-        .option("--all", "Download all attachments for the message")
-        .option(
-          "-o, --output <dir>",
-          "Output directory (default: current directory)",
-          ".",
-        )
-        .option("--list", "List attachments without downloading")
-        .addHelpText(
-          "after",
-          `
-Arguments:
-message-id      Email message ID (from \`assistant email list --json\`)
-attachment-id   Attachment ID (optional — required unless --all or --list)
+          if (!opts.all && !attachmentId) {
+            log.error(
+              "Specify an attachment ID, or use --all to download all. Use --list to see available.",
+            );
+            process.exitCode = 1;
+            return;
+          }
 
-Download one or all attachments from a specific email message. Use
---list to see available attachments without downloading.
+          // Ensure output directory exists and download attachment(s)
+          const outDir = opts.output ?? ".";
+          try {
+            mkdirSync(outDir, { recursive: true });
+          } catch (err) {
+            log.error(
+              `Failed to create output directory ${outDir}: ${err instanceof Error ? err.message : String(err)}`,
+            );
+            process.exitCode = 1;
+            return;
+          }
 
-Examples:
-$ assistant email attachment msg_abc1 --list
-$ assistant email attachment msg_abc1 att_xyz1
-$ assistant email attachment msg_abc1 att_xyz1 -o ./downloads/
-$ assistant email attachment msg_abc1 --all
-$ assistant email attachment msg_abc1 --all -o ./attachments/
-$ assistant email attachment msg_abc1 --list --json`,
-        )
-        .action(
-          async (
-            messageId: string,
-            attachmentId: string | undefined,
-            opts: {
-              all?: boolean;
-              output?: string;
-              list?: boolean;
-            },
-            cmd: Command,
-          ) => {
-            if (opts.list) {
-              // List mode — show attachment metadata without downloading
-              const r = await cliIpcCall<{ results: AttachmentMeta[] }>(
+          try {
+            if (opts.all) {
+              // Download all attachments — list first to get filenames
+              const listR = await cliIpcCall<{ results: AttachmentMeta[] }>(
                 "email_attachment_list",
                 { queryParams: { messageId } },
               );
-              if (!r.ok) {
+              if (!listR.ok) {
                 return handleEmailIpcError(
-                  { ok: false, error: r.error, statusCode: r.statusCode },
+                  {
+                    ok: false,
+                    error: listR.error,
+                    statusCode: listR.statusCode,
+                  },
                   cmd,
                 );
               }
-              const data = r.result!;
+              const attachments = listR.result!.results ?? [];
+              if (attachments.length === 0) {
+                log.error("No attachments for this message.");
+                process.exitCode = 1;
+                return;
+              }
+
+              const downloaded: { filename: string; size_bytes: number }[] = [];
+              for (const att of attachments) {
+                const dest = join(outDir, safeFilename(att.filename));
+                await streamDownloadAttachment(att.id, messageId, dest);
+                downloaded.push({
+                  filename: att.filename,
+                  size_bytes: att.size_bytes,
+                });
+              }
+
               if (shouldOutputJson(cmd)) {
-                writeOutput(cmd, data);
+                writeOutput(cmd, {
+                  downloaded: downloaded.length,
+                  directory: outDir,
+                  files: downloaded,
+                });
               } else {
-                const attachments = data.results ?? [];
-                if (attachments.length === 0) {
-                  log.info("No attachments for this message.");
-                } else {
-                  for (const att of attachments) {
-                    log.info(
-                      `  ${att.id}  ${att.filename}  (${att.content_type}, ${formatBytes(att.size_bytes)})`,
-                    );
-                  }
-                  log.info(`\n${attachments.length} attachment(s)`);
+                log.info(
+                  `✓ Downloaded ${downloaded.length} attachment(s) to ${outDir}`,
+                );
+                for (const f of downloaded) {
+                  log.info(`  - ${f.filename} (${formatBytes(f.size_bytes)})`);
                 }
               }
-              return;
-            }
-
-            if (!opts.all && !attachmentId) {
-              log.error(
-                "Specify an attachment ID, or use --all to download all. Use --list to see available.",
-              );
-              process.exitCode = 1;
-              return;
-            }
-
-            // Ensure output directory exists and download attachment(s)
-            const outDir = opts.output ?? ".";
-            try {
-              mkdirSync(outDir, { recursive: true });
-            } catch (err) {
-              log.error(
-                `Failed to create output directory ${outDir}: ${err instanceof Error ? err.message : String(err)}`,
+            } else {
+              // Download single attachment — look up metadata from the list first
+              const listR = await cliIpcCall<{ results: AttachmentMeta[] }>(
+                "email_attachment_list",
+                { queryParams: { messageId } },
               );
-              process.exitCode = 1;
-              return;
-            }
-
-            try {
-              if (opts.all) {
-                // Download all attachments — list first to get filenames
-                const listR = await cliIpcCall<{ results: AttachmentMeta[] }>(
-                  "email_attachment_list",
-                  { queryParams: { messageId } },
+              if (!listR.ok) {
+                return handleEmailIpcError(
+                  {
+                    ok: false,
+                    error: listR.error,
+                    statusCode: listR.statusCode,
+                  },
+                  cmd,
                 );
-                if (!listR.ok) {
-                  return handleEmailIpcError(
-                    {
-                      ok: false,
-                      error: listR.error,
-                      statusCode: listR.statusCode,
-                    },
-                    cmd,
-                  );
-                }
-                const attachments = listR.result!.results ?? [];
-                if (attachments.length === 0) {
-                  log.error("No attachments for this message.");
-                  process.exitCode = 1;
-                  return;
-                }
-
-                const downloaded: { filename: string; size_bytes: number }[] =
-                  [];
-                for (const att of attachments) {
-                  const dest = join(outDir, safeFilename(att.filename));
-                  await streamDownloadAttachment(att.id, messageId, dest);
-                  downloaded.push({
-                    filename: att.filename,
-                    size_bytes: att.size_bytes,
-                  });
-                }
+              }
+              const meta = (listR.result!.results ?? []).find(
+                (a) => a.id === attachmentId,
+              );
+              if (!meta) {
+                log.error(`Attachment not found: ${attachmentId}`);
+                process.exitCode = 2;
+                return;
+              }
+              const dest = join(outDir, safeFilename(meta.filename));
+              await streamDownloadAttachment(attachmentId!, messageId, dest);
 
-                if (shouldOutputJson(cmd)) {
-                  writeOutput(cmd, {
-                    downloaded: downloaded.length,
-                    directory: outDir,
-                    files: downloaded,
-                  });
-                } else {
-                  log.info(
-                    `✓ Downloaded ${downloaded.length} attachment(s) to ${outDir}`,
-                  );
-                  for (const f of downloaded) {
-                    log.info(
-                      `  - ${f.filename} (${formatBytes(f.size_bytes)})`,
-                    );
-                  }
-                }
+              if (shouldOutputJson(cmd)) {
+                writeOutput(cmd, {
+                  filename: meta.filename,
+                  size_bytes: meta.size_bytes,
+                  saved: dest,
+                });
               } else {
-                // Download single attachment — look up metadata from the list first
-                const listR = await cliIpcCall<{ results: AttachmentMeta[] }>(
-                  "email_attachment_list",
-                  { queryParams: { messageId } },
-                );
-                if (!listR.ok) {
-                  return handleEmailIpcError(
-                    {
-                      ok: false,
-                      error: listR.error,
-                      statusCode: listR.statusCode,
-                    },
-                    cmd,
-                  );
-                }
-                const meta = (listR.result!.results ?? []).find(
-                  (a) => a.id === attachmentId,
+                log.info(
+                  `✓ Downloaded ${meta.filename} (${formatBytes(meta.size_bytes)})`,
                 );
-                if (!meta) {
-                  log.error(`Attachment not found: ${attachmentId}`);
-                  process.exitCode = 2;
-                  return;
-                }
-                const dest = join(outDir, safeFilename(meta.filename));
-                await streamDownloadAttachment(attachmentId!, messageId, dest);
-
-                if (shouldOutputJson(cmd)) {
-                  writeOutput(cmd, {
-                    filename: meta.filename,
-                    size_bytes: meta.size_bytes,
-                    saved: dest,
-                  });
-                } else {
-                  log.info(
-                    `✓ Downloaded ${meta.filename} (${formatBytes(meta.size_bytes)})`,
-                  );
-                }
               }
-            } catch (err) {
-              log.error(
-                `Failed to download attachment: ${err instanceof Error ? err.message : String(err)}`,
-              );
-              process.exitCode = 1;
-              return;
             }
-          },
-        );
+          } catch (err) {
+            log.error(
+              `Failed to download attachment: ${err instanceof Error ? err.message : String(err)}`,
+            );
+            process.exitCode = 1;
+            return;
+          }
+        },
+      );
     },
   });
 }