@agent-native/core 0.146.0 → 0.146.2

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.2",
   "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.5"
   },
   "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.