@agent-native/core 0.119.6 → 0.120.0

package/corpus/README.md

@@ -30,4 +30,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 - core files: 1662
 - toolkit files: 159
-- template files: 6331
+- template files: 6334

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/core
 
+## 0.120.0
+
+### Minor Changes
+
+- 20ebb96: `agent-native dev --inspect` (and `--inspect-brk`, optionally `=<port>`) now
+  attaches the Node inspector to **only** the Nitro API-server process, on a
+  single known port (default 9229). It selects Nitro's `node-process` dev runner
+  so the server is a real, attachable process, and injects `NODE_OPTIONS` through
+  a Vite preload that runs before Vite's own startup — so Vite, pnpm, and the CLI
+  are never inspected and there is exactly one debugger target. Set
+  `NITRO_DEV_RUNNER` yourself to override the runner.
+
 ## 0.119.6
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.119.6",
+  "version": "0.120.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": {

package/corpus/core/src/cli/index.ts

@@ -276,6 +276,22 @@ function findViteBin(): string {
   return findBinUpwards("vite") ?? "vite";
 }
 
+function findViteJsEntry(): string | null {
+  try {
+    const require = createRequire(path.join(process.cwd(), "package.json"));
+    const pkgJsonPath = require.resolve("vite/package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8")) as {
+      bin?: string | Record<string, string>;
+    };
+    const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vite;
+    if (!rel) return null;
+    const entry = path.join(path.dirname(pkgJsonPath), rel);
+    return fs.existsSync(entry) ? entry : null;
+  } catch {
+    return null;
+  }
+}
+
 function findTsxBin(): string {
   const localTsx = path.resolve("node_modules/.bin/tsx");
   if (fs.existsSync(localTsx)) return localTsx;
@@ -386,15 +402,31 @@ function isWorkspaceRoot(): boolean {
   }
 }
 
+function extractNodeInspectFlag(args: string[]): {
+  inspectFlag: string | null;
+  rest: string[];
+} {
+  const rest: string[] = [];
+  let inspectFlag: string | null = null;
+  for (const arg of args) {
+    if (/^--inspect(-brk)?(=.+)?$/.test(arg)) {
+      inspectFlag = arg;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { inspectFlag, rest };
+}
+
 function run(
   cmd: string,
   cmdArgs: string[],
-  opts?: { stdio?: "inherit" | "pipe" },
+  opts?: { stdio?: "inherit" | "pipe"; env?: NodeJS.ProcessEnv },
 ) {
   const child = spawn(cmd, cmdArgs, {
     stdio: opts?.stdio ?? "inherit",
     shell: process.platform === "win32",
-    env: process.env,
+    env: opts?.env ?? process.env,
   });
   child.on("exit", (code) => process.exit(code ?? 0));
   // Forward signals to child so Cmd+C doesn't leave zombie processes holding ports
@@ -545,7 +577,36 @@ switch (command) {
       break;
     }
     const vite = findViteBin();
-    run(vite, args);
+    const { inspectFlag, rest } = extractNodeInspectFlag(args);
+    if (!inspectFlag) {
+      run(vite, rest);
+      break;
+    }
+    const viteJsEntry = findViteJsEntry();
+    if (!viteJsEntry) {
+      console.warn(
+        "[agent-native] Could not resolve Vite's JS entry; starting dev " +
+          "server without the debugger.",
+      );
+      run(vite, rest);
+      break;
+    }
+    // Attach inspect flag to server process (not Vite or Nitro process)
+    const parsed = inspectFlag.match(/^--(inspect(?:-brk)?)(?:=(.+))?$/);
+    const kind = parsed?.[1] ?? "inspect";
+    const target = parsed?.[2] ?? "9229";
+    const directive = `--${kind}=${target}`;
+    const preload =
+      "data:text/javascript," +
+      encodeURIComponent(
+        `process.env.NODE_OPTIONS=((process.env.NODE_OPTIONS??"")+" ${directive}").trim();`,
+      );
+    const env = {
+      ...process.env,
+      NITRO_DEV_RUNNER: process.env.NITRO_DEV_RUNNER ?? "node-process",
+    };
+    console.log(`[agent-native] API server debugger listening on ${target}`);
+    run(process.execPath, ["--import", preload, viteJsEntry, ...rest], { env });
     break;
   }
 

package/corpus/core/src/templates/default/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "typecheck": "agent-native typecheck",

package/corpus/templates/assets/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run",

package/corpus/templates/brain/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run --config vitest.config.ts",

package/corpus/templates/calendar/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run",

package/corpus/templates/clips/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "agent-native dev",
+    "dev": "agent-native dev --inspect",
     "build": "agent-native build",
     "start": "agent-native start",
     "typecheck": "agent-native typecheck",

package/corpus/templates/content/actions/add-database-item.ts

@@ -217,6 +217,7 @@ export default defineAction({
       ...(await getContentDatabaseResponse(databaseId)),
       createdItemId: itemId,
       createdDocumentId: documentId,
+      createdDocumentUpdatedAt: now,
     };
   },
 });

package/corpus/templates/content/actions/set-document-property.ts

@@ -1,5 +1,4 @@
 import { defineAction } from "@agent-native/core";
-import { writeAppState } from "@agent-native/core/application-state";
 import { assertAccess } from "@agent-native/core/sharing";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
@@ -87,7 +86,6 @@ export default defineAction({
           now,
         });
       }
-      await writeAppState("refresh-signal", { ts: Date.now() });
       return {
         documentId,
         databaseId: database.id,
@@ -133,8 +131,6 @@ export default defineAction({
       });
     }
 
-    await writeAppState("refresh-signal", { ts: Date.now() });
-
     return {
       documentId,
       databaseId: database.id,

package/corpus/templates/content/app/components/editor/DocumentBlockFields.tsx

@@ -38,6 +38,7 @@ const BLOCK_FIELD_DRAG_THRESHOLD = 6;
 
 interface DocumentBlockFieldsProps {
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   /**
    * The fully-wired collaborative body editor for the primary "Content" field.
@@ -238,6 +239,7 @@ export function blockFieldsRenderState(args: {
  */
 export function DocumentBlockFields({
   documentId,
+  databaseDocumentId,
   canEdit,
   primaryEditor,
 }: DocumentBlockFieldsProps) {
@@ -303,6 +305,7 @@ export function DocumentBlockFields({
               // field while SAVING to another across an identity change.
               key={`${documentId}:${state.field.definition.id}`}
               documentId={documentId}
+              databaseDocumentId={databaseDocumentId}
               property={state.field}
               canEdit={canEdit}
             />
@@ -318,6 +321,7 @@ export function DocumentBlockFields({
       return (
         <MultiBlockFields
           documentId={documentId}
+          databaseDocumentId={databaseDocumentId}
           canEdit={canEdit}
           blockFields={state.fields}
           primaryEditor={primaryEditor}
@@ -329,12 +333,14 @@ export function DocumentBlockFields({
 
 function MultiBlockFields({
   documentId,
+  databaseDocumentId,
   canEdit,
   blockFields,
   primaryEditor,
   t,
 }: {
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   blockFields: DocumentProperty[];
   primaryEditor: ReactNode;
@@ -504,6 +510,7 @@ function MultiBlockFields({
                   // doc's edits to the old field's closure.
                   key={`${documentId}:${property.definition.id}`}
                   documentId={documentId}
+                  databaseDocumentId={databaseDocumentId}
                   property={property}
                   canEdit={canEdit}
                 />
@@ -789,14 +796,16 @@ export function useBlockFieldEditor({
  */
 function AdditionalBlockEditor({
   documentId,
+  databaseDocumentId,
   property,
   canEdit,
 }: {
   documentId: string;
+  databaseDocumentId: string;
   property: DocumentProperty;
   canEdit: boolean;
 }) {
-  const setProperty = useSetDocumentProperty(documentId);
+  const setProperty = useSetDocumentProperty(documentId, databaseDocumentId);
   const propertyId = property.definition.id;
   const initialContent =
     typeof property.value === "string" ? property.value : "";

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -80,6 +80,7 @@ import {
   canWriteLinkedLocalSource,
   writeDocumentToLinkedLocalSource,
 } from "@/lib/local-content-source-files";
+import { isDatabaseChoicePending } from "@/lib/optimistic-document";
 import { cn } from "@/lib/utils";
 
 import {
@@ -1519,6 +1520,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   );
   const defaultIconKind = documentEditorDefaultIconKind(document);
   const isDatabasePage = Boolean(document.database);
+  const databaseChoicePending = isDatabaseChoicePending(
+    document,
+    createDatabase.isPending,
+  );
   const showNewDocumentTypeChooser =
     canEdit &&
     !isLocalFileDocument &&
@@ -1791,12 +1796,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                               type="button"
                               variant="outline"
                               className="justify-start gap-2"
-                              disabled={
-                                !editorCanEdit || createDatabase.isPending
-                              }
+                              disabled={!editorCanEdit || databaseChoicePending}
                               onClick={() => void handleChooseDatabase()}
                             >
-                              {createDatabase.isPending ? (
+                              {databaseChoicePending ? (
                                 <IconLoader2 className="animate-spin" />
                               ) : (
                                 <IconDatabase />
@@ -1867,6 +1870,9 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                         return (
                           <DocumentBlockFields
                             documentId={documentId}
+                            databaseDocumentId={
+                              document.databaseMembership.databaseDocumentId
+                            }
                             canEdit={editorCanEdit}
                             primaryEditor={primaryEditor}
                           />

package/corpus/templates/content/app/components/editor/DocumentInfoPanel.tsx

@@ -32,7 +32,11 @@ export function DocumentInfoPanel({
         onSave={onSaveDescription}
       />
       {document.databaseMembership && !isLocalFileDocument ? (
-        <DocumentProperties documentId={document.id} canEdit={canEdit} />
+        <DocumentProperties
+          documentId={document.id}
+          databaseDocumentId={document.databaseMembership.databaseDocumentId}
+          canEdit={canEdit}
+        />
       ) : null}
     </div>
   );

package/corpus/templates/content/app/components/editor/DocumentProperties.tsx

@@ -165,6 +165,7 @@ function tWithFallback(
 
 interface DocumentPropertiesProps {
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   popoversPortalled?: boolean;
 }
@@ -796,6 +797,7 @@ function scalarPlaceholder(type: DocumentPropertyType, t: TFunction) {
 
 export function DocumentProperties({
   documentId,
+  databaseDocumentId,
   canEdit,
   popoversPortalled = true,
 }: DocumentPropertiesProps) {
@@ -826,6 +828,7 @@ export function DocumentProperties({
               key={property.definition.id}
               property={property}
               documentId={documentId}
+              databaseDocumentId={databaseDocumentId}
               canEdit={canEdit}
               popoversPortalled={popoversPortalled}
               t={t}
@@ -927,12 +930,14 @@ function HiddenPropertiesMenu({
 function PropertyRow({
   property,
   documentId,
+  databaseDocumentId,
   canEdit,
   popoversPortalled,
   t,
 }: {
   property: DocumentProperty;
   documentId: string;
+  databaseDocumentId: string;
   canEdit: boolean;
   popoversPortalled: boolean;
   t: TFunction;
@@ -978,6 +983,7 @@ function PropertyRow({
         <PropertyValuePopover
           property={property}
           documentId={documentId}
+          databaseDocumentId={databaseDocumentId}
           portalled={popoversPortalled}
         >
           {value}

package/corpus/templates/content/app/components/editor/database/DatabaseView.tsx

@@ -197,6 +197,7 @@ import {
 } from "@/hooks/use-document-properties";
 import {
   isDocumentUpdateConflict,
+  type DocumentUpdateResult,
   useDeleteDocument,
   useDocument,
   seedDatabaseItemDocumentCaches,
@@ -254,7 +255,10 @@ import { EmojiPicker } from "../EmojiPicker";
 import {
   createPreviewDocumentSaveController,
   deferredPreviewDocumentSave,
+  type PreviewDocumentPayload,
   type PreviewDocumentSaveAdapter,
+  type PreviewDocumentSaveDeferred,
+  type PreviewDocumentSaveSuccess,
 } from "../previewDocumentSaveController";
 import {
   acquirePreviewDocumentSaveController,
@@ -436,7 +440,8 @@ export function databaseCreatedItemForImmediatePreview(
   if (returnedItem) return returnedItem;
   if (!response.createdItemId || !response.createdDocumentId) return null;
 
-  const now = args.now ?? new Date().toISOString();
+  const now =
+    response.createdDocumentUpdatedAt ?? args.now ?? new Date().toISOString();
   const position = Math.max(
     0,
     (response.pagination?.totalItems ?? response.items.length + 1) - 1,
@@ -473,6 +478,42 @@ export function databaseCreatedItemForImmediatePreview(
   };
 }
 
+export function previewDocumentSaveResult(args: {
+  result: DocumentUpdateResult;
+  payload: PreviewDocumentPayload;
+  baseline?: PreviewDocumentPayload;
+  contentChanged: boolean;
+}): PreviewDocumentSaveDeferred | PreviewDocumentSaveSuccess {
+  const serverDocument = isDocumentUpdateConflict(args.result)
+    ? args.result.document
+    : args.result;
+  const titleSaveObservedExternalBody =
+    !args.contentChanged && serverDocument.content !== args.payload.content;
+
+  if (isDocumentUpdateConflict(args.result) || titleSaveObservedExternalBody) {
+    return deferredPreviewDocumentSave("conflict", {
+      lastSaved: args.baseline ?? args.payload,
+      pending: {
+        title: serverDocument.title,
+        content: serverDocument.content,
+        loadedUpdatedAt: serverDocument.updatedAt,
+        loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
+          serverDocument.content,
+        ),
+      },
+      deferredReason: "conflict",
+    });
+  }
+
+  return {
+    outcome: "saved",
+    loadedUpdatedAt: args.result.updatedAt,
+    loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
+      args.result.content,
+    ),
+  };
+}
+
 export function databaseBuilderHydrationSourceForItem(
   item: ContentDatabaseItem,
   sources: ContentDatabaseSource[],
@@ -4098,8 +4139,6 @@ function DatabaseItemPreview({
   // ever touch its own row's state. See previewDocumentSaveRegistry.
   const updateDocumentRef = useRef(updateDocument);
   updateDocumentRef.current = updateDocument;
-  const queryClientRef = useRef(queryClient);
-  queryClientRef.current = queryClient;
   const bodyHydrationPendingRef = useRef(bodyHydrationPending);
   bodyHydrationPendingRef.current = bodyHydrationPending;
   const draftVersionsRef = useRef<Map<string, number | null>>(new Map());
@@ -4244,30 +4283,14 @@ function DatabaseItemPreview({
           },
           {
             onSuccess: (result) => {
-              if (isDocumentUpdateConflict(result)) {
-                resolve(
-                  deferredPreviewDocumentSave("conflict", {
-                    lastSaved: baseline ?? payload,
-                    pending: {
-                      title: result.document.title,
-                      content: result.document.content,
-                      loadedUpdatedAt: result.document.updatedAt,
-                      loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
-                        result.document.content,
-                      ),
-                    },
-                    deferredReason: "conflict",
-                  }),
-                );
-                return;
-              }
-              resolve({
-                outcome: "saved" as const,
-                loadedUpdatedAt: result.updatedAt,
-                loadedContentWasEmpty: isEffectivelyEmptyDocumentContent(
-                  result.content,
-                ),
-              });
+              resolve(
+                previewDocumentSaveResult({
+                  result,
+                  payload,
+                  baseline,
+                  contentChanged,
+                }),
+              );
             },
             onError: reject,
           },
@@ -4276,12 +4299,6 @@ function DatabaseItemPreview({
     onSaved: (persistedPayload) => {
       const controller = peekPreviewDocumentSaveController(documentId);
       if (controller) enqueueDraftWrite(controller, "delete", persistedPayload);
-      void queryClientRef.current.invalidateQueries({
-        queryKey: contentDatabaseQueryKey(databaseDocumentId),
-      });
-      void queryClientRef.current.invalidateQueries({
-        queryKey: ["action", "list-documents"],
-      });
     },
     onError: (err) => {
       toast.error(dbText("failedToSavePagePreview"), {
@@ -4876,6 +4893,7 @@ function DatabaseItemPreview({
             {previewDocument.databaseMembership ? (
               <DocumentProperties
                 documentId={previewDocument.id}
+                databaseDocumentId={databaseDocumentId}
                 canEdit={previewCanEdit}
                 popoversPortalled={false}
               />
@@ -4913,6 +4931,7 @@ function DatabaseItemPreview({
                 const editor = previewDocument.databaseMembership ? (
                   <DocumentBlockFields
                     documentId={previewDocument.id}
+                    databaseDocumentId={databaseDocumentId}
                     canEdit={previewCanEdit}
                     primaryEditor={primaryEditor}
                   />

package/corpus/templates/content/app/components/editor/previewDocumentSaveController.ts

@@ -130,8 +130,8 @@ export interface PreviewDocumentSaveController {
   /** Adopt `payload` as the confirmed-saved baseline (no save scheduled). */
   mark(payload: PreviewDocumentPayload): void;
   /**
-   * Adopt a fresher server baseline while retaining the user's pending title
-   * and content. Used only after an explicit "keep local draft" choice.
+   * Adopt a fresher server baseline while retaining only fields the user
+   * changed locally. Used only after an explicit "keep local draft" choice.
    */
   rebasePending(payload: PreviewDocumentPayload): void;
   /** Replace callbacks captured by an older preview mount. */
@@ -261,8 +261,7 @@ export function createPreviewDocumentSaveController(
         // the controller was created/last marked — e.g. "empty" for a
         // brand-new page — forever, even after real content has been saved.
         const success = asSaveSuccess(result);
-        lastSaved = {
-          ...attempted,
+        const savedMetadata = {
           ...(success?.loadedUpdatedAt !== undefined
             ? { loadedUpdatedAt: success.loadedUpdatedAt }
             : {}),
@@ -270,6 +269,15 @@ export function createPreviewDocumentSaveController(
             ? { loadedContentWasEmpty: success.loadedContentWasEmpty }
             : {}),
         };
+        lastSaved = {
+          ...attempted,
+          ...savedMetadata,
+        };
+        // A later keystroke starts from `pending`, including while this save is
+        // in flight. Rebase that trailing payload onto our own successful write
+        // so its next CAS does not mistake the preceding save for an external
+        // change.
+        pending = { ...pending, ...savedMetadata };
         hasSavedLocally = true;
         deferredReason = null;
         inFlight = null;
@@ -336,9 +344,13 @@ export function createPreviewDocumentSaveController(
     },
     rebasePending(payload: PreviewDocumentPayload) {
       clearTimer();
+      const titleChangedLocally = pending.title !== lastSaved.title;
+      const contentChangedLocally = pending.content !== lastSaved.content;
       lastSaved = { ...payload };
       pending = {
         ...pending,
+        title: titleChangedLocally ? pending.title : payload.title,
+        content: contentChangedLocally ? pending.content : payload.content,
         loadedUpdatedAt: payload.loadedUpdatedAt,
         loadedContentWasEmpty: payload.loadedContentWasEmpty,
       };

package/corpus/templates/content/app/components/sidebar/DocumentSidebar.tsx

@@ -121,6 +121,10 @@ import {
   filterDocumentTreeDocuments,
 } from "@/hooks/use-documents";
 import { useLocalStorage } from "@/hooks/use-local-storage";
+import {
+  markDocumentCreationPending,
+  shouldCreateDocumentOptimistically,
+} from "@/lib/optimistic-document";
 import { cn } from "@/lib/utils";
 
 import {
@@ -747,7 +751,12 @@ export function DocumentSidebar({
       optimisticId?: string,
       rootFilesDatabaseId?: string,
     ) => {
-      if (localFileMode) {
+      if (
+        !shouldCreateDocumentOptimistically({
+          localFileMode,
+          filesDatabaseId: rootFilesDatabaseId,
+        })
+      ) {
         try {
           const created = await createDocument.mutateAsync({
             title: "",
@@ -774,7 +783,7 @@ export function DocumentSidebar({
 
       const id = optimisticId ?? nanoid();
       const now = new Date().toISOString();
-      const tempDoc: Document = {
+      const tempDoc = markDocumentCreationPending({
         id,
         parentId: parentId ?? null,
         title: "",
@@ -789,7 +798,7 @@ export function DocumentSidebar({
         canManage: true,
         createdAt: now,
         updatedAt: now,
-      };
+      });
 
       // Optimistically inject into caches so UI updates immediately
       queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, (old: any) => {
@@ -824,14 +833,14 @@ export function DocumentSidebar({
           spaceId: parentId ? undefined : rootSpaceId,
         });
         const nextId = created?.id || id;
+        queryClient.setQueryData(
+          ["action", "get-document", { id: nextId }],
+          created,
+        );
         if (nextId !== id) {
           queryClient.removeQueries({
             queryKey: ["action", "get-document", { id }],
           });
-          queryClient.setQueryData(
-            ["action", "get-document", { id: nextId }],
-            created,
-          );
           navigateToDocument(nextId);
         }
         // Replace optimistic doc with real server doc + clear any 404 error