@agent-native/core 0.91.1 → 0.92.0

package/corpus/templates/mail/app/lib/gmail-mutation-queue.ts

@@ -0,0 +1,325 @@
+/**
+ * Debounced client-side buffer for Gmail state mutations.
+ *
+ * Rapid archive / mark-read / star must feel instant (optimistic UI), but
+ * each keypress hitting Gmail as its own modify burns quota. We keep the
+ * React Query optimistic path, then coalesce outbound calls into the
+ * existing bulk actions (one messages.batchModify per account).
+ */
+
+import { callAction } from "@agent-native/core/client";
+
+export type GmailMutationKind = "archive" | "mark-read" | "star";
+
+export interface GmailMutationTarget {
+  id: string;
+  threadId?: string;
+  accountEmail?: string;
+  /** Archive-from-label view: also remove this label. */
+  removeLabel?: string;
+  /** mark-read: true = read, false = unread. star: true = star. */
+  flag?: boolean;
+}
+
+interface QueuedMutation extends GmailMutationTarget {
+  kind: GmailMutationKind;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+}
+
+const DEFAULT_DEBOUNCE_MS = 280;
+const MAX_WAIT_MS = 1200;
+
+type FlushListener = (info: {
+  kind: GmailMutationKind;
+  count: number;
+  error?: unknown;
+}) => void;
+
+function targetKey(
+  kind: GmailMutationKind,
+  target: GmailMutationTarget,
+): string {
+  // Coalesce by message id + kind + removeLabel so re-pressing `e` on the
+  // same thread replaces the pending op instead of stacking duplicates.
+  return `${kind}:${target.id}:${target.removeLabel ?? ""}:${target.flag ?? ""}`;
+}
+
+function bulkArgs(targets: GmailMutationTarget[]) {
+  return {
+    id: targets.map((t) => t.id).join(","),
+    threadIds: targets.map((t) => t.threadId ?? "").join(","),
+    accountEmails: targets.map((t) => t.accountEmail ?? "").join(","),
+  };
+}
+
+function assertActionSuccess<T>(result: T): T {
+  if (
+    typeof result === "string" &&
+    (result.startsWith("Error:") || /failed/i.test(result.slice(0, 40)))
+  ) {
+    throw new Error(result);
+  }
+  if (
+    result &&
+    typeof result === "object" &&
+    "ok" in result &&
+    (result as { ok?: boolean }).ok === false
+  ) {
+    const message =
+      "error" in result &&
+      typeof (result as { error?: unknown }).error === "string"
+        ? (result as { error: string }).error
+        : "Action failed";
+    throw new Error(message);
+  }
+  return result;
+}
+
+class GmailMutationQueue {
+  private pending = new Map<string, QueuedMutation>();
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private maxWaitTimer: ReturnType<typeof setTimeout> | null = null;
+  private flushing: Promise<void> | null = null;
+  private firstEnqueueAt = 0;
+  private debounceMs = DEFAULT_DEBOUNCE_MS;
+  private listeners = new Set<FlushListener>();
+  private installedUnload = false;
+
+  /** Test-only: override debounce. */
+  setDebounceMs(ms: number) {
+    this.debounceMs = ms;
+  }
+
+  onFlush(listener: FlushListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Pending op count — useful in tests. */
+  size(): number {
+    return this.pending.size;
+  }
+
+  enqueue(kind: GmailMutationKind, target: GmailMutationTarget): Promise<void> {
+    this.ensureUnloadHook();
+    const key = targetKey(kind, target);
+    return new Promise<void>((resolve, reject) => {
+      const existing = this.pending.get(key);
+      if (existing) {
+        // Drop the superseded waiter as success — the newer op owns the flush.
+        existing.resolve();
+      }
+      this.pending.set(key, { kind, ...target, resolve, reject });
+      if (!this.firstEnqueueAt) this.firstEnqueueAt = Date.now();
+      this.scheduleFlush();
+    });
+  }
+
+  /**
+   * Drop a pending op without sending it (e.g. user undid an archive before
+   * the debounce window closed). Resolves waiters so callers don't hang.
+   */
+  cancel(kind: GmailMutationKind, id: string, removeLabel?: string): boolean {
+    let cancelled = false;
+    for (const [key, op] of this.pending) {
+      if (
+        op.kind === kind &&
+        op.id === id &&
+        (removeLabel === undefined || op.removeLabel === removeLabel)
+      ) {
+        this.pending.delete(key);
+        op.resolve();
+        cancelled = true;
+      }
+    }
+    if (this.pending.size === 0) this.clearTimers();
+    return cancelled;
+  }
+
+  /** Force-send everything now. Safe to call while a flush is already running. */
+  async flush(): Promise<void> {
+    this.clearTimers();
+    if (this.flushing) {
+      await this.flushing;
+      if (this.pending.size > 0) await this.flush();
+      return;
+    }
+    if (this.pending.size === 0) return;
+
+    const batch = [...this.pending.values()];
+    this.pending.clear();
+    this.firstEnqueueAt = 0;
+
+    this.flushing = this.runFlush(batch).finally(() => {
+      this.flushing = null;
+    });
+    await this.flushing;
+  }
+
+  private scheduleFlush() {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      void this.flush();
+    }, this.debounceMs);
+
+    if (!this.maxWaitTimer && this.firstEnqueueAt) {
+      const remaining = Math.max(
+        0,
+        MAX_WAIT_MS - (Date.now() - this.firstEnqueueAt),
+      );
+      this.maxWaitTimer = setTimeout(() => {
+        void this.flush();
+      }, remaining);
+    }
+  }
+
+  private clearTimers() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.maxWaitTimer) {
+      clearTimeout(this.maxWaitTimer);
+      this.maxWaitTimer = null;
+    }
+  }
+
+  private async runFlush(batch: QueuedMutation[]): Promise<void> {
+    const byKind = new Map<GmailMutationKind, QueuedMutation[]>();
+    for (const op of batch) {
+      const list = byKind.get(op.kind) ?? [];
+      list.push(op);
+      byKind.set(op.kind, list);
+    }
+
+    for (const [kind, ops] of byKind) {
+      // Group archives that share the same removeLabel so label-view archives
+      // stay correct without blocking the default bulk INBOX path.
+      if (kind === "archive") {
+        const byLabel = new Map<string, QueuedMutation[]>();
+        for (const op of ops) {
+          const labelKey = op.removeLabel ?? "";
+          const list = byLabel.get(labelKey) ?? [];
+          list.push(op);
+          byLabel.set(labelKey, list);
+        }
+        for (const [, group] of byLabel) {
+          await this.flushArchive(group);
+        }
+        continue;
+      }
+
+      if (kind === "mark-read") {
+        const byFlag = new Map<boolean, QueuedMutation[]>();
+        for (const op of ops) {
+          const flag = op.flag !== false;
+          const list = byFlag.get(flag) ?? [];
+          list.push(op);
+          byFlag.set(flag, list);
+        }
+        for (const [isRead, group] of byFlag) {
+          await this.flushMarkRead(group, isRead);
+        }
+        continue;
+      }
+
+      if (kind === "star") {
+        const byFlag = new Map<boolean, QueuedMutation[]>();
+        for (const op of ops) {
+          const flag = op.flag !== false;
+          const list = byFlag.get(flag) ?? [];
+          list.push(op);
+          byFlag.set(flag, list);
+        }
+        for (const [isStarred, group] of byFlag) {
+          await this.flushStar(group, isStarred);
+        }
+      }
+    }
+  }
+
+  private async flushArchive(ops: QueuedMutation[]): Promise<void> {
+    try {
+      await callAction("archive-email", {
+        ...bulkArgs(ops),
+        removeLabel: ops[0]?.removeLabel,
+      }).then(assertActionSuccess);
+      for (const op of ops) op.resolve();
+      this.emit({ kind: "archive", count: ops.length });
+    } catch (error) {
+      for (const op of ops) op.reject(error);
+      this.emit({ kind: "archive", count: ops.length, error });
+    }
+  }
+
+  private async flushMarkRead(
+    ops: QueuedMutation[],
+    isRead: boolean,
+  ): Promise<void> {
+    try {
+      await callAction("mark-read", {
+        ...bulkArgs(ops),
+        unread: !isRead,
+      }).then(assertActionSuccess);
+      for (const op of ops) op.resolve();
+      this.emit({ kind: "mark-read", count: ops.length });
+    } catch (error) {
+      for (const op of ops) op.reject(error);
+      this.emit({ kind: "mark-read", count: ops.length, error });
+    }
+  }
+
+  private async flushStar(
+    ops: QueuedMutation[],
+    isStarred: boolean,
+  ): Promise<void> {
+    try {
+      await callAction("star-email", {
+        ...bulkArgs(ops),
+        unstar: !isStarred,
+      }).then(assertActionSuccess);
+      for (const op of ops) op.resolve();
+      this.emit({ kind: "star", count: ops.length });
+    } catch (error) {
+      for (const op of ops) op.reject(error);
+      this.emit({ kind: "star", count: ops.length, error });
+    }
+  }
+
+  private emit(info: {
+    kind: GmailMutationKind;
+    count: number;
+    error?: unknown;
+  }) {
+    for (const listener of this.listeners) {
+      try {
+        listener(info);
+      } catch {
+        // ignore listener errors
+      }
+    }
+  }
+
+  private ensureUnloadHook() {
+    if (this.installedUnload || typeof window === "undefined") return;
+    this.installedUnload = true;
+    const flushSync = () => {
+      // Best-effort: kick flush; can't reliably await on unload.
+      void this.flush();
+    };
+    window.addEventListener("pagehide", flushSync);
+    window.addEventListener("beforeunload", flushSync);
+  }
+
+  /** Test helper: wipe pending state. */
+  resetForTests() {
+    this.clearTimers();
+    for (const op of this.pending.values()) op.resolve();
+    this.pending.clear();
+    this.firstEnqueueAt = 0;
+    this.flushing = null;
+  }
+}
+
+export const gmailMutationQueue = new GmailMutationQueue();

package/corpus/templates/mail/changelog/2026-07-08-rapid-archive-and-mark-read-now-batch-gmail-updates-so-the-i.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-08
+---
+
+Rapid archive and mark-read now batch Gmail updates so the inbox stays snappy under rate limits

package/corpus/templates/mail/package.json

@@ -80,7 +80,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",
@@ -103,7 +102,8 @@
     "tailwindcss": "catalog:",
     "tiptap-markdown": "^0.9.0",
     "tsx": "^4.20.3",
-    "typescript": "^6.0.3",
+    "typescript": "catalog:",
+    "typescript-7": "catalog:",
     "vaul": "^1.1.2",
     "vite": "catalog:",
     "vitest": "catalog:"

package/corpus/templates/plan/.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/plan/.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/plan/package.json

@@ -81,7 +81,6 @@
     "@types/node": "^24.2.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "@typescript/native-preview": "catalog:",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",
     "@xterm/xterm": "^6.0.0",
@@ -103,7 +102,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/slides/.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/slides/.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