@agent-native/core 0.85.7 → 0.86.0

package/corpus/core/src/collab/undo.ts

@@ -0,0 +1,432 @@
+/**
+ * Shared per-user undo/redo for collaborative surfaces.
+ *
+ * Two primitives, one rule: undo NEVER reverts another participant's (human
+ * or agent) work, and never restores whole-document snapshots that would
+ * clobber concurrent edits.
+ *
+ * - `useCollabUndo` — Y.UndoManager lifecycle wrapper for Yjs-backed surfaces.
+ *   Tracks only transactions tagged with the local origin, coalesces rapid
+ *   edits, and is recreated/destroyed when the document changes (stale
+ *   managers hold Y.Doc references and grow unboundedly).
+ *
+ * - `useLocalOpUndo` / `createLocalOpUndoController` — inverse-operation undo
+ *   for op-based apps (slides decks, forms). Each local mutation registers
+ *   the granular ops that redo and undo it; Cmd+Z replays the inverse ops
+ *   through the app's normal granular mutation path, so concurrent edits by
+ *   other participants to OTHER items are never touched.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import * as Y from "yjs";
+
+// ---------------------------------------------------------------------------
+// Keyboard shortcut helper (shared by both hooks)
+// ---------------------------------------------------------------------------
+
+export interface UndoKeyboardOptions {
+  /** Bind Mod+Z / Shift+Mod+Z / Mod+Y on window while mounted. */
+  enableKeyboardShortcuts?: boolean;
+  /**
+   * Skip the shortcut when the event target is an input, textarea, or
+   * contentEditable (those own their own undo). Default true.
+   */
+  ignoreInputTargets?: boolean;
+}
+
+function isEditableTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  if (!el) return false;
+  const tag = el.tagName;
+  return (
+    tag === "INPUT" ||
+    tag === "TEXTAREA" ||
+    tag === "SELECT" ||
+    !!el.isContentEditable
+  );
+}
+
+function useUndoKeyboard(
+  undo: () => void,
+  redo: () => void,
+  options: UndoKeyboardOptions | undefined,
+): void {
+  const enabled = options?.enableKeyboardShortcuts ?? false;
+  const ignoreInputs = options?.ignoreInputTargets ?? true;
+
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return;
+
+    function onKeyDown(e: KeyboardEvent) {
+      if (!(e.metaKey || e.ctrlKey)) return;
+      if (ignoreInputs && isEditableTarget(e.target)) return;
+      const key = e.key.toLowerCase();
+      if (key === "z") {
+        e.preventDefault();
+        if (e.shiftKey) redo();
+        else undo();
+      } else if (key === "y") {
+        e.preventDefault();
+        redo();
+      }
+    }
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [enabled, ignoreInputs, undo, redo]);
+}
+
+// ---------------------------------------------------------------------------
+// Yjs-backed undo — useCollabUndo
+// ---------------------------------------------------------------------------
+
+export type CollabUndoScope =
+  | Y.AbstractType<any>
+  | Y.AbstractType<any>[]
+  | ((doc: Y.Doc) => Y.AbstractType<any> | Y.AbstractType<any>[]);
+
+export interface UseCollabUndoOptions extends UndoKeyboardOptions {
+  /** The collaborative document. Null/undefined while loading. */
+  ydoc: Y.Doc | null | undefined;
+  /**
+   * Shared type(s) to track, or a factory receiving the doc (evaluated when
+   * the doc changes) — e.g. `(doc) => doc.getText("content")`.
+   */
+  scope: CollabUndoScope;
+  /**
+   * Origins captured as undoable. Defaults to the hook's own `localOrigin`.
+   * Transactions from remote peers ("remote") and the agent ("agent"/
+   * "server") are never captured.
+   */
+  trackedOrigins?: unknown[];
+  /** Coalesce rapid edits into one undo step. Default 500ms. */
+  captureTimeout?: number;
+}
+
+export interface UseCollabUndoResult {
+  /** Undo the local user's most recent edit. Returns true if applied. */
+  undo: () => boolean;
+  /** Redo the local user's most recently undone edit. */
+  redo: () => boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  /**
+   * Tag local transactions with this origin so they're captured:
+   * `ydoc.transact(() => { ... }, localOrigin)` — or use `transactLocal`.
+   */
+  localOrigin: unknown;
+  /** Run a mutation in a transaction tagged with the local origin. */
+  transactLocal: <T>(fn: () => T) => T;
+  /** The underlying manager (null while the doc is loading). */
+  undoManager: Y.UndoManager | null;
+}
+
+export function useCollabUndo(
+  options: UseCollabUndoOptions,
+): UseCollabUndoResult {
+  const { ydoc, scope, trackedOrigins, captureTimeout = 500 } = options;
+
+  // Stable per-hook local origin (an object identity — never collides).
+  const localOrigin = useMemo<unknown>(
+    () => ({ collabUndoLocalOrigin: true }),
+    [],
+  );
+
+  const managerRef = useRef<Y.UndoManager | null>(null);
+  const [canUndo, setCanUndo] = useState(false);
+  const [canRedo, setCanRedo] = useState(false);
+
+  // Keep latest scope/origins in refs so the effect only re-runs on doc change.
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+  const trackedRef = useRef(trackedOrigins);
+  trackedRef.current = trackedOrigins;
+
+  useEffect(() => {
+    if (!ydoc) {
+      managerRef.current = null;
+      setCanUndo(false);
+      setCanRedo(false);
+      return;
+    }
+
+    const rawScope = scopeRef.current;
+    const resolved = typeof rawScope === "function" ? rawScope(ydoc) : rawScope;
+    const scopes = Array.isArray(resolved) ? resolved : [resolved];
+
+    const origins = new Set<unknown>(trackedRef.current ?? [localOrigin]);
+    const manager = new Y.UndoManager(scopes, {
+      trackedOrigins: origins,
+      captureTimeout,
+    });
+    // The manager applies undo/redo transactions with itself as origin;
+    // track it so redo of an undone step is capturable.
+    origins.add(manager);
+    managerRef.current = manager;
+
+    function refresh() {
+      setCanUndo(manager.undoStack.length > 0);
+      setCanRedo(manager.redoStack.length > 0);
+    }
+    refresh();
+
+    manager.on("stack-item-added", refresh);
+    manager.on("stack-item-popped", refresh);
+    manager.on("stack-cleared", refresh);
+
+    return () => {
+      manager.off("stack-item-added", refresh);
+      manager.off("stack-item-popped", refresh);
+      manager.off("stack-cleared", refresh);
+      manager.destroy();
+      if (managerRef.current === manager) {
+        managerRef.current = null;
+      }
+    };
+  }, [ydoc, captureTimeout, localOrigin]);
+
+  const undo = useCallback((): boolean => {
+    const m = managerRef.current;
+    if (!m || m.undoStack.length === 0) return false;
+    m.undo();
+    return true;
+  }, []);
+
+  const redo = useCallback((): boolean => {
+    const m = managerRef.current;
+    if (!m || m.redoStack.length === 0) return false;
+    m.redo();
+    return true;
+  }, []);
+
+  const transactLocal = useCallback(
+    <T>(fn: () => T): T => {
+      if (!ydoc) return fn();
+      let result!: T;
+      ydoc.transact(() => {
+        result = fn();
+      }, localOrigin);
+      return result;
+    },
+    [ydoc, localOrigin],
+  );
+
+  useUndoKeyboard(undo, redo, options);
+
+  return {
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    localOrigin,
+    transactLocal,
+    undoManager: managerRef.current,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Inverse-op undo — createLocalOpUndoController / useLocalOpUndo
+// ---------------------------------------------------------------------------
+
+export interface LocalOpUndoEntry<TOp> {
+  /** Granular ops that reverse the mutation. */
+  undo: TOp[];
+  /** Granular ops that re-apply the mutation. */
+  redo: TOp[];
+  /** Optional label for UI ("Delete slide 3"). */
+  label?: string;
+  /**
+   * Coalescing key: consecutive pushes with the same non-empty key within
+   * `coalesceMs` merge into one entry (keeps the FIRST undo ops and the
+   * LATEST redo ops) — e.g. per-keystroke text patches on one field.
+   */
+  coalesceKey?: string;
+}
+
+export interface LocalOpUndoController<TOp> {
+  /** Record a local mutation. Clears the redo stack. */
+  push(entry: LocalOpUndoEntry<TOp>): void;
+  /** Apply the inverse ops of the most recent entry. */
+  undo(): Promise<boolean>;
+  /** Re-apply the most recently undone entry. */
+  redo(): Promise<boolean>;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  clear(): void;
+  /** Peek labels for UI (undo tooltip). */
+  peekUndoLabel(): string | undefined;
+  peekRedoLabel(): string | undefined;
+}
+
+export interface CreateLocalOpUndoOptions<TOp> {
+  /**
+   * Apply granular ops through the app's normal mutation path. MUST NOT
+   * push back into this controller (re-entrant pushes are ignored).
+   */
+  apply: (
+    ops: TOp[],
+    direction: "undo" | "redo",
+    entry: LocalOpUndoEntry<TOp>,
+  ) => void | Promise<void>;
+  /** Max retained entries. Default 200. */
+  maxDepth?: number;
+  /** Window for coalescing same-key pushes. Default 800ms. */
+  coalesceMs?: number;
+  /** Called after any stack change (for canUndo/canRedo UI updates). */
+  onChange?: () => void;
+  /** Clock override for tests. */
+  now?: () => number;
+}
+
+interface StampedEntry<TOp> extends LocalOpUndoEntry<TOp> {
+  at: number;
+}
+
+export function createLocalOpUndoController<TOp>(
+  options: CreateLocalOpUndoOptions<TOp>,
+): LocalOpUndoController<TOp> {
+  const {
+    apply,
+    maxDepth = 200,
+    coalesceMs = 800,
+    onChange,
+    now = () => Date.now(),
+  } = options;
+
+  const undoStack: StampedEntry<TOp>[] = [];
+  const redoStack: StampedEntry<TOp>[] = [];
+  let applying = false;
+
+  function notify() {
+    onChange?.();
+  }
+
+  return {
+    push(entry) {
+      // Ignore pushes triggered by our own undo/redo application.
+      if (applying) return;
+
+      const at = now();
+      const top = undoStack[undoStack.length - 1];
+      if (
+        top &&
+        entry.coalesceKey &&
+        top.coalesceKey === entry.coalesceKey &&
+        at - top.at <= coalesceMs
+      ) {
+        // Merge: first undo wins (restores the pre-burst state), latest redo
+        // wins (re-applies the final state).
+        top.redo = entry.redo;
+        top.at = at;
+      } else {
+        undoStack.push({ ...entry, at });
+        if (undoStack.length > maxDepth) {
+          undoStack.splice(0, undoStack.length - maxDepth);
+        }
+      }
+      redoStack.length = 0;
+      notify();
+    },
+
+    async undo() {
+      const entry = undoStack.pop();
+      if (!entry) return false;
+      redoStack.push(entry);
+      notify();
+      applying = true;
+      try {
+        await apply(entry.undo, "undo", entry);
+      } finally {
+        applying = false;
+      }
+      return true;
+    },
+
+    async redo() {
+      const entry = redoStack.pop();
+      if (!entry) return false;
+      undoStack.push(entry);
+      notify();
+      applying = true;
+      try {
+        await apply(entry.redo, "redo", entry);
+      } finally {
+        applying = false;
+      }
+      return true;
+    },
+
+    canUndo: () => undoStack.length > 0,
+    canRedo: () => redoStack.length > 0,
+
+    clear() {
+      undoStack.length = 0;
+      redoStack.length = 0;
+      notify();
+    },
+
+    peekUndoLabel: () => undoStack[undoStack.length - 1]?.label,
+    peekRedoLabel: () => redoStack[redoStack.length - 1]?.label,
+  };
+}
+
+export interface UseLocalOpUndoOptions<TOp>
+  extends
+    Omit<CreateLocalOpUndoOptions<TOp>, "onChange">,
+    UndoKeyboardOptions {}
+
+export interface UseLocalOpUndoResult<TOp> {
+  push: (entry: LocalOpUndoEntry<TOp>) => void;
+  undo: () => Promise<boolean>;
+  redo: () => Promise<boolean>;
+  canUndo: boolean;
+  canRedo: boolean;
+  clear: () => void;
+  controller: LocalOpUndoController<TOp>;
+}
+
+export function useLocalOpUndo<TOp>(
+  options: UseLocalOpUndoOptions<TOp>,
+): UseLocalOpUndoResult<TOp> {
+  const [, setTick] = useState(0);
+  const applyRef = useRef(options.apply);
+  applyRef.current = options.apply;
+
+  const controller = useMemo(
+    () =>
+      createLocalOpUndoController<TOp>({
+        apply: (ops, direction, entry) =>
+          applyRef.current(ops, direction, entry),
+        maxDepth: options.maxDepth,
+        coalesceMs: options.coalesceMs,
+        now: options.now,
+        onChange: () => setTick((n) => n + 1),
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  const undo = useCallback(() => controller.undo(), [controller]);
+  const redo = useCallback(() => controller.redo(), [controller]);
+  const push = useCallback(
+    (entry: LocalOpUndoEntry<TOp>) => controller.push(entry),
+    [controller],
+  );
+  const clear = useCallback(() => controller.clear(), [controller]);
+
+  useUndoKeyboard(
+    () => void controller.undo(),
+    () => void controller.redo(),
+    options,
+  );
+
+  return {
+    push,
+    undo,
+    redo,
+    canUndo: controller.canUndo(),
+    canRedo: controller.canRedo(),
+    clear,
+    controller,
+  };
+}

package/corpus/core/src/collab/ydoc-manager.ts

@@ -38,6 +38,57 @@ import { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";
 const DEFAULT_FIELD = "content";
 const MAX_CACHE = 50;
 
+/**
+ * Auto-presence: any agent-sourced write produces visible presence and
+ * lingering edit attribution without the calling action having to wire
+ * agentEnterDocument/agentLeaveDocument itself. Dynamic import avoids a
+ * static cycle (agent-presence.ts imports searchAndReplace from this module).
+ */
+function touchAgentPresence(
+  docId: string,
+  requestSource: string | undefined,
+  edit: { descriptor: Record<string, unknown>; label?: string } | null,
+): void {
+  if (requestSource !== "agent") return;
+  import("./agent-presence.js")
+    .then((mod) => {
+      mod.agentTouchDocument(docId, edit ? { edit: edit as any } : undefined);
+    })
+    .catch(() => {
+      // Presence is best-effort; never fail the write for it.
+    });
+}
+
+/**
+ * Compute a small "what changed" descriptor from a text diff by trimming the
+ * common prefix/suffix. Used for lingering edit highlights client-side.
+ */
+export function computeTextEditDescriptor(
+  oldText: string,
+  newText: string,
+): { kind: "text"; quote: string } | { kind: "doc" } {
+  let start = 0;
+  const maxStart = Math.min(oldText.length, newText.length);
+  while (start < maxStart && oldText[start] === newText[start]) start++;
+
+  let endOld = oldText.length;
+  let endNew = newText.length;
+  while (
+    endOld > start &&
+    endNew > start &&
+    oldText[endOld - 1] === newText[endNew - 1]
+  ) {
+    endOld--;
+    endNew--;
+  }
+
+  const inserted = newText.slice(start, endNew).trim();
+  if (inserted.length > 0) {
+    return { kind: "text", quote: inserted.slice(0, 120) };
+  }
+  return { kind: "doc" };
+}
+
 /**
  * Compaction ratio threshold. When the stored state byte count exceeds
  * COMPACTION_RATIO × the freshly encoded state, write the compact form
@@ -234,6 +285,7 @@ export async function applyText(
 ): Promise<string> {
   return withDocWriteLock(docId, async () => {
     const doc = await getDoc(docId);
+    const oldText = doc.getText(fieldName).toString();
     const update = applyTextToYDoc(doc, fieldName, newText, "server");
 
     if (update.length === 0) {
@@ -245,6 +297,9 @@ export async function applyText(
     );
 
     emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+    touchAgentPresence(docId, requestSource, {
+      descriptor: computeTextEditDescriptor(oldText, newText),
+    });
     return doc.getText(fieldName).toString();
   });
 }
@@ -285,6 +340,12 @@ export async function searchAndReplace(
 
     await persistMergedState(docId, doc, () => extractTextFromYXml(fragment));
     emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+    touchAgentPresence(docId, requestSource, {
+      descriptor: {
+        kind: "text",
+        quote: (replace || find).slice(0, 120),
+      },
+    });
 
     return { found: true, update };
   });
@@ -369,6 +430,7 @@ export async function applyJson(
     );
 
     emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+    touchAgentPresence(docId, requestSource, { descriptor: { kind: "doc" } });
   });
 }
 
@@ -392,6 +454,12 @@ export async function applyPatchOps(
     );
 
     emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+    touchAgentPresence(docId, requestSource, {
+      descriptor: {
+        kind: "paths",
+        paths: ops.slice(0, 5).map((op) => op.path),
+      },
+    });
   });
 }
 

package/corpus/core/src/connections/catalog.ts

@@ -17,8 +17,7 @@ export type WorkspaceConnectionTemplateUse =
   | "dispatch"
   | "forms"
   | "mail"
-  | "slides"
-  | "videos";
+  | "slides";
 
 export type WorkspaceConnectionProviderId =
   | "slack"
@@ -191,7 +190,7 @@ export const WORKSPACE_CONNECTION_PROVIDERS = [
       "Agent-native Clips exports and recordings for transcript import and searchable meeting context.",
     credentialKeys: [],
     capabilities: ["search", "import", "meetings"],
-    recommendedTemplateUses: ["brain", "clips", "videos"],
+    recommendedTemplateUses: ["brain", "clips"],
   }),
   defineWorkspaceConnectionProvider({
     id: "generic",

package/corpus/core/src/db/create-get-db.ts

@@ -180,6 +180,88 @@ export function buildResilientNeonPool(pool: {
   });
 }
 
+/**
+ * Wraps a postgres.js client so Drizzle queries on the non-Neon Postgres
+ * path get the same withDbTimeout + retryOnConnectionError protection as
+ * every other Postgres path (raw DbExec postgres.js, raw DbExec Neon, and
+ * the Drizzle Neon pool above). Without this, one hung query on a BYO
+ * Postgres deployment stalls its request forever.
+ *
+ * Drizzle's postgres-js session only calls `client.unsafe(query, params)` —
+ * awaited directly for row-object results or via `.values()` for row-array
+ * results — plus `client.begin(...)` for transactions. We interpose on
+ * `unsafe` with a lazy thenable that re-issues the query per retry attempt,
+ * and leave transactions unwrapped (same rule as the Neon wrapper: the
+ * driver manages the sticky connection inside `begin`).
+ *
+ * Retry-safety mirrors buildResilientNeonPool: reads retry freely on
+ * connection-class errors; writes retry only on CONNECT_TIMEOUT (postgres.js
+ * raises it before the statement is ever sent), so writes can't
+ * double-execute.
+ */
+export function buildResilientPostgresJsClient<
+  T extends {
+    unsafe(query: string, params?: any[], options?: any): any;
+  },
+>(client: T): T {
+  const wrapUnsafe = (query: string, params?: any[], options?: any) => {
+    const isRead = isSqlRead(query);
+
+    const runAttempt = (mode: "rows" | "values") => async (): Promise<any> => {
+      const pending = client.unsafe(query, params, options);
+      return withDbTimeout(
+        "query",
+        async () => (mode === "values" ? pending.values() : pending),
+        dbOpTimeoutMs(),
+        () => {
+          // Best-effort cancel so the timed-out statement doesn't keep
+          // occupying one of the (small, serverless-capped) pool slots.
+          try {
+            pending.cancel?.();
+          } catch {
+            // ignore — cancellation is advisory
+          }
+        },
+      );
+    };
+
+    const execute = async (mode: "rows" | "values"): Promise<any> => {
+      if (isRead) return retryOnConnectionError(runAttempt(mode));
+      try {
+        return await runAttempt(mode)();
+      } catch (err) {
+        // Connect timeout fires before the statement is sent → one retry is
+        // safe even for writes.
+        if (
+          isConnectionError(err) &&
+          (err as any)?.code === "CONNECT_TIMEOUT"
+        ) {
+          return runAttempt(mode)();
+        }
+        throw err;
+      }
+    };
+
+    // Lazy thenable mirroring the slice of postgres.js's PendingQuery
+    // surface that Drizzle uses: `await q` or `await q.values()`.
+    return {
+      then: (onFulfilled?: any, onRejected?: any) =>
+        execute("rows").then(onFulfilled, onRejected),
+      catch: (onRejected?: any) => execute("rows").catch(onRejected),
+      finally: (onFinally?: any) => execute("rows").finally(onFinally),
+      values: () => execute("values"),
+    };
+  };
+
+  return new Proxy(client as any, {
+    get(target, prop) {
+      if (prop === "unsafe") return wrapUnsafe;
+      const val = target[prop];
+      return typeof val === "function" ? val.bind(target) : val;
+    },
+  }) as T;
+}
+
 /**
  * Neon's pooler endpoints cold-start in 5–10s. Serverless environments
  * (Netlify Functions, Vercel Edge, CF Workers) have short cold-start
@@ -369,7 +451,7 @@ export function createGetDb<T extends Record<string, unknown>>(schema: T) {
           // concurrent frozen instances don't exhaust Neon/Postgres'
           // connection limit ("Max client connections reached").
           const client = postgres(url, pgPoolOptions(url));
-          _db = drizzle(client, { schema });
+          _db = drizzle(buildResilientPostgresJsClient(client), { schema });
         });
       }
     } else if (isLocalSqliteUrl(url)) {
@@ -378,6 +460,9 @@ export function createGetDb<T extends Record<string, unknown>>(schema: T) {
         getBetterSqliteDrizzle(),
       ]).then(([sqliteUrl, { drizzle, Database }]) => {
         const sqlite = new Database(sqliteFilenameFromUrl(sqliteUrl));
+        // Wait up to 10s for a concurrent writer instead of failing fast
+        // with SQLITE_BUSY — mirrors the raw DbExec SQLite path in client.ts.
+        sqlite.pragma("busy_timeout = 10000");
         sqlite.pragma("journal_mode = WAL");
         const db = drizzle(sqlite, { schema });
         _db = patchBetterSqliteTransactions(db, sqlite);