@agent-native/core 0.92.0 → 0.92.1

package/corpus/core/src/templates/workspace-core/.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/workspace-core/AGENTS.md

@@ -44,6 +44,10 @@ agent should know.
   UI or "AI" features.
 - Put shared code in `packages/shared` only when multiple apps need it.
 - Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
   `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
@@ -114,7 +118,9 @@ App database code must be provider-agnostic. Define schemas with
 query builder and portable `drizzle-orm` operators. Do not import from
 `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Keep raw SQL
 for additive migrations, health checks, or carefully scoped maintenance, and
-never write SQLite-only or Postgres-only product code.
+never write SQLite-only or Postgres-only product code. Do not use SQL as object
+storage; file bytes belong in upload/private-blob providers with only references
+saved to app tables.
 
 In local development, run
 `pnpm exec agent-native create <app-name> --template=<template>` from the

package/corpus/core/src/templates/workspace-root/AGENTS.md

@@ -75,6 +75,10 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 - Keep application routes, actions, server plugins, and app state inside the
   relevant `apps/<app>` directory unless multiple apps need the same behavior.
 - Put reusable code in `packages/shared` only after at least two apps need it.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Never copy live credentials, API keys, tokens, webhook URLs, signing secrets,
   personal email addresses, customer data, private Builder/internal data, or
   company-specific placeholder values into source files, docs, prompts,
@@ -153,7 +157,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
   Drizzle's query builder and portable `drizzle-orm` operators. Do not import
   from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates.
   Keep raw SQL for additive migrations, health checks, or carefully scoped
-  maintenance, and never write SQLite-only or Postgres-only product code.
+  maintenance, and never write SQLite-only or Postgres-only product code. Do
+  not use SQL as object storage; file bytes belong in upload/private-blob
+  providers with only references saved to app tables.
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch

package/corpus/templates/analytics/.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/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -18,7 +18,9 @@ Current storage:
 | `dashboards`       | Explorer and SQL dashboard records           |
 | `dashboard_views`  | Saved filter presets per dashboard           |
 | `dashboard_shares` | Standard framework share grants              |
+| `dashboard_revisions` | Bounded dashboard history snapshots       |
 | `analyses`         | Saved ad-hoc analysis records                |
+| `analysis_revisions` | Bounded analysis history snapshots        |
 | `analysis_shares`  | Standard framework share grants for analyses |
 
 Legacy settings keys such as `u:<email>:dashboard-*`, `u:<email>:sql-dashboard-*`, `o:<orgId>:sql-dashboard-*`, and `adhoc-analysis-*` are still read as a fallback and copied into SQL on access. Do not create new dashboard settings rows.
@@ -29,6 +31,14 @@ syncs collab, and returns compact proof. Use `update-dashboard` for new
 full-config saves, UI full-config saves, or explicitly requested low-level
 JSON-pointer edits.
 
+Every meaningful dashboard save snapshots the previous state into
+`dashboard_revisions`. Use `list-dashboard-revisions` to inspect available undo
+points and `restore-dashboard-revision` to restore one; restore snapshots the
+current state first, then syncs open dashboard editors.
+
+Saved analyses follow the same undo model with `analysis_revisions`,
+`list-analysis-revisions`, and `restore-analysis-revision`.
+
 Never use `db-patch`, raw SQL, or settings-key edits to create or modify a
 dashboard config. Those bypass the dashboard action's access checks, SQL
 validation, collab sync, and proof-of-done return. If a dashboard action fails

package/corpus/templates/analytics/.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/templates/analytics/.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/templates/analytics/.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/templates/analytics/AGENTS.md

@@ -9,6 +9,10 @@ details live in `.agents/skills/`.
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Data integrity comes first. Do not invent numbers, dimensions, filters, or
   source semantics. State uncertainty and inspect the source when needed.
@@ -84,15 +88,18 @@ details live in `.agents/skills/`.
   / `$ai_latency`, `status`, `tool_calls`, `successful_tools`, `failed_tools`,
   and `$ai_error` / `error_message`. Do not expect prompts, tool args, or model
   responses in these tracked events by default.
-- `/agents` is the Analytics home for core agent-admin surfaces. The default
-  Monitoring view embeds the shared observability dashboard for traces,
-  conversations, evals, experiments, and feedback. The Advanced menu opens
-  `/agents?view=database`, where organization owners/admins can connect other
-  agent-native app databases and use the shared database admin tool for table
-  browsing, row editing, and SQL inspection. This surface is for connected
-  target app databases, not broad access to all Analytics data. Keep future
-  agent-admin additions inside this route instead of adding many top-level
-  sidebar tabs.
+- `/agents` is the Analytics home for admin surfaces. The default Monitoring
+  view embeds the shared observability dashboard for traces, conversations,
+  evals, experiments, and feedback. `/agents?view=dashboards` shows the
+  admin-only dashboard usage audit; call `list-dashboard-usage-stats` when
+  admins ask about dashboard created/modified dates, owners, last tracked
+  modifier, views, engagements, saved views, or cleanup candidates. The
+  Advanced menu opens `/agents?view=database`, where organization owners/admins
+  can connect other agent-native app databases and use the shared database admin
+  tool for table browsing, row editing, and SQL inspection. This database
+  surface is for connected target app databases, not broad access to all
+  Analytics data. Keep future admin additions inside this route instead of
+  adding many top-level sidebar tabs.
 - For dashboard edits, default to `mutate-dashboard` with its typed
   `dashboard.*` script API. It supports id-based panel moves, title/SQL/config
   edits, inserts, duplication, removal, and dashboard field patches in one
@@ -100,6 +107,13 @@ details live in `.agents/skills/`.
   serialization traps. The script is constrained: only documented dashboard
   method calls with JSON-compatible arguments are parsed; variables, imports,
   loops, functions, network, filesystem, and DB access are not available.
+- Dashboard saves keep bounded history in SQL. Use
+  `list-dashboard-revisions` to inspect undo points and
+  `restore-dashboard-revision` to restore one instead of hand-editing history
+  rows.
+- Saved analyses also keep bounded history. Use `list-analysis-revisions` and
+  `restore-analysis-revision` for rollback after a re-run updates the saved
+  findings.
 - Do not count shifting `/panels/<index>` values for ordinary dashboard edit
   requests. Use low-level JSON-pointer edits only when explicitly requested.
 - `get-sql-dashboard` is compact by default for agents. Use its `panels`
@@ -146,7 +160,9 @@ details live in `.agents/skills/`.
   `NOTIFICATIONS_SLACK_WEBHOOK_URL` / `NOTIFICATIONS_WEBHOOK_URL`. Configure
   optional `NOTIFICATIONS_SLACK_WEBHOOK_AUTH`; configure email with existing
   `RESEND_API_KEY` or `SENDGRID_API_KEY` plus `EMAIL_FROM`, and pass per-rule
-  `emailRecipients` or the fallback `NOTIFICATIONS_EMAIL_RECIPIENTS`.
+  `emailRecipients` or the fallback `NOTIFICATIONS_EMAIL_RECIPIENTS`. Saving
+  explicit `emailRecipients` also remembers them as the current user's defaults
+  for the next alert rule created in Settings.
   Netlify builds emit an alert cron trigger plus background worker from
   `scripts/emit-netlify-dashboard-report-cron.ts` every five minutes; long-lived
   runtimes use the in-process scheduler unless `ANALYTICS_ALERT_JOBS=0` is set.
@@ -163,9 +179,9 @@ details live in `.agents/skills/`.
   `view="catalog"` for the template catalog, `view="sessions"` for session
   replay, `view="monitoring"` with `monitoringView="uptime|errors"` (plus the
   `monitorId`, `statusPageId`, or `errorIssueId` deep links) for uptime checks,
-  public status pages, or error triage, and `view="agents"` /
-  `agentsView="database"` with optional `dbAdminConnectionId` for agent
-  monitoring or connected app database admin.
+  public status pages, or error triage, and `view="agents"` with
+  `agentsView="dashboards|database"` plus optional `dbAdminConnectionId` for
+  dashboard usage or connected app database admin.
 - Use `view-screen` when the active dashboard/chart context is unclear.
 
 ## Session Replay
@@ -242,7 +258,10 @@ details live in `.agents/skills/`.
   `@agent-native/core/client` (`captureException` / `captureMessage` /
   `addErrorBreadcrumb`), auto-enabled by `configureTracking` and transported
   through the first-party analytics ingest as a `$exception` event. Deep link:
-  `?view=errors&issue=<id>`. See `docs/error-capture.md`.
+  `?view=errors&issue=<id>`. Issue detail includes recent frequency,
+  parsed/raw stack traces, source code snippets when available, breadcrumbs,
+  tags, occurrence history, and session replay links. See
+  `docs/error-capture.md`.
 - Session replay ↔ Errors: a recording's devtools Console error lines link to
   the grouped issue at `/monitoring?view=errors&issue=<id>`, resolved by
   `match-error-issues` (exact fingerprint match, no heuristics); issues link

package/corpus/templates/analytics/actions/capture-test-error.ts

@@ -19,10 +19,14 @@ export default defineAction({
   schema: z.object({
     message: z
       .string()
+      .trim()
+      .max(500)
       .optional()
       .describe("Optional custom error message for the sample error."),
     type: z
       .string()
+      .trim()
+      .regex(/^[A-Za-z_$][\w$.]{0,79}$/)
       .optional()
       .describe("Optional error type/name, e.g. TypeError. Defaults to Error."),
   }),

package/corpus/templates/analytics/actions/get-analytics-alert-rule-defaults.ts

@@ -0,0 +1,23 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getAnalyticsAlertRuleDefaults } from "../server/lib/analytics-alerts";
+
+export default defineAction({
+  description:
+    "Read the current user's remembered defaults for creating analytics alert rules.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  agentTool: false,
+  run: async () => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() || null;
+    return getAnalyticsAlertRuleDefaults({ email, orgId });
+  },
+});

package/corpus/templates/analytics/actions/get-error-issue.ts

@@ -15,7 +15,7 @@ function resolveScope() {
 
 export default defineAction({
   description:
-    "Get one captured error issue with its recent occurrences (parsed stack frames, breadcrumbs, tags/extra) and links to the session replays where the error happened. Use this to triage a specific issue and jump to the replay.",
+    "Get one captured error issue with its recent occurrence frequency, parsed/raw stack traces, source code snippets when available, breadcrumbs, tags/extra, and links to the session replays where the error happened. Use this to triage a specific issue and jump to the replay.",
   schema: z.object({
     id: z.string().describe("Error issue id (erriss_...)."),
     eventsLimit: z.coerce

package/corpus/templates/analytics/actions/list-analysis-revisions.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listAnalysisRevisions } from "../server/lib/dashboards-store";
+
+function resolveScope() {
+  const orgId = getRequestOrgId() || null;
+  const email = getRequestUserEmail();
+  if (!email) throw new Error("no authenticated user");
+  return { orgId, email };
+}
+
+export default defineAction({
+  description: "List saved history revisions for an ad-hoc analysis.",
+  schema: z.object({
+    analysisId: z.string().describe("Analysis id to inspect"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const revisions = await listAnalysisRevisions(
+      args.analysisId,
+      resolveScope(),
+    );
+    return {
+      revisions: revisions.map((revision) => ({
+        id: revision.id,
+        analysisId: revision.analysisId,
+        name: revision.name,
+        description: revision.description,
+        createdAt: revision.createdAt,
+        createdBy: revision.createdBy,
+      })),
+    };
+  },
+});

package/corpus/templates/analytics/actions/list-dashboard-revisions.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listDashboardRevisions } from "../server/lib/dashboards-store";
+
+function resolveScope() {
+  const orgId = getRequestOrgId() || null;
+  const email = getRequestUserEmail();
+  if (!email) throw new Error("no authenticated user");
+  return { orgId, email };
+}
+
+export default defineAction({
+  description: "List saved dashboard history revisions for undo/restore.",
+  schema: z.object({
+    dashboardId: z.string().describe("Dashboard id to inspect"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const revisions = await listDashboardRevisions(
+      args.dashboardId,
+      resolveScope(),
+    );
+    return {
+      revisions: revisions.map((revision) => ({
+        id: revision.id,
+        dashboardId: revision.dashboardId,
+        kind: revision.kind,
+        title: revision.title,
+        createdAt: revision.createdAt,
+        createdBy: revision.createdBy,
+      })),
+    };
+  },
+});