@agent-native/core 0.100.0 → 0.100.2

package/corpus/templates/mail/actions/list-emails.ts

@@ -6,9 +6,24 @@ import { z } from "zod";
 
 import {
   getClients,
+  getConnectedAccounts,
   fetchGmailLabelMap,
   isConnected,
 } from "../server/lib/google-auth.js";
+import {
+  buildMailInventoryPage,
+  claimInventoryCursor,
+  compareInventoryItems,
+  createInventoryCursor,
+  inventoryQueryFingerprint,
+  releaseInventoryCursorClaim,
+  settleInventoryCursorClaim,
+  type MailInventoryError,
+  type MailInventoryFetchResult,
+  type MailInventoryItem,
+  type MailInventoryCursorState,
+  type MailInventoryCursorClaim,
+} from "../server/lib/inventory-cursor.js";
 import {
   getSnoozedThreadIds,
   getSyntheticEmailsForView,
@@ -38,6 +53,55 @@ function toCompact(emails: any[]): any[] {
   }));
 }
 
+function toInventoryItem(
+  email: any,
+  includeSnippet: boolean,
+): MailInventoryItem {
+  return {
+    id: String(email.id ?? "").slice(0, 256),
+    threadId: String(email.threadId ?? email.id ?? "").slice(0, 256),
+    accountEmail: String(email.accountEmail ?? "").slice(0, 320),
+    date: String(email.date ?? "").slice(0, 64),
+    from: email.from?.email
+      ? {
+          ...(email.from.name
+            ? { name: String(email.from.name).slice(0, 160) }
+            : {}),
+          email: String(email.from.email).slice(0, 320),
+        }
+      : { email: String(email.from ?? "").slice(0, 320) },
+    subject: String(email.subject ?? "").slice(0, 500),
+    isUnread: email.hasUnread ?? !email.isRead,
+    ...(email.isStarred !== undefined ? { isStarred: email.isStarred } : {}),
+    messageCount: email.messageCount ?? 1,
+    unreadCount: email.unreadCount ?? (email.isRead ? 0 : 1),
+    ...(includeSnippet && email.snippet
+      ? { snippet: String(email.snippet).slice(0, 320) }
+      : {}),
+  };
+}
+
+function inventoryError(message: unknown): MailInventoryError {
+  const bounded = String(message ?? "Provider request failed")
+    .replace(/\bBearer\s+\S+/gi, "Bearer [redacted]")
+    .replace(
+      /\b(access_token|refresh_token|id_token|token)=([^\s&]+)/gi,
+      "$1=[redacted]",
+    )
+    .slice(0, 240);
+  const rateLimited = /\b(?:429|quota|rate.?limit)\b/i.test(bounded);
+  const auth = /\b(?:401|403|auth|token|credential|permission)\b/i.test(
+    bounded,
+  );
+  return {
+    code: rateLimited ? "rate_limited" : auth ? "authentication" : "provider",
+    message: bounded,
+    retryable:
+      rateLimited ||
+      /\b(?:timeout|temporar|unavailable|5\d\d)\b/i.test(bounded),
+  };
+}
+
 function latestPerThread(emails: any[]): any[] {
   const byThread = new Map<
     string,
@@ -85,6 +149,107 @@ function latestPerThread(emails: any[]): any[] {
     );
 }
 
+async function localInventoryEnvelope(
+  emails: any[],
+  requestedAccounts: string[] | undefined,
+  resolvedAccounts: string[],
+  query: { view: string; q?: string },
+  limit: number,
+  ownerEmail: string,
+  cursor?: string,
+) {
+  const normalizedRequested = requestedAccounts
+    ? [...new Set(requestedAccounts.map((email) => email.toLowerCase()))]
+    : null;
+  const queryFingerprint = inventoryQueryFingerprint({
+    ...query,
+    requestedAccounts: normalizedRequested,
+    limit,
+    source: "local",
+  });
+  let claim: MailInventoryCursorClaim | null = null;
+  let state: MailInventoryCursorState;
+  if (cursor) {
+    claim = await claimInventoryCursor(ownerEmail, cursor, queryFingerprint);
+    if (!claim) {
+      throw new Error(
+        "Inventory cursor is invalid, expired, or has already been used.",
+      );
+    }
+    state = claim.state;
+  } else {
+    const inventoryItems = latestPerThread(emails)
+      .map((email) =>
+        toInventoryItem(
+          {
+            ...email,
+            accountEmail: email.accountEmail ?? resolvedAccounts[0] ?? "local",
+          },
+          false,
+        ),
+      )
+      .sort(compareInventoryItems);
+    state = {
+      queryFingerprint,
+      requestedAccounts: normalizedRequested,
+      firstPage: true,
+      accounts: resolvedAccounts.map((accountEmail) => {
+        const pending = inventoryItems.filter(
+          (item) =>
+            item.accountEmail.toLowerCase() === accountEmail.toLowerCase(),
+        );
+        return {
+          accountEmail,
+          status: "ok" as const,
+          exhausted: true,
+          pending,
+          emittedCount: 0,
+          knownCount: pending.length,
+          emittedThreadIds: [],
+        };
+      }),
+    };
+  }
+
+  try {
+    const { items, hasMore } = await buildMailInventoryPage(
+      state,
+      limit,
+      async () => ({ items: [], errors: {}, nextPageTokens: {} }),
+    );
+    const nextCursor = claim
+      ? await settleInventoryCursorClaim(claim, state, hasMore)
+      : hasMore
+        ? await createInventoryCursor(ownerEmail, state)
+        : undefined;
+    return {
+      version: 1,
+      query,
+      requestedAccounts: state.requestedAccounts,
+      resolvedAccounts: state.accounts.map((account) => account.accountEmail),
+      queriedAccounts: state.accounts.map((account) => account.accountEmail),
+      accounts: state.accounts.map((account) => ({
+        accountEmail: account.accountEmail,
+        status: account.status,
+        count: account.knownCount ?? account.emittedCount,
+        emittedCount: account.emittedCount,
+        exhausted: account.exhausted && account.pending.length === 0,
+      })),
+      coverageComplete: true,
+      complete: !hasMore,
+      items,
+      page: {
+        returned: items.length,
+        hasMore,
+        ...(nextCursor ? { nextCursor } : {}),
+      },
+    };
+  } catch (error) {
+    if (claim) await releaseInventoryCursorClaim(claim);
+    throw error;
+  }
+}
+
 async function readLocalEmails(ownerEmail: string): Promise<any[]> {
   const data = await getUserSetting(ownerEmail, "local-emails");
   if (data && Array.isArray((data as any).emails)) {
@@ -112,13 +277,27 @@ export default defineAction({
       ])
       .optional()
       .describe("View to list (default: inbox)"),
-    q: z.string().optional().describe("Full-text search query"),
+    q: z.string().max(500).optional().describe("Full-text search query"),
     account: z
       .string()
       .optional()
       .describe(
         "Filter to a specific account email address. By default searches all connected accounts.",
       ),
+    accountEmails: z
+      .array(z.string().email())
+      .min(1)
+      .optional()
+      .describe(
+        "Inventory only: connected account email addresses to include.",
+      ),
+    format: z
+      .enum(["legacy", "inventory"])
+      .optional()
+      .describe(
+        "Use inventory for a coverage-aware compact multi-account read.",
+      ),
+    cursor: z.string().max(256).optional().describe("Inventory page cursor."),
     limit: z.coerce
       .number()
       .optional()
@@ -146,7 +325,7 @@ export default defineAction({
       view,
     };
   },
-  run: async (args) => {
+  run: async (args, ctx) => {
     const view = args.view ?? "inbox";
     const query = args.q;
     const limit = args.limit ?? 50;
@@ -155,9 +334,47 @@ export default defineAction({
     const accountFilter = args.account?.toLowerCase();
     const ownerEmail = getRequestUserEmail();
     if (!ownerEmail) throw new Error("no authenticated user");
+    if (args.account && args.accountEmails) {
+      throw new Error("Pass account or accountEmails, not both.");
+    }
+    const inventory =
+      args.format === "inventory" ||
+      (ctx?.caller === "mcp" && args.format === undefined);
+    if (inventory && (!Number.isInteger(limit) || limit < 1 || limit > 100)) {
+      throw new Error("Inventory limit must be an integer from 1 through 100.");
+    }
+
+    // Inventory is deliberately resolved before any refresh/list call. Apart
+    // from preventing a cross-account data leak, this keeps a selected read
+    // from touching token state for accounts the caller did not choose.
+    const requestedAccounts =
+      args.accountEmails ?? (args.account ? [args.account] : undefined);
 
     if (view === "snoozed" || view === "scheduled") {
       let emails = await getSyntheticEmailsForView(ownerEmail, view);
+      const syntheticAccountsByLower = new Map<string, string>();
+      for (const email of emails) {
+        const accountEmail = String(email.accountEmail ?? ownerEmail);
+        syntheticAccountsByLower.set(accountEmail.toLowerCase(), accountEmail);
+      }
+      const syntheticSelectedAccounts = inventory
+        ? Array.from(
+            new Set(
+              (
+                requestedAccounts ??
+                Array.from(syntheticAccountsByLower.values())
+              ).map((email) => email.toLowerCase()),
+            ),
+          ).map((email) => {
+            const available = syntheticAccountsByLower.get(email);
+            if (!available) {
+              throw new Error(
+                `Account ${email} is not available in ${view} mail for this user.`,
+              );
+            }
+            return available;
+          })
+        : undefined;
       if (query) {
         emails = emails.filter((e) => emailMessageMatchesSearch(e, query));
       }
@@ -166,6 +383,35 @@ export default defineAction({
           (e) => e.accountEmail?.toLowerCase() === accountFilter,
         );
       }
+      if (inventory) {
+        const selected = new Set(
+          (syntheticSelectedAccounts ?? []).map((email) => email.toLowerCase()),
+        );
+        if (selected.size > 0) {
+          emails = emails.filter((email) =>
+            selected.has(String(email.accountEmail ?? "").toLowerCase()),
+          );
+        }
+        const syntheticResolvedAccounts =
+          syntheticSelectedAccounts && syntheticSelectedAccounts.length > 0
+            ? syntheticSelectedAccounts
+            : Array.from(
+                new Set(
+                  emails.map((email) =>
+                    String(email.accountEmail ?? ownerEmail).toLowerCase(),
+                  ),
+                ),
+              );
+        return await localInventoryEnvelope(
+          emails,
+          requestedAccounts,
+          syntheticResolvedAccounts,
+          { view, ...(query ? { q: query } : {}) },
+          limit,
+          ownerEmail,
+          args.cursor,
+        );
+      }
       return JSON.stringify(
         compact ? toCompact(emails.slice(0, limit)) : emails.slice(0, limit),
         null,
@@ -173,8 +419,192 @@ export default defineAction({
       );
     }
 
-    if (await isConnected(ownerEmail)) {
-      const clients = await getClients(ownerEmail);
+    const connectedAccounts = inventory
+      ? await getConnectedAccounts(ownerEmail)
+      : [];
+    const connectedByLower = new Map(
+      connectedAccounts.map((email) => [email.toLowerCase(), email]),
+    );
+    const selectedAccounts =
+      inventory && connectedAccounts.length > 0
+        ? Array.from(
+            new Set(
+              (requestedAccounts ?? connectedAccounts).map((email) =>
+                email.toLowerCase(),
+              ),
+            ),
+          ).map((email) => {
+            const owned = connectedByLower.get(email);
+            if (!owned)
+              throw new Error(
+                `Account ${email} is not connected for this user.`,
+              );
+            return owned;
+          })
+        : undefined;
+
+    if (
+      (inventory && selectedAccounts && selectedAccounts.length > 0) ||
+      (!inventory && (await isConnected(ownerEmail)))
+    ) {
+      const inventoryAccounts = selectedAccounts ?? [];
+      const clients = inventory
+        ? inventoryAccounts.map((email) => ({
+            email,
+            accessToken: "",
+            refreshToken: "",
+          }))
+        : await getClients(ownerEmail);
+      if (inventory) {
+        const normalizedRequested = requestedAccounts
+          ? [...new Set(requestedAccounts.map((email) => email.toLowerCase()))]
+          : null;
+        const queryFingerprint = inventoryQueryFingerprint({
+          view,
+          q: query ?? null,
+          requestedAccounts: normalizedRequested,
+          limit,
+        });
+        let cursorState: MailInventoryCursorState;
+        let cursorClaim: MailInventoryCursorClaim | null = null;
+        if (args.cursor) {
+          const claimed = await claimInventoryCursor(
+            ownerEmail,
+            args.cursor,
+            queryFingerprint,
+          );
+          if (!claimed) {
+            throw new Error(
+              "Inventory cursor is invalid, expired, or has already been used.",
+            );
+          }
+          cursorClaim = claimed;
+          cursorState = claimed.state;
+        } else {
+          cursorState = {
+            queryFingerprint,
+            requestedAccounts: normalizedRequested,
+            firstPage: true,
+            accounts: inventoryAccounts.map((accountEmail) => ({
+              accountEmail,
+              status: "ok",
+              exhausted: false,
+              pending: [],
+              emittedCount: 0,
+              knownCount: 0,
+              emittedThreadIds: [],
+            })),
+          };
+        }
+
+        const fetchInventory = async (
+          requests: Array<{ accountEmail: string; pageToken?: string }>,
+        ): Promise<MailInventoryFetchResult> => {
+          const accountEmails = requests.map((request) => request.accountEmail);
+          const pageTokens = Object.fromEntries(
+            requests
+              .filter((request) => request.pageToken)
+              .map((request) => [request.accountEmail, request.pageToken!]),
+          );
+          const listResult = await listInboxEmails({
+            ownerEmail,
+            view,
+            q: query,
+            limit,
+            pageTokens:
+              Object.keys(pageTokens).length > 0 ? pageTokens : undefined,
+            threadFormat: "metadata",
+            includeRecentMessageCandidates: false,
+            accountTokens: accountEmails.map((email) => ({
+              email,
+              accessToken: "",
+            })),
+            accountEmails,
+            labelMap: new Map(),
+          });
+          if (!listResult.ok) {
+            return {
+              items: [],
+              errors: Object.fromEntries(
+                accountEmails.map((email) => [
+                  email.toLowerCase(),
+                  inventoryError(listResult.message),
+                ]),
+              ),
+              nextPageTokens: {},
+            };
+          }
+          return {
+            items: latestPerThread(listResult.emails).map((email) =>
+              toInventoryItem(email, false),
+            ),
+            errors: Object.fromEntries(
+              listResult.errors.map((error) => [
+                error.email.toLowerCase(),
+                inventoryError(error.error),
+              ]),
+            ),
+            nextPageTokens: Object.fromEntries(
+              Object.entries(listResult.nextPageTokens ?? {}).map(
+                ([email, token]) => [email.toLowerCase(), token],
+              ),
+            ),
+          };
+        };
+
+        try {
+          const { items, hasMore } = await buildMailInventoryPage(
+            cursorState,
+            limit,
+            fetchInventory,
+          );
+          const nextCursor = cursorClaim
+            ? await settleInventoryCursorClaim(
+                cursorClaim,
+                cursorState,
+                hasMore,
+              )
+            : hasMore
+              ? await createInventoryCursor(ownerEmail, cursorState)
+              : undefined;
+          const coverageComplete = cursorState.accounts.every(
+            (account) => account.status === "ok",
+          );
+          return {
+            version: 1,
+            query: { view, ...(query ? { q: query } : {}) },
+            requestedAccounts: cursorState.requestedAccounts,
+            resolvedAccounts: cursorState.accounts.map(
+              (account) => account.accountEmail,
+            ),
+            queriedAccounts: cursorState.accounts.map(
+              (account) => account.accountEmail,
+            ),
+            accounts: cursorState.accounts.map((account) => ({
+              accountEmail: account.accountEmail,
+              status: account.status,
+              count: account.knownCount ?? account.emittedCount,
+              emittedCount: account.emittedCount,
+              exhausted:
+                account.status === "ok" &&
+                account.exhausted &&
+                account.pending.length === 0,
+              ...(account.error ? { error: account.error } : {}),
+            })),
+            coverageComplete,
+            complete: coverageComplete && !hasMore,
+            items,
+            page: {
+              returned: items.length,
+              hasMore,
+              ...(nextCursor ? { nextCursor } : {}),
+            },
+          };
+        } catch (error) {
+          if (cursorClaim) await releaseInventoryCursorClaim(cursorClaim);
+          throw error;
+        }
+      }
       const labelMap = new Map<string, string>();
       await Promise.all(
         clients.map(async ({ accessToken }) => {
@@ -239,6 +669,37 @@ export default defineAction({
 
     // Fallback: local store
     let emails = await readLocalEmails(ownerEmail);
+    const localAccountsByLower = new Map<string, string>();
+    for (const email of emails) {
+      const accountEmail = String(email.accountEmail ?? "local");
+      localAccountsByLower.set(accountEmail.toLowerCase(), accountEmail);
+    }
+    const localSelectedAccounts = inventory
+      ? Array.from(
+          new Set(
+            (
+              requestedAccounts ?? Array.from(localAccountsByLower.values())
+            ).map((email) => email.toLowerCase()),
+          ),
+        ).map((email) => {
+          const available = localAccountsByLower.get(email);
+          if (!available) {
+            throw new Error(
+              `Account ${email} is not available in local mail for this user.`,
+            );
+          }
+          return available;
+        })
+      : undefined;
+
+    if (localSelectedAccounts && requestedAccounts) {
+      const selected = new Set(
+        localSelectedAccounts.map((email) => email.toLowerCase()),
+      );
+      emails = emails.filter((email) =>
+        selected.has(String(email.accountEmail ?? "local").toLowerCase()),
+      );
+    }
 
     switch (view) {
       case "inbox":
@@ -288,6 +749,27 @@ export default defineAction({
       }
     }
 
+    if (inventory) {
+      const localResolvedAccounts =
+        localSelectedAccounts && localSelectedAccounts.length > 0
+          ? localSelectedAccounts
+          : Array.from(
+              new Set(
+                emails.map((email) =>
+                  String(email.accountEmail ?? "local").toLowerCase(),
+                ),
+              ),
+            );
+      return await localInventoryEnvelope(
+        emails,
+        requestedAccounts,
+        localResolvedAccounts,
+        { view, ...(query ? { q: query } : {}) },
+        limit,
+        ownerEmail,
+        args.cursor,
+      );
+    }
     emails = latestPerThread(emails).slice(0, limit);
     const payload = compact ? toCompact(emails) : emails;
     if (includeCounts) {

package/corpus/templates/mail/changelog/2026-07-13-coverage-aware-connected-inbox-inventory.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-13
+---
+
+Mail can now return a compact coverage-aware direct inventory across selected connected inboxes.

package/corpus/templates/mail/server/db/schema.ts

@@ -1,5 +1,22 @@
 import { table, text, integer } from "@agent-native/core/db/schema";
 
+/**
+ * Short-lived, owner-scoped continuation state for the external Mail
+ * inventory. It intentionally contains compact metadata only; credentials,
+ * bodies, HTML and attachments never enter this table.
+ */
+export const mailInventoryCursors = table("mail_inventory_cursors", {
+  id: text("id").primaryKey(),
+  ownerEmail: text("owner_email").notNull(),
+  queryFingerprint: text("query_fingerprint").notNull(),
+  state: text("state").notNull(),
+  version: integer("version").notNull().default(1),
+  claimId: text("claim_id"),
+  claimedAt: integer("claimed_at"),
+  expiresAt: integer("expires_at").notNull(),
+  updatedAt: integer("updated_at").notNull(),
+});
+
 export const scheduledJobs = table("scheduled_jobs", {
   id: text("id").primaryKey(),
   type: text("type", { enum: ["snooze", "send_later"] }).notNull(),

package/corpus/templates/mail/server/lib/google-auth.ts

@@ -375,12 +375,23 @@ export async function getClients(
  * handler uses this to return a 502 with the underlying reason instead
  * of silently rendering an empty inbox.
  */
-export async function getClientsWithErrors(forEmail?: string): Promise<{
+export async function getClientsWithErrors(
+  forEmail?: string,
+  accountEmails?: string[],
+): Promise<{
   clients: Array<{ email: string; accessToken: string; refreshToken: string }>;
   errors: Array<{ email: string; error: string }>;
 }> {
   if (!forEmail) return { clients: [], errors: [] };
-  const accounts = await listOAuthAccountsByOwner("google", forEmail);
+  const requested = accountEmails
+    ? new Set(accountEmails.map((email) => email.toLowerCase()))
+    : null;
+  // Filtering happens before getValidAccessToken. This is important: token
+  // refreshes are writes and an explicitly scoped inventory read must not
+  // refresh unrelated accounts.
+  const accounts = (await listOAuthAccountsByOwner("google", forEmail)).filter(
+    (account) => !requested || requested.has(account.accountId.toLowerCase()),
+  );
 
   const clients: Array<{
     email: string;
@@ -571,6 +582,13 @@ type ListOptions = {
    * without hydrating a large metadata ranking window on every inbox poll.
    */
   threadRecentMessageCandidateLimit?: number;
+  /**
+   * Restrict this read before OAuth refreshes or provider calls.  This is
+   * deliberately an account-id allow-list rather than a post-fetch filter:
+   * a Mail user can have several connected inboxes and an explicitly scoped
+   * read must not wake up the others.
+   */
+  accountEmails?: string[];
 };
 
 const LIST_CACHE_TTL = 45_000;
@@ -791,6 +809,10 @@ async function fetchThreadBatchWithRefill(
     }
   }
 
+  if (batchResults.some((result) => !result.data)) {
+    throw new Error("Gmail thread metadata response was incomplete");
+  }
+
   return batchResults;
 }
 
@@ -852,7 +874,11 @@ function listCacheKey(
         .join("|")
     : "";
   const queryPart = query === undefined ? "<default>" : query;
-  return `${forEmail ?? ""}::${queryPart}::${maxResults}::${tokenPart}::${options?.mode ?? "messages"}::${options?.threadFormat ?? ""}::${options?.messageFormat ?? ""}::${options?.threadCandidateLimit ?? ""}::${options?.threadRecentMessageCandidateLimit ?? ""}`;
+  const accounts = options?.accountEmails
+    ?.map((email) => email.toLowerCase())
+    .sort()
+    .join(",");
+  return `${forEmail ?? ""}::${queryPart}::${maxResults}::${tokenPart}::${options?.mode ?? "messages"}::${options?.threadFormat ?? ""}::${options?.messageFormat ?? ""}::${options?.threadCandidateLimit ?? ""}::${options?.threadRecentMessageCandidateLimit ?? ""}::${accounts ?? ""}`;
 }
 
 export async function listGmailMessages(
@@ -1542,8 +1568,10 @@ async function listGmailMessagesUncached(
   pageTokens?: Record<string, string>,
   options?: ListOptions,
 ): Promise<ListResult> {
-  const { clients, errors: refreshErrors } =
-    await getClientsWithErrors(forEmail);
+  const { clients, errors: refreshErrors } = await getClientsWithErrors(
+    forEmail,
+    options?.accountEmails,
+  );
   // Seed the per-fetch error list with refresh failures so a fully-dead
   // connection (every account's refresh_token revoked or invalidated by a
   // GOOGLE_CLIENT_ID rotation) reaches the handler — otherwise the list