@agent-native/core 0.92.9 → 0.92.11

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/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/app/components/editor/DocumentEditor.tsx

@@ -477,6 +477,18 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     canEdit && !bodyHydrationPending && (isLocalFileDocument || !collabLoading);
   canEditRef.current = editorCanEdit;
 
+  // Viewers intentionally join awareness so they receive live cursors, but
+  // only an editor runs the app-state flush poller below. Publish that exact
+  // capability so server-side pull/push/conflict actions do not wait on a
+  // read-only tab that can never acknowledge their request.
+  useEffect(() => {
+    if (!awareness || !collabEnabled) return;
+    awareness.setLocalStateField("canFlushDocument", editorCanEdit);
+    return () => {
+      awareness.setLocalStateField("canFlushDocument", false);
+    };
+  }, [awareness, collabEnabled, editorCanEdit]);
+
   // Initialize from fetched document, reset on document switch
   useEffect(() => {
     if (!document) return;
@@ -813,6 +825,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
           try {
             const next = await pushDocumentToNotion.mutateAsync({
               documentId,
+              // The exact editor value was persisted immediately above. Avoid
+              // a redundant live-editor flush handshake on every auto-sync
+              // save; manual pushes/conflict choices keep the safe default.
+              flushOpenEditor: false,
             });
             queryClient.setQueryData(
               documentSyncStatusQueryKey(documentId, { autoSync }),
@@ -1030,8 +1046,21 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       try {
         const res = await fetch(flushPath);
         if (res.ok) {
-          const pending = (await res.json()) as { id?: string } | null;
+          const pending = (await res.json()) as {
+            id?: string;
+            ts?: number;
+            requestId?: string;
+            status?: "pending" | "success" | "error";
+            error?: string;
+          } | null;
           if (pending && active) {
+            // A terminal acknowledgement waits for the requesting action to
+            // read and clear it. Retrying here could hide a failed flush or
+            // replace the explicit success signal before the server sees it.
+            if (pending.status === "error" || pending.status === "success") {
+              if (active) setTimeout(poll, 600);
+              return;
+            }
             const title = localTitleRef.current;
             const content = localContentRef.current;
             const updates: Record<string, string> = {};
@@ -1043,30 +1072,60 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             try {
               if (Object.keys(updates).length > 0) {
                 const saved = await persistDocumentUpdates(updates);
-                // A CAS conflict here means a newer write landed between this
-                // editor's last reconcile and the flush; leave watermarks
-                // alone so the external-change effects reconcile this editor
-                // to the winning server content instead of us claiming the
-                // now-discarded flush content as saved.
-                if (!isDocumentUpdateConflict(saved)) {
-                  const savedAt = saved?.updatedAt ?? new Date().toISOString();
-                  adoptConfirmedSaveWatermarks({
-                    saved,
-                    savedAt,
-                    title,
-                    content,
-                    updates,
-                    lastSavedTitleRef,
-                    lastSavedContentRef,
-                  });
+                if (isDocumentUpdateConflict(saved)) {
+                  // Do not acknowledge a CAS loss as a successful flush. The
+                  // requester must stop instead of pushing/replacing stale SQL.
+                  throw new Error(
+                    "The document changed while preparing it for sync.",
+                  );
                 }
+                const savedAt = saved?.updatedAt ?? new Date().toISOString();
+                adoptConfirmedSaveWatermarks({
+                  saved,
+                  savedAt,
+                  title,
+                  content,
+                  updates,
+                  lastSavedTitleRef,
+                  lastSavedContentRef,
+                });
               }
-            } finally {
-              // Acknowledge the flush even if nothing changed — the SQL row is
-              // already current, and pull-document is waiting on this delete.
+              // Explicitly acknowledge this exact request only after the live
+              // editor state is confirmed in SQL (or nothing needed saving).
+              // A delete is ambiguous with a transient app-state read failure.
               await fetch(flushPath, {
-                method: "DELETE",
-                headers: { "X-Agent-Native-CSRF": "1" },
+                method: "PUT",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Agent-Native-CSRF": "1",
+                },
+                body: JSON.stringify({
+                  id: pending.id ?? documentId,
+                  ts: pending.ts ?? Date.now(),
+                  requestId: pending.requestId,
+                  status: "success",
+                }),
+              }).catch(() => {});
+            } catch (error) {
+              // Keep a durable negative acknowledgement so the requesting
+              // Notion action can fail closed instead of timing out and using a
+              // stale documents row. The server clears this after reading it.
+              await fetch(flushPath, {
+                method: "PUT",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Agent-Native-CSRF": "1",
+                },
+                body: JSON.stringify({
+                  id: pending.id ?? documentId,
+                  ts: pending.ts ?? Date.now(),
+                  requestId: pending.requestId,
+                  status: "error",
+                  error:
+                    error instanceof Error
+                      ? error.message
+                      : t("editor.liveDocumentSaveBeforeSyncFailed"),
+                }),
               }).catch(() => {});
             }
           }
@@ -1082,7 +1141,13 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       active = false;
       clearTimeout(timer);
     };
-  }, [documentId, editorCanEdit, isLocalFileDocument, persistDocumentUpdates]);
+  }, [
+    documentId,
+    editorCanEdit,
+    isLocalFileDocument,
+    persistDocumentUpdates,
+    t,
+  ]);
 
   const handleTitleChange = useCallback(
     (newTitle: string) => {

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

@@ -822,6 +822,28 @@ export function shouldSeedCollaborativeContent({
   return !!content.trim() && (fragmentLength === 0 || !semanticMarkdown);
 }
 
+/**
+ * Parse authoritative Content NFM with Content's exact NFM parser before the
+ * shared reconcile computes its top-level surgical diff.
+ *
+ * Falling back to the shared CommonMark parser is lossy here: canonical NFM
+ * stores one Notion block per line without blank paragraph separators, while
+ * CommonMark merges those consecutive lines into one paragraph. That made
+ * external replacements such as Notion conflict resolution and version
+ * restores look correct in the non-collaborative history preview, then collapse
+ * into one wrapped paragraph when reconciled into the live Y.Doc.
+ */
+export function parseNfmForCollabReconcile(
+  editor: CoreEditor,
+  value: string,
+): ProseMirrorNode | null {
+  try {
+    return editor.schema.nodeFromJSON(nfmToDoc(value) as any);
+  } catch {
+    return null;
+  }
+}
+
 export function shouldApplyExternalContentSync({
   docChanged,
   content,
@@ -1669,10 +1691,14 @@ export function VisualEditor({
   // Clean up awareness on unmount
   useEffect(() => {
     return () => {
-      localAwareness?.setLocalState(null);
+      // Only the fallback instance is owned by this editor. A provided
+      // awareness belongs to the shared useCollaborativeDoc connection; clearing
+      // it here races StrictMode/remounts and can erase the tab's durable
+      // presence while the shared connection is still active.
+      fallbackAwareness?.setLocalState(null);
       fallbackAwareness?.destroy();
     };
-  }, [fallbackAwareness, localAwareness]);
+  }, [fallbackAwareness]);
 
   const extensions = useMemo(
     () =>
@@ -1941,6 +1967,10 @@ export function VisualEditor({
       e.commands.setContent(doc);
     },
     normalizeValue: canonicalizeNfm,
+    // The shared fallback parser is CommonMark. Content stores canonical NFM,
+    // whose adjacent lines are separate Notion blocks, so always provide the
+    // exact NFM parser for the surgical reconcile path.
+    parseValue: parseNfmForCollabReconcile,
     shouldSeed: ({ value, currentMarkdown, fragmentLength }) =>
       editable &&
       shouldSeedCollaborativeContent({

package/corpus/templates/content/app/hooks/use-notion.ts

@@ -253,12 +253,12 @@ export function usePullDocumentFromNotion(documentId: string) {
 
 export function usePushDocumentToNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useActionMutation<DocumentSyncStatus, { documentId: string }>(
-    "push-notion-page",
-    {
-      onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
-    },
-  );
+  return useActionMutation<
+    DocumentSyncStatus,
+    { documentId: string; flushOpenEditor?: boolean }
+  >("push-notion-page", {
+    onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
+  });
 }
 
 export function useResolveDocumentSyncConflict(documentId: string) {

package/corpus/templates/content/app/i18n/zh-TW.ts

@@ -94,6 +94,7 @@ const messages = {
     couldNotReadLocalSourceFile: "無法讀取本機來源檔案",
     couldNotSaveLocalFile: "無法儲存本機檔案",
     collabConnectingReadOnly: "正在連接即時編輯器。顯示唯讀快照。",
+    liveDocumentSaveBeforeSyncFailed: "即時文件無法在同步前儲存。",
     documentTitle: "檔案標題",
     builderBodySyncing: "內容仍在從 Builder 同步",
     builderBodySyncingDescription: