@agent-native/core 0.92.10 → 0.92.12

package/corpus/templates/content/actions/_document-flush.ts

@@ -1,62 +1,177 @@
+import { randomUUID } from "node:crypto";
+
 import {
   appStateDelete,
   appStateGet,
   appStatePut,
 } from "@agent-native/core/application-state";
-import { hasCollabState } from "@agent-native/core/collab";
+import {
+  AGENT_CLIENT_ID,
+  hasCollabState,
+  loadAwarenessRowsStrict,
+} from "@agent-native/core/collab";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 
 const FLUSH_POLL_INTERVAL_MS = 200;
 const FLUSH_TIMEOUT_MS = 4000;
 
+function parseAwarenessState(state: string): {
+  canFlushDocument?: unknown;
+  visible?: boolean;
+  user?: { email?: unknown };
+} | null {
+  try {
+    return JSON.parse(state) as {
+      canFlushDocument?: unknown;
+      visible?: boolean;
+      user?: { email?: unknown };
+    };
+  } catch {
+    return null;
+  }
+}
+
+function awarenessFlushCandidate(entry: {
+  clientId: number;
+  state: string;
+}): { sessionEmail: string | null; required: boolean } | null {
+  if (entry.clientId === AGENT_CLIENT_ID) return null;
+  const state = parseAwarenessState(entry.state);
+  if (!state || state.visible === false || !state.user) return null;
+  // New clients publish an exact boolean. `false` is a known read-only viewer
+  // and must never block. A missing field is a pre-deploy client which may be
+  // an editor, so offer it the old handshake on a best-effort basis. Invalid
+  // values are neither a trustworthy editor capability nor a legacy omission.
+  if (state.canFlushDocument !== true && state.canFlushDocument !== undefined) {
+    return null;
+  }
+  const email = state.user.email;
+  return {
+    sessionEmail:
+      typeof email === "string" && email.trim() ? email.trim() : null,
+    required: state.canFlushDocument === true,
+  };
+}
+
 export async function flushOpenDocumentEditorToSql(args: {
   documentId: string;
   ownerEmail?: string | null;
 }) {
   // If a live Yjs collab session is open, the in-memory editor doc is fresher
   // than the SQL column. Ask the open editor to serialize + save, then wait
-  // for it to acknowledge by clearing the flush-request key.
+  // for an explicit request-id-matched acknowledgement.
   if (!(await hasCollabState(args.documentId))) return;
 
+  // Persisted Yjs state outlives browser tabs. Modern clients distinguish
+  // editors (`true`) from viewers (`false`), so only the former are a hard
+  // freshness barrier. Pre-deploy tabs omit the field; they still know how to
+  // service this request, but may also be legacy viewers, so offer them the
+  // bounded handshake without failing if they stay silent. This preserves live
+  // legacy editor changes without making viewer-only tabs time out sync actions.
+  const awarenessRows = await loadAwarenessRowsStrict(args.documentId);
+  const flushCandidates = awarenessRows
+    .map(awarenessFlushCandidate)
+    .filter((candidate): candidate is NonNullable<typeof candidate> => {
+      return candidate !== null;
+    });
+  if (flushCandidates.length === 0) return;
+  const acknowledgementRequired = flushCandidates.some(
+    (candidate) => candidate.required,
+  );
+  const activeSessionEmails = flushCandidates
+    .map((candidate) => candidate.sessionEmail)
+    .filter((email): email is string => !!email);
+
   const flushKey = `flush-request-${args.documentId}`;
   // The editor polls `flush-request-<id>` via the framework app-state route,
-  // which scopes reads to the logged-in browser user (the document owner).
-  // Writing under the caller's (external agent's) session alone can miss the
-  // human editor tab, so write under both plausible sessions and de-dupe.
+  // which scopes reads to the logged-in browser user. Target every active
+  // collaborator email plus owner/caller fallbacks so shared editors and
+  // cross-instance actions reach the tab that can serialize the live Y.Doc.
   const callerEmail = getRequestUserEmail() || undefined;
   const targetSessions = Array.from(
     new Set(
-      [args.ownerEmail ?? undefined, callerEmail].filter(
-        (s): s is string => typeof s === "string" && s.length > 0,
-      ),
+      [
+        ...activeSessionEmails,
+        args.ownerEmail ?? undefined,
+        callerEmail,
+      ].filter((s): s is string => typeof s === "string" && s.length > 0),
     ),
   );
-  if (targetSessions.length === 0) return;
+  if (targetSessions.length === 0) {
+    if (!acknowledgementRequired) return;
+    throw new Error("Could not identify the open document editor to flush.");
+  }
 
-  const flushValue = { id: args.documentId, ts: Date.now() };
-  await Promise.all(
+  const requestId = randomUUID();
+  const flushValue = {
+    id: args.documentId,
+    ts: Date.now(),
+    requestId,
+    status: "pending",
+  };
+  const writes = await Promise.allSettled(
     targetSessions.map((session) =>
       appStatePut(session, flushKey, flushValue, {
         requestSource: "agent",
-      }).catch(() => {}),
+      }),
     ),
   );
+  const writtenSessions = targetSessions.filter(
+    (_session, index) => writes[index]?.status === "fulfilled",
+  );
+  if (writtenSessions.length === 0) {
+    if (!acknowledgementRequired) return;
+    throw new Error("Could not ask the open document editor to save.");
+  }
 
   const deadline = Date.now() + FLUSH_TIMEOUT_MS;
+  let flushError: string | null = null;
+  let acknowledged = false;
   while (Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, FLUSH_POLL_INTERVAL_MS));
-    const pending = await Promise.all(
-      targetSessions.map((session) => appStateGet(session, flushKey)),
+    const reads = await Promise.allSettled(
+      writtenSessions.map((session) => appStateGet(session, flushKey)),
+    );
+    const responses = reads.flatMap((result) =>
+      result.status === "fulfilled" && result.value ? [result.value] : [],
+    );
+    const failed = responses.find(
+      (
+        value,
+      ): value is {
+        requestId: string;
+        status: "error";
+        error?: string;
+      } => value.requestId === requestId && value.status === "error",
+    );
+    if (failed) {
+      flushError =
+        typeof failed.error === "string" && failed.error.trim()
+          ? failed.error
+          : "The live document could not be saved before syncing.";
+      break;
+    }
+    acknowledged = responses.some(
+      (value) => value.requestId === requestId && value.status === "success",
     );
-    if (pending.every((value) => !value)) break;
+    if (acknowledged) break;
   }
 
-  // Best-effort cleanup if the editor never picked it up (no tab open).
+  // Best-effort cleanup after success, explicit failure, or timeout.
   await Promise.all(
-    targetSessions.map((session) =>
+    writtenSessions.map((session) =>
       appStateDelete(session, flushKey, { requestSource: "agent" }).catch(
         () => {},
       ),
     ),
   );
+
+  if (flushError) {
+    throw new Error(flushError);
+  }
+  if (!acknowledged && acknowledgementRequired) {
+    throw new Error(
+      "The open document editor did not finish saving before sync timed out.",
+    );
+  }
 }

package/corpus/templates/content/actions/_notion-action-utils.ts

@@ -4,6 +4,8 @@ import {
 } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
 
+import { flushOpenDocumentEditorToSql } from "./_document-flush.js";
+
 export function getCurrentNotionOwner() {
   const owner = getRequestUserEmail();
   if (!owner) throw new Error("no authenticated user");
@@ -23,6 +25,19 @@ export async function getNotionDocumentOwner(documentId: string) {
   return owner;
 }
 
+/**
+ * Flush the live collaborative editor before a user-triggered Notion operation
+ * reads or replaces SQL content. The Y.Doc can be ahead of the debounced
+ * documents row; without this handshake "Use local" can push a stale snapshot,
+ * while "Use Notion" can discard edits that never reached version history.
+ */
+export async function flushNotionDocumentEditor(
+  documentId: string,
+  ownerEmail: string,
+) {
+  await flushOpenDocumentEditorToSql({ documentId, ownerEmail });
+}
+
 export function resolveDocumentId(args: { documentId?: string; id?: string }) {
   const documentId = args.documentId?.trim() || args.id?.trim();
   if (!documentId) {

package/corpus/templates/content/actions/add-content-database-source-field-property.ts

@@ -201,10 +201,7 @@ export function sourceFieldPropertyOptions(args: {
 }
 
 function builderFieldNameForSourceKey(sourceFieldKey: string) {
-  return sourceFieldKey
-    .replace(/^data\./, "")
-    .trim()
-    .toLowerCase();
+  return sourceFieldKey.replace(/^data\./, "").trim();
 }
 
 function builderModelFieldsFromMetadata(
@@ -231,15 +228,15 @@ function builderModelFieldsFromMetadata(
   }
 }
 
-function builderMetadataForSourceField(args: {
+export function builderMetadataForSourceField(args: {
   sourceFieldKey: string;
   sourceMetadataJson: string | null | undefined;
 }) {
   const fieldName = builderFieldNameForSourceKey(args.sourceFieldKey);
-  const sourceFieldKey = args.sourceFieldKey.trim().toLowerCase();
+  const sourceFieldKey = args.sourceFieldKey.trim();
   return (
     builderModelFieldsFromMetadata(args.sourceMetadataJson).find((field) => {
-      const name = field.name.trim().toLowerCase();
+      const name = field.name.trim();
       return name === fieldName || `data.${name}` === sourceFieldKey;
     }) ?? null
   );

package/corpus/templates/content/actions/attach-content-database-source.ts

@@ -48,13 +48,41 @@ const BUILDER_CMS_ATTACH_INITIAL_PAGES = 1;
 export async function readInitialBuilderCmsAttachEntries(
   sourceTable: string,
   readEntries: typeof readBuilderCmsContentEntries = readBuilderCmsContentEntries,
+  fieldPaths: readonly string[] = [],
 ) {
   return readEntries({
     model: sourceTable,
+    fieldPaths,
     maxPages: BUILDER_CMS_ATTACH_INITIAL_PAGES,
   });
 }
 
+export async function readInitialBuilderCmsAttachSource(
+  sourceTable: string,
+  dependencies: {
+    readModelFields?: typeof readBuilderCmsModelFields;
+    readEntries?: typeof readBuilderCmsContentEntries;
+  } = {},
+) {
+  const readModelFields =
+    dependencies.readModelFields ?? readBuilderCmsModelFields;
+  const readEntries = dependencies.readEntries ?? readBuilderCmsContentEntries;
+  let modelFields: BuilderCmsModelFieldSummary[] = [];
+  let modelFieldsError: unknown = null;
+  try {
+    modelFields = await readModelFields({ model: sourceTable });
+  } catch (error) {
+    modelFieldsError = error;
+  }
+  const read = await readInitialBuilderCmsAttachEntries(
+    sourceTable,
+    readEntries,
+    modelFields.map((field) => `data.${field.name}`),
+  );
+  if (modelFieldsError) throw modelFieldsError;
+  return { read, modelFields };
+}
+
 function builderReadHasMore(read: BuilderCmsReadResult | null | undefined) {
   return read?.state === "live" && read.progress?.hasMore === true;
 }
@@ -238,9 +266,10 @@ export default defineAction({
       let modelFields: BuilderCmsModelFieldSummary[];
       let builderRead: BuilderCmsReadResult | null = null;
       if (sourceType === "builder-cms") {
-        builderRead = await readInitialBuilderCmsAttachEntries(sourceTable);
+        const initial = await readInitialBuilderCmsAttachSource(sourceTable);
+        modelFields = initial.modelFields;
+        builderRead = initial.read;
         entries = builderRead.state === "live" ? builderRead.entries : [];
-        modelFields = await readBuilderCmsModelFields({ model: sourceTable });
       } else if (sourceType === "local-table") {
         // sourceTable carries the target database id for a local-table source.
         ({ entries, modelFields } = await readLocalTableEntries(sourceTable, {
@@ -327,13 +356,12 @@ export default defineAction({
       if (await databaseSourceExistsForTable(database.id, sourceTable)) {
         throw new Error(`"${sourceTable}" is already attached as a source.`);
       }
-      const additionalRead =
-        await readInitialBuilderCmsAttachEntries(sourceTable);
+      const additionalInitial =
+        await readInitialBuilderCmsAttachSource(sourceTable);
+      const additionalModelFields = additionalInitial.modelFields;
+      const additionalRead = additionalInitial.read;
       const additionalEntries =
         additionalRead.state === "live" ? additionalRead.entries : [];
-      const additionalModelFields = await readBuilderCmsModelFields({
-        model: sourceTable,
-      });
       const additionalSourceId = await insertSecondarySource({
         database,
         sourceType,
@@ -436,6 +464,10 @@ export default defineAction({
     const existingSourceRows = existingSource
       ? await getSourceRows(existingSource.id)
       : [];
+    const builderInitial =
+      sourceType === "builder-cms"
+        ? await readInitialBuilderCmsAttachSource(sourceTable)
+        : null;
     const sourceId = await replaceSourceMetadata({
       database,
       source: existingSource,
@@ -444,18 +476,10 @@ export default defineAction({
       sourceTable,
       now,
     });
-    const builderRead =
-      sourceType === "builder-cms"
-        ? await readInitialBuilderCmsAttachEntries(sourceTable)
-        : null;
+    const builderModelFields = builderInitial?.modelFields ?? [];
+    const builderRead = builderInitial?.read ?? null;
     const builderEntries =
       builderRead?.state === "live" ? builderRead.entries : [];
-    const builderModelFields =
-      sourceType === "builder-cms"
-        ? await readBuilderCmsModelFields({
-            model: sourceTable,
-          })
-        : [];
     let importedEntriesByDocumentId = new Map<string, BuilderCmsSourceEntry>();
     if (builderRead?.state === "live") {
       const importResult = await importBuilderCmsEntriesAsDatabaseItems({

package/corpus/templates/content/actions/change-content-database-source-role.ts

@@ -187,6 +187,37 @@ async function removeRowsOwnedOnlyBySource(args: {
     );
 }
 
+export async function readBuilderCmsEntriesForRoleChange(
+  args: {
+    model: string;
+    existingFieldPaths?: readonly string[];
+  },
+  dependencies: {
+    readModelFields?: typeof readBuilderCmsModelFields;
+    readEntries?: typeof readBuilderCmsContentEntries;
+  } = {},
+) {
+  const readModelFields =
+    dependencies.readModelFields ?? readBuilderCmsModelFields;
+  const readEntries = dependencies.readEntries ?? readBuilderCmsContentEntries;
+  let modelFields: BuilderCmsModelFieldSummary[] = [];
+  let modelFieldsError: unknown = null;
+  try {
+    modelFields = await readModelFields({ model: args.model });
+  } catch (error) {
+    modelFieldsError = error;
+  }
+  const read = await readEntries({
+    model: args.model,
+    fieldPaths: [
+      ...(args.existingFieldPaths ?? []),
+      ...modelFields.map((field) => `data.${field.name}`),
+    ],
+  });
+  if (modelFieldsError) throw modelFieldsError;
+  return { read, modelFields };
+}
+
 async function readSourceEntries(args: {
   sourceType: ContentDatabaseSourceType;
   sourceTable: string;
@@ -200,12 +231,12 @@ async function readSourceEntries(args: {
   message: string | null;
 }> {
   if (args.sourceType === "builder-cms") {
-    const read = await readBuilderCmsContentEntries({
+    const { read, modelFields } = await readBuilderCmsEntriesForRoleChange({
       model: args.sourceTable,
     });
     return {
       entries: read.state === "live" ? read.entries : [],
-      modelFields: await readBuilderCmsModelFields({ model: args.sourceTable }),
+      modelFields,
       readState: read.state,
       fetchedAt: read.fetchedAt,
       message: read.message,
@@ -328,13 +359,20 @@ export default defineAction({
         throw new Error("Only Builder sources can add more items right now.");
       }
 
-      const read = await readBuilderCmsContentEntries({
-        model: source.sourceTable,
-      });
+      const existingSourceFields = await db
+        .select({
+          sourceFieldKey: schema.contentDatabaseSourceFields.sourceFieldKey,
+        })
+        .from(schema.contentDatabaseSourceFields)
+        .where(eq(schema.contentDatabaseSourceFields.sourceId, source.id));
+      const { read, modelFields: builderModelFields } =
+        await readBuilderCmsEntriesForRoleChange({
+          model: source.sourceTable,
+          existingFieldPaths: existingSourceFields.map(
+            (field) => field.sourceFieldKey,
+          ),
+        });
       const entries = read.state === "live" ? read.entries : [];
-      const builderModelFields = await readBuilderCmsModelFields({
-        model: source.sourceTable,
-      });
       await db
         .delete(schema.contentDatabaseSourceFields)
         .where(eq(schema.contentDatabaseSourceFields.sourceId, source.id));

package/corpus/templates/content/actions/create-and-link-notion-page.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { createAndLinkNotionPage } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -18,6 +19,7 @@ export default defineAction({
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return createAndLinkNotionPage(owner, documentId, args.parentPageIdOrUrl);
   },
 });

package/corpus/templates/content/actions/link-notion-page.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { linkDocumentToNotionPage } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -26,6 +27,7 @@ export default defineAction({
     }
 
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return linkDocumentToNotionPage(owner, documentId, pageIdOrUrl);
   },
 });

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

@@ -29,12 +29,10 @@ import {
  *      never saw the key, so every external `pull-document` waited the full
  *      timeout and returned stale DB content.
  *   2. The editor polls that key, serializes its current Y.Doc to markdown
- *      through its existing serializer, calls `update-document`, then deletes
- *      the key.
- *   3. We poll (across both candidate sessions) for the key to disappear
- *      (flush acknowledged) and then read the now-fresh row. If the key never
- *      clears (no editor actually open), we fall back to the DB column, which
- *      is the best available snapshot.
+ *      through its existing serializer, calls `update-document`, then writes an
+ *      explicit success/error acknowledgement for that request id.
+ *   3. We poll every active collaborator session for the acknowledgement, fail
+ *      closed on editor errors/timeouts, and then read the now-fresh row.
  *
  * When there is no live collab session the DB column is authoritative and we
  * skip the handshake entirely. The helper bounds the wait so stale collab
@@ -90,7 +88,7 @@ export default defineAction({
 
     // If a live Yjs collab session is open, the in-memory editor doc is fresher
     // than the SQL column. Ask the open editor to serialize + save, then wait
-    // for it to acknowledge by clearing the flush-request key.
+    // for its explicit request-id-matched acknowledgement.
     await flushOpenDocumentEditorToSql({
       documentId: id,
       ownerEmail: (access.resource.ownerEmail as string | undefined) || null,

package/corpus/templates/content/actions/pull-notion-page.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { pullDocumentFromNotion } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -17,6 +18,7 @@ export default defineAction({
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return pullDocumentFromNotion(owner, documentId, true);
   },
 });

package/corpus/templates/content/actions/push-notion-page.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { pushDocumentToNotion } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -12,11 +13,20 @@ export default defineAction({
   schema: z.object({
     documentId: z.string().optional().describe("Document ID (required)"),
     id: z.string().optional().describe("Alias for --documentId"),
+    flushOpenEditor: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Flush an open collaborative editor before pushing (disable only when the caller just persisted the exact editor content)",
+      ),
   }),
   http: { method: "POST" },
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    if (args.flushOpenEditor) {
+      await flushNotionDocumentEditor(documentId, owner);
+    }
     return pushDocumentToNotion(owner, documentId);
   },
 });

package/corpus/templates/content/actions/resolve-notion-sync-conflict.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { resolveDocumentSyncConflict } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -18,6 +19,7 @@ export default defineAction({
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return resolveDocumentSyncConflict(owner, documentId, args.direction);
   },
 });

package/corpus/templates/content/actions/suggest-source-join-key.ts

@@ -6,7 +6,10 @@ import type {
   DocumentPropertyValue,
   SuggestSourceJoinKeyResponse,
 } from "../shared/api.js";
-import { readBuilderCmsContentEntries } from "./_builder-cms-read-client.js";
+import {
+  readBuilderCmsContentEntries,
+  readBuilderCmsModelFields,
+} from "./_builder-cms-read-client.js";
 import {
   getContentDatabaseSourceSnapshot,
   resolveDatabaseForSourceMutation,
@@ -52,8 +55,12 @@ export default defineAction({
 
     let secondaryValues: Record<string, DocumentPropertyValue>[];
     if (args.candidateSourceType === "builder-cms") {
+      const modelFields = await readBuilderCmsModelFields({
+        model: args.candidateSourceTable,
+      }).catch(() => []);
       const read = await readBuilderCmsContentEntries({
         model: args.candidateSourceTable,
+        fieldPaths: modelFields.map((field) => `data.${field.name}`),
       });
       secondaryValues = (read.state === "live" ? read.entries : [])
         .map((entry) => entry.sourceValues)