Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

45.1 KB
Raw Blame
// Agent mail service: provisioning, quotes, metered sends, and the inbox.
//
// Both callers, the v1 REST routes (api/v1/agent-mail.js) and the MCP tools
// (api/_mcp/tools/mail.js), go through this module, so the rules are
// identical however an agent reaches its mailbox:
//
//   • Ownership. Every call names an agent the caller owns; anything else is a
//     404 that does not reveal whether the agent exists.
//   • Quote first. Provisioning and every send are financial. A quote binds the
//     price, the payment source and, for a send, a hash of the exact content.
//     The execute call must cite an unexpired, unconsumed quote and carry the
//     explicit confirm flag; a send whose content differs from what was quoted
//     is refused.
//   • Charge once. The charge is idempotent on the quote id, on both rails:
//     credits (debitCredits) or the agent's own USDC (transferUsdcGuarded, which
//     runs the wallet's spend limits, freeze switch and audit trail). A send the
//     provider rejects is refunded to credits.
//   • Conduct. Outbound content passes checkOutboundContent, recipients are
//     validated, and a warm-up throttle bounds a new mailbox's volume.
//   • Owner controls. The agent's recipient allowlist and daily send cap
//     (./controls.js) are checked on the quote and again on the confirmed send.
//   • Routing. Recipients on the agents domain are delivered internally
//     (./inbound.js deliverLocal); everyone else goes through the provider.

import { createHash } from 'node:crypto';
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { sql } from '../db.js';
import { env } from '../env.js';
import { r2, putObject } from '../r2.js';
import { debitCredits, getCreditAccount, refundCredits } from '../credits.js';
import { transferUsdcGuarded } from '../agent-usdc-transfer.js';
import { getSolanaAddressBalances } from '../agent-wallet.js';
import { currentSignatureFor } from '../real-funds-agreement.js';
import { fetchSafePublicUrlPinned } from '../ssrf-guard.js';
import { logAudit } from '../audit.js';
import {
	mailDomain,
	mailPricing,
	warmupLimits,
	QUOTE_TTL_MS,
	RESERVED_LOCAL_PARTS,
	MAX_RECIPIENTS,
	MAX_ATTACHMENTS,
	MAX_ATTACHMENT_BYTES,
	MAX_TOTAL_ATTACHMENT_BYTES,
	MAX_TEXT_CHARS,
	MAX_HTML_CHARS,
} from './config.js';
import { checkOutboundContent } from './content-rules.js';
import { isValidAddress, isValidLocalPart, localPartFrom, replyHeaders, replySubject } from './threading.js';
import { mailProvider, ProviderError } from './provider.js';
import { loadPolicy, savePolicy, blockedRecipients, PolicyInputError, MAX_ALLOWLIST_ENTRIES, MAX_DAILY_SEND_CAP } from './controls.js';
import { deliverLocal, localMailboxes } from './inbound.js';
import * as rules from './rules.js';

export class MailError extends Error {
	constructor(status, code, message, details = null) {
		super(message);
		this.status = status;
		this.code = code;
		this.details = details;
	}
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

function usd(n) {
	return Math.round(Number(n) * 1e6) / 1e6;
}

function hashPayload(obj) {
	return createHash('sha256').update(JSON.stringify(obj)).digest('hex');
}

// ── ownership ────────────────────────────────────────────────────────────────

export async function loadOwnedAgent(agentId, userId) {
	if (!UUID_RE.test(String(agentId || ''))) throw new MailError(404, 'agent_not_found', 'No agent with that id is on your account.');
	const [row] = await sql`
		select id, user_id, name, meta
		from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!row || row.user_id !== userId) throw new MailError(404, 'agent_not_found', 'No agent with that id is on your account.');
	return row;
}

export async function activeMailbox(agentId) {
	const [row] = await sql`
		select * from agent_mailboxes where agent_id = ${agentId} and status = 'active' limit 1
	`;
	return row || null;
}

async function outboundCounts(mailboxId) {
	const [row] = await sql`
		select
			count(*) filter (where created_at > now() - interval '1 hour')::int as last_hour,
			count(*) filter (where created_at > now() - interval '1 day')::int  as last_day
		from agent_mail_sends
		where mailbox_id = ${mailboxId} and kind = 'send'
		  and status not in ('charge_failed', 'refunded')
	`;
	return { lastHour: row?.last_hour ?? 0, lastDay: row?.last_day ?? 0 };
}

export async function mailboxView(mb) {
	if (!mb) return null;
	const limits = warmupLimits(mb.created_at);
	const [counts, [unread]] = await Promise.all([
		outboundCounts(mb.id),
		sql`
			select count(*)::int as n from agent_mail_messages
			where mailbox_id = ${mb.id} and direction = 'in' and read_at is null and deleted_at is null
			  and coalesce(spam_score, 0) < 6
		`,
	]);
	return {
		id: mb.id,
		address: mb.address,
		display_name: mb.display_name,
		status: mb.status,
		created_at: mb.created_at,
		unread: unread?.n ?? 0,
		limits: {
			per_hour: limits.perHour,
			per_day: limits.perDay,
			warming_up: limits.warming,
			sent_last_hour: counts.lastHour,
			sent_last_day: counts.lastDay,
		},
	};
}

// ── payment source ───────────────────────────────────────────────────────────

async function fundingView(userId, agent) {
	const credits = await getCreditAccount(userId).catch(() => ({ balanceUsd: 0 }));
	const address = agent.meta?.solana_address || null;
	let walletUsdc = null;
	if (address) {
		const b = await getSolanaAddressBalances(address, 'mainnet').catch(() => null);
		walletUsdc = b?.usdc != null ? Number(b.usdc) : null;
	}
	return {
		credits_usd: usd(credits.balanceUsd),
		wallet_address: address,
		wallet_usdc: walletUsdc,
		wallet_payable: Boolean(address && agent.meta?.encrypted_solana_secret && env.X402_PAY_TO_SOLANA),
	};
}

function choosePaymentSource(requested, price, funding) {
	const creditsOk = funding.credits_usd >= price;
	const walletOk = funding.wallet_payable && (funding.wallet_usdc ?? 0) >= price;
	if (requested === 'credits') {
		if (!creditsOk) throw new MailError(402, 'insufficient_credits', `This costs $${price} and your credit balance is $${funding.credits_usd}. Top up at /credits or pay from the agent wallet.`, { funding, price_usd: price });
		return 'credits';
	}
	if (requested === 'wallet') {
		if (!funding.wallet_payable) throw new MailError(409, 'wallet_unavailable', 'This agent has no custodial Solana wallet that can pay. Provision one, or pay with credits.', { funding });
		if (!walletOk) throw new MailError(402, 'insufficient_wallet_usdc', `This costs $${price} USDC and the agent wallet holds ${funding.wallet_usdc ?? 0} USDC.`, { funding, price_usd: price });
		return 'wallet';
	}
	if (creditsOk) return 'credits';
	if (walletOk) return 'wallet';
	throw new MailError(402, 'insufficient_funds', `This costs $${price}. Add credits at /credits or fund the agent wallet with USDC.`, { funding, price_usd: price });
}

// ── quotes ───────────────────────────────────────────────────────────────────

async function insertQuote({ userId, agentId, kind, price, source, payload }) {
	const expiresAt = new Date(Date.now() + QUOTE_TTL_MS);
	const [row] = await sql`
		insert into agent_mail_quotes (user_id, agent_id, kind, price_usd, payment_source, payload_hash, payload, expires_at)
		values (${userId}, ${agentId}, ${kind}, ${String(price)}, ${source}, ${hashPayload(payload)},
		        ${JSON.stringify(payload)}::jsonb, ${expiresAt.toISOString()})
		returning id, expires_at
	`;
	return row;
}

/**
 * Atomically consume a quote. Refuses a missing, foreign, stale, used or
 * mismatched quote with an error that names the preview tool to call again.
 */
async function consumeQuote({ quoteId, userId, agentId, kind, payload }) {
	const redo = kind === 'create' ? 'agent_mail_quote with action "create"' : 'agent_mail_quote with action "send"';
	if (!UUID_RE.test(String(quoteId || ''))) {
		throw new MailError(400, 'quote_required', `Call ${redo} first and pass its quote_id.`);
	}
	const [q] = await sql`select * from agent_mail_quotes where id = ${quoteId} limit 1`;
	if (!q || q.user_id !== userId || q.agent_id !== agentId || q.kind !== kind) {
		throw new MailError(400, 'quote_invalid', `That quote does not belong to this ${kind}. Call ${redo} again.`);
	}
	if (q.consumed_at) throw new MailError(409, 'quote_used', `That quote was already used. Call ${redo} for a new one.`);
	if (new Date(q.expires_at).getTime() < Date.now()) {
		throw new MailError(410, 'quote_expired', `That quote expired (quotes last 10 minutes). Call ${redo} again.`);
	}
	if (payload && q.payload_hash !== hashPayload(payload)) {
		throw new MailError(409, 'quote_mismatch', `The ${kind === 'send' ? 'message' : 'request'} differs from what was quoted. Call ${redo} with the final content.`);
	}
	const [claimed] = await sql`
		update agent_mail_quotes set consumed_at = now()
		where id = ${quoteId} and consumed_at is null
		returning id
	`;
	if (!claimed) throw new MailError(409, 'quote_used', `That quote was already used. Call ${redo} for a new one.`);
	return { ...q, price_usd: Number(q.price_usd) };
}

async function requireAgreementForWallet(userId) {
	const sig = await currentSignatureFor(userId).catch(() => {
		throw new MailError(503, 'agreement_check_unavailable', 'Could not verify your signed real-funds agreements, so nothing was charged. Try again in a moment.');
	});
	if (!sig) {
		throw new MailError(403, 'risk_ack_required', 'Sign the real-funds agreements at /legal/sign before paying from the agent wallet, or pay with credits.');
	}
}

// ── charging ─────────────────────────────────────────────────────────────────

async function charge({ quote, agent, userId, kind }) {
	const idempotencyKey = `agent-mail:${quote.id}`;
	if (quote.payment_source === 'credits') {
		const debit = await debitCredits({
			userId,
			amountUsd: quote.price_usd,
			action: `agent_mail.${kind}`,
			refType: 'agent_mail_quote',
			refId: quote.id,
			idempotencyKey,
			meta: { agent_id: agent.id },
		});
		return { creditLedgerId: debit.ledgerId, signature: null };
	}
	await requireAgreementForWallet(userId);
	const paid = await transferUsdcGuarded({
		fromAgentId: agent.id,
		fromUserId: userId,
		fromMeta: agent.meta || {},
		toAddress: env.X402_PAY_TO_SOLANA,
		usdc: quote.price_usd,
		network: 'mainnet',
		category: 'x402',
		idempotencyKey,
		rowMeta: { purpose: 'agent_mail', kind, quote_id: quote.id },
	});
	if (paid.status === 'paid' || paid.status === 'replayed') return { creditLedgerId: null, signature: paid.signature };
	if (paid.status === 'blocked') {
		throw new MailError(403, paid.code || 'spend_blocked', paid.message || 'The agent wallet spend policy blocked this payment.');
	}
	throw new MailError(402, paid.code || 'wallet_payment_failed', `The USDC payment from the agent wallet did not settle (${paid.code || 'failed'}). Nothing was sent.`);
}

// A failed delivery is made whole in credits on either rail: credits come back
// as credits, and a settled USDC payment is refunded as the same USD in credits.
async function refund({ quote, userId, kind, reason }) {
	await refundCredits({
		userId,
		amountUsd: quote.price_usd,
		action: `agent_mail.${kind}.refund`,
		refType: 'agent_mail_quote',
		refId: quote.id,
		idempotencyKey: `agent-mail-refund:${quote.id}`,
		meta: { reason, paid_with: quote.payment_source },
	});
}

async function recordSend(fields) {
	const [row] = await sql`
		insert into agent_mail_sends
			(mailbox_id, agent_id, user_id, kind, quote_id, cost_usd, payment_source, status)
		values (${fields.mailboxId}, ${fields.agentId}, ${fields.userId}, ${fields.kind}, ${fields.quoteId},
		        ${String(fields.cost)}, ${fields.source}, 'charging')
		returning id
	`;
	return row.id;
}

async function updateSend(id, patch) {
	await sql`
		update agent_mail_sends set
			status = coalesce(${patch.status ?? null}, status),
			mailbox_id = coalesce(${patch.mailboxId ?? null}::uuid, mailbox_id),
			credit_ledger_id = coalesce(${patch.creditLedgerId ?? null}::uuid, credit_ledger_id),
			signature = coalesce(${patch.signature ?? null}, signature),
			provider = coalesce(${patch.provider ?? null}, provider),
			provider_id = coalesce(${patch.providerId ?? null}, provider_id),
			message_row_id = coalesce(${patch.messageRowId ?? null}::uuid, message_row_id),
			error_code = ${patch.errorCode ?? null},
			error_message = ${patch.errorMessage ?? null},
			updated_at = now()
		where id = ${id}
	`;
}

// ── provisioning ─────────────────────────────────────────────────────────────

async function pickLocalPart(agent, requested) {
	if (requested != null && requested !== '') {
		const lp = String(requested).trim().toLowerCase();
		if (!isValidLocalPart(lp)) {
			throw new MailError(400, 'invalid_local_part', 'Use 3 to 32 lowercase letters, digits, dots or hyphens, starting and ending with a letter or digit.');
		}
		if (RESERVED_LOCAL_PARTS.has(lp)) throw new MailError(409, 'local_part_reserved', `"${lp}" is a reserved role address. Pick another.`);
		const [taken] = await sql`select 1 from agent_mailboxes where local_part = ${lp} and domain = ${mailDomain()} limit 1`;
		if (taken) throw new MailError(409, 'address_taken', `${lp}@${mailDomain()} is taken. Pick another.`);
		return lp;
	}
	const base = localPartFrom(agent.name) || `agent-${String(agent.id).slice(0, 8)}`;
	const stem = RESERVED_LOCAL_PARTS.has(base) ? `${base}-agent` : base;
	for (let i = 0; i < 20; i++) {
		const candidate = i === 0 ? stem : `${stem.slice(0, 28)}-${i + 1}`;
		const [taken] = await sql`select 1 from agent_mailboxes where local_part = ${candidate} and domain = ${mailDomain()} limit 1`;
		if (!taken) return candidate;
	}
	return `${stem.slice(0, 22)}-${String(agent.id).slice(0, 8)}`;
}

function cleanDisplayName(name, agent) {
	const s = String(name ?? agent.name ?? '').replace(/[<>"\r\n]/g, '').trim().slice(0, 64);
	return s || null;
}

export async function quoteCreate({ userId, agentId, localPart, displayName, paymentSource }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const existing = await activeMailbox(agent.id);
	if (existing) {
		throw new MailError(409, 'mailbox_exists', `This agent already has ${existing.address}.`, { address: existing.address });
	}
	const lp = await pickLocalPart(agent, localPart);
	const pricing = await mailPricing();
	const price = pricing.create_usd;
	const funding = await fundingView(userId, agent);
	const source = choosePaymentSource(paymentSource, price, funding);
	const payload = { local_part: lp, display_name: cleanDisplayName(displayName, agent) };
	const q = await insertQuote({ userId, agentId: agent.id, kind: 'create', price, source, payload });
	return {
		quote_id: q.id,
		action: 'create',
		price_usd: price,
		payment_source: source,
		expires_at: q.expires_at,
		address: `${lp}@${mailDomain()}`,
		display_name: payload.display_name,
		funding,
		confirm_with: { tool: 'agent_mail_create', flag: 'confirm_spend', quote_id: q.id },
	};
}

export async function createMailbox({ userId, agentId, quoteId, confirm }) {
	if (confirm !== true) {
		throw new MailError(400, 'confirm_required', 'Provisioning charges the account. Show the quote to the user, then call again with confirm_spend: true.');
	}
	const agent = await loadOwnedAgent(agentId, userId);
	const quote = await consumeQuote({ quoteId, userId, agentId: agent.id, kind: 'create' });
	const { local_part: lp, display_name: displayName } = quote.payload || {};
	const domain = mailDomain();
	const sendId = await recordSend({ mailboxId: null, agentId: agent.id, userId, kind: 'create', quoteId: quote.id, cost: quote.price_usd, source: quote.payment_source });

	let paid;
	try {
		paid = await charge({ quote, agent, userId, kind: 'create' });
	} catch (err) {
		await updateSend(sendId, { status: 'charge_failed', errorCode: err.code || 'charge_failed', errorMessage: err.message });
		throw err;
	}

	let mb;
	try {
		[mb] = await sql`
			insert into agent_mailboxes (agent_id, user_id, address, local_part, domain, display_name)
			values (${agent.id}, ${userId}, ${`${lp}@${domain}`}, ${lp}, ${domain}, ${displayName})
			returning *
		`;
	} catch (err) {
		await refund({ quote, userId, kind: 'create', reason: 'address_conflict' });
		await updateSend(sendId, { status: 'refunded', errorCode: 'address_conflict', errorMessage: err.message, ...paid });
		throw new MailError(409, 'address_taken', `${lp}@${domain} was claimed a moment ago. You were refunded in credits; quote again.`);
	}
	await updateSend(sendId, { status: 'provisioned', mailboxId: mb.id, creditLedgerId: paid.creditLedgerId, signature: paid.signature });
	logAudit({ userId, action: 'agent_mail.create', resourceId: agent.id, meta: { address: mb.address, paid_with: quote.payment_source, cost_usd: quote.price_usd } });
	return { mailbox: await mailboxView(mb), charge: { cost_usd: quote.price_usd, payment_source: quote.payment_source, signature: paid.signature, credit_ledger_id: paid.creditLedgerId } };
}

// ── drafting and sending ─────────────────────────────────────────────────────

function asList(v) {
	if (v == null || v === '') return [];
	return (Array.isArray(v) ? v : String(v).split(',')).map((s) => String(s).trim().toLowerCase()).filter(Boolean);
}

/**
 * Validate and canonicalize a draft. The canonical form is what gets hashed
 * into the quote, so the confirmed send is byte-for-byte what was previewed.
 */
async function canonicalDraft(mb, draft) {
	const to = [...new Set(asList(draft.to))];
	const cc = [...new Set(asList(draft.cc))].filter((a) => !to.includes(a));
	if (!to.length) throw new MailError(400, 'recipient_required', 'Name at least one recipient in "to".');
	if (to.length + cc.length > MAX_RECIPIENTS) throw new MailError(400, 'too_many_recipients', `At most ${MAX_RECIPIENTS} recipients per message.`);
	const bad = [...to, ...cc].filter((a) => !isValidAddress(a));
	if (bad.length) throw new MailError(400, 'invalid_recipient', `Not a valid email address: ${bad.join(', ')}.`, { invalid: bad });
	if ([...to, ...cc].includes(mb.address)) throw new MailError(400, 'self_send', 'An agent cannot email its own address.');

	let parent = null;
	if (draft.in_reply_to) {
		if (!UUID_RE.test(String(draft.in_reply_to))) throw new MailError(400, 'invalid_reply', 'in_reply_to must be the id of a message in this mailbox.');
		[parent] = await sql`
			select id, thread_id, message_id, references_ids, subject from agent_mail_messages
			where id = ${draft.in_reply_to} and mailbox_id = ${mb.id} and deleted_at is null limit 1
		`;
		if (!parent) throw new MailError(404, 'reply_target_not_found', 'The message you are replying to is not in this mailbox.');
	}

	const subject = String(draft.subject ?? (parent ? replySubject(parent.subject) : '')).trim();
	const text = String(draft.text ?? '').trim();
	const html = draft.html ? String(draft.html) : null;
	if (text.length > MAX_TEXT_CHARS) throw new MailError(400, 'text_too_long', `The text body is over ${MAX_TEXT_CHARS} characters.`);
	if (html && html.length > MAX_HTML_CHARS) throw new MailError(400, 'html_too_long', `The HTML body is over ${MAX_HTML_CHARS} characters.`);
	if (!text) throw new MailError(400, 'text_required', 'Every message needs a plain-text body (html is optional and additional).');

	const verdict = checkOutboundContent({ subject, text, html, isReply: Boolean(parent) });
	if (!verdict.ok) {
		throw new MailError(422, 'content_rejected', verdict.violations.map((v) => v.message).join(' '), { violations: verdict.violations });
	}

	const attachments = Array.isArray(draft.attachments) ? draft.attachments : [];
	if (attachments.length > MAX_ATTACHMENTS) throw new MailError(400, 'too_many_attachments', `At most ${MAX_ATTACHMENTS} attachments per message.`);
	const atts = attachments.map((a, i) => {
		const url = String(a?.url || '').trim();
		let parsed;
		try { parsed = new URL(url); } catch { throw new MailError(400, 'invalid_attachment', `Attachment ${i + 1} needs a public https url.`); }
		if (parsed.protocol !== 'https:') throw new MailError(400, 'invalid_attachment', `Attachment ${i + 1} must be served over https.`);
		const filename = String(a?.filename || decodeURIComponent(parsed.pathname.split('/').pop() || '') || `attachment-${i + 1}`)
			.replace(/[\\/\r\n"]/g, '_')
			.slice(0, 120);
		return { url, filename };
	});

	return {
		canonical: { to, cc, subject, text, html, attachments: atts, in_reply_to: parent?.id || null },
		parent,
		routing: await routeRecipients([...to, ...cc]),
	};
}

/**
 * Split recipients into agent mailboxes on the agents domain (delivered
 * internally) and everyone else (delivered by the provider). An address on the
 * agents domain that no active mailbox holds is refused before any charge.
 */
async function routeRecipients(all) {
	const domain = `@${mailDomain()}`;
	const onDomain = all.filter((a) => a.endsWith(domain));
	const held = new Set((await localMailboxes(onDomain)).map((m) => m.address));
	const unknown = onDomain.filter((a) => !held.has(a));
	if (unknown.length) {
		throw new MailError(404, 'unknown_agent_address', `No agent mailbox exists at ${unknown.join(', ')}.`, { unknown });
	}
	return { local: onDomain, external: all.filter((a) => !a.endsWith(domain)) };
}

/**
 * Every limit a send must pass, checked on the quote and again on the send:
 * the owner's allowlist and daily cap, then the platform warm-up throttle.
 */
async function assertSendAllowed(mb, canonical) {
	const policy = await loadPolicy(mb.agent_id);
	const blocked = blockedRecipients(policy, [...canonical.to, ...canonical.cc]);
	if (blocked.length) {
		throw new MailError(403, 'recipient_not_allowed', `This agent may only email its owner's allowlist, and ${blocked.join(', ')} ${blocked.length === 1 ? 'is' : 'are'} not on it. The owner can add ${blocked.length === 1 ? 'it' : 'them'} on the agent's mail page.`, { blocked, allowlist: policy.allowlist });
	}
	const throttle = await assertThrottle(mb);
	if (policy.daily_send_cap != null && throttle.counts.lastDay >= policy.daily_send_cap) {
		throw new MailError(429, 'daily_send_cap', `This agent reached the owner's cap of ${policy.daily_send_cap} sends per 24 hours. The owner can raise it on the agent's mail page.`, { daily_send_cap: policy.daily_send_cap, sent_last_day: throttle.counts.lastDay });
	}
	return { ...throttle, policy };
}

async function assertThrottle(mb) {
	const limits = warmupLimits(mb.created_at);
	const counts = await outboundCounts(mb.id);
	if (counts.lastHour >= limits.perHour) {
		throw new MailError(429, 'mailbox_hourly_limit', `This mailbox sent ${counts.lastHour} messages in the last hour, its limit${limits.warming ? ' while warming up' : ''}. Try again later.`, { limits, counts });
	}
	if (counts.lastDay >= limits.perDay) {
		throw new MailError(429, 'mailbox_daily_limit', `This mailbox reached its ${limits.perDay} messages per day limit${limits.warming ? ' while warming up' : ''}.`, { limits, counts });
	}
	return { limits, counts };
}

async function requireMailbox(agent) {
	const mb = await activeMailbox(agent.id);
	if (!mb) throw new MailError(404, 'no_mailbox', 'This agent has no mailbox yet. Quote one with agent_mail_quote (action "create").');
	return mb;
}

export async function quoteSend({ userId, agentId, draft, paymentSource }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const { canonical, routing } = await canonicalDraft(mb, draft || {});
	const throttle = await assertSendAllowed(mb, canonical);
	const pricing = await mailPricing();
	const price = pricing.send_usd;
	const funding = await fundingView(userId, agent);
	const source = choosePaymentSource(paymentSource, price, funding);
	const q = await insertQuote({ userId, agentId: agent.id, kind: 'send', price, source, payload: canonical });
	return {
		quote_id: q.id,
		action: 'send',
		price_usd: price,
		payment_source: source,
		expires_at: q.expires_at,
		preview: {
			from: fromHeader(mb),
			to: canonical.to,
			cc: canonical.cc,
			subject: canonical.subject,
			text: canonical.text,
			has_html: Boolean(canonical.html),
			attachments: canonical.attachments,
			in_reply_to: canonical.in_reply_to,
		},
		delivery: { agent_mailboxes: routing.local, external: routing.external },
		limits: {
			per_hour: throttle.limits.perHour,
			per_day: throttle.limits.perDay,
			sent_last_hour: throttle.counts.lastHour,
			sent_last_day: throttle.counts.lastDay,
			owner_daily_cap: throttle.policy.daily_send_cap,
			allowlist_enabled: throttle.policy.allowlist_enabled,
		},
		funding,
		confirm_with: { tool: 'agent_mail_send', flag: 'confirm_send', quote_id: q.id },
	};
}

function fromHeader(mb) {
	return mb.display_name ? `"${mb.display_name}" <${mb.address}>` : mb.address;
}

async function fetchAttachments(list) {
	const out = [];
	let total = 0;
	for (const [i, a] of list.entries()) {
		let res;
		try {
			res = await fetchSafePublicUrlPinned(a.url, { signal: AbortSignal.timeout(20_000) }, { maxBytes: MAX_ATTACHMENT_BYTES });
		} catch (err) {
			throw new MailError(422, 'attachment_fetch_failed', `Attachment ${i + 1} (${a.filename}) could not be fetched: ${err?.message || 'blocked'}.`);
		}
		if (!res.ok) throw new MailError(422, 'attachment_fetch_failed', `Attachment ${i + 1} (${a.filename}) answered HTTP ${res.status}.`);
		const buf = Buffer.from(await res.arrayBuffer());
		total += buf.length;
		if (total > MAX_TOTAL_ATTACHMENT_BYTES) throw new MailError(413, 'attachments_too_large', `Attachments total over ${MAX_TOTAL_ATTACHMENT_BYTES / 1024 / 1024} MB.`);
		out.push({ filename: a.filename, content: buf, contentType: res.headers.get('content-type') || 'application/octet-stream', size: buf.length });
	}
	return out;
}

export async function sendMail({ userId, agentId, quoteId, draft, confirm }) {
	if (confirm !== true) {
		throw new MailError(400, 'confirm_required', 'Sending is outward-facing and metered. Show the quote preview to the user, then call again with confirm_send: true.');
	}
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const { canonical, parent, routing } = await canonicalDraft(mb, draft || {});
	await assertSendAllowed(mb, canonical);
	const quote = await consumeQuote({ quoteId, userId, agentId: agent.id, kind: 'send', payload: canonical });

	// Fetch attachments before charging, so an unreachable file costs nothing.
	const files = await fetchAttachments(canonical.attachments);

	const sendId = await recordSend({ mailboxId: mb.id, agentId: agent.id, userId, kind: 'send', quoteId: quote.id, cost: quote.price_usd, source: quote.payment_source });
	let paid;
	try {
		paid = await charge({ quote, agent, userId, kind: 'send' });
	} catch (err) {
		await updateSend(sendId, { status: 'charge_failed', errorCode: err.code || 'charge_failed', errorMessage: err.message });
		throw err;
	}
	await updateSend(sendId, { status: 'sending', creditLedgerId: paid.creditLedgerId, signature: paid.signature });

	const domain = mailDomain();
	const messageId = `${quote.id}@${domain}`;
	const headers = { 'Message-ID': `<${messageId}>`, ...(parent ? replyHeaders(parent) : {}) };
	const externalTo = canonical.to.filter((a) => routing.external.includes(a));
	const externalCc = canonical.cc.filter((a) => routing.external.includes(a));
	const goesExternal = externalTo.length + externalCc.length > 0;

	// Provider leg: only the recipients outside the agents domain. A message
	// whose "to" is all agents but whose cc is external promotes the cc.
	let provider = null;
	let sent = { id: `local:${quote.id}` };
	if (goesExternal) {
		provider = mailProvider();
		try {
			sent = await provider.send({
				from: fromHeader(mb),
				to: externalTo.length ? externalTo : externalCc,
				cc: externalTo.length ? externalCc : [],
				subject: canonical.subject,
				text: canonical.text,
				html: canonical.html,
				headers,
				attachments: files,
				idempotencyKey: `agent-mail-send:${quote.id}`,
			});
		} catch (err) {
			const code = err instanceof ProviderError ? err.code : 'provider_error';
			await refund({ quote, userId, kind: 'send', reason: code });
			await updateSend(sendId, { status: 'refunded', provider: provider.name, errorCode: code, errorMessage: err.message });
			throw new MailError(502, 'send_failed', `The mail provider did not accept the message (${err.message}). You were refunded $${quote.price_usd} in credits; fix the issue and retry.`, { provider_code: code, retryable: Boolean(err.retryable) });
		}
	}
	const providerName = provider ? provider.name : 'local';

	const stored = await storeOutboundAttachments({ mailboxId: mb.id, quoteId: quote.id, files });
	const references = parent ? [...(parent.references_ids || []), parent.message_id].filter(Boolean).slice(-20) : [];
	const [msg] = await sql`
		insert into agent_mail_messages
			(mailbox_id, direction, thread_id, from_address, from_name, to_addresses, cc_addresses, subject,
			 text_body, html_body, attachments, message_id, in_reply_to, references_ids, provider,
			 provider_message_id, read_at, delivery_status)
		values
			(${mb.id}, 'out', ${parent?.thread_id || quote.id}, ${mb.address}, ${mb.display_name}, ${canonical.to}, ${canonical.cc},
			 ${canonical.subject}, ${canonical.text}, ${canonical.html}, ${JSON.stringify(stored)}::jsonb,
			 ${messageId}, ${parent?.message_id || null}, ${references}, ${providerName}, ${sent.id}, now(),
			 ${goesExternal ? 'sent' : 'delivered'})
		returning *
	`;

	// Local leg: agent mailboxes on the agents domain get their copy directly.
	let delivered = [];
	if (routing.local.length) {
		try {
			delivered = await deliverLocal({ fromMailbox: mb, sent: msg, recipients: routing.local });
		} catch (err) {
			if (!goesExternal) {
				await refund({ quote, userId, kind: 'send', reason: 'local_delivery_failed' });
				await sql`update agent_mail_messages set delivery_status = 'failed' where id = ${msg.id}`;
				await updateSend(sendId, { status: 'refunded', provider: providerName, providerId: sent.id, messageRowId: msg.id, errorCode: 'local_delivery_failed', errorMessage: err.message });
				throw new MailError(502, 'send_failed', `The message could not be delivered to ${routing.local.join(', ')}. You were refunded $${quote.price_usd} in credits; try again.`);
			}
			console.error('[agent-mail] local leg failed after provider send:', err.message);
		}
	}

	await updateSend(sendId, { status: goesExternal ? 'sent' : 'delivered', provider: providerName, providerId: sent.id, messageRowId: msg.id });
	logAudit({ userId, action: 'agent_mail.send', resourceId: agent.id, meta: { to: canonical.to, cc: canonical.cc, message_id: msg.id, local: routing.local, paid_with: quote.payment_source, cost_usd: quote.price_usd } });
	return {
		message: { id: msg.id, thread_id: msg.thread_id, created_at: msg.created_at, status: goesExternal ? 'sent' : 'delivered', provider_id: sent.id },
		delivered_to_agents: delivered.map((d) => d.mailbox),
		charge: { cost_usd: quote.price_usd, payment_source: quote.payment_source, signature: paid.signature, credit_ledger_id: paid.creditLedgerId },
	};
}

/**
 * Keep a copy of every sent attachment so the sender (and any agent mailbox
 * that received it locally) can download it later. Same key scheme and
 * download path as inbound attachments.
 */
async function storeOutboundAttachments({ mailboxId, quoteId, files }) {
	const out = [];
	for (const [i, f] of files.entries()) {
		const base = { filename: f.filename, size: f.size, content_type: f.contentType };
		const safe = String(f.filename || `attachment-${i + 1}`).replace(/[^\w.\- ]+/g, '_').slice(0, 120);
		const key = `agent-mail/${mailboxId}/out-${quoteId}/${i}-${safe}`;
		try {
			await putObject({ key, body: f.content, contentType: 'application/octet-stream', metadata: { 'original-type': String(f.contentType).slice(0, 100) } });
			out.push({ ...base, key });
		} catch (err) {
			out.push({ ...base, skipped_reason: `Sent, but no copy was kept: ${String(err?.message || 'storage failed').slice(0, 160)}` });
		}
	}
	return out;
}

// ── replies ──────────────────────────────────────────────────────────────────

/**
 * The draft a reply to `messageId` sends. Deterministic from the stored
 * message, so the quote and the confirmed send hash the same content.
 * Replying to a received message answers its Reply-To (or sender); replying to
 * one of the agent's own sent messages follows up with the same recipients.
 */
async function replyDraft(mb, { messageId, text, html, replyAll, attachments }) {
	const parent = await loadMessage(mb, messageId);
	let to;
	let cc = [];
	if (parent.direction === 'in') {
		to = [(parent.reply_to && parent.reply_to[0]) || parent.from_address];
		if (replyAll) cc = [...(parent.to_addresses || []), ...(parent.cc_addresses || [])];
	} else {
		to = parent.to_addresses || [];
		if (replyAll) cc = parent.cc_addresses || [];
	}
	cc = cc.filter((a) => a !== mb.address && !to.includes(a));
	return { to, cc, text, html, attachments, in_reply_to: parent.id };
}

export async function quoteReply({ userId, agentId, messageId, text, html, replyAll = false, attachments, paymentSource }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const draft = await replyDraft(mb, { messageId, text, html, replyAll, attachments });
	const quote = await quoteSend({ userId, agentId, draft, paymentSource });
	return { ...quote, reply_to_message: messageId, confirm_with: { tool: 'agent_mail_reply', flag: 'confirm_send', quote_id: quote.quote_id } };
}

export async function sendReply({ userId, agentId, messageId, text, html, replyAll = false, attachments, quoteId, confirm }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const draft = await replyDraft(mb, { messageId, text, html, replyAll, attachments });
	return sendMail({ userId, agentId, quoteId, draft, confirm });
}

// ── inbox reads ──────────────────────────────────────────────────────────────

function summaryRow(r) {
	return {
		id: r.id,
		direction: r.direction,
		thread_id: r.thread_id,
		from: r.from_address,
		from_name: r.from_name,
		to: r.to_addresses,
		cc: r.cc_addresses,
		subject: r.subject,
		snippet: String(r.text_body || '').replace(/\s+/g, ' ').trim().slice(0, 180),
		attachment_count: Array.isArray(r.attachments) ? r.attachments.length : 0,
		read: Boolean(r.read_at),
		spam: r.spam_score != null && Number(r.spam_score) >= 6,
		spam_score: r.spam_score != null ? Number(r.spam_score) : null,
		delivery_status: r.delivery_status,
		created_at: r.created_at,
	};
}

export async function getMailboxForAgent({ userId, agentId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await activeMailbox(agent.id);
	const pricing = await mailPricing();
	return { agent: { id: agent.id, name: agent.name }, mailbox: await mailboxView(mb), pricing, domain: mailDomain() };
}

/**
 * List messages newest first. Cursor is the id of the last row of the previous
 * page. folder: inbox (received, not spam) | sent | spam | all.
 */
export async function listMessages({ userId, agentId, folder = 'inbox', unread = false, q = '', limit = 25, cursor = null }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const cap = Math.min(Math.max(Number(limit) || 25, 1), 100);
	const f = ['inbox', 'sent', 'spam', 'all'].includes(folder) ? folder : 'inbox';
	const search = String(q || '').trim().slice(0, 120);
	const pattern = search ? `%${search.replace(/[\\%_]/g, (c) => `\\${c}`)}%` : null;

	let beforeTs = null;
	let beforeId = null;
	if (cursor && UUID_RE.test(String(cursor))) {
		const [anchor] = await sql`select created_at from agent_mail_messages where id = ${cursor} and mailbox_id = ${mb.id}`;
		if (anchor) {
			beforeTs = anchor.created_at;
			beforeId = cursor;
		}
	}
	const rows = await sql`
		select id, direction, thread_id, from_address, from_name, to_addresses, cc_addresses, subject,
		       left(text_body, 400) as text_body, attachments, read_at, spam_score, delivery_status, created_at
		from agent_mail_messages
		where mailbox_id = ${mb.id} and deleted_at is null
		  and (${f} = 'all'
		       or (${f} = 'inbox' and direction = 'in' and coalesce(spam_score, 0) < 6)
		       or (${f} = 'spam' and direction = 'in' and coalesce(spam_score, 0) >= 6)
		       or (${f} = 'sent' and direction = 'out'))
		  and (${unread === true} = false or (direction = 'in' and read_at is null))
		  and (${pattern}::text is null
		       or subject ilike ${pattern} or from_address ilike ${pattern} or text_body ilike ${pattern}
		       or array_to_string(to_addresses, ' ') ilike ${pattern})
		  and (${beforeTs}::timestamptz is null
		       or created_at < ${beforeTs}::timestamptz
		       or (created_at = ${beforeTs}::timestamptz and id < ${beforeId}::uuid))
		order by created_at desc, id desc
		limit ${cap + 1}
	`;
	const hasMore = rows.length > cap;
	const items = (hasMore ? rows.slice(0, cap) : rows).map(summaryRow);
	return { items, hasMore, nextCursor: hasMore ? items[items.length - 1].id : null, mailbox: { address: mb.address } };
}

async function loadMessage(mb, messageId) {
	if (!UUID_RE.test(String(messageId || ''))) throw new MailError(404, 'message_not_found', 'No message with that id in this mailbox.');
	const [row] = await sql`
		select * from agent_mail_messages where id = ${messageId} and mailbox_id = ${mb.id} and deleted_at is null limit 1
	`;
	if (!row) throw new MailError(404, 'message_not_found', 'No message with that id in this mailbox.');
	return row;
}

export async function readMessage({ userId, agentId, messageId, markRead = true }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const row = await loadMessage(mb, messageId);
	if (markRead && row.direction === 'in' && !row.read_at) {
		await sql`update agent_mail_messages set read_at = now() where id = ${row.id} and read_at is null`;
		row.read_at = new Date().toISOString();
	}
	const thread = await sql`
		select id, direction, from_address, subject, created_at
		from agent_mail_messages
		where mailbox_id = ${mb.id} and thread_id = ${row.thread_id} and deleted_at is null
		order by created_at asc limit 50
	`;
	let send = null;
	if (row.direction === 'out') {
		[send] = await sql`
			select status, cost_usd, payment_source, signature, error_code, error_message
			from agent_mail_sends where message_row_id = ${row.id} limit 1
		`;
	}
	return {
		...summaryRow(row),
		reply_to: row.reply_to,
		text: row.text_body,
		html: row.html_body,
		message_id: row.message_id,
		in_reply_to: row.in_reply_to,
		attachments: (row.attachments || []).map((a, i) => ({
			index: i,
			filename: a.filename,
			size: a.size,
			content_type: a.content_type,
			stored: Boolean(a.key),
			quarantined: Boolean(a.quarantined),
		})),
		spam_verdict: row.spam_verdict,
		virus_verdict: row.virus_verdict,
		auth_results: row.auth_results,
		send: send ? { ...send, cost_usd: Number(send.cost_usd) } : null,
		thread: thread.map((t) => ({ id: t.id, direction: t.direction, from: t.from_address, subject: t.subject, created_at: t.created_at })),
		untrusted: row.direction === 'in',
	};
}

export async function setRead({ userId, agentId, messageId, read }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const row = await loadMessage(mb, messageId);
	await sql`update agent_mail_messages set read_at = ${read ? new Date().toISOString() : null} where id = ${row.id}`;
	return { id: row.id, read: Boolean(read) };
}

export async function deleteMessage({ userId, agentId, messageId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const row = await loadMessage(mb, messageId);
	await sql`update agent_mail_messages set deleted_at = now() where id = ${row.id}`;
	return { id: row.id, deleted: true };
}

/**
 * A short-lived download URL for one stored attachment, always served with
 * Content-Disposition: attachment and a neutral content type, so a hostile
 * file is saved, never rendered in the browser.
 */
export async function attachmentDownloadUrl({ userId, agentId, messageId, index }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await requireMailbox(agent);
	const row = await loadMessage(mb, messageId);
	const att = (row.attachments || [])[Number(index)];
	if (!att) throw new MailError(404, 'attachment_not_found', 'No attachment at that index.');
	if (att.quarantined) throw new MailError(451, 'attachment_quarantined', 'This attachment was flagged by the malware scan and was not stored.');
	if (!att.key) throw new MailError(404, 'attachment_not_stored', att.skipped_reason || 'This attachment was not stored.');
	const safeName = String(att.filename || 'attachment').replace(/[^\w.\- ]+/g, '_').slice(0, 120);
	const cmd = new GetObjectCommand({
		Bucket: env.S3_BUCKET,
		Key: att.key,
		ResponseContentDisposition: `attachment; filename="${safeName}"`,
		ResponseContentType: 'application/octet-stream',
	});
	const url = await getSignedUrl(r2, cmd, { expiresIn: 300 });
	return { url, filename: att.filename, size: att.size, expires_in: 300 };
}

/**
 * Full-text-ish search across one mailbox (subject, sender, recipients, body).
 * Same rows and paging as listMessages; every folder unless one is named.
 */
export async function searchMessages({ userId, agentId, query, folder = 'all', limit = 25, cursor = null }) {
	const q = String(query || '').trim();
	if (!q) throw new MailError(400, 'query_required', 'Pass a search query: words from the subject or body, or an address.');
	const result = await listMessages({ userId, agentId, folder, q, limit, cursor });
	return { ...result, query: q.slice(0, 120) };
}

// ── owner controls: allowlist, daily cap, mail rules ─────────────────────────

/** Map a controls/rules validation error onto the service's error type. */
function asMailError(err) {
	if (err instanceof MailError) return err;
	if (err instanceof PolicyInputError) return new MailError(400, err.code, err.message, err.details);
	if (err instanceof rules.RuleError) return new MailError(err.status, err.code, err.message, err.details);
	return err;
}

async function guarded(fn) {
	try {
		return await fn();
	} catch (err) {
		throw asMailError(err);
	}
}

/** Everything the owner's mail settings panel shows. */
export async function getMailSettings({ userId, agentId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const mb = await activeMailbox(agent.id);
	const [policy, ruleList] = await Promise.all([loadPolicy(agent.id), rules.listRules(agent.id)]);
	const counts = mb ? await outboundCounts(mb.id) : { lastHour: 0, lastDay: 0 };
	const limits = mb ? warmupLimits(mb.created_at) : null;
	return {
		policy,
		rules: ruleList,
		usage: {
			sent_last_hour: counts.lastHour,
			sent_last_day: counts.lastDay,
			warmup_per_hour: limits?.perHour ?? null,
			warmup_per_day: limits?.perDay ?? null,
		},
		limits: { max_allowlist_entries: MAX_ALLOWLIST_ENTRIES, max_daily_send_cap: MAX_DAILY_SEND_CAP, max_rules: rules.MAX_RULES_PER_AGENT, max_prompt_chars: rules.MAX_PROMPT_CHARS },
	};
}

export async function updateMailPolicy({ userId, agentId, patch }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const policy = await guarded(() => savePolicy({ agentId: agent.id, userId, patch: patch || {} }));
	logAudit({ userId, action: 'agent_mail.policy', resourceId: agent.id, meta: policy });
	return { policy };
}

export async function listMailRules({ userId, agentId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	return { rules: await rules.listRules(agent.id) };
}

export async function createMailRule({ userId, agentId, input }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const rule = await guarded(() => rules.createRule({ agentId: agent.id, userId, input: input || {} }));
	logAudit({ userId, action: 'agent_mail.rule_create', resourceId: agent.id, meta: { rule_id: rule.id, match_from: rule.match_from, mode: rule.mode } });
	return { rule };
}

export async function updateMailRule({ userId, agentId, ruleId, input }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const rule = await guarded(() => rules.updateRule({ agentId: agent.id, ruleId, input: input || {} }));
	logAudit({ userId, action: 'agent_mail.rule_update', resourceId: agent.id, meta: { rule_id: rule.id } });
	return { rule };
}

export async function deleteMailRule({ userId, agentId, ruleId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const out = await guarded(() => rules.deleteRule({ agentId: agent.id, ruleId }));
	logAudit({ userId, action: 'agent_mail.rule_delete', resourceId: agent.id, meta: { rule_id: ruleId } });
	return out;
}

export async function listMailRuleEvents({ userId, agentId, limit = 50 }) {
	const agent = await loadOwnedAgent(agentId, userId);
	return { events: await rules.listRuleEvents({ agentId: agent.id, limit }) };
}