@agent-native/core 0.101.6 → 0.101.10

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

@@ -36,6 +36,12 @@ export default defineAction({
       .string()
       .describe("Document ID used to scope the property workspace"),
     name: z.string().min(1).describe("Property name"),
+    description: z
+      .string()
+      .optional()
+      .describe(
+        "Stable guidance describing what this property means and which value belongs here",
+      ),
     type: z.enum(CREATABLE_DOCUMENT_PROPERTY_TYPES).describe("Property type"),
     visibility: z
       .enum(DOCUMENT_PROPERTY_VISIBILITIES)
@@ -49,6 +55,7 @@ export default defineAction({
               id: z.string(),
               name: z.string(),
               color: z.string(),
+              description: z.string().optional(),
             }),
           )
           .optional(),
@@ -162,6 +169,9 @@ export default defineAction({
         .update(schema.documentPropertyDefinitions)
         .set({
           name,
+          ...(args.description === undefined
+            ? {}
+            : { description: args.description.trim() }),
           type,
           visibility:
             args.visibility === undefined
@@ -196,6 +206,7 @@ export default defineAction({
             orgId: document.orgId ?? null,
             databaseId: database.id,
             name,
+            description: args.description?.trim() ?? "",
             type,
             visibility: normalizePropertyVisibility(args.visibility),
             optionsJson,

package/corpus/templates/content/actions/create-content-database.ts

@@ -28,6 +28,10 @@ const createContentDatabaseSchema = z.object({
     .nullish()
     .describe("Parent document for a new database page"),
   title: z.string().optional().describe("Database title"),
+  description: z
+    .string()
+    .optional()
+    .describe("Stable guidance describing what belongs in this database"),
 });
 
 export default defineAction({
@@ -110,6 +114,12 @@ export async function createContentDatabaseRecord(
         .set({ title, updatedAt: now })
         .where(eq(schema.documents.id, documentId));
     }
+    if (args.description !== undefined) {
+      await db
+        .update(schema.documents)
+        .set({ description: args.description.trim(), updatedAt: now })
+        .where(eq(schema.documents.id, documentId));
+    }
   } else {
     title = databaseTitleForPage(title);
     const parentId = args.parentId || null;
@@ -163,6 +173,7 @@ export async function createContentDatabaseRecord(
           parentId,
           title,
           content: "",
+          description: args.description?.trim() ?? "",
           icon: null,
           position: (maxPos?.max ?? -1) + 1,
           isFavorite: 0,

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

@@ -45,6 +45,12 @@ export default defineAction({
       .describe("Pre-generated document ID (for optimistic UI)"),
     title: z.string().describe("Document title"),
     content: z.string().optional().describe("Markdown content"),
+    description: z
+      .string()
+      .optional()
+      .describe(
+        "Stable guidance describing why this page exists and what belongs in it",
+      ),
     parentId: z.string().nullish().describe("Parent document ID for nesting"),
     icon: z.string().optional().describe("Emoji icon"),
   }),
@@ -78,6 +84,7 @@ export default defineAction({
     const title = args.title;
 
     let content = args.content || "";
+    const description = args.description?.trim() ?? "";
     // Strip leading H1 that duplicates the title
     if (title && content) {
       const h1Match = content.match(/^#\s+(.+?)(\r?\n|$)/);
@@ -154,6 +161,7 @@ export default defineAction({
           parentId,
           title,
           content,
+          description,
           icon,
           position,
           isFavorite: 0,
@@ -202,6 +210,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/create-inline-content-database.ts

@@ -22,10 +22,12 @@ export default defineAction({
   schema: z.object({
     hostDocumentId: z.string().describe("Host page document ID"),
     title: z.string().optional().describe("Database title"),
+    description: z.string().optional().describe("Stable database guidance"),
   }),
   run: async ({
     hostDocumentId,
     title,
+    description,
   }): Promise<CreateInlineDatabaseResponse> => {
     const db = getDb();
     const ownerBlockId = createInlineDatabaseBlockId();
@@ -37,6 +39,7 @@ export default defineAction({
         {
           parentId: hostDocumentId,
           title: databaseTitleForPage(title),
+          description,
         },
         { db: tx },
       );

package/corpus/templates/content/actions/execute-builder-source-batch.ts

@@ -10,6 +10,7 @@ import {
   type ExecuteBuilderSourceBatchResponse,
   type ExecuteBuilderSourceBatchTransition,
 } from "../shared/api.js";
+import { createBuilderSourceTiming } from "./_builder-source-timings.js";
 import {
   getContentDatabaseSourceSnapshotForWrite,
   resolveDatabaseForSourceMutation,
@@ -63,25 +64,41 @@ function realBatchDeps(
         publicationTransition: transition?.publicationTransition,
         confirmUnpublish: transition?.confirmUnpublish,
       };
+      let preparationTimings;
       if (transition?.publicationTransition) {
-        await prepareBuilderSourceExecution.run(executionArgs);
+        preparationTimings = (
+          await prepareBuilderSourceExecution.run(executionArgs)
+        ).timings;
       }
       try {
-        await executeBuilderSourceExecutionWithDeps(
+        const response = await executeBuilderSourceExecutionWithDeps(
           executionArgs,
           realExecutionDeps(args.sourceId),
         );
+        return {
+          changeSetId,
+          status: "succeeded",
+          timings: [...(preparationTimings ?? []), ...(response.timings ?? [])],
+        };
       } catch (error) {
         if (!isMissingGateMessage(errorMessage(error))) {
           throw error;
         }
-        await prepareBuilderSourceExecution.run(executionArgs);
-        await executeBuilderSourceExecutionWithDeps(
+        const preparation =
+          await prepareBuilderSourceExecution.run(executionArgs);
+        const response = await executeBuilderSourceExecutionWithDeps(
           executionArgs,
           realExecutionDeps(args.sourceId),
         );
+        return {
+          changeSetId,
+          status: "succeeded",
+          timings: [
+            ...(preparation.timings ?? []),
+            ...(response.timings ?? []),
+          ],
+        };
       }
-      return { changeSetId, status: "succeeded" };
     },
   };
 }
@@ -112,6 +129,12 @@ function isBlockedMessage(message: string) {
   ].some((pattern) => pattern.test(message));
 }
 
+function isReconciliationRequiredMessage(message: string) {
+  return /reconciliation required|requires reconciliation|remote outcome is unknown/i.test(
+    message,
+  );
+}
+
 function clampConcurrency(value: number | undefined) {
   if (!value || !Number.isFinite(value)) {
     return DEFAULT_BUILDER_SOURCE_BATCH_CONCURRENCY;
@@ -180,6 +203,9 @@ function summarize(results: BuilderSourceBatchItemResult[]) {
     total: results.length,
     succeeded: results.filter((result) => result.status === "succeeded").length,
     blocked: results.filter((result) => result.status === "blocked").length,
+    reconciliationRequired: results.filter(
+      (result) => result.status === "reconciliation_required",
+    ).length,
     failed: results.filter((result) => result.status === "failed").length,
   };
 }
@@ -188,55 +214,100 @@ export async function executeBuilderSourceBatchWithDeps(
   args: ExecuteBuilderSourceBatchRequest,
   deps: ExecuteBuilderSourceBatchDeps,
 ): Promise<ExecuteBuilderSourceBatchResponse> {
-  const database = await deps.resolveDatabase(args);
-  if (!database) throw new Error("Database not found.");
-  await deps.assertEditor(database);
+  const timing = createBuilderSourceTiming("execute_builder_source_batch");
+  try {
+    const { source } = await timing.measure(
+      "snapshot_read_and_diff_load",
+      async () => {
+        const database = await deps.resolveDatabase(args);
+        if (!database) throw new Error("Database not found.");
+        await deps.assertEditor(database);
+        return { source: await deps.getSourceSnapshot(database) };
+      },
+    );
+    if (!source || source.sourceType !== "builder-cms") {
+      throw new Error("Attach a Builder CMS source before executing writes.");
+    }
 
-  const source = await deps.getSourceSnapshot(database);
-  if (!source || source.sourceType !== "builder-cms") {
-    throw new Error("Attach a Builder CMS source before executing writes.");
-  }
+    const ids = uniqueIds(
+      args.changeSetIds ?? defaultBatchChangeSetIds(source),
+    );
+    const changeSetsById = new Map(
+      source.changeSets.map((changeSet) => [changeSet.id, changeSet]),
+    );
+    const maxConcurrency = clampConcurrency(args.maxConcurrency);
+    const results = await timing.measure("batch_dispatch", () =>
+      runBoundedPool(ids, maxConcurrency, async (changeSetId) => {
+        const changeSet = changeSetsById.get(changeSetId);
+        if (changeSet && hasSucceededExecution(changeSet)) {
+          return {
+            changeSetId,
+            status: "succeeded",
+            message: "Builder execution already succeeded; skipped.",
+          };
+        }
 
-  const ids = uniqueIds(args.changeSetIds ?? defaultBatchChangeSetIds(source));
-  const changeSetsById = new Map(
-    source.changeSets.map((changeSet) => [changeSet.id, changeSet]),
-  );
-  const maxConcurrency = clampConcurrency(args.maxConcurrency);
-  const results = await runBoundedPool(
-    ids,
-    maxConcurrency,
-    async (changeSetId) => {
-      const changeSet = changeSetsById.get(changeSetId);
-      if (changeSet && hasSucceededExecution(changeSet)) {
-        return {
-          changeSetId,
-          status: "succeeded",
-          message: "Builder execution already succeeded; skipped.",
-        };
-      }
+        const blocker = explicitBatchBlocker(changeSet);
+        if (blocker) {
+          return { changeSetId, status: "blocked", message: blocker };
+        }
 
-      const blocker = explicitBatchBlocker(changeSet);
-      if (blocker) {
-        return { changeSetId, status: "blocked", message: blocker };
-      }
+        try {
+          return await deps.runOne(
+            changeSetId,
+            args.transitions?.[changeSetId],
+          );
+        } catch (error) {
+          const message = errorMessage(error);
+          return {
+            changeSetId,
+            status: isReconciliationRequiredMessage(message)
+              ? "reconciliation_required"
+              : isBlockedMessage(message)
+                ? "blocked"
+                : "failed",
+            message,
+          };
+        }
+      }),
+    );
 
-      try {
-        return await deps.runOne(changeSetId, args.transitions?.[changeSetId]);
-      } catch (error) {
-        const message = errorMessage(error);
-        return {
-          changeSetId,
-          status: isBlockedMessage(message) ? "blocked" : "failed",
-          message,
-        };
-      }
-    },
-  );
+    const phaseDuration = (names: string[]) =>
+      results.reduce(
+        (total, result) =>
+          total +
+          (result.timings ?? [])
+            .filter((item) => names.includes(item.name))
+            .reduce((sum, item) => sum + item.durationMs, 0),
+        0,
+      );
+    timing.add(
+      "approval_gate_preparation_and_dry_run_validation",
+      phaseDuration([
+        "gate_preparation_and_dry_run_validation",
+        "approval_gate_and_dry_run_validation",
+      ]),
+    );
+    timing.add("write_dispatch", phaseDuration(["write_dispatch"]));
+    timing.add(
+      "reconciliation_and_persistence",
+      phaseDuration(["reconciliation_and_persistence"]),
+    );
 
-  return {
-    summary: summarize(results),
-    results,
-  };
+    const response = {
+      summary: summarize(results),
+      results,
+      timings: timing.finish(),
+    };
+    timing.log("succeeded");
+    return response;
+  } catch (error) {
+    timing.ensure("approval_gate_preparation_and_dry_run_validation");
+    timing.ensure("write_dispatch");
+    timing.ensure("reconciliation_and_persistence");
+    timing.log("failed");
+    throw error;
+  }
 }
 
 const transitionSchema = z.object({