@agent-native/core 0.100.0 → 0.100.1

package/corpus/templates/mail/server/lib/inventory-cursor.ts

@@ -0,0 +1,406 @@
+import { createHash } from "node:crypto";
+
+import { and, eq, gt, lt, or, sql } from "drizzle-orm";
+
+import { getDb } from "../db/index.js";
+import { mailInventoryCursors } from "../db/schema.js";
+
+const TTL_MS = 10 * 60 * 1000;
+const CLAIM_TTL_MS = 60 * 1000;
+const PAGE_ITEMS_BUDGET_BYTES = 12 * 1024;
+
+export interface MailInventoryItem {
+  id: string;
+  threadId: string;
+  accountEmail: string;
+  date: string;
+  from: { name?: string; email: string };
+  subject: string;
+  isUnread: boolean;
+  isStarred?: boolean;
+  messageCount: number;
+  unreadCount: number;
+  snippet?: string;
+}
+
+export interface MailInventoryError {
+  code: string;
+  message: string;
+  retryable: boolean;
+}
+
+export interface MailInventoryAccountState {
+  accountEmail: string;
+  status: "ok" | "error";
+  error?: MailInventoryError;
+  providerPageToken?: string;
+  exhausted: boolean;
+  pending: MailInventoryItem[];
+  emittedCount: number;
+  /** Unique rows discovered so coverage remains visible before emission. */
+  knownCount?: number;
+  /** Account-local thread ids already emitted by an earlier output page. */
+  emittedThreadIds?: string[];
+}
+
+export interface MailInventoryCursorState {
+  queryFingerprint: string;
+  requestedAccounts: string[] | null;
+  accounts: MailInventoryAccountState[];
+  firstPage: boolean;
+}
+
+export interface MailInventoryCursorClaim {
+  id: string;
+  claimId: string;
+  ownerEmail: string;
+  queryFingerprint: string;
+  version: number;
+  state: MailInventoryCursorState;
+}
+
+export interface MailInventoryFetchResult {
+  items: MailInventoryItem[];
+  errors: Record<string, MailInventoryError>;
+  nextPageTokens: Record<string, string>;
+}
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, child]) => [key, stableValue(child)]),
+    );
+  }
+  return value;
+}
+
+export function inventoryQueryFingerprint(input: unknown): string {
+  return createHash("sha256")
+    .update(JSON.stringify(stableValue(input)))
+    .digest("hex");
+}
+
+export function compareInventoryItems(
+  a: MailInventoryItem,
+  b: MailInventoryItem,
+): number {
+  const date = new Date(b.date).getTime() - new Date(a.date).getTime();
+  if (date) return date;
+  const account = a.accountEmail.localeCompare(b.accountEmail);
+  if (account) return account;
+  const thread = a.threadId.localeCompare(b.threadId);
+  if (thread) return thread;
+  return a.id.localeCompare(b.id);
+}
+
+function dedupeAndSort(items: MailInventoryItem[]): MailInventoryItem[] {
+  const unique = new Map<string, MailInventoryItem>();
+  for (const item of items) {
+    const key = `${item.accountEmail.toLowerCase()}:${item.threadId}`;
+    const current = unique.get(key);
+    if (!current || compareInventoryItems(item, current) < 0) {
+      unique.set(key, item);
+    }
+  }
+  return [...unique.values()].sort(compareInventoryItems);
+}
+
+function applyFetch(
+  states: MailInventoryAccountState[],
+  result: MailInventoryFetchResult,
+): void {
+  const byAccount = new Map<string, MailInventoryItem[]>();
+  for (const item of result.items) {
+    const key = item.accountEmail.toLowerCase();
+    const accountItems = byAccount.get(key) ?? [];
+    accountItems.push(item);
+    byAccount.set(key, accountItems);
+  }
+
+  for (const state of states) {
+    const key = state.accountEmail.toLowerCase();
+    const error = result.errors[key];
+    if (error) {
+      state.status = "error";
+      state.error = error;
+      state.exhausted = true;
+      state.providerPageToken = undefined;
+      continue;
+    }
+    const emitted = new Set(state.emittedThreadIds ?? []);
+    const before = new Set(
+      state.pending.map((item) => item.threadId).concat([...emitted]),
+    );
+    const additions = (byAccount.get(key) ?? []).filter(
+      (item) => !before.has(item.threadId),
+    );
+    state.knownCount =
+      (state.knownCount ?? state.emittedCount) + additions.length;
+    state.pending = dedupeAndSort([...state.pending, ...additions]);
+    state.providerPageToken = result.nextPageTokens[key];
+    state.exhausted = !state.providerPageToken;
+  }
+}
+
+export async function buildMailInventoryPage(
+  state: MailInventoryCursorState,
+  limit: number,
+  fetch: (
+    accounts: Array<{ accountEmail: string; pageToken?: string }>,
+  ) => Promise<MailInventoryFetchResult>,
+): Promise<{ items: MailInventoryItem[]; hasMore: boolean }> {
+  const pageLimit = Math.max(1, Math.min(Math.floor(limit), 100));
+  const refillCounts = new Map<string, number>();
+  const refillFrontiers = async () => {
+    while (true) {
+      const needsFetch = state.accounts.filter(
+        (account) =>
+          account.status === "ok" &&
+          account.pending.length === 0 &&
+          !account.exhausted,
+      );
+      if (needsFetch.length === 0) return;
+      const fetchable = needsFetch.filter((account) => {
+        const key = account.accountEmail.toLowerCase();
+        const count = refillCounts.get(key) ?? 0;
+        if (count < 4) {
+          refillCounts.set(key, count + 1);
+          return true;
+        }
+        account.status = "error";
+        account.error = {
+          code: "pagination_limit",
+          message:
+            "Mail pagination did not expose a row frontier within four provider pages.",
+          retryable: true,
+        };
+        account.exhausted = true;
+        account.providerPageToken = undefined;
+        return false;
+      });
+      if (fetchable.length === 0) continue;
+      const prior = fetchable.map((account) => ({
+        account,
+        token: account.providerPageToken,
+      }));
+      applyFetch(
+        fetchable,
+        await fetch(
+          fetchable.map((account) => ({
+            accountEmail: account.accountEmail,
+            pageToken: account.providerPageToken,
+          })),
+        ),
+      );
+      for (const { account, token } of prior) {
+        if (
+          account.status === "ok" &&
+          !account.exhausted &&
+          account.pending.length === 0 &&
+          account.providerPageToken === token
+        ) {
+          throw new Error(
+            `Mail provider pagination made no progress for ${account.accountEmail}.`,
+          );
+        }
+      }
+    }
+  };
+
+  const page: MailInventoryItem[] = [];
+  const emittedKeys = new Set<string>();
+  let pageBytes = 2; // JSON array brackets
+  const emit = (
+    account: MailInventoryAccountState,
+    item: MailInventoryItem,
+  ) => {
+    const key = `${item.accountEmail.toLowerCase()}:${item.threadId}`;
+    if (emittedKeys.has(key)) return;
+    emittedKeys.add(key);
+    page.push(item);
+    account.emittedCount += 1;
+    account.emittedThreadIds = [
+      ...(account.emittedThreadIds ?? []),
+      item.threadId,
+    ];
+  };
+
+  while (page.length < pageLimit) {
+    // A global merge is only safe when every live account has a known
+    // frontier. Refill an emptied account before emitting an older candidate
+    // from another account; otherwise an unseen newer provider row can be
+    // skipped across the page boundary.
+    await refillFrontiers();
+    const candidates = state.accounts
+      .filter((account) => account.pending.length > 0)
+      .map((account) => ({ account, item: account.pending[0] }))
+      .sort((a, b) => compareInventoryItems(a.item, b.item));
+    if (candidates.length === 0) {
+      break;
+    }
+    const winner = candidates[0];
+    const itemBytes = new TextEncoder().encode(
+      JSON.stringify(winner.item),
+    ).byteLength;
+    if (
+      page.length > 0 &&
+      pageBytes + itemBytes + 1 > PAGE_ITEMS_BUDGET_BYTES
+    ) {
+      break;
+    }
+    winner.account.pending.shift();
+    emit(winner.account, winner.item);
+    pageBytes += itemBytes + (page.length > 1 ? 1 : 0);
+  }
+
+  page.sort(compareInventoryItems);
+  state.firstPage = false;
+  return {
+    items: page,
+    hasMore: state.accounts.some(
+      (account) => account.pending.length > 0 || !account.exhausted,
+    ),
+  };
+}
+
+export async function createInventoryCursor(
+  ownerEmail: string,
+  state: MailInventoryCursorState,
+): Promise<string> {
+  const now = Date.now();
+  const id = crypto.randomUUID();
+  await getDb()
+    .insert(mailInventoryCursors)
+    .values({
+      id,
+      ownerEmail,
+      queryFingerprint: state.queryFingerprint,
+      state: JSON.stringify(state),
+      version: 1,
+      expiresAt: now + TTL_MS,
+      updatedAt: now,
+    });
+  await getDb()
+    .delete(mailInventoryCursors)
+    .where(lt(mailInventoryCursors.expiresAt, now));
+  return id;
+}
+
+/**
+ * Atomically leases a cursor without consuming it. Provider work happens only
+ * after this short-lived CAS. Failures can release the lease; success settles
+ * it into a distinct successor id (or deletes it at exhaustion).
+ */
+export async function claimInventoryCursor(
+  ownerEmail: string,
+  id: string,
+  queryFingerprint: string,
+): Promise<MailInventoryCursorClaim | null> {
+  const now = Date.now();
+  const claimId = crypto.randomUUID();
+  const staleBefore = now - CLAIM_TTL_MS;
+  const rows = await getDb()
+    .update(mailInventoryCursors)
+    .set({ claimId, claimedAt: now, updatedAt: now })
+    .where(
+      and(
+        eq(mailInventoryCursors.id, id),
+        eq(mailInventoryCursors.ownerEmail, ownerEmail),
+        eq(mailInventoryCursors.queryFingerprint, queryFingerprint),
+        gt(mailInventoryCursors.expiresAt, now),
+        or(
+          sql`${mailInventoryCursors.claimId} IS NULL`,
+          lt(mailInventoryCursors.claimedAt, staleBefore),
+        ),
+      ),
+    )
+    .returning({
+      state: mailInventoryCursors.state,
+      expiresAt: mailInventoryCursors.expiresAt,
+      version: mailInventoryCursors.version,
+    });
+  const row = rows[0];
+  if (!row || row.expiresAt <= now) return null;
+  try {
+    return {
+      id,
+      claimId,
+      ownerEmail,
+      queryFingerprint,
+      version: row.version,
+      state: JSON.parse(row.state) as MailInventoryCursorState,
+    };
+  } catch {
+    await releaseInventoryCursorClaim({
+      id,
+      claimId,
+      ownerEmail,
+      queryFingerprint,
+      version: row.version,
+      state: {} as MailInventoryCursorState,
+    });
+    return null;
+  }
+}
+
+export async function releaseInventoryCursorClaim(
+  claim: MailInventoryCursorClaim,
+): Promise<void> {
+  await getDb()
+    .update(mailInventoryCursors)
+    .set({ claimId: null, claimedAt: null, updatedAt: Date.now() })
+    .where(
+      and(
+        eq(mailInventoryCursors.id, claim.id),
+        eq(mailInventoryCursors.ownerEmail, claim.ownerEmail),
+        eq(mailInventoryCursors.queryFingerprint, claim.queryFingerprint),
+        eq(mailInventoryCursors.version, claim.version),
+        eq(mailInventoryCursors.claimId, claim.claimId),
+      ),
+    );
+}
+
+/** Atomically consumes a leased id and optionally creates its successor. */
+export async function settleInventoryCursorClaim(
+  claim: MailInventoryCursorClaim,
+  state: MailInventoryCursorState,
+  hasMore: boolean,
+): Promise<string | undefined> {
+  const db = getDb();
+  const successorId = hasMore ? crypto.randomUUID() : undefined;
+  const now = Date.now();
+  return db.transaction(async (tx: any) => {
+    const consumed = await tx
+      .delete(mailInventoryCursors)
+      .where(
+        and(
+          eq(mailInventoryCursors.id, claim.id),
+          eq(mailInventoryCursors.ownerEmail, claim.ownerEmail),
+          eq(mailInventoryCursors.queryFingerprint, claim.queryFingerprint),
+          eq(mailInventoryCursors.version, claim.version),
+          eq(mailInventoryCursors.claimId, claim.claimId),
+        ),
+      )
+      .returning({ id: mailInventoryCursors.id });
+    if (consumed.length !== 1) {
+      throw new Error("Inventory cursor lease was lost before settlement.");
+    }
+    if (successorId) {
+      await tx.insert(mailInventoryCursors).values({
+        id: successorId,
+        ownerEmail: claim.ownerEmail,
+        queryFingerprint: claim.queryFingerprint,
+        state: JSON.stringify(state),
+        version: claim.version + 1,
+        claimId: null,
+        claimedAt: null,
+        expiresAt: now + TTL_MS,
+        updatedAt: now,
+      });
+    }
+    return successorId;
+  });
+}

package/corpus/templates/mail/server/lib/list-inbox-emails.ts

@@ -45,7 +45,11 @@ export interface ListInboxEmailsParams {
   pageTokens?: Record<string, string>;
   threadFormat?: "full" | "metadata" | "minimal";
   threadCandidateLimit?: number;
+  /** Disable the extra recent-message candidate pass for bounded inventory. */
+  includeRecentMessageCandidates?: boolean;
   accountTokens: ListInboxEmailsAccountToken[];
+  /** Selected account ids are forwarded to Gmail before token refresh. */
+  accountEmails?: string[];
   labelMap: Map<string, string>;
 }
 
@@ -108,7 +112,9 @@ export async function listInboxEmails(
     pageTokens,
     threadFormat,
     threadCandidateLimit,
+    includeRecentMessageCandidates = true,
     accountTokens,
+    accountEmails,
     labelMap,
   } = params;
 
@@ -123,12 +129,25 @@ export async function listInboxEmails(
       threadFormat,
       threadCandidateLimit,
       threadRecentMessageCandidateLimit:
-        !q && (view === "inbox" || view === "unread")
+        includeRecentMessageCandidates &&
+        !q &&
+        (view === "inbox" || view === "unread")
           ? DEFAULT_THREAD_RECENT_MESSAGE_CANDIDATE_LIMIT
           : undefined,
+      accountEmails,
     });
 
-  if (messages.length === 0 && errors.length > 0) {
+  const failedAccounts = new Set(
+    errors.map((error) => error.email.toLowerCase()),
+  );
+  const everySelectedAccountFailed = [...connectedEmails].every((email) =>
+    failedAccounts.has(email),
+  );
+  if (
+    messages.length === 0 &&
+    errors.length > 0 &&
+    everySelectedAccountFailed
+  ) {
     const isQuotaError = errors.every((e) => isGmailQuotaError(e.error));
     return {
       ok: false,

package/corpus/templates/mail/server/lib/mail-connector-catalog.ts

@@ -0,0 +1,8 @@
+/**
+ * Deliberately narrow authenticated MCP surface for Mail.
+ *
+ * External callers may read inbox coverage through list-emails. Other actions
+ * remain available through the in-app agent, ask_app, or an explicit
+ * full-catalog connection; tool-search alone never makes them callable.
+ */
+export const MAIL_CONNECTOR_CATALOG = ["list-emails"] as const;

package/corpus/templates/mail/server/plugins/agent-chat.ts

@@ -6,6 +6,7 @@ import {
 } from "@agent-native/core/server";
 
 import actionsRegistry from "../../.generated/actions-registry.js";
+import { MAIL_CONNECTOR_CATALOG } from "../lib/mail-connector-catalog.js";
 
 const INITIAL_TOOL_NAMES = [
   "view-screen",
@@ -33,6 +34,7 @@ export default createAgentChatPlugin({
   actions: loadActionsFromStaticRegistry(actionsRegistry),
   appId: "mail",
   initialToolNames: INITIAL_TOOL_NAMES,
+  connectorCatalog: [...MAIL_CONNECTOR_CATALOG],
   resolveOrgId: async (event) => {
     const ctx = await getOrgContext(event);
     return ctx.orgId;
@@ -90,16 +92,9 @@ export default createAgentChatPlugin({
 
 Some less-common tool schemas are loaded on demand. Use tool-search with a specific query when you need a capability that is not already available as a direct tool.
 
-## Google Connection Check — CRITICAL
+## Deterministic Mail Reads
 
-BEFORE doing anything else, run view-screen to check if Google is connected.
-If view-screen shows 0 emails or indicates Google is not connected:
-- Do NOT run list-emails, search-emails, send-email, or any email operation scripts
-- Do NOT pretend to have access to emails
-- Tell the user: "You need to connect your Google account first. Click the 'Connect Google' button on the main screen to get started."
-- You can still answer general questions, but you cannot perform any email operations
-
-Only proceed with email operations if view-screen confirms real emails are available.
+For deterministic headless email reads, call list-emails directly in inventory/coverage mode. Do not require view-screen as a Google connection preflight: list-emails selects the connected Gmail or synthetic local-mail backend for the user and returns the relevant result. Use view-screen only when the answer depends on visible UI state, such as the active thread, selected message, draft, queue item, or current inbox view. Treat real action errors as the evidence for an unavailable connection; do not infer it from a zero-email screen.
 
 Available operations:
 - List and search emails

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

@@ -188,6 +188,26 @@ CREATE INDEX IF NOT EXISTS idx_snippets_owner_name ON snippets(owner_email, name
       sql: `ALTER TABLE queued_email_drafts ADD COLUMN IF NOT EXISTS send_claim_id TEXT;
 ALTER TABLE queued_email_drafts ADD COLUMN IF NOT EXISTS send_claimed_at ${intType()}`,
     },
+    {
+      version: 18,
+      name: "mail-inventory-cursors",
+      sql: `CREATE TABLE IF NOT EXISTS mail_inventory_cursors (
+    id TEXT PRIMARY KEY,
+    owner_email TEXT NOT NULL,
+    query_fingerprint TEXT NOT NULL,
+    state TEXT NOT NULL,
+    version ${intType()} NOT NULL DEFAULT 1,
+    expires_at ${intType()} NOT NULL,
+    updated_at ${intType()} NOT NULL
+  );
+CREATE INDEX IF NOT EXISTS idx_mail_inventory_cursors_owner_expiry ON mail_inventory_cursors(owner_email, expires_at);`,
+    },
+    {
+      version: 19,
+      name: "mail-inventory-cursor-leases",
+      sql: `ALTER TABLE mail_inventory_cursors ADD COLUMN IF NOT EXISTS claim_id TEXT;
+ALTER TABLE mail_inventory_cursors ADD COLUMN IF NOT EXISTS claimed_at ${intType()}`,
+    },
   ],
   { table: "mail_migrations" },
 );

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/notifications/routes.d.ts

@@ -13,13 +13,13 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     count?: undefined;
     updated: number;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;
@@ -28,7 +28,7 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/resources/handlers.d.ts

@@ -52,8 +52,8 @@ export declare function handleDeleteResource(event: any): Promise<{
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -74,10 +74,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
-    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
+    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,11 +27,11 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};
 //# sourceMappingURL=agent-engine-api-key-route.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.100.0",
+  "version": "0.100.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {