@agent-native/core 0.148.0 → 0.149.0

package/docs/content/server-overview.mdx

@@ -85,7 +85,7 @@ The `server/` directory is the infrastructure layer of an agent-native app. It h
 
 ## Where the Server Fits {#role}
 
-In a traditional web app, the server is where most logic lives. Business rules, data access, and presentation all happen inside route handlers. Agent-native apps work differently. Logic lives in actions, which the agent and UI share as equal partners. The server's job is coordination: run database migrations, configure authentication, mount the agent loop, and handle the narrow set of HTTP concerns that actions can't express on their own.
+In a traditional web app, the server is where most logic lives. Business rules, data access, and presentation all happen inside route handlers. Agent-native apps work differently. Logic lives in actions, which the agent and UI share as equal partners. The server's job is coordination: apply app-owned database migrations, configure authentication, mount the agent loop, and handle the narrow set of HTTP concerns that actions can't express on their own.
 
 <Diagram id="doc-block-server-overview-2" title="Traditional server vs. Agent Native">
 
@@ -194,19 +194,19 @@ Browser requests, the agent loop, and external API clients all route through the
 
 These are the directories and files inside `server/` that every agent-native app ships. Each corresponds to a specific piece of the server layer: what it does, when to reach for it, and how it connects to the rest of the framework.
 
-| Page                                      | What it covers                                                                      |
-| ----------------------------------------- | ----------------------------------------------------------------------------------- |
-| **[Database](/docs/server-database)**     | Schema definition with `table()` helpers, `getDb`, and ownable table patterns       |
-| **[Middleware](/docs/server-middleware)** | Auth guards in `server/middleware/` and why they run there instead of in a plugin   |
-| **[Plugins](/docs/server-plugins)**       | The three startup plugins every app ships: db migrations, auth, and agent-chat      |
-| **[Routes](/docs/server-routes)**         | File-based routes, the SSR catch-all, and scoping custom routes to the request user |
+| Page                                      | What it covers                                                                       |
+| ----------------------------------------- | ------------------------------------------------------------------------------------ |
+| **[Database](/docs/server-database)**     | Schema definition with `table()` helpers, `getDb`, and ownable table patterns        |
+| **[Middleware](/docs/server-middleware)** | Auth guards in `server/middleware/` and why they run there instead of in a plugin    |
+| **[Plugins](/docs/server-plugins)**       | Startup plugins for auth and agent-chat, plus optional app-owned database migrations |
+| **[Routes](/docs/server-routes)**         | File-based routes, the SSR catch-all, and scoping custom routes to the request user  |
 
 ## Nitro {#nitro}
 
 [Nitro](https://nitro.build) is the server toolkit that powers the agent-native HTTP layer. Most of what you'll configure in `server/` is Nitro: file-based routes, startup plugins, and middleware.
 
 - **File-based routing**: the filename maps directly to an HTTP method and URL path, with no registration needed. `server/routes/api/health.get.ts` becomes `GET /api/health` automatically. Visit [Routes](/docs/server-routes) for more details.
-- **Plugins**: code that runs once at server startup, before any request is served. Database migrations, auth configuration, and the agent-chat mount all happen in `server/plugins/`. Visit [Plugins](/docs/server-plugins) for more details.
+- **Plugins**: code registered at server startup and loaded once. Framework helpers initialize auth and the agent-chat mount; optional app-owned database migrations may still be running when the first request arrives. Visit [Plugins](/docs/server-plugins) for more details.
 - **Middleware**: code that runs on every incoming request before it reaches a route. The auth guard lives in `server/middleware/`. Visit [Middleware](/docs/server-middleware) for more details.
 
 Nitro is also deployment-agnostic. The same app deploys to Node.js, Cloudflare Workers, Netlify, Vercel, and other runtimes with no code changes. Just set a preset. See [Deployment](/docs/deployment).
@@ -230,5 +230,5 @@ Use custom `/api/*` routes only when you need a route-shaped protocol or binary/
 - [**Actions**](/docs/actions): the default operation surface. Reach for a custom route only when it doesn't fit.
 - [**Database**](/docs/server-database): the `getDb()`/schema pattern custom routes and actions both import
 - [**Middleware**](/docs/server-middleware): auth guards and the `server/middleware/` directory
-- [**Plugins**](/docs/server-plugins): startup plugins for migrations, auth, and the agent
+- [**Plugins**](/docs/server-plugins): startup plugins for auth, the agent, and optional app-owned migrations
 - [**Routes**](/docs/server-routes): file-based routes, request context, and the SSR catch-all

package/docs/content/server-plugins.mdx

@@ -5,7 +5,7 @@ description: "Startup plugins in server/plugins/ — what they are, the two plug
 
 # Plugins
 
-Plugins are startup hooks. Each file in `server/plugins/` exports a function that Nitro calls once when the server initializes, before any route is served. They are the right place for one-time setup: configuring auth, mounting the agent loop, running database migrations, or registering any other initialization code that needs to complete before requests arrive.
+Plugins are startup hooks. Nitro loads each file in `server/plugins/` once when the server initializes. They are the right place for one-time setup: configuring auth, mounting the agent loop, running database migrations, or registering other initialization code. Framework helpers coordinate their async setup; custom plugin work may still be in flight when the first request arrives.
 
 Nitro discovers plugins automatically from the filesystem. No registration or imports are required. Files run in alphabetical order, so execution order is controlled by filename prefix.
 
@@ -21,7 +21,7 @@ Apps that need custom database tables add a third:
 
 ```text
 server/plugins/
-  db.ts          -> run migrations on startup
+  db.ts          -> register app-owned migrations for local startup
 ```
 
 ## Auth Plugin {#auth-plugin}
@@ -80,7 +80,7 @@ screen when context matters.`,
 
 ## Database Plugin {#database-plugin}
 
-If your app defines custom database tables, add `server/plugins/db.ts` to run schema migrations at startup. It uses `runMigrations` from `@agent-native/core/db`:
+If your app defines custom database tables, add `server/plugins/db.ts` to register schema migrations for local startup. It uses `runMigrations` from `@agent-native/core/db`:
 
 ```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
@@ -110,6 +110,12 @@ Each entry needs a `version` number and a `sql` string. Give it a stable `name`
   TABLE ... DROP COLUMN`, `DELETE FROM`) in startup plugins.
 </Callout>
 
+<Callout tone="warning">
+  For production or serverless deployments, run migrations in a release or
+  deploy step instead of on the first request. The Chat template provides `pnpm
+  migrate:production` for this.
+</Callout>
+
 ## Writing Custom Plugins {#custom-plugins}
 
 The framework helpers (`createAuthPlugin`, `createAgentChatPlugin`, `runMigrations`) each return a Nitro plugin function. For anything outside those helpers, write a plugin using `defineNitroPlugin`:
@@ -142,6 +148,6 @@ If you add custom plugins, prefix their filenames to control invocation order, b
 
 - [**Database**](/docs/server-database): schema helpers and the `getDb` pattern used inside plugins
 - [**Middleware**](/docs/server-middleware): the auth guard that enforces what the auth plugin configures
-- [**Routes**](/docs/server-routes): custom file routes served after plugins complete
+- [**Routes**](/docs/server-routes): custom file routes and when to use them
 - [**Writing Agent Instructions**](/docs/writing-agent-instructions): how to craft the `systemPrompt` in the agent-chat plugin
 - [**Nitro plugin docs**](https://nitro.build/guide/plugins): the full plugin API and lifecycle hooks

package/docs/content/server-routes.mdx

@@ -77,7 +77,12 @@ export default defineEventHandler(async (event) => {
   }
 
   const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
-  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+  const signatureBytes = Buffer.from(signature, "utf8");
+  const expectedBytes = Buffer.from(expected, "utf8");
+  if (
+    signatureBytes.length !== expectedBytes.length ||
+    !timingSafeEqual(signatureBytes, expectedBytes)
+  ) {
     throw createError({ statusCode: 401, statusMessage: "Invalid signature" });
   }
 
@@ -189,6 +194,6 @@ Every SSR response is an impersonal, public shell cached at the CDN. Never read
 ## What's next {#whats-next}
 
 - [**Actions**](/docs/actions): the preferred surface for app operations; reach for a route only when it doesn't fit
-- [**Plugins**](/docs/server-plugins): startup plugins that run before routes are served
+- [**Plugins**](/docs/server-plugins): startup plugins and their initialization behavior
 - [**Middleware**](/docs/server-middleware): auth guards that protect all routes including `/api/*`
 - [**Security**](/docs/security#access-guards): `accessFilter`/`assertAccess` and the full data-scoping model

package/docs/content/tracking.mdx

@@ -15,7 +15,7 @@ import { track } from "@agent-native/core/tracking";
 track(
   "order.completed",
   { total: 49.99, items: 3 },
-  { userId: "steve@builder.io" },
+  { userId: "user@example.com" },
 );
 ```
 
@@ -126,7 +126,7 @@ import { track } from "@agent-native/core/tracking";
 track(
   "meal.logged",
   { mealName: "Salad", calories: 350 },
-  { userId: "steve@builder.io" },
+  { userId: "user@example.com" },
 );
 ```
 
@@ -150,7 +150,7 @@ Identify a user with traits. Forwarded to providers that support it (PostHog, Mi
 ```ts
 import { identify } from "@agent-native/core/tracking";
 
-identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+identify("user@example.com", { plan: "pro", company: "Builder.io" });
 ```
 
 Need a custom backend, the provider-registry API, or the batching/singleton internals? See [Advanced: custom providers & internals](#advanced) at the end.
@@ -391,5 +391,5 @@ The framework also tracks `builder connect clicked` from Connect Builder CTAs, a
 ## What's next
 
 - [**Actions**](/docs/actions) — where most tracking calls originate
-- [**Server Plugins**](/docs/server#server-plugins) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
+- [**Server Plugins**](/docs/server-plugins) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
 - [**Security — Secrets Management**](/docs/security#secrets) — manage API keys for tracking providers

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

@@ -39,7 +39,7 @@ The UI updates in real time as the agent opens views, edits drafts, and runs rep
 
 ### Steer it like a teammate
 
-Give feedback, queue tasks, audit what it did, edit its instructions. It remembers, and it improves.
+Give feedback, queue tasks, audit what it did, and edit its instructions.
 
 </Cards>
 
@@ -93,7 +93,7 @@ graph TD
   DB --> AG_OUT
 ```
 
-The diagram above shows what this looks like at runtime: both the user and the agent submit actions to the same layer, which writes to the same database and broadcasts updates back to both surfaces. When the agent creates a draft email, it appears in your inbox immediately. When you click Send, the agent knows it was sent. See [Key Concepts](/docs/key-concepts) for the full architecture.
+The diagram above shows what this looks like at runtime: both the user and the agent submit actions to the same layer, which writes to the same database and sends updates back to both surfaces. When the agent creates a draft email, it appears in your inbox immediately. When you click Send, the agent knows it was sent. See [Key Concepts](/docs/key-concepts) for the full architecture.
 
 ## Why agents need a UI — and apps need an agent {#why-both}
 
@@ -211,7 +211,7 @@ Browse [agent-native.com/templates](/templates) and pick the one closest to what
 
 ### Use it immediately
 
-Every template deploys as a hosted app (e.g. `mail.agent-native.com`). Try it before you touch any code.
+Many first-party templates are available as hosted apps (e.g. `mail.agent-native.com`). Try one before you touch any code.
 
 ### Clone and customize
 
@@ -235,7 +235,7 @@ Agent-native apps can talk to each other. From inside the mail app, you can tag
 
 ### [Getting Started](/docs/getting-started)
 
-Build a working chat app in under five minutes, then add actions, a database, and a page.
+Build a working chat app in under five minutes, then add an action and a page. Add your own database tables when you need to persist domain data.
 
 ### [Key Concepts](/docs/key-concepts)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.148.0",
+  "version": "0.149.0",
   "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": {
@@ -414,7 +414,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.4",
-    "@agent-native/toolkit": "^0.13.7"
+    "@agent-native/toolkit": "^0.13.8"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/default/app/i18n/ar-SA.ts

@@ -232,7 +232,7 @@ const messages = {
     newTerminal: "محطة جديدة",
     panelOptions: "خيارات لوحة الوكيل",
     collapseSidebar: "طي الشريط الجانبي",
-    widenChat: "توسيع الدردشة إلى 75٪",
+    widenChat: "توسيع الدردشة",
     returnChatToLayout: "إعادة الدردشة إلى تخطيط الصفحة",
     hideChats: "إخفاء الدردشات",
     allChats: "جميع الدردشات",

package/src/templates/default/app/i18n/de-DE.ts

@@ -234,7 +234,7 @@ const messages = {
     newTerminal: "Neues Terminal",
     panelOptions: "Optionen im Agentenpanel",
     collapseSidebar: "Seitenleiste einklappen",
-    widenChat: "Chat auf 75 % verbreitern",
+    widenChat: "Chat verbreitern",
     returnChatToLayout: "Chat zurück ins Layout",
     hideChats: "Chats ausblenden",
     allChats: "Alle Chats",

package/src/templates/default/app/i18n/en-US.ts

@@ -229,7 +229,7 @@ const messages = {
     newTerminal: "New terminal",
     panelOptions: "Agent panel options",
     collapseSidebar: "Collapse sidebar",
-    widenChat: "Widen chat to 75%",
+    widenChat: "Widen chat",
     returnChatToLayout: "Return chat to layout",
     hideChats: "Hide chats",
     allChats: "All chats",

package/src/templates/default/app/i18n/es-ES.ts

@@ -235,7 +235,7 @@ const messages = {
     newTerminal: "Nueva terminal",
     panelOptions: "Opciones del panel de agentes",
     collapseSidebar: "Contraer barra lateral",
-    widenChat: "Ampliar el chat al 75 %",
+    widenChat: "Ampliar el chat",
     returnChatToLayout: "Devolver el chat al diseño",
     hideChats: "Ocultar chats",
     allChats: "Todos los chats",

package/src/templates/default/app/i18n/fr-FR.ts

@@ -236,7 +236,7 @@ const messages = {
     newTerminal: "Nouvelle borne",
     panelOptions: "Options du panneau d'agent",
     collapseSidebar: "Réduire la barre latérale",
-    widenChat: "Élargir le chat à 75 %",
+    widenChat: "Élargir le chat",
     returnChatToLayout: "Remettre le chat dans la mise en page",
     hideChats: "Masquer les discussions",
     allChats: "Toutes les discussions",

package/src/templates/default/app/i18n/hi-IN.ts

@@ -221,7 +221,7 @@ const messages = {
     newTerminal: "नया टर्मिनल",
     panelOptions: "एजेंट पैनल विकल्प",
     collapseSidebar: "साइडबार समेटें",
-    widenChat: "चैट को 75% चौड़ा करें",
+    widenChat: "चैट को चौड़ा करें",
     returnChatToLayout: "चैट को लेआउट में वापस लाएँ",
     hideChats: "चैट छुपाएं",
     allChats: "सभी चैट",

package/src/templates/default/app/i18n/ja-JP.ts

@@ -230,7 +230,7 @@ const messages = {
     newTerminal: "新しいターミナル",
     panelOptions: "エージェントパネルのオプション",
     collapseSidebar: "サイドバーを折りたたむ",
-    widenChat: "チャットを75%に広げる",
+    widenChat: "チャットを広げる",
     returnChatToLayout: "チャットをレイアウトに戻す",
     hideChats: "チャットを非表示にする",
     allChats: "すべてのチャット",

package/src/templates/default/app/i18n/ko-KR.ts

@@ -225,7 +225,7 @@ const messages = {
     newTerminal: "새로운 터미널",
     panelOptions: "상담원 패널 옵션",
     collapseSidebar: "사이드바 접기",
-    widenChat: "채팅을 75% 너비로 넓히기",
+    widenChat: "채팅 넓히기",
     returnChatToLayout: "채팅을 레이아웃으로 되돌리기",
     hideChats: "채팅 숨기기",
     allChats: "모든 채팅",

package/src/templates/default/app/i18n/pt-BR.ts

@@ -234,7 +234,7 @@ const messages = {
     newTerminal: "Novo terminal",
     panelOptions: "Opções do painel do agente",
     collapseSidebar: "Recolher barra lateral",
-    widenChat: "Ampliar o chat para 75%",
+    widenChat: "Ampliar o chat",
     returnChatToLayout: "Retornar o chat ao layout",
     hideChats: "Ocultar bate-papos",
     allChats: "Todos os bate-papos",

package/src/templates/default/app/i18n/zh-CN.ts

@@ -219,7 +219,7 @@ const messages = {
     newTerminal: "新航站楼",
     panelOptions: "代理面板选项",
     collapseSidebar: "收起侧边栏",
-    widenChat: "将聊天窗口加宽到 75%",
+    widenChat: "加宽聊天窗口",
     returnChatToLayout: "将聊天窗口恢复到布局中",
     hideChats: "隐藏聊天记录",
     allChats: "所有聊天记录",

package/src/templates/default/app/i18n/zh-TW.ts

@@ -217,7 +217,7 @@ const messages = {
     newTerminal: "新航站樓",
     panelOptions: "代理面板選項",
     collapseSidebar: "收起側邊欄",
-    widenChat: "將聊天視窗加寬至 75%",
+    widenChat: "將聊天視窗加寬",
     returnChatToLayout: "將聊天視窗放回版面配置",
     hideChats: "隱藏聊天紀錄",
     allChats: "所有聊天紀錄",

package/src/templates/default/pnpm-workspace.yaml

@@ -6,3 +6,4 @@ overrides:
 allowBuilds:
   better-sqlite3: true
   esbuild: true
+  tesseract.js: true

package/src/templates/workspace-root/pnpm-workspace.yaml

@@ -24,6 +24,7 @@ onlyBuiltDependencies:
   - esbuild
   - lightningcss
   - node-pty
+  - tesseract.js
 
 allowBuilds:
   "@swc/core": true
@@ -33,3 +34,4 @@ allowBuilds:
   esbuild: true
   lightningcss: true
   node-pty: true
+  tesseract.js: true