@agent-native/core 0.91.2 → 0.92.1

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

@@ -23,7 +23,8 @@ import {
   type ActionChangeTarget,
 } from "../action-change-marker.js";
 import { getAppStateEmitter } from "../application-state/emitter.js";
-import { getDbExec } from "../db/client.js";
+import { getDbExec, isPostgres } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import {
   EXTENSION_CHANGE_MARKER_KEY,
   parseExtensionChangeMarker,
@@ -66,11 +67,17 @@ export interface ChangeEvent {
 // In-memory ring buffer of recent changes. Kept small since clients
 // poll frequently (every 2-3s) and only need events since their last poll.
 const MAX_BUFFER = 200;
+const DURABLE_READ_LIMIT = 1000;
+const DURABLE_RETENTION_MS = 24 * 60 * 60 * 1000;
+const LEGACY_DB_CHECK_INTERVAL_MS = 1000;
+const DURABLE_LEGACY_DB_CHECK_INTERVAL_MS = 30_000;
 let _version = 0;
 const _buffer: ChangeEvent[] = [];
 export const POLL_CHANGE_EVENT = "poll-change";
 const _pollEmitter = new EventEmitter();
 _pollEmitter.setMaxListeners(0);
+let _syncEventsInitPromise: Promise<boolean> | undefined;
+let _lastDurablePrune = 0;
 
 /**
  * Whether we've seeded _version from the DB. In serverless (Netlify,
@@ -144,6 +151,130 @@ function sqlWatermarkValue(value: unknown): string | number | undefined {
   return undefined;
 }
 
+function syncEventsDisabled(): boolean {
+  return (
+    process.env.AGENT_NATIVE_SYNC_EVENTS_DISABLE === "1" ||
+    (process.env.VITEST === "true" &&
+      process.env.AGENT_NATIVE_SYNC_EVENTS_ENABLE_IN_TESTS !== "1")
+  );
+}
+
+async function ensureSyncEventsTable(): Promise<boolean> {
+  if (syncEventsDisabled()) return false;
+  if (!_syncEventsInitPromise) {
+    _syncEventsInitPromise = (async () => {
+      const client = getDbExec();
+      const createSql = `
+        CREATE TABLE IF NOT EXISTS sync_events (
+          id TEXT PRIMARY KEY,
+          version BIGINT NOT NULL,
+          event_json TEXT NOT NULL,
+          source TEXT NOT NULL,
+          type TEXT NOT NULL,
+          event_key TEXT,
+          owner TEXT,
+          org_id TEXT,
+          resource_type TEXT,
+          resource_id TEXT,
+          created_at BIGINT NOT NULL
+        )
+      `;
+
+      if (isPostgres()) {
+        await ensureTableExists("sync_events", createSql);
+        await ensureIndexExists(
+          "sync_events_version_idx",
+          "CREATE INDEX IF NOT EXISTS sync_events_version_idx ON sync_events (version)",
+        );
+        await ensureIndexExists(
+          "sync_events_owner_version_idx",
+          "CREATE INDEX IF NOT EXISTS sync_events_owner_version_idx ON sync_events (owner, version)",
+        );
+        await ensureIndexExists(
+          "sync_events_org_version_idx",
+          "CREATE INDEX IF NOT EXISTS sync_events_org_version_idx ON sync_events (org_id, version)",
+        );
+        return true;
+      }
+
+      await client.execute(createSql);
+      for (const ddl of [
+        "CREATE INDEX IF NOT EXISTS sync_events_version_idx ON sync_events (version)",
+        "CREATE INDEX IF NOT EXISTS sync_events_owner_version_idx ON sync_events (owner, version)",
+        "CREATE INDEX IF NOT EXISTS sync_events_org_version_idx ON sync_events (org_id, version)",
+      ]) {
+        try {
+          await client.execute(ddl);
+        } catch {
+          // Index already exists or the dialect rejected a duplicate.
+        }
+      }
+      return true;
+    })().catch(() => {
+      _syncEventsInitPromise = undefined;
+      return false;
+    });
+  }
+  return _syncEventsInitPromise;
+}
+
+function durableEventId(version: number): string {
+  return `${version}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+async function pruneDurableEvents(client: ReturnType<typeof getDbExec>) {
+  const now = Date.now();
+  if (now - _lastDurablePrune < 5 * 60 * 1000) return;
+  _lastDurablePrune = now;
+  await client
+    .execute({
+      sql: "DELETE FROM sync_events WHERE created_at < ?",
+      args: [now - DURABLE_RETENTION_MS],
+    })
+    .catch(() => {});
+}
+
+async function persistSyncEvent(event: ChangeEvent): Promise<void> {
+  if (!(await ensureSyncEventsTable())) return;
+  const client = getDbExec();
+  await client
+    .execute({
+      sql: isPostgres()
+        ? `INSERT INTO sync_events (id, version, event_json, source, type, event_key, owner, org_id, resource_type, resource_id, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT (id) DO NOTHING`
+        : `INSERT OR IGNORE INTO sync_events (id, version, event_json, source, type, event_key, owner, org_id, resource_type, resource_id, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      args: [
+        durableEventId(event.version),
+        event.version,
+        JSON.stringify(event),
+        event.source,
+        event.type,
+        event.key ?? null,
+        event.owner ?? null,
+        event.orgId ?? null,
+        event.resourceType ?? null,
+        event.resourceId ?? null,
+        Date.now(),
+      ],
+    })
+    .catch(() => {});
+  await pruneDurableEvents(client);
+}
+
+async function readMaxSyncEventVersion(): Promise<number> {
+  if (!(await ensureSyncEventsTable())) return 0;
+  try {
+    const result = await getDbExec().execute(
+      "SELECT MAX(version) as max_version FROM sync_events",
+    );
+    return timestampValue(result.rows[0]?.max_version);
+  } catch {
+    return 0;
+  }
+}
+
 async function readMaxUpdatedAtRaw(
   db: {
     execute: (
@@ -340,6 +471,16 @@ export function __resetCollabAccessCacheForTests(): void {
 }
 
 type ChangeVisibility = "visible" | "hidden" | "pending";
+type ChangeReadResult = {
+  version: number;
+  events: ChangeEvent[];
+  /**
+   * True when the returned version is an intentional cursor stop, not the
+   * source high-water mark. This happens when access is still pending or when a
+   * durable page hit the read limit and more rows may remain unread.
+   */
+  cursorLimited?: boolean;
+};
 
 /**
  * Decide whether a poll/SSE change event should be delivered to a user.
@@ -424,6 +565,7 @@ export function recordChange(event: {
     _buffer.splice(0, _buffer.length - MAX_BUFFER);
   }
   _pollEmitter.emit(POLL_CHANGE_EVENT, entry);
+  void persistSyncEvent(entry);
 }
 
 function extensionTargetKey(target: ExtensionChangeTarget): string | null {
@@ -565,7 +707,7 @@ export function getChangesSinceForUser(
   since: number,
   userEmail: string,
   orgId: string | undefined,
-): { version: number; events: ChangeEvent[] } {
+): ChangeReadResult {
   if (since >= _version) {
     return { version: _version, events: [] };
   }
@@ -580,12 +722,139 @@ export function getChangesSinceForUser(
     }
     if (visibility === "pending") {
       version = Math.max(since, event.version - 1);
-      break;
+      return { version, events, cursorLimited: true };
     }
   }
   return { version, events };
 }
 
+async function getDurableChangesSinceForUser(
+  since: number,
+  userEmail: string,
+  orgId: string | undefined,
+): Promise<ChangeReadResult> {
+  if (since <= 0 || !(await ensureSyncEventsTable())) {
+    return { version: _version, events: [] };
+  }
+
+  try {
+    const result = await getDbExec().execute({
+      sql: `SELECT version, event_json FROM sync_events WHERE version > ? ORDER BY version ASC LIMIT ?`,
+      args: [since, DURABLE_READ_LIMIT + 1],
+    });
+    const events: ChangeEvent[] = [];
+    let version = Math.max(_version, since);
+    let lastDurableVersion = since;
+    const rows = result.rows.slice(0, DURABLE_READ_LIMIT);
+    const overflowVersion = timestampValue(
+      result.rows[DURABLE_READ_LIMIT]?.version,
+    );
+
+    for (const row of rows) {
+      const rawVersion = timestampValue(row.version);
+      if (rawVersion > lastDurableVersion) lastDurableVersion = rawVersion;
+      if (rawVersion > version) version = rawVersion;
+      let event: ChangeEvent | null = null;
+      try {
+        const parsed = JSON.parse(String(row.event_json));
+        if (
+          parsed &&
+          typeof parsed === "object" &&
+          typeof parsed.source === "string" &&
+          typeof parsed.type === "string"
+        ) {
+          event = {
+            ...(parsed as ChangeEvent),
+            version: rawVersion || (parsed as ChangeEvent).version,
+          };
+        }
+      } catch {
+        event = null;
+      }
+      if (!event) continue;
+
+      const visibility = getChangeVisibilityForUser(event, userEmail, orgId);
+      if (visibility === "visible") {
+        events.push(event);
+        continue;
+      }
+      if (visibility === "pending") {
+        return {
+          version: Math.max(since, event.version - 1),
+          events,
+          cursorLimited: true,
+        };
+      }
+    }
+
+    if (rows.length >= DURABLE_READ_LIMIT) {
+      if (overflowVersion === lastDurableVersion) {
+        const boundaryVersion = lastDurableVersion;
+        return {
+          version: Math.max(since, boundaryVersion - 1),
+          events: events.filter((event) => event.version < boundaryVersion),
+          cursorLimited: true,
+        };
+      }
+      return {
+        version: Math.max(since, lastDurableVersion),
+        events,
+        cursorLimited: true,
+      };
+    }
+
+    return { version, events };
+  } catch {
+    return { version: _version, events: [] };
+  }
+}
+
+async function getCombinedChangesSinceForUser(
+  since: number,
+  userEmail: string,
+  orgId: string | undefined,
+  useDurableEvents: boolean,
+): Promise<{ version: number; events: ChangeEvent[] }> {
+  const memory = getChangesSinceForUser(since, userEmail, orgId);
+  if (!useDurableEvents) return memory;
+
+  const durable = await getDurableChangesSinceForUser(since, userEmail, orgId);
+  const byIdentity = new Map<string, ChangeEvent>();
+  for (const event of [...durable.events, ...memory.events]) {
+    byIdentity.set(
+      JSON.stringify([
+        event.version,
+        event.source,
+        event.type,
+        event.key,
+        event.owner,
+        event.orgId,
+        event.resourceType,
+        event.resourceId,
+      ]),
+      event,
+    );
+  }
+  const events = Array.from(byIdentity.values()).sort(
+    (a, b) => a.version - b.version,
+  );
+  const limitedVersions = [memory, durable]
+    .filter((result) => result.cursorLimited)
+    .map((result) => result.version);
+  return {
+    version:
+      limitedVersions.length > 0
+        ? Math.min(...limitedVersions)
+        : Math.max(memory.version, durable.version, since),
+    events:
+      limitedVersions.length > 0
+        ? events.filter(
+            (event) => event.version <= Math.min(...limitedVersions),
+          )
+        : events,
+  };
+}
+
 /**
  * Seed _version from DB timestamps on the first call so serverless
  * cold starts don't return version 0 and confuse polling clients.
@@ -598,6 +867,7 @@ async function seedVersionFromDb(): Promise<void> {
     const db = getDbExec();
 
     const [
+      syncEventsTs,
       appTs,
       settingsTs,
       extensionsMaxUpdatedAt,
@@ -605,6 +875,7 @@ async function seedVersionFromDb(): Promise<void> {
       actionMarkerTs,
       refreshResult,
     ] = await Promise.all([
+      readMaxSyncEventVersion(),
       readMaxUpdatedAt(db, "application_state"),
       readMaxUpdatedAt(db, "settings"),
       readMaxUpdatedAtRaw(db, "tools"),
@@ -627,6 +898,7 @@ async function seedVersionFromDb(): Promise<void> {
     // Seed version — never decrease an already-set value
     _version = Math.max(
       _version,
+      syncEventsTs,
       appTs,
       settingsTs,
       extensionsTs,
@@ -667,9 +939,14 @@ async function seedVersionFromDb(): Promise<void> {
  * Check for cross-process DB writes by comparing updated_at timestamps.
  * Runs at most once per second to avoid excessive queries.
  */
-async function checkExternalDbChanges(): Promise<void> {
+async function checkExternalDbChanges(options: {
+  durableEvents: boolean;
+}): Promise<void> {
   const now = Date.now();
-  if (now - _lastDbCheck < 1000) return;
+  const interval = options.durableEvents
+    ? DURABLE_LEGACY_DB_CHECK_INTERVAL_MS
+    : LEGACY_DB_CHECK_INTERVAL_MS;
+  if (now - _lastDbCheck < interval) return;
   // Coalesce: if a check is already running, await it instead of starting a
   // second overlapping run that would double-advance the shared watermarks
   // (and double-emit change events).
@@ -906,11 +1183,19 @@ export function createPollHandler() {
     }
     // On cold start, seed _version from DB so we don't return version: 0
     await seedVersionFromDb();
-    // Check for cross-process writes before responding
-    await checkExternalDbChanges();
+    const durableEvents = await ensureSyncEventsTable();
+    // Durable sync_events rows are the cheap cross-process path. Keep the
+    // legacy watermark scan as a slower safety net for direct SQL writes and
+    // older processes that have not started writing durable events yet.
+    await checkExternalDbChanges({ durableEvents });
 
     const query = getQuery(event);
     const since = parseInt(String(query.since ?? "0"), 10) || 0;
-    return getChangesSinceForUser(since, session.email, session.orgId);
+    return getCombinedChangesSinceForUser(
+      since,
+      session.email,
+      session.orgId,
+      durableEvents,
+    );
   });
 }

package/corpus/core/src/server/request-context.ts

@@ -118,6 +118,13 @@ export interface RequestRunContext {
   toolCalls?: Array<{ name: string; input: unknown }>;
   /** Tool results returned so far in the current agent loop. */
   toolResults?: Array<{ name: string; content: string; isError: boolean }>;
+  /** Per-run fingerprints for large extension bodies already sent to the LLM. */
+  extensionContentReads?: Record<string, string>;
+  /** Per-run fingerprints for repeated tool-search calls already sent to the LLM. */
+  toolSearchReads?: Record<
+    string,
+    { totalTools: number; resultNames: string[] }
+  >;
 }
 
 export interface RequestContext {

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

@@ -684,7 +684,7 @@
   }
 }
 
-/* Tool-code viewer that uses shiki inside the ToolDetailViewer. */
+/* Tool-code viewer that uses shiki inside the Codex-style gray box. */
 .agent-tool-code .agent-markdown-shiki {
   margin: 0;
   border-radius: 0;

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

@@ -515,6 +515,33 @@
   --ring: 215 12% 60%;
 }
 
+/* Full settings page section bodies.
+   The framework's shared settings sections (LLM, App model defaults, Agent
+   limits, Email, Account, Secrets, Usage, Voice, Automations, A2A, hosting
+   cards, etc.) are authored dense for the compact agent sidebar. On the
+   full-width settings page they render inside polished shadcn-style cards
+   (PageSettingsSection), so bump the smallest fixed type up to a comfortable,
+   consistent reading size that matches the app-owned General/Team cards.
+   Scoped to `[data-agent-native-settings-page]` (only PageSettingsSection's
+   body) so app-owned tab content is never affected. The `.text-[…px]` classes
+   are Tailwind arbitrary values; the double-class specificity here wins. */
+[data-agent-native-settings-page] .text-\[10px\] {
+  font-size: 0.75rem;
+  line-height: 1rem;
+}
+[data-agent-native-settings-page] .text-\[11px\] {
+  font-size: 0.8125rem;
+  line-height: 1.15rem;
+}
+[data-agent-native-settings-page] .text-\[12px\] {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+[data-agent-native-settings-page] .text-\[13px\] {
+  font-size: 0.9375rem;
+  line-height: 1.4rem;
+}
+
 /* Composer toolbar: keep the model name + version readable on narrow
    chatfields. The bordered composer box is a size container; below 370px
    wide (e.g. a narrow agent sidebar) we drop the reasoning-level suffix

package/corpus/core/src/templates/default/.agents/skills/actions/SKILL.md

@@ -377,6 +377,11 @@ Most operations should be actions. You only need custom routes in `server/routes
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
 
+When the agent needs a durable image or file URL, call the core `upload-image`
+action or use `uploadFile()` in server code. Do not write base64 into SQL,
+markdown, deck/design JSON, or action results. `_agentImages` on action results
+is for ephemeral vision previews only, not persistence.
+
 If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
 
 ## Legacy Pattern (bare export)

package/corpus/core/src/templates/default/.agents/skills/adding-a-feature/SKILL.md

@@ -74,6 +74,11 @@ Builder/internal data, or customer data in the action, UI, seed data, fixtures,
 docs, prompts, or generated extension/app content. Register required secrets,
 use OAuth helpers, or read scoped values from the vault/credential store.
 
+If the feature involves attachments, images, recordings, screenshots, exports,
+or other file-like payloads, design the upload path in the same change:
+provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
+columns or stuff files into `application_state`.
+
 **If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
 
 ### 3. Skills / Instructions

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

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback — it detects DB timestamp changes even when the write happened in a different process or invocation.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/core/src/templates/default/.agents/skills/security/SKILL.md

@@ -51,6 +51,13 @@ export default defineAction({
 
 The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
 
+## Large Payloads
+
+Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
+or `application_state`. Route uploads through the file-upload provider and store
+references. This prevents database bloat, slow hot paths, and accidental secret
+or customer-data embedding inside binary payloads.
+
 ## SQL Injection
 
 Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:

package/corpus/core/src/templates/default/.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/core/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -13,7 +13,9 @@ metadata:
 
 ## Rule
 
-All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
 
 **Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
 
@@ -136,6 +138,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Use the `settings` store for app configuration and user preferences
 - Use `application-state` for ephemeral UI state that the agent and UI share
 - Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
 - Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
 - Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
 - Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
@@ -146,6 +149,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
 - Don't keep state only in memory (server variables, global stores)
 - Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
 - Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
 - Don't write SQLite-only or Postgres-only SQL in app code
 - Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder

package/corpus/core/src/templates/default/.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