@agent-native/core 0.85.7 → 0.86.1

package/corpus/core/src/client/rich-markdown-editor/surgical-apply.ts

@@ -0,0 +1,192 @@
+/**
+ * Surgical reconcile — apply an authoritative external document into the live
+ * editor by replacing only the changed top-level node run, instead of a
+ * whole-document `setContent`.
+ *
+ * Why: under the Collaboration extension, `setContent` routes through
+ * y-prosemirror and rewrites the ENTIRE `Y.XmlFragment`. Every block-level
+ * NodeView is torn down and recreated (each `ReactRenderer` constructor calls
+ * `flushSync`, firing inside a React lifecycle), remote carets jump, and the
+ * CRDT sees a delete-all + insert-all instead of a small edit. Diffing the
+ * top-level children and dispatching one `tr.replaceWith(from, to, changed)`
+ * leaves unchanged NodeViews untouched and produces minimal Yjs ops.
+ *
+ * This is the core mechanism behind re-enabling single-doc collab in the plan
+ * editor (see templates/plan/shared/plan-doc.collab-stability.spec.ts, "Option
+ * B") and removing agent-edit NodeView churn in content.
+ */
+
+import { createNodeFromContent } from "@tiptap/core";
+import type { Fragment, Node as ProseMirrorNode } from "@tiptap/pm/model";
+import type { Editor } from "@tiptap/react";
+
+/**
+ * Transaction meta marking programmatic (non-user) rich-markdown transactions.
+ * Declared here (not in useCollabReconcile) so the module dependency stays
+ * one-directional; useCollabReconcile re-exports it for consumers.
+ */
+export const RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION =
+  "an-rich-md-programmatic-transaction";
+
+export interface TopLevelDiff {
+  /** Index of the first differing top-level child. */
+  fromIndex: number;
+  /** Exclusive end index of the differing run in the OLD doc. */
+  oldToIndex: number;
+  /** Exclusive end index of the differing run in the NEW doc. */
+  newToIndex: number;
+  /** Document position where the differing run starts. */
+  fromPos: number;
+  /** Document position where the differing run ends in the OLD doc. */
+  toPos: number;
+}
+
+/**
+ * Diff two documents at top-level-node granularity: trim the common prefix and
+ * suffix (node equality via ProseMirror's `Node.eq`, which is deep) and return
+ * the remaining changed run. Returns null when the documents are equal.
+ */
+export function diffTopLevel(
+  oldDoc: ProseMirrorNode,
+  newDoc: ProseMirrorNode,
+): TopLevelDiff | null {
+  const oldCount = oldDoc.childCount;
+  const newCount = newDoc.childCount;
+
+  let prefix = 0;
+  const maxPrefix = Math.min(oldCount, newCount);
+  while (prefix < maxPrefix && oldDoc.child(prefix).eq(newDoc.child(prefix))) {
+    prefix++;
+  }
+
+  if (prefix === oldCount && prefix === newCount) return null; // identical
+
+  let suffix = 0;
+  const maxSuffix = Math.min(oldCount, newCount) - prefix;
+  while (
+    suffix < maxSuffix &&
+    oldDoc.child(oldCount - 1 - suffix).eq(newDoc.child(newCount - 1 - suffix))
+  ) {
+    suffix++;
+  }
+
+  const fromIndex = prefix;
+  const oldToIndex = oldCount - suffix;
+  const newToIndex = newCount - suffix;
+
+  // Positions: sum nodeSize of the preserved prefix, then of the changed run.
+  let fromPos = 0;
+  for (let i = 0; i < fromIndex; i++) fromPos += oldDoc.child(i).nodeSize;
+  let toPos = fromPos;
+  for (let i = fromIndex; i < oldToIndex; i++) {
+    toPos += oldDoc.child(i).nodeSize;
+  }
+
+  return { fromIndex, oldToIndex, newToIndex, fromPos, toPos };
+}
+
+function changedFragment(
+  newDoc: ProseMirrorNode,
+  diff: TopLevelDiff,
+): Fragment {
+  return newDoc.content.cut(
+    positionOfChild(newDoc, diff.fromIndex),
+    positionOfChild(newDoc, diff.newToIndex),
+  );
+}
+
+function positionOfChild(doc: ProseMirrorNode, index: number): number {
+  let pos = 0;
+  for (let i = 0; i < index; i++) pos += doc.child(i).nodeSize;
+  return pos;
+}
+
+function isEmptyParagraph(node: ProseMirrorNode | null): boolean {
+  return !!node && node.type.name === "paragraph" && node.content.size === 0;
+}
+
+/**
+ * Markdown can't represent a trailing empty paragraph (the cursor line users
+ * keep below a list/code block), so a parsed authoritative value never has
+ * one — but the live doc often does, and the legacy `setContent` path
+ * preserves it. Without this, every surgical reconcile whose old doc ends
+ * with an empty paragraph would DELETE the user's trailing cursor line.
+ */
+function withPreservedTrailingParagraph(
+  oldDoc: ProseMirrorNode,
+  newDoc: ProseMirrorNode,
+): ProseMirrorNode {
+  const oldLast =
+    oldDoc.childCount > 0 ? oldDoc.child(oldDoc.childCount - 1) : null;
+  if (!isEmptyParagraph(oldLast)) return newDoc;
+  const newLast =
+    newDoc.childCount > 0 ? newDoc.child(newDoc.childCount - 1) : null;
+  if (isEmptyParagraph(newLast)) return newDoc;
+  return newDoc.copy(newDoc.content.addToEnd(oldLast!.type.create()));
+}
+
+/**
+ * Replace only the changed top-level run of the live document with the
+ * corresponding run from `newDoc`, in one programmatic, history-free
+ * transaction. Returns:
+ *  - "applied"   — a targeted replacement was dispatched
+ *  - "noop"      — the documents were already equal (nothing dispatched)
+ *  - "failed"    — the diff/transaction could not be applied (schema mismatch,
+ *                  invalid content, …); caller should fall back to setContent.
+ */
+export function applyDocSurgically(
+  editor: Editor,
+  newDoc: ProseMirrorNode,
+): "applied" | "noop" | "failed" {
+  try {
+    const oldDoc = editor.state.doc;
+    // The parsed doc MUST come from this editor's schema — NodeType identity
+    // is per-Schema-instance, so a foreign-schema doc can never diff or apply.
+    if (newDoc.type.schema !== editor.schema || newDoc.type !== oldDoc.type) {
+      return "failed";
+    }
+
+    const target = withPreservedTrailingParagraph(oldDoc, newDoc);
+    const diff = diffTopLevel(oldDoc, target);
+    if (!diff) return "noop";
+
+    const fragment = changedFragment(target, diff);
+    const tr = editor.state.tr;
+    tr.replaceWith(diff.fromPos, diff.toPos, fragment);
+    tr.setMeta("addToHistory", false);
+    tr.setMeta(RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION, true);
+    editor.view.dispatch(tr);
+    return "applied";
+  } catch {
+    return "failed";
+  }
+}
+
+/**
+ * Best-effort default parser for the surgical path: use the tiptap-markdown
+ * storage parser (present when the shared editor's `features.markdown` is on)
+ * to turn the authoritative markdown into a ProseMirror document. Returns null
+ * when unavailable or when parsing fails — the caller falls back to the full
+ * `setContent` path.
+ *
+ * Apps with their own serializers (Content's NFM, Plan's blocks[] doc) should
+ * pass an explicit `parseValue` producing the exact doc their `setContent`
+ * would have written.
+ */
+export function defaultParseValue(
+  editor: Editor,
+  value: string,
+): ProseMirrorNode | null {
+  try {
+    const storage = (editor.storage as Record<string, any>).markdown;
+    const parsed = storage?.parser?.parse?.(value, { inline: false });
+    if (typeof parsed !== "string" || !parsed) return null;
+    const node = createNodeFromContent(parsed, editor.schema, {
+      slice: false,
+    });
+    // createNodeFromContent with slice:false returns a Node (the doc).
+    return (node as ProseMirrorNode) ?? null;
+  } catch {
+    return null;
+  }
+}

package/corpus/core/src/client/rich-markdown-editor/useCollabReconcile.ts

@@ -1,4 +1,5 @@
 import { isChangeOrigin } from "@tiptap/extension-collaboration";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
 import type { Transaction } from "@tiptap/pm/state";
 import type { Editor } from "@tiptap/react";
 import { useEffect, useRef, useState, type MutableRefObject } from "react";
@@ -7,9 +8,13 @@ import type { Doc as YDoc } from "yjs";
 
 import { AGENT_CLIENT_ID } from "../../collab/agent-identity.js";
 import { isReconcileLeadClient } from "../../collab/client.js";
+import {
+  RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION,
+  applyDocSurgically,
+  defaultParseValue,
+} from "./surgical-apply.js";
 
-export const RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION =
-  "an-rich-md-programmatic-transaction";
+export { RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION };
 
 /** Reads the current markdown out of the tiptap-markdown storage. */
 export function getEditorMarkdown(editor: Editor): string {
@@ -71,6 +76,22 @@ export interface UseCollabReconcileOptions {
     value: string,
     options: { emitUpdate?: boolean; addToHistory?: boolean },
   ) => void;
+  /**
+   * Parses the authoritative `value` into a full ProseMirror document for the
+   * SURGICAL reconcile path: instead of a whole-document `setContent` (which
+   * under Collaboration rewrites the entire Y.XmlFragment and tears down every
+   * block NodeView), the reconcile diffs the parsed doc against the live doc
+   * and replaces only the changed top-level run. Return null to skip the
+   * surgical path for a given value (falls back to `setContent`).
+   *
+   * Defaults to a best-effort tiptap-markdown parse; apps with their own
+   * serializers (Content's NFM, Plan's blocks[] doc) should supply the exact
+   * doc their `setContent` would write. Pass `false` to disable surgical
+   * application entirely.
+   */
+  parseValue?:
+    | ((editor: Editor, value: string) => ProseMirrorNode | null)
+    | false;
   /**
    * Normalizes the authoritative `value` to the canonical markdown the editor
    * would emit, so the "already in sync / our own echo" equality checks match a
@@ -198,6 +219,7 @@ export function useCollabReconcile({
   editable,
   getMarkdown = getEditorMarkdown,
   setContent = defaultSetContent,
+  parseValue,
   normalizeValue = (v) => v,
   shouldSeed = defaultShouldSeed,
   initialAppliedUpdatedAt,
@@ -281,20 +303,32 @@ export function useCollabReconcile({
     // Seed only when the shared doc is genuinely empty — either the fragment has
     // no nodes yet, or it holds no semantic markdown (an empty paragraph, or an
     // app's sentinel-empty filler via a custom `shouldSeed`).
+    seededRef.current = true;
     if (
-      shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
+      !shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
     ) {
+      return;
+    }
+
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (cancelled || editor.isDestroyed) return;
       isSettingContentRef.current = true;
-      setContent(editor, value, {});
-      isSettingContentRef.current = false;
+      try {
+        setContent(editor, value, {});
+      } finally {
+        isSettingContentRef.current = false;
+      }
       const serialized = getMarkdown(editor);
       lastEmittedRef.current = serialized;
       pushEmittedRing(recentEmittedRef.current, serialized);
       lastAppliedValueRef.current = value;
       lastAppliedSerializedRef.current = serialized;
       if (contentUpdatedAt) lastAppliedUpdatedAtRef.current = contentUpdatedAt;
-    }
-    seededRef.current = true;
+    });
+    return () => {
+      cancelled = true;
+    };
   }, [
     collab,
     editor,
@@ -452,7 +486,23 @@ export function useCollabReconcile({
           return;
         }
         isSettingContentRef.current = true;
-        setContent(editor, value, { emitUpdate: false, addToHistory: false });
+        // Surgical path first: replace only the changed top-level run so
+        // unchanged block NodeViews are never torn down and (under
+        // Collaboration) Yjs sees a minimal edit instead of a full-fragment
+        // rewrite. Falls back to the classic whole-document setContent when no
+        // parser is available or the targeted transaction cannot be applied.
+        let appliedSurgically = false;
+        if (parseValue !== false) {
+          const parse = parseValue ?? defaultParseValue;
+          const parsedDoc = parse(editor, value);
+          if (parsedDoc) {
+            const result = applyDocSurgically(editor, parsedDoc);
+            appliedSurgically = result === "applied" || result === "noop";
+          }
+        }
+        if (!appliedSurgically) {
+          setContent(editor, value, { emitUpdate: false, addToHistory: false });
+        }
         isSettingContentRef.current = false;
         // Capture the SERIALIZED result, not the raw value. For non-idempotent
         // input these differ; recording the serialized output is what lets the
@@ -482,6 +532,7 @@ export function useCollabReconcile({
     isLeadClient,
     getMarkdown,
     setContent,
+    parseValue,
     normalizeValue,
   ]);
 

package/corpus/core/src/client/session-replay.ts

@@ -95,9 +95,16 @@ export interface SessionReplayConsoleOptions {
  * `agent-native.network` custom events emitted per recording session
  * (default 2000); once hit, capture stops for the rest of the session and one
  * final truncation-notice event is emitted.
+ *
+ * `captureErrorBodies` (default true) additionally captures a bounded,
+ * redacted response-body snippet for 5xx responses only -- request bodies
+ * and headers are never captured, and non-5xx/network-failure responses
+ * never carry a body. `maxErrorBodyLength` (default 2048) caps that snippet.
  */
 export interface SessionReplayNetworkOptions {
   maxEvents?: number;
+  captureErrorBodies?: boolean;
+  maxErrorBodyLength?: number;
 }
 
 export interface SessionReplayOptions {
@@ -141,7 +148,9 @@ export interface SessionReplayOptions {
   console?: boolean | SessionReplayConsoleOptions;
   /**
    * Capture fetch/XHR requests as `agent-native.network` custom rrweb
-   * events (method, URL, status, timing -- never bodies or headers).
+   * events (method, URL, status, timing). Request bodies and headers are
+   * never captured; response bodies are captured only as a bounded,
+   * redacted snippet for 5xx responses (see `captureErrorBodies`).
    * Defaults to on whenever session replay is enabled. Pass `false` to
    * disable, or an options object to override caps.
    */
@@ -203,6 +212,10 @@ interface NormalizedSessionReplayOptions {
 
 interface NormalizedCaptureOptions {
   maxEvents: number;
+  /** Network-only: capture a bounded 5xx response-body snippet. Unused by console. */
+  captureErrorBodies?: boolean;
+  /** Network-only: cap (chars) for the captured error-body snippet. */
+  maxErrorBodyLength?: number;
 }
 
 const DEFAULT_REPLAY_PATH = "/api/analytics/replay";
@@ -263,6 +276,10 @@ const MAX_CONSOLE_ARGS = 10;
 const MAX_CONSOLE_STACK_LENGTH = 2000;
 const MAX_CONSOLE_SERIALIZE_DEPTH = 4;
 const MAX_CONSOLE_SERIALIZE_ENTRIES = 20;
+/** Default cap (chars) for a captured 5xx response-body snippet. */
+const DEFAULT_MAX_ERROR_BODY_LENGTH = 2048;
+/** Hard timeout for the async response-body read; emit without body past this. */
+const ERROR_BODY_READ_TIMEOUT_MS = 1500;
 
 /**
  * Re-entrancy guard: true while the recorder itself is emitting custom events
@@ -644,10 +661,12 @@ function normalizeOptions(
 
 /**
  * Console/network capture default to ON whenever session replay records;
- * `false` disables a category, an object form overrides its caps.
+ * `false` disables a category, an object form overrides its caps. Network
+ * options may additionally carry `captureErrorBodies`/`maxErrorBodyLength`;
+ * console ignores those fields.
  */
 function normalizeCaptureToggle(
-  value: boolean | { maxEvents?: number } | undefined,
+  value: boolean | SessionReplayNetworkOptions | undefined,
   defaultMaxEvents: number,
 ): NormalizedCaptureOptions | null {
   if (value === false) return null;
@@ -657,7 +676,16 @@ function normalizeCaptureToggle(
     Number.isFinite(overrides.maxEvents)
       ? Math.max(1, Math.floor(overrides.maxEvents))
       : defaultMaxEvents;
-  return { maxEvents };
+  const maxErrorBodyLength =
+    typeof overrides.maxErrorBodyLength === "number" &&
+    Number.isFinite(overrides.maxErrorBodyLength)
+      ? Math.max(0, Math.floor(overrides.maxErrorBodyLength))
+      : DEFAULT_MAX_ERROR_BODY_LENGTH;
+  return {
+    maxEvents,
+    captureErrorBodies: overrides.captureErrorBodies !== false,
+    maxErrorBodyLength,
+  };
 }
 
 function scrubStringValue(key: string, value: string): string {
@@ -1507,6 +1535,36 @@ function isCaptureExcludedUrl(rawUrl: string, ingestEndpoint: string): boolean {
   return false;
 }
 
+/**
+ * Best-effort, synchronous read of a 5xx XHR response body, sliced to `cap`
+ * before redaction runs (caller redacts). Only reads `responseText` when
+ * `responseType` is "" or "text" -- other response types are read via
+ * `JSON.stringify` (guarded) for `"json"`, and skipped entirely otherwise
+ * since arbitrary binary/blob/arraybuffer bodies are not useful error text.
+ */
+function readXhrErrorBody(
+  xhr: XMLHttpRequest,
+  cap: number,
+): string | undefined {
+  try {
+    const responseType = xhr.responseType;
+    if (responseType === "" || responseType === "text") {
+      const text = xhr.responseText;
+      return typeof text === "string" ? text.slice(0, cap) : undefined;
+    }
+    if (responseType === "json") {
+      try {
+        return JSON.stringify(xhr.response)?.slice(0, cap);
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function installNetworkCapture(
   state: SessionReplayState,
   captureOptions: NormalizedCaptureOptions,
@@ -1531,6 +1589,11 @@ function installNetworkCapture(
     emitReplayCustomEvent(state, SESSION_REPLAY_NETWORK_EVENT_TAG, payload);
   };
 
+  const errorBodyCap =
+    captureOptions.captureErrorBodies !== false
+      ? (captureOptions.maxErrorBodyLength ?? DEFAULT_MAX_ERROR_BODY_LENGTH)
+      : null;
+
   const recordRequest = (
     api: "fetch" | "xhr",
     method: string,
@@ -1539,6 +1602,7 @@ function installNetworkCapture(
     ok: boolean,
     durationMs: number,
     error?: string,
+    responseBody?: string,
   ) => {
     if (stopped) return;
     try {
@@ -1560,12 +1624,58 @@ function installNetworkCapture(
               ),
             }
           : {}),
+        ...(responseBody
+          ? {
+              responseBody: truncateCaptureText(
+                redactCaptureText(responseBody),
+                errorBodyCap ?? DEFAULT_MAX_ERROR_BODY_LENGTH,
+              ),
+            }
+          : {}),
       });
     } catch {
       // capture must never break the host page
     }
   };
 
+  /**
+   * Best-effort bounded read of a 5xx response body. Reads a decoded stream
+   * up to `cap` chars and cancels the reader, or falls back to `.text()`
+   * sliced to `cap` when no readable stream is exposed. Never throws --
+   * opaque/no-body responses (or any read failure) resolve to undefined.
+   */
+  const readBoundedErrorBody = async (
+    response: Response,
+    cap: number,
+  ): Promise<string | undefined> => {
+    try {
+      const reader = response.body?.getReader?.();
+      if (reader) {
+        const decoder = new TextDecoder();
+        let text = "";
+        while (text.length < cap) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (value) text += decoder.decode(value, { stream: true });
+        }
+        // Fire-and-forget: cancelling an already-exhausted (or still-open but
+        // no-longer-wanted) reader can hang indefinitely on some stream
+        // implementations. We never need the result, so don't await it --
+        // that would defeat the whole point of bounding this read.
+        try {
+          reader.cancel().catch(() => {});
+        } catch {
+          // best-effort; some readers throw synchronously instead
+        }
+        return text.slice(0, cap);
+      }
+      const text = await response.text();
+      return text.slice(0, cap);
+    } catch {
+      return undefined;
+    }
+  };
+
   const restores: Array<() => void> = [];
 
   if (typeof window.fetch === "function") {
@@ -1593,8 +1703,10 @@ function installNetworkCapture(
         return originalFetch.call(self, input as RequestInfo | URL, init);
       }
       const startedAt = performance.now();
-      // Call the original exactly as the page did; never read bodies, never
-      // replace the response, propagate rejections untouched.
+      // Call the original exactly as the page did; never read the caller's
+      // response before returning it, never replace the response, propagate
+      // rejections untouched. A 5xx body snippet (if any) is read from a
+      // clone and emitted from a detached promise chain afterward.
       const result = originalFetch.call(self, input as RequestInfo | URL, init);
       if (!result || typeof (result as Promise<Response>).then !== "function") {
         return result;
@@ -1602,14 +1714,62 @@ function installNetworkCapture(
       return result.then(
         (response) => {
           try {
-            recordRequest(
-              "fetch",
-              method,
-              url,
-              response.status,
-              response.ok,
-              performance.now() - startedAt,
-            );
+            const durationMs = performance.now() - startedAt;
+            if (errorBodyCap !== null && response.status >= 500) {
+              // Clone immediately -- before any other code (including this
+              // handler returning) can consume the original body -- so the
+              // clone's stream is guaranteed unconsumed.
+              let clone: Response | null = null;
+              try {
+                clone = response.clone();
+              } catch {
+                clone = null;
+              }
+              if (clone) {
+                const bodyPromise = readBoundedErrorBody(clone, errorBodyCap);
+                const timeoutPromise = new Promise<undefined>((resolve) => {
+                  setTimeout(
+                    () => resolve(undefined),
+                    ERROR_BODY_READ_TIMEOUT_MS,
+                  );
+                });
+                // Detached chain: never rejects, never awaited by the caller.
+                Promise.race([bodyPromise, timeoutPromise])
+                  .then((responseBody) => {
+                    recordRequest(
+                      "fetch",
+                      method,
+                      url,
+                      response.status,
+                      response.ok,
+                      durationMs,
+                      undefined,
+                      responseBody,
+                    );
+                  })
+                  .catch(() => {
+                    // never affect the caller
+                  });
+              } else {
+                recordRequest(
+                  "fetch",
+                  method,
+                  url,
+                  response.status,
+                  response.ok,
+                  durationMs,
+                );
+              }
+            } else {
+              recordRequest(
+                "fetch",
+                method,
+                url,
+                response.status,
+                response.ok,
+                durationMs,
+              );
+            }
           } catch {
             // never affect the caller
           }
@@ -1700,14 +1860,20 @@ function installNetworkCapture(
             "loadend",
             () => {
               const status = typeof this.status === "number" ? this.status : 0;
+              const effectiveStatus = errorMessage ? 0 : status;
+              let responseBody: string | undefined;
+              if (errorBodyCap !== null && !errorMessage && status >= 500) {
+                responseBody = readXhrErrorBody(this, errorBodyCap);
+              }
               recordRequest(
                 "xhr",
                 info.method,
                 info.url,
-                errorMessage ? 0 : status,
+                effectiveStatus,
                 !errorMessage && status >= 200 && status < 300,
                 performance.now() - startedAt,
                 errorMessage,
+                responseBody,
               );
               xhrInfo.delete(this);
             },