@agent-native/core 0.85.6 → 0.86.0

package/corpus/core/src/server/poll.ts

@@ -47,6 +47,19 @@ export interface ChangeEvent {
   owner?: string;
   /** Optional org ID for org-scoped events. */
   orgId?: string;
+  /**
+   * Shareable resource type this event belongs to (e.g. "document"). When
+   * present together with `resourceId`, the per-user delivery filter
+   * (`canSeeChangeForUser`) can run an access-aware check so non-owner sharees
+   * with explicit viewer+ access receive the push instead of only the poll
+   * fallback. See the SYNC-CACHE note above `canSeeChangeForUser`.
+   */
+  resourceType?: string;
+  /**
+   * Shareable resource id this event belongs to. Paired with `resourceType`
+   * to drive the access-aware delivery check in `canSeeChangeForUser`.
+   */
+  resourceId?: string;
   [k: string]: unknown;
 }
 
@@ -202,16 +215,196 @@ export function getPollEmitter(): EventEmitter {
   return _pollEmitter;
 }
 
+/**
+ * In-memory, TTL'd access cache for the access-aware branch of
+ * `canSeeChangeForUser`. Keyed by `${userEmail}|${resourceType}|${resourceId}`.
+ *
+ * Insertion order doubles as FIFO for eviction (JS Maps preserve insertion
+ * order), so we can evict the oldest entries when we exceed the cap.
+ */
+const _accessCache = new Map<string, { allowed: boolean; checkedAt: number }>();
+/** In-flight background access checks, keyed identically, to dedupe bursts. */
+const _accessInFlight = new Set<string>();
+/** Per-resource generation bumped when shares/visibility change. */
+const _accessInvalidationEpoch = new Map<string, number>();
+/** TTL for an allowed (true) cache entry. */
+const ACCESS_CACHE_TTL_MS = 30_000;
+/**
+ * Shorter TTL for a denied (false) entry so a transient DB error (which we
+ * fail-closed on) doesn't lock a legitimate user out of the push path for the
+ * full 30s — they recover on their next event after this window.
+ */
+const ACCESS_CACHE_DENY_TTL_MS = 5_000;
+/** Max cache entries before FIFO eviction kicks in. */
+const ACCESS_CACHE_MAX = 500;
+
+function accessCacheKey(
+  userEmail: string,
+  resourceType: string,
+  resourceId: string,
+): string {
+  return `${userEmail}|${resourceType}|${resourceId}`;
+}
+
+function accessResourceKey(resourceType: string, resourceId: string): string {
+  return `${resourceType}|${resourceId}`;
+}
+
+function accessCacheTtl(allowed: boolean): number {
+  return allowed ? ACCESS_CACHE_TTL_MS : ACCESS_CACHE_DENY_TTL_MS;
+}
+
+export function invalidateCollabAccessCache(
+  resourceType: string,
+  resourceId: string,
+): void {
+  const resourceKey = accessResourceKey(resourceType, resourceId);
+  _accessInvalidationEpoch.set(
+    resourceKey,
+    (_accessInvalidationEpoch.get(resourceKey) ?? 0) + 1,
+  );
+  const suffix = `|${resourceKey}`;
+  for (const key of Array.from(_accessCache.keys())) {
+    if (key.endsWith(suffix)) _accessCache.delete(key);
+  }
+  for (const key of Array.from(_accessInFlight)) {
+    if (key.endsWith(suffix)) _accessInFlight.delete(key);
+  }
+}
+
+function setAccessCache(key: string, allowed: boolean, now: number): void {
+  // Re-insert so the key moves to the end (most-recent) for FIFO ordering.
+  _accessCache.delete(key);
+  _accessCache.set(key, { allowed, checkedAt: now });
+  if (_accessCache.size > ACCESS_CACHE_MAX) {
+    // Evict the oldest entries (front of insertion order) back under the cap.
+    const overflow = _accessCache.size - ACCESS_CACHE_MAX;
+    let removed = 0;
+    for (const oldestKey of _accessCache.keys()) {
+      _accessCache.delete(oldestKey);
+      if (++removed >= overflow) break;
+    }
+  }
+}
+
+/**
+ * Fire a background access check for a cache-miss key. Never awaited by the
+ * caller — the current event is NOT delivered (we returned false), but the
+ * result is cached so the user's NEXT event within the TTL is pushed. Dedupes
+ * concurrent checks for the same key via `_accessInFlight`.
+ */
+function scheduleAccessCheck(
+  key: string,
+  resourceType: string,
+  resourceId: string,
+  userEmail: string,
+  orgId: string | undefined,
+): void {
+  if (_accessInFlight.has(key)) return;
+  _accessInFlight.add(key);
+  const resourceKey = accessResourceKey(resourceType, resourceId);
+  const epoch = _accessInvalidationEpoch.get(resourceKey) ?? 0;
+  void (async () => {
+    try {
+      // Dynamic import to avoid a load-order/circular-import hazard: poll.ts is
+      // imported very widely, and the sharing/access module pulls in the
+      // resource registry. Importing it lazily inside this background function
+      // keeps the module graph acyclic at load time.
+      const { resolveAccess } = await import("../sharing/access.js");
+      const access = await resolveAccess(resourceType, resourceId, {
+        userEmail,
+        orgId,
+      });
+      if ((_accessInvalidationEpoch.get(resourceKey) ?? 0) !== epoch) return;
+      setAccessCache(key, access != null, Date.now());
+    } catch {
+      // Fail closed on any error (DB not ready, missing registration, etc.),
+      // but with the short deny TTL so a transient failure self-heals quickly.
+      if ((_accessInvalidationEpoch.get(resourceKey) ?? 0) !== epoch) return;
+      setAccessCache(key, false, Date.now());
+    } finally {
+      _accessInFlight.delete(key);
+    }
+  })();
+}
+
+/**
+ * Test-only: clear the access cache and in-flight set so cases don't bleed
+ * into each other. Underscore-prefixed and intentionally NOT part of the
+ * public API — do not rely on it outside tests.
+ */
+export function __resetCollabAccessCacheForTests(): void {
+  _accessCache.clear();
+  _accessInFlight.clear();
+  _accessInvalidationEpoch.clear();
+}
+
+type ChangeVisibility = "visible" | "hidden" | "pending";
+
+/**
+ * Decide whether a poll/SSE change event should be delivered to a user.
+ *
+ * SYNC-CACHE VARIANT — WHY THIS IS SYNCHRONOUS:
+ * This function is called on hot, synchronous paths: the SSE emitter callback
+ * `push(change)` in poll-events.ts (fires per event) and the
+ * `getChangesSinceForUser` loop in this file. Making it async would be
+ * invasive (it would ripple through both call sites and their emitters).
+ * Instead, for the access-aware branch we consult an in-memory cache and, on a
+ * miss, fire a NON-BLOCKING background access check and return `false` for the
+ * current event. Because the poll fallback (`getChangesSinceForUser` on the
+ * next `/poll` cycle) re-evaluates with the now-populated cache, delivery is
+ * eventually guaranteed — the only cost is that the very first event for a
+ * fresh (user, resource) pair goes over poll instead of push, and every
+ * subsequent event within the TTL is pushed.
+ *
+ * Security: a cache MISS returns `false`, so we NEVER deliver to a user before
+ * their access has been affirmatively confirmed by `resolveAccess` — the same
+ * authority that gates the HTTP routes. Errors fail closed (cached deny). The
+ * owner/org fast paths below are unchanged and evaluated first.
+ */
 export function canSeeChangeForUser(
-  event: ChangeEvent,
+  event: Pick<ChangeEvent, "owner" | "orgId" | "resourceType" | "resourceId">,
   userEmail: string,
   orgId: string | undefined,
 ): boolean {
-  // Global / unowned events: every authenticated user gets them.
-  if (!event.owner && !event.orgId) return true;
-  if (event.owner && event.owner === userEmail) return true;
-  if (event.orgId && orgId && event.orgId === orgId) return true;
-  return false;
+  return getChangeVisibilityForUser(event, userEmail, orgId) === "visible";
+}
+
+function getChangeVisibilityForUser(
+  event: Pick<ChangeEvent, "owner" | "orgId" | "resourceType" | "resourceId">,
+  userEmail: string,
+  orgId: string | undefined,
+): ChangeVisibility {
+  // Global / unowned events: every authenticated user gets them. Events that
+  // predate resource tagging (owner/org only, no resourceType) keep the exact
+  // conservative contract they had before.
+  if (!event.owner && !event.orgId && !event.resourceType) return "visible";
+  if (event.owner && event.owner === userEmail) return "visible";
+  if (event.orgId && orgId && event.orgId === orgId) return "visible";
+
+  // Access-aware branch: only when the event carries BOTH resourceType and
+  // resourceId and the owner/org fast paths above did not already grant.
+  if (event.resourceType && event.resourceId) {
+    const key = accessCacheKey(userEmail, event.resourceType, event.resourceId);
+    const cached = _accessCache.get(key);
+    const now = Date.now();
+    if (cached && now - cached.checkedAt < accessCacheTtl(cached.allowed)) {
+      // Fresh, non-expired cache hit → trust the cached decision.
+      return cached.allowed ? "visible" : "hidden";
+    }
+    // Miss or expired: do NOT deliver this event, but schedule the async check
+    // so the user's next event (or poll cycle) resolves correctly.
+    scheduleAccessCheck(
+      key,
+      event.resourceType,
+      event.resourceId,
+      userEmail,
+      orgId,
+    );
+    return "pending";
+  }
+
+  return "hidden";
 }
 
 /** Record a change event. Called by emitter listeners. */
@@ -359,10 +552,13 @@ export function getChangesSince(since: number): {
  * allowed to see.
  *
  * Filtering rules:
- *   - Events without an `owner` are deployment-global (table-level pings,
- *     screen-refresh, etc.) and visible to every authenticated user.
+ *   - Events without an `owner`/`orgId`/`resourceType` are deployment-global
+ *     (table-level pings, screen-refresh, etc.) and visible to every
+ *     authenticated user.
  *   - Events with `owner === userEmail` go to that user.
  *   - Events with `orgId === orgId` go to anyone in that org.
+ *   - Events carrying `resourceType` + `resourceId` additionally reach explicit
+ *     viewer+ sharees via the access-aware cache in `canSeeChangeForUser`.
  *   - All other owned events are filtered out.
  */
 export function getChangesSinceForUser(
@@ -373,10 +569,21 @@ export function getChangesSinceForUser(
   if (since >= _version) {
     return { version: _version, events: [] };
   }
-  const events = _buffer.filter(
-    (e) => e.version > since && canSeeChangeForUser(e, userEmail, orgId),
-  );
-  return { version: _version, events };
+  const events: ChangeEvent[] = [];
+  let version = _version;
+  for (const event of _buffer) {
+    if (event.version <= since) continue;
+    const visibility = getChangeVisibilityForUser(event, userEmail, orgId);
+    if (visibility === "visible") {
+      events.push(event);
+      continue;
+    }
+    if (visibility === "pending") {
+      version = Math.max(since, event.version - 1);
+      break;
+    }
+  }
+  return { version, events };
 }
 
 /**

package/corpus/core/src/server/schema-prompt.ts

@@ -173,6 +173,14 @@ async function introspectSqlite(db: DbExec): Promise<TableSchema[]> {
 
 // ─── Cached entry point ─────────────────────────────────────────────────────
 
+// Coalesces concurrent cache-miss introspections (same pattern as poll.ts's
+// _checkPromise): several chat turns starting inside one TTL window would
+// otherwise each run the full multi-query DB introspection in parallel.
+let _inflight: {
+  key: string;
+  promise: Promise<{ tables: TableSchema[]; dialect: "postgres" | "sqlite" }>;
+} | null = null;
+
 async function getSchema(): Promise<{
   tables: TableSchema[];
   dialect: "postgres" | "sqlite";
@@ -182,16 +190,27 @@ async function getSchema(): Promise<{
   if (_cache && _cache.key === key && _cache.expires > now) {
     return { tables: _cache.tables, dialect: _cache.dialect };
   }
+  if (_inflight && _inflight.key === key) {
+    return _inflight.promise;
+  }
 
-  const db = getDbExec();
-  const dialect: "postgres" | "sqlite" = isPostgres() ? "postgres" : "sqlite";
-  const tables =
-    dialect === "postgres"
-      ? await introspectPostgres(db)
-      : await introspectSqlite(db);
-
-  _cache = { key, expires: now + CACHE_TTL_MS, tables, dialect };
-  return { tables, dialect };
+  const promise = (async () => {
+    const db = getDbExec();
+    const dialect: "postgres" | "sqlite" = isPostgres() ? "postgres" : "sqlite";
+    const tables =
+      dialect === "postgres"
+        ? await introspectPostgres(db)
+        : await introspectSqlite(db);
+
+    _cache = { key, expires: Date.now() + CACHE_TTL_MS, tables, dialect };
+    return { tables, dialect };
+  })();
+  _inflight = { key, promise };
+  try {
+    return await promise;
+  } finally {
+    if (_inflight?.promise === promise) _inflight = null;
+  }
 }
 
 /** Manually drop the cache — useful from tests or after running a migration. */

package/corpus/core/src/settings/store.ts

@@ -3,9 +3,32 @@ import { EventEmitter } from "events";
 import { getDbExec, isPostgres, intType } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
+import { getRequestContext } from "../server/request-context.js";
 
 let _initPromise: Promise<void> | undefined;
 
+// Per-request memoization of settings reads, keyed on the active
+// AsyncLocalStorage RequestContext (WeakMap → freed with the request). One
+// action request can read the same setting several times (org resolution,
+// guards, the action body), and each read is a network round trip on
+// serverless Postgres. Mirrors the per-request session/org caches on
+// event.context. The cache holds the raw JSON string and re-parses per hit
+// so callers can't mutate a shared object; writes in the same request are
+// written through, while other in-flight requests keep their snapshot for
+// their own (short) lifetime.
+const _requestSettingsCache = new WeakMap<object, Map<string, string | null>>();
+
+function requestSettingsCache(): Map<string, string | null> | null {
+  const ctx = getRequestContext();
+  if (!ctx || typeof ctx !== "object") return null;
+  let cache = _requestSettingsCache.get(ctx);
+  if (!cache) {
+    cache = new Map();
+    _requestSettingsCache.set(ctx, cache);
+  }
+  return cache;
+}
+
 const _emitter = new EventEmitter();
 
 export function getSettingsEmitter(): EventEmitter {
@@ -83,6 +106,11 @@ async function ensureTable(): Promise<void> {
 export async function getSetting(
   key: string,
 ): Promise<Record<string, unknown> | null> {
+  const cache = requestSettingsCache();
+  if (cache?.has(key)) {
+    const cached = cache.get(key);
+    return cached == null ? null : JSON.parse(cached);
+  }
   await ensureTable();
   const client = getDbExec();
   const table = settingsTable();
@@ -90,8 +118,9 @@ export async function getSetting(
     sql: `SELECT value FROM ${table} WHERE key = ?`,
     args: [key],
   });
-  if (rows.length === 0) return null;
-  return JSON.parse(rows[0].value as string);
+  const raw = rows.length === 0 ? null : (rows[0].value as string);
+  cache?.set(key, raw);
+  return raw == null ? null : JSON.parse(raw);
 }
 
 export interface StoreWriteOptions {
@@ -113,6 +142,7 @@ export async function putSetting(
       : `INSERT OR REPLACE INTO ${table} (key, value, updated_at) VALUES (?, ?, ?)`,
     args: [key, JSON.stringify(value), Date.now()],
   });
+  requestSettingsCache()?.set(key, JSON.stringify(value));
   _emitter.emit("settings", {
     source: "settings",
     type: "change",
@@ -132,6 +162,7 @@ export async function deleteSetting(
     sql: `DELETE FROM ${table} WHERE key = ?`,
     args: [key],
   });
+  requestSettingsCache()?.set(key, null);
   if (result.rowsAffected > 0) {
     _emitter.emit("settings", {
       source: "settings",

package/corpus/core/src/sharing/actions/set-resource-visibility.ts

@@ -2,6 +2,7 @@ import { eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { defineAction } from "../../action.js";
+import { invalidateCollabAccessCache } from "../../server/poll.js";
 import {
   assertAccess,
   currentAccess,
@@ -79,6 +80,7 @@ export default defineAction({
       .update(reg.resourceTable)
       .set(update)
       .where(eq(reg.resourceTable.id, args.resourceId));
+    invalidateCollabAccessCache(args.resourceType, args.resourceId);
     await notifyExtensionShareChanged(
       args.resourceType,
       args.resourceId,

package/corpus/core/src/sharing/actions/share-resource.ts

@@ -6,6 +6,7 @@ import { getDbExec } from "../../db/client.js";
 import { getAppProductionUrl } from "../../server/app-url.js";
 import { renderEmail, emailStrong } from "../../server/email-template.js";
 import { sendEmail, isEmailConfigured } from "../../server/email.js";
+import { invalidateCollabAccessCache } from "../../server/poll.js";
 import { getRequestUserEmail } from "../../server/request-context.js";
 import { assertAccess, ForbiddenError } from "../access.js";
 import { requireShareableResource } from "../registry.js";
@@ -235,6 +236,7 @@ export default defineAction({
         .update(reg.sharesTable)
         .set({ role: args.role })
         .where(eq(reg.sharesTable.id, existing.id));
+      invalidateCollabAccessCache(args.resourceType, args.resourceId);
       await notifyExtensionShareChanged(
         args.resourceType,
         args.resourceId,
@@ -253,6 +255,7 @@ export default defineAction({
       createdBy: actor,
       createdAt: new Date().toISOString(),
     });
+    invalidateCollabAccessCache(args.resourceType, args.resourceId);
     await notifyExtensionShareChanged(
       args.resourceType,
       args.resourceId,

package/corpus/core/src/sharing/actions/unshare-resource.ts

@@ -2,6 +2,7 @@ import { and, eq, sql, type SQL } from "drizzle-orm";
 import { z } from "zod";
 
 import { defineAction } from "../../action.js";
+import { invalidateCollabAccessCache } from "../../server/poll.js";
 import { assertAccess } from "../access.js";
 import { requireShareableResource } from "../registry.js";
 import {
@@ -60,6 +61,7 @@ export default defineAction({
           principalIdMatches(reg.sharesTable, args.principalType, principalId),
         ),
       );
+    invalidateCollabAccessCache(args.resourceType, args.resourceId);
     await notifyExtensionShareChanged(
       args.resourceType,
       args.resourceId,

package/corpus/core/src/styles/agent-native.css

@@ -735,11 +735,6 @@
   top: calc(100% + 0.5rem);
 }
 
-[data-agent-empty-state="compact-setup"] > .agent-chat-scroll {
-  flex: 0 0 auto;
-  overflow: visible;
-}
-
 [data-agent-empty-state="compact-setup"] .agent-empty-state {
   height: auto;
   min-height: 5rem;

package/corpus/core/src/templates/default/.agents/skills/real-time-collab/SKILL.md

@@ -249,34 +249,97 @@ type PatchDeckOp =
 Concurrent edits to different slides both succeed at the action level; there
 is no whole-deck LWW. Forms use the same shape with field-level ops.
 
-## Collaborative Undo Scoping (Y.UndoManager)
+## Agent Presence & Lingering Edit Highlights
+
+The agent is a *visible* collaborator, not a silent content-swapper. Core
+handles most of this automatically:
+
+- **Auto-presence on agent writes** — any `applyText` / `searchAndReplace` /
+  `applyJson` / `applyPatchOps` call with `requestSource: "agent"` publishes
+  an agent awareness entry plus a `recentEdits` attribution describing what
+  changed. Actions that route writes through the collab layer get full
+  presence UX with zero extra wiring.
+- **Linger** — `agentLeaveDocument` (and the auto-presence path) keeps the
+  agent's awareness entry alive for ~6s (`AGENT_PRESENCE_LINGER_MS`) after the
+  last edit so viewers see who just changed what. Pass `{ lingerMs: 0 }` to
+  clear immediately. On serverless the linger degrades to the 30s awareness
+  expiry.
+- **`agentTouchDocument(docId, { edit, metadata })`** — refcount-neutral
+  presence + attribution for actions that write SQL directly (no collab doc).
+  `edit.descriptor` is one of `{kind:"text",quote}`, `{kind:"selector",selector}`,
+  `{kind:"paths",paths}`, `{kind:"doc"}`.
+- **Durable across instances** — awareness is mirrored to the additive
+  `_collab_awareness` table, so presence written by an action in one
+  serverless invocation is visible to clients polling any other instance.
+
+Client rendering:
+
+```tsx
+import {
+  usePresence, useRecentEdits, RecentEditHighlights,
+  PresenceBar, LiveCursorOverlay, RemoteSelectionRings,
+} from "@agent-native/core/client";
+
+const { others, setPresence } = usePresence(awareness, ydoc?.clientID);
+const recentEdits = useRecentEdits(others); // non-expired, ~6s TTL
+
+<RecentEditHighlights
+  edits={recentEdits}
+  containerRef={containerRef}
+  resolveRect={(edit) => /* map descriptor → DOMRect, or null */ null}
+/>
+```
+
+Humans get the same treatment: call `publishRecentEdit(awareness, { descriptor })`
+from local mutation paths so peers see lingering highlights for human edits
+too. `CollabUser.avatarUrl` puts faces on avatars, cursors, and edit tags.
+
+## Per-User Undo (never revert someone else's work)
 
-Scope undo/redo to the local user's own edits so peer and agent changes are
-never accidentally reversed:
+Undo must only reverse the local user's edits — and must never restore a
+whole-document snapshot (that clobbers concurrent edits by peers/the agent).
+Core ships two primitives:
+
+**Yjs surfaces — `useCollabUndo`** (wraps `Y.UndoManager` lifecycle):
 
 ```ts
-import * as Y from "yjs";
+import { useCollabUndo } from "@agent-native/core/client";
+
+const { undo, redo, canUndo, canRedo, transactLocal, localOrigin } =
+  useCollabUndo({
+    ydoc,
+    scope: (doc) => doc.getText("content"),
+    captureTimeout: 500,
+    enableKeyboardShortcuts: true, // Mod+Z / Shift+Mod+Z / Mod+Y
+  });
 
-const LOCAL_EDIT_ORIGIN = "local";
+// Tag every local mutation so it is captured:
+transactLocal(() => { /* mutate shared types */ });
+```
 
-const undoManager = new Y.UndoManager(ydoc.getText("content"), {
-  trackedOrigins: new Set([LOCAL_EDIT_ORIGIN]),
-  captureTimeout: 800, // coalesces rapid slider drags into one undo step
-});
+Remote (`"remote"`) and agent (`"agent"`/`"server"`) origins are never
+captured. The manager is recreated/destroyed automatically when `ydoc`
+changes. (TipTap's Collaboration extension already provides this behavior
+for its own editor content.)
 
-// Mark local edits with the tracked origin
-ydoc.transact(() => {
-  // apply local change
-}, LOCAL_EDIT_ORIGIN);
+**Op-based surfaces (slides/forms) — `useLocalOpUndo`**: record inverse
+granular ops for each local mutation; undo replays the inverse ops through
+your normal granular mutation path:
 
-undoManager.undo(); // only reverses LOCAL_EDIT_ORIGIN transactions
-undoManager.redo();
+```ts
+const { push, undo, redo, canUndo, canRedo } = useLocalOpUndo({
+  apply: (ops) => applyGranularOps(ops), // your patch path
+});
+
+push({
+  undo: [{ type: "patch", slideId, fields: prevFields }],
+  redo: [{ type: "patch", slideId, fields: nextFields }],
+  coalesceKey: `${slideId}:content`, // merge rapid bursts into one step
+});
 ```
 
-Rules:
-- Pass a `Set` to `trackedOrigins` — not an array.
-- Remote (`"remote"`) and agent (`"agent"`) origins are never captured.
-- Recreate and destroy the manager when the active document changes.
+Entries whose target no longer exists should fail soft (skip), never reset
+the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 

package/corpus/core/src/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/core/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |

package/corpus/core/src/templates/default/package.json

@@ -23,8 +23,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-query": "^5.99.2",
@@ -38,7 +38,7 @@
     "oxfmt": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^4.1.18",

package/corpus/core/src/templates/workspace-core/.agents/skills/client-methods/SKILL.md

@@ -36,8 +36,16 @@ method gives the UI, docs, and future agents one stable contract.
    | Agent chat context | Agent chat client helpers from `@agent-native/core/client` |
    | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
    | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` |
+   | Listen to the shared SSE/poll change stream | `subscribeSyncEvents` from `@agent-native/core/client` — never open a second `EventSource` to `/_agent-native/events` |
    | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |
 
+   Action fetch behavior: every `useActionQuery` / `useActionMutation` /
+   `callAction` request is bounded by a 60s timeout, and timeouts surface as
+   errors instead of retrying silently. `useActionQuery` cancels superseded
+   requests automatically via React Query's abort signal. For imperative
+   calls, `callAction(name, params, { method, signal, timeoutMs })` accepts an
+   `AbortSignal` and a `timeoutMs` override for legitimately long operations.
+
 2. If no client API exists, add the narrowest helper at the boundary.
 
    - Put shared framework helpers in `packages/core/src/client/*`.