Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
47.3 KB
Raw Blame
/**
 * Email — outbound (Resend) + address resolution + threading helpers.
 *
 * Agents get a real address shaped `<participantId>.<companySlug>@<EMAIL_DOMAIN>`
 * (apex on purpose — see computeAgentAddress for the why).
 * Addresses are minted lazily the first time something asks for one, so old
 * agents don't need a backfill migration — they get an address on their next
 * email-related action.
 *
 * Inbound is in api/inbound-email.ts (it's a webhook, not an outbound flow).
 *
 * Mock mode: when RESEND_API_KEY is empty, `sendViaProvider` returns a fake
 * smtp_message_id and logs. The rest of the flow (DB writes, threading,
 * agent wakes) runs identically — useful for local dev where you don't
 * want to burn Resend quota.
 */
import { randomUUID } from 'node:crypto'
import type { PoolClient } from 'pg'
import { pool } from './db/pool.js'
import { env } from './env.js'
import { grantAttachment } from './attachments/grants.js'

/** Lowercased domain for an address-construction call. Returns '' when
 *  EMAIL_DOMAIN isn't configured — callers should treat that as "email
 *  feature disabled". */
function rootDomain(): string { return env.EMAIL_DOMAIN }

/** Slug-safe form of companies.slug. Already lowercased + hyphenated per
 *  onboardCompany.ts, but defend against legacy rows that predate that
 *  rule. We strip `.` so the apex address `<id>.<slug>@<dom>` parses
 *  unambiguously by splitting the local-part on its LAST `.`. */
function safeSlugPart(slug: string): string {
  return slug.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^-+|-+$/g, '').slice(0, 63)
}

/** Local-part sanitizer for an agent id. Same DNS-1123-ish constraints as
 *  the orchestrator pod-name slug — they're related concepts. We strip
 *  `.` so the slug separator in `<id>.<slug>@<dom>` is the only `.` in
 *  the local-part, making reverse parsing unambiguous. */
function safeLocalPart(id: string): string {
  return id.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^[-_]+|[-_]+$/g, '').slice(0, 64)
}

/** Compute an agent's email address from id + companySlug.
 *  Format: `<sanitized id>.<sanitized slug>@<EMAIL_DOMAIN>`, e.g.
 *  `[email protected]`. Apex domain on purpose — keeps Resend's
 *  per-domain DKIM/verification at one-time-setup cost no matter how many
 *  tenants the system grows to. (Earlier iterations used a per-tenant
 *  subdomain; we moved off it because each new company would have needed
 *  its own Resend domain verified.)
 *
 *  Returns null when the email feature isn't configured. */
export function computeAgentAddress(agentId: string, companySlug: string): string | null {
  const dom = rootDomain()
  if (!dom) return null
  const local = safeLocalPart(agentId)
  const slug = safeSlugPart(companySlug)
  if (!local || !slug) return null
  return `${local}.${slug}@${dom}`
}

interface ParticipantAddrRow {
  participant_id: string
  email: string | null
  company_slug: string
  display_name: string
  kind: string
}

/** Read or mint a participant's cumora email address (works for both
 *  agents AND humans — the address scheme is the same:
 *  `<participantId>.<companySlug>@<EMAIL_DOMAIN>`). Idempotent — once
 *  written to participants.email we just return what's there. Returns
 *  null when:
 *    - the participant doesn't exist OR has no company slug, OR
 *    - EMAIL_DOMAIN isn't set (feature disabled).
 *
 *  Why humans need a cumora address (and not their auth gmail / outlook):
 *  Resend will refuse outbound from any domain we haven't verified, so a
 *  human "send via cumora" can't put their personal gmail in the From
 *  line. The cumora address solves both directions — Resend accepts it
 *  (we own cumora.ai), and replies route back through the inbound webhook
 *  so the conversation lives in cumora. The user's auth email becomes a
 *  secondary identifier (still used for /participants display + the
 *  inbound resolver's "is this incoming sender a known workspace
 *  member?" check). */
export async function ensureParticipantAddress(participantId: string, companyId: string): Promise<{
  participantId: string
  email: string
  displayName: string
  kind: string
} | null> {
  const { rows } = await pool.query<ParticipantAddrRow>(
    `SELECT p.id AS participant_id, p.email, p.name AS display_name,
            p.kind, c.slug AS company_slug
       FROM participants p
       JOIN companies c ON c.id = p.company_id
      WHERE p.id = $1 AND p.company_id = $2 AND p.departed_at IS NULL
      LIMIT 1`,
    [participantId, companyId],
  )
  const row = rows[0]
  if (!row) return null
  if (row.email) return { participantId: row.participant_id, email: row.email, displayName: row.display_name, kind: row.kind }
  const minted = computeAgentAddress(row.participant_id, row.company_slug)
  if (!minted) return null
  // Race-safe: the unique index on lower(email) means concurrent mints for
  // the same participant collapse to one row.
  await pool.query(
    `UPDATE participants SET email = $2
      WHERE id = $1 AND company_id = $3 AND email IS NULL`,
    [participantId, minted, companyId],
  )
  return { participantId: row.participant_id, email: minted, displayName: row.display_name, kind: row.kind }
}

/** Backwards-compat shim — older callers that knew the agent id but not
 *  the company id. Looks up the company implicitly. Prefer
 *  ensureParticipantAddress() at new call sites. */
export async function ensureAgentAddress(agentId: string): Promise<{
  agentId: string
  email: string
  displayName: string
} | null> {
  const { rows } = await pool.query<{ company_id: string }>(
    `SELECT company_id FROM participants
      WHERE id = $1 AND kind = 'agent' AND departed_at IS NULL LIMIT 1`,
    [agentId],
  )
  if (!rows[0]) return null
  const r = await ensureParticipantAddress(agentId, rows[0].company_id)
  if (!r) return null
  return { agentId: r.participantId, email: r.email, displayName: r.displayName }
}

/** Backfill addresses for every agent in a tenant that doesn't have one.
 *  Used by the boot path when the email feature is freshly enabled, AND
 *  by onboardCompany when a new company is created. */
export async function backfillCompanyAgentAddresses(companyId: string): Promise<number> {
  if (!env.EMAIL_DOMAIN) return 0
  const { rows } = await pool.query<{ id: string; slug: string }>(
    `SELECT p.id, c.slug
       FROM participants p
       JOIN companies c ON c.id = p.company_id
      WHERE p.company_id = $1
        AND p.kind = 'agent' AND p.departed_at IS NULL
        AND p.email IS NULL`,
    [companyId],
  )
  let n = 0
  for (const r of rows) {
    const addr = computeAgentAddress(r.id, r.slug)
    if (!addr) continue
    const u = await pool.query(
      `UPDATE participants SET email = $2
        WHERE id = $1 AND company_id = $3 AND email IS NULL`,
      [r.id, addr, companyId],
    )
    n += u.rowCount ?? 0
  }
  return n
}

/** Parse one address from "Name <addr@host>" or "addr@host". Returns the
 *  lowercased address. Returns null on garbage input — caller handles the
 *  rejection. */
export function parseAddress(raw: string): { addr: string; name: string | null } | null {
  const trimmed = raw.trim()
  if (!trimmed) return null
  const m = /^\s*(?:"?([^"<]*?)"?\s*)?<([^>]+)>\s*$/.exec(trimmed)
  if (m) {
    const addr = m[2].trim().toLowerCase()
    const name = (m[1] ?? '').trim() || null
    return /^[^@\s]+@[^@\s]+$/.test(addr) ? { addr, name } : null
  }
  const addr = trimmed.toLowerCase()
  return /^[^@\s]+@[^@\s]+$/.test(addr) ? { addr, name: null } : null
}

/** Render "Name <addr>" if a name is given, otherwise just "addr". */
export function formatAddress(addr: string, name: string | null): string {
  if (!name) return addr
  // Quote if the name contains anything that'd confuse a parser.
  const needsQuote = /["<>,;:@()[\]\\]/.test(name)
  const safeName = name.replace(/"/g, '\\"')
  return needsQuote ? `"${safeName}" <${addr}>` : `${safeName} <${addr}>`
}

/** Clean an outbound Subject line: collapse whitespace, strip control chars
 *  and stray BOMs that LLMs occasionally emit, cap length so we never blow
 *  past what MTAs accept (RFC 5322 soft-limit is 998 octets per line; 200
 *  is plenty for a human-readable subject and well under what every webmail
 *  preview pane shows). Returns an empty string only when the input had no
 *  printable characters — callers gate on that. */
export function sanitizeSubject(raw: string): string {
  if (!raw) return ''
  // eslint-disable-next-line no-control-regex
  const stripped = raw
    // ASCII C0 controls + DEL -> space.
    // eslint-disable-next-line no-control-regex
    .replace(/[-]+/g, ' ')
    // Zero-width / direction marks / BOM -> drop entirely (replacing with
    // a space would create a visible word break where none was intended).
    .replace(/[​-‏‪-‮⁠]+/g, '')
    .replace(/\s+/g, ' ')
    .trim()
  return stripped.slice(0, 200)
}

/** Sanitize an inbound HTML email body for safe rendering inside a
 *  sandboxed iframe. Defense in depth: the iframe sandbox (no
 *  `allow-scripts`, no `allow-top-navigation`) is the primary barrier, but
 *  we still strip every obvious vector so the rendered surface stays small
 *  and predictable across mail clients' quirky markup.
 *
 *  Conservative: tags / attributes get dropped, not transformed. Real
 *  mailers ship a lot of inline CSS; we leave style="..." alone because
 *  blocking it would break almost every newsletter, and a sandboxed
 *  iframe can't be navigated or scripted by inline CSS anyway. */
export function sanitizeEmailHtml(raw: string): string {
  if (!raw) return ''
  let out = raw
  // Strip whole tag bodies for anything that can execute or load remote code.
  for (const tag of ['script', 'style', 'iframe', 'object', 'embed', 'frame', 'frameset', 'applet', 'svg', 'math']) {
    const re = new RegExp(`<${tag}[\\s\\S]*?<\\/${tag}>`, 'gi')
    out = out.replace(re, '')
    // Self-closing / unclosed variants.
    out = out.replace(new RegExp(`<${tag}\\b[^>]*\\/?>`, 'gi'), '')
  }
  // Strip <link> + <meta> entirely — they're load-side-effect or
  // refresh vectors and bring nothing to a rendered email body.
  out = out.replace(/<(?:link|meta|base)\b[^>]*\/?>/gi, '')
  // <!-- comments --> often hide MS Office conditional comments that
  // contain real markup. Drop them — they're never load-bearing in modern
  // mail rendering, and they confuse the regex passes below.
  out = out.replace(/<!--[\s\S]*?-->/g, '')
  // Strip event-handler attributes (on*=...) regardless of quoting style.
  out = out.replace(/\son[a-z]+\s*=\s*"[^"]*"/gi, '')
  out = out.replace(/\son[a-z]+\s*=\s*'[^']*'/gi, '')
  out = out.replace(/\son[a-z]+\s*=\s*[^\s>]+/gi, '')
  // Neutralize dangerous URL schemes in href / src / action / formaction /
  // background / poster / xlink:href. We rewrite to "#" rather than dropping
  // the attribute so anchor structure (and the renderer's link icon) stays.
  const urlAttr = /\b(href|src|action|formaction|background|poster|xlink:href|data)\s*=\s*("|'|)\s*(javascript:|vbscript:|data:(?!image\/(?:png|jpeg|gif|webp|svg\+xml);)|file:)/gi
  out = out.replace(urlAttr, (_m, attr, q) => `${attr}=${q || '"'}#${q || '"'}`)
  // Strip srcdoc on any remaining tag (iframe already gone; defense in depth).
  out = out.replace(/\bsrcdoc\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
  return out
}

/** Reply-all address split. RFC 5322 / typical webmail semantics:
 *    TO  = original From (the person we're answering)
 *    CC  = original To + original Cc, with self / duplicates removed
 *  Earlier iterations collapsed everything into TO, which read fine to
 *  humans but broke any client that uses the CC list to decide whose
 *  attention is required vs. who's merely informed.
 *
 *  selfAddresses are lowercased addresses that identify the replier (their
 *  cumora address AND, for humans, their auth email — both can appear in
 *  the original headers, and either marks "this is me, drop me"). */
export function splitReplyAddresses(args: {
  originalFrom: string
  originalTo: string[]
  originalCc: string[]
  selfAddresses: string[]
}): { to: string[]; cc: string[] } {
  const seen = new Set<string>(args.selfAddresses.map((s) => s.toLowerCase()))
  const fromParsed = parseAddress(args.originalFrom)
  const to: string[] = []
  if (fromParsed && !seen.has(fromParsed.addr)) {
    seen.add(fromParsed.addr)
    to.push(formatAddress(fromParsed.addr, fromParsed.name))
  }
  const cc: string[] = []
  for (const raw of [...(args.originalTo ?? []), ...(args.originalCc ?? [])]) {
    const p = parseAddress(raw)
    if (!p || seen.has(p.addr)) continue
    seen.add(p.addr)
    cc.push(formatAddress(p.addr, p.name))
  }
  return { to, cc }
}

/** Mint an RFC 5322 Message-ID local-half. Domain half is added by the
 *  caller using EMAIL_DOMAIN so the id is recognizable as ours. */
function mintLocalMessageId(): string {
  return `${Date.now().toString(36)}-${randomUUID().replace(/-/g, '').slice(0, 22)}`
}

/** Mint a complete Message-ID (no surrounding angle brackets — we store
 *  bracket-less throughout). Resend assigns its own message-id but for
 *  outbound rows we want a stable id we know up-front so threading writes
 *  can land before the provider call returns. The provider's id (if
 *  different) overwrites this on success. */
export function mintMessageId(): string {
  const dom = env.EMAIL_DOMAIN || 'cumora.local'
  return `${mintLocalMessageId()}@${dom}`
}

/** Strip <…> wrappers and lowercase. Used everywhere we compare a
 *  Message-ID — RFC 5322 says they're case-sensitive, but in practice
 *  every MTA and webmail normalizes; doing the same lets in-reply-to
 *  match references chains across mixed-case providers. */
export function normalizeMessageId(raw: string | null | undefined): string | null {
  if (!raw) return null
  const trimmed = String(raw).trim().replace(/^<+|>+$/g, '').trim()
  if (!trimmed) return null
  return trimmed.toLowerCase()
}

/** Outcome of a provider send. We always return one — failures don't
 *  throw — so the caller can decide whether to mark transport_status
 *  failed (and what error to record) without try/catch boilerplate. */
export interface ProviderSendResult {
  ok: boolean
  smtpMessageId: string | null
  error: string | null
  /** True when we ran in mock mode (RESEND_API_KEY empty). */
  mock: boolean
}

interface SendArgs {
  /** Full From line: e.g. "Aurora <[email protected]>" */
  from: string
  to: string[]
  cc?: string[]
  bcc?: string[]
  subject: string
  text: string
  html?: string
  /** Bracket-less message-ids to thread under. Resend honors these. */
  inReplyTo?: string | null
  references?: string[]
  /** When set, the provider should accept this id as the Message-ID rather
   *  than minting its own. The same stable value also derives Resend's
   *  Idempotency-Key, making crash recovery safe within its 24-hour window. */
  messageId?: string | null
  /** True when this send is automation (heartbeat decision or agent CLI
   *  shelling out). Adds an RFC 3834 Auto-Submitted header so receiving
   *  MTAs / vacation responders don't bounce-loop with us, and the inbound
   *  side has a signal to refuse auto-replying back. False / omitted for
   *  human-driven sends (compose drawer). */
  autoSubmitted?: 'auto-replied' | 'auto-generated'
  /** Reply-To address (a single mailbox, with or without a display name —
   *  same format as `from`). Used when the From address is a no-inbox
   *  sender (e.g. invites@) but we want replies to land somewhere real
   *  (e.g. the human inviter's mailbox). Resend supports this as a
   *  top-level `reply_to` field; omitting it lets replies default to
   *  From, which for no-inbox addresses means /dev/null. */
  replyTo?: string
  /** Outbound attachments. Each entry MUST supply either base64-encoded
   *  bytes (small inline files, e.g. agent CLI's `--attach`) OR a public
   *  `path` URL Resend can fetch (preferred for already-uploaded files).
   *  Bare metadata-only entries are skipped at provider time — the
   *  message still persists with an email_attachments row marked
   *  truncated, useful when the caller wants the audit trail without
   *  actually attaching bytes. */
  attachments?: Array<{
    filename: string
    mimeType?: string
    /** Base64 body. Wins if both `path` and `base64` are present. */
    base64?: string
    /** Public URL Resend (or curious MTAs) can GET. Used by the human
     *  compose path: file already lives in object storage with a signed
     *  URL, no need to download + re-encode it. */
    path?: string
  }>
}

/** Talk to Resend's HTTP API (or mock). Returns the provider's
 *  message-id. NEVER throws — failures populate `error`. */
export async function sendViaProvider(args: SendArgs): Promise<ProviderSendResult> {
  // Read from process.env directly (not env.*) so:
  //   1. an operator can rotate the Resend key without restarting,
  //   2. the retry integration tests can flip live ↔ mock between cases
  //      by toggling the env var.
  const apiKey = process.env.RESEND_API_KEY ?? ''
  if (!apiKey) {
    // Mock-mode failure injection. EMAIL_MOCK_FAIL_RATE in (0..1] lets local
    // dev exercise the failed-transport branch without burning Resend quota
    // or actually misconfiguring credentials. 0 / unset = always succeed.
    // Read from process.env directly (not env.*) so integration tests can
    // toggle the rate per-call between successful + failing retry attempts
    // without restarting the process.
    const failRate = Math.max(0, Math.min(1, Number(process.env.EMAIL_MOCK_FAIL_RATE ?? 0) || 0))
    if (failRate > 0 && Math.random() < failRate) {
      console.log(`[email/mock] ${args.from} → ${args.to.join(',')} · subj="${args.subject.slice(0, 80)}" · INJECTED FAILURE`)
      const { inc } = await import('./metrics.js')
      inc('email.send.fail', { mock: true })
      return { ok: false, smtpMessageId: null, error: `mock_injected_failure (rate=${failRate})`, mock: true }
    }
    const mockedId = args.messageId ?? mintMessageId()
    const attTag = args.attachments?.length
      ? ` · attach=[${args.attachments.map((a) => a.filename).join(',').slice(0, 200)}]`
      : ''
    console.log(`[email/mock] ${args.from} → ${args.to.join(',')} · subj="${args.subject.slice(0, 80)}"${attTag} · id=${mockedId}`)
    const { inc } = await import('./metrics.js')
    inc('email.send.ok', { mock: true })
    return { ok: true, smtpMessageId: mockedId, error: null, mock: true }
  }
  // Build Resend's payload. Headers field is how we attach In-Reply-To /
  // References — Resend doesn't have first-class fields for those.
  const headers: Record<string, string> = {}
  // Wire Message-ID: hand Resend our minted id and trust SES to honor it.
  // Without this header, SES generates its own Message-ID
  // (`0106xxx@*.amazonses.com`), recipients reply with
  // `In-Reply-To: <SES-id>`, and our threading lookup against
  // email_messages.smtp_message_id (which we set to OUR id) misses —
  // every reply spawns a new conversation. Setting Message-ID
  // explicitly keeps the id we persist matching what's on the wire.
  if (args.messageId) headers['Message-ID'] = `<${args.messageId}>`
  if (args.inReplyTo) headers['In-Reply-To'] = `<${args.inReplyTo}>`
  if (args.references && args.references.length) {
    headers['References'] = args.references.map((r) => `<${r}>`).join(' ')
  }
  if (args.autoSubmitted) {
    headers['Auto-Submitted'] = args.autoSubmitted
  }
  const body: Record<string, unknown> = {
    from: args.from,
    to: args.to,
    subject: args.subject,
    text: args.text,
  }
  if (args.html) body.html = args.html
  if (args.cc?.length) body.cc = args.cc
  if (args.bcc?.length) body.bcc = args.bcc
  if (args.replyTo) body.reply_to = args.replyTo
  if (Object.keys(headers).length) body.headers = headers
  // Resend accepts attachments as [{filename, content}] (base64) OR
  // [{filename, path}] (URL fetched server-side by Resend). We forward
  // whichever the caller supplied; entries with NEITHER are dropped at
  // this layer (no bytes to send) but the persistence layer still records
  // the row as truncated so the recipient sees what was supposed to be
  // there.
  if (args.attachments?.length) {
    const resendAttachments: Array<Record<string, string>> = []
    for (const a of args.attachments) {
      if (a.base64) {
        resendAttachments.push({ filename: a.filename, content: a.base64 })
      } else if (a.path) {
        resendAttachments.push({ filename: a.filename, path: a.path })
      }
    }
    if (resendAttachments.length) body.attachments = resendAttachments
  }

  const t0 = Date.now()
  let res: Response
  try {
    res = await fetch('https://api.resend.com/emails', {
      method: 'POST',
      headers: {
        'authorization': `Bearer ${apiKey}`,
        'content-type': 'application/json',
        ...(args.messageId
          ? { 'idempotency-key': `cumora-email/${normalizeMessageId(args.messageId) ?? args.messageId}` }
          : {}),
      },
      body: JSON.stringify(body),
    })
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e)
    console.warn(JSON.stringify({
      evt: 'email.send.network_error', error: msg,
      to_count: args.to.length, cc_count: args.cc?.length ?? 0,
    }))
    const { inc } = await import('./metrics.js')
    inc('email.send.fail', { mock: false })
    return { ok: false, smtpMessageId: null, error: `network: ${msg}`, mock: false }
  }
  const ms = Date.now() - t0
  if (!res.ok) {
    const text = await res.text().catch(() => '')
    console.warn(JSON.stringify({
      evt: 'email.send.provider_reject', status: res.status,
      detail: text.slice(0, 200), latency_ms: ms,
      to_count: args.to.length, cc_count: args.cc?.length ?? 0,
    }))
    const { inc } = await import('./metrics.js')
    inc('email.send.fail', { mock: false })
    return {
      ok: false,
      smtpMessageId: null,
      error: `resend ${res.status}: ${text.slice(0, 400)}`,
      mock: false,
    }
  }
  // Resend returns { id, ... } where `id` is its INTERNAL provider id
  // (not the wire Message-ID). We pass our minted id via the
  // `Message-ID` header above, so SES emits it on the wire and every
  // downstream MTA references THAT when threading. The provider id is
  // useful for cross-referencing in the Resend dashboard but not for
  // threading lookups.
  let payload: { id?: string } = {}
  try { payload = await res.json() as { id?: string } } catch { /* ignore */ }
  console.log(JSON.stringify({
    evt: 'email.send.ok', provider_id: payload.id ?? null,
    latency_ms: ms, to_count: args.to.length, cc_count: args.cc?.length ?? 0,
    attachment_count: args.attachments?.length ?? 0,
    auto_submitted: args.autoSubmitted ?? null,
  }))
  const { inc } = await import('./metrics.js')
  inc('email.send.ok', { mock: false })
  return {
    ok: true,
    smtpMessageId: args.messageId ?? mintMessageId(),
    error: null,
    mock: false,
  }
}

/** Look up an existing email conversation that any of these message-ids
 *  belong to. Returns the conversation_id of the first match, or null.
 *  Used by the inbound webhook (in-reply-to / references → existing
 *  thread) and by the CLI reply path. */
export async function findEmailConversationByMessageIds(
  messageIds: string[],
  companyId: string,
  client?: PoolClient,
): Promise<string | null> {
  if (messageIds.length === 0) return null
  const norm = messageIds.map(normalizeMessageId).filter((x): x is string => Boolean(x))
  if (norm.length === 0) return null
  const { rows } = await (client ?? pool).query<{ conversation_id: string }>(
    `SELECT conversation_id FROM email_messages
      WHERE company_id = $1
        AND LOWER(smtp_message_id) = ANY($2::text[])
      ORDER BY created_at DESC
      LIMIT 1`,
    [companyId, norm],
  )
  return rows[0]?.conversation_id ?? null
}

/** Resolve a recipient address to a participant in the same company.
 *  Returns null if not found / not in this company. Case-insensitive. */
export async function findParticipantByAddress(
  addr: string,
  companyId: string,
): Promise<{ id: string; name: string; kind: string } | null> {
  const lc = addr.trim().toLowerCase()
  if (!lc) return null
  const { rows } = await pool.query<{ id: string; name: string; kind: string }>(
    `SELECT id, name, kind FROM participants
      WHERE company_id = $1 AND LOWER(email) = $2 AND departed_at IS NULL
      LIMIT 1`,
    [companyId, lc],
  )
  return rows[0] ?? null
}

/** Find a human user by their auth email AND verify they belong to a
 *  given company (so a stranger guessing emails can't post to a tenant
 *  they have no membership in). Returns the user's id, used as the
 *  participant id for human authors. */
export async function findUserInCompanyByAuthEmail(
  authEmail: string,
  companyId: string,
): Promise<{ id: string; displayName: string } | null> {
  const lc = authEmail.trim().toLowerCase()
  if (!lc) return null
  const { rows } = await pool.query<{ id: string; display_name: string }>(
    `SELECT u.id, u.display_name
       FROM users u
       JOIN company_members cm ON cm.user_id = u.id
      WHERE LOWER(u.email) = $1 AND cm.company_id = $2
      LIMIT 1`,
    [lc, companyId],
  )
  return rows[0] ? { id: rows[0].id, displayName: rows[0].display_name } : null
}

/** Insert one row into the messages + email_messages pair, atomically
 *  bumping the conversation sequence and publishing the wake event so
 *  every recipient agent's pod gets a chance to react.
 *
 *  This is the SHARED write path for both directions — outbound (CLI:
 *  `cumora email send/reply`) and inbound (webhook). Centralizing it
 *  keeps the threading invariants in one spot:
 *    - one messages.id per email message; same id is the email_messages PK
 *    - the conversation already exists; caller decides which one
 *    - smtp_message_id is unique within a company (set per direction)
 *    - in_reply_to / references_chain are bracket-less, lowercased
 *    - the sender (authorId) is a participant in the same company
 *    - publish so other agents in the conversation wake naturally
 *
 *  Returns the new messageId. Throws on DB error — caller's catch
 *  surfaces it as a 4xx / CLI error.
 */
export async function persistEmailMessage(args: {
  conversationId: string
  companyId: string
  /** Participant id authoring this message — agent for outbound, agent or
   *  human for inbound from a recognized sender, or a synthetic
   *  `external:<addr>` id for unknown senders. */
  authorId: string
  direction: 'in' | 'out'
  transportStatus: 'queued' | 'sending' | 'sent' | 'failed' | 'received'
  transportError?: string | null
  smtpMessageId: string | null
  inReplyTo: string | null
  references: string[]
  subject: string
  fromAddr: string
  toAddrs: string[]
  ccAddrs?: string[]
  bccAddrs?: string[]
  /** Body the agent / renderer reads. Plain text always, even when the
   *  source was HTML — caller strips tags before passing in. */
  body: string
  html?: string | null
  rawSizeBytes?: number | null
  /** RFC 3834: true means automation generated this. Outbound from the
   *  heartbeat / agent CLI sets this; human-composed sends and inbound
   *  from real humans don't. Used by loadEmailSnapshot to keep the LLM
   *  from auto-replying to other automation (loop protection). */
  autoSubmitted?: boolean
  /** Optional attachment metadata, already-uploaded form. Each entry
   *  becomes one email_attachments row so the renderer's JOIN sees the
   *  same shape it does for inbound mail. `storageKey` is the object-
   *  storage path; pass null when only metadata is being recorded (e.g.
   *  a file that failed to upload — we still want the audit row with
   *  truncated=true). */
  attachments?: Array<{
    filename: string
    mimeType: string
    sizeBytes: number
    storageKey: string | null
    truncated?: boolean
  }>
}): Promise<{ messageId: string; sequence: number }> {
  // Need this lazily to avoid a circular import (redis pulls in env, etc).
  const { CH_MESSAGE_NEW, publish } = await import('./redis.js')
  const messageId = `m-${randomUUID()}`
  interface PersistedAttachment {
    id: string; filename: string; mimeType: string; sizeBytes: number;
    storageKey: string | null; truncated: boolean;
  }
  const persistedAttachments: PersistedAttachment[] = []
  let sequence = 0
  const client = await pool.connect()
  try {
    await client.query('BEGIN')
    if (args.direction === 'out') {
      // Outbound mail is a privileged conversation write. Pin the current
      // participant row before checking membership so a concurrent kick,
      // offboarding, or tenant reassignment serializes at this boundary.
      const actor = await client.query(
        `SELECT id FROM participants
          WHERE id = $1 AND company_id = $2
            AND kind IN ('agent', 'human') AND departed_at IS NULL
          FOR SHARE`,
        [args.authorId, args.companyId],
      )
      if (!actor.rowCount) throw new Error('email author is no longer an active tenant participant')
    }
    const conversation = await client.query(
      `SELECT id FROM conversations
        WHERE id = $1 AND company_id = $2
        FOR UPDATE`,
      [args.conversationId, args.companyId],
    )
    if (!conversation.rowCount) throw new Error('email conversation not found or no longer authorized')
    if (args.direction === 'out') {
      const membership = await client.query(
        `SELECT 1 FROM conversation_members
          WHERE conversation_id = $1
            AND company_id = $2
            AND participant_id = $3`,
        [args.conversationId, args.companyId, args.authorId],
      )
      if (!membership.rowCount) throw new Error('email conversation not found or no longer authorized')
    }

    const seqResult = await client.query<{ seq: number }>(
      `INSERT INTO conversation_counters (conversation_id, next_sequence)
       VALUES ($1, 2)
       ON CONFLICT (conversation_id) DO UPDATE SET next_sequence = conversation_counters.next_sequence + 1
       RETURNING next_sequence - 1 AS seq`,
      [args.conversationId],
    )
    sequence = seqResult.rows[0]?.seq ?? 1
    await client.query(
      `INSERT INTO messages (id, conversation_id, author_id, kind, body, sequence, company_id)
       VALUES ($1, $2, $3, 'email', $4, $5, $6)`,
      [messageId, args.conversationId, args.authorId, args.body, sequence, args.companyId],
    )
    const initialRetryAt = args.direction === 'out'
      ? (args.transportStatus === 'failed'
          ? new Date(Date.now() + 60_000)
          : args.transportStatus === 'sending'
            ? new Date(Date.now() + 5 * 60_000)
            : null)
      : null
    await client.query(
      `INSERT INTO email_messages (
        message_id, conversation_id, company_id, direction, transport_status,
        transport_error, smtp_message_id, in_reply_to, references_chain,
        subject, from_addr, to_addrs, cc_addrs, bcc_addrs, html, raw_size_bytes,
        auto_submitted, next_retry_at
     ) VALUES (
        $1, $2, $3, $4, $5,
        $6, $7, $8, $9::jsonb,
        $10, $11, $12::jsonb, $13::jsonb, $14::jsonb, $15, $16,
        $17, $18
     )`,
    [
      messageId, args.conversationId, args.companyId, args.direction, args.transportStatus,
      args.transportError ?? null,
      normalizeMessageId(args.smtpMessageId),
      normalizeMessageId(args.inReplyTo),
      JSON.stringify(args.references.map((r) => normalizeMessageId(r)).filter(Boolean)),
      args.subject.slice(0, 1000),
      args.fromAddr.slice(0, 320),
      JSON.stringify(args.toAddrs.slice(0, 64)),
      JSON.stringify((args.ccAddrs ?? []).slice(0, 64)),
      JSON.stringify((args.bccAddrs ?? []).slice(0, 64)),
      args.html ?? null,
      args.rawSizeBytes ?? null,
      Boolean(args.autoSubmitted),
      initialRetryAt,
      ],
    )
    if (args.attachments?.length) {
      for (const a of args.attachments) {
        const attId = `eatt-${randomUUID().slice(0, 12)}`
        const filename = a.filename.slice(0, 200)
        const mimeType = (a.mimeType || 'application/octet-stream').slice(0, 120)
        const truncated = Boolean(a.truncated)
        if (a.storageKey && !truncated) {
          await grantAttachment(client, args.companyId, a.storageKey)
        }
        await client.query(
          `INSERT INTO email_attachments
           (id, message_id, conversation_id, company_id, filename, mime_type, size_bytes, storage_key, truncated)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
          [
            attId,
            messageId, args.conversationId, args.companyId,
            filename, mimeType, a.sizeBytes,
            a.storageKey, truncated,
          ],
        )
        persistedAttachments.push({
          id: attId, filename, mimeType, sizeBytes: a.sizeBytes,
          storageKey: a.storageKey, truncated,
        })
      }
    }
    await client.query(
      `UPDATE conversations SET updated_at = NOW() WHERE id = $1 AND company_id = $2`,
      [args.conversationId, args.companyId],
    )
    await client.query('COMMIT')
  } catch (error) {
    await client.query('ROLLBACK').catch(() => {})
    throw error
  } finally {
    client.release()
  }
  // Resolve a fresh public URL per attachment for the wake event, mirroring
  // what /conversations/:id/messages does on read. Truncated rows stay
  // url=null. Storage failures degrade to null too — the renderer
  // distinguishes that from a real URL.
  const { storage } = await import('./storage.js')
  const wakeAttachments = await Promise.all(persistedAttachments.map(async (a) => {
    let url: string | null = null
    if (a.storageKey && !a.truncated) {
      try { url = await storage.publicUrl(a.storageKey) } catch { url = null }
    }
    return {
      id: a.id, filename: a.filename, mimeType: a.mimeType, sizeBytes: a.sizeBytes,
      url, truncated: a.truncated,
    }
  }))
  // Wake every member-agent of the conversation. The scheduler dedups
  // across replicas via the wake-claim Redis key.
  await publish(CH_MESSAGE_NEW, {
    type: 'message.new',
    conversationId: args.conversationId,
    companyId: args.companyId,
    message: {
      id: messageId,
      conversationId: args.conversationId,
      authorId: args.authorId,
      kind: 'email',
      body: args.body,
      sequence,
      at: new Date().toISOString(),
      // Mirror what the /messages endpoint emits via JOIN, so a freshly-
      // arrived email bubble in the open chat pane has all the headers
      // it needs without waiting for a /messages refetch on the next view.
      email: {
        subject: args.subject,
        from: args.fromAddr,
        to: args.toAddrs,
        cc: args.ccAddrs ?? [],
        direction: args.direction,
        transportStatus: args.transportStatus,
        transportError: args.transportError ?? null,
        smtpMessageId: normalizeMessageId(args.smtpMessageId),
        inReplyTo: normalizeMessageId(args.inReplyTo),
        hasHtml: Boolean(args.html),
        autoSubmitted: Boolean(args.autoSubmitted),
        attachments: wakeAttachments,
      },
    },
  }).catch((error) => {
    // Persistence is the outbox boundary. A transient Redis outage must not
    // prevent the caller from reaching the provider; clients will refetch the
    // committed row, and a stale `sending` deadline lets the retry worker
    // recover if the process dies before finalizing transport state.
    console.warn(`[email] message publish failed for ${messageId}`, error)
  })
  return { messageId, sequence }
}

/** Find or create the email conversation for a thread. Threading rule:
 *    1. If any in-reply-to / references id matches an existing
 *       email_messages row in this company → reuse that conversation.
 *    2. Else: create a new conversations row (kind='email') with
 *       members = unique([sender, ...recipients]) — the same shape
 *       direct/group conversations use. Title = the subject line
 *       (collapses Re:/Fwd: prefixes for display sanity).
 *
 *  Normalized participant memberships power inbox authorization and wake
 *  fan-out. Synthetic `external:<addr>` author markers are deliberately not
 *  memberships; including the internal sender still makes their own outbox
 *  messages appear in their inbox (matching Gmail's behavior). */
export async function findOrCreateEmailConversation(args: {
  companyId: string
  inReplyTo: string | null
  references: string[]
  subject: string
  /** Participant ids that should be on the conversation. Includes the
   *  sender. Order is preserved for the title fallback ("A ↔ B"). */
  memberIds: string[]
}): Promise<{ conversationId: string; created: boolean }> {
  const concreteMembers = Array.from(new Set(args.memberIds))
    .filter((id) => !id.startsWith('external:'))
    .sort()
  const client = await pool.connect()
  try {
    await client.query('BEGIN')
    if (concreteMembers.length > 0) {
      const active = await client.query<{ id: string }>(
        `SELECT id FROM participants
          WHERE company_id = $1 AND id = ANY($2::text[])
            AND kind IN ('agent', 'human') AND departed_at IS NULL
          ORDER BY id FOR SHARE`,
        [args.companyId, concreteMembers],
      )
      if (active.rows.length !== concreteMembers.length) {
        throw new Error('email conversation contains a foreign or departed participant')
      }
    }

    const candidates = [args.inReplyTo, ...args.references]
      .map((x) => normalizeMessageId(x))
      .filter((x): x is string => Boolean(x))
    const existing = await findEmailConversationByMessageIds(candidates, args.companyId, client)
    if (existing) {
      // Serialize thread repair before checking/inserting normalized rows.
      // The next statement gets a fresh snapshot after any lock wait.
      const locked = await client.query(
        `SELECT id FROM conversations
          WHERE id = $1 AND company_id = $2
          FOR UPDATE`,
        [existing, args.companyId],
      )
      if (!locked.rowCount) throw new Error('email conversation moved or disappeared')
      await client.query(
        `INSERT INTO conversation_members (
           conversation_id, company_id, participant_id, ordinal
         )
         SELECT $1, $3, incoming.participant_id,
                base.next_ordinal + incoming.input_ordinal - 1
           FROM UNNEST($2::text[]) WITH ORDINALITY
                  AS incoming(participant_id, input_ordinal)
           CROSS JOIN LATERAL (
             SELECT COALESCE(MAX(ordinal) + 1, 0)::integer AS next_ordinal
               FROM conversation_members
              WHERE conversation_id = $1 AND company_id = $3
           ) base
         ON CONFLICT (conversation_id, participant_id) DO NOTHING`,
        [existing, concreteMembers, args.companyId],
      )
      await client.query(`SELECT refresh_conversation_members_projection($1)`, [existing])
      await client.query('COMMIT')
      return { conversationId: existing, created: false }
    }

    const cleanSubject = args.subject.replace(/^\s*((re|fwd|fw)\s*:\s*)+/i, '').trim() || '(no subject)'
    const id = `email-${randomUUID().slice(0, 12)}`
    await client.query(
      `INSERT INTO conversations (id, kind, title, members, company_id, topic)
       VALUES ($1, 'email', $2, $3::jsonb, $4, $5)`,
      [id, cleanSubject.slice(0, 200), JSON.stringify(concreteMembers), args.companyId, cleanSubject.slice(0, 200)],
    )
    await client.query('COMMIT')
    return { conversationId: id, created: true }
  } catch (error) {
    await client.query('ROLLBACK').catch(() => {})
    throw error
  } finally {
    client.release()
  }
}

/** Bump (or create) the email_contacts row for an external sender. We
 *  use this to bias the agent's heartbeat prompt toward people they've
 *  actually corresponded with. Cheap and append-only-ish. */
export async function recordExternalContact(args: {
  companyId: string
  address: string
  displayName: string | null
}): Promise<void> {
  const lc = args.address.trim().toLowerCase()
  if (!lc) return
  await pool.query(
    `INSERT INTO email_contacts (company_id, address, display_name, message_count, last_seen_at)
     VALUES ($1, $2, $3, 1, NOW())
     ON CONFLICT (company_id, address) DO UPDATE
       SET message_count = email_contacts.message_count + 1,
           last_seen_at = NOW(),
           display_name = COALESCE(EXCLUDED.display_name, email_contacts.display_name)`,
    [args.companyId, lc, args.displayName ?? null],
  )
}

/** Auto-promote a chat-style reply in an email conversation into a real
 *  email reply. Shared by the HTTP /conversations/:id/messages handler and
 *  the agent CLI's `cumora reply` — both need to detect kind='email'
 *  conversations and route the body through Resend instead of writing a
 *  plain text message that the external recipient never sees.
 *
 *  Builds the reply context from the latest email_messages row in the
 *  conversation: subject (with Re: prefix), In-Reply-To, References,
 *  recipient list (splitReplyAddresses minus self). Sender's From line
 *  uses the caller's cumora-domain address — lazy-minted if it wasn't
 *  there yet, matching the resolver used by /participants. */
export async function replyInEmailConversation(args: {
  conversationId: string
  companyId: string
  authorId: string
  body: string
  /** True when the reply is automation-driven (agent CLI). Stamps the
   *  RFC 3834 Auto-Submitted header so the recipient's vacation responders
   *  and our own loop protection know it's machine-generated. */
  autoSubmitted?: boolean
}): Promise<{ messageId: string; sequence: number; transportStatus: string; mock: boolean; error: string | null }> {
  // Latest email row anchors the reply. Email conversations always have
  // at least one email_messages row (otherwise they wouldn't be kind='email'),
  // so the "no parent" case is a programmer error, not a user-facing path.
  const { rows: parent } = await pool.query<{
    smtp_message_id: string | null
    references_chain: string[]
    subject: string
    from_addr: string
    to_addrs: string[]
    cc_addrs: string[]
  }>(
    `SELECT em.smtp_message_id, em.references_chain, em.subject,
            em.from_addr, em.to_addrs, em.cc_addrs
       FROM email_messages em
      WHERE em.conversation_id = $1
      ORDER BY em.created_at DESC
      LIMIT 1`,
    [args.conversationId],
  )
  const p = parent[0]
  if (!p) {
    throw new Error(`replyInEmailConversation: conversation ${args.conversationId} has no email_messages parent`)
  }

  const sender = await ensureParticipantAddress(args.authorId, args.companyId)
  if (!sender) {
    throw new Error(`replyInEmailConversation: no cumora address for participant ${args.authorId} in ${args.companyId}`)
  }
  // For human authors, ALSO consider their auth email as "self" — the
  // original may have me listed under either my cumora address or my
  // real Gmail. Agents don't have an auth email, query is a no-op.
  const { rows: authUser } = await pool.query<{ email: string | null }>(
    `SELECT email FROM users WHERE id = $1 LIMIT 1`,
    [args.authorId],
  )
  const selfAddrs = [sender.email.toLowerCase()]
  if (authUser[0]?.email) selfAddrs.push(authUser[0].email.toLowerCase())

  // Two cases for the parent row:
  //   (a) Parent is from someone ELSE — reply-all semantics: TO = original
  //       From, CC = original To+Cc minus self.
  //   (b) Parent is from US (we sent the last message; nobody has replied
  //       yet) — splitReplyAddresses would put US in TO and then strip
  //       us out, leaving TO empty. The intent here isn't "reply-all" —
  //       it's "continue the thread to the same people I just addressed".
  //       Use the parent's to_addrs / cc_addrs verbatim (minus self).
  const parentFromParsed = parseAddress(p.from_addr)
  const parentFromIsSelf = parentFromParsed
    ? selfAddrs.includes(parentFromParsed.addr.toLowerCase())
    : false
  let replyTo: string[]
  let replyCc: string[]
  if (parentFromIsSelf) {
    const filterSelf = (addrs: string[]) => addrs.filter((raw) => {
      const p2 = parseAddress(raw)
      return p2 ? !selfAddrs.includes(p2.addr.toLowerCase()) : true
    })
    replyTo = filterSelf(p.to_addrs ?? [])
    replyCc = filterSelf(p.cc_addrs ?? [])
  } else {
    const split = splitReplyAddresses({
      originalFrom: p.from_addr,
      originalTo: p.to_addrs ?? [],
      originalCc: p.cc_addrs ?? [],
      selfAddresses: selfAddrs,
    })
    replyTo = split.to
    replyCc = split.cc
  }
  if (replyTo.length === 0) {
    throw new Error(`replyInEmailConversation: no remaining recipients after self-removal for ${args.conversationId}`)
  }

  const subject = /^(re|fwd|fw)\s*:/i.test(p.subject) ? sanitizeSubject(p.subject) : sanitizeSubject(`Re: ${p.subject}`)
  const newReferences = [...(p.references_chain ?? []), ...(p.smtp_message_id ? [p.smtp_message_id] : [])]
    .filter((x): x is string => Boolean(x))
  const inReplyTo = p.smtp_message_id ? normalizeMessageId(p.smtp_message_id) : null
  const messageId = mintMessageId()
  const fromLine = formatAddress(sender.email, sender.displayName)

  // WRITE-FIRST, then SEND. Previously we sent via Resend FIRST and
  // persisted second — if persist failed after a successful send,
  // the email was delivered to the recipient but no DB row existed,
  // so the next wake would treat the convo as "still un-replied" and
  // send AGAIN. Users got duplicate emails.
  //
  // Now: persist the row as 'sending' BEFORE the network hop. The
  // Message-ID is committed first; if persist fails, no send happens.
  // If send fails after persist, the row stays 'sending' / 'failed'
  // and the email-retry worker picks it up (the existing retry path
  // already handles status='failed' + future next_retry_at). If send
  // succeeds but the post-send UPDATE fails, the retry worker will
  // see status='sending', retry-send with the SAME Message-ID, and
  // Resend dedupes server-side via that header — no duplicate hits
  // the user's inbox.
  const persisted = await persistEmailMessage({
    conversationId: args.conversationId,
    companyId: args.companyId,
    authorId: args.authorId,
    direction: 'out',
    transportStatus: 'sending',
    transportError: null,
    smtpMessageId: messageId,
    inReplyTo,
    references: newReferences,
    subject,
    fromAddr: fromLine,
    toAddrs: replyTo,
    ccAddrs: replyCc,
    body: args.body,
    autoSubmitted: Boolean(args.autoSubmitted),
  })

  const sendRes = await sendViaProvider({
    from: fromLine,
    to: replyTo,
    cc: replyCc.length ? replyCc : undefined,
    subject,
    text: args.body,
    inReplyTo: inReplyTo ?? undefined,
    references: newReferences,
    messageId,
    autoSubmitted: args.autoSubmitted ? 'auto-replied' : undefined,
  })

  // Update the row to its final state. We do NOT throw if this UPDATE
  // fails — the retry worker will fix it on the next tick by reading
  // status='sending' or 'failed' and re-attempting (Resend dedupes by
  // Message-ID). The caller still gets the correct transportStatus
  // returned below.
  const finalStatus = sendRes.ok ? 'sent' : 'failed'
  const finalSmtpId = sendRes.smtpMessageId ?? messageId
  await pool.query(
    `UPDATE email_messages
        SET transport_status = $1,
            transport_error  = $2,
            smtp_message_id  = $3,
            next_retry_at    = $4
      WHERE message_id = $5`,
    [
      finalStatus,
      sendRes.error,
      finalSmtpId,
      // Schedule a retry kick if the send failed; the retry worker
      // owns the rest of the backoff curve.
      finalStatus === 'failed' ? new Date(Date.now() + 60_000) : null,
      persisted.messageId,
    ],
  ).catch((err) => {
    // Row is now in a half-finished state. retry worker will reconcile.
    console.warn(`[email] post-send UPDATE failed for ${persisted.messageId} — leaving for retry worker:`,
      err instanceof Error ? err.message : err)
  })

  return {
    messageId: persisted.messageId,
    sequence: persisted.sequence,
    transportStatus: finalStatus,
    mock: sendRes.mock,
    error: sendRes.error,
  }
}