@agent-native/core 0.47.1 → 0.48.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.47.1",
+  "version": "0.48.1",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -21,7 +21,7 @@
     "provenance": true
   },
   "bin": {
-    "agent-native": "dist/cli/index.js"
+    "agent-native": "bin/agent-native.js"
   },
   "exports": {
     ".": {
@@ -30,6 +30,7 @@
     },
     "./vite": "./dist/vite/index.js",
     "./server": "./dist/server/index.js",
+    "./server/entry-server": "./dist/server/entry-server.js",
     "./server/ssr-handler": "./dist/server/ssr-handler.js",
     "./server/agent-discovery": "./dist/server/agent-discovery.js",
     "./server/request-context": "./dist/server/request-context.js",
@@ -41,6 +42,12 @@
     "./db/schema": "./dist/db/schema.js",
     "./db/drizzle-config": "./dist/db/drizzle-config.js",
     "./client": "./dist/client/index.js",
+    "./client/chat": "./dist/client/chat/index.js",
+    "./client/collab": "./dist/client/collab/index.js",
+    "./client/composer": "./dist/client/composer/index.js",
+    "./client/conversation": "./dist/client/conversation/index.js",
+    "./client/editor": "./dist/client/editor/index.js",
+    "./client/resources": "./dist/client/resources/index.js",
     "./blocks": "./dist/client/blocks/index.js",
     "./blocks/server": "./dist/client/blocks/server.js",
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
@@ -97,6 +104,12 @@
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
     "./provider-api": "./dist/provider-api/index.js",
+    "./provider-api/staging": "./dist/provider-api/staging.js",
+    "./provider-api/staged-datasets-store": "./dist/provider-api/staged-datasets-store.js",
+    "./provider-api/staged-datasets-aggregate": "./dist/provider-api/staged-datasets-aggregate.js",
+    "./provider-api/actions/query-staged-dataset": "./dist/provider-api/actions/query-staged-dataset.js",
+    "./provider-api/actions/list-staged-datasets": "./dist/provider-api/actions/list-staged-datasets.js",
+    "./provider-api/actions/delete-staged-dataset": "./dist/provider-api/actions/delete-staged-dataset.js",
     "./workspace-files": "./dist/workspace-files/index.js",
     "./code-agents": "./dist/code-agents/index.js",
     "./code-agents/transcript-normalizer": "./dist/code-agents/transcript-normalizer.js",
@@ -113,14 +126,18 @@
     "./agent/engine": "./dist/agent/engine/index.js",
     "./tsconfig.base.json": "./tsconfig.base.json"
   },
+  "sideEffects": [
+    "*.css"
+  ],
   "files": [
+    "bin",
     "dist",
     "docs",
     "tsconfig.base.json",
     "src/templates"
   ],
   "scripts": {
-    "build": "tsc && node scripts/finalize-build.mjs",
+    "build": "tsc && tsc -p tsconfig.cli.json && node scripts/finalize-build.mjs",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest --run src",
@@ -154,7 +171,6 @@
     "@sentry/browser": "^10.50.0",
     "@sentry/node": "^10.50.0",
     "@standard-schema/spec": "^1.1.0",
-    "@tabler/icons-react": "^3",
     "@tailwindcss/typography": "^0.5.19",
     "@tanstack/react-table": "^8.21.3",
     "@tiptap/core": "^3.26.0",
@@ -175,7 +191,7 @@
     "@tiptap/starter-kit": "^3.26.0",
     "@tiptap/y-tiptap": "^3.0.4",
     "@uiw/react-codemirror": "^4.25.10",
-    "better-auth": "1.6.0",
+    "better-auth": "1.6.16",
     "better-sqlite3": "^12.8.0",
     "clsx": "^2.1.1",
     "cron-parser": "^5.5.0",
@@ -198,7 +214,7 @@
     "prettier": "^3.8.3",
     "react-markdown": "^10.1.0",
     "react-router": "^7.16.0",
-    "recharts": "3.8.1",
+    "recharts": "^3.8.1",
     "remark-gfm": "^4.0.1",
     "roughjs": "4.6.6",
     "shiki": "^4.0.2",
@@ -354,6 +370,7 @@
     "@types/node": "^24.2.1",
     "@types/pako": "^2.0.4",
     "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react-swc": "^4.0.0",
     "@vitest/coverage-v8": "4.1.5",
@@ -364,6 +381,8 @@
     "autoprefixer": "^10.4.21",
     "drizzle-kit": "^0.31.10",
     "express": "^5.2.1",
+    "next-themes": "^0.4.6",
+    "sonner": "^2.0.7",
     "mermaid": "11.15.0",
     "node-pty": "^1.1.0",
     "playwright": "^1.60.0",

package/src/templates/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -13,7 +13,11 @@ metadata:
 
 ## Rule
 
-The UI and server never call an LLM directly. All AI work is delegated to the agent through the chat bridge.
+The UI never calls an LLM directly. Product workflows are delegated to the
+agent through the chat bridge so users can see, steer, and audit the work.
+Server-side one-shot model calls are an explicit escape hatch for narrow text
+transforms only; use `completeText()` from `@agent-native/core/server` when the
+work intentionally does not need tools, chat history, or run state.
 
 ## Why
 
@@ -33,6 +37,24 @@ sendToAgentChat({
 });
 ```
 
+**From the UI, in the background:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+
+sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run: tools, actions, thread state, and run tracking
+all remain active. It simply does not focus or open the sidebar.
+
 **From scripts (Node):**
 
 ```ts
@@ -41,6 +63,22 @@ import { agentChat } from "@agent-native/core";
 agentChat.submit("Process the uploaded images and create thumbnails");
 ```
 
+**For narrow server-side text transforms:**
+
+```ts
+import { completeText } from "@agent-native/core/server";
+
+const result = await completeText({
+  systemPrompt: "Return exactly one sentiment label.",
+  input: messageBody,
+  maxOutputTokens: 12,
+  temperature: 0,
+});
+```
+
+Wrap user-facing uses in actions so the UI and agent share the same operation.
+Do not call provider SDKs directly.
+
 **From the UI, detecting when agent is done:**
 
 ```ts
@@ -183,10 +221,20 @@ rather than ad-hoc LLM calls.
 - Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
 - Don't build "AI features" that bypass the agent chat
 - Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+- Don't use `completeText()` for workflows that need tools, database writes,
+  auditability, user steering, or multi-step reasoning. Use the agent chat
+  instead, optionally with `background: true`.
 
 ## Exception
 
-Scripts may call external APIs (image generation, search, etc.) — but the AI reasoning and orchestration still goes through the agent. A script is a tool the agent uses, not a replacement for the agent.
+Scripts may call external APIs (image generation, search, etc.) — but the AI
+reasoning and orchestration still goes through the agent. A script is a tool
+the agent uses, not a replacement for the agent.
+
+`completeText()` is allowed for small server-side transforms such as
+classification, extraction, rewriting a short string, or normalizing messy
+provider text. It deliberately runs with `tools: []` and does not create chat
+thread state.
 
 ## When to Use A2A Instead
 

package/src/templates/default/AGENTS.md

@@ -7,7 +7,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 ### Core Principles
 
 1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
-2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips.
+2. **AI through the right framework surface** -- Product workflows delegate to the agent via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows; add `newTab: true, background: true, openSidebar: false` when the agent should work silently without focusing the sidebar. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips. For rare server-side text transforms that intentionally need no tools, chat history, or run state, use `completeText()` from `@agent-native/core/server` inside an action instead of importing provider SDKs directly.
 3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
 4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.

package/src/templates/default/DEVELOPING.md

@@ -101,6 +101,8 @@ sendToAgentChat({
 
 For most UI handoffs, pass hidden context directly with `sendToAgentChat()`. Use
 `submit: false` when the user should review the draft first. Use
+`newTab: true, background: true, openSidebar: false` when a button should start
+a full agent run without opening or focusing the sidebar. Use
 `useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`,
 `removeAgentChatContextItem`, and `clearAgentChatContext` only for advanced UI
 that needs to read, mirror, stage, remove, or clear staged context chips as local
@@ -113,6 +115,23 @@ import { agentChat } from "@agent-native/core";
 agentChat.submit("Generate something");
 ```
 
+**Server-side one-shot text transforms:**
+
+```ts
+import { completeText } from "@agent-native/core/server";
+
+const result = await completeText({
+  systemPrompt: "Return exactly one category label.",
+  input: body,
+  maxOutputTokens: 16,
+  temperature: 0,
+});
+```
+
+Use this only for narrow transforms that intentionally need no tools, chat
+history, or run state. For user-facing operations, call it inside an action so
+the UI and agent share the same capability.
+
 ## Database
 
 Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.

package/src/templates/default/app/entry.client.tsx

@@ -1,4 +1,7 @@
-import { appBasePath } from "@agent-native/core/client";
+// Import only the tiny URL-helper module, not the full client barrel.
+// This keeps the ~650-700 KB gzip chat stack off the static import closure
+// of the client entry point so it can't block the first page parse.
+import { appBasePath } from "@agent-native/core/client/api-path";
 import { hydrateRoot } from "react-dom/client";
 import { HydratedRouter } from "react-router/dom";
 

package/src/templates/default/app/entry.server.tsx

@@ -1,56 +1,4 @@
-import type { AppLoadContext, EntryContext } from "react-router";
-import { ServerRouter } from "react-router";
-import ReactDOMServer from "react-dom/server.browser";
-const { renderToReadableStream } = ReactDOMServer;
-import { isbot } from "isbot";
-import { wrapWithAnalytics } from "@agent-native/core/server";
-
-export const streamTimeout = 5_000;
-
-export default async function handleRequest(
-  request: Request,
-  responseStatusCode: number,
-  responseHeaders: Headers,
-  routerContext: EntryContext,
-  _loadContext: AppLoadContext,
-) {
-  if (request.method.toUpperCase() === "HEAD") {
-    return new Response(null, {
-      status: responseStatusCode,
-      headers: responseHeaders,
-    });
-  }
-
-  const userAgent = request.headers.get("user-agent");
-  const waitForAll = (userAgent && isbot(userAgent)) || routerContext.isSpaMode;
-
-  const abortController = new AbortController();
-  const timeoutId = setTimeout(() => abortController.abort(), streamTimeout);
-
-  try {
-    const body = await renderToReadableStream(
-      <ServerRouter context={routerContext} url={request.url} />,
-      {
-        signal: abortController.signal,
-        onError(error: unknown) {
-          if (!abortController.signal.aborted) {
-            responseStatusCode = 500;
-            console.error(error);
-          }
-        },
-      },
-    );
-
-    if (waitForAll) {
-      await body.allReady;
-    }
-
-    responseHeaders.set("Content-Type", "text/html");
-    return new Response(wrapWithAnalytics(body), {
-      headers: responseHeaders,
-      status: responseStatusCode,
-    });
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
+export {
+  handleDocumentRequest as default,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";

package/src/templates/default/app/global.css

@@ -1,4 +1,5 @@
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap");
+/* Self-hosted via @fontsource-variable/inter — no render-blocking Google Fonts request */
+@import "@fontsource-variable/inter";
 
 @import "tailwindcss";
 @import "@agent-native/core/styles/agent-native.css";
@@ -71,7 +72,7 @@
   body {
     background: hsl(var(--background));
     color: hsl(var(--foreground));
-    font-family: "Inter", sans-serif;
+    font-family: "Inter Variable", "Inter", sans-serif;
     font-feature-settings: "cv02", "cv03", "cv04", "cv11";
   }
 }

package/src/templates/default/app/root.tsx

@@ -9,20 +9,14 @@ import {
   useRouteError,
 } from "react-router";
 import { useEffect, useState } from "react";
-import {
-  QueryClient,
-  QueryClientProvider,
-  useQueryClient,
-} from "@tanstack/react-query";
-import { ThemeProvider } from "next-themes";
+import { useQueryClient } from "@tanstack/react-query";
 import { useDbSync } from "@agent-native/core";
 import {
-  ClientOnly,
-  DefaultSpinner,
+  AppProviders,
   appPath,
   getThemeInitScript,
+  createAgentNativeQueryClient,
 } from "@agent-native/core/client";
-import { Toaster } from "sonner";
 import { configureTracking } from "@agent-native/core/client";
 import { useNavigationState } from "./hooks/use-navigation-state";
 import { TAB_ID } from "./lib/tab-id";
@@ -92,22 +86,12 @@ function DbSyncSetup() {
 }
 
 export default function Root() {
-  const [queryClient] = useState(() => new QueryClient());
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
   return (
-    <ClientOnly fallback={<DefaultSpinner />}>
-      <ThemeProvider
-        attribute="class"
-        defaultTheme="system"
-        enableSystem
-        disableTransitionOnChange
-      >
-        <QueryClientProvider client={queryClient}>
-          <DbSyncSetup />
-          <Outlet />
-          <Toaster richColors position="bottom-left" />
-        </QueryClientProvider>
-      </ThemeProvider>
-    </ClientOnly>
+    <AppProviders queryClient={queryClient}>
+      <DbSyncSetup />
+      <Outlet />
+    </AppProviders>
   );
 }
 

package/src/templates/default/app/routes/_index.tsx

@@ -1,23 +1,10 @@
 import { useTheme } from "next-themes";
-import { IconLoader2 } from "@tabler/icons-react";
 import { useActionQuery } from "@agent-native/core/client";
 
 export function meta() {
   return [{ title: "{{APP_TITLE}}" }];
 }
 
-export function HydrateFallback() {
-  return (
-    <div className="flex items-center justify-center h-screen">
-      <IconLoader2
-        className="size-8 animate-spin text-foreground"
-        role="status"
-        aria-label="Loading"
-      />
-    </div>
-  );
-}
-
 export default function IndexPage() {
   const { resolvedTheme, setTheme } = useTheme();
   const isDark = resolvedTheme === "dark";

package/src/templates/default/package.json

@@ -14,7 +14,8 @@
     "@agent-native/core": "latest",
     "@assistant-ui/react": "^0.12.19",
     "@assistant-ui/react-markdown": "^0.12.6",
-    "@tabler/icons-react": "^3.40.0",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@tabler/icons-react": "catalog:",
     "h3": "^2.0.1-rc.20",
     "isbot": "^5",
     "postgres": "^3.4.9",
@@ -26,14 +27,14 @@
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-query": "^5.99.2",
     "@types/node": "^24.2.1",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "next-themes": "^0.4.6",
     "prettier": "^3.6.2",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "react-router": "^7.16.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",

package/src/templates/default/tsconfig.json

@@ -6,6 +6,7 @@
     "shared/**/*",
     "vite.config.ts",
     "react-router.config.ts",
-    ".react-router/types/**/*"
+    ".react-router/types/**/*",
+    ".generated/**/*"
   ]
 }

package/src/templates/starter-shell-sync.spec.ts

@@ -0,0 +1,118 @@
+/**
+ * Guard: the scaffold template (packages/core/src/templates/default) and
+ * templates/starter must ship byte-identical shell files so that scaffolded
+ * apps start from exactly the same code as the reference starter template.
+ *
+ * When you update entry.server.tsx or entry.client.tsx in either location,
+ * update the other copy to match (copy in either direction — the content is
+ * canonical, not the direction).
+ *
+ * Sync commands:
+ *   # scaffold → starter
+ *   cp packages/core/src/templates/default/app/entry.server.tsx \
+ *      templates/starter/app/entry.server.tsx
+ *   cp packages/core/src/templates/default/app/entry.client.tsx \
+ *      templates/starter/app/entry.client.tsx
+ *
+ *   # starter → scaffold
+ *   cp templates/starter/app/entry.server.tsx \
+ *      packages/core/src/templates/default/app/entry.server.tsx
+ *   cp templates/starter/app/entry.client.tsx \
+ *      packages/core/src/templates/default/app/entry.client.tsx
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+function workspaceRoot(): string {
+  let current = process.cwd();
+  while (current !== path.dirname(current)) {
+    if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  throw new Error("Could not locate workspace root (pnpm-workspace.yaml).");
+}
+
+const ROOT = workspaceRoot();
+
+const SCAFFOLD_DIR = path.join(ROOT, "packages/core/src/templates/default/app");
+const STARTER_DIR = path.join(ROOT, "templates/starter/app");
+
+function md5(content: string): string {
+  return crypto.createHash("md5").update(content).digest("hex");
+}
+
+function readFile(dir: string, filename: string): string {
+  return fs.readFileSync(path.join(dir, filename), "utf-8");
+}
+
+/**
+ * Shell files that must be byte-identical between scaffold and starter.
+ * Each entry is [filename, reason]:
+ *   entry.server.tsx — both now re-export the shared core handler; any
+ *     future change to the pattern must land in both places at once.
+ *   entry.client.tsx — lightweight hydration entry that sets basename from
+ *     APP_BASE_PATH; must stay in sync for workspace-mount correctness.
+ */
+const SHELL_FILES: Array<[string, string]> = [
+  [
+    "entry.server.tsx",
+    "re-exports @agent-native/core/server/entry-server; must be identical",
+  ],
+  [
+    "entry.client.tsx",
+    "basename hydration from APP_BASE_PATH; must be identical",
+  ],
+];
+
+describe("starter-shell sync guard", () => {
+  it("keeps scaffold and starter shell files byte-identical", () => {
+    const violations: string[] = [];
+
+    for (const [filename] of SHELL_FILES) {
+      const scaffoldContent = readFile(SCAFFOLD_DIR, filename);
+      const starterContent = readFile(STARTER_DIR, filename);
+
+      const scaffoldHash = md5(scaffoldContent);
+      const starterHash = md5(starterContent);
+
+      if (scaffoldHash !== starterHash) {
+        violations.push(
+          `${filename}: scaffold (packages/core/src/templates/default/app) and starter (templates/starter/app) differ.\n` +
+            `  Update both to match or copy one to the other.`,
+        );
+      }
+    }
+
+    expect(
+      violations,
+      [
+        "Scaffold/starter shell files have drifted.",
+        "Copy the updated file to the other location to fix.",
+        "",
+        ...violations,
+      ].join("\n"),
+    ).toEqual([]);
+  });
+
+  it("every listed shell file exists in both scaffold and starter", () => {
+    for (const [filename, reason] of SHELL_FILES) {
+      const scaffoldPath = path.join(SCAFFOLD_DIR, filename);
+      const starterPath = path.join(STARTER_DIR, filename);
+
+      expect(
+        fs.existsSync(scaffoldPath),
+        `${filename} missing from scaffold (${reason})`,
+      ).toBe(true);
+
+      expect(
+        fs.existsSync(starterPath),
+        `${filename} missing from starter (${reason})`,
+      ).toBe(true);
+    }
+  });
+});