@agent-native/core 0.102.1 → 0.103.0

package/corpus/templates/mail/actions/mark-read.ts

@@ -3,37 +3,148 @@ import { writeAppState } from "@agent-native/core/application-state";
 import { getRequestUserEmail } from "@agent-native/core/server";
 import { z } from "zod";
 
-import { markRead } from "../server/lib/email-state.js";
+import { markAllLocalUnreadRead, markRead } from "../server/lib/email-state.js";
 import {
   gmailBatchModifyByAccount,
   isConnected,
+  markAllUnreadReadForAccount,
 } from "../server/lib/google-auth.js";
 
+export const MARK_READ_DESCRIPTION =
+  'Mark explicit email IDs as read/unread, or use scope "all-unread" once to mark every unread message in one account read while preserving excluded thread IDs. Never loop mark-thread-read for broad cleanup.';
+
 export default defineAction({
-  description: "Mark one or more emails as read or unread.",
-  schema: z.object({
-    id: z.string().optional().describe("Email ID(s), comma-separated"),
-    unread: z.coerce
-      .boolean()
-      .optional()
-      .describe("Set to true to mark as unread instead of read"),
-    accountEmail: z
-      .string()
-      .optional()
-      .describe("Specific connected account to use"),
-    accountEmails: z
-      .string()
-      .optional()
-      .describe(
-        "Per-id account emails, comma-separated and positionally matched to --id (bulk UI calls only)",
-      ),
-  }),
+  description: MARK_READ_DESCRIPTION,
+  schema: z
+    .object({
+      id: z.string().optional().describe("Email ID(s), comma-separated"),
+      unread: z.coerce
+        .boolean()
+        .optional()
+        .describe("Set to true to mark explicit IDs unread instead of read"),
+      accountEmail: z
+        .string()
+        .optional()
+        .describe(
+          'Exact connected account; required when scope is "all-unread"',
+        ),
+      accountEmails: z
+        .string()
+        .optional()
+        .describe(
+          "Per-id account emails, comma-separated and positionally matched to --id (bulk UI calls only)",
+        ),
+      scope: z
+        .enum(["all-unread"])
+        .optional()
+        .describe(
+          'Mark every unread message in accountEmail read in one verified action; mutually exclusive with "id"',
+        ),
+      excludeThreadIds: z
+        .string()
+        .optional()
+        .describe(
+          'Thread IDs to leave unread, comma-separated; valid only with scope "all-unread"',
+        ),
+    })
+    .superRefine((args, ctx) => {
+      const hasIds = Boolean(args.id?.trim());
+      const hasScope = Boolean(args.scope);
+      if (hasIds === hasScope) {
+        ctx.addIssue({
+          code: "custom",
+          message: 'Provide exactly one of "id" or "scope"',
+        });
+      }
+      if (hasScope && !args.accountEmail?.trim()) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["accountEmail"],
+          message: 'accountEmail is required for scope "all-unread"',
+        });
+      }
+      if (hasScope && args.accountEmails) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["accountEmails"],
+          message: 'accountEmails cannot be used with scope "all-unread"',
+        });
+      }
+      if (hasScope && args.unread === true) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["unread"],
+          message: 'scope "all-unread" can only mark messages read',
+        });
+      }
+      if (hasIds && args.excludeThreadIds) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["excludeThreadIds"],
+          message: "excludeThreadIds can only be used with bulk scope",
+        });
+      }
+    }),
   run: async (args) => {
     const ids = args.id
       ?.split(",")
       .map((s) => s.trim())
       .filter(Boolean);
-    if (!ids || ids.length === 0) throw new Error("--id is required");
+    const hasIds = Boolean(ids?.length);
+    const hasScope = args.scope === "all-unread";
+    if (hasIds === hasScope) {
+      throw new Error('Provide exactly one of "id" or "scope"');
+    }
+
+    if (hasScope) {
+      if (!args.accountEmail?.trim()) {
+        throw new Error('accountEmail is required for scope "all-unread"');
+      }
+      if (args.accountEmails) {
+        throw new Error('accountEmails cannot be used with scope "all-unread"');
+      }
+      if (args.unread === true) {
+        throw new Error('scope "all-unread" can only mark messages read');
+      }
+
+      const ownerEmail = getRequestUserEmail();
+      if (!ownerEmail) throw new Error("no authenticated user");
+      const excludeThreadIds = (args.excludeThreadIds ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+      const input = {
+        ownerEmail,
+        accountEmail: args.accountEmail.trim(),
+        excludeThreadIds,
+      };
+      let result;
+      try {
+        result = (await isConnected(ownerEmail))
+          ? await markAllUnreadReadForAccount(input)
+          : await markAllLocalUnreadRead(input);
+      } finally {
+        // A provider verification read can fail after Gmail accepted the
+        // mutation. Always make the UI discard its pre-mutation list cache.
+        await writeAppState("refresh-signal", { ts: Date.now() });
+      }
+
+      if (!result.verificationComplete) {
+        const verificationDetail = result.verificationError
+          ? `verification failed: ${result.verificationError}`
+          : `${result.unexpectedUnreadMessages} unexpected unread messages remain`;
+        const error = new Error(
+          `Bulk mark-read incomplete for ${result.accountEmail}: matched ${result.matchedMessages}, excluded ${result.excludedMessages}, changed ${result.changedMessages}; ${result.failures.length} failed and ${verificationDetail}`,
+        ) as Error & { details?: typeof result };
+        error.details = result;
+        throw error;
+      }
+      return result;
+    }
+
+    if (!ids || ids.length === 0) {
+      throw new Error('Provide exactly one of "id" or "scope"');
+    }
     const isRead = args.unread !== true;
 
     const ownerEmail = getRequestUserEmail();

package/corpus/templates/mail/actions/mark-thread-read.ts

@@ -7,7 +7,7 @@ import { markThreadRead } from "../server/lib/email-state.js";
 
 export default defineAction({
   description:
-    "Mark all messages in a thread as read or unread. Prefer this over mark-read when acting on a whole conversation.",
+    'Mark one conversation thread as read or unread. For broad unread cleanup across many threads, call mark-read once with scope "all-unread" instead of looping this action.',
   schema: z.object({
     threadId: z.string().describe("Thread ID to mark read/unread"),
     unread: z.coerce

package/corpus/templates/mail/actions/move-email.ts

@@ -1,7 +1,6 @@
 import { defineAction } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { getRequestUserEmail } from "@agent-native/core/server";
-import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
 import { z } from "zod";
 
 import {
@@ -10,6 +9,11 @@ import {
   gmailModifyThread,
 } from "../server/lib/google-api.js";
 import { isConnected } from "../server/lib/google-auth.js";
+import {
+  readLocalEmails,
+  withLocalEmailMutationLock,
+  writeLocalEmails,
+} from "../server/lib/local-email-store.js";
 import { getAccessTokens } from "./helpers.js";
 
 type GmailLabel = { id?: string; name?: string };
@@ -80,31 +84,33 @@ export default defineAction({
     if (!ownerEmail) throw new Error("no authenticated user");
 
     if (!(await isConnected(ownerEmail))) {
-      const data = await getUserSetting(ownerEmail, "local-emails");
-      const emails =
-        data && Array.isArray((data as any).emails) ? (data as any).emails : [];
-      const idSet = new Set(ids);
-      const targetThreads = new Set<string>();
-      for (const email of emails) {
-        if (idSet.has(email.id)) targetThreads.add(email.threadId || email.id);
-      }
+      const changed = await withLocalEmailMutationLock(ownerEmail, async () => {
+        const emails = await readLocalEmails(ownerEmail);
+        const idSet = new Set(ids);
+        const targetThreads = new Set<string>();
+        for (const email of emails) {
+          if (idSet.has(email.id))
+            targetThreads.add(email.threadId || email.id);
+        }
 
-      let changed = 0;
-      const updated = emails.map((email: any) => {
-        if (!targetThreads.has(email.threadId || email.id)) return email;
-        changed++;
-        const labelIds = new Set<string>(email.labelIds ?? []);
-        labelIds.delete("inbox");
-        if (args.removeLabel) labelIds.delete(args.removeLabel);
-        labelIds.add(targetLabel);
-        return {
-          ...email,
-          isArchived: true,
-          labelIds: [...labelIds],
-        };
+        let changed = 0;
+        const updated = emails.map((email) => {
+          if (!targetThreads.has(email.threadId || email.id)) return email;
+          changed++;
+          const labelIds = new Set<string>(email.labelIds ?? []);
+          labelIds.delete("inbox");
+          if (args.removeLabel) labelIds.delete(args.removeLabel);
+          labelIds.add(targetLabel);
+          return {
+            ...email,
+            isArchived: true,
+            labelIds: [...labelIds],
+          };
+        });
+
+        await writeLocalEmails(ownerEmail, updated);
+        return changed;
       });
-
-      await putUserSetting(ownerEmail, "local-emails", { emails: updated });
       await writeAppState("refresh-signal", { ts: Date.now() });
       return `Moved ${changed} local email(s) to ${targetLabel}`;
     }

package/corpus/templates/mail/actions/send-email.ts

@@ -3,7 +3,7 @@ import { emit } from "@agent-native/core/event-bus";
 import { setOAuthDisplayName } from "@agent-native/core/oauth-tokens";
 import { getRequestUserEmail } from "@agent-native/core/server";
 import { getAppProductionUrl } from "@agent-native/core/server";
-import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
+import { getUserSetting } from "@agent-native/core/settings";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 
@@ -20,6 +20,11 @@ import {
   invalidateListCacheForOwner,
   setAccountDisplayName,
 } from "../server/lib/google-auth.js";
+import {
+  readLocalEmails,
+  withLocalEmailMutationLock,
+  writeLocalEmails,
+} from "../server/lib/local-email-store.js";
 import {
   bodyToHtml,
   buildRawEmail,
@@ -154,73 +159,73 @@ export default defineAction({
 
     const accounts = await getAccessTokens();
     if (accounts.length === 0) {
-      const data = await getUserSetting(ownerEmail, "local-emails");
-      const emails =
-        data && Array.isArray((data as any).emails) ? (data as any).emails : [];
-      const newEmail = {
-        id: `msg-${nanoid(8)}`,
-        threadId: args.replyToId
-          ? (emails.find((e: any) => e.id === args.replyToId)?.threadId ??
-            `thread-${nanoid(8)}`)
-          : `thread-${nanoid(8)}`,
-        from: { name: settings.name, email: settings.email },
-        to: args.to.split(",").map((value) => {
-          const trimmed = value.trim();
-          return { name: trimmed, email: trimmed };
-        }),
-        ...(args.cc
-          ? {
-              cc: args.cc.split(",").map((value) => {
-                const trimmed = value.trim();
-                return { name: trimmed, email: trimmed };
-              }),
-            }
-          : {}),
-        ...(args.bcc
-          ? {
-              bcc: args.bcc.split(",").map((value) => {
-                const trimmed = value.trim();
-                return { name: trimmed, email: trimmed };
-              }),
-            }
-          : {}),
-        subject: args.subject,
-        snippet: markdownPreviewSnippet(args.body),
-        body: args.body,
-        bodyHtml: bodyToHtml(args.body),
-        date: new Date().toISOString(),
-        isRead: true,
-        isStarred: false,
-        isSent: true,
-        isArchived: false,
-        isTrashed: false,
-        labelIds: ["sent"],
-        ...(resolvedAttachments.length > 0
-          ? {
-              attachments: resolvedAttachments.map((att) => ({
-                id: att.filename,
-                filename: att.originalName,
-                mimeType: att.mimeType,
-                size: att.size,
-                url: att.url,
-              })),
-            }
-          : {}),
-      };
-      emails.push(newEmail);
-      await putUserSetting(ownerEmail, "local-emails", { emails });
-      try {
-        emit(
-          "mail.message.sent",
-          {
-            messageId: newEmail.id,
-            to: args.to,
-            subject: args.subject,
-          },
-          { owner: ownerEmail },
-        );
-      } catch {}
-      return JSON.stringify(newEmail, null, 2);
+      return withLocalEmailMutationLock(ownerEmail, async () => {
+        const emails = await readLocalEmails(ownerEmail);
+        const newEmail = {
+          id: `msg-${nanoid(8)}`,
+          threadId: args.replyToId
+            ? (emails.find((e: any) => e.id === args.replyToId)?.threadId ??
+              `thread-${nanoid(8)}`)
+            : `thread-${nanoid(8)}`,
+          from: { name: settings.name, email: settings.email },
+          to: args.to.split(",").map((value) => {
+            const trimmed = value.trim();
+            return { name: trimmed, email: trimmed };
+          }),
+          ...(args.cc
+            ? {
+                cc: args.cc.split(",").map((value) => {
+                  const trimmed = value.trim();
+                  return { name: trimmed, email: trimmed };
+                }),
+              }
+            : {}),
+          ...(args.bcc
+            ? {
+                bcc: args.bcc.split(",").map((value) => {
+                  const trimmed = value.trim();
+                  return { name: trimmed, email: trimmed };
+                }),
+              }
+            : {}),
+          subject: args.subject,
+          snippet: markdownPreviewSnippet(args.body),
+          body: args.body,
+          bodyHtml: bodyToHtml(args.body),
+          date: new Date().toISOString(),
+          isRead: true,
+          isStarred: false,
+          isSent: true,
+          isArchived: false,
+          isTrashed: false,
+          labelIds: ["sent"],
+          ...(resolvedAttachments.length > 0
+            ? {
+                attachments: resolvedAttachments.map((att) => ({
+                  id: att.filename,
+                  filename: att.originalName,
+                  mimeType: att.mimeType,
+                  size: att.size,
+                  url: att.url,
+                })),
+              }
+            : {}),
+        };
+        emails.push(newEmail);
+        await writeLocalEmails(ownerEmail, emails);
+        try {
+          emit(
+            "mail.message.sent",
+            {
+              messageId: newEmail.id,
+              to: args.to,
+              subject: args.subject,
+            },
+            { owner: ownerEmail },
+          );
+        } catch {}
+        return JSON.stringify(newEmail, null, 2);
+      });
     }
 
     let selectedToken = accounts[0].accessToken;

package/corpus/templates/mail/changelog/2026-07-15-unread-inbox-cleanup-now-completes-reliably.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-15
+---
+
+Unread inbox cleanup now completes reliably in one verified operation while preserving excluded conversations.