@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-gmail.ts

@@ -0,0 +1,78 @@
+import { parseMailbox, pkcePair, SignInError } from '@metro-labs/core/stations/oauth';
+import { managedRequest, managedTokens } from '@metro-labs/gmail/managed';
+import { ApiError } from '@metro-labs/http/api-error';
+import { stringOf } from '@metro-labs/http/api-http';
+import type { AttachOwner } from './attach-session.js';
+import type { AttachOutcome, DriverHooks, StartedAttach } from './attach-driver.js';
+
+interface ManagedStart {
+  host: string;
+  owner: AttachOwner;
+  mailbox: unknown;
+  sendEnabled: boolean;
+  check: () => void;
+}
+
+function authorizationOf(owner: AttachOwner): string {
+  if (!owner.userId || !owner.sessionId || !owner.organization || !owner.authorization) throw new ApiError('Sign in to Metro again before connecting Gmail.', 401);
+  return owner.authorization;
+}
+
+function signInLink(started: Record<string, unknown>): { state: string; authorizeUrl: string; expiresAt: number } {
+  const state = stringOf(started.state);
+  const authorizeUrl = stringOf(started.authorizeUrl);
+  const url = new URL(authorizeUrl);
+  const expiresAt = started.expiresAt;
+  if (!state || url.origin !== 'https://accounts.google.com' || url.pathname !== '/o/oauth2/v2/auth' || url.searchParams.get('state') !== state || url.searchParams.get('redirect_uri') !== 'https://metro.box/' || typeof expiresAt !== 'number' || !Number.isFinite(expiresAt) || expiresAt <= Date.now()) throw new SignInError('Metro returned an invalid Gmail sign-in link.');
+  return { state, authorizeUrl, expiresAt };
+}
+
+function outcomeOf(result: Record<string, unknown>, input: ManagedStart, mailbox: string | null): AttachOutcome {
+  const accountEmail = parseMailbox(result.accountEmail);
+  if (accountEmail === null || (mailbox !== null && accountEmail !== mailbox) || result.managed !== true || result.managedHost !== input.host || result.sendEnabled !== input.sendEnabled) throw new SignInError('Metro returned a Gmail connection for a different mailbox or access level.');
+  return { config: { ...managedTokens(result), accountEmail, managed: true, managedHost: input.host, managedOrganization: input.owner.organization, sendEnabled: input.sendEnabled }, identity: { email: accountEmail } };
+}
+
+export async function startManagedGmail(input: ManagedStart, hooks: DriverHooks): Promise<StartedAttach> {
+  const { host, owner, sendEnabled, check } = input;
+  const bearer = authorizationOf(owner);
+  const pair = pkcePair();
+  const mailbox = parseMailbox(input.mailbox);
+  check();
+  const started = await managedRequest('start', { host, agentId: owner.agentId, challenge: pair.challenge, ...(mailbox === null ? {} : { mailbox }), sendEnabled }, bearer);
+  check();
+  const { state, authorizeUrl, expiresAt } = signInLink(started);
+  let cancelled = false;
+  let used = false;
+  return {
+    expiresAt,
+    prompt: { step: 'browser', prompt: sendEnabled ? 'Approve sending for this mailbox on Google. Metro write permissions stay unchanged.' : 'Choose a Google account and approve read-only Gmail access. Metro cannot send mail with this connection.', authorizeUrl },
+    driver: {
+      cancel: async () => {
+        cancelled = true;
+        await managedRequest('cancel', { state, host, agentId: owner.agentId }, bearer);
+      },
+      submit: async (value, authorization) => {
+        if (cancelled || used || Date.now() >= expiresAt) throw new ApiError('This sign-in is finished or expired. Start again.', 409);
+        if (stringOf(value.state) !== state) throw new ApiError('This sign-in belongs to another attempt.', 400);
+        if (!authorization) throw new ApiError('Sign in to Metro again.', 401);
+        used = true;
+        try {
+          if (stringOf(value.error)) {
+            await managedRequest('cancel', { state, host, agentId: owner.agentId }, authorization);
+            hooks.fail('Google sign-in was declined or blocked. Nothing was connected.');
+            return;
+          }
+          const code = stringOf(value.code);
+          if (!code) throw new ApiError('Google did not return a sign-in code.', 400);
+          check();
+          const result = await managedRequest('exchange', { state, code, verifier: pair.verifier, host, agentId: owner.agentId }, authorization);
+          check();
+          if (!cancelled) hooks.done(outcomeOf(result, input, mailbox));
+        } catch {
+          hooks.fail('Metro could not finish this Gmail sign-in. Start again.');
+        }
+      },
+    },
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-inline.ts

@@ -0,0 +1,128 @@
+import { mkdtemp, open, rm, writeFile } from 'node:fs/promises';
+import { assertAttachmentSize } from '@metro-labs/core/stations/attachments';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export const MAX_INLINE_BYTES = 8 * 1024 * 1024;
+
+const INLINE_TEMP_PREFIX = 'metro-inline-';
+
+const BASE64_RE = /^[A-Za-z0-9+/_-]*={0,2}$/;
+
+const mib = (n: number): string => `${(n / (1024 * 1024)).toFixed(2)} MiB`;
+
+const LIMIT_HINT =
+  `inline \`data\` is capped at ${mib(MAX_INLINE_BYTES)} (${MAX_INLINE_BYTES} bytes) of decoded ` +
+  'bytes per attachment and per send, because the base64 travels inside the MCP request body. ' +
+  'Pass `url`, or a `path` already on the daemon host, for anything larger.';
+
+function assertInlineSize(bytes: number, label: string): void {
+  if (bytes > MAX_INLINE_BYTES)
+    throw new Error(`inline attachment ${label} is ${mib(bytes)}; ${LIMIT_HINT}`);
+}
+
+export function assertInlineTotal(bytes: number): void {
+  if (bytes > MAX_INLINE_BYTES)
+    throw new Error(
+      `inline attachments total ${mib(bytes)} in one send; ${LIMIT_HINT}`,
+    );
+}
+
+const padOf = (b64: string): number =>
+  b64.endsWith('==') ? 2 : b64.endsWith('=') ? 1 : 0;
+
+export const decodedLengthOf = (b64: string): number =>
+  Math.max(0, Math.floor((b64.length * 3) / 4) - padOf(b64));
+
+const malformed = (why: string): Error =>
+  new Error(
+    `inline \`data\` ${why}; pass the file's bytes base64-encoded ` +
+      '(standard or url-safe alphabet, optionally behind a `data:<mime>;base64,` prefix)',
+  );
+
+const DATA_URL_RE = /^data:([^,]*),/i;
+
+export interface InlineSource {
+  data: string;
+  mime?: string;
+}
+
+export function splitInlineData(raw: string): InlineSource {
+  const compact = raw.replace(/\s+/g, '');
+  const match = DATA_URL_RE.exec(compact);
+  if (!match) return { data: raw };
+  const params = (match[1] ?? '').split(';');
+  if (!params.slice(1).some((p) => p.toLowerCase() === 'base64'))
+    throw malformed('is a `data:` url whose payload is not base64');
+  const mime = params[0]?.toLowerCase();
+  const data = compact.slice(match[0].length);
+  return mime === undefined || mime === '' ? { data } : { data, mime };
+}
+
+export function decodeInline(raw: string, label: string): Uint8Array {
+  const b64 = raw.replace(/\s+/g, '');
+  if (!b64) throw malformed('is empty');
+  const expected = decodedLengthOf(b64);
+  assertInlineSize(expected, label);
+  if (!BASE64_RE.test(b64)) throw malformed('is not base64');
+  if (b64.length % 4 === 1 || (padOf(b64) > 0 && b64.length % 4 !== 0))
+    throw malformed('is not a whole number of base64 quanta');
+  const buf = Buffer.from(b64, 'base64');
+  if (buf.length !== expected)
+    throw malformed(`decoded to ${buf.length} bytes instead of ${expected}`);
+  return new Uint8Array(buf);
+}
+
+export const safeFileName = (name: string | undefined): string => {
+  const base = (name ?? '').split(/[\\/]/).pop() ?? '';
+  const clean = base
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .replace(/^\.+/, '')
+    .slice(0, 64);
+  return clean || 'attachment';
+};
+
+export interface InlineTemp {
+  dir: string;
+  path: string;
+}
+
+export async function writeInlineTemp(
+  data: Uint8Array,
+  name: string | undefined,
+): Promise<InlineTemp> {
+  const dir = await mkdtemp(join(tmpdir(), INLINE_TEMP_PREFIX));
+  const path = join(dir, safeFileName(name));
+  await writeFile(path, data, { mode: 0o600 });
+  return { dir, path };
+}
+
+export const removeInlineTemp = (dir: string): Promise<void> =>
+  rm(dir, { recursive: true, force: true });
+
+export async function streamToTemp(
+  body: ReadableStream<Uint8Array>,
+  name: string | undefined,
+): Promise<InlineTemp & { bytes: number }> {
+  const dir = await mkdtemp(join(tmpdir(), INLINE_TEMP_PREFIX));
+  const path = join(dir, safeFileName(name));
+  const handle = await open(path, 'wx', 0o600);
+  const reader = body.getReader();
+  let bytes = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.length;
+      assertAttachmentSize(bytes);
+      await handle.write(value);
+    }
+  } catch (err) {
+    await reader.cancel().catch(() => undefined);
+    await handle.close();
+    await removeInlineTemp(dir);
+    throw err;
+  }
+  await handle.close();
+  return { dir, path, bytes };
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-interactive.ts

@@ -0,0 +1,135 @@
+import { StationAttachError } from './attach.js';
+import type { DriverHooks, StartedAttach } from './attach-driver.js';
+import { startGmail, startOutlook } from './attach-browser.js';
+
+export const INTERACTIVE_STATIONS = ['telegram', 'whatsapp', 'outlook', 'gmail'] as const;
+
+export type InteractiveStation = (typeof INTERACTIVE_STATIONS)[number];
+
+const CODE_PROMPT =
+  'Telegram sent a login code to that number. Enter it here.';
+const PASSWORD_PROMPT =
+  'This account has two-step verification. Enter its password.';
+const SCAN_PROMPT =
+  'Open WhatsApp on your phone, go to Settings, Linked Devices, Link a Device, and scan this code.';
+const PAIR_PROMPT =
+  'Open WhatsApp on your phone, go to Settings, Linked Devices, Link a Device, Link with phone number, and type this code.';
+
+export function isInteractiveStation(raw: unknown): raw is InteractiveStation {
+  return (
+    typeof raw === 'string' &&
+    (INTERACTIVE_STATIONS as readonly string[]).includes(raw)
+  );
+}
+
+function refuse(err: unknown, fallback: string): never {
+  throw new StationAttachError(
+    err instanceof Error && err.message !== '' ? err.message : fallback,
+    400,
+  );
+}
+
+async function startTelegramUser(
+  input: Record<string, unknown>,
+  hooks: DriverHooks,
+): Promise<StartedAttach> {
+  const { TelegramLogin, TelegramLoginError, validateCredentials } =
+    await import('@metro-labs/telegram/login');
+  const isOwn = (e: unknown): boolean => e instanceof TelegramLoginError;
+  let login;
+  try {
+    login = new TelegramLogin(
+      validateCredentials({
+        apiId: input.apiId,
+        apiHash: input.apiHash,
+        phone: input.phone,
+      }),
+    );
+    await login.requestCode();
+  } catch (err) {
+    await login?.close();
+    refuse(isOwn(err) ? err : null, 'Telegram refused to start the sign-in');
+  }
+  const settled = login;
+  return {
+    prompt: { step: 'code', prompt: CODE_PROMPT },
+    driver: {
+      cancel: () => settled.close(),
+      submit: async (values) => {
+        try {
+          if (typeof values.password === 'string') {
+            hooks.done(await settled.submitPassword(values.password));
+            return;
+          }
+          if (typeof values.code !== 'string')
+            throw new StationAttachError('enter the login code', 400);
+          const result = await settled.submitCode(values.code);
+          if (result === 'password') {
+            hooks.prompt({ step: 'password', prompt: PASSWORD_PROMPT });
+            return;
+          }
+          hooks.done(result);
+        } catch (err) {
+          if (err instanceof StationAttachError) throw err;
+          refuse(isOwn(err) ? err : null, 'Telegram refused the sign-in');
+        }
+      },
+    },
+  };
+}
+
+async function startWhatsapp(
+  input: Record<string, unknown>,
+  hooks: DriverHooks,
+): Promise<StartedAttach> {
+  const { WhatsappLogin, WhatsappLoginError, normalizePhone } = await import(
+    '@metro-labs/whatsapp/login'
+  );
+  const isOwn = (e: unknown): boolean => e instanceof WhatsappLoginError;
+  let login;
+  try {
+    login = new WhatsappLogin(normalizePhone(input.phone), {
+      onQr: (qr) => {
+        hooks.prompt({ step: 'scan', prompt: SCAN_PROMPT, qr });
+      },
+      onPairingCode: (pairingCode) => {
+        hooks.prompt({ step: 'pair', prompt: PAIR_PROMPT, pairingCode });
+      },
+      onPaired: hooks.done,
+      onFailed: hooks.fail,
+    });
+    await login.start();
+  } catch (err) {
+    await login?.cancel();
+    refuse(isOwn(err) ? err : null, 'WhatsApp refused to start the pairing');
+  }
+  const settled = login;
+  const qrMode = settled.mode === 'qr';
+  return {
+    prompt: qrMode
+      ? { step: 'scan', prompt: SCAN_PROMPT }
+      : { step: 'pair', prompt: PAIR_PROMPT },
+    driver: {
+      cancel: () => settled.cancel(),
+      submit: () =>
+        Promise.reject(
+          new StationAttachError(
+            'this pairing finishes on your phone, there is nothing to submit here',
+            409,
+          ),
+        ),
+    },
+  };
+}
+
+export async function startInteractiveAttach(
+  station: InteractiveStation,
+  input: Record<string, unknown>,
+  hooks: DriverHooks,
+): Promise<StartedAttach> {
+  if (station === 'outlook') return startOutlook(input, hooks);
+  if (station === 'gmail') return startGmail(input, hooks);
+  return station === 'telegram'
+    ? startTelegramUser(input, hooks)
+    : startWhatsapp(input, hooks);
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-resolve.ts

@@ -0,0 +1,271 @@
+import {
+  assertAttachmentSize,
+  assertContentLength,
+  guessMime,
+  MAX_ATTACHMENT_BYTES,
+} from '@metro-labs/core/stations/attachments';
+import {
+  assertInlineTotal,
+  decodeInline,
+  removeInlineTemp,
+  splitInlineData,
+  streamToTemp,
+  writeInlineTemp,
+} from './attach-inline.js';
+import { realpathSync } from 'node:fs';
+import { agentCommand, agentUser, type AgentUser } from '../agent-user/user.js';
+import { log } from '@metro-labs/core/log';
+import { readUpload, UPLOAD_TTL_MS } from '../files/upload-store.js';
+import type { CanonicalAttachment } from '@metro-labs/core/stations/types';
+
+export interface ResolvedAttachment {
+  path: string;
+  mime: string;
+  name: string;
+  bytes: number;
+  temp?: string;
+}
+
+export interface ResolveOptions {
+  allowed?: Set<string>;
+}
+
+interface InlineBudget {
+  used: number;
+}
+
+const FETCH_TIMEOUT_MS = 60_000;
+
+const basenameOf = (src: string): string =>
+  src.split('?')[0]?.split('#')[0]?.split('/').filter(Boolean).pop() ?? '';
+
+const isHttpUrl = (src: string): boolean => /^https?:\/\//i.test(src);
+
+const HIDDEN_SEGMENT = /(^|\/)\.[^/]/;
+
+function assertReadablePath(path: string): void {
+  let real: string;
+  try {
+    real = realpathSync(path);
+  } catch {
+    return;
+  }
+  if (HIDDEN_SEGMENT.test(real))
+    throw new Error(
+      `attachment path '${path}' resolves into a hidden directory ` +
+        `('${real}') and will not be read. \`path\` is read on the daemon ` +
+        'machine; put the file somewhere non-hidden or pass `upload` instead.',
+    );
+}
+
+async function fromPathAs(
+  user: AgentUser,
+  a: CanonicalAttachment,
+  path: string,
+): Promise<ResolvedAttachment> {
+  const proc = Bun.spawn(agentCommand(['cat', '--', path]), { stdout: 'pipe', stderr: 'pipe' });
+  const name = a.name ?? basenameOf(path) ?? 'attachment';
+  let saved: Awaited<ReturnType<typeof streamToTemp>>;
+  try {
+    saved = await streamToTemp(proc.stdout, name);
+  } catch (err) {
+    proc.kill();
+    throw err;
+  }
+  if ((await proc.exited) !== 0) {
+    await removeInlineTemp(saved.dir);
+    throw new Error(
+      `attachment path '${path}' cannot be read by the ${user.name} user Claude Code runs as. ` +
+        '`path` is read on the daemon machine with the agent\'s own rights; pass `upload` instead.',
+    );
+  }
+  assertAttachmentSize(saved.bytes);
+  return { path: saved.path, mime: a.mime ?? guessMime(path), name, bytes: saved.bytes, temp: saved.dir };
+}
+
+async function fromPath(
+  a: CanonicalAttachment,
+  path: string,
+): Promise<ResolvedAttachment> {
+  assertReadablePath(path);
+  const user = agentUser();
+  if (user !== null) return fromPathAs(user, a, path);
+  const file = Bun.file(path);
+  if (!(await file.exists()))
+    throw new Error(
+      `attachment path '${path}' does not exist on the metro host. ` +
+        '`path` is read on the daemon machine, not on the caller\'s machine; ' +
+        'pass `url` instead if the file is not already on the daemon.',
+    );
+  assertAttachmentSize(file.size);
+  return {
+    path,
+    mime: a.mime ?? guessMime(path),
+    name: a.name ?? basenameOf(path) ?? 'attachment',
+    bytes: file.size,
+  };
+}
+
+export const curlArgs = (url: string): string[] => [
+  'curl', '-sS', '-f', '-L', '--max-redirs', '5', '--proto', '=http,https', '--proto-redir', '=http,https',
+  '--max-time', String(FETCH_TIMEOUT_MS / 1000), '--max-filesize', String(MAX_ATTACHMENT_BYTES),
+  '-w', '%{stderr}\n%{content_type}', '--', url,
+];
+
+interface CurlSaid {
+  type: string;
+  why: string;
+}
+
+function curlSaid(text: string): CurlSaid {
+  const lines = text.trimEnd().split('\n');
+  const type = lines.pop()?.split(';')[0]?.trim() ?? '';
+  return { type, why: lines.join(' ').replace(/^curl: \(\d+\)\s*/, '').trim() };
+}
+
+async function fromUrlAs(
+  user: AgentUser,
+  a: CanonicalAttachment,
+  url: string,
+): Promise<ResolvedAttachment> {
+  const proc = Bun.spawn(agentCommand(curlArgs(url)), { stdout: 'pipe', stderr: 'pipe' });
+  const name = a.name ?? basenameOf(url) ?? 'attachment';
+  const said = new Response(proc.stderr).text().catch((err: unknown) => {
+    log.debug({ err: String(err) }, 'send: could not read what curl said');
+    return '';
+  });
+  let saved: Awaited<ReturnType<typeof streamToTemp>>;
+  try {
+    saved = await streamToTemp(proc.stdout, name);
+  } catch (err) {
+    proc.kill();
+    throw err;
+  }
+  const { type, why } = curlSaid(await said);
+  if ((await proc.exited) !== 0) {
+    await removeInlineTemp(saved.dir);
+    throw new Error(`attachment fetch failed for '${url}' (fetched as the ${user.name} user): ${why || 'no answer'}`);
+  }
+  return { path: saved.path, mime: a.mime ?? (type || guessMime(url)), name, bytes: saved.bytes, temp: saved.dir };
+}
+
+async function fromUrl(
+  a: CanonicalAttachment,
+  url: string,
+): Promise<ResolvedAttachment> {
+  if (!isHttpUrl(url))
+    throw new Error(
+      `attachment url '${url}' is not an http(s) url; use \`path\` for a local file`,
+    );
+  const user = agentUser();
+  if (user !== null) return fromUrlAs(user, a, url);
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok)
+    throw new Error(`attachment fetch failed ${res.status} for '${url}'`);
+  assertContentLength(res.headers.get('content-length'));
+  const mime =
+    a.mime ?? res.headers.get('content-type')?.split(';')[0] ?? guessMime(url);
+  const name = a.name ?? basenameOf(url) ?? 'attachment';
+  if (res.body === null) throw new Error(`attachment fetch returned no body for '${url}'`);
+  const { dir, path, bytes } = await streamToTemp(res.body, name);
+  return { path, mime, name, bytes, temp: dir };
+}
+
+async function fromData(
+  a: CanonicalAttachment,
+  data: string,
+  budget: InlineBudget,
+): Promise<ResolvedAttachment> {
+  const name = a.name ?? 'attachment';
+  const source = splitInlineData(data);
+  const bytes = decodeInline(source.data, `'${name}'`);
+  budget.used += bytes.length;
+  assertInlineTotal(budget.used);
+  const { dir, path } = await writeInlineTemp(bytes, a.name);
+  return {
+    path,
+    mime: a.mime ?? source.mime ?? guessMime(name),
+    name,
+    bytes: bytes.length,
+    temp: dir,
+  };
+}
+
+const uploadMissing = (id: string): Error =>
+  new Error(
+    `upload '${id}' is not a live upload of yours. Either it was never created, or its ` +
+      'bytes were never pushed to `POST /api/uploads`, or it belongs to another agent, or ' +
+      `it expired (an upload lives ${Math.round(UPLOAD_TTL_MS / 60_000)} minutes). ` +
+      'Create a new one with `create_upload` and push the file again.',
+  );
+
+function fromUpload(
+  a: CanonicalAttachment,
+  id: string,
+  allowed: Set<string> | undefined,
+): ResolvedAttachment {
+  const rec = allowed === undefined ? undefined : readUpload(id);
+  if (rec === undefined || !(allowed?.has(rec.agentId) ?? false))
+    throw uploadMissing(id);
+  const name = a.name ?? rec.name;
+  return { path: rec.path, mime: a.mime ?? rec.mime, name, bytes: rec.bytes };
+}
+
+export const SOURCE_KEYS = ['path', 'url', 'data', 'upload'] as const;
+
+const sourcesOf = (a: CanonicalAttachment): string[] =>
+  SOURCE_KEYS.filter((k) => {
+    const v = a[k];
+    return typeof v === 'string' && v.length > 0;
+  });
+
+async function resolveAttachment(
+  a: CanonicalAttachment,
+  budget: InlineBudget = { used: 0 },
+  opts: ResolveOptions = {},
+): Promise<ResolvedAttachment> {
+  const sources = sourcesOf(a);
+  if (sources.length === 0)
+    throw new Error(
+      'attachment requires exactly one of `upload`, `data`, `url` or `path`',
+    );
+  if (sources.length > 1)
+    throw new Error(
+      `attachment names ${sources.length} sources (${sources
+        .map((s) => `\`${s}\``)
+        .join(', ')}); pass exactly one of \`upload\`, \`data\`, \`url\` or \`path\``,
+    );
+  log.info({ source: sources[0] }, 'send: attachment source');
+  if (a.upload) return fromUpload(a, a.upload, opts.allowed);
+  if (a.data) return fromData(a, a.data, budget);
+  if (a.path) return fromPath(a, a.path);
+  return fromUrl(a, a.url ?? '');
+}
+
+export async function cleanupAttachments(
+  atts: ResolvedAttachment[],
+): Promise<void> {
+  for (const a of atts) if (a.temp) await removeInlineTemp(a.temp);
+}
+
+export async function resolveAttachments(
+  atts: CanonicalAttachment[],
+  opts: ResolveOptions = {},
+): Promise<ResolvedAttachment[]> {
+  const out: ResolvedAttachment[] = [];
+  const budget: InlineBudget = { used: 0 };
+  for (let i = 0; i < atts.length; i++) {
+    const a = atts[i];
+    if (!a) continue;
+    try {
+      out.push(await resolveAttachment(a, budget, opts));
+    } catch (e) {
+      await cleanupAttachments(out);
+      const why = e instanceof Error ? e.message : String(e);
+      throw new Error(`attachment ${i + 1} of ${atts.length}: ${why}`);
+    }
+  }
+  return out;
+}