@agent-native/core 0.91.1 → 0.92.0

package/corpus/templates/forms/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/forms/package.json

@@ -74,7 +74,6 @@
     "@types/node": "^24.2.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "@typescript/native-preview": "catalog:",
     "@vitejs/plugin-react-swc": "^4.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -88,7 +87,8 @@
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "catalog:",
-    "typescript": "^6.0.3",
+    "typescript": "catalog:",
+    "typescript-7": "catalog:",
     "vite": "catalog:",
     "vitest": "catalog:"
   },

package/corpus/templates/macros/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/macros/package.json

@@ -67,7 +67,6 @@
     "@types/node": "^24.2.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "@typescript/native-preview": "catalog:",
     "@vitejs/plugin-react-swc": "^4.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -87,7 +86,8 @@
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "catalog:",
     "tsx": "^4.20.3",
-    "typescript": "^6.0.3",
+    "typescript": "catalog:",
+    "typescript-7": "catalog:",
     "vaul": "^1.1.2",
     "vite": "catalog:",
     "vitest": "catalog:"

package/corpus/templates/mail/.agents/skills/self-modifying-code/SKILL.md

@@ -28,7 +28,19 @@ Not all modifications are equal. Use this to decide what level of care is needed
 | 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
 | 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
 | 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
-| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
+
+Tier 4 includes **all** of the following — not only editing package source:
+
+- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
+- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
+  target any `@agent-native/*` package
+- Local patches, vendored copies, or invented "dispatch/core behavior"
+  shims meant to paper over a version skew or failed upgrade
+
+When an older branch needs current packages, use **`agent-native upgrade`**
+(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
+**app** code or stop and ask — do not patch the framework.
 
 ## Git Checkpoint Pattern
 
@@ -74,13 +86,19 @@ inline strings in components.
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
-- Don't modify `@agent-native/core` package internals
+- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
+  `@agent-native/*` package internals (including under `node_modules`)
+- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
+  `@agent-native/*` to "make the app run" after a version bump
+- Don't invent local dispatch/core behavior overrides when upgrade fails —
+  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
 - Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
 - Don't skip the typecheck/lint step after editing source code
 - Don't make source changes without a git checkpoint to roll back to
 
 ## Related Skills
 
+- **upgrade-agent-native** — supported path to bring an older app/workspace current
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/corpus/templates/mail/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/mail/app/hooks/use-emails.ts

@@ -13,10 +13,11 @@ import {
   useMutation,
   useQueryClient,
 } from "@tanstack/react-query";
-import { useMemo, useRef } from "react";
+import { useMemo } from "react";
 import { toast } from "sonner";
 
 import { useAccountFilter } from "@/hooks/use-account-filter";
+import { gmailMutationQueue } from "@/lib/gmail-mutation-queue";
 import { TAB_ID } from "@/lib/tab-id";
 import {
   useThreadCache,
@@ -636,14 +637,21 @@ export function useMarkRead() {
       id,
       isRead,
       accountEmail,
+      threadId,
     }: {
       id: string;
       isRead: boolean;
       accountEmail?: string;
+      threadId?: string;
     }) =>
-      callAction("mark-read", { id, unread: !isRead, accountEmail }).then(
-        assertActionSuccess,
-      ),
+      // Buffer + batch via Gmail messages.batchModify so rapid open/mark-read
+      // (and e-e-e archive) stay snappy without burning quota per keypress.
+      gmailMutationQueue.enqueue("mark-read", {
+        id,
+        threadId,
+        accountEmail,
+        flag: isRead,
+      }),
     onMutate: async ({ id, isRead }) => {
       await qc.cancelQueries({ queryKey: ["emails"] });
       const previous = qc.getQueriesData<InfiniteEmails>({
@@ -667,22 +675,9 @@ export function useMarkRead() {
 
 export function useMarkThreadRead() {
   const qc = useQueryClient();
-  // Per-thread pending entries — using a Map so concurrent mutations for different
-  // threads don't overwrite each other's pending entries.
-  const pendingByThread = useRef(
-    new Map<string, { id: string; accountEmail?: string }[]>(),
-  );
   return useMutation({
-    mutationFn: async (threadId: string) => {
-      const entries = pendingByThread.current.get(threadId) ?? [];
-      pendingByThread.current.delete(threadId);
-      if (entries.length > 0) {
-        await callAction("mark-thread-read", {
-          threadId,
-          accountEmail: entries[0]?.accountEmail,
-        }).then(assertActionSuccess);
-      }
-    },
+    mutationFn: (threadId: string) =>
+      callAction("mark-thread-read", { threadId }).then(assertActionSuccess),
     onMutate: async (threadId) => {
       await qc.cancelQueries({ queryKey: ["emails"] });
       const previous = qc.getQueriesData<InfiniteEmails>({
@@ -691,11 +686,9 @@ export function useMarkThreadRead() {
       // Capture unread entries BEFORE optimistic update
       const allEmails =
         previous.flatMap(([, data]) => flattenInfiniteEmails(data)) ?? [];
-      const unreadEntries = allEmails
+      const unreadIds = allEmails
         .filter((e) => (e.threadId || e.id) === threadId && !e.isRead)
-        .map((e) => ({ id: e.id, accountEmail: e.accountEmail }));
-      pendingByThread.current.set(threadId, unreadEntries);
-      const unreadIds = unreadEntries.map((e) => e.id);
+        .map((e) => e.id);
       const previousThread = getCachedThread(threadId);
       // Set overrides so refetches don't revert read state
       for (const id of unreadIds) {
@@ -737,17 +730,19 @@ export function useToggleStar() {
       id,
       isStarred,
       accountEmail,
+      threadId,
     }: {
       id: string;
       isStarred: boolean;
       accountEmail?: string;
       threadId?: string;
     }) =>
-      callAction("star-email", {
+      gmailMutationQueue.enqueue("star", {
         id,
-        unstar: !isStarred,
+        threadId,
         accountEmail,
-      }).then(assertActionSuccess),
+        flag: isStarred,
+      }),
     onMutate: async ({ id, isStarred, threadId }) => {
       await qc.cancelQueries({ queryKey: ["emails"] });
       const previous = qc.getQueriesData<InfiniteEmails>({
@@ -802,12 +797,12 @@ export function useArchiveEmail() {
       removeLabel?: string;
       threadId?: string;
     }) =>
-      callAction("archive-email", {
+      gmailMutationQueue.enqueue("archive", {
         id,
         accountEmail,
         removeLabel,
         threadId,
-      }).then(assertActionSuccess),
+      }),
     onMutate: async ({
       id,
       threadId: hintedThreadId,
@@ -848,8 +843,13 @@ export function useArchiveEmail() {
 export function useUnarchiveEmail() {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: (id: string) =>
-      callAction("unarchive-email", { id }).then(assertActionSuccess),
+    mutationFn: (id: string) => {
+      // Undo often lands inside the debounce window — drop the pending
+      // archive so we never send a modify we immediately reverse.
+      const cancelled = gmailMutationQueue.cancel("archive", id);
+      if (cancelled) return Promise.resolve("cancelled-pending-archive");
+      return callAction("unarchive-email", { id }).then(assertActionSuccess);
+    },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["emails"] }),
   });
 }
@@ -924,10 +924,14 @@ export function useBulkArchiveEmails() {
   const t = useT();
   return useMutation({
     mutationFn: ({ targets, removeLabel }: BulkArchiveVars) =>
-      callAction("archive-email", {
-        ...bulkActionArgs(targets),
-        removeLabel,
-      }).then(assertActionSuccess),
+      Promise.all(
+        targets.map((target) =>
+          gmailMutationQueue.enqueue("archive", {
+            ...target,
+            removeLabel,
+          }),
+        ),
+      ).then(() => `Queued archive for ${targets.length} email(s)`),
     onMutate: async ({ targets }: BulkArchiveVars) => {
       await qc.cancelQueries({ queryKey: ["emails"] });
       const previous = qc.getQueriesData<InfiniteEmails>({
@@ -1008,7 +1012,7 @@ export function useBulkTrashEmails() {
   });
 }
 
-/** Bulk star/unstar: one action call, one optimistic override per message. */
+/** Bulk star/unstar: queued + batched Gmail modify, one optimistic override. */
 export function useBulkToggleStar() {
   const qc = useQueryClient();
   return useMutation({
@@ -1019,10 +1023,14 @@ export function useBulkToggleStar() {
       targets: BulkEmailTarget[];
       isStarred: boolean;
     }) =>
-      callAction("star-email", {
-        ...bulkActionArgs(targets),
-        unstar: !isStarred,
-      }).then(assertActionSuccess),
+      Promise.all(
+        targets.map((target) =>
+          gmailMutationQueue.enqueue("star", {
+            ...target,
+            flag: isStarred,
+          }),
+        ),
+      ).then(() => `Queued star for ${targets.length} email(s)`),
     onMutate: async ({ targets, isStarred }) => {
       await qc.cancelQueries({ queryKey: ["emails"] });
       const previous = qc.getQueriesData<InfiniteEmails>({
@@ -1045,7 +1053,7 @@ export function useBulkToggleStar() {
   });
 }
 
-/** Bulk mark read/unread: one action call, one optimistic override per message. */
+/** Bulk mark read/unread: queued + batched Gmail modify, one optimistic override. */
 export function useBulkMarkRead() {
   const qc = useQueryClient();
   return useMutation({
@@ -1056,10 +1064,14 @@ export function useBulkMarkRead() {
       targets: BulkEmailTarget[];
       isRead: boolean;
     }) =>
-      callAction("mark-read", {
-        ...bulkActionArgs(targets),
-        unread: !isRead,
-      }).then(assertActionSuccess),
+      Promise.all(
+        targets.map((target) =>
+          gmailMutationQueue.enqueue("mark-read", {
+            ...target,
+            flag: isRead,
+          }),
+        ),
+      ).then(() => `Queued mark-read for ${targets.length} email(s)`),
     onMutate: async ({ targets, isRead }) => {
       await qc.cancelQueries({ queryKey: ["emails"] });
       const previous = qc.getQueriesData<InfiniteEmails>({