@agent-native/core 0.99.3 → 0.100.1

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/app/components/layout/AppLayout.tsx

@@ -13,6 +13,7 @@ import { normalizeMailLabel } from "@shared/gmail-labels";
 import type { Label } from "@shared/types";
 import {
   IconMenu2,
+  IconBrain,
   IconSettings,
   IconSearch,
   IconCheck,
@@ -144,6 +145,7 @@ function AccountAvatar({
 function isStandardLayoutPath(pathname: string): boolean {
   return (
     pathname === "/settings" ||
+    pathname === "/agent" ||
     pathname === "/team" ||
     pathname === "/draft-queue" ||
     pathname.startsWith("/draft-queue/") ||
@@ -195,6 +197,7 @@ export function AppLayout({ children }: AppLayoutProps) {
     <AgentSidebar
       position="right"
       defaultOpen={!isMobile}
+      agentPageHref="/agent"
       emptyStateText={t("agent.emptyState")}
       suggestions={[
         t("agent.suggestionSummarize"),
@@ -1748,6 +1751,25 @@ function AppLayoutInner({ children }: AppLayoutProps) {
                     <div className="flex items-center gap-1 px-2 py-2">
                       <DevDatabaseLink />
                       <FeedbackButton className="min-w-0 flex-1" />
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <Link
+                            to="/agent"
+                            onClick={closeSidebar}
+                            aria-label={t("settings.openAgentSettings")}
+                            className={cn(
+                              "flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground",
+                              location.pathname === "/agent" &&
+                                "bg-accent/60 text-foreground",
+                            )}
+                          >
+                            <IconBrain className="h-4 w-4" />
+                          </Link>
+                        </TooltipTrigger>
+                        <TooltipContent>
+                          {t("settings.openAgentSettings")}
+                        </TooltipContent>
+                      </Tooltip>
                       <Tooltip>
                         <TooltipTrigger asChild>
                           <Link
@@ -1967,6 +1989,7 @@ function StandardLayout({ children }: AppLayoutProps) {
 
   const fallbackTitle = (() => {
     if (location.pathname === "/settings") return t("settings.title");
+    if (location.pathname === "/agent") return t("settings.agentTitle");
     if (location.pathname === "/team") return t("mail.pages.team");
     if (location.pathname.startsWith("/draft-queue"))
       return t("mail.views.draftQueue");
@@ -2101,6 +2124,25 @@ function StandardLayout({ children }: AppLayoutProps) {
               <DevDatabaseLink />
               <FeedbackButton className="min-w-0 flex-1" />
               <div className="flex shrink-0 items-center gap-0.5">
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Link
+                      to="/agent"
+                      onClick={() => setSidebarOpen(false)}
+                      aria-label={t("settings.openAgentSettings")}
+                      className={cn(
+                        "flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground",
+                        location.pathname === "/agent" &&
+                          "bg-accent/60 text-foreground",
+                      )}
+                    >
+                      <IconBrain className="h-4 w-4" />
+                    </Link>
+                  </TooltipTrigger>
+                  <TooltipContent>
+                    {t("settings.openAgentSettings")}
+                  </TooltipContent>
+                </Tooltip>
                 <Tooltip>
                   <TooltipTrigger asChild>
                     <Link

package/corpus/templates/mail/app/components/layout/CommandPalette.tsx

@@ -1,5 +1,6 @@
 import { CommandMenu, useT } from "@agent-native/core/client";
 import {
+  IconBrain,
   IconInbox,
   IconStar,
   IconSend,
@@ -74,6 +75,11 @@ const navCommands = [
     shortcut: "G A",
   },
   { labelKey: "commandPalette.goToTrash", icon: IconTrash, route: "/trash" },
+  {
+    labelKey: "settings.openAgentSettings",
+    icon: IconBrain,
+    route: "/agent",
+  },
 ];
 
 export function CommandPalette({

package/corpus/templates/mail/app/routes/agent.tsx

@@ -0,0 +1,15 @@
+import { AgentTabsPage, useT } from "@agent-native/core/client";
+import { useSetPageTitle } from "@agent-native/toolkit/app-shell";
+
+import messages from "@/i18n/en-US";
+
+export function meta() {
+  return [{ title: messages.settings.agentTitle }];
+}
+
+export default function AgentRoute() {
+  const t = useT();
+  useSetPageTitle(t("settings.agentTitle"));
+
+  return <AgentTabsPage appName="Mail" />;
+}

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/changelog/2026-07-13-new-agent-page-see-and-manage-your-agent-s-context-files-con.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-13
+---
+
+New Agent page: see and manage your agent's context, files, connections, jobs, and external access in one place