@agent-native/core 0.146.0 → 0.146.1

package/dist/vite/client.js

@@ -2406,9 +2406,17 @@ function getConfiguredAppBasePath() {
     return { appBasePath, base };
 }
 function createNitroDevPlugin(options, appBasePath) {
+    const nitroOptions = options.nitro ?? {};
     return nitroVitePlugin({
         serverDir: "./server",
-        ...(options.nitro ?? {}),
+        ...nitroOptions,
+        replace: {
+            ...nitroOptions.replace,
+            // Netlify's netlify.toml environment is available to the build but not
+            // injected into deployed Functions. Nitro is a separate server build,
+            // so it needs the release ownership decision in its own replacement map.
+            "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(process.env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
+        },
         // Never auto-load test files as server handlers/plugins/middleware.
         // Nitro scans server/{plugins,middleware,routes,api}/*; a co-located
         // *.spec.ts would otherwise be loaded at runtime and crash the server
@@ -2739,6 +2747,10 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
             __AGENT_NATIVE_APP_CONFIG__: JSON.stringify(appConfig),
             __AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID__: JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
             "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
+            // The release migration owner is configured at build time. Netlify's
+            // 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() || ""),
             __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/drop-in-agent.mdx

@@ -142,11 +142,11 @@ children stays in the main app area. The agent chat is the side panel.
   ]}
 />
 
-That's it. The user now has a toggleable agent on every page — with chat history, resources tab, CLI terminal, voice input, and a fullscreen mode. State persists across reloads via `localStorage`.
+That's it. The user now has a toggleable agent on every page — with chat history, resources tab, CLI terminal, voice input, and a wider drawer. State persists across reloads via `localStorage`.
 
 ### Props
 
-- **`children`** — your app's normal layout and routes. Rendered in the main area; the agent panel mounts beside it on desktop and over it on mobile/fullscreen.
+- **`children`** — your app's normal layout and routes. Rendered in the main area; the agent panel mounts beside it on desktop and over it on mobile.
 - **`emptyStateText`** — greeting shown when the chat has no messages. Default: `"How can I help you?"`.
 - **`suggestions`** — starter prompts rendered as clickable chips when empty.
 - **`dynamicSuggestions`** — context-aware prompt chips merged with `suggestions`. Enabled by default; pass `false` to show only static suggestions, or `{ max, includeStatic, getSuggestions }` to customize.
@@ -177,7 +177,7 @@ export default function AgentRoute() {
 - **`defaultMode`** — `"chat"` or `"cli"`. Default: `"chat"`.
 - **`className`** — CSS class for the outer container.
 - **`onCollapse`** — if provided, a collapse button appears in the header.
-- **`isFullscreen`** / **`onToggleFullscreen`** — wire up external fullscreen state if you want a Claude-style centered column.
+- **`isFullscreen`** — set this when you want a Claude-style centered column for a page-level or custom panel surface. The sidebar uses the wider drawer instead.
 - **`storageKey`** — namespace for `localStorage` keys. Useful when you render multiple panels (different app instances or workspaces) in the same page.
 
 Full props: `AgentPanelProps` in `@agent-native/core/client`.

package/docs/content/getting-started-actions.mdx

@@ -89,5 +89,4 @@ custom native components, see [Native Chat UI](/docs/native-chat-ui).
 ## Continue
 
 Continue with [Add a Page](/docs/getting-started-pages) to use the same action
-outside the transcript. When results need to survive conversations, return to
-[Persist Data in SQL](/docs/getting-started-database).
+outside the transcript.

package/docs/content/getting-started-pages.mdx

@@ -71,6 +71,5 @@ patterns, see [Context Awareness](/docs/context-awareness).
 ## Continue
 
 You've built a chat app with an action and a page that calls the same source of
-truth. Continue with [Persist Data in SQL](/docs/getting-started-database) when
-results need to persist, or explore [Key Concepts](/docs/key-concepts) and
+truth. Continue with [Key Concepts](/docs/key-concepts) or
 [Agent Surfaces](/docs/agent-surfaces).

package/docs/content/getting-started.mdx

@@ -26,10 +26,6 @@ Define a typed text analyzer and render its result as a chart in the chat.
 
 Build a React route that calls the same action outside the transcript.
 
-### Persist data in SQL (optional)
-
-Add a table and persistence actions when results need to survive conversations.
-
 </Steps>
 
 ## 1. Create a chat app {#create-your-app}

package/docs/content/what-is-agent-native.mdx

@@ -79,10 +79,10 @@ Every operation is defined as a typed **action**: a name, a schema, and a `run`
 
 ```mermaid
 graph TD
-  UI_IN["👤 Click a button"]
-  AG_IN["🤖 Type a message to the agent"]
-  ACTION["⚡ Same typed action"]
-  DB["🗄️ Shared database"]
+  UI_IN["Click a button"]
+  AG_IN["Type a message to the agent"]
+  ACTION["Same typed action"]
+  DB["Shared database"]
   UI_OUT["UI updates instantly"]
   AG_OUT["Agent sees the change"]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.146.0",
+  "version": "0.146.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": {
@@ -412,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "^0.13.4",
-    "@agent-native/recap-cli": "0.5.3"
+    "@agent-native/recap-cli": "0.5.3",
+    "@agent-native/toolkit": "^0.13.4"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/turn-into-app/SKILL.md

@@ -27,6 +27,10 @@ The build location depends on the host. Treat this as a hard routing rule:
   `resourceIds` when available. This is the Builder handoff.
 - Do not substitute the generic `create_workspace_app` MCP tool in an online
   host. That tool is a local workspace scaffolder, not the Builder handoff.
+- Connect the Agent-Native Dispatch MCP connector only. Dispatch uses the
+  authenticated Builder Projects API to reuse or provision the workspace
+  project before starting the Builder Cloud Agent; a separate Builder CMS MCP
+  connection is not required for this workflow.
 - If `start-workspace-app-creation` is not available or Dispatch is not
   authenticated, stop with the connector setup needed. Do not fall back to a
   local build or claim that the app exists.

package/src/templates/chat/.agents/skills/turn-into-app/references/fresh-project.md

@@ -50,6 +50,14 @@ skills. For a ChatGPT Project or any host that exposes only the MCP connector,
 also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
+This single connector is enough: Dispatch provisions or reuses the Builder
+project through the Builder Projects API, so do not ask the user to add a
+separate Builder CMS MCP for app creation.
+Builder's separate Fusion MCP is available as a custom remote connector at
+`https://mcp.builder.io/mcp/fusion` for direct Builder work. It can run an
+existing project, but it cannot provision the repo-backed Agent-Native
+workspace project, so it is optional and not a replacement for the Dispatch
+handoff in this skill. Do not add Builder's CMS MCP for this workflow.
 
 For Claude Web, ChatGPT Web, and their web Projects, the host is an
 orchestrator, not the build environment. After forming the source brief, call

package/src/templates/default/.agents/skills/turn-into-app/SKILL.md

@@ -27,6 +27,10 @@ The build location depends on the host. Treat this as a hard routing rule:
   `resourceIds` when available. This is the Builder handoff.
 - Do not substitute the generic `create_workspace_app` MCP tool in an online
   host. That tool is a local workspace scaffolder, not the Builder handoff.
+- Connect the Agent-Native Dispatch MCP connector only. Dispatch uses the
+  authenticated Builder Projects API to reuse or provision the workspace
+  project before starting the Builder Cloud Agent; a separate Builder CMS MCP
+  connection is not required for this workflow.
 - If `start-workspace-app-creation` is not available or Dispatch is not
   authenticated, stop with the connector setup needed. Do not fall back to a
   local build or claim that the app exists.

package/src/templates/default/.agents/skills/turn-into-app/references/fresh-project.md

@@ -50,6 +50,14 @@ skills. For a ChatGPT Project or any host that exposes only the MCP connector,
 also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
+This single connector is enough: Dispatch provisions or reuses the Builder
+project through the Builder Projects API, so do not ask the user to add a
+separate Builder CMS MCP for app creation.
+Builder's separate Fusion MCP is available as a custom remote connector at
+`https://mcp.builder.io/mcp/fusion` for direct Builder work. It can run an
+existing project, but it cannot provision the repo-backed Agent-Native
+workspace project, so it is optional and not a replacement for the Dispatch
+handoff in this skill. Do not add Builder's CMS MCP for this workflow.
 
 For Claude Web, ChatGPT Web, and their web Projects, the host is an
 orchestrator, not the build environment. After forming the source brief, call

package/src/templates/headless/.agents/skills/turn-into-app/SKILL.md

@@ -27,6 +27,10 @@ The build location depends on the host. Treat this as a hard routing rule:
   `resourceIds` when available. This is the Builder handoff.
 - Do not substitute the generic `create_workspace_app` MCP tool in an online
   host. That tool is a local workspace scaffolder, not the Builder handoff.
+- Connect the Agent-Native Dispatch MCP connector only. Dispatch uses the
+  authenticated Builder Projects API to reuse or provision the workspace
+  project before starting the Builder Cloud Agent; a separate Builder CMS MCP
+  connection is not required for this workflow.
 - If `start-workspace-app-creation` is not available or Dispatch is not
   authenticated, stop with the connector setup needed. Do not fall back to a
   local build or claim that the app exists.

package/src/templates/headless/.agents/skills/turn-into-app/references/fresh-project.md

@@ -50,6 +50,14 @@ skills. For a ChatGPT Project or any host that exposes only the MCP connector,
 also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
+This single connector is enough: Dispatch provisions or reuses the Builder
+project through the Builder Projects API, so do not ask the user to add a
+separate Builder CMS MCP for app creation.
+Builder's separate Fusion MCP is available as a custom remote connector at
+`https://mcp.builder.io/mcp/fusion` for direct Builder work. It can run an
+existing project, but it cannot provision the repo-backed Agent-Native
+workspace project, so it is optional and not a replacement for the Dispatch
+handoff in this skill. Do not add Builder's CMS MCP for this workflow.
 
 For Claude Web, ChatGPT Web, and their web Projects, the host is an
 orchestrator, not the build environment. After forming the source brief, call

package/src/templates/workspace-core/.agents/skills/turn-into-app/SKILL.md

@@ -27,6 +27,10 @@ The build location depends on the host. Treat this as a hard routing rule:
   `resourceIds` when available. This is the Builder handoff.
 - Do not substitute the generic `create_workspace_app` MCP tool in an online
   host. That tool is a local workspace scaffolder, not the Builder handoff.
+- Connect the Agent-Native Dispatch MCP connector only. Dispatch uses the
+  authenticated Builder Projects API to reuse or provision the workspace
+  project before starting the Builder Cloud Agent; a separate Builder CMS MCP
+  connection is not required for this workflow.
 - If `start-workspace-app-creation` is not available or Dispatch is not
   authenticated, stop with the connector setup needed. Do not fall back to a
   local build or claim that the app exists.

package/src/templates/workspace-core/.agents/skills/turn-into-app/references/fresh-project.md

@@ -50,6 +50,14 @@ skills. For a ChatGPT Project or any host that exposes only the MCP connector,
 also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
+This single connector is enough: Dispatch provisions or reuses the Builder
+project through the Builder Projects API, so do not ask the user to add a
+separate Builder CMS MCP for app creation.
+Builder's separate Fusion MCP is available as a custom remote connector at
+`https://mcp.builder.io/mcp/fusion` for direct Builder work. It can run an
+existing project, but it cannot provision the repo-backed Agent-Native
+workspace project, so it is optional and not a replacement for the Dispatch
+handoff in this skill. Do not add Builder's CMS MCP for this workflow.
 
 For Claude Web, ChatGPT Web, and their web Projects, the host is an
 orchestrator, not the build environment. After forming the source brief, call

package/docs/content/getting-started-database.mdx

@@ -1,173 +0,0 @@
----
-title: "Persist Data in SQL"
-description: "Persist action results in SQL when they need to survive conversations."
----
-
-# Persist Data in SQL
-
-This is the optional fourth part of the Getting Started series. In [Add a Page](/docs/getting-started-pages)
-you used `analyze-text` directly from a route. Here you'll add app-owned SQL
-data when results need to survive conversations.
-
-## Add a table {#persist-data}
-
-Chat already includes the SQL runtime, framework tables, and a local SQLite file
-by default. You do not need to install a database, set `DATABASE_URL`, or add a
-migration for Chat's built-in tables. For a new app-owned table, add these three
-server files:
-
-1. `server/plugins/db.ts` creates the table with an additive migration.
-2. `server/db/schema.ts` describes the table for typed queries.
-3. `server/db/index.ts` creates the app's typed database client.
-
-Create `server/plugins/db.ts`:
-
-```ts filename="server/plugins/db.ts"
-import { runMigrations } from "@agent-native/core/db";
-
-export default runMigrations(
-  [
-    {
-      version: 1,
-      name: "create-text-analyses",
-      sql: `CREATE TABLE IF NOT EXISTS text_analyses (
-        id TEXT PRIMARY KEY,
-        input TEXT NOT NULL,
-        char_count INTEGER NOT NULL,
-        word_count INTEGER NOT NULL,
-        sentence_count INTEGER NOT NULL,
-        paragraph_count INTEGER NOT NULL,
-        owner_email TEXT NOT NULL,
-        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
-      )`,
-    },
-  ],
-  { table: "text_analyses_migrations" },
-);
-```
-
-Create `server/db/schema.ts`:
-
-```ts filename="server/db/schema.ts"
-import { integer, now, table, text } from "@agent-native/core/db/schema";
-
-export const textAnalyses = table("text_analyses", {
-  id: text("id").primaryKey(),
-  input: text("input").notNull(),
-  charCount: integer("char_count").notNull(),
-  wordCount: integer("word_count").notNull(),
-  sentenceCount: integer("sentence_count").notNull(),
-  paragraphCount: integer("paragraph_count").notNull(),
-  ownerEmail: text("owner_email").notNull(),
-  createdAt: text("created_at").notNull().default(now()),
-});
-```
-
-Create `server/db/index.ts`:
-
-```ts filename="server/db/index.ts"
-import { createGetDb } from "@agent-native/core/db";
-import * as schema from "./schema.js";
-
-export const getDb = createGetDb(schema);
-export { schema };
-```
-
-Restart `pnpm dev` once so the migration runs. Keep future migrations additive,
-and give each one a new `version` and `name`.
-
-## Add save and list actions
-
-Keep `analyze-text` read-only and make saving explicit with a separate action.
-Create `actions/save-text-analysis.ts`:
-
-```ts filename="actions/save-text-analysis.ts"
-import { defineAction } from "@agent-native/core/action";
-import { z } from "zod";
-
-import { getDb, schema } from "../server/db/index.js";
-
-export default defineAction({
-  description: "Save a text analysis result to the database.",
-  schema: z.object({
-    input: z.string().min(1),
-    charCount: z.number(),
-    wordCount: z.number(),
-    sentenceCount: z.number(),
-    paragraphCount: z.number(),
-  }),
-  run: async (
-    { input, charCount, wordCount, sentenceCount, paragraphCount },
-    ctx,
-  ) => {
-    const ownerEmail = ctx?.userEmail;
-    if (!ownerEmail) throw new Error("Sign in before saving analyses.");
-
-    const id = crypto.randomUUID();
-    await getDb().insert(schema.textAnalyses).values({
-      id,
-      input,
-      charCount,
-      wordCount,
-      sentenceCount,
-      paragraphCount,
-      ownerEmail,
-    });
-
-    return { id };
-  },
-});
-```
-
-Create `actions/list-text-analyses.ts`:
-
-```ts filename="actions/list-text-analyses.ts"
-import { defineAction } from "@agent-native/core/action";
-import { desc, eq } from "drizzle-orm";
-import { z } from "zod";
-
-import { getDb, schema } from "../server/db/index.js";
-
-export default defineAction({
-  description: "List the signed-in user's saved text analyses, newest first.",
-  schema: z.object({}),
-  http: { method: "GET" },
-  readOnly: true,
-  run: async (_, ctx) => {
-    const ownerEmail = ctx?.userEmail;
-    if (!ownerEmail) throw new Error("Sign in before listing analyses.");
-
-    return getDb()
-      .select({
-        id: schema.textAnalyses.id,
-        input: schema.textAnalyses.input,
-        charCount: schema.textAnalyses.charCount,
-        wordCount: schema.textAnalyses.wordCount,
-        sentenceCount: schema.textAnalyses.sentenceCount,
-        paragraphCount: schema.textAnalyses.paragraphCount,
-        createdAt: schema.textAnalyses.createdAt,
-      })
-      .from(schema.textAnalyses)
-      .where(eq(schema.textAnalyses.ownerEmail, ownerEmail))
-      .orderBy(desc(schema.textAnalyses.createdAt));
-  },
-});
-```
-
-The actions use the typed Drizzle client for app reads and writes. Raw SQL is
-only needed here for the additive migration. Skip this page until your action
-needs durable domain data.
-
-## Try it
-
-In chat, ask the agent to do the whole flow:
-
-> Run analyze-text on "Hello world", save the result with save-text-analysis, then list my saved text analyses.
-
-The saved row is now available to the agent and to any page that reads
-`list-text-analyses`.
-
-## Continue
-
-You now have durable app data. Continue with [Key Concepts](/docs/key-concepts)
-to learn how actions, SQL, and pages fit together.