@agent-native/core 0.175.3 → 0.175.4-nightly-20260826190205

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8620
+- template files: 8623

package/corpus/templates/clips/server/plugins/agent-chat.ts

@@ -49,6 +49,9 @@ export default createAgentChatPlugin({
     `<clips-transcript-guidance>
 The transcript in view-screen and get-recording-player-data are bounded previews when called by the agent. When previewTruncated is true, the text is expected to end mid-sentence and is never evidence that transcription stopped early. Use the bounded payload for a concise summary and do not request or reconstruct the omitted transcript by searching other recordings. For a failed or pending transcript, use request-transcript with force=true. For an explicit fresh retry of an existing ready transcript, also pass regenerate=true. Agent-triggered retries are queued for the durable worker and return pending while processing.
 </clips-transcript-guidance>
+<clips-agent-routing>
+For summaries, action-item lists, follow-up lists, and todo lists based on the recording in view, use Clips' recording/transcript actions and answer directly in this chat. Do not call Plan or another app for a generic written list. Only delegate to Plan when the user explicitly asks for a visual or structured Agent-Native Plan, a Plan artifact, or the Plans app.
+</clips-agent-routing>
 <clips-recording-discovery>
 Clips public recordings are unlisted-by-link, not a searchable public catalog. Treat a recording as known only when it is owned by the current user, already appears in the current screen, or the current user has already viewed it. Do not use list-recordings or search-recordings to discover someone else's clips, recover from a failed direct lookup, answer a date/time question, or search by a title that was not supplied by the user. A question such as when this clip was created refers to the clip already in context; answer it from current-screen or get-recording-player-data. If a direct recording lookup fails, report the failure and stop instead of broadening the search. Only inspect another clip when the user provides its share URL or recording id in the request.
 </clips-recording-discovery>`,

package/corpus/templates/content/actions/_linked-local-document-edit.ts

@@ -0,0 +1,167 @@
+import {
+  callBrowserSession,
+  listBrowserSessions,
+} from "@agent-native/core/server";
+
+import type { DocumentTextEdit } from "../shared/document-text-edits.js";
+
+export const linkedLocalDocumentEditActionName = (documentId: string) =>
+  `content-edit-linked-document:${documentId}`;
+
+type LinkedLocalEditReceipt =
+  | {
+      status: "persisted";
+      content: string;
+      title: string;
+      path: string;
+      runtime: "browser" | "desktop";
+      revision?: string;
+    }
+  | {
+      status: "source-persisted/history-pending";
+      content: string;
+      title: string;
+      description: string;
+      metadata: {
+        parentId: string | null;
+        icon: string | null;
+        position: number;
+        isFavorite: boolean;
+        hideFromSearch: boolean;
+        visibility: "private" | "org" | "public";
+      };
+      path: string;
+      runtime: "browser" | "desktop";
+      revision?: string;
+    }
+  | {
+      status: "source-persisted/readback-pending";
+      content: string;
+      title: string;
+      path: string;
+      runtime: "browser" | "desktop";
+      revision?: string;
+    }
+  | {
+      status: "conflict" | "unavailable" | "failed";
+      error: string;
+    };
+
+function isReceipt(value: unknown): value is LinkedLocalEditReceipt {
+  if (!value || typeof value !== "object") return false;
+  const receipt = value as Record<string, unknown>;
+  if (
+    receipt.status === "persisted" ||
+    receipt.status === "source-persisted/history-pending" ||
+    receipt.status === "source-persisted/readback-pending"
+  ) {
+    const hasPersistedFields =
+      typeof receipt.content === "string" &&
+      typeof receipt.title === "string" &&
+      receipt.title.length > 0 &&
+      typeof receipt.path === "string" &&
+      receipt.path.length > 0 &&
+      (receipt.runtime === "browser" || receipt.runtime === "desktop") &&
+      (receipt.revision === undefined ||
+        (typeof receipt.revision === "string" && receipt.revision.length > 0));
+    if (!hasPersistedFields) return false;
+    if (receipt.status !== "source-persisted/history-pending") return true;
+    const metadata = receipt.metadata as Record<string, unknown> | undefined;
+    return (
+      typeof receipt.description === "string" &&
+      !!metadata &&
+      (metadata.parentId === null || typeof metadata.parentId === "string") &&
+      (metadata.icon === null || typeof metadata.icon === "string") &&
+      typeof metadata.position === "number" &&
+      typeof metadata.isFavorite === "boolean" &&
+      typeof metadata.hideFromSearch === "boolean" &&
+      (metadata.visibility === "private" ||
+        metadata.visibility === "org" ||
+        metadata.visibility === "public")
+    );
+  }
+  return (
+    (receipt.status === "conflict" ||
+      receipt.status === "unavailable" ||
+      receipt.status === "failed") &&
+    typeof receipt.error === "string" &&
+    receipt.error.length > 0
+  );
+}
+
+export async function editLinkedLocalDocumentThroughBrowser(args: {
+  ownerEmail: string;
+  documentId: string;
+  expectedContent: string;
+  expectedTitle: string;
+  expectedDescription: string;
+  expectedMetadata: string;
+  expectedResultContent: string;
+  edits: DocumentTextEdit[];
+}): Promise<LinkedLocalEditReceipt> {
+  const name = linkedLocalDocumentEditActionName(args.documentId);
+  const sessions = await listBrowserSessions(args.ownerEmail, { limit: 100 });
+  const matches = sessions.filter((session) =>
+    session.actions.some((action) => action.name === name),
+  );
+  if (matches.length === 0) {
+    return {
+      status: "unavailable",
+      error:
+        "Open this linked document in a browser with its local source folder connected, then retry the edit.",
+    };
+  }
+  if (matches.length > 1) {
+    return {
+      status: "conflict",
+      error:
+        "This linked document is open in more than one writable browser session. Close the extra tab and retry.",
+    };
+  }
+
+  try {
+    const result = await callBrowserSession(
+      args.ownerEmail,
+      matches[0]!.sessionId,
+      {
+        type: "run-action",
+        name,
+        args: {
+          documentId: args.documentId,
+          expectedContent: args.expectedContent,
+          expectedTitle: args.expectedTitle,
+          expectedDescription: args.expectedDescription,
+          expectedMetadata: args.expectedMetadata,
+          edits: args.edits,
+        },
+        timeoutMs: 30_000,
+      },
+      { timeoutMs: 30_000 },
+    );
+    if (!isReceipt(result)) {
+      return {
+        status: "failed",
+        error: "The local source returned an invalid receipt.",
+      };
+    }
+    if (
+      (result.status === "persisted" ||
+        result.status === "source-persisted/readback-pending") &&
+      result.content !== args.expectedResultContent
+    ) {
+      return {
+        status: "conflict",
+        error: "The local source receipt did not match the requested edit.",
+      };
+    }
+    return result;
+  } catch (error) {
+    return {
+      status: "failed",
+      error:
+        error instanceof Error
+          ? error.message
+          : "The local source write failed.",
+    };
+  }
+}

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

@@ -5,6 +5,7 @@ import {
   hasCollabState,
   searchAndReplace,
 } from "@agent-native/core/collab";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { assertAccess } from "@agent-native/core/sharing";
 import {
   getGenerationCreativeContext,
@@ -13,14 +14,17 @@ import {
   validateGenerationCreativeContext,
 } from "@agent-native/creative-context/server";
 import type { CreativeContextReuseLabel } from "@agent-native/creative-context/types";
-import { eq } from "drizzle-orm";
+import { and, eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import { applyDocumentTextEdits } from "../shared/document-text-edits.js";
+import { inspectNfmFidelity } from "../shared/nfm.js";
 import {
   lockPrimaryBlocksFields,
   persistBlocksFieldIdentity,
 } from "./_blocks-field-identity.js";
+import { editLinkedLocalDocumentThroughBrowser } from "./_linked-local-document-edit.js";
 
 interface TextEdit {
   find: string;
@@ -110,46 +114,47 @@ export default defineAction({
 
     // ─── Apply edits to the document markdown ───────────────────────────────
     //
-    // The agent edits the canonical `documents.content` (markdown is the source
-    // of truth). The change is delivered live to any open editor through the
-    // framework's normal change-sync: the action bump refetches `get-document`,
-    // and the editor reconciles the newer content into the live Y.Doc — parsing
-    // the markdown through the real editor pipeline so new block structure
-    // (lists, headings, tables) renders correctly and merges with any
-    // concurrent human edits via the Yjs CRDT. See the `real-time-collab` skill.
+    // Native documents edit canonical `documents.content`. A linked local file
+    // instead commits through its exact live source bridge before SQL mirrors
+    // the accepted bytes. The SQL change is delivered to open editors through
+    // normal change-sync and parsed through the real editor pipeline so new
+    // block structure renders correctly and merges through Yjs.
     //
     // (The old approach POSTed a Yjs search-replace to a localhost collab origin,
     // which silently no-oped on serverless — different process, no localhost —
     // and could only patch text inside existing nodes, never create structure.)
-    let content: string = existing.content ?? "";
-    const results: string[] = [];
-    let changeCount = 0;
-    const appliedEdits: TextEdit[] = [];
-
-    for (const edit of edits) {
-      const idx = content.indexOf(edit.find);
-      if (idx === -1) {
-        results.push(
-          `NOT FOUND: "${edit.find.slice(0, 60)}${edit.find.length > 60 ? "..." : ""}"`,
-        );
-        continue;
-      }
-      content =
-        content.slice(0, idx) +
-        edit.replace +
-        content.slice(idx + edit.find.length);
-      changeCount++;
-      appliedEdits.push(edit);
-      const action = edit.replace === "" ? "deleted" : "replaced";
-      results.push(
-        `${action}: "${edit.find.slice(0, 40)}${edit.find.length > 40 ? "..." : ""}"`,
-      );
-    }
+    const applied = applyDocumentTextEdits(existing.content ?? "", edits);
+    let { content } = applied;
+    const { results, appliedEdits, changeCount } = applied;
 
     if (changeCount === 0) {
       return { applied: 0, total: edits.length, results };
     }
 
+    let linkedLocalPersistence:
+      | {
+          status:
+            | "persisted"
+            | "source-persisted/readback-pending"
+            | "source-persisted/history-pending";
+          path: string;
+          runtime: "browser" | "desktop";
+        }
+      | undefined;
+    let linkedLocalHistoryReconciliation = false;
+    let linkedLocalReconciliationDocument:
+      | {
+          title: string;
+          description: string;
+          parentId: string | null;
+          icon: string | null;
+          position: number;
+          isFavorite: boolean;
+          hideFromSearch: boolean;
+          visibility: "private" | "org" | "public";
+        }
+      | undefined;
+
     const previousGeneration =
       args.contextModeOverride === "off"
         ? null
@@ -236,39 +241,146 @@ export default defineAction({
       };
     }
 
+    const isLinkedLocalSource =
+      existing.sourceMode === "local-files" &&
+      existing.sourceKind !== "folder" &&
+      Boolean(existing.sourcePath) &&
+      !id.startsWith("local-file:") &&
+      !id.startsWith("local-folder:");
+    if (isLinkedLocalSource) {
+      const ownerEmail = getRequestUserEmail();
+      if (!ownerEmail) {
+        return {
+          applied: 0,
+          total: edits.length,
+          results,
+          persistence: "unavailable",
+          error:
+            "No authenticated user is available for the local source write.",
+        };
+      }
+      const receipt = await editLinkedLocalDocumentThroughBrowser({
+        ownerEmail,
+        documentId: id,
+        expectedContent: existing.content ?? "",
+        expectedTitle: existing.title,
+        expectedDescription: existing.description ?? "",
+        expectedMetadata: JSON.stringify({
+          parentId: existing.parentId,
+          icon: existing.icon,
+          position: existing.position,
+          isFavorite: Boolean(existing.isFavorite),
+          hideFromSearch: Boolean(existing.hideFromSearch),
+          visibility: existing.visibility,
+        }),
+        expectedResultContent: applied.content,
+        edits,
+      });
+      if (receipt.status === "source-persisted/history-pending") {
+        linkedLocalHistoryReconciliation = true;
+        linkedLocalReconciliationDocument = {
+          title: receipt.title,
+          description: receipt.description,
+          ...receipt.metadata,
+          visibility: existing.visibility,
+        };
+      }
+      if (
+        receipt.status !== "persisted" &&
+        receipt.status !== "source-persisted/history-pending" &&
+        receipt.status !== "source-persisted/readback-pending"
+      ) {
+        return {
+          applied: 0,
+          total: edits.length,
+          results,
+          persistence: receipt.status,
+          error: receipt.error,
+        };
+      }
+      content = receipt.content;
+      linkedLocalPersistence = {
+        status: receipt.status,
+        path: receipt.path,
+        runtime: receipt.runtime,
+      };
+    }
+
     // Persist. The fresh updatedAt is the signal the open editor uses to tell an
     // intentional external edit apart from a stale autosave echo.
     const db = getDb();
     const now = new Date().toISOString();
-    await db.transaction(async (tx: any) => {
-      const primaryBlocksFields = await lockPrimaryBlocksFields(tx, id);
-      await tx
-        .update(schema.documents)
-        .set({ content, updatedAt: now })
-        .where(eq(schema.documents.id, id));
-      for (const field of primaryBlocksFields) {
-        await persistBlocksFieldIdentity({
-          db: tx as unknown as ReturnType<typeof getDb>,
-          ownerEmail: field.ownerEmail,
-          documentId: id,
-          propertyId: field.propertyId,
-          previousMarkdown: existing.content ?? "",
-          markdown: content,
-          now,
-        });
-      }
-      if (creativeContext) {
-        await recordGenerationCreativeContext(
-          {
-            appId: "content",
-            artifactType: "document",
-            artifactId: id,
-            ...creativeContext,
-          },
-          { db: tx },
-        );
-      }
-    });
+    try {
+      await db.transaction(async (tx: any) => {
+        const primaryBlocksFields = await lockPrimaryBlocksFields(tx, id);
+        const mirrored = await tx
+          .update(schema.documents)
+          .set({
+            content,
+            updatedAt: now,
+            ...(linkedLocalReconciliationDocument ?? {}),
+          })
+          .where(
+            and(
+              eq(schema.documents.id, id),
+              eq(schema.documents.updatedAt, existing.updatedAt),
+            ),
+          )
+          .returning({ id: schema.documents.id });
+        if (mirrored.length !== 1) {
+          throw new Error(
+            "The document changed before Content history could be updated.",
+          );
+        }
+        for (const field of primaryBlocksFields) {
+          await persistBlocksFieldIdentity({
+            db: tx as unknown as ReturnType<typeof getDb>,
+            ownerEmail: field.ownerEmail,
+            documentId: id,
+            propertyId: field.propertyId,
+            previousMarkdown: existing.content ?? "",
+            markdown: content,
+            now,
+          });
+        }
+        if (creativeContext) {
+          await recordGenerationCreativeContext(
+            {
+              appId: "content",
+              artifactType: "document",
+              artifactId: id,
+              ...creativeContext,
+            },
+            { db: tx },
+          );
+        }
+      });
+    } catch (error) {
+      if (!linkedLocalPersistence) throw error;
+      return {
+        applied: changeCount,
+        total: edits.length,
+        results,
+        persistence: "source-persisted/history-pending",
+        path: linkedLocalPersistence.path,
+        error:
+          error instanceof Error
+            ? error.message
+            : "The local file changed, but Content history was not updated.",
+      };
+    }
+
+    if (linkedLocalHistoryReconciliation) {
+      return {
+        applied: 0,
+        total: edits.length,
+        results,
+        persistence: "source-persisted/history-reconciled",
+        path: linkedLocalPersistence?.path,
+        error:
+          "The source changed during verification. Content history was reconciled to the physical file, but the requested agent edit was not confirmed.",
+      };
+    }
 
     // Make the agent edit VISIBLE as a live collaborator. Content's collab doc
     // binds the TipTap Y.XmlFragment("default"), so a live editing session is
@@ -310,6 +422,14 @@ export default defineAction({
       applied: changeCount,
       total: edits.length,
       results,
+      ...(linkedLocalPersistence
+        ? {
+            persistence: linkedLocalPersistence.status,
+            path: linkedLocalPersistence.path,
+            runtime: linkedLocalPersistence.runtime,
+          }
+        : {}),
+      contentFidelity: inspectNfmFidelity(content),
       ...(creativeContext
         ? {
             contextMode: creativeContext.contextMode,

package/corpus/templates/content/actions/import-content-source.ts

@@ -15,6 +15,7 @@ import {
   parseContentSourceFile,
   type ParsedContentSourceFile,
 } from "../shared/content-source.js";
+import { inspectNfmFidelity } from "../shared/nfm.js";
 import {
   favoriteDocumentIds,
   setFavoriteMembership,
@@ -63,6 +64,10 @@ function canEditRole(role: string) {
   return ROLE_RANK[role as keyof typeof ROLE_RANK] >= ROLE_RANK.editor;
 }
 
+function canAdminRole(role: string) {
+  return ROLE_RANK[role as keyof typeof ROLE_RANK] >= ROLE_RANK.admin;
+}
+
 function normalizedFileEntries(files: Record<string, string>) {
   return Object.entries(files)
     .filter(([filePath]) => isContentSourcePath(filePath))
@@ -214,6 +219,9 @@ export default defineAction({
     const parsed: ParsedContentSourceFile[] = entries.map(
       ([filePath, source]) => parseContentSourceFile(filePath, source),
     );
+    const fidelityByPath = new Map(
+      parsed.map((file) => [file.path, inspectNfmFidelity(file.content)]),
+    );
     const importPaths = [...new Set(parsed.map((file) => file.path))];
     const existingLocalDocs =
       importPaths.length > 0
@@ -292,6 +300,14 @@ export default defineAction({
         });
         continue;
       }
+      const fidelity = fidelityByPath.get(file.path);
+      if (fidelity?.status === "failed") {
+        errors.push({
+          path: file.path,
+          reason: `Document conversion failed: ${fidelity.error ?? "unreadable content"}.`,
+        });
+        continue;
+      }
 
       const sourceMatchedDocument = file.id
         ? null
@@ -337,6 +353,19 @@ export default defineAction({
         const discoverabilityChanged =
           file.hideFromSearch !== undefined &&
           boolToInt(file.hideFromSearch) !== (existing.hideFromSearch ?? 0);
+        const visibilityChanged =
+          file.visibility !== undefined &&
+          file.visibility !== existing.visibility;
+        if (
+          visibilityChanged &&
+          (!existingRole || !canAdminRole(existingRole))
+        ) {
+          skipped.push({
+            path: file.path,
+            reason: `Requires admin access to change visibility on document "${id}".`,
+          });
+          continue;
+        }
         const sourceUpdates = localSourceFields(file.path, now);
         const sourceChanged =
           existing.sourceMode !== sourceUpdates.sourceMode ||
@@ -351,6 +380,7 @@ export default defineAction({
           iconChanged ||
           favoriteChanged ||
           discoverabilityChanged ||
+          visibilityChanged ||
           sourceChanged ||
           spaceChanged;
 
@@ -379,6 +409,7 @@ export default defineAction({
           if (discoverabilityChanged) {
             updates.hideFromSearch = boolToInt(file.hideFromSearch);
           }
+          if (visibilityChanged) updates.visibility = file.visibility;
           Object.assign(updates, sourceUpdates);
 
           await db
@@ -416,7 +447,7 @@ export default defineAction({
             isFavorite: boolToInt(file.isFavorite),
             hideFromSearch: boolToInt(file.hideFromSearch),
             ...localSourceFields(file.path, now),
-            visibility: "private",
+            visibility: file.visibility ?? "private",
             createdAt: now,
             updatedAt: now,
           });
@@ -544,6 +575,7 @@ export default defineAction({
       skipped,
       errors,
       idByPath: Object.fromEntries(idByPath),
+      fidelity: Object.fromEntries(fidelityByPath),
     };
   },
 });

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

@@ -19,6 +19,7 @@ import {
   parseDocumentHideFromSearch,
 } from "../server/lib/documents.js";
 import type { DocumentUpdateResponse } from "../shared/api.js";
+import { inspectNfmFidelity } from "../shared/nfm.js";
 import {
   lockPrimaryBlocksFields,
   persistBlocksFieldIdentity,
@@ -778,6 +779,7 @@ export default defineAction({
         canManage: canManageRole(access.role),
         createdAt: doc.createdAt,
         updatedAt: doc.updatedAt,
+        contentFidelity: inspectNfmFidelity(doc.content),
         source: serializeDocumentSource(doc),
         softDeletedDatabaseIds,
         ...(creativeContext

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

@@ -105,6 +105,7 @@ import { DocumentEditorSkeleton } from "./DocumentEditorSkeleton";
 import { DocumentInfoPanel } from "./DocumentInfoPanel";
 import { DocumentToolbar, type ToolbarBreadcrumbItem } from "./DocumentToolbar";
 import { EmojiPicker } from "./EmojiPicker";
+import { LinkedLocalDocumentAgentBridge } from "./LinkedLocalDocumentAgentBridge";
 import {
   classifyLocalSourceRead,
   localSourceRevisionForQueuedEdit,
@@ -749,6 +750,13 @@ function DocumentEditorBody({
   localTitleRef.current = localTitle;
   const localContentRef = useRef(localContent);
   localContentRef.current = localContent;
+  const getLinkedLocalEditorSnapshot = useCallback(
+    () => ({
+      title: localTitleRef.current,
+      content: localContentRef.current,
+    }),
+    [],
+  );
   const localSourceWriteErrorShownRef = useRef(false);
   const documentUpdatedAtRef = useRef<string | null>(
     document.updatedAt ?? null,
@@ -1267,6 +1275,59 @@ function DocumentEditorBody({
     };
   }, [document.id, document.source, isLinkedLocalSourceDocument]);
 
+  const handleLinkedLocalAgentPersistence = useCallback(
+    (persisted: Document, revision?: DesktopContentFileRevision) => {
+      localSourceRevisionRef.current = revision;
+      localTitleRef.current = persisted.title;
+      localContentRef.current = persisted.content;
+      setLocalTitle(persisted.title);
+      setLocalContent(persisted.content);
+      setLocalContentUpdatedAt(persisted.updatedAt ?? new Date().toISOString());
+      lastSavedTitleRef.current = {
+        title: persisted.title,
+        updatedAt: lastSavedTitleRef.current.updatedAt,
+      };
+      lastSavedContentRef.current = {
+        content: persisted.content,
+        updatedAt: lastSavedContentRef.current.updatedAt,
+      };
+      setLocalFileSyncRevision((revision) => revision + 1);
+      setLocalSourceConflict(null);
+      const sqlUpdatedAt = documentUpdatedAtRef.current;
+      queryClient.setQueriesData(documentQueryFilter(documentId), (old) =>
+        mergeDocumentIntoDocumentCache(old, {
+          ...persisted,
+          updatedAt: sqlUpdatedAt ?? persisted.updatedAt,
+        }),
+      );
+    },
+    [documentId, queryClient],
+  );
+
+  useEffect(() => {
+    if (
+      !isLinkedLocalSourceDocument ||
+      document.title !== localTitleRef.current ||
+      document.content !== localContentRef.current ||
+      !document.updatedAt
+    ) {
+      return;
+    }
+    lastSavedTitleRef.current = {
+      title: document.title,
+      updatedAt: document.updatedAt,
+    };
+    lastSavedContentRef.current = {
+      content: document.content,
+      updatedAt: document.updatedAt,
+    };
+  }, [
+    document.content,
+    document.title,
+    document.updatedAt,
+    isLinkedLocalSourceDocument,
+  ]);
+
   const saveDocumentImmediately = useCallback(
     async (
       title: string,
@@ -2024,6 +2085,13 @@ function DocumentEditorBody({
       registry={contentBlockRegistry}
       ctx={blockRenderContext}
     >
+      {isLinkedLocalSourceDocument && editorCanEdit ? (
+        <LinkedLocalDocumentAgentBridge
+          document={document}
+          getEditorSnapshot={getLinkedLocalEditorSnapshot}
+          onPersisted={handleLinkedLocalAgentPersistence}
+        />
+      ) : null}
       <div
         className="relative flex min-h-0 min-w-0 flex-1"
         data-document-print-root