@agent-native/core 0.163.0 → 0.163.1

package/dist/deploy/build.js

@@ -891,6 +891,77 @@ function isTruthyRuntimeValue(value) {
   );
 }
 
+function normalizeExplicitDeploymentEnvironment(value) {
+  const normalized = firstNonEmpty(value)?.toLowerCase();
+  if (!normalized) return;
+  if (
+    normalized !== "local" &&
+    normalized !== "beta" &&
+    normalized !== "production" &&
+    normalized !== "preview"
+  ) {
+    throw new Error(
+      'AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT must be "local", "beta", "production", or "preview"',
+    );
+  }
+  return normalized;
+}
+
+function normalizeFallbackDeploymentEnvironment(value) {
+  const normalized = firstNonEmpty(value)?.toLowerCase();
+  if (normalized === "development" || normalized === "test") return "local";
+  return normalized === "local" ||
+    normalized === "beta" ||
+    normalized === "production" ||
+    normalized === "preview"
+    ? normalized
+    : undefined;
+}
+
+function resolveDeploymentEnvironment() {
+  const env = globalThis.process?.env || {};
+  const explicit = normalizeExplicitDeploymentEnvironment(
+    env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT,
+  );
+  if (explicit) return explicit;
+
+  const context = firstNonEmpty(
+    typeof env.CONTEXT === "string" ? env.CONTEXT : undefined,
+    typeof env.NETLIFY_CONTEXT === "string" ? env.NETLIFY_CONTEXT : undefined,
+    typeof env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT === "string"
+      ? env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT
+      : undefined,
+  )?.toLowerCase();
+  const branch =
+    typeof env.BRANCH === "string" ? env.BRANCH.trim().toLowerCase() : "";
+  const vercelEnv = String(env.VERCEL_ENV || "").trim().toLowerCase();
+  const sentryEnvironment = firstNonEmpty(env.SENTRY_ENVIRONMENT);
+  if (branch === "beta") return "beta";
+  if (
+    branch === "production" ||
+    (context === "production" && branch !== "beta")
+  ) {
+    return "production";
+  }
+  if (context === "branch-deploy" && branch === "main") return "beta";
+  if (
+    context === "deploy-preview" ||
+    context === "branch-deploy" ||
+    branch.startsWith("deploy-preview") ||
+    vercelEnv === "preview"
+  ) {
+    return "preview";
+  }
+  if (!context && !branch && !vercelEnv && sentryEnvironment) {
+    return normalizeFallbackDeploymentEnvironment(sentryEnvironment) || "production";
+  }
+  return (
+    normalizeFallbackDeploymentEnvironment(firstNonEmpty(context, vercelEnv)) ||
+    normalizeFallbackDeploymentEnvironment(env.NODE_ENV) ||
+    "production"
+  );
+}
+
 function getSentryClientConfigScript() {
   const env = globalThis.process?.env || {};
   const key = firstNonEmpty(env.SENTRY_CLIENT_KEY, env.VITE_SENTRY_CLIENT_KEY);
@@ -909,16 +980,15 @@ function getSentryClientConfigScript() {
       env.VITE_SENTRY_DSN,
       env.SENTRY_DSN,
     ) || (key && projectId && host ? "https://" + key + "@" + host + "/" + projectId : undefined);
-  if (!dsn) return null;
+  const deploymentEnvironment = resolveDeploymentEnvironment();
   const config = {
-    sentryDsn: dsn,
-    sentryEnvironment:
-      firstNonEmpty(
-        env.SENTRY_ENVIRONMENT,
-        env.NETLIFY_CONTEXT,
-        env.VERCEL_ENV,
-        env.NODE_ENV,
-      ) || "production",
+    ...(dsn
+      ? {
+          sentryDsn: dsn,
+          sentryEnvironment: deploymentEnvironment,
+        }
+      : {}),
+    deploymentEnvironment,
   };
   return (
     '<script data-agent-native-sentry-config>' +
@@ -3742,7 +3812,9 @@ function createBrowserOnlyServerStubPlugin() {
         },
     };
 }
-export function resolveNitroBuildReplacements(env = process.env) {
+export function resolveNitroBuildReplacements(env = process.env, deploymentEnvironment) {
+    const configuredDeploymentEnvironment = deploymentEnvironment?.trim() ||
+        env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT?.trim();
     return {
         // Netlify exposes DEPLOY_ID only while building. Embed it into the Nitro
         // function so preview OAuth relays can target this immutable deployment
@@ -3755,7 +3827,12 @@ export function resolveNitroBuildReplacements(env = process.env) {
         // a separate server build, so embed release migration ownership here as
         // well as in the Vite server bundle.
         "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
-        "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(env.CONTEXT?.trim() || ""),
+        "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(env.CONTEXT?.trim() || env.NETLIFY_CONTEXT?.trim() || ""),
+        ...(configuredDeploymentEnvironment
+            ? {
+                "process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT": JSON.stringify(configuredDeploymentEnvironment),
+            }
+            : {}),
     };
 }
 async function buildWithNitro() {
@@ -3841,7 +3918,7 @@ export default bundle;
         virtual: {
             "virtual:agents-bundle": agentsBundleModuleSource,
         },
-        replace: resolveNitroBuildReplacements(),
+        replace: resolveNitroBuildReplacements(process.env, nitroAgentConfig.deployment?.environment),
         // Replace browser-only renderers (Excalidraw/Mermaid) with an inert proxy in
         // the server bundle. Without this, Nitro's Rolldown build pulls the real
         // Excalidraw into a shared vendor chunk imported statically by the SSR render

package/dist/observability/routes.d.ts

@@ -62,6 +62,6 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/observability/tracking-identity.js

@@ -1,3 +1,4 @@
+import { resolveDeployEnvironment } from "../server/deploy-environment.js";
 function normalizeTrackingSlug(value) {
     const raw = value?.trim().toLowerCase();
     if (!raw)
@@ -44,6 +45,7 @@ export function trackingIdentityProperties() {
         normalizeTrackingSlug(process.env.VITE_APP_TEMPLATE) ||
         app;
     return {
+        deployment_environment: resolveDeployEnvironment(),
         ...(app ? { app, agent_native_app: app } : {}),
         ...(template ? { template, agent_native_template: template } : {}),
     };

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/collab-plugin.d.ts

@@ -41,6 +41,8 @@ export interface CollabPluginOptions {
     idColumn?: string;
     /** Whether to auto-seed existing documents on startup. Default: true */
     autoSeed?: boolean;
+    /** Map a source-table id to the id used by the collab document store. */
+    resolveCollabDocumentId?: (sourceId: string) => string;
     /**
      * Callback invoked after a collab update to sync the content column.
      * If not provided, the plugin auto-syncs using table/contentColumn/idColumn.
@@ -78,4 +80,8 @@ export interface CollabPluginOptions {
 }
 export declare function normalizeCollabAccess(options: Pick<CollabPluginOptions, "access" | "resourceType" | "resolveResourceId">): NormalizedCollabAccess;
 export declare function createCollabPlugin(options?: CollabPluginOptions): NitroPluginDef;
+export declare function selectUnseededCollabRows(rows: ReadonlyArray<Record<string, unknown>>, idColumn: string, existingDocIds: ReadonlySet<string>, resolveCollabDocumentId?: (sourceId: string) => string): Array<{
+    row: Record<string, unknown>;
+    docId: string;
+}>;
 export {};

package/dist/server/collab-plugin.js

@@ -16,7 +16,7 @@ import { defineEventHandler, getMethod, setResponseStatus, } from "h3";
 import { postAwareness, getActiveUsers } from "../collab/awareness.js";
 import { getCollabEmitter } from "../collab/emitter.js";
 import { getCollabState, postCollabUpdate, postCollabText, postCollabSearchReplace, } from "../collab/routes.js";
-import { hasCollabState } from "../collab/storage.js";
+import { listCollabDocIds } from "../collab/storage.js";
 import { postCollabJson, getCollabJson, postCollabPatch, } from "../collab/struct-routes.js";
 import { seedFromText, seedFromJson } from "../collab/ydoc-manager.js";
 import { getDbExec } from "../db/client.js";
@@ -82,6 +82,7 @@ function warnForImplicitAllAuthenticatedAccess(table) {
 export function createCollabPlugin(options = {}) {
     const normalizedAccess = normalizeCollabAccess(options);
     const { table = "documents", contentColumn = "content", idColumn = "id", autoSeed = true, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, } = options;
+    const resolveCollabDocumentId = options.resolveCollabDocumentId ?? ((sourceId) => sourceId);
     const resourceType = normalizedAccess.mode === "resource"
         ? normalizedAccess.resourceType
         : undefined;
@@ -308,13 +309,14 @@ export function createCollabPlugin(options = {}) {
             // Run in background so it doesn't block startup
             setTimeout(async () => {
                 try {
+                    // Read existing ids once, then apply the plugin's document-id
+                    // mapping before filtering. A source-table SQL predicate can use
+                    // the wrong id for integrations such as Analytics' dash-* docs.
+                    const existingDocIds = await listCollabDocIds();
                     const client = getDbExec();
                     const { rows } = await client.execute(`SELECT ${idColumn}, ${seedColumn} FROM ${table}`);
-                    for (const row of rows) {
-                        const docId = row[idColumn];
-                        const exists = await hasCollabState(docId);
-                        if (exists)
-                            continue;
+                    for (const { row, docId } of selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId)) {
+                        let seeded = false;
                         if (isJson) {
                             const raw = row[seedColumn] ?? "{}";
                             try {
@@ -323,6 +325,7 @@ export function createCollabPlugin(options = {}) {
                                     ? "array"
                                     : "map";
                                 await seedFromJson(docId, parsed, "data", inferredType);
+                                seeded = true;
                             }
                             catch {
                                 // Invalid JSON — skip
@@ -331,7 +334,10 @@ export function createCollabPlugin(options = {}) {
                         else {
                             const content = row[seedColumn] ?? "";
                             await seedFromText(docId, content);
+                            seeded = true;
                         }
+                        if (seeded)
+                            existingDocIds.add(docId);
                     }
                 }
                 catch {
@@ -341,3 +347,18 @@ export function createCollabPlugin(options = {}) {
         }
     };
 }
+export function selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId = (sourceId) => sourceId) {
+    const seenDocIds = new Set(existingDocIds);
+    const unseeded = [];
+    for (const row of rows) {
+        const sourceId = String(row[idColumn] ?? "");
+        if (!sourceId)
+            continue;
+        const docId = resolveCollabDocumentId(sourceId);
+        if (seenDocIds.has(docId))
+            continue;
+        seenDocIds.add(docId);
+        unseeded.push({ row, docId });
+    }
+    return unseeded;
+}

package/dist/server/deploy-environment.d.ts

@@ -5,7 +5,7 @@
  * not the vendor, and a second backend that reports errors without them
  * produces issues nobody can tie to a release.
  */
-/** The deploy environment name, e.g. `production`, `deploy-preview`. */
+/** The deploy environment name, e.g. `production`, `beta`, or `preview`. */
 export declare function resolveDeployEnvironment(): string;
 /**
  * Resolve the agent-native version baked into core's package.json so the

package/dist/server/deploy-environment.js

@@ -8,6 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isAgentNativeDeploymentEnvironment } from "../config.js";
 function firstNonEmpty(...values) {
     for (const value of values) {
         const trimmed = value?.trim();
@@ -16,9 +17,46 @@ function firstNonEmpty(...values) {
     }
     return undefined;
 }
-/** The deploy environment name, e.g. `production`, `deploy-preview`. */
+function normalizeFallbackEnvironment(value) {
+    const normalized = firstNonEmpty(value)?.toLowerCase();
+    if (normalized === "development" || normalized === "test")
+        return "local";
+    return isAgentNativeDeploymentEnvironment(normalized)
+        ? normalized
+        : undefined;
+}
+/** The deploy environment name, e.g. `production`, `beta`, or `preview`. */
 export function resolveDeployEnvironment() {
-    return (firstNonEmpty(process.env.SENTRY_ENVIRONMENT, process.env.NETLIFY_CONTEXT, process.env.VERCEL_ENV, process.env.NODE_ENV) ?? "production");
+    const explicit = firstNonEmpty(process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT)?.toLowerCase();
+    if (explicit) {
+        if (!isAgentNativeDeploymentEnvironment(explicit)) {
+            throw new Error('AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT must be "local", "beta", "production", or "preview"');
+        }
+        return explicit;
+    }
+    const context = firstNonEmpty(process.env.CONTEXT, process.env.NETLIFY_CONTEXT, process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT)?.toLowerCase();
+    const branch = process.env.BRANCH?.trim().toLowerCase();
+    const vercelEnv = process.env.VERCEL_ENV?.trim().toLowerCase();
+    if (branch === "beta")
+        return "beta";
+    if (branch === "production" ||
+        (context === "production" && branch !== "beta")) {
+        return "production";
+    }
+    if (context === "branch-deploy" && branch === "main")
+        return "beta";
+    if (context === "deploy-preview" ||
+        context === "branch-deploy" ||
+        branch?.startsWith("deploy-preview") ||
+        vercelEnv === "preview") {
+        return "preview";
+    }
+    if (!context && !branch && !vercelEnv) {
+        return (normalizeFallbackEnvironment(firstNonEmpty(process.env.SENTRY_ENVIRONMENT, process.env.NODE_ENV)) ?? "production");
+    }
+    return (normalizeFallbackEnvironment(firstNonEmpty(context, vercelEnv)) ??
+        normalizeFallbackEnvironment(process.env.NODE_ENV) ??
+        "production");
 }
 /**
  * Resolve the agent-native version baked into core's package.json so the

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/sentry-config.js

@@ -28,11 +28,15 @@ export function resolvePublicSentryDsn() {
 }
 export function getSentryClientConfigScript() {
     const dsn = resolvePublicSentryDsn();
-    if (!dsn)
-        return null;
+    const deploymentEnvironment = resolveDeployEnvironment();
     const config = {
-        sentryDsn: dsn,
-        sentryEnvironment: resolveSentryEnvironment(),
+        ...(dsn
+            ? {
+                sentryDsn: dsn,
+                sentryEnvironment: resolveSentryEnvironment(),
+            }
+            : {}),
+        deploymentEnvironment,
     };
     return [
         "<script data-agent-native-sentry-config>",

package/dist/server/sentry.js

@@ -62,6 +62,10 @@ export function initServerSentry() {
         // cookies, or process.env contents to Sentry without explicit consent.
         sendDefaultPii: false,
         beforeSend(event) {
+            event.tags = {
+                ...event.tags,
+                deployment_environment: resolveDeployEnvironment(),
+            };
             // Drop rules live in `error-noise-filter.ts` so every backend applies
             // the same ones — they describe which server errors are non-bugs in
             // this framework, not a Sentry preference.

package/dist/tracking/registry.js

@@ -1,3 +1,4 @@
+import { resolveDeployEnvironment } from "../server/deploy-environment.js";
 import { getRequestContext } from "../server/request-context.js";
 import { ANALYTICS_CLIENT_PLATFORM_PROPERTY } from "../shared/analytics-platform.js";
 const REGISTRY_KEY = Symbol.for("@agent-native/core/tracking.registry");
@@ -46,12 +47,13 @@ function resolveTrackingSource(source) {
 export function track(name, properties, source) {
     const { userId, anonymousId, sessionId } = resolveTrackingSource(source);
     const clientPlatform = getRequestContext()?.clientPlatform;
-    const trackedProperties = clientPlatform
-        ? {
-            ...(properties ?? {}),
-            [ANALYTICS_CLIENT_PLATFORM_PROPERTY]: clientPlatform,
-        }
-        : properties;
+    const trackedProperties = {
+        ...(properties ?? {}),
+        deployment_environment: resolveDeployEnvironment(),
+        ...(clientPlatform
+            ? { [ANALYTICS_CLIENT_PLATFORM_PROPERTY]: clientPlatform }
+            : {}),
+    };
     const event = {
         name,
         properties: trackedProperties,

package/dist/vite/client.js

@@ -2913,6 +2913,11 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
             // netlify.toml environment is available to the build but not injected
             // into deployed Functions, so embed the decision in the server bundle.
             "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(process.env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
+            ...(resolvedAppConfig.deployment?.environment
+                ? {
+                    "process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT": JSON.stringify(resolvedAppConfig.deployment.environment),
+                }
+                : {}),
             __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
             "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
             // Framework route warmup controls how SSR `.data` routes are fetched:

package/docs/content/deployment.mdx

@@ -26,11 +26,11 @@ pnpm install
 
 The install step creates the lockfile that the production Dockerfile below copies into its build stage.
 
-### 2. Add a local Compose file
+### 2. Add the local Docker files
 
-Create `docker-compose.yml` in the app root. It uses the [Dockerfile](#docker) in the next section and starts Postgres only on the private Compose network:
+Create `Dockerfile`, `.dockerignore`, and `docker-compose.yml` in the app root. `docker compose up --build` needs the Dockerfile, and `.dockerignore` keeps host-only files such as `node_modules` out of the Linux build context. Compose starts Postgres only on the private Compose network.
 
-You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture.
+You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [.dockerignore](https://www.agent-native.com/examples/self-hosted-chat/.dockerignore), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture. The [Dockerfile](#docker) below matches the fixture.
 
 ```yaml filename="docker-compose.yml" maxLines=40
 services:
@@ -53,7 +53,7 @@ services:
       POSTGRES_USER: agent_native
       POSTGRES_HOST_AUTH_METHOD: trust
     volumes:
-      - postgres-data:/var/lib/postgresql
+      - postgres-data-v18:/var/lib/postgresql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U agent_native -d agent_native"]
       interval: 5s
@@ -61,9 +61,11 @@ services:
       retries: 10
 
 volumes:
-  postgres-data:
+  postgres-data-v18:
 ```
 
+PostgreSQL 18 uses `/var/lib/postgresql` as its volume mount path, unlike PostgreSQL 17 and earlier. The versioned volume name keeps this fresh fixture separate from older local stacks. If you are upgrading an existing PostgreSQL 17 or earlier stack, back up and migrate its data before changing the image or mount path. Do not point this fixture at the old volume without a migration.
+
 ### 3. Run it
 
 ```bash
@@ -322,6 +324,18 @@ EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]
 ```
 
+Create `.dockerignore` alongside the Dockerfile:
+
+```text filename=".dockerignore"
+node_modules
+.output
+data
+.env
+.env.*
+!.env.example
+.git
+```
+
 ### Self-hosted workspace with Docker Compose {#workspace-docker-compose}
 
 The Dockerfile above is for one standalone app. A workspace is not one Nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.163.0",
+  "version": "0.163.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {