nolo-cli 0.1.13 → 0.1.14

package/database/server/emailRepository.ts

@@ -0,0 +1,1480 @@
+import type { ActorContext } from "auth/actor";
+import { DataType } from "create/types";
+import type {
+  EmailMailbox,
+  EmailParticipant,
+  EmailRecord,
+  EmailStatus,
+} from "database/email";
+import { emailKey } from "database/keys";
+import type { ApiContext, ApiError } from "server/api/types";
+import {
+  type EmailProvider,
+  type EmailProviderSendResult,
+} from "server/email/provider";
+import { getEmailProvider } from "server/email/providerRegistry";
+import { authorizeActorRecordAccess } from "./actorAccess";
+import { agentDelegationKey } from "./agentDelegation";
+import serverDb from "./db";
+import { resolveKeyOwnerId } from "./writeAuthority";
+
+type CreateEmailRecordInput = {
+  ownerId: string;
+  ownerType?: EmailRecord["ownerType"];
+  tenantId?: string;
+  spaceId?: string | null;
+  mailbox?: EmailMailbox;
+  status?: EmailStatus;
+  from: EmailParticipant;
+  to?: EmailParticipant[];
+  cc?: EmailParticipant[];
+  bcc?: EmailParticipant[];
+  replyTo?: EmailParticipant[];
+  subject?: string;
+  text?: string;
+  html?: string;
+  messageId?: string;
+  threadId?: string;
+  inReplyTo?: string;
+  references?: string[];
+  tags?: string[];
+  meta?: Record<string, unknown>;
+  now?: string | number;
+};
+
+type ListEmailsParams = {
+  ownerId?: string;
+  mailbox?: EmailMailbox;
+  status?: EmailStatus;
+  tag?: string;
+  limit?: number;
+};
+
+type EmailKeyParams = {
+  dbKey: string;
+};
+
+type UpdateEmailTagsParams = EmailKeyParams & {
+  tags: string[];
+};
+
+type SendEmailParams = {
+  agentId: string;
+  from: EmailParticipant;
+  to: EmailParticipant[];
+  cc?: EmailParticipant[];
+  bcc?: EmailParticipant[];
+  replyTo?: EmailParticipant[];
+  subject: string;
+  text?: string;
+  html?: string;
+};
+
+type ReceiveInboundEmailResult = {
+  records: EmailRecord[];
+  existing: EmailRecord[];
+};
+
+type MirrorEmailToControlledInboxesParams = {
+  from: EmailParticipant;
+  to?: EmailParticipant[];
+  cc?: EmailParticipant[];
+  bcc?: EmailParticipant[];
+  replyTo?: EmailParticipant[];
+  subject?: string;
+  text?: string;
+  html?: string;
+  providerName: string;
+  providerMessageId?: string;
+  providerReceivedAt?: string | number;
+  rawHeaders?: unknown;
+  raw?: unknown;
+  meta?: Record<string, unknown>;
+};
+
+type BindAgentEmailIdentityParams = {
+  agentId: string;
+  emailAddress: string;
+  provider?: string;
+};
+
+type ProvisionAgentEmailIdentityParams = {
+  agentId: string;
+  purpose?: string;
+  localPart?: string;
+  domain?: string;
+  provider?: string;
+  makePrimary?: boolean;
+};
+
+type AgentEmailIdentity = {
+  emailAddress: string;
+  provider?: string;
+  purpose?: string;
+  createdAt?: string | number;
+  verifiedAt?: string | number;
+  readinessStatus?: "created" | "warming" | "ready" | "failed_warmup";
+  ingressReadyAt?: string | number | null;
+  lastWarmupAt?: string | number | null;
+  lastWarmupError?: string | null;
+  disabledAt?: string | number | null;
+  source?: "bound" | "provisioned";
+};
+
+const MAX_LIST_LIMIT = 200;
+const DEFAULT_AGENT_EMAIL_PROVIDER = "cloudflare";
+const DEFAULT_CLOUDFLARE_EMAIL_ROUTING_WORKER = "bun-nolo-agent-email-router";
+const DEFAULT_CLOUDFLARE_EMAIL_ROUTE_READY_TIMEOUT_MS = 60000;
+const DEFAULT_CLOUDFLARE_EMAIL_ROUTE_READY_POLL_MS = 2500;
+
+const apiError = (code: ApiError["code"], message: string): ApiError => ({
+  code,
+  message,
+});
+
+const normalizeTags = (tags?: unknown): string[] => {
+  if (!Array.isArray(tags)) return [];
+  return Array.from(
+    new Set(
+      tags
+        .map((tag) => (typeof tag === "string" ? tag.trim() : ""))
+        .filter(Boolean)
+    )
+  );
+};
+
+const actorOwnerId = (actor?: ActorContext | null): string | null => {
+  if (!actor) return null;
+  if (actor.type === "user") return actor.userId;
+  return actor.principalUserId || null;
+};
+
+const requireActor = (context?: ApiContext): ActorContext => {
+  const actor = context?.actor;
+  if (!actor) throw apiError("unauthorized", "Authentication required");
+  return actor;
+};
+
+const assertEmailAccess = async (
+  actor: ActorContext,
+  action: "read" | "manage" | "write",
+  record: EmailRecord
+) => {
+  const access = await authorizeActorRecordAccess({
+    action,
+    actor,
+    dbKey: record.dbKey,
+    record,
+  });
+  if (!access.allowed) {
+    throw apiError("forbidden", "You do not have access to this email");
+  }
+};
+
+const loadEmailRecord = async (dbKey: string): Promise<EmailRecord> => {
+  if (!dbKey) throw apiError("invalid_input", "dbKey is required");
+
+  const record = await serverDb.get(dbKey).catch(() => null);
+  if (!record || record.type !== DataType.EMAIL || record.deletedAt) {
+    throw apiError("not_found", "Email not found");
+  }
+  return record as EmailRecord;
+};
+
+const normalizeEmailAddress = (value?: unknown): string =>
+  typeof value === "string" ? value.trim().toLowerCase() : "";
+
+const normalizeParticipants = (value?: unknown): EmailParticipant[] => {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => {
+      if (!item || typeof item !== "object") return null;
+      const raw = item as Record<string, unknown>;
+      const email = normalizeEmailAddress(raw.email);
+      if (!email) return null;
+      const name =
+        typeof raw.name === "string" && raw.name.trim()
+          ? raw.name.trim()
+          : undefined;
+      return { email, ...(name ? { name } : {}) };
+    })
+    .filter((item): item is EmailParticipant => Boolean(item));
+};
+
+const normalizeEmailDomain = (value?: unknown): string =>
+  typeof value === "string"
+    ? value.trim().toLowerCase().replace(/^@+/, "")
+    : "";
+
+const normalizeLocalPart = (value?: unknown): string =>
+  typeof value === "string" ? value.trim().toLowerCase() : "";
+
+const normalizePurpose = (value?: unknown): string => {
+  if (typeof value !== "string") return "";
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+};
+
+const hashToken = (value: string): string => {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36).padStart(6, "0").slice(0, 8);
+};
+
+const PROVISIONED_EMAIL_FIRST_NAMES = [
+  "ava",
+  "clara",
+  "ella",
+  "grace",
+  "iris",
+  "julia",
+  "lena",
+  "maya",
+  "nina",
+  "olive",
+  "sara",
+  "tessa",
+  "leo",
+  "milo",
+  "owen",
+  "theo",
+] as const;
+
+const PROVISIONED_EMAIL_LAST_NAMES = [
+  "bennett",
+  "brooks",
+  "carter",
+  "ellis",
+  "foster",
+  "hayes",
+  "jensen",
+  "morris",
+  "parker",
+  "quinn",
+  "reed",
+  "sawyer",
+  "turner",
+  "walker",
+  "wright",
+  "young",
+] as const;
+
+const splitConfiguredDomains = (value?: string): string[] =>
+  String(value || "")
+    .split(",")
+    .map(normalizeEmailDomain)
+    .filter(Boolean);
+
+const extractDomainFromEmailValue = (value?: string): string => {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw) return "";
+  const match = raw.match(/<?([^<>\s]+@[^<>\s]+)>?/);
+  if (!match?.[1]) return "";
+  const [, domain = ""] = match[1].split("@");
+  return normalizeEmailDomain(domain);
+};
+
+const configuredAgentEmailDomains = (): string[] => {
+  const domains = [
+    ...splitConfiguredDomains(process.env.AGENT_EMAIL_DOMAINS),
+    ...splitConfiguredDomains(process.env.AGENT_EMAIL_DOMAIN),
+    ...splitConfiguredDomains(process.env.EMAIL_AGENT_DOMAINS),
+    ...splitConfiguredDomains(process.env.EMAIL_AGENT_DOMAIN),
+    ...splitConfiguredDomains(process.env.EMAIL_INBOUND_DOMAINS),
+    ...splitConfiguredDomains(process.env.EMAIL_INBOUND_DOMAIN),
+    extractDomainFromEmailValue(process.env.AGENT_EMAIL_E2E_FROM),
+    extractDomainFromEmailValue(process.env.CLOUDFLARE_EMAIL_FROM),
+    extractDomainFromEmailValue(process.env.EMAIL_FROM),
+    extractDomainFromEmailValue(process.env.RESEND_FROM_EMAIL),
+  ];
+  return Array.from(new Set(domains.filter(Boolean)));
+};
+
+const resolveAgentEmailDomain = (requestedDomain?: unknown): string => {
+  const configured = configuredAgentEmailDomains();
+  const requested = normalizeEmailDomain(requestedDomain);
+  if (requested) {
+    if (configured.length === 0) {
+      throw apiError(
+        "invalid_input",
+        "AGENT_EMAIL_DOMAIN or AGENT_EMAIL_DOMAINS must be configured"
+      );
+    }
+    if (configured.length > 0 && !configured.includes(requested)) {
+      throw apiError("forbidden", "Requested email domain is not allowed");
+    }
+    return requested;
+  }
+  const first = configured[0];
+  if (!first) {
+    throw apiError(
+      "invalid_input",
+      "AGENT_EMAIL_DOMAIN or AGENT_EMAIL_DOMAINS must be configured"
+    );
+  }
+  return first;
+};
+
+const normalizeProviderName = (value?: unknown): string =>
+  typeof value === "string" ? value.trim().toLowerCase() : "";
+
+const resolveCloudflareEmailRoutingConfig = () => {
+  const zoneId =
+    process.env.CLOUDFLARE_EMAIL_ROUTING_ZONE_ID?.trim() ||
+    process.env.CLOUDFLARE_ZONE_ID?.trim() ||
+    "";
+  const apiToken =
+    process.env.CLOUDFLARE_EMAIL_ROUTING_API_TOKEN?.trim() ||
+    process.env.CLOUDFLARE_API_TOKEN?.trim() ||
+    "";
+  const workerName =
+    process.env.CLOUDFLARE_EMAIL_ROUTING_WORKER_NAME?.trim() ||
+    DEFAULT_CLOUDFLARE_EMAIL_ROUTING_WORKER;
+  if (!zoneId || !apiToken || !workerName) return null;
+  return {
+    zoneId,
+    apiToken,
+    workerName,
+    apiBaseUrl:
+      process.env.CLOUDFLARE_EMAIL_ROUTING_API_BASE_URL?.trim() ||
+      "https://api.cloudflare.com/client/v4",
+  };
+};
+
+const parseCloudflareApiJson = async (response: Response) => {
+  const text = await response.text();
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return { rawText: text };
+  }
+};
+
+const cloudflareApiErrorMessage = (payload: any, fallback: string): string => {
+  const errors = Array.isArray(payload?.errors)
+    ? payload.errors
+        .map((error: any) => error?.message || error?.code)
+        .filter(Boolean)
+    : [];
+  return errors.length > 0 ? errors.join("; ") : fallback;
+};
+
+const isMatchingCloudflareWorkerRoute = (
+  rule: any,
+  emailAddress: string,
+  workerName: string
+) => {
+  const matchers = Array.isArray(rule?.matchers) ? rule.matchers : [];
+  const matcher = matchers.find(
+    (item: any) =>
+      item?.type === "literal" &&
+      item?.field === "to" &&
+      normalizeEmailAddress(item?.value) === emailAddress
+  );
+  if (!matcher) return false;
+  const actions = Array.isArray(rule?.actions) ? rule.actions : [];
+  return actions.some(
+    (action: any) =>
+      action?.type === "worker" &&
+      Array.isArray(action?.value) &&
+      action.value.includes(workerName)
+  );
+};
+
+const hasConflictingCloudflareRoute = (rule: any, emailAddress: string): boolean => {
+  const matchers = Array.isArray(rule?.matchers) ? rule.matchers : [];
+  return matchers.some(
+    (item: any) =>
+      item?.type === "literal" &&
+      item?.field === "to" &&
+      normalizeEmailAddress(item?.value) === emailAddress
+  );
+};
+
+const ensureCloudflareEmailRoutingRule = async (
+  emailAddress: string,
+  provider?: unknown
+) => {
+  if (normalizeProviderName(provider) !== "cloudflare") return;
+  const config = resolveCloudflareEmailRoutingConfig();
+  if (!config) return;
+
+  const url = `${config.apiBaseUrl.replace(/\/+$/, "")}/zones/${encodeURIComponent(
+    config.zoneId
+  )}/email/routing/rules`;
+  const headers = {
+    Authorization: `Bearer ${config.apiToken}`,
+    "Content-Type": "application/json",
+  };
+
+  const listResponse = await fetch(url, {
+    method: "GET",
+    headers,
+  });
+  const listPayload = await parseCloudflareApiJson(listResponse);
+  if (!listResponse.ok || listPayload?.success === false) {
+    throw apiError(
+      "internal_error",
+      `Failed to list Cloudflare email routing rules for ${emailAddress}: ${cloudflareApiErrorMessage(
+        listPayload,
+        `HTTP ${listResponse.status}`
+      )}`
+    );
+  }
+
+  const existingRules = Array.isArray(listPayload?.result) ? listPayload.result : [];
+  const matchingRule = existingRules.find((rule: any) =>
+    isMatchingCloudflareWorkerRoute(rule, emailAddress, config.workerName)
+  );
+  if (matchingRule && matchingRule.enabled !== false) {
+    return;
+  }
+
+  const conflictingRule = existingRules.find((rule: any) =>
+    hasConflictingCloudflareRoute(rule, emailAddress)
+  );
+  if (conflictingRule) {
+    throw apiError(
+      "invalid_input",
+      `Cloudflare email routing already has a conflicting rule for ${emailAddress}`
+    );
+  }
+
+  const createResponse = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      name: `Agent email route ${emailAddress}`,
+      enabled: true,
+      priority: 0,
+      matchers: [
+        {
+          type: "literal",
+          field: "to",
+          value: emailAddress,
+        },
+      ],
+      actions: [
+        {
+          type: "worker",
+          value: [config.workerName],
+        },
+      ],
+    }),
+  });
+  const createPayload = await parseCloudflareApiJson(createResponse);
+  if (!createResponse.ok || createPayload?.success === false) {
+    throw apiError(
+      "internal_error",
+      `Failed to create Cloudflare email routing rule for ${emailAddress}: ${cloudflareApiErrorMessage(
+        createPayload,
+        `HTTP ${createResponse.status}`
+      )}`
+    );
+  }
+};
+
+const resolveRouteReadinessSender = (domain: string): EmailParticipant => {
+  const configured = [
+    process.env.AGENT_EMAIL_E2E_FROM,
+    process.env.CLOUDFLARE_EMAIL_FROM,
+    process.env.EMAIL_FROM,
+    process.env.RESEND_FROM_EMAIL,
+  ]
+    .map((item) => String(item || "").trim())
+    .find(Boolean);
+  const normalized = normalizeEmailAddress(configured);
+  if (normalized) {
+    return { email: normalized };
+  }
+  return { email: `no-reply@${domain}` };
+};
+
+const parsePositiveInt = (value: unknown, fallback: number): number => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+};
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const findRecentInboundEmail = async (
+  agentId: string,
+  matcher: (record: EmailRecord) => boolean
+): Promise<EmailRecord | null> => {
+  const range = emailKey.rangeOfOwner(agentId);
+  for await (const [, value] of serverDb.iterator({
+    gte: range.start,
+    lte: range.end,
+    reverse: true,
+  })) {
+    const record = value as EmailRecord | null;
+    if (!record || record.type !== DataType.EMAIL || (record as any).deletedAt) continue;
+    if (matcher(record)) return record;
+  }
+  return null;
+};
+
+const archiveRouteReadinessProbe = async (record: EmailRecord) => {
+  await serverDb.put(record.dbKey, {
+    ...record,
+    mailbox: "archive",
+    tags: normalizeTags([...(record.tags || []), "route-readiness-probe"]),
+    updatedAt: new Date().toISOString(),
+    meta: {
+      ...(record.meta || {}),
+      routeReadinessProbe: true,
+    },
+  });
+};
+
+const waitForCloudflareRouteReadiness = async (
+  agentId: string,
+  emailAddress: string,
+  domain: string,
+  provider?: unknown
+): Promise<string> => {
+  if (normalizeProviderName(provider) !== "cloudflare") {
+    return new Date().toISOString();
+  }
+  if (!resolveCloudflareEmailRoutingConfig()) {
+    return new Date().toISOString();
+  }
+
+  const readinessEnabled = String(process.env.CLOUDFLARE_EMAIL_ROUTE_READY_ENABLED || "1")
+    .trim()
+    .toLowerCase();
+  if (readinessEnabled === "0" || readinessEnabled === "false") {
+    return new Date().toISOString();
+  }
+
+  const timeoutMs = parsePositiveInt(
+    process.env.CLOUDFLARE_EMAIL_ROUTE_READY_TIMEOUT_MS,
+    DEFAULT_CLOUDFLARE_EMAIL_ROUTE_READY_TIMEOUT_MS
+  );
+  const pollMs = parsePositiveInt(
+    process.env.CLOUDFLARE_EMAIL_ROUTE_READY_POLL_MS,
+    DEFAULT_CLOUDFLARE_EMAIL_ROUTE_READY_POLL_MS
+  );
+  const providerClient = getEmailProvider();
+  const now = Date.now();
+  const probeToken = `${now.toString(36)}-${hashToken(`${agentId}:${emailAddress}:${now}`)}`;
+  const subject = `Agent email route readiness ${probeToken}`;
+  const text = `route-readiness-probe:${probeToken}`;
+  const startedAt = Date.now();
+
+  await providerClient.sendEmail({
+    from: resolveRouteReadinessSender(domain),
+    to: [{ email: emailAddress }],
+    subject,
+    text,
+    headers: {
+      "X-Nolo-Route-Readiness": probeToken,
+    },
+  });
+
+  while (Date.now() - startedAt <= timeoutMs) {
+    const matched = await findRecentInboundEmail(agentId, (record) => {
+      if (record.mailbox !== "inbox") return false;
+      if (record.subject !== subject) return false;
+      if (!record.to?.some((item) => normalizeEmailAddress(item?.email) === emailAddress)) {
+        return false;
+      }
+      const createdAt = Number(new Date(record.createdAt).getTime());
+      return Number.isFinite(createdAt) ? createdAt >= startedAt - 1000 : true;
+    });
+    if (matched) {
+      await archiveRouteReadinessProbe(matched);
+      return new Date().toISOString();
+    }
+    await sleep(Math.min(pollMs, timeoutMs));
+  }
+
+  throw apiError(
+    "internal_error",
+    `Cloudflare email route for ${emailAddress} was created but did not become ingress-ready in time`
+  );
+};
+
+const assertValidLocalPart = (localPart: string) => {
+  if (
+    localPart.length < 1 ||
+    localPart.length > 64 ||
+    !/^[a-z0-9][a-z0-9._+-]*[a-z0-9]$|^[a-z0-9]$/.test(localPart)
+  ) {
+    throw apiError(
+      "invalid_input",
+      "localPart must be 1-64 chars and contain only letters, numbers, dot, underscore, plus, or hyphen"
+    );
+  }
+};
+
+const buildProvisionedLocalPart = (agentId: string, purpose?: unknown): string => {
+  const purposeSlug = normalizePurpose(purpose);
+  const token = hashToken(`${agentId}:${purposeSlug || "primary"}`);
+  const firstHash = Number.parseInt(hashToken(`${token}:first`), 36);
+  const lastHash = Number.parseInt(hashToken(`${token}:last`), 36);
+  const firstName =
+    PROVISIONED_EMAIL_FIRST_NAMES[firstHash % PROVISIONED_EMAIL_FIRST_NAMES.length];
+  const lastName =
+    PROVISIONED_EMAIL_LAST_NAMES[lastHash % PROVISIONED_EMAIL_LAST_NAMES.length];
+  const suffix = token.slice(-4);
+  return `${firstName}.${lastName}-${suffix}`;
+};
+
+const getAgentEmailIdentities = (agent: any): AgentEmailIdentity[] => {
+  const identities: AgentEmailIdentity[] = [];
+  const seen = new Set<string>();
+  const push = (identity: Partial<AgentEmailIdentity> | null | undefined) => {
+    const emailAddress = normalizeEmailAddress(identity?.emailAddress);
+    if (!emailAddress || seen.has(emailAddress) || identity?.disabledAt) return;
+    seen.add(emailAddress);
+    identities.push({
+      ...identity,
+      emailAddress,
+    });
+  };
+
+  push({
+    emailAddress: agent?.meta?.emailAddress,
+    provider: agent?.meta?.emailProvider,
+    verifiedAt: agent?.meta?.emailVerifiedAt,
+    readinessStatus: agent?.meta?.emailReadinessStatus,
+    ingressReadyAt: agent?.meta?.emailIngressReadyAt,
+    lastWarmupAt: agent?.meta?.emailLastWarmupAt,
+    lastWarmupError: agent?.meta?.emailLastWarmupError,
+    source: "bound",
+  });
+
+  if (Array.isArray(agent?.meta?.emailIdentities)) {
+    agent.meta.emailIdentities.forEach((identity: any) => push(identity));
+  }
+
+  return identities;
+};
+
+const hasAgentEmailIdentity = (agent: any, emailAddress: string): boolean => {
+  const normalized = normalizeEmailAddress(emailAddress);
+  return getAgentEmailIdentities(agent).some(
+    (identity) => identity.emailAddress === normalized
+  );
+};
+
+const getAgentEmailIdentity = (
+  agent: any,
+  emailAddress: string
+): AgentEmailIdentity | undefined => {
+  const normalized = normalizeEmailAddress(emailAddress);
+  return getAgentEmailIdentities(agent).find(
+    (identity) => identity.emailAddress === normalized
+  );
+};
+
+const withReadinessState = (
+  identity: AgentEmailIdentity,
+  patch: Partial<
+    Pick<
+      AgentEmailIdentity,
+      "readinessStatus" | "ingressReadyAt" | "lastWarmupAt" | "lastWarmupError"
+    >
+  >
+): AgentEmailIdentity => ({
+  ...identity,
+  ...patch,
+});
+
+const assertValidEmailAddress = (emailAddress: string) => {
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(emailAddress)) {
+    throw apiError("invalid_input", "emailAddress must be a valid email address");
+  }
+};
+
+const upsertAgentEmailIdentity = (
+  agent: any,
+  identity: AgentEmailIdentity,
+  options: { makePrimary?: boolean } = {}
+) => {
+  const emailAddress = normalizeEmailAddress(identity.emailAddress);
+  assertValidEmailAddress(emailAddress);
+  const now = new Date().toISOString();
+  const existingIdentities = Array.isArray(agent?.meta?.emailIdentities)
+    ? agent.meta.emailIdentities
+    : [];
+  const nextIdentity: AgentEmailIdentity = {
+    ...identity,
+    emailAddress,
+    createdAt: identity.createdAt || now,
+    verifiedAt: identity.verifiedAt || now,
+  };
+  const nextIdentities = [
+    nextIdentity,
+    ...existingIdentities.filter(
+      (item: any) => normalizeEmailAddress(item?.emailAddress) !== emailAddress
+    ),
+  ];
+  const currentPrimaryEmail = normalizeEmailAddress(agent?.meta?.emailAddress);
+  const shouldMakePrimary =
+    options.makePrimary ?? (!currentPrimaryEmail || currentPrimaryEmail === emailAddress);
+
+  return {
+    ...agent,
+    meta: {
+      ...(agent.meta || {}),
+      emailAddress: shouldMakePrimary
+        ? emailAddress
+        : normalizeEmailAddress(agent?.meta?.emailAddress) || emailAddress,
+      emailProvider:
+        shouldMakePrimary || !agent?.meta?.emailProvider
+          ? nextIdentity.provider || agent?.meta?.emailProvider || DEFAULT_AGENT_EMAIL_PROVIDER
+          : agent.meta.emailProvider,
+      emailVerifiedAt:
+        shouldMakePrimary || !agent?.meta?.emailVerifiedAt
+          ? nextIdentity.verifiedAt
+          : agent.meta.emailVerifiedAt,
+      emailIngressReadyAt:
+        shouldMakePrimary || !agent?.meta?.emailIngressReadyAt
+          ? nextIdentity.ingressReadyAt
+          : agent.meta.emailIngressReadyAt,
+      emailReadinessStatus:
+        shouldMakePrimary || !agent?.meta?.emailReadinessStatus
+          ? nextIdentity.readinessStatus
+          : agent.meta.emailReadinessStatus,
+      emailLastWarmupAt:
+        shouldMakePrimary || !agent?.meta?.emailLastWarmupAt
+          ? nextIdentity.lastWarmupAt
+          : agent.meta.emailLastWarmupAt,
+      emailLastWarmupError:
+        shouldMakePrimary || !agent?.meta?.emailLastWarmupError
+          ? nextIdentity.lastWarmupError
+          : agent.meta.emailLastWarmupError,
+      emailIdentities: nextIdentities,
+    },
+    updatedAt: now,
+  };
+};
+
+const buildBindIdentityResult = (
+  agentId: string,
+  emailAddress: string,
+  agent: any
+) => {
+  const identity = getAgentEmailIdentity(agent, emailAddress);
+  return {
+    agentId,
+    emailAddress,
+    readinessStatus: identity?.readinessStatus || null,
+    ingressReadyAt: identity?.ingressReadyAt || null,
+    lastWarmupAt: identity?.lastWarmupAt || null,
+    lastWarmupError: identity?.lastWarmupError || null,
+    agent,
+    delegationResourcePrefix: `email-${agentId}-`,
+  };
+};
+
+const buildProvisionIdentityResult = (
+  agentId: string,
+  emailAddress: string,
+  localPart: string,
+  domain: string,
+  provider: string,
+  purpose: string | null,
+  agent: any
+) => {
+  const identity = getAgentEmailIdentity(agent, emailAddress);
+  return {
+    agentId,
+    emailAddress,
+    localPart,
+    domain,
+    provider,
+    purpose,
+    readinessStatus: identity?.readinessStatus || null,
+    ingressReadyAt: identity?.ingressReadyAt || null,
+    lastWarmupAt: identity?.lastWarmupAt || null,
+    lastWarmupError: identity?.lastWarmupError || null,
+    agent,
+    delegationResourcePrefix: `email-${agentId}-`,
+  };
+};
+
+const loadOwnedAgent = async (
+  agentId: string,
+  principalUserId: string
+): Promise<any> => {
+  if (!agentId?.trim()) throw apiError("invalid_input", "agentId is required");
+  const agent = await serverDb.get(agentId).catch(() => null);
+  if (!agent || agent.deletedAt) throw apiError("not_found", "Agent not found");
+
+  const access = await authorizeActorRecordAccess({
+    action: "read",
+    actor: { type: "user", userId: principalUserId },
+    dbKey: agentId,
+    record: agent,
+  });
+  if (!access.allowed) {
+    throw apiError("forbidden", "You do not own this agent");
+  }
+  return agent;
+};
+
+export const findAgentByEmailAddress = async (email: string): Promise<any | null> => {
+  const normalized = normalizeEmailAddress(email);
+  if (!normalized) return null;
+
+  for await (const [, value] of serverDb.iterator({
+    gte: "agent-",
+    lte: "agent-\uffff",
+  })) {
+    if (hasAgentEmailIdentity(value, normalized) && !value?.deletedAt) {
+      return value;
+    }
+  }
+  return null;
+};
+
+const findExistingInboundEmail = async (
+  ownerId: string,
+  messageId?: string,
+  providerMessageId?: string
+): Promise<EmailRecord | null> => {
+  if (!messageId && !providerMessageId) return null;
+  const { start, end } = emailKey.rangeOfOwner(ownerId);
+  for await (const [, value] of serverDb.iterator({ gte: start, lte: end })) {
+    if (!value || value.type !== DataType.EMAIL || value.deletedAt) continue;
+    const record = value as EmailRecord;
+    if (messageId && record.messageId === messageId) return record;
+    if (
+      providerMessageId &&
+      (record.meta as any)?.provider?.messageId === providerMessageId
+    ) {
+      return record;
+    }
+  }
+  return null;
+};
+
+export async function mirrorEmailToControlledInboxes(
+  params: MirrorEmailToControlledInboxesParams
+): Promise<EmailRecord[]> {
+  const recipients = normalizeParticipants([
+    ...(params.to || []),
+    ...(params.cc || []),
+    ...(params.bcc || []),
+  ]);
+  const mirrored: EmailRecord[] = [];
+  const mirroredOwners = new Set<string>();
+
+  for (const recipient of recipients) {
+    const agent = await findAgentByEmailAddress(recipient.email);
+    if (!agent?.dbKey || mirroredOwners.has(agent.dbKey)) continue;
+    mirroredOwners.add(agent.dbKey);
+
+    const existingRecord = await findExistingInboundEmail(
+      agent.dbKey,
+      undefined,
+      params.providerMessageId
+    );
+    if (existingRecord) {
+      mirrored.push(existingRecord);
+      continue;
+    }
+
+    const now = params.providerReceivedAt || new Date().toISOString();
+    const record = createEmailRecord({
+      ownerType: "agent",
+      ownerId: agent.dbKey,
+      tenantId: resolveKeyOwnerId(agent.dbKey) || agent.ownerId || agent.dbKey,
+      mailbox: "inbox",
+      status: "received",
+      from: params.from,
+      to: [recipient],
+      cc: params.cc,
+      bcc: params.bcc,
+      replyTo: params.replyTo,
+      subject: params.subject,
+      text: params.text,
+      html: params.html,
+      messageId: params.providerMessageId,
+      meta: {
+        ...(params.meta || {}),
+        provider: {
+          name: params.providerName,
+          messageId: params.providerMessageId,
+          mirrored: true,
+          receivedAt: now,
+          rawHeaders: params.rawHeaders,
+          raw: params.raw,
+        },
+      },
+      now,
+    });
+    await serverDb.put(record.dbKey, record);
+    mirrored.push(record);
+  }
+
+  return mirrored;
+}
+
+const allowedRecipientEmails = async (recipients: EmailParticipant[]) => {
+  const allowlist = new Set(
+    String(process.env.EMAIL_TEST_ALLOWLIST || "")
+      .split(",")
+      .map((item) => normalizeEmailAddress(item))
+      .filter(Boolean)
+  );
+
+  const denied: string[] = [];
+  for (const recipient of recipients) {
+    const email = normalizeEmailAddress(recipient.email);
+    if (allowlist.has(email)) continue;
+    if (await findAgentByEmailAddress(email)) continue;
+    denied.push(recipient.email);
+  }
+
+  return denied;
+};
+
+const providerMeta = (
+  provider: EmailProvider,
+  result: EmailProviderSendResult,
+  extra?: Record<string, unknown>
+) => ({
+  provider: {
+    name: provider.name,
+    messageId: result.providerMessageId,
+    delivered: result.delivered,
+    queued: result.queued,
+    permanentBounces: result.permanentBounces,
+    error: result.error,
+    raw: result.raw,
+    ...extra,
+  },
+});
+
+const ensureAgentEmailDelegation = async (
+  principalUserId: string,
+  agentId: string
+) => {
+  const key = agentDelegationKey(principalUserId, agentId);
+  const existing = await serverDb.get(key).catch(() => null);
+  const scopes = new Set(Array.isArray(existing?.scopes) ? existing.scopes : []);
+  ["email:read", "email:manage", "email:send"].forEach((scope) => scopes.add(scope));
+
+  const prefixes = new Set(
+    Array.isArray(existing?.resourcePrefixes) ? existing.resourcePrefixes : []
+  );
+  prefixes.add(`email-${agentId}-`);
+
+  await serverDb.put(key, {
+    ...existing,
+    principalUserId,
+    agentId,
+    scopes: Array.from(scopes),
+    resourcePrefixes: Array.from(prefixes),
+  });
+};
+
+export function createEmailRecord(input: CreateEmailRecordInput): EmailRecord {
+  if (!input.ownerId?.trim()) {
+    throw apiError("invalid_input", "ownerId is required");
+  }
+  if (!input.from?.email?.trim()) {
+    throw apiError("invalid_input", "from.email is required");
+  }
+
+  const ownerId = input.ownerId.trim();
+  const { dbKey, emailId } = emailKey.create(ownerId);
+  const now = input.now ?? new Date().toISOString();
+
+  return {
+    dbKey,
+    type: DataType.EMAIL,
+    ownerType: input.ownerType ?? "user",
+    ownerId,
+    tenantId: input.tenantId ?? ownerId,
+    spaceId: input.spaceId ?? null,
+    mailbox: input.mailbox ?? "inbox",
+    status: input.status ?? "received",
+    from: input.from,
+    to: Array.isArray(input.to) ? input.to : [],
+    cc: input.cc,
+    bcc: input.bcc,
+    replyTo: input.replyTo,
+    subject: input.subject ?? "",
+    text: input.text,
+    html: input.html,
+    messageId: input.messageId ?? emailId,
+    threadId: input.threadId,
+    inReplyTo: input.inReplyTo,
+    references: input.references,
+    tags: normalizeTags(input.tags),
+    meta: input.meta ?? {},
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export async function listEmails(
+  params: ListEmailsParams = {},
+  context?: ApiContext
+): Promise<EmailRecord[]> {
+  const actor = requireActor(context);
+  const ownerId = params.ownerId?.trim() || actorOwnerId(actor);
+  if (!ownerId) throw apiError("forbidden", "Email owner is required");
+
+  const actorOwner = actorOwnerId(actor);
+  const isOwnedAgentMailbox =
+    actorOwner && resolveKeyOwnerId(ownerId) === actorOwner;
+  if (ownerId !== actorOwner && !isOwnedAgentMailbox) {
+    throw apiError("forbidden", "Cannot list emails for another owner");
+  }
+
+  const { start, end } = emailKey.rangeOfOwner(ownerId);
+  const limit = Math.min(
+    Math.max(Number(params.limit ?? 50), 1),
+    MAX_LIST_LIMIT
+  );
+  const rows: EmailRecord[] = [];
+
+  for await (const [, value] of serverDb.iterator({ gte: start, lte: end })) {
+    if (!value || value.type !== DataType.EMAIL || value.deletedAt) continue;
+    const record = value as EmailRecord;
+    if (params.mailbox && record.mailbox !== params.mailbox) continue;
+    if (params.status && record.status !== params.status) continue;
+    if (params.tag && !record.tags?.includes(params.tag)) continue;
+
+    const access = await authorizeActorRecordAccess({
+      action: "read",
+      actor,
+      dbKey: record.dbKey,
+      record,
+    });
+    if (!access.allowed) continue;
+
+    rows.push(record);
+    if (rows.length >= limit) break;
+  }
+
+  return rows.sort((a, b) => {
+    const bTime = new Date(b.updatedAt).getTime();
+    const aTime = new Date(a.updatedAt).getTime();
+    return (Number.isFinite(bTime) ? bTime : 0) - (Number.isFinite(aTime) ? aTime : 0);
+  });
+}
+
+export async function getEmail(
+  params: EmailKeyParams,
+  context?: ApiContext
+): Promise<EmailRecord> {
+  const actor = requireActor(context);
+  const record = await loadEmailRecord(params?.dbKey);
+
+  await assertEmailAccess(actor, "read", record);
+  return record;
+}
+
+export async function updateEmailTags(
+  params: UpdateEmailTagsParams,
+  context?: ApiContext
+): Promise<EmailRecord> {
+  const actor = requireActor(context);
+  const record = await loadEmailRecord(params?.dbKey);
+  await assertEmailAccess(actor, "manage", record);
+
+  const updated: EmailRecord = {
+    ...record,
+    tags: normalizeTags(params.tags),
+    updatedAt: new Date().toISOString(),
+  };
+  await serverDb.put(record.dbKey, updated);
+  return updated;
+}
+
+export async function archiveEmail(
+  params: EmailKeyParams,
+  context?: ApiContext
+): Promise<EmailRecord> {
+  const actor = requireActor(context);
+  const record = await loadEmailRecord(params?.dbKey);
+  await assertEmailAccess(actor, "manage", record);
+
+  const updated: EmailRecord = {
+    ...record,
+    mailbox: "archive",
+    updatedAt: new Date().toISOString(),
+  };
+  await serverDb.put(record.dbKey, updated);
+  return updated;
+}
+
+export async function sendEmail(
+  params: SendEmailParams,
+  context?: ApiContext,
+  provider: EmailProvider = getEmailProvider()
+): Promise<EmailRecord> {
+  if (!context?.userId) {
+    throw apiError("unauthorized", "Authentication required");
+  }
+
+  const agentId = params?.agentId?.trim() || "";
+  const agent = await loadOwnedAgent(agentId, context.userId);
+  const fromEmail = normalizeEmailAddress(params?.from?.email);
+  if (getAgentEmailIdentities(agent).length === 0) {
+    throw apiError("invalid_input", "Agent does not have an email identity");
+  }
+  if (!fromEmail || !hasAgentEmailIdentity(agent, fromEmail)) {
+    throw apiError("forbidden", "from must match one of the agent email identities");
+  }
+
+  const to = normalizeParticipants(params?.to);
+  if (to.length === 0) {
+    throw apiError("invalid_input", "to is required");
+  }
+  if (!params.subject?.trim()) {
+    throw apiError("invalid_input", "subject is required");
+  }
+  if (!params.text?.trim() && !params.html?.trim()) {
+    throw apiError("invalid_input", "text or html is required");
+  }
+
+  const deniedRecipients = await allowedRecipientEmails(to);
+  if (deniedRecipients.length > 0) {
+    throw apiError("forbidden", "Recipient is not an allowed agent or test address");
+  }
+
+  const now = new Date().toISOString();
+  const queued = createEmailRecord({
+    ownerType: "agent",
+    ownerId: agentId,
+    tenantId: context.userId,
+    mailbox: "sent",
+    status: "queued",
+    from: { ...params.from, email: fromEmail },
+    to,
+    cc: normalizeParticipants(params.cc),
+    bcc: normalizeParticipants(params.bcc),
+    replyTo: normalizeParticipants(params.replyTo),
+    subject: params.subject,
+    text: params.text,
+    html: params.html,
+    meta: {
+      agentId,
+      requestedByUserId: context.userId,
+      queuedAt: now,
+    },
+    now,
+  });
+
+  await assertEmailAccess(
+    { type: "agent", agentId, principalUserId: context.userId },
+    "write",
+    queued
+  );
+  await serverDb.put(queued.dbKey, queued);
+
+  try {
+    const result = await provider.sendEmail({
+      from: queued.from,
+      to: queued.to,
+      cc: queued.cc,
+      bcc: queued.bcc,
+      replyTo: queued.replyTo,
+      subject: queued.subject,
+      text: queued.text,
+      html: queued.html,
+    });
+    const status: EmailStatus = result.status === "failed" ? "failed" : "sent";
+    const updated: EmailRecord = {
+      ...queued,
+      status,
+      updatedAt: new Date().toISOString(),
+      meta: {
+        ...queued.meta,
+        ...providerMeta(provider, result),
+      },
+    };
+    await serverDb.put(updated.dbKey, updated);
+    if (status !== "failed") {
+      await mirrorEmailToControlledInboxes({
+        from: queued.from,
+        to: queued.to,
+        cc: queued.cc,
+        bcc: queued.bcc,
+        replyTo: queued.replyTo,
+        subject: queued.subject,
+        text: queued.text,
+        html: queued.html,
+        providerName: provider.name,
+        providerMessageId: result.providerMessageId,
+        meta: {
+          source: "sendEmail",
+          sentRecordKey: updated.dbKey,
+        },
+      });
+    }
+    return updated;
+  } catch (error: any) {
+    const failed: EmailRecord = {
+      ...queued,
+      status: "failed",
+      updatedAt: new Date().toISOString(),
+      meta: {
+        ...queued.meta,
+        provider: {
+          name: provider.name,
+          error: error?.message || String(error),
+        },
+      },
+    };
+    await serverDb.put(failed.dbKey, failed);
+    return failed;
+  }
+}
+
+export async function receiveInboundEmail(
+  payload: unknown,
+  provider: EmailProvider = getEmailProvider()
+): Promise<ReceiveInboundEmailResult> {
+  const inbound = await provider.parseInbound(payload);
+  const records: EmailRecord[] = [];
+  const existing: EmailRecord[] = [];
+  const unresolved: string[] = [];
+
+  for (const recipient of inbound.to) {
+    const agent = await findAgentByEmailAddress(recipient.email);
+    if (!agent?.dbKey) {
+      unresolved.push(recipient.email);
+      continue;
+    }
+
+    const existingRecord = await findExistingInboundEmail(
+      agent.dbKey,
+      inbound.messageId,
+      inbound.providerMessageId
+    );
+    if (existingRecord) {
+      existing.push(existingRecord);
+      continue;
+    }
+
+    const now = inbound.providerReceivedAt || new Date().toISOString();
+    const record = createEmailRecord({
+      ownerType: "agent",
+      ownerId: agent.dbKey,
+      tenantId: resolveKeyOwnerId(agent.dbKey) || agent.ownerId || agent.dbKey,
+      mailbox: "inbox",
+      status: "received",
+      from: inbound.from,
+      to: [recipient],
+      cc: inbound.cc,
+      bcc: inbound.bcc,
+      replyTo: inbound.replyTo,
+      subject: inbound.subject,
+      text: inbound.text,
+      html: inbound.html,
+      messageId: inbound.messageId,
+      meta: {
+        provider: {
+          name: provider.name,
+          messageId: inbound.providerMessageId,
+          receivedAt: now,
+          rawHeaders: inbound.rawHeaders,
+          raw: inbound.raw,
+        },
+      },
+      now,
+    });
+    await serverDb.put(record.dbKey, record);
+    records.push(record);
+  }
+
+  if (unresolved.length > 0 && records.length === 0 && existing.length === 0) {
+    throw apiError("not_found", `No agent email identity found for ${unresolved.join(", ")}`);
+  }
+
+  return { records, existing };
+}
+
+export async function bindAgentEmailIdentity(
+  params: BindAgentEmailIdentityParams,
+  context?: ApiContext
+) {
+  if (!context?.userId) {
+    throw apiError("unauthorized", "Authentication required");
+  }
+
+  const agentId = params?.agentId?.trim() || "";
+  const emailAddress = normalizeEmailAddress(params?.emailAddress);
+  assertValidEmailAddress(emailAddress);
+
+  const agent = await loadOwnedAgent(agentId, context.userId);
+  const existing = await findAgentByEmailAddress(emailAddress);
+  if (existing?.dbKey && existing.dbKey !== agentId) {
+    throw apiError("invalid_input", "emailAddress is already bound to another agent");
+  }
+
+  const now = new Date().toISOString();
+  const updated = upsertAgentEmailIdentity(
+    agent,
+    {
+      emailAddress,
+      provider: params.provider || agent.meta?.emailProvider || process.env.EMAIL_PROVIDER || "mock",
+      createdAt: now,
+      verifiedAt: now,
+      readinessStatus: "warming",
+      ingressReadyAt: null,
+      lastWarmupAt: now,
+      lastWarmupError: null,
+      source: "bound",
+    },
+    { makePrimary: true }
+  );
+
+  await ensureCloudflareEmailRoutingRule(emailAddress, params.provider);
+  await serverDb.put(agentId, updated);
+  try {
+    const ingressReadyAt = await waitForCloudflareRouteReadiness(
+      agentId,
+      emailAddress,
+      extractDomainFromEmailValue(emailAddress),
+      params.provider || updated.meta?.emailProvider
+    );
+    const readyAgent = upsertAgentEmailIdentity(
+      updated,
+      withReadinessState(getAgentEmailIdentity(updated, emailAddress) || { emailAddress }, {
+        readinessStatus: "ready",
+        ingressReadyAt,
+        lastWarmupAt: new Date().toISOString(),
+        lastWarmupError: null,
+      }),
+      { makePrimary: true }
+    );
+    await serverDb.put(agentId, readyAgent);
+    await ensureAgentEmailDelegation(context.userId, agentId);
+
+    return buildBindIdentityResult(agentId, emailAddress, readyAgent);
+  } catch (error: any) {
+    const failedWarmupAgent = upsertAgentEmailIdentity(
+      updated,
+      withReadinessState(getAgentEmailIdentity(updated, emailAddress) || { emailAddress }, {
+        readinessStatus: "failed_warmup",
+        ingressReadyAt: null,
+        lastWarmupAt: new Date().toISOString(),
+        lastWarmupError: error?.message || String(error),
+      }),
+      { makePrimary: true }
+    );
+    await serverDb.put(agentId, failedWarmupAgent);
+    await ensureAgentEmailDelegation(context.userId, agentId);
+    return buildBindIdentityResult(agentId, emailAddress, failedWarmupAgent);
+  }
+}
+
+export async function provisionAgentEmailIdentity(
+  params: ProvisionAgentEmailIdentityParams,
+  context?: ApiContext
+) {
+  if (!context?.userId) {
+    throw apiError("unauthorized", "Authentication required");
+  }
+
+  const agentId = params?.agentId?.trim() || "";
+  const agent = await loadOwnedAgent(agentId, context.userId);
+  const domain = resolveAgentEmailDomain(params?.domain);
+  const localPart = normalizeLocalPart(params?.localPart) ||
+    buildProvisionedLocalPart(agentId, params?.purpose);
+  assertValidLocalPart(localPart);
+
+  const emailAddress = `${localPart}@${domain}`;
+  assertValidEmailAddress(emailAddress);
+
+  const existing = await findAgentByEmailAddress(emailAddress);
+  if (existing?.dbKey && existing.dbKey !== agentId) {
+    throw apiError("invalid_input", "emailAddress is already bound to another agent");
+  }
+
+  const now = new Date().toISOString();
+  const provider =
+    params?.provider ||
+    agent.meta?.emailProvider ||
+    process.env.EMAIL_PROVIDER ||
+    DEFAULT_AGENT_EMAIL_PROVIDER;
+  const updated = upsertAgentEmailIdentity(
+    agent,
+    {
+      emailAddress,
+      provider,
+      purpose: normalizePurpose(params?.purpose) || undefined,
+      createdAt: now,
+      verifiedAt: now,
+      readinessStatus: "warming",
+      ingressReadyAt: null,
+      lastWarmupAt: now,
+      lastWarmupError: null,
+      source: "provisioned",
+    },
+    { makePrimary: params?.makePrimary }
+  );
+
+  await ensureCloudflareEmailRoutingRule(emailAddress, provider);
+  await serverDb.put(agentId, updated);
+  try {
+    const ingressReadyAt = await waitForCloudflareRouteReadiness(
+      agentId,
+      emailAddress,
+      domain,
+      provider
+    );
+    const readyAgent = upsertAgentEmailIdentity(
+      updated,
+      withReadinessState(getAgentEmailIdentity(updated, emailAddress) || { emailAddress }, {
+        readinessStatus: "ready",
+        ingressReadyAt,
+        lastWarmupAt: new Date().toISOString(),
+        lastWarmupError: null,
+      }),
+      { makePrimary: params?.makePrimary }
+    );
+    await serverDb.put(agentId, readyAgent);
+    await ensureAgentEmailDelegation(context.userId, agentId);
+
+    return buildProvisionIdentityResult(
+      agentId,
+      emailAddress,
+      localPart,
+      domain,
+      provider,
+      normalizePurpose(params?.purpose) || null,
+      readyAgent
+    );
+  } catch (error: any) {
+    const failedWarmupAgent = upsertAgentEmailIdentity(
+      updated,
+      withReadinessState(getAgentEmailIdentity(updated, emailAddress) || { emailAddress }, {
+        readinessStatus: "failed_warmup",
+        ingressReadyAt: null,
+        lastWarmupAt: new Date().toISOString(),
+        lastWarmupError: error?.message || String(error),
+      }),
+      { makePrimary: params?.makePrimary }
+    );
+    await serverDb.put(agentId, failedWarmupAgent);
+    await ensureAgentEmailDelegation(context.userId, agentId);
+    return buildProvisionIdentityResult(
+      agentId,
+      emailAddress,
+      localPart,
+      domain,
+      provider,
+      normalizePurpose(params?.purpose) || null,
+      failedWarmupAgent
+    );
+  }
+}