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

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

@@ -0,0 +1,245 @@
+import { getBrowserTabId } from "@agent-native/core/client/hooks";
+import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client/host";
+import type { AgentNativeClientAction } from "@agent-native/core/client/host";
+import type { Document } from "@shared/api";
+import {
+  applyDocumentTextEdits,
+  type DocumentTextEdit,
+} from "@shared/document-text-edits";
+import { useEffect, useRef } from "react";
+
+import type { DesktopContentFileRevision } from "@/lib/desktop-content-files";
+import {
+  readDocumentFromLinkedLocalSource,
+  writeDocumentToLinkedLocalSource,
+} from "@/lib/local-content-source-files";
+
+type EditArgs = {
+  documentId: string;
+  expectedContent: string;
+  expectedTitle: string;
+  expectedDescription: string;
+  expectedMetadata: string;
+  edits: DocumentTextEdit[];
+};
+
+const actionName = (documentId: string) =>
+  `content-edit-linked-document:${documentId}`;
+
+function managedDocumentMetadata(document: Document) {
+  return {
+    parentId: document.parentId,
+    icon: document.icon,
+    position: document.position,
+    isFavorite: document.isFavorite,
+    hideFromSearch: document.hideFromSearch,
+    visibility: document.visibility,
+  };
+}
+
+export function LinkedLocalDocumentAgentBridge({
+  document,
+  getEditorSnapshot,
+  onPersisted,
+}: {
+  document: Document;
+  getEditorSnapshot(): { title: string; content: string };
+  onPersisted(document: Document, revision?: DesktopContentFileRevision): void;
+}) {
+  const documentRef = useRef(document);
+  documentRef.current = document;
+
+  useEffect(() => {
+    let active = true;
+    const action: AgentNativeClientAction<EditArgs> = {
+      name: actionName(document.id),
+      description: actionName(document.id),
+      schema: {
+        type: "object",
+        properties: {
+          documentId: { type: "string" },
+          expectedContent: { type: "string" },
+          expectedTitle: { type: "string" },
+          expectedDescription: { type: "string" },
+          expectedMetadata: { type: "string" },
+          edits: { type: "array" },
+        },
+        required: [
+          "documentId",
+          "expectedContent",
+          "expectedTitle",
+          "expectedDescription",
+          "expectedMetadata",
+          "edits",
+        ],
+      },
+      async run(args) {
+        const current = documentRef.current;
+        if (args.documentId !== current.id) {
+          return { status: "conflict", error: "The open document changed." };
+        }
+        const editorMatchesExpected = () => {
+          const editor = getEditorSnapshot();
+          return (
+            editor.content === args.expectedContent &&
+            editor.title === args.expectedTitle
+          );
+        };
+        if (!editorMatchesExpected()) {
+          return {
+            status: "conflict",
+            error:
+              "Save the pending editor changes before retrying the agent edit.",
+          };
+        }
+        const baseline = await readDocumentFromLinkedLocalSource(current);
+        if (!active || documentRef.current.id !== args.documentId) {
+          return { status: "conflict", error: "The open document changed." };
+        }
+        if (!baseline.ok) {
+          return {
+            status: baseline.unavailable ? "unavailable" : "failed",
+            error: baseline.error,
+          };
+        }
+        if (
+          baseline.document.content !== args.expectedContent ||
+          baseline.document.title !== args.expectedTitle ||
+          (baseline.document.description ?? "") !== args.expectedDescription ||
+          JSON.stringify(managedDocumentMetadata(baseline.document)) !==
+            args.expectedMetadata
+        ) {
+          return {
+            status: "conflict",
+            error: "The linked file changed after the agent loaded it.",
+          };
+        }
+        const applied = applyDocumentTextEdits(
+          baseline.document.content,
+          args.edits,
+        );
+        if (applied.changeCount === 0) {
+          return {
+            status: "failed",
+            error: "None of the requested text was found in the linked file.",
+          };
+        }
+        const next = { ...baseline.document, content: applied.content };
+        if (!editorMatchesExpected()) {
+          return {
+            status: "conflict",
+            error:
+              "The editor changed while the agent edit was being prepared.",
+          };
+        }
+        if (!active || documentRef.current.id !== args.documentId) {
+          return { status: "conflict", error: "The open document changed." };
+        }
+        const written = await writeDocumentToLinkedLocalSource(
+          next,
+          current.source,
+          { expectedRevision: baseline.revision },
+        );
+        if (!written.ok) {
+          return {
+            status: written.conflict
+              ? "conflict"
+              : written.unavailable
+                ? "unavailable"
+                : "failed",
+            error: written.error,
+          };
+        }
+        const readBack = await readDocumentFromLinkedLocalSource(next);
+        if (!active || documentRef.current.id !== args.documentId) {
+          return {
+            status: "source-persisted/history-pending",
+            content: next.content,
+            title: next.title,
+            description: next.description ?? "",
+            metadata: managedDocumentMetadata(next),
+            path: written.path,
+            runtime: written.runtime,
+            revision: written.revision,
+          };
+        }
+        if (!readBack.ok) {
+          return {
+            status: "source-persisted/readback-pending",
+            content: next.content,
+            title: next.title,
+            path: written.path,
+            runtime: written.runtime,
+            revision: written.revision,
+          };
+        }
+        const revisionMatches =
+          !written.revision ||
+          !readBack.revision ||
+          written.revision === readBack.revision;
+        const managedMetadataMatches =
+          JSON.stringify(managedDocumentMetadata(readBack.document)) ===
+          JSON.stringify(managedDocumentMetadata(next));
+        if (
+          !revisionMatches ||
+          readBack.document.content !== applied.content ||
+          !managedMetadataMatches ||
+          (readBack.document.description ?? "") !== (next.description ?? "") ||
+          readBack.document.title !== next.title
+        ) {
+          return {
+            status: "source-persisted/history-pending",
+            content: readBack.document.content,
+            title: readBack.document.title,
+            description: readBack.document.description ?? "",
+            metadata: managedDocumentMetadata(readBack.document),
+            path: readBack.path,
+            runtime: readBack.runtime,
+            revision: readBack.revision,
+          };
+        }
+        if (!editorMatchesExpected()) {
+          return {
+            status: "source-persisted/history-pending",
+            content: readBack.document.content,
+            title: readBack.document.title,
+            description: readBack.document.description ?? "",
+            metadata: managedDocumentMetadata(readBack.document),
+            path: readBack.path,
+            runtime: readBack.runtime,
+            revision: readBack.revision,
+          };
+        }
+        onPersisted(readBack.document, readBack.revision);
+        return {
+          status: "persisted",
+          content: readBack.document.content,
+          title: readBack.document.title,
+          path: readBack.path,
+          runtime: readBack.runtime,
+          revision: readBack.revision,
+        };
+      },
+    };
+    const bridge = startAgentNativeBrowserSessionBridge({
+      session: {
+        id: `${getBrowserTabId()}:content-page:${document.id}`,
+        label: document.title,
+        connectedAt: new Date().toISOString(),
+        url: window.location.href,
+      },
+      label: `Content: ${document.title}`,
+      getContext: () => ({
+        route: { pathname: window.location.pathname },
+        resource: { type: "document", id: document.id },
+      }),
+      actions: [action],
+    });
+    return () => {
+      active = false;
+      bridge.stop();
+    };
+  }, [document.id, getEditorSnapshot, onPersisted]);
+
+  return null;
+}

package/corpus/templates/content/app/lib/local-content-source-files.ts

@@ -15,13 +15,18 @@ import type {
 type PermissionState = "granted" | "denied" | "prompt";
 type LocalWritable = {
   write(data: string): Promise<void>;
+  truncate?(size: number): Promise<void>;
   close(): Promise<void>;
+  abort?(reason?: unknown): Promise<void>;
 };
 type LocalFileHandle = {
   kind: "file";
   name: string;
   getFile(): Promise<File>;
-  createWritable(): Promise<LocalWritable>;
+  createWritable(options?: {
+    keepExistingData?: boolean;
+    mode?: "exclusive" | "siloed";
+  }): Promise<LocalWritable>;
 };
 type LocalDirectoryHandle = {
   kind: "directory";
@@ -309,6 +314,7 @@ async function writeBrowserFile(
   root: LocalDirectoryHandle,
   filePath: string,
   content: string,
+  expectedRevision: string,
 ) {
   const writePath =
     root.name === CONTENT_SOURCE_ROOT &&
@@ -323,10 +329,55 @@ async function writeBrowserFile(
   for (const part of parts) {
     dir = await dir.getDirectoryHandle(part, { create: true });
   }
-  const file = await dir.getFileHandle(filename, { create: true });
-  const writable = await file.createWritable();
-  await writable.write(content);
-  await writable.close();
+  const file = await dir.getFileHandle(filename);
+  let writable: LocalWritable;
+  try {
+    writable = await file.createWritable({
+      keepExistingData: true,
+      mode: "exclusive",
+    });
+  } catch (error) {
+    if (
+      error instanceof DOMException &&
+      error.name === "NoModificationAllowedError"
+    ) {
+      return { ok: false as const, locked: true as const };
+    }
+    throw error;
+  }
+  try {
+    const current = await file.getFile();
+    const currentRevision = await browserFileRevision(await current.text());
+    if (currentRevision !== expectedRevision) {
+      await writable.abort?.(
+        new DOMException("The local file changed.", "AbortError"),
+      );
+      return { ok: false as const, actualRevision: currentRevision };
+    }
+    if (!writable.truncate) {
+      throw new Error("The browser cannot safely replace this local file.");
+    }
+    await writable.truncate(0);
+    await writable.write(content);
+    await writable.close();
+  } catch (error) {
+    await writable.abort?.(error).catch(() => undefined);
+    throw error;
+  }
+  return {
+    ok: true as const,
+    revision: await browserFileRevision(content),
+  };
+}
+
+async function browserFileRevision(content: string) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(content),
+  );
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("")}`;
 }
 
 async function readBrowserFile(root: LocalDirectoryHandle, filePath: string) {
@@ -345,9 +396,11 @@ async function readBrowserFile(root: LocalDirectoryHandle, filePath: string) {
   }
   const handle = await dir.getFileHandle(filename);
   const file = await handle.getFile();
+  const content = await file.text();
   return {
-    content: await file.text(),
+    content,
     updatedAt: new Date(file.lastModified).toISOString(),
+    revision: await browserFileRevision(content),
   };
 }
 
@@ -373,6 +426,7 @@ export function sourceFileContent(document: Document, existingSource?: string) {
     parentId: document.parentId,
     title: document.title,
     content: document.content,
+    description: document.description,
     icon: document.icon,
     position: document.position,
     isFavorite: document.isFavorite,
@@ -419,10 +473,12 @@ function documentFromSourceContent(input: {
         parsed.parentId === undefined ? input.base.parentId : parsed.parentId,
       title: parsed.title,
       content: parsed.content,
+      description: parsed.description ?? input.base.description,
       icon: parsed.icon === undefined ? null : parsed.icon,
       position: parsed.position ?? input.base.position,
       isFavorite: parsed.isFavorite ?? false,
       hideFromSearch: parsed.hideFromSearch ?? false,
+      visibility: parsed.visibility ?? input.base.visibility,
       updatedAt: input.updatedAt,
       source: input.source,
     },
@@ -538,9 +594,39 @@ export async function writeDocumentToLinkedLocalSource(
     browserSource.handle,
     browserSource.path,
   );
+  const expectedRevision = options.expectedRevision;
+  if (!expectedRevision) {
+    return {
+      ok: false,
+      error: `Local file "${filePath}" has no observed revision.`,
+    };
+  }
   const content = sourceFileContent(document, existingSource.content);
-  await writeBrowserFile(browserSource.handle, browserSource.path, content);
-  return { ok: true, path: filePath, runtime: "browser" };
+  const result = await writeBrowserFile(
+    browserSource.handle,
+    browserSource.path,
+    content,
+    expectedRevision,
+  );
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: result.locked
+        ? `Local file "${filePath}" is already open for writing.`
+        : `Local file "${filePath}" changed after it was read.`,
+      conflict: {
+        path: filePath,
+        expectedRevision,
+        actualRevision: result.locked ? undefined : result.actualRevision,
+      },
+    };
+  }
+  return {
+    ok: true,
+    path: filePath,
+    runtime: "browser",
+    revision: result.revision,
+  };
 }
 
 /**
@@ -677,13 +763,14 @@ export async function readDocumentFromLinkedLocalSource(
       browserSource.handle,
       browserSource.path,
     );
-    return documentFromSourceContent({
+    const read = documentFromSourceContent({
       base: document,
       path: filePath,
       source,
       content: file.content,
       updatedAt: file.updatedAt,
     });
+    return read.ok ? { ...read, revision: file.revision } : read;
   } catch (error) {
     return {
       ok: false,

package/corpus/templates/content/shared/api.ts

@@ -1,4 +1,5 @@
 import type { BlocksFieldIdentity } from "./blocks-field-identity";
+import type { NfmFidelityReport } from "./nfm";
 import type {
   DocumentPropertyOptions,
   DocumentPropertyType,
@@ -46,6 +47,7 @@ export interface Document {
   contextPath?: ContentContextPathEntry[];
   createdAt: string;
   updatedAt: string;
+  contentFidelity?: NfmFidelityReport;
 }
 
 export interface DocumentSourceInfo {

package/corpus/templates/content/shared/content-source.ts

@@ -37,6 +37,7 @@ export interface ParsedContentSourceFile {
   position?: number;
   isFavorite?: boolean;
   hideFromSearch?: boolean;
+  visibility?: "private" | "org" | "public";
   errors?: string[];
 }
 
@@ -192,6 +193,18 @@ export function parseContentSourceFile(
   const rawTitle = typeof metadata.title === "string" ? metadata.title : "";
   const title = rawTitle.trim() || titleFromPath(filePath) || "Untitled";
   const rawPosition = metadata.position;
+  let visibility: "private" | "org" | "public" | undefined;
+  if (hasOwn(metadata, "visibility")) {
+    if (
+      metadata.visibility === "private" ||
+      metadata.visibility === "org" ||
+      metadata.visibility === "public"
+    ) {
+      visibility = metadata.visibility;
+    } else {
+      errors.push("Invalid visibility frontmatter.");
+    }
+  }
 
   return {
     path: filePath,
@@ -220,6 +233,7 @@ export function parseContentSourceFile(
       typeof metadata.hideFromSearch === "boolean"
         ? metadata.hideFromSearch
         : undefined,
+    visibility,
     errors: errors.length > 0 ? errors : undefined,
   };
 }

package/corpus/templates/content/shared/document-text-edits.ts

@@ -0,0 +1,39 @@
+export interface DocumentTextEdit {
+  find: string;
+  replace: string;
+}
+
+export function applyDocumentTextEdits(
+  source: string,
+  edits: DocumentTextEdit[],
+) {
+  let content = source;
+  const results: string[] = [];
+  const appliedEdits: DocumentTextEdit[] = [];
+
+  for (const edit of edits) {
+    const index = content.indexOf(edit.find);
+    if (index === -1) {
+      results.push(
+        `NOT FOUND: "${edit.find.slice(0, 60)}${edit.find.length > 60 ? "..." : ""}"`,
+      );
+      continue;
+    }
+    content =
+      content.slice(0, index) +
+      edit.replace +
+      content.slice(index + edit.find.length);
+    appliedEdits.push(edit);
+    const action = edit.replace === "" ? "deleted" : "replaced";
+    results.push(
+      `${action}: "${edit.find.slice(0, 40)}${edit.find.length > 40 ? "..." : ""}"`,
+    );
+  }
+
+  return {
+    content,
+    results,
+    appliedEdits,
+    changeCount: appliedEdits.length,
+  };
+}