@agent-native/core 0.101.6 → 0.101.10

package/corpus/templates/content/actions/preview-builder-source-review.ts

@@ -0,0 +1,99 @@
+import { defineAction } from "@agent-native/core";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import type {
+  PreviewBuilderSourceReviewRequest,
+  PreviewBuilderSourceReviewResponse,
+} from "../shared/api.js";
+import {
+  getContentDatabaseSourceSnapshotForWrite,
+  resolveDatabaseForSourceMutation,
+} from "./_database-source-utils.js";
+import {
+  BUILDER_SOURCE_REVIEW_PREPARE_LIMIT,
+  buildBuilderSourceReviewPayload,
+  reviewPreparePriority,
+  withAuthoritativeBuilderTargetRows,
+} from "./prepare-builder-source-review.js";
+
+export default defineAction({
+  description:
+    "Preview complete Builder CMS review diffs, including document body changes, without approving or writing anything.",
+  schema: z.object({
+    databaseId: z.string().optional().describe("Database ID"),
+    documentId: z.string().optional().describe("Database document/page ID"),
+    sourceId: z.string().optional().describe("Specific Builder source ID"),
+    scope: z.enum(["selected", "all"]).optional().default("all"),
+    documentIds: z
+      .array(z.string())
+      .max(BUILDER_SOURCE_REVIEW_PREPARE_LIMIT)
+      .optional()
+      .describe("Optional selected document IDs that bound the preview"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (
+    args: PreviewBuilderSourceReviewRequest,
+  ): Promise<PreviewBuilderSourceReviewResponse> => {
+    const database = await resolveDatabaseForSourceMutation(args);
+    if (!database) throw new Error("Database not found.");
+    await assertAccess("document", database.documentId, "editor");
+
+    const source = await getContentDatabaseSourceSnapshotForWrite(
+      database,
+      args.sourceId,
+    );
+    if (!source || source.sourceType !== "builder-cms") {
+      throw new Error("Attach a Builder CMS source before reviewing updates.");
+    }
+
+    const selectedDocumentIds = new Set(args.documentIds ?? []);
+    if (args.scope === "selected" && selectedDocumentIds.size === 0) {
+      throw new Error("Select at least one Builder row before reviewing it.");
+    }
+    const allReviewableChanges = source.changeSets.filter((changeSet) => {
+      if (
+        changeSet.direction !== "outbound" ||
+        (changeSet.state !== "pending_push" &&
+          changeSet.state !== "staged_revision" &&
+          changeSet.state !== "approved")
+      ) {
+        return false;
+      }
+      return (
+        args.scope === "all" ||
+        (!!changeSet.documentId &&
+          selectedDocumentIds.has(changeSet.documentId))
+      );
+    });
+    const changeSets = [...allReviewableChanges]
+      .sort(
+        (left, right) =>
+          reviewPreparePriority(left) - reviewPreparePriority(right),
+      )
+      .slice(0, BUILDER_SOURCE_REVIEW_PREPARE_LIMIT);
+    const authoritativeSource = await withAuthoritativeBuilderTargetRows({
+      source,
+      changeSets,
+    });
+    const review =
+      changeSets.length > 0
+        ? buildBuilderSourceReviewPayload({
+            source: authoritativeSource,
+            changeSets,
+          })
+        : null;
+    if (review) {
+      review.totalRowCount = allReviewableChanges.length;
+      review.preparedRowLimit = changeSets.length;
+    }
+
+    return {
+      sourceId: source.id,
+      sourceTable: source.sourceTable,
+      changeSetIds: changeSets.map((changeSet) => changeSet.id),
+      review,
+    };
+  },
+});

package/corpus/templates/content/actions/pull-document.ts

@@ -73,6 +73,7 @@ export default defineAction({
       return {
         id: doc.id,
         title: doc.title,
+        description: doc.description ?? "",
         content: formatDocumentContent(doc.content ?? "", format),
         format,
         deepLink: buildDeepLink({
@@ -104,6 +105,7 @@ export default defineAction({
     return {
       id: doc.id,
       title: doc.title,
+      description: (doc.description as string | null | undefined) ?? "",
       content,
       format,
       deepLink: buildDeepLink({

package/corpus/templates/content/actions/search-documents.ts

@@ -59,6 +59,7 @@ export default defineAction({
           (doc) =>
             !normalizedQuery ||
             doc.title.toLowerCase().includes(normalizedQuery) ||
+            (doc.description ?? "").toLowerCase().includes(normalizedQuery) ||
             doc.content.toLowerCase().includes(normalizedQuery),
         )
         .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
@@ -69,6 +70,7 @@ export default defineAction({
           id: doc.id,
           parentId: doc.parentId,
           title: doc.title,
+          description: doc.description,
           icon: doc.icon,
           snippet: makeSnippet(doc.content, query),
           contentLength: doc.content.length,
@@ -95,6 +97,7 @@ export default defineAction({
         id: schema.documents.id,
         parentId: schema.documents.parentId,
         title: schema.documents.title,
+        description: schema.documents.description,
         icon: schema.documents.icon,
         contentPreview: sql<string>`substr(${schema.documents.content}, 1, 5000)`,
         contentLength: sql<number>`length(${schema.documents.content})`,
@@ -106,7 +109,7 @@ export default defineAction({
         and(
           accessFilter(schema.documents, schema.documentShares),
           documentDiscoveryFilter(),
-          sql`(${schema.documents.title} LIKE ${pattern} ESCAPE '\\' OR ${schema.documents.content} LIKE ${pattern} ESCAPE '\\')`,
+          sql`(${schema.documents.title} LIKE ${pattern} ESCAPE '\\' OR ${schema.documents.description} LIKE ${pattern} ESCAPE '\\' OR ${schema.documents.content} LIKE ${pattern} ESCAPE '\\')`,
         ),
       )
       .orderBy(sql`${schema.documents.updatedAt} DESC`)
@@ -117,6 +120,7 @@ export default defineAction({
         id: doc.id,
         parentId: doc.parentId,
         title: doc.title,
+        description: doc.description,
         icon: doc.icon,
         snippet: makeSnippet(doc.contentPreview, query),
         contentLength: Number(doc.contentLength) || 0,

package/corpus/templates/content/actions/set-content-database-source-write-mode.ts

@@ -38,7 +38,7 @@ function executableWriteModes(
 
 export default defineAction({
   description:
-    "Set the tiered Builder CMS write mode for one source. Writes stay off by default and can only be enabled for the safe Builder test collection.",
+    "Set the tiered Builder CMS write mode for one source. Writes stay off by default and require document administrator access to enable or change.",
   schema: z.object({
     databaseId: z.string().optional().describe("Database ID"),
     documentId: z.string().optional().describe("Database document/page ID"),
@@ -79,7 +79,7 @@ export default defineAction({
   ): Promise<ContentDatabaseResponse> => {
     const database = await resolveDatabaseForSourceMutation(args);
     if (!database) throw new Error("Database not found.");
-    await assertAccess("document", database.documentId, "editor");
+    await assertAccess("document", database.documentId, "admin");
 
     const db = getDb();
     const source = await getExistingSourceForWrite(database.id, args.sourceId);

package/corpus/templates/content/actions/update-document.ts

@@ -152,6 +152,10 @@ export default defineAction({
     id: z.string().optional().describe("Document ID (required)"),
     title: z.string().optional().describe("New title"),
     content: z.string().optional().describe("New markdown content"),
+    description: z
+      .string()
+      .optional()
+      .describe("Stable page guidance; this does not alter page content"),
     icon: z.string().nullable().optional().describe("New emoji icon"),
     isFavorite: z.coerce
       .boolean()
@@ -285,8 +289,15 @@ export default defineAction({
     const favoriteChanged =
       args.isFavorite !== undefined &&
       (args.isFavorite ? 1 : 0) !== (existing.isFavorite ?? 0);
+    const descriptionChanged =
+      args.description !== undefined &&
+      args.description.trim() !== existing.description;
     const anyChange =
-      titleChanged || contentChanged || iconChanged || favoriteChanged;
+      titleChanged ||
+      contentChanged ||
+      iconChanged ||
+      favoriteChanged ||
+      descriptionChanged;
 
     // Snapshot the current state before applying content/title changes.
     // Versions are scoped to the document owner, not the caller — an editor
@@ -338,6 +349,8 @@ export default defineAction({
       };
 
       if (titleChanged) updates.title = args.title;
+      if (args.description !== undefined)
+        updates.description = args.description.trim();
       if (contentChanged) updates.content = content;
       if (iconChanged) updates.icon = args.icon;
       if (favoriteChanged) updates.isFavorite = args.isFavorite ? 1 : 0;
@@ -373,6 +386,7 @@ export default defineAction({
               parentId: current.parentId,
               title: current.title,
               content: current.content,
+              description: current.description,
               icon: current.icon,
               position: current.position,
               isFavorite: parseDocumentFavorite(current.isFavorite),
@@ -449,6 +463,7 @@ export default defineAction({
       parentId: doc.parentId,
       title: doc.title,
       content: doc.content,
+      description: doc.description,
       icon: doc.icon,
       position: doc.position,
       isFavorite: parseDocumentFavorite(doc.isFavorite),

package/corpus/templates/content/actions/update-preview-document-draft.ts

@@ -0,0 +1,153 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { readPreviewDocumentDraft } from "./_preview-document-draft.js";
+
+const draftPayload = z.object({
+  title: z.string().max(10_000),
+  content: z.string().max(500_000),
+  baseDocumentUpdatedAt: z.string().max(100).nullable(),
+  loadedContentWasEmpty: z.boolean(),
+  deferredReason: z.enum(["hydration", "conflict"]).nullable(),
+});
+
+function draftId() {
+  return crypto.randomUUID();
+}
+
+export default defineAction({
+  description:
+    "Atomically save or delete the current user's private preview draft.",
+  schema: z.discriminatedUnion("operation", [
+    z.object({
+      operation: z.literal("upsert"),
+      documentId: z.string().min(1),
+      expectedVersion: z.number().int().positive().nullable(),
+      draft: draftPayload,
+    }),
+    z.object({
+      operation: z.literal("delete"),
+      documentId: z.string().min(1),
+      expectedVersion: z.number().int().positive(),
+      expectedTitle: z.string().max(10_000),
+      expectedContent: z.string().max(500_000),
+    }),
+  ]),
+  agentTool: false,
+  toolCallable: false,
+  run: async (args, ctx) => {
+    const userEmail = getRequestUserEmail();
+    const orgId = getRequestOrgId() ?? "";
+    if (!userEmail) throw new Error("Not authenticated.");
+    await assertAccess("document", args.documentId, "editor");
+    const db = getDb();
+    const ownerFilter = and(
+      eq(schema.documentPreviewDrafts.ownerEmail, userEmail),
+      eq(schema.documentPreviewDrafts.orgId, orgId),
+      eq(schema.documentPreviewDrafts.documentId, args.documentId),
+    );
+
+    if (args.operation === "delete") {
+      const deleted = await db
+        .delete(schema.documentPreviewDrafts)
+        .where(
+          and(
+            ownerFilter,
+            eq(schema.documentPreviewDrafts.version, args.expectedVersion),
+            eq(schema.documentPreviewDrafts.title, args.expectedTitle),
+            eq(schema.documentPreviewDrafts.content, args.expectedContent),
+          ),
+        )
+        .returning({ id: schema.documentPreviewDrafts.id });
+      if (deleted.length > 0)
+        return { status: "deleted" as const, draft: null };
+      return {
+        status: "conflict" as const,
+        draft: await readPreviewDocumentDraft(
+          userEmail,
+          orgId,
+          args.documentId,
+        ),
+      };
+    }
+
+    const now = new Date().toISOString();
+    if (args.expectedVersion === null) {
+      const inserted = await db
+        .insert(schema.documentPreviewDrafts)
+        .values({
+          id: draftId(),
+          ownerEmail: userEmail,
+          orgId,
+          documentId: args.documentId,
+          title: args.draft.title,
+          content: args.draft.content,
+          baseDocumentUpdatedAt: args.draft.baseDocumentUpdatedAt,
+          loadedContentWasEmpty: args.draft.loadedContentWasEmpty ? 1 : 0,
+          deferredReason: args.draft.deferredReason,
+          version: 1,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .onConflictDoNothing({
+          target: [
+            schema.documentPreviewDrafts.ownerEmail,
+            schema.documentPreviewDrafts.orgId,
+            schema.documentPreviewDrafts.documentId,
+          ],
+        })
+        .returning({ version: schema.documentPreviewDrafts.version });
+      if (inserted.length > 0) {
+        return {
+          status: "saved" as const,
+          draft: await readPreviewDocumentDraft(
+            userEmail,
+            orgId,
+            args.documentId,
+          ),
+        };
+      }
+    } else {
+      const updated = await db
+        .update(schema.documentPreviewDrafts)
+        .set({
+          title: args.draft.title,
+          content: args.draft.content,
+          baseDocumentUpdatedAt: args.draft.baseDocumentUpdatedAt,
+          loadedContentWasEmpty: args.draft.loadedContentWasEmpty ? 1 : 0,
+          deferredReason: args.draft.deferredReason,
+          version: sql`${schema.documentPreviewDrafts.version} + 1`,
+          updatedAt: now,
+        })
+        .where(
+          and(
+            ownerFilter,
+            eq(schema.documentPreviewDrafts.version, args.expectedVersion),
+          ),
+        )
+        .returning({ version: schema.documentPreviewDrafts.version });
+      if (updated.length > 0) {
+        return {
+          status: "saved" as const,
+          draft: await readPreviewDocumentDraft(
+            userEmail,
+            orgId,
+            args.documentId,
+          ),
+        };
+      }
+    }
+
+    return {
+      status: "conflict" as const,
+      draft: await readPreviewDocumentDraft(userEmail, orgId, args.documentId),
+    };
+  },
+});

package/corpus/templates/content/actions/view-screen.ts

@@ -34,11 +34,13 @@ import {
   getContentDatabaseResponse,
   getDatabaseByDocumentId,
   getDatabaseItemByDocumentId,
+  getDocumentContextPath,
   serializeDatabaseMembership,
 } from "./_database-utils.js";
 import { serializeDocumentSource } from "./_document-source.js";
 import {
   getLocalFileDocument,
+  getLocalDocumentContextPath,
   isContentLocalFileMode,
   isLocalDocumentId,
   localContentViewScreenSummary,
@@ -675,7 +677,10 @@ export default defineAction({
         ],
       };
       if (nav?.documentId && isLocalDocumentId(nav.documentId)) {
-        screen.document = await getLocalFileDocument(nav.documentId);
+        screen.document = {
+          ...(await getLocalFileDocument(nav.documentId)),
+          contextPath: await getLocalDocumentContextPath(nav.documentId),
+        };
       } else if (nav?.documentId) {
         const access = await resolveAccess("document", nav.documentId);
         if (access) {
@@ -685,6 +690,7 @@ export default defineAction({
             parentId: doc.parentId,
             title: doc.title,
             content: doc.content,
+            description: doc.description,
             icon: doc.icon,
             position: doc.position,
             isFavorite: parseDocumentFavorite(doc.isFavorite),
@@ -693,6 +699,7 @@ export default defineAction({
             source: serializeDocumentSource(doc),
             createdAt: doc.createdAt,
             updatedAt: doc.updatedAt,
+            contextPath: await getDocumentContextPath(doc),
           };
         }
       }
@@ -725,18 +732,22 @@ export default defineAction({
           parentId: doc.parentId,
           title: doc.title,
           content: doc.content,
+          description: doc.description,
           icon: doc.icon,
           position: doc.position,
           isFavorite: parseDocumentFavorite(doc.isFavorite),
           hideFromSearch: parseDocumentHideFromSearch(doc.hideFromSearch),
           visibility: doc.visibility,
-          database: database ? serializeDatabase(database) : undefined,
+          database: database
+            ? serializeDatabase(database, doc.description)
+            : undefined,
           databaseMembership: databaseMembership
             ? serializeDatabaseMembership(databaseMembership)
             : undefined,
           properties: await listPropertiesForDocument(doc),
           createdAt: doc.createdAt,
           updatedAt: doc.updatedAt,
+          contextPath: await getDocumentContextPath(doc),
         };
         if (database) {
           const databaseResponse = await getContentDatabaseResponse(
@@ -774,6 +785,7 @@ export default defineAction({
                   parentId: previewDoc.parentId,
                   title: previewDoc.title,
                   content: previewDoc.content,
+                  description: previewDoc.description,
                   icon: previewDoc.icon,
                   position: previewDoc.position,
                   isFavorite: parseDocumentFavorite(previewDoc.isFavorite),
@@ -786,6 +798,7 @@ export default defineAction({
                   properties: await listPropertiesForDocument(previewDoc),
                   createdAt: previewDoc.createdAt,
                   updatedAt: previewDoc.updatedAt,
+                  contextPath: await getDocumentContextPath(previewDoc),
                 },
               };
             }

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

@@ -0,0 +1,121 @@
+import { useEffect, useRef, useState } from "react";
+
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+
+export function descriptionFieldSavedValue(
+  draft: string,
+  savedDescription: string | null | undefined,
+) {
+  const next = draft.trim();
+  return next === (savedDescription ?? "") ? null : next;
+}
+
+export function descriptionFieldEscapeDraft(
+  savedDescription: string | null | undefined,
+) {
+  return savedDescription ?? "";
+}
+
+/**
+ * Quiet, stable guidance attached to a page or database. This intentionally
+ * renders the owned description only; ancestor context is assembled for agent
+ * reads rather than copied into the surface.
+ */
+export function DescriptionField({
+  description,
+  canEdit,
+  label = "Description",
+  placeholder = "Add a description…",
+  className,
+  onSave,
+}: {
+  description: string | null | undefined;
+  canEdit: boolean;
+  label?: string;
+  placeholder?: string;
+  className?: string;
+  onSave: (description: string) => Promise<unknown> | unknown;
+}) {
+  const [draft, setDraft] = useState(description ?? "");
+  const [editing, setEditing] = useState(false);
+  const skipNextBlurSaveRef = useRef(false);
+  const saveQueueRef = useRef<Promise<void>>(Promise.resolve());
+  const saveRevisionRef = useRef(0);
+  const confirmedDescriptionRef = useRef(description ?? "");
+
+  useEffect(() => {
+    confirmedDescriptionRef.current = description ?? "";
+  }, [description]);
+
+  useEffect(() => {
+    if (!editing) setDraft(description ?? "");
+  }, [description, editing]);
+
+  const save = async () => {
+    const next = descriptionFieldSavedValue(draft, description);
+    if (next === null) return;
+
+    const revision = ++saveRevisionRef.current;
+    const request = saveQueueRef.current.then(() => onSave(next));
+    saveQueueRef.current = request.then(
+      () => undefined,
+      () => undefined,
+    );
+
+    try {
+      await request;
+      confirmedDescriptionRef.current = next;
+    } catch {
+      if (saveRevisionRef.current === revision) {
+        setDraft(confirmedDescriptionRef.current);
+      }
+    }
+  };
+
+  if (!canEdit && !description) return null;
+
+  if (!canEdit) {
+    return (
+      <p
+        className={cn(
+          "mt-2 text-sm leading-6 text-muted-foreground",
+          className,
+        )}
+      >
+        {description}
+      </p>
+    );
+  }
+
+  return (
+    <Textarea
+      aria-label={label}
+      rows={editing || draft ? 2 : 1}
+      value={draft}
+      placeholder={placeholder}
+      onFocus={() => setEditing(true)}
+      onChange={(event) => setDraft(event.target.value)}
+      onBlur={() => {
+        setEditing(false);
+        if (skipNextBlurSaveRef.current) {
+          skipNextBlurSaveRef.current = false;
+          return;
+        }
+        void save();
+      }}
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          skipNextBlurSaveRef.current = true;
+          setDraft(descriptionFieldEscapeDraft(description));
+          event.currentTarget.blur();
+        }
+      }}
+      className={cn(
+        "mt-2 block w-full resize-none overflow-hidden rounded border-0 bg-transparent px-0 py-0 text-sm leading-6 text-muted-foreground outline-none placeholder:text-muted-foreground/45 hover:bg-muted/30 focus:bg-muted/30 focus:px-1 focus:outline-none focus:ring-1 focus:ring-ring",
+        className,
+      )}
+    />
+  );
+}

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

@@ -61,6 +61,7 @@ import {
 import { BuilderBodySyncingNotice } from "./BuilderBodySyncingNotice";
 import type { CommentTextAnchor } from "./comment-anchors";
 import { CommentsSidebar } from "./CommentsSidebar";
+import { DescriptionField } from "./DescriptionField";
 import { DocumentBlockFields } from "./DocumentBlockFields";
 import { DocumentDatabase } from "./DocumentDatabase";
 import { DocumentEditorSkeleton } from "./DocumentEditorSkeleton";
@@ -629,6 +630,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       updates: {
         title?: string;
         content?: string;
+        description?: string;
         icon?: string | null;
       },
       options: DocumentSaveOptions = {},
@@ -645,6 +647,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
         ...document,
         title: updates.title ?? localTitleRef.current,
         content: updates.content ?? localContentRef.current,
+        description: updates.description ?? document.description,
         icon: updates.icon !== undefined ? updates.icon : document.icon,
         updatedAt: nextSavedAt,
         source: localSource,
@@ -1431,6 +1434,17 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                       isDatabasePage ? "text-3xl" : "text-3xl md:text-4xl",
                     )}
                   />
+                  {!document.database ? (
+                    <DescriptionField
+                      description={document.description}
+                      canEdit={editorCanEdit}
+                      label={t("editor.properties.description")}
+                      placeholder={t("editor.properties.addPageDescription")}
+                      onSave={(description) =>
+                        persistDocumentUpdates({ description })
+                      }
+                    />
+                  ) : null}
                   {document.databaseMembership && !isLocalFileDocument ? (
                     <DocumentProperties
                       documentId={documentId}