@agent-native/core 0.164.11 → 0.164.15

package/corpus/templates/content/app/components/sidebar/local-source-hierarchy.ts

@@ -0,0 +1,189 @@
+import type { ContentDatabaseItem, DocumentProperty } from "@shared/api";
+
+const LOCAL_SOURCE_DIRECTORY_PREFIX = "local-source-directory:";
+
+function normalizedSourcePath(path: string | undefined) {
+  const normalized = (path ?? "").replace(/\\/g, "/").replace(/^\/+/, "");
+  if (
+    !normalized ||
+    normalized.includes("\0") ||
+    normalized.split("/").some((part) => !part || part === "." || part === "..")
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+function parentPath(path: string) {
+  const separator = path.lastIndexOf("/");
+  return separator === -1 ? "" : path.slice(0, separator);
+}
+
+function sourceIds(item: ContentDatabaseItem) {
+  const value = item.properties.find(
+    (property) => property.definition.systemRole === "files_source",
+  )?.value;
+  return Array.isArray(value)
+    ? value.filter(
+        (candidate): candidate is string =>
+          typeof candidate === "string" && candidate !== "local",
+      )
+    : [];
+}
+
+export function localSourceItemIdentity(item: ContentDatabaseItem) {
+  return sourceIds(item)[0] ?? item.document.source?.rootPath ?? null;
+}
+
+function directoryId(sourceIdentity: string, path: string) {
+  return `${LOCAL_SOURCE_DIRECTORY_PREFIX}${encodeURIComponent(sourceIdentity)}:${encodeURIComponent(path)}`;
+}
+
+function systemProperties(
+  item: ContentDatabaseItem,
+  sourceIdentity: string,
+  parentId: string | null,
+): DocumentProperty[] {
+  return item.properties
+    .filter((property) => property.definition.systemRole)
+    .map((property) => {
+      if (property.definition.systemRole === "files_parent") {
+        return { ...property, value: parentId, editable: false };
+      }
+      if (property.definition.systemRole === "files_source") {
+        return { ...property, value: [sourceIdentity], editable: false };
+      }
+      return { ...property, editable: false };
+    });
+}
+
+function directoryItem(
+  template: ContentDatabaseItem,
+  sourceIdentity: string,
+  path: string,
+  position: number,
+): ContentDatabaseItem {
+  const parent = parentPath(path);
+  const parentId = parent ? directoryId(sourceIdentity, parent) : null;
+  const id = directoryId(sourceIdentity, path);
+  return {
+    id,
+    databaseId: template.databaseId,
+    document: {
+      ...template.document,
+      id,
+      parentId,
+      title: path.split("/").pop()?.replace(/[-_]+/g, " ") || path,
+      content: "",
+      description: "",
+      icon: null,
+      position,
+      isFavorite: false,
+      hideFromSearch: true,
+      accessRole: "viewer",
+      canView: true,
+      canComment: false,
+      canEdit: false,
+      canManage: false,
+      databaseMembership: undefined,
+      source: {
+        mode: "local-files",
+        kind: "folder",
+        path,
+        rootPath: template.document.source?.rootPath,
+      },
+    },
+    position,
+    properties: systemProperties(template, sourceIdentity, parentId),
+  };
+}
+
+export interface LocalSourceHierarchySelection {
+  sourceId?: string | null;
+  rootPath?: string | null;
+}
+
+export function firstLocalSourceDocumentId(items: ContentDatabaseItem[]) {
+  return items.find(
+    (item) =>
+      item.document.source?.mode === "local-files" &&
+      item.document.source.kind !== "folder",
+  )?.document.id;
+}
+
+export function projectLocalSourceHierarchy(
+  items: ContentDatabaseItem[],
+  selection: LocalSourceHierarchySelection = {},
+) {
+  const localFiles = items.filter((item) => {
+    if (
+      item.document.source?.mode !== "local-files" ||
+      item.document.source.kind === "folder"
+    ) {
+      return false;
+    }
+    if (selection.sourceId) {
+      return sourceIds(item).includes(selection.sourceId);
+    }
+    if (selection.rootPath) {
+      return item.document.source.rootPath === selection.rootPath;
+    }
+    return true;
+  });
+  const retained = items.filter(
+    (item) => item.document.source?.mode !== "local-files",
+  );
+  const directories = new Map<
+    string,
+    { template: ContentDatabaseItem; sourceIdentity: string; path: string }
+  >();
+  const projectedFiles: ContentDatabaseItem[] = [];
+
+  for (const item of localFiles) {
+    const path = normalizedSourcePath(item.document.source?.path);
+    const sourceIdentity =
+      selection.sourceId && sourceIds(item).includes(selection.sourceId)
+        ? selection.sourceId
+        : localSourceItemIdentity(item);
+    if (!path || !sourceIdentity) continue;
+    const folder = parentPath(path);
+    if (folder) {
+      const parts = folder.split("/");
+      for (let index = 1; index <= parts.length; index += 1) {
+        const directoryPath = parts.slice(0, index).join("/");
+        directories.set(`${sourceIdentity}\0${directoryPath}`, {
+          template: item,
+          sourceIdentity,
+          path: directoryPath,
+        });
+      }
+    }
+    const parentId = folder ? directoryId(sourceIdentity, folder) : null;
+    projectedFiles.push({
+      ...item,
+      document: { ...item.document, parentId },
+      properties: item.properties.map((property) =>
+        property.definition.systemRole === "files_parent"
+          ? { ...property, value: parentId }
+          : property,
+      ),
+    });
+  }
+
+  const projectedDirectories = [...directories.values()]
+    .sort((left, right) =>
+      left.sourceIdentity === right.sourceIdentity
+        ? left.path.localeCompare(right.path)
+        : left.sourceIdentity.localeCompare(right.sourceIdentity),
+    )
+    .map((directory, index) =>
+      directoryItem(
+        directory.template,
+        directory.sourceIdentity,
+        directory.path,
+        index,
+      ),
+    );
+
+  return [...retained, ...projectedDirectories, ...projectedFiles];
+}

package/corpus/templates/content/app/hooks/use-create-page.ts

@@ -1,7 +1,7 @@
 import type { Document } from "@shared/api";
 import { useQueryClient } from "@tanstack/react-query";
 import { useCallback } from "react";
-import { useNavigate } from "react-router";
+import { useLocation, useNavigate } from "react-router";
 import { toast } from "sonner";
 
 import {
@@ -10,7 +10,10 @@ import {
   SELECTED_CONTENT_SPACE_STORAGE_KEY,
 } from "@/components/sidebar/select-content-space";
 import { useContentSpaces } from "@/hooks/use-content-spaces";
-import { useCreateDocument } from "@/hooks/use-documents";
+import {
+  rollbackOptimisticCreatedDocument,
+  useCreateDocument,
+} from "@/hooks/use-documents";
 import { useLocalStorage } from "@/hooks/use-local-storage";
 import { documentQueryFilter } from "@/lib/document-query";
 import { markDocumentCreationPending } from "@/lib/optimistic-document";
@@ -34,6 +37,7 @@ export function useCreatePage(opts?: {
   awaitPersist?: boolean;
 }) {
   const navigate = useNavigate();
+  const location = useLocation();
   const queryClient = useQueryClient();
   const createDocument = useCreateDocument();
   const contentSpacesQuery = useContentSpaces();
@@ -78,11 +82,19 @@ export function useCreatePage(opts?: {
         createdAt: now,
         updatedAt: now,
       });
+      const previousDocuments = queryClient.getQueryData(
+        LIST_DOCUMENTS_QUERY_KEY,
+      );
+      const previousPath = `${location.pathname}${location.search}${location.hash}`;
 
       queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, (old: any) => {
         const docs: Document[] =
           old?.documents ?? (Array.isArray(old) ? old : []);
-        return { documents: [...docs, tempDoc] };
+        if (Array.isArray(old)) return [...docs, tempDoc];
+        return {
+          ...(old && typeof old === "object" ? old : {}),
+          documents: [...docs, tempDoc],
+        };
       });
       queryClient.setQueryData(["action", "get-document", { id }], tempDoc);
 
@@ -111,11 +123,18 @@ export function useCreatePage(opts?: {
       };
 
       const onPersistError = (err: unknown) => {
+        rollbackOptimisticCreatedDocument(
+          queryClient,
+          id,
+          previousDocuments !== undefined,
+        );
         queryClient.invalidateQueries({
           queryKey: ["action", "list-documents"],
         });
         queryClient.removeQueries(documentQueryFilter(id));
-        if (shouldNavigate) navigate("/");
+        if (shouldNavigate) {
+          navigate(previousPath, { replace: true, flushSync: true });
+        }
         toast.error("Failed to create page", {
           description:
             err instanceof Error ? err.message : "Something went wrong",
@@ -137,6 +156,9 @@ export function useCreatePage(opts?: {
     },
     [
       createDocument,
+      location.hash,
+      location.pathname,
+      location.search,
       navigate,
       onAfterNavigate,
       queryClient,

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

@@ -66,6 +66,89 @@ export const LIST_DOCUMENTS_QUERY_KEY = [
   undefined,
 ] as const;
 
+export function restoreListDocumentsSnapshot(
+  queryClient: Pick<QueryClient, "removeQueries" | "setQueryData">,
+  snapshot: unknown,
+) {
+  if (snapshot === undefined) {
+    queryClient.removeQueries({ queryKey: LIST_DOCUMENTS_QUERY_KEY });
+    return;
+  }
+  queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, snapshot);
+}
+
+export function rollbackOptimisticCreatedDocument(
+  queryClient: Pick<
+    QueryClient,
+    "getQueryData" | "removeQueries" | "setQueryData"
+  >,
+  documentId: string,
+  hadListSnapshot: boolean,
+) {
+  const current = queryClient.getQueryData(LIST_DOCUMENTS_QUERY_KEY);
+  const documents: Document[] = Array.isArray(current)
+    ? current
+    : ((current as DocumentListResponse | undefined)?.documents ?? []);
+  const remaining = documents.filter((document) => document.id !== documentId);
+
+  if (!hadListSnapshot && remaining.length === 0) {
+    queryClient.removeQueries({ queryKey: LIST_DOCUMENTS_QUERY_KEY });
+    return;
+  }
+
+  if (Array.isArray(current)) {
+    queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, remaining);
+    return;
+  }
+
+  queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, {
+    ...(current && typeof current === "object" ? current : {}),
+    documents: remaining,
+  });
+}
+
+export function restoreDeletedDocumentSnapshots(
+  queryClient: Pick<QueryClient, "getQueryData" | "setQueryData">,
+  listSnapshot: unknown,
+  documentSnapshots: Array<[readonly unknown[], unknown]>,
+  deletedDocumentIds: Iterable<string>,
+) {
+  const deletedIds = new Set(deletedDocumentIds);
+  const snapshotDocuments: Document[] = Array.isArray(listSnapshot)
+    ? listSnapshot
+    : ((listSnapshot as DocumentListResponse | undefined)?.documents ?? []);
+  const current = queryClient.getQueryData(LIST_DOCUMENTS_QUERY_KEY);
+  const currentDocuments: Document[] = Array.isArray(current)
+    ? current
+    : ((current as DocumentListResponse | undefined)?.documents ?? []);
+  const currentDocumentIds = new Set(
+    currentDocuments.map((document) => document.id),
+  );
+  const restoredDocuments = snapshotDocuments.filter(
+    (document) =>
+      deletedIds.has(document.id) && !currentDocumentIds.has(document.id),
+  );
+  const documents = [...currentDocuments, ...restoredDocuments];
+
+  if (Array.isArray(current)) {
+    queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, documents);
+  } else {
+    queryClient.setQueryData(LIST_DOCUMENTS_QUERY_KEY, {
+      ...(current && typeof current === "object"
+        ? current
+        : listSnapshot && typeof listSnapshot === "object"
+          ? listSnapshot
+          : {}),
+      documents,
+    });
+  }
+  for (const [queryKey, data] of documentSnapshots) {
+    if (queryClient.getQueryData(queryKey) === undefined) {
+      queryClient.setQueryData(queryKey, data);
+    }
+  }
+}
+
 const DOCUMENT_LIST_PAGE_SIZE = 200;
 
 export async function fetchCompleteDocumentList(

package/corpus/templates/content/app/i18n-data.ts

@@ -2876,6 +2876,7 @@ const editorToolbarMessages = {
   pushFailed: "Push failed.",
   pushLocal: "Push local",
   pushToNotion: "Push to Notion",
+  redo: "Redo",
   revealInFinder: "Reveal in Finder",
   revealedLocalFile: "Revealed local file",
   searchNotionPages: "Search Notion pages...",
@@ -2896,6 +2897,7 @@ const editorToolbarMessages = {
   disconnectedNotionWorkspace: "Disconnected Notion workspace.",
   unlinkFailed: "Unlink failed.",
   unlinkedFromNotion: "Unlinked from Notion.",
+  undo: "Undo",
   versionHistory: "Version history",
 };
 
@@ -3153,6 +3155,13 @@ const enUS = {
       "This Blocks field changed elsewhere. Your edit wasn't saved; the latest version is now shown.",
     couldNotReadLocalSourceFile: "Could not read local source file",
     couldNotSaveLocalFile: "Could not save local file",
+    localFileChangedWithUnsavedEdits:
+      "The file changed on disk while this page had unsaved edits.",
+    localFileReadOnlySnapshot:
+      "Read-only snapshot · Last synced from {{device}} at {{date}}",
+    copyUnsavedText: "Copy my unsaved text",
+    unsavedTextCopied: "Unsaved text copied",
+    useDiskVersion: "Use disk version",
     collabConnectingReadOnly:
       "Connecting live editor. Showing a read-only snapshot.",
     liveDocumentSaveBeforeSyncFailed:
@@ -3497,10 +3506,17 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     editor: {
       couldNotReadLocalSourceFile: "无法读取本地源文件",
       couldNotSaveLocalFile: "无法保存本地文件",
+      localFileChangedWithUnsavedEdits:
+        "此页面有未保存的编辑时，磁盘上的文件已更改。",
+      copyUnsavedText: "复制我未保存的文本",
+      unsavedTextCopied: "已复制未保存的文本",
+      useDiskVersion: "使用磁盘版本",
       documentTitle: "文档标题",
       localFileSavedHistoryNotUpdated: "本地文件已保存，但历史记录未更新",
       title: "标题",
       toolbar: {
+        undo: "撤销",
+        redo: "重做",
         conflict: "冲突",
         conflictResolutionFailed: "冲突解决失败。",
         conflictResolvedFromLocalDocument: "已从本本文档解决冲突。",
@@ -3725,6 +3741,11 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     editor: {
       couldNotReadLocalSourceFile: "No se pudo leer el archivo local de origen",
       couldNotSaveLocalFile: "No se pudo guardar el archivo local",
+      localFileChangedWithUnsavedEdits:
+        "El archivo del disco cambió mientras esta página tenía ediciones sin guardar.",
+      copyUnsavedText: "Copiar mi texto sin guardar",
+      unsavedTextCopied: "Texto sin guardar copiado",
+      useDiskVersion: "Usar la versión del disco",
       documentTitle: "Título del documento",
       localFileSavedHistoryNotUpdated:
         "El archivo local se guardó, pero el historial no se actualizó",
@@ -3791,6 +3812,8 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
           "Transcribe este video y agrega la transcripción debajo.",
       },
       toolbar: {
+        undo: "Deshacer",
+        redo: "Rehacer",
         conflict: "Conflicto",
         conflictResolutionFailed: "Error al resolver el conflicto.",
         conflictResolvedFromLocalDocument:
@@ -3929,6 +3952,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "fr-FR": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "Le fichier sur le disque a changé alors que cette page contenait des modifications non enregistrées.",
+      copyUnsavedText: "Copier mon texte non enregistré",
+      unsavedTextCopied: "Texte non enregistré copié",
+      useDiskVersion: "Utiliser la version du disque",
+      toolbar: { undo: "Annuler", redo: "Rétablir" },
+    },
     sidebar: {
       addChild: "Ajouter un enfant",
       addChildTo: "Ajouter un enfant à {{title}}",
@@ -3965,6 +3996,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "de-DE": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "Die Datei auf dem Datenträger wurde geändert, während diese Seite ungespeicherte Änderungen enthielt.",
+      copyUnsavedText: "Meinen ungespeicherten Text kopieren",
+      unsavedTextCopied: "Ungespeicherter Text kopiert",
+      useDiskVersion: "Version vom Datenträger verwenden",
+      toolbar: { undo: "Rückgängig", redo: "Wiederholen" },
+    },
     sidebar: {
       addChild: "Unterelement hinzufügen",
       addChildTo: "Unterelement zu {{title}} hinzufügen",
@@ -4000,6 +4039,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "ja-JP": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "このページに未保存の編集がある間に、ディスク上のファイルが変更されました。",
+      copyUnsavedText: "未保存のテキストをコピー",
+      unsavedTextCopied: "未保存のテキストをコピーしました",
+      useDiskVersion: "ディスク上の版を使用",
+      toolbar: { undo: "元に戻す", redo: "やり直す" },
+    },
     sidebar: {
       addChild: "子項目を追加",
       addChildTo: "{{title}} に子項目を追加",
@@ -4033,6 +4080,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "ko-KR": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "이 페이지에 저장하지 않은 편집 내용이 있는 동안 디스크의 파일이 변경되었습니다.",
+      copyUnsavedText: "저장하지 않은 텍스트 복사",
+      unsavedTextCopied: "저장하지 않은 텍스트를 복사했습니다",
+      useDiskVersion: "디스크 버전 사용",
+      toolbar: { undo: "실행 취소", redo: "다시 실행" },
+    },
     sidebar: {
       addChild: "하위 항목 추가",
       addChildTo: "{{title}}에 하위 항목 추가",
@@ -4065,6 +4120,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "pt-BR": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "O arquivo no disco foi alterado enquanto esta página tinha edições não salvas.",
+      copyUnsavedText: "Copiar meu texto não salvo",
+      unsavedTextCopied: "Texto não salvo copiado",
+      useDiskVersion: "Usar versão do disco",
+      toolbar: { undo: "Desfazer", redo: "Refazer" },
+    },
     sidebar: {
       addChild: "Adicionar filho",
       addChildTo: "Adicionar filho a {{title}}",
@@ -4099,6 +4162,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "hi-IN": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "इस पेज में सहेजे नहीं गए बदलाव होने के दौरान डिस्क की फ़ाइल बदल गई।",
+      copyUnsavedText: "मेरा सहेजा नहीं गया टेक्स्ट कॉपी करें",
+      unsavedTextCopied: "सहेजा नहीं गया टेक्स्ट कॉपी किया गया",
+      useDiskVersion: "डिस्क वाला संस्करण उपयोग करें",
+      toolbar: { undo: "पूर्ववत करें", redo: "फिर से करें" },
+    },
     sidebar: {
       addChild: "चाइल्ड जोड़ें",
       addChildTo: "{{title}} में चाइल्ड जोड़ें",
@@ -4131,6 +4202,14 @@ const rawLiteralLocaleMessages: Partial<Record<LocaleCode, PartialMessages>> = {
     },
   },
   "ar-SA": {
+    editor: {
+      localFileChangedWithUnsavedEdits:
+        "تغيّر الملف على القرص أثناء وجود تعديلات غير محفوظة في هذه الصفحة.",
+      copyUnsavedText: "نسخ النص غير المحفوظ",
+      unsavedTextCopied: "تم نسخ النص غير المحفوظ",
+      useDiskVersion: "استخدام نسخة القرص",
+      toolbar: { undo: "تراجع", redo: "إعادة" },
+    },
     sidebar: {
       addChild: "إضافة عنصر فرعي",
       addChildTo: "إضافة عنصر فرعي إلى {{title}}",

package/corpus/templates/content/app/lib/desktop-content-files.ts

@@ -1,7 +1,17 @@
 export interface DesktopContentFilesFolder {
   id?: string;
   name: string;
-  path?: string;
+  kind?: "persistent" | "temporary";
+  repository?: {
+    localId: string;
+    branch?: string;
+    commit?: string;
+    detached?: boolean;
+  };
+  contentSource?: {
+    sourceId: string;
+    databaseId?: string;
+  };
   sourcePrefix?: string;
   updatedAt?: string;
 }
@@ -10,6 +20,27 @@ export interface DesktopContentFilesFolderRequest {
   folderId?: string;
 }
 
+/** Opaque content fingerprint returned by the trusted local bridge. */
+export type DesktopContentFileRevision = string;
+
+export interface DesktopContentFileConflict {
+  path: string;
+  expectedRevision?: string | null;
+  actualRevision?: string;
+}
+
+export type DesktopContentFilesChange = {
+  folderId: string;
+  revision: string;
+  changedAt: string;
+  missing?: boolean;
+  reason?: "attached" | "changed" | "missing";
+};
+
+export type DesktopContentFilesWatchResult =
+  | { ok: true; unsubscribe(): void }
+  | { ok: false; error: string; unavailable?: boolean };
+
 export type DesktopContentFilesResult =
   | {
       ok: true;
@@ -17,6 +48,8 @@ export type DesktopContentFilesResult =
       folders?: DesktopContentFilesFolder[];
       files?: string[];
       sources?: Record<string, string>;
+      revisions?: Record<string, DesktopContentFileRevision>;
+      identities?: Record<string, string>;
       controlResources?: Record<string, string>;
     }
   | {
@@ -25,6 +58,8 @@ export type DesktopContentFilesResult =
       canceled?: boolean;
       folder?: DesktopContentFilesFolder;
       folders?: DesktopContentFilesFolder[];
+      code?: "conflict" | "unavailable" | "invalid-request";
+      conflict?: DesktopContentFileConflict;
     };
 
 export interface DesktopContentFilesApi {
@@ -32,18 +67,27 @@ export interface DesktopContentFilesApi {
     request?: DesktopContentFilesFolderRequest,
   ): Promise<DesktopContentFilesResult>;
   chooseFolder(): Promise<DesktopContentFilesResult>;
+  associateSource?(request: {
+    folderId: string;
+    sourceId: string;
+    databaseId?: string;
+  }): Promise<DesktopContentFilesResult>;
   writeFiles(request: {
     folderId?: string;
     files: Record<string, string>;
+    expectedRevisions: Record<string, string | null>;
   }): Promise<DesktopContentFilesResult>;
   writeFile(request: {
     folderId?: string;
     path: string;
     content: string;
+    /** The revision observed by the editor; a mismatch must not overwrite. */
+    expectedRevision: string | null;
   }): Promise<DesktopContentFilesResult>;
   deleteFile?(request: {
     folderId?: string;
     path: string;
+    expectedRevision: string;
   }): Promise<DesktopContentFilesResult>;
   readFiles(
     request?: DesktopContentFilesFolderRequest,
@@ -55,6 +99,18 @@ export interface DesktopContentFilesApi {
   clearFolder(
     request?: DesktopContentFilesFolderRequest,
   ): Promise<DesktopContentFilesResult>;
+  subscribeChanges?(
+    request: DesktopContentFilesFolderRequest,
+  ): Promise<DesktopContentFilesResult>;
+  unsubscribeChanges?(
+    request: DesktopContentFilesFolderRequest,
+  ): Promise<DesktopContentFilesResult>;
+  onChange?(callback: (change: DesktopContentFilesChange) => void): () => void;
+  /** Optional until the installed Desktop bridge supports live folder events. */
+  watchFiles?(
+    request: DesktopContentFilesFolderRequest,
+    onChange: (change: DesktopContentFilesChange) => void,
+  ): Promise<DesktopContentFilesWatchResult>;
 }
 
 type WindowWithAgentNativeDesktop = Window & {