Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): replace honors atomic-overwrite (PRD-6667) (#1270)

Nick Gomeze5e21520cb2e
diff --git a/.changeset/agent-write-divergence-recovery.md b/.changeset/agent-write-divergence-recovery.md
new file mode 100644
index 000000000..bf2f0db86
--- /dev/null
+++ b/.changeset/agent-write-divergence-recovery.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Agent-write content-divergence warnings now carry the converged document inline so an agent recovers without a second read. `structuredContent.contentDivergence` gains `currentState` (`{kind:"inline", content}`, or `{kind:"truncated", byteLength, hint}` over a 50 KB soft cap) plus a coarse `divergenceType`. The Site A gate is extracted to a shared predicate and extended to `version({ action: "rollback" })`. Divergence is now rate-measurable via the `ok.agent_write.gate_fired_total` / `ok.agent_write.content_divergence_total` counters (bounded `{handler}` label). Adds a production-Electron `agent-patch-divergence-probe` smoke test as permanent regression coverage.
diff --git a/.changeset/fix-write-document-replace-atomic.md b/.changeset/fix-write-document-replace-atomic.md
new file mode 100644
index 000000000..4c7e32767
--- /dev/null
+++ b/.changeset/fix-write-document-replace-atomic.md
@@ -0,0 +1,9 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix `write_document({ position: "replace" })`: the call now performs an atomic overwrite at the CRDT layer. Previously when an agent's payload shared substrings with the existing content, only the differing characters were written (a DMP-incremental merge), and concurrent human typing could combine with the result into a hybrid document. The case now routes through the same atomic primitive `version({ action: "rollback" })` already uses, which deletes the prior bytes wholesale before inserting the new payload.
+
+`append`, `prepend`, and `edit_document` find/replace are unchanged — they keep the item-preserving incremental primitive. (`edit_document` routes through an internal `patch` position so a surgical find/replace produces a minimal CRDT delta rather than a whole-document overwrite, which keeps a concurrent human's edits outside the matched span intact.)
+
+PRD-6667.
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index b0ea62d9c..33a356207 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -468,6 +468,10 @@ export {
ClientLogsSuccessSchema,
ConflictEntrySchema,
type ConflictEntryWire,
+ type ContentDivergenceCurrentState,
+ ContentDivergenceCurrentStateSchema,
+ type ContentDivergenceWarning,
+ ContentDivergenceWarningSchema,
type CreateFolderRequest,
CreateFolderRequestSchema,
type CreateFolderSuccess,
diff --git a/packages/core/src/schemas/api/agent-write.ts b/packages/core/src/schemas/api/agent-write.ts
index 60242219c..c09aba6a9 100644
--- a/packages/core/src/schemas/api/agent-write.ts
+++ b/packages/core/src/schemas/api/agent-write.ts
@@ -57,6 +57,29 @@ export const SummaryResponseFieldSchema = z
.loose() satisfies StandardSchemaV1;
export type SummaryResponseField = z.infer<typeof SummaryResponseFieldSchema>;
+export const ContentDivergenceCurrentStateSchema = z.discriminatedUnion('kind', [
+ z.object({ kind: z.literal('inline'), content: z.string() }),
+ z.object({
+ kind: z.literal('truncated'),
+ byteLength: z.number().int().nonnegative(),
+ hint: z.string(),
+ }),
+]);
+export type ContentDivergenceCurrentState = z.infer<typeof ContentDivergenceCurrentStateSchema>;
+
+export const ContentDivergenceWarningSchema = z
+ .object({
+ kind: z.literal('content-divergence'),
+ intendedBytes: z.number().int().nonnegative(),
+ actualBytes: z.number().int().nonnegative(),
+ byteDelta: z.number().int(),
+ divergenceType: z.string().optional(),
+ currentState: ContentDivergenceCurrentStateSchema.optional(),
+ hint: z.string().optional(),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type ContentDivergenceWarning = z.infer<typeof ContentDivergenceWarningSchema>;
+
export const OrphanHintSchema = z
.object({
type: z.literal('orphan'),
@@ -81,6 +104,7 @@ export const AgentWriteMdSuccessSchema = z
systemSubscriberCount: z.number().int().nonnegative(),
hints: z.array(OrphanHintSchema).optional(),
summary: SummaryResponseFieldSchema.optional(),
+ warning: ContentDivergenceWarningSchema.optional(),
})
.loose() satisfies StandardSchemaV1;
export type AgentWriteMdSuccess = z.infer<typeof AgentWriteMdSuccessSchema>;
@@ -91,6 +115,7 @@ export const AgentPatchSuccessSchema = z
subscriberCount: z.number().int().nonnegative(),
systemSubscriberCount: z.number().int().nonnegative(),
summary: SummaryResponseFieldSchema.optional(),
+ warning: ContentDivergenceWarningSchema.optional(),
})
.loose() satisfies StandardSchemaV1;
export type AgentPatchSuccess = z.infer<typeof AgentPatchSuccessSchema>;
diff --git a/packages/core/src/schemas/api/pages.ts b/packages/core/src/schemas/api/pages.ts
index 1588e5d4f..4f92abed8 100644
--- a/packages/core/src/schemas/api/pages.ts
+++ b/packages/core/src/schemas/api/pages.ts
@@ -1,7 +1,7 @@
import type { StandardSchemaV1 } from '@standard-schema/spec';
import { z } from 'zod';
import { agentIdentityFields, requiredSafeDocNameField, summaryField } from './_shared.ts';
-import { SummaryResponseFieldSchema } from './agent-write.ts';
+import { ContentDivergenceWarningSchema, SummaryResponseFieldSchema } from './agent-write.ts';
export const RenamedDocMappingSchema = z
.object({
@@ -207,6 +207,7 @@ export const RollbackSuccessSchema = z
restoredFrom: z.string().min(1),
timestamp: z.string().min(1),
summary: SummaryResponseFieldSchema.optional(),
+ warning: ContentDivergenceWarningSchema.optional(),
})
.loose() satisfies StandardSchemaV1;
export type RollbackSuccess = z.infer<typeof RollbackSuccessSchema>;
diff --git a/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts b/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
new file mode 100644
index 000000000..990ba2aef
--- /dev/null
+++ b/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
@@ -0,0 +1,420 @@
+import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { type ElectronApplication, _electron as electron } from '@playwright/test';
+import { expect, test } from './_helpers/smoke-test';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAIN_ENTRY = resolve(__dirname, '..', '..', 'out', 'main', 'index.js');
+const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';
+const DARWIN = process.platform === 'darwin';
+
+const YDOC_SETTLE_BUDGET_MS = 15_000;
+const YDOC_POLL_INTERVAL_MS = 250;
+
+type Variant = 'same-para' | 'diff-para' | 'mark-overlap' | 'burst' | 'randomized';
+
+interface ProbeOutcome {
+ variant: Variant;
+ trials: number;
+ httpStatusCodes: number[];
+ finalContents: string[];
+ cherryPresent: boolean[];
+ bananaAbsent: boolean[];
+ humanXCount: number[];
+ raceFired: boolean[]; // 200 OK + agent's CHERRY missing in post-settle Y.Doc
+}
+
+interface ApiPort {
+ port: number;
+}
+
+async function detectApiPort(userDataDir: string): Promise<ApiPort> {
+ const userDataBasename = userDataDir.split('/').pop() ?? userDataDir;
+ const psOut = execSync('ps -axww -o command 2>/dev/null', { encoding: 'utf-8' });
+ const line = psOut
+ .split('\n')
+ .find((l) => l.includes(userDataBasename) && l.includes('ok-api-origin='));
+ const m = line?.match(/ok-api-origin=http:\/\/localhost:(\d+)/);
+ if (!m) {
+ throw new Error(
+ `Could not auto-detect API port via renderer argv (userDataBasename=${userDataBasename})`,
+ );
+ }
+ return { port: Number(m[1]) };
+}
+
+async function fetchYDocContent(port: number, docName: string): Promise<string> {
+ const r = await fetch(
+ `http://localhost:${port}/api/document?docName=${encodeURIComponent(docName)}`,
+ ).catch(() => null);
+ if (!r) return '';
+ const j = (await r.json().catch(() => ({}))) as { content?: string };
+ return j.content ?? '';
+}
+
+interface RaceResult {
+ httpStatus: number;
+ finalContent: string;
+ cherryPresent: boolean;
+ bananaAbsent: boolean;
+ humanXCount: number;
+ raceFired: boolean;
+}
+
+async function executeRace(opts: {
+ page: import('@playwright/test').Page;
+ port: number;
+ docName: string;
+ variant: Variant;
+ trial: number;
+ randomizedStaggerMs?: number;
+}): Promise<RaceResult> {
+ const { page, port, docName, variant, trial, randomizedStaggerMs } = opts;
+
+ const seedContent =
+ '# Probe\n\nBANANA is here in the first paragraph.\n\nSecond paragraph for diff-para variant.\n';
+ const seedRes = await fetch(`http://localhost:${port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName,
+ markdown: seedContent,
+ position: 'replace',
+ agentId: `probe-seed`,
+ agentName: 'probe-seed',
+ }),
+ });
+ if (!seedRes.ok) {
+ throw new Error(`Seed write failed: ${seedRes.status} ${await seedRes.text()}`);
+ }
+
+ await expect(page.locator('.ProseMirror')).toContainText('BANANA is here', {
+ timeout: 10_000,
+ });
+ await wait(150);
+
+ let targetPara: import('@playwright/test').Locator;
+ if (variant === 'diff-para') {
+ targetPara = page.locator('.ProseMirror p').filter({ hasText: 'Second paragraph' });
+ } else {
+ targetPara = page.locator('.ProseMirror p').filter({ hasText: 'BANANA' });
+ }
+ await targetPara.click();
+ await page.keyboard.press('End');
+
+ if (variant === 'mark-overlap') {
+ for (let i = 0; i < 16; i++) {
+ await page.keyboard.press('Shift+ArrowLeft');
+ }
+ await page.keyboard.press('Meta+B');
+ await page.keyboard.press('End');
+ await wait(150);
+ }
+
+ const humanText = 'XXXXXXXX';
+ const typingDelay = variant === 'burst' ? 0 : 5;
+
+ const agentPatchPromise = (): Promise<Response> =>
+ fetch(`http://localhost:${port}/api/agent-patch`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ docName,
+ find: 'BANANA',
+ replace: 'CHERRY',
+ agentId: trial < 5 ? `probe-${variant}-${trial}` : `probe-${variant}-pool-${trial % 5}`,
+ agentName: 'probe',
+ }),
+ });
+ let httpStatus: number;
+ if (randomizedStaggerMs !== undefined && randomizedStaggerMs > 0) {
+ const firstHalf = humanText.slice(0, 4);
+ const secondHalf = humanText.slice(4);
+ await page.keyboard.type(firstHalf, { delay: typingDelay });
+ await wait(randomizedStaggerMs);
+ const [agentRes] = await Promise.all([
+ agentPatchPromise(),
+ page.keyboard.type(secondHalf, { delay: typingDelay }),
+ ]);
+ httpStatus = agentRes.status;
+ } else {
+ const [agentRes] = await Promise.all([
+ agentPatchPromise(),
+ page.keyboard.type(humanText, { delay: typingDelay }),
+ ]);
+ httpStatus = agentRes.status;
+ }
+
+ let finalContent = '';
+ let cherryPresent = false;
+ let bananaAbsent = false;
+ let humanXCount = 0;
+ const deadline = Date.now() + YDOC_SETTLE_BUDGET_MS;
+ while (Date.now() < deadline) {
+ finalContent = await fetchYDocContent(port, docName);
+ cherryPresent = finalContent.includes('CHERRY');
+ bananaAbsent = !finalContent.includes('BANANA');
+ humanXCount = (finalContent.match(/X/g) ?? []).length;
+ if (cherryPresent && bananaAbsent && humanXCount >= 4) break;
+ await wait(YDOC_POLL_INTERVAL_MS);
+ }
+
+ const raceFired = httpStatus === 200 && !cherryPresent;
+ return {
+ httpStatus,
+ finalContent,
+ cherryPresent,
+ bananaAbsent,
+ humanXCount,
+ raceFired,
+ };
+}
+
+async function setupElectron(
+ variantTag: string,
+ captureStderrFor: (app: ElectronApplication) => void,
+): Promise<{
+ app: ElectronApplication;
+ page: import('@playwright/test').Page;
+ port: number;
+ docName: string;
+ contentDir: string;
+ userDataDir: string;
+}> {
+ test.skip(!SMOKE_ENABLED, 'Set OK_DESKTOP_E2E_SMOKE=1 to run Electron smoke tests.');
+ test.skip(!DARWIN, 'Driver uses macOS open(1).');
+ test.skip(!existsSync(MAIN_ENTRY), `out/main/index.js missing — run \`bun run build:desktop\`.`);
+
+ const contentDir = mkdtempSync(join(tmpdir(), `ok-agent-patch-probe-${variantTag}-`));
+ const userDataDir = mkdtempSync(join(tmpdir(), `ok-pw-userdata-${variantTag}-`));
+ const docName = `probe-${variantTag}-${randomUUID().slice(0, 8)}`;
+ const initialContent =
+ '# Probe\n\nBANANA is here in the first paragraph.\n\nSecond paragraph for diff-para variant.\n';
+
+ mkdirSync(join(contentDir, '.ok'), { recursive: true });
+ writeFileSync(join(contentDir, '.ok', 'config.yml'), 'content:\n dir: .\n');
+ writeFileSync(join(contentDir, `${docName}.md`), initialContent);
+
+ const deepLink = `openknowledge://open?project=${encodeURIComponent(contentDir)}&doc=${encodeURIComponent(docName)}`;
+
+ const app = await electron.launch({
+ args: [MAIN_ENTRY, `--user-data-dir=${userDataDir}`, deepLink],
+ env: { ...process.env, NODE_ENV: 'production' },
+ timeout: 30_000,
+ });
+ captureStderrFor(app);
+
+ const expectedHashSuffix = `#/${docName}`;
+ let page: import('@playwright/test').Page | undefined;
+ await expect(async () => {
+ for (const w of app.windows()) {
+ const hash = await w.evaluate(() => window.location.hash).catch(() => '');
+ if (hash.endsWith(expectedHashSuffix)) {
+ page = w;
+ return;
+ }
+ }
+ throw new Error('editor window not yet open');
+ }).toPass({ timeout: 30_000 });
+ if (!page) throw new Error('editor page not found');
+ await page.waitForLoadState('domcontentloaded');
+ await expect(page.locator('.ProseMirror')).toContainText('BANANA', { timeout: 30_000 });
+
+ const { port } = await detectApiPort(userDataDir);
+
+ const beforeContent = await fetchYDocContent(port, docName);
+ console.log(
+ `[PROBE ${variantTag}] BEFORE — server Y.Doc len=${beforeContent.length}, includes BANANA=${beforeContent.includes('BANANA')}`,
+ );
+ expect(beforeContent).toContain('BANANA');
+
+ return { app, page, port, docName, contentDir, userDataDir };
+}
+
+test.describe('PRD-6666 — agent-patch divergence (production-built Electron)', () => {
+ test('Variant A — human types in SAME paragraph as agent find target', async ({
+ captureStderrFor,
+ }) => {
+ test.setTimeout(120_000);
+ const { page, port, docName } = await setupElectron('A', captureStderrFor);
+
+ const result = await executeRace({
+ page,
+ port,
+ docName,
+ variant: 'same-para',
+ trial: 0,
+ });
+ console.log('[PROBE A] result:', {
+ httpStatus: result.httpStatus,
+ cherryPresent: result.cherryPresent,
+ bananaAbsent: result.bananaAbsent,
+ humanXCount: result.humanXCount,
+ raceFired: result.raceFired,
+ finalLen: result.finalContent.length,
+ preview: result.finalContent.slice(0, 200),
+ });
+
+ expect(result.httpStatus).toBe(200);
+ expect(result.cherryPresent).toBe(true);
+ expect(result.bananaAbsent).toBe(true);
+ expect(result.humanXCount).toBeGreaterThanOrEqual(4);
+ expect(result.raceFired).toBe(false);
+ });
+
+ test('Variant B — human types in DIFFERENT paragraph (negative control)', async ({
+ captureStderrFor,
+ }) => {
+ test.setTimeout(120_000);
+ const { page, port, docName } = await setupElectron('B', captureStderrFor);
+
+ const result = await executeRace({
+ page,
+ port,
+ docName,
+ variant: 'diff-para',
+ trial: 0,
+ });
+ console.log('[PROBE B] result:', {
+ httpStatus: result.httpStatus,
+ cherryPresent: result.cherryPresent,
+ bananaAbsent: result.bananaAbsent,
+ humanXCount: result.humanXCount,
+ raceFired: result.raceFired,
+ finalLen: result.finalContent.length,
+ preview: result.finalContent.slice(0, 200),
+ });
+
+ expect(result.httpStatus).toBe(200);
+ expect(result.cherryPresent).toBe(true);
+ expect(result.bananaAbsent).toBe(true);
+ expect(result.humanXCount).toBeGreaterThanOrEqual(4);
+ expect(result.raceFired).toBe(false);
+ });
+
+ test('Variant C — human applies BOLD mark overlapping agent find region', async ({
+ captureStderrFor,
+ }) => {
+ test.setTimeout(120_000);
+ const { page, port, docName } = await setupElectron('C', captureStderrFor);
+
+ const result = await executeRace({
+ page,
+ port,
+ docName,
+ variant: 'mark-overlap',
+ trial: 0,
+ });
+ console.log('[PROBE C] result:', {
+ httpStatus: result.httpStatus,
+ cherryPresent: result.cherryPresent,
+ bananaAbsent: result.bananaAbsent,
+ humanXCount: result.humanXCount,
+ raceFired: result.raceFired,
+ finalLen: result.finalContent.length,
+ preview: result.finalContent.slice(0, 200),
+ });
+
+ expect(result.httpStatus).toBe(200);
+ expect(result.cherryPresent).toBe(true);
+ expect(result.bananaAbsent).toBe(true);
+ expect(result.humanXCount).toBeGreaterThanOrEqual(4);
+ expect(result.raceFired).toBe(false);
+ });
+
+ test('Variant D — BURST typing (no keystroke delay) races agent-patch', async ({
+ captureStderrFor,
+ }) => {
+ test.setTimeout(120_000);
+ const { page, port, docName } = await setupElectron('D', captureStderrFor);
+
+ const result = await executeRace({
+ page,
+ port,
+ docName,
+ variant: 'burst',
+ trial: 0,
+ });
+ console.log('[PROBE D] result:', {
+ httpStatus: result.httpStatus,
+ cherryPresent: result.cherryPresent,
+ bananaAbsent: result.bananaAbsent,
+ humanXCount: result.humanXCount,
+ raceFired: result.raceFired,
+ finalLen: result.finalContent.length,
+ preview: result.finalContent.slice(0, 200),
+ });
+
+ expect(result.httpStatus).toBe(200);
+ expect(result.cherryPresent).toBe(true);
+ expect(result.bananaAbsent).toBe(true);
+ expect(result.humanXCount).toBeGreaterThanOrEqual(4);
+ expect(result.raceFired).toBe(false);
+ });
+
+ test('Variant E — 100-trial randomized stagger race (same-paragraph)', async ({
+ captureStderrFor,
+ }) => {
+ test.setTimeout(15 * 60_000);
+ const { page, port, docName } = await setupElectron('E', captureStderrFor);
+
+ const TRIALS = process.env.CI ? 25 : 100;
+ const outcomes: ProbeOutcome = {
+ variant: 'randomized',
+ trials: TRIALS,
+ httpStatusCodes: [],
+ finalContents: [],
+ cherryPresent: [],
+ bananaAbsent: [],
+ humanXCount: [],
+ raceFired: [],
+ };
+ for (let trial = 0; trial < TRIALS; trial++) {
+ const stagger = Math.floor(Math.random() * 10);
+ const result = await executeRace({
+ page,
+ port,
+ docName,
+ variant: 'same-para',
+ trial,
+ randomizedStaggerMs: stagger,
+ });
+ outcomes.httpStatusCodes.push(result.httpStatus);
+ outcomes.finalContents.push(result.finalContent);
+ outcomes.cherryPresent.push(result.cherryPresent);
+ outcomes.bananaAbsent.push(result.bananaAbsent);
+ outcomes.humanXCount.push(result.humanXCount);
+ outcomes.raceFired.push(result.raceFired);
+
+ if (result.raceFired) {
+ console.log(`[PROBE E trial ${trial}] RACE FIRED — stagger=${stagger}ms:`, {
+ httpStatus: result.httpStatus,
+ finalContent: result.finalContent,
+ });
+ break;
+ }
+ if ((trial + 1) % 10 === 0) {
+ console.log(`[PROBE E] ${trial + 1}/${TRIALS} trials complete; no race fired so far.`);
+ }
+ }
+
+ const raceCount = outcomes.raceFired.filter(Boolean).length;
+ const cherryMissedCount = outcomes.cherryPresent.filter((c) => !c).length;
+ const bananaPresentCount = outcomes.bananaAbsent.filter((a) => !a).length;
+ console.log('[PROBE E] aggregate:', {
+ totalTrials: outcomes.raceFired.length,
+ raceFiredCount: raceCount,
+ cherryMissedCount,
+ bananaPresentCount,
+ });
+
+ expect(raceCount).toBe(0);
+ expect(cherryMissedCount).toBe(0);
+ expect(bananaPresentCount).toBe(0);
+ });
+});
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index e8e259c04..9a610a218 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -102,6 +102,8 @@ Call `write_document` / `edit_document` as soon as you have content. Native `Edi
**Pass a `summary` on every content write (SHOULD).** `write_document`, `edit_document`, and `edit_frontmatter` each take a one-line `summary` (≤80 chars) describing the user-facing outcome of the change — "Add gear list and permit info", not "edited trip doc". It renders as a bullet under your name in the document timeline and is the only human-readable change-note persisted to the shadow-repo history; omit it and the timeline shows *that* you wrote but not *what changed*. Write it from the reader's perspective, keep it specific, and avoid secrets or PII (it lands in git history). Each entry in the batch `docs:` form carries its own `summary`.
+**Content-divergence warning (Site A gate).** `write_document` and `edit_document` responses may include a content-divergence warning when the converged Y.Text doesn't match the bytes the payload composed to (concurrent peer left residue, or — rare — a primitive regression). The write still landed; on this signal, re-read the doc (`exec("cat <path>")`) to see what actually converged before continuing. Single-doc shape: `structuredContent.contentDivergence = { kind: "content-divergence", intendedBytes, actualBytes, byteDelta, hint }`. Batch shape: per-doc `structuredContent.documents[].contentDivergence` with the same fields. Distinct from the preview-attach `warning` field (`action: "attach-preview-once" | "start-ui"`) — separate keys, can coexist.
+
To author an MDX doc (the KB renders MDX/JSX components), pass a `.mdx` `docName` on the create: `write_document({ docName: "guides/widget.mdx", markdown, position: "replace" })` lands `guides/widget.mdx`. A `.md` or extension-less `docName` lands `.md`. An existing doc keeps its on-disk extension regardless of the suffix you pass — changing it in place isn't available via the MCP today.
To delete a doc, call `delete_document` — never `rm` / `unlink` / native `Bash` removal on in-scope markdown. The MCP path closes open agent sessions and unloads the doc from Hocuspocus before unlinking; native `rm` desynchronizes those. Deletion is irreversible — call `version({ action: "save" })` first if you may need to roll back (restore via `version({ action: "rollback" })`; list snapshots via `get_history`), and `links({ kind: "backlinks", docName })` first if you want to fix referrers that will become redlinks. To move or rename a doc instead of delete + rewrite, use `rename({ from, to })` — it auto-detects file vs folder and rewrites incoming references atomically.
diff --git a/packages/server/src/agent-patch-crdt-convergence.test.ts b/packages/server/src/agent-patch-crdt-convergence.test.ts
new file mode 100644
index 000000000..4b7e8cfbd
--- /dev/null
+++ b/packages/server/src/agent-patch-crdt-convergence.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test';
+import type { Document } from '@hocuspocus/server';
+import * as Y from 'yjs';
+import { AGENT_WRITE_ORIGIN, applyAgentMarkdownWrite } from './agent-sessions.ts';
+
+function asDocument(ydoc: Y.Doc, name = 'doc.md'): Document {
+ return {
+ name,
+ awareness: undefined,
+ getText: (n: string) => ydoc.getText(n),
+ getMap: (n: string) => ydoc.getMap(n),
+ getXmlFragment: (n: string) => ydoc.getXmlFragment(n),
+ transact: (fn: () => void, origin?: unknown) => ydoc.transact(fn, origin),
+ on: ydoc.on.bind(ydoc),
+ off: ydoc.off.bind(ydoc),
+ } as unknown as Document;
+}
+
+function exchangeUpdates(a: Y.Doc, b: Y.Doc): void {
+ const aState = Y.encodeStateVector(a);
+ const bState = Y.encodeStateVector(b);
+ const aDiff = Y.encodeStateAsUpdate(a, bState);
+ const bDiff = Y.encodeStateAsUpdate(b, aState);
+ Y.applyUpdate(b, aDiff);
+ Y.applyUpdate(a, bDiff);
+}
+
+function patchBody(current: string, find: string, replace: string): string {
+ const pos = current.indexOf(find);
+ if (pos === -1) throw new Error(`find not present: ${find}`);
+ return current.slice(0, pos) + replace + current.slice(pos + find.length);
+}
+
+const INITIAL = '# Doc\n\nIntro with the OLDWORD token.\n\nSecond para the peer cares about.\n';
+
+describe('applyAgentMarkdownWrite(patch) — CRDT-level convergence (edit_document item-preservation)', () => {
+ test('single-writer convergence: peer synced before patch, converged Y.Text equals patched body', () => {
+ const server = new Y.Doc();
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), INITIAL, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+
+ const peer = new Y.Doc();
+ Y.applyUpdate(peer, Y.encodeStateAsUpdate(server));
+ expect(peer.getText('source').toString()).toBe(INITIAL);
+
+ const patched = patchBody(INITIAL, 'OLDWORD', 'NEWWORD');
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), patched, 'patch');
+ }, AGENT_WRITE_ORIGIN);
+ expect(server.getText('source').toString()).toBe(patched);
+
+ exchangeUpdates(server, peer);
+ expect(server.getText('source').toString()).toBe(patched);
+ expect(peer.getText('source').toString()).toBe(patched);
+ });
+
+ test('concurrent peer edit outside the patched span survives item-preserved (woven in place)', () => {
+ const server = new Y.Doc();
+ const peer = new Y.Doc();
+
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), INITIAL, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+ Y.applyUpdate(peer, Y.encodeStateAsUpdate(server));
+ expect(peer.getText('source').toString()).toBe(INITIAL);
+
+ const peerMarker = 'PEER_TYPING ';
+ const peerInsertOffset = INITIAL.indexOf('cares about'); // before "cares"
+ for (let i = 0; i < peerMarker.length; i++) {
+ peer.getText('source').insert(peerInsertOffset + i, peerMarker.charAt(i));
+ }
+ expect(peer.getText('source').toString()).toContain('peer PEER_TYPING cares about');
+ expect(server.getText('source').toString()).toBe(INITIAL); // server hasn't seen it
+
+ const patched = patchBody(INITIAL, 'OLDWORD', 'NEWWORD');
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), patched, 'patch');
+ }, AGENT_WRITE_ORIGIN);
+ expect(server.getText('source').toString()).toBe(patched);
+
+ exchangeUpdates(server, peer);
+ const serverFinal = server.getText('source').toString();
+ const peerFinal = peer.getText('source').toString();
+
+ expect(serverFinal).toBe(peerFinal);
+ expect(serverFinal).toContain('NEWWORD');
+ expect(serverFinal).not.toContain('OLDWORD');
+ expect(serverFinal).toContain('PEER_TYPING');
+ expect(serverFinal).toContain('peer PEER_TYPING cares about');
+ });
+});
diff --git a/packages/server/src/agent-sessions.test.ts b/packages/server/src/agent-sessions.test.ts
index 91adc7ea3..57dc3ee4e 100644
--- a/packages/server/src/agent-sessions.test.ts
+++ b/packages/server/src/agent-sessions.test.ts
@@ -712,3 +712,193 @@ describe('conflict-aware write gate (FR9 a, d)', () => {
_resetDocExtensionsForTests();
});
});
+
+describe('applyAgentMarkdownWrite — position: "replace" atomic-overwrite contract (PRD-6667)', () => {
+ test('replace overwrites prior bytes atomically — full delete + full insert, not DMP-incremental merge', async () => {
+ const session = await manager.getSession('doc-replace-shape.md', 'agent-shape');
+ const ytext = session.dc.document.getText('source');
+
+ const seed = 'aaaa bbbb cccc\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, seed, 'replace');
+ }, session.origin);
+ expect(ytext.toString()).toBe(seed);
+
+ let insertCharCount = 0;
+ let deleteCharCount = 0;
+ const observer = (event: Y.YTextEvent): void => {
+ for (const change of event.changes.delta) {
+ if (change.insert && typeof change.insert === 'string') {
+ insertCharCount += change.insert.length;
+ }
+ if (change.delete) deleteCharCount += change.delete;
+ }
+ };
+ ytext.observe(observer);
+
+ const replacePayload = 'aaaa bbbb cccc and extra\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, replacePayload, 'replace');
+ }, session.origin);
+ ytext.unobserve(observer);
+
+ expect(insertCharCount).toBe(replacePayload.length);
+ expect(deleteCharCount).toBe(seed.length);
+ });
+
+ test("position 'patch' (edit_document) writes incrementally and clears on empty body (not a no-op)", async () => {
+ const session = await manager.getSession('doc-patch-incremental.md', 'agent-patch-inc');
+ const ytext = session.dc.document.getText('source');
+
+ const seed = 'aaaa bbbb cccc\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, seed, 'replace');
+ }, session.origin);
+ expect(ytext.toString()).toBe(seed);
+
+ let insertCharCount = 0;
+ let deleteCharCount = 0;
+ const observer = (event: Y.YTextEvent): void => {
+ for (const change of event.changes.delta) {
+ if (change.insert && typeof change.insert === 'string') {
+ insertCharCount += change.insert.length;
+ }
+ if (change.delete) deleteCharCount += change.delete;
+ }
+ };
+ ytext.observe(observer);
+ const patchedBody = 'aaaa XXXX cccc\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, patchedBody, 'patch');
+ }, session.origin);
+ ytext.unobserve(observer);
+
+ expect(ytext.toString()).toBe(patchedBody);
+ expect(deleteCharCount).toBeLessThan(seed.length);
+ expect(insertCharCount).toBeLessThan(patchedBody.length);
+
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, '', 'patch');
+ }, session.origin);
+ expect(ytext.toString()).toBe('');
+
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, 'restored\n', 'replace');
+ }, session.origin);
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, '', 'append');
+ }, session.origin);
+ expect(ytext.toString()).toBe('restored\n');
+ });
+
+ test('single-writer replace lands payload bytes verbatim in Y.Text', async () => {
+ const session = await manager.getSession('doc-replace-verbatim.md', 'agent-verbatim');
+ const ytext = session.dc.document.getText('source');
+
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, '# Heading\n\nOld body text.\n', 'replace');
+ }, session.origin);
+
+ const payload = '# Heading\n\nCompletely different body text.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, payload, 'replace');
+ }, session.origin);
+
+ expect(ytext.toString()).toBe(payload);
+ });
+
+ test('replace with FM in payload supersedes existing FM', async () => {
+ const session = await manager.getSession('doc-fm-payload.md', 'agent-fm-payload');
+ const ytext = session.dc.document.getText('source');
+
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, '---\ntitle: Old\n---\nOld body.\n', 'replace');
+ }, session.origin);
+ expect(ytext.toString()).toContain('title: Old');
+
+ const payload = '---\ntitle: New\n---\nNew body.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, payload, 'replace');
+ }, session.origin);
+
+ expect(ytext.toString()).toBe(payload);
+ expect(ytext.toString()).toContain('title: New');
+ expect(ytext.toString()).not.toContain('title: Old');
+ });
+
+ test('replace with body-only payload preserves existing FM', async () => {
+ const session = await manager.getSession('doc-fm-preserve.md', 'agent-fm-preserve');
+ const ytext = session.dc.document.getText('source');
+
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(
+ session.dc.document,
+ '---\ntitle: Existing\n---\nOriginal body.\n',
+ 'replace',
+ );
+ }, session.origin);
+
+ const bodyOnly = 'Body-only replacement, no FM.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, bodyOnly, 'replace');
+ }, session.origin);
+
+ expect(ytext.toString()).toContain('title: Existing');
+ expect(ytext.toString()).toContain('Body-only replacement, no FM.');
+ expect(ytext.toString()).not.toContain('Original body.');
+ });
+
+ test('replace with content identical to current state is a no-op (idempotent)', async () => {
+ const session = await manager.getSession('doc-idempotent.md', 'agent-idempotent');
+ const ytext = session.dc.document.getText('source');
+
+ const content = '# Heading\n\nBody paragraph.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, content, 'replace');
+ }, session.origin);
+
+ let mutationCount = 0;
+ const observer = (): void => {
+ mutationCount++;
+ };
+ ytext.observe(observer);
+
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, content, 'replace');
+ }, session.origin);
+ ytext.unobserve(observer);
+
+ expect(mutationCount).toBe(0);
+ expect(ytext.toString()).toBe(content);
+ });
+
+ test('returns undefined when ytext matches intent (Site A negative path)', async () => {
+ const session = await manager.getSession('doc-gate-negative.md', 'agent-gate-negative');
+ let divergence: unknown;
+ session.dc.document.transact(() => {
+ divergence = applyAgentMarkdownWrite(session.dc.document, '# Heading\n\nBody.\n', 'replace');
+ }, session.origin);
+ expect(divergence).toBeUndefined();
+ });
+
+ test('session.um.undo() after a replace restores prior bytes (one atomic UM frame)', async () => {
+ const session = await manager.getSession('doc-replace-undo.md', 'agent-replace-undo');
+ const ytext = session.dc.document.getText('source');
+
+ const seed = '# Seed Heading\n\nSeed body text.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, seed, 'replace');
+ }, session.origin);
+ session.um.stopCapturing();
+
+ const replacement = '# Replacement Heading\n\nDifferent body content.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, replacement, 'replace');
+ }, session.origin);
+ expect(ytext.toString()).toBe(replacement);
+
+ const undone = applyAgentUndo(session, 'last');
+ expect(undone).toBe(true);
+ expect(ytext.toString()).toBe(seed);
+ });
+});
diff --git a/packages/server/src/agent-sessions.ts b/packages/server/src/agent-sessions.ts
index a902b846a..8d22f847c 100644
--- a/packages/server/src/agent-sessions.ts
+++ b/packages/server/src/agent-sessions.ts
@@ -9,9 +9,17 @@ import {
export { colorFromSeed } from '@inkeep/open-knowledge-core';
import * as Y from 'yjs';
-import { composeAndWriteRawBody, deriveFragmentFromYtext } from './bridge-intake.ts';
+import {
+ composeAndWriteRawBody,
+ deriveFragmentFromYtext,
+ replaceRawBody,
+} from './bridge-intake.ts';
import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';
import { DocInConflictError, isDocInConflict } from './conflict-errors.ts';
+import {
+ type AgentWriteContentDivergence,
+ evaluateContentDivergence,
+} from './content-divergence-gate.ts';
import { getDocExtension, stripDocExtension } from './doc-extensions.ts';
import { FrontmatterMalformedError } from './frontmatter-malformed-error.ts';
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
@@ -19,6 +27,8 @@ import { getLogger } from './logger.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
+export type { AgentWriteContentDivergence };
+
const log = getLogger('agent-sessions');
export interface AgentDirectConnection extends DirectConnection {
@@ -41,16 +51,16 @@ function docNameToFile(docName: string): string {
export function applyAgentMarkdownWrite(
document: Document,
markdown: string,
- position: 'append' | 'prepend' | 'replace',
+ position: 'append' | 'prepend' | 'replace' | 'patch',
embedResolver?: {
resolveEmbed: (basename: string, sourcePath: string) => string | null;
sourcePath: string;
},
-): void {
+): AgentWriteContentDivergence | undefined {
if (isDocInConflict(document)) {
throw new DocInConflictError({ file: docNameToFile(document.name) });
}
- withSpanSync(
+ return withSpanSync(
'agent.applyAgentMarkdownWrite',
{
attributes: {
@@ -59,19 +69,31 @@ export function applyAgentMarkdownWrite(
'agent.markdown.bytes': markdown.length,
},
},
- () => applyAgentMarkdownWriteInner(document, markdown, position, embedResolver),
+ () => {
+ const divergence = applyAgentMarkdownWriteInner(document, markdown, position, embedResolver);
+ if (divergence !== undefined) {
+ setActiveSpanAttributes({
+ 'agent.content_divergent': true,
+ 'agent.intended_bytes': divergence.intendedBytes,
+ 'agent.actual_bytes': divergence.actualBytes,
+ 'agent.byte_delta': divergence.byteDelta,
+ 'agent.divergence_type': divergence.divergenceType,
+ });
+ }
+ return divergence;
+ },
);
}
function applyAgentMarkdownWriteInner(
document: Document,
markdown: string,
- position: 'append' | 'prepend' | 'replace',
+ position: 'append' | 'prepend' | 'replace' | 'patch',
embedResolver?: {
resolveEmbed: (basename: string, sourcePath: string) => string | null;
sourcePath: string;
},
-): void {
+): AgentWriteContentDivergence | undefined {
try {
const ytext = document.getText('source');
const currentYText = ytext.toString();
@@ -90,6 +112,10 @@ function applyAgentMarkdownWriteInner(
finalFm = payloadFm || existingFm;
newBody = payloadBody;
break;
+ case 'patch':
+ finalFm = payloadFm || existingFm;
+ newBody = payloadBody;
+ break;
case 'prepend':
finalFm = existingFm;
newBody =
@@ -118,7 +144,14 @@ function applyAgentMarkdownWriteInner(
}
const newContent = prependFrontmatter(finalFm, newBody);
- composeAndWriteRawBody(document, newContent, 'agent', embedResolver);
+ if (position === 'replace') {
+ replaceRawBody(document, newContent, embedResolver);
+ } else {
+ composeAndWriteRawBody(document, newContent, 'agent', embedResolver);
+ }
+
+ const actualYText = document.getText('source').toString();
+ return evaluateContentDivergence(actualYText, newContent, position);
} catch (err) {
if (!(err instanceof FrontmatterMalformedError)) {
log.error(
diff --git a/packages/server/src/agent-write-replace-crdt-convergence.test.ts b/packages/server/src/agent-write-replace-crdt-convergence.test.ts
new file mode 100644
index 000000000..da6d5ed30
--- /dev/null
+++ b/packages/server/src/agent-write-replace-crdt-convergence.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+import type { Document } from '@hocuspocus/server';
+import * as Y from 'yjs';
+import { AGENT_WRITE_ORIGIN, applyAgentMarkdownWrite } from './agent-sessions.ts';
+
+function asDocument(ydoc: Y.Doc, name = 'doc.md'): Document {
+ return {
+ name,
+ awareness: undefined,
+ getText: (n: string) => ydoc.getText(n),
+ getMap: (n: string) => ydoc.getMap(n),
+ getXmlFragment: (n: string) => ydoc.getXmlFragment(n),
+ transact: (fn: () => void, origin?: unknown) => ydoc.transact(fn, origin),
+ on: ydoc.on.bind(ydoc),
+ off: ydoc.off.bind(ydoc),
+ } as unknown as Document;
+}
+
+function exchangeUpdates(a: Y.Doc, b: Y.Doc): void {
+ const aState = Y.encodeStateVector(a);
+ const bState = Y.encodeStateVector(b);
+ const aDiff = Y.encodeStateAsUpdate(a, bState);
+ const bDiff = Y.encodeStateAsUpdate(b, aState);
+ Y.applyUpdate(b, aDiff);
+ Y.applyUpdate(a, bDiff);
+}
+
+describe('applyAgentMarkdownWrite(replace) — CRDT-level convergence (PRD-6667)', () => {
+ test('single-writer convergence: peer fully synced before replace, converged Y.Text equals agent payload', () => {
+ const server = new Y.Doc();
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), '# Initial\n\nInitial body.\n', 'replace');
+ }, AGENT_WRITE_ORIGIN);
+
+ const peer = new Y.Doc();
+ Y.applyUpdate(peer, Y.encodeStateAsUpdate(server));
+ expect(peer.getText('source').toString()).toBe('# Initial\n\nInitial body.\n');
+
+ const payload = '# Replaced\n\nCompletely new body content.\n';
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), payload, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+
+ expect(server.getText('source').toString()).toBe(payload);
+
+ exchangeUpdates(server, peer);
+ expect(server.getText('source').toString()).toBe(payload);
+ expect(peer.getText('source').toString()).toBe(payload);
+ });
+
+ test('concurrent peer typing during replace: agent payload survives as a contiguous substring (atomic primitive shape)', () => {
+ const server = new Y.Doc();
+ const peer = new Y.Doc();
+
+ const initial = '# Original\n\nOriginal body that the peer cares about.\n';
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), initial, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+ Y.applyUpdate(peer, Y.encodeStateAsUpdate(server));
+ expect(peer.getText('source').toString()).toBe(initial);
+
+ const peerInsertOffset = initial.length - 1; // before trailing '\n'
+ const peerText = ' PEER_TYPING';
+ for (let i = 0; i < peerText.length; i++) {
+ peer.getText('source').insert(peerInsertOffset + i, peerText.charAt(i));
+ }
+ expect(peer.getText('source').toString()).toContain('PEER_TYPING');
+ expect(server.getText('source').toString()).toBe(initial);
+
+ const agentPayload = '# Replaced By Agent\n\nAll original content should be gone.\n';
+ server.transact(() => {
+ applyAgentMarkdownWrite(asDocument(server), agentPayload, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+ expect(server.getText('source').toString()).toBe(agentPayload);
+
+ exchangeUpdates(server, peer);
+
+ const serverFinal = server.getText('source').toString();
+ const peerFinal = peer.getText('source').toString();
+
+ expect(serverFinal).toBe(peerFinal);
+
+ expect(serverFinal).toContain(agentPayload);
+ });
+});
diff --git a/packages/server/src/api-agent-patch.test.ts b/packages/server/src/api-agent-patch.test.ts
index 4662100ad..c371c46dd 100644
--- a/packages/server/src/api-agent-patch.test.ts
+++ b/packages/server/src/api-agent-patch.test.ts
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable } from 'node:stream';
import { Hocuspocus } from '@hocuspocus/server';
+import type * as Y from 'yjs';
import {
AGENT_WRITE_ORIGIN,
AgentSessionManager,
@@ -181,3 +182,59 @@ describe('POST /api/agent-patch', () => {
}
});
});
+
+describe('POST /api/agent-patch — surgical/incremental write shape', () => {
+ test('a small find/replace produces a minimal Y.Text delta, not a whole-doc overwrite', async () => {
+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-api-agent-patch-shape-'));
+ const contentDir = join(projectDir, 'content');
+ mkdirSync(contentDir, { recursive: true });
+
+ const hocuspocus = new Hocuspocus({ quiet: true });
+ const sessionManager = new AgentSessionManager(hocuspocus);
+
+ try {
+ const session = await sessionManager.getSession('test-doc');
+ const ytext = session.dc.document.getText('source');
+ const seed =
+ '# Heading\n\n' +
+ 'Alpha paragraph one with several words of filler content here.\n\n' +
+ 'Beta paragraph two with the TARGET token buried in the middle.\n\n' +
+ 'Gamma paragraph three with several more words of filler content here.\n';
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, seed, 'replace');
+ }, AGENT_WRITE_ORIGIN);
+ expect(ytext.toString()).toBe(seed);
+ const wholeDocLen = seed.length;
+
+ let insertCharCount = 0;
+ let deleteCharCount = 0;
+ const observer = (event: Y.YTextEvent): void => {
+ for (const change of event.changes.delta) {
+ if (change.insert && typeof change.insert === 'string') {
+ insertCharCount += change.insert.length;
+ }
+ if (change.delete) deleteCharCount += change.delete;
+ }
+ };
+ ytext.observe(observer);
+ const response = await callAgentPatch(hocuspocus, sessionManager, contentDir, {
+ docName: 'test-doc',
+ find: 'TARGET',
+ replace: 'REPLACED-TOKEN',
+ });
+ ytext.unobserve(observer);
+
+ expect(response.status).toBe(200);
+ expect(ytext.toString()).toBe(seed.replace('TARGET', 'REPLACED-TOKEN'));
+ const newDocLen = ytext.toString().length;
+
+ expect(deleteCharCount).toBeLessThan(wholeDocLen);
+ expect(insertCharCount).toBeLessThan(newDocLen);
+ expect(deleteCharCount).toBeLessThan(64);
+ expect(insertCharCount).toBeLessThan(64);
+ } finally {
+ await sessionManager.closeAll();
+ rmSync(projectDir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index eb95e3462..ce09e875f 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -185,6 +185,7 @@ import { type AgentPresenceBroadcaster, BROADCASTER_EVICTION_MS } from './agent-
import {
AgentSessionCapacityError,
type AgentSessionManager,
+ type AgentWriteContentDivergence,
applyAgentMarkdownWrite,
applyAgentUndo,
iconFromClientName,
@@ -208,6 +209,10 @@ import {
applyTemplateWrite,
type TemplateFrontmatter,
} from './content/templates-write.ts';
+import {
+ evaluateContentDivergence,
+ toContentDivergenceWarning,
+} from './content-divergence-gate.ts';
import { recordContributor } from './contributor-tracker.ts';
import { deriveDetection, embedProbeRing, recordEmbedProbe } from './embed-probe.ts';
import {
@@ -480,6 +485,51 @@ function renameAttributionCounter(): ReturnType<ReturnType<typeof getMeter>['cre
return _renameAttributionCounter;
}
+let _agentWriteGateFiredCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null =
+ null;
+function agentWriteGateFiredCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
+ if (!_agentWriteGateFiredCounter) {
+ _agentWriteGateFiredCounter = getMeter().createCounter('ok.agent_write.gate_fired_total', {
+ description:
+ 'Count of agent writes that ran the Site A content-divergence gate (denominator for the divergence rate). Bounded label: handler ∈ {agent-write-md, agent-patch, rollback}.',
+ });
+ }
+ return _agentWriteGateFiredCounter;
+}
+
+let _agentWriteContentDivergenceCounter: ReturnType<
+ ReturnType<typeof getMeter>['createCounter']
+> | null = null;
+function agentWriteContentDivergenceCounter(): ReturnType<
+ ReturnType<typeof getMeter>['createCounter']
+> {
+ if (!_agentWriteContentDivergenceCounter) {
+ _agentWriteContentDivergenceCounter = getMeter().createCounter(
+ 'ok.agent_write.content_divergence_total',
+ {
+ description:
+ 'Count of agent writes whose converged Y.Text diverged from the composed intent (numerator for the divergence rate). Bounded labels: handler ∈ {agent-write-md, agent-patch, rollback}, divergence_type.',
+ },
+ );
+ }
+ return _agentWriteContentDivergenceCounter;
+}
+
+type DivergenceHandler = 'agent-write-md' | 'agent-patch' | 'rollback';
+
+function recordContentDivergenceGate(
+ handler: DivergenceHandler,
+ divergence: AgentWriteContentDivergence | undefined,
+): void {
+ agentWriteGateFiredCounter().add(1, { handler });
+ if (divergence !== undefined) {
+ agentWriteContentDivergenceCounter().add(1, {
+ handler,
+ divergence_type: divergence.divergenceType,
+ });
+ }
+}
+
export function __resetRenameTelemetryForTesting(): void {
_renameAttributionCounter = null;
}
@@ -3054,6 +3104,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
});
const timestamp = new Date().toISOString();
+ let writeDivergence: AgentWriteContentDivergence | undefined;
+
try {
const icon = iconFromClientName(clientName);
const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
@@ -3067,7 +3119,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
});
captureEffect(session.dc.document.getText('source'), agentId, colorSeed, clientName);
session.dc.document.transact(() => {
- applyAgentMarkdownWrite(
+ writeDivergence = applyAgentMarkdownWrite(
session.dc.document,
body.markdown,
position,
@@ -3084,6 +3136,21 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
description: `Added (${agentName}): ${body.markdown.trim().slice(0, 50)}`,
});
}, session.origin);
+ if (writeDivergence !== undefined) {
+ console.warn(
+ JSON.stringify({
+ event: 'agent-write-content-divergence',
+ 'doc.name': resolvedDocName,
+ position,
+ intendedBytes: writeDivergence.intendedBytes,
+ actualBytes: writeDivergence.actualBytes,
+ byteDelta: writeDivergence.byteDelta,
+ 'agent.id': agentId,
+ 'agent.client_name': clientName,
+ }),
+ );
+ }
+ recordContentDivergenceGate('agent-write-md', writeDivergence);
recordContributor(
resolvedDocName,
agentId,
@@ -3137,6 +3204,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
systemSubscriberCount,
...(hints ? { hints } : {}),
...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(writeDivergence !== undefined
+ ? { warning: toContentDivergenceWarning(writeDivergence) }
+ : {}),
},
{ handler: 'agent-write-md' },
);
@@ -4227,6 +4297,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
let notFound = false;
let staleTarget = false;
let fmIntersect = false;
+ let patchDivergence: AgentWriteContentDivergence | undefined;
try {
const icon = iconFromClientName(clientName);
const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
@@ -4277,10 +4348,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const newFull =
currentFull.slice(0, pos) + replace + currentFull.slice(pos + find.length);
const { body: newBody } = stripFrontmatter(newFull);
- applyAgentMarkdownWrite(
+ patchDivergence = applyAgentMarkdownWrite(
session.dc.document,
newBody,
- 'replace',
+ 'patch',
options.resolveEmbed
? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
: undefined,
@@ -4294,6 +4365,20 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
description: `Patched (${agentName}): ${find.slice(0, 50)}`,
});
}, session.origin);
+ if (patchDivergence !== undefined) {
+ console.warn(
+ JSON.stringify({
+ event: 'agent-write-content-divergence',
+ 'doc.name': docName,
+ position: 'patch',
+ intendedBytes: patchDivergence.intendedBytes,
+ actualBytes: patchDivergence.actualBytes,
+ byteDelta: patchDivergence.byteDelta,
+ 'agent.id': agentId,
+ 'agent.client_name': clientName,
+ }),
+ );
+ }
if (!notFound && !staleTarget && !fmIntersect) {
const { stored: storedSummary } = summaryResponseFields(normalizedSummary);
recordContributor(
@@ -4307,6 +4392,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
);
incrementAgentWriteCalls();
countNormalizedSummary(normalizedSummary);
+ recordContentDivergenceGate('agent-patch', patchDivergence);
}
} finally {
agentPresenceBroadcaster?.touchMode(agentId, 'idle');
@@ -4377,6 +4463,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
subscriberCount,
systemSubscriberCount,
...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(patchDivergence !== undefined
+ ? { warning: toContentDivergenceWarning(patchDivergence) }
+ : {}),
},
{ handler: 'agent-patch' },
);
@@ -5307,9 +5396,32 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const rollbackEmbedResolver = options.resolveEmbed
? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
: undefined;
+ let rollbackDivergence: AgentWriteContentDivergence | undefined;
document.transact(() => {
replaceRawBody(document, markdown, rollbackEmbedResolver);
+ rollbackDivergence = evaluateContentDivergence(
+ document.getText('source').toString(),
+ markdown,
+ 'rollback',
+ );
}, ROLLBACK_ORIGIN);
+ if (rollbackDivergence !== undefined) {
+ console.warn(
+ JSON.stringify({
+ event: 'agent-write-content-divergence',
+ 'doc.name': docName,
+ position: 'rollback',
+ intendedBytes: rollbackDivergence.intendedBytes,
+ actualBytes: rollbackDivergence.actualBytes,
+ byteDelta: rollbackDivergence.byteDelta,
+ 'actor.kind': actor.kind,
+ ...(actor.kind === 'agent' || actor.kind === 'principal'
+ ? { 'actor.writer_id': actor.writerId }
+ : {}),
+ }),
+ );
+ }
+ recordContentDivergenceGate('rollback', rollbackDivergence);
let summaryResponse: SummaryResponse | undefined;
switch (actor.kind) {
@@ -5398,6 +5510,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
restoredFrom: commitSha,
timestamp,
...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(rollbackDivergence !== undefined
+ ? { warning: toContentDivergenceWarning(rollbackDivergence) }
+ : {}),
},
{ handler: 'rollback' },
);
diff --git a/packages/server/src/bridge-intake.ts b/packages/server/src/bridge-intake.ts
index 7f07af7a6..a5e70229e 100644
--- a/packages/server/src/bridge-intake.ts
+++ b/packages/server/src/bridge-intake.ts
@@ -78,21 +78,32 @@ export function replaceRawBody(
rawContent: string,
embedResolver?: EmbedResolverArg,
): void {
- const xmlFragment = document.getXmlFragment('default');
- const ytext = document.getText('source');
+ withSpanSync(
+ 'bridge.replaceRawBody',
+ {
+ attributes: {
+ 'body.bytes': rawContent.length,
+ 'doc.name': document.guid,
+ },
+ },
+ () => {
+ const xmlFragment = document.getXmlFragment('default');
+ const ytext = document.getText('source');
- const { body } = stripFrontmatter(rawContent);
- const parsedJson = mdManager.parseWithFallback(body, buildParseOpts(embedResolver));
- const pmNode = schema.nodeFromJSON(parsedJson);
+ const { body } = stripFrontmatter(rawContent);
+ const parsedJson = mdManager.parseWithFallback(body, buildParseOpts(embedResolver));
+ const pmNode = schema.nodeFromJSON(parsedJson);
- const currentText = ytext.toString();
- if (currentText !== rawContent) {
- ytext.delete(0, currentText.length);
- ytext.insert(0, rawContent);
- }
+ const currentText = ytext.toString();
+ if (currentText !== rawContent) {
+ ytext.delete(0, currentText.length);
+ ytext.insert(0, rawContent);
+ }
- const meta = { mapping: new Map(), isOMark: new Map() };
- updateYFragment(document, xmlFragment, pmNode, meta);
+ const meta = { mapping: new Map(), isOMark: new Map() };
+ updateYFragment(document, xmlFragment, pmNode, meta);
+ },
+ );
}
export function deriveFragmentFromYtext(document: Y.Doc, embedResolver?: EmbedResolverArg): void {
diff --git a/packages/server/src/content-divergence-gate.test.ts b/packages/server/src/content-divergence-gate.test.ts
new file mode 100644
index 000000000..8ef48fde6
--- /dev/null
+++ b/packages/server/src/content-divergence-gate.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test';
+import { ContentDivergenceWarningSchema } from '@inkeep/open-knowledge-core';
+import {
+ CONTENT_DIVERGENCE_CAP_BYTES,
+ capContent,
+ evaluateContentDivergence,
+ toContentDivergenceWarning,
+} from './content-divergence-gate.ts';
+
+describe('content-divergence gate', () => {
+ test('byte-equal content returns undefined (no divergence, the common path)', () => {
+ expect(evaluateContentDivergence('same bytes', 'same bytes', 'replace')).toBeUndefined();
+ expect(evaluateContentDivergence('', '', 'append')).toBeUndefined();
+ });
+
+ test('divergence carries the converged content inline + a coarse type', () => {
+ const actual = '# Heading\n\nwhat actually landed\n';
+ const intended = '# Heading\n\nwhat I intended\n';
+ const d = evaluateContentDivergence(actual, intended, 'patch');
+ expect(d).toBeDefined();
+ if (!d) return;
+ expect(d.intendedBytes).toBe(intended.length);
+ expect(d.actualBytes).toBe(actual.length);
+ expect(d.byteDelta).toBe(actual.length - intended.length);
+ expect(d.divergenceType).toBe('patch-content-mismatch');
+ expect(d.currentState).toEqual({ kind: 'inline', content: actual });
+ });
+
+ test('divergenceType label tracks the write surface', () => {
+ expect(evaluateContentDivergence('a', 'b', 'replace')?.divergenceType).toBe(
+ 'replace-content-mismatch',
+ );
+ expect(evaluateContentDivergence('a', 'b', 'append')?.divergenceType).toBe(
+ 'append-content-mismatch',
+ );
+ expect(evaluateContentDivergence('a', 'b', 'rollback')?.divergenceType).toBe(
+ 'rollback-content-mismatch',
+ );
+ });
+
+ test('byte fields are UTF-8 byte counts, not UTF-16 code units', () => {
+ const d = evaluateContentDivergence('abé😀', 'abc', 'replace');
+ expect(d).toBeDefined();
+ if (!d) return;
+ expect(d.intendedBytes).toBe(3);
+ expect(d.actualBytes).toBe(8);
+ expect(d.byteDelta).toBe(5);
+ expect(d.currentState).toEqual({ kind: 'inline', content: 'abé😀' });
+ });
+
+ test('capContent is inline at exactly the soft cap, truncated one byte over', () => {
+ const atCap = 'x'.repeat(CONTENT_DIVERGENCE_CAP_BYTES);
+ expect(capContent(atCap)).toEqual({ kind: 'inline', content: atCap });
+
+ const overCap = 'x'.repeat(CONTENT_DIVERGENCE_CAP_BYTES + 1);
+ const cs = capContent(overCap);
+ expect(cs.kind).toBe('truncated');
+ if (cs.kind === 'truncated') {
+ expect(cs.byteLength).toBe(overCap.length);
+ expect(cs.hint).toContain('exec');
+ expect('content' in cs).toBe(false);
+ }
+ });
+
+ test('an over-cap divergence degrades currentState to a truncation marker', () => {
+ const actual = 'y'.repeat(CONTENT_DIVERGENCE_CAP_BYTES + 100);
+ const d = evaluateContentDivergence(actual, 'small', 'replace');
+ expect(d?.currentState.kind).toBe('truncated');
+ });
+
+ test('toContentDivergenceWarning maps the wire shape with a default hint', () => {
+ const d = evaluateContentDivergence('actual', 'intended', 'replace');
+ expect(d).toBeDefined();
+ if (!d) return;
+ const w = toContentDivergenceWarning(d);
+ expect(w.kind).toBe('content-divergence');
+ expect(w.intendedBytes).toBe(d.intendedBytes);
+ expect(w.actualBytes).toBe(d.actualBytes);
+ expect(w.byteDelta).toBe(d.byteDelta);
+ expect(w.divergenceType).toBe('replace-content-mismatch');
+ expect(w.currentState).toEqual(d.currentState);
+ expect(typeof w.hint).toBe('string');
+ expect(w.hint).toContain('currentState');
+ });
+
+ test('toContentDivergenceWarning accepts an explicit hint override', () => {
+ const d = evaluateContentDivergence('a', 'b', 'replace');
+ if (!d) return;
+ expect(toContentDivergenceWarning(d, 'custom hint').hint).toBe('custom hint');
+ });
+
+ test('the wire schema round-trips a full warning (inline + truncated currentState)', () => {
+ const small = evaluateContentDivergence('a', 'b', 'replace');
+ const big = evaluateContentDivergence(
+ 'x'.repeat(CONTENT_DIVERGENCE_CAP_BYTES + 1),
+ 'b',
+ 'replace',
+ );
+ expect(small).toBeDefined();
+ expect(big).toBeDefined();
+ if (!small || !big) return;
+ expect(
+ ContentDivergenceWarningSchema.safeParse(toContentDivergenceWarning(small)).success,
+ ).toBe(true);
+ expect(ContentDivergenceWarningSchema.safeParse(toContentDivergenceWarning(big)).success).toBe(
+ true,
+ );
+ });
+});
diff --git a/packages/server/src/content-divergence-gate.ts b/packages/server/src/content-divergence-gate.ts
new file mode 100644
index 000000000..4ec9803ea
--- /dev/null
+++ b/packages/server/src/content-divergence-gate.ts
@@ -0,0 +1,65 @@
+import type {
+ ContentDivergenceCurrentState,
+ ContentDivergenceWarning,
+} from '@inkeep/open-knowledge-core';
+
+export const CONTENT_DIVERGENCE_CAP_BYTES = 50 * 1024;
+
+const byteLength = (s: string): number => Buffer.byteLength(s, 'utf8');
+
+export type ContentDivergenceLabel = 'replace' | 'append' | 'prepend' | 'patch' | 'rollback';
+
+export interface AgentWriteContentDivergence {
+ intendedBytes: number;
+ actualBytes: number;
+ byteDelta: number;
+ divergenceType: string;
+ currentState: ContentDivergenceCurrentState;
+}
+
+export function capContent(content: string): ContentDivergenceCurrentState {
+ const bytes = byteLength(content);
+ if (bytes <= CONTENT_DIVERGENCE_CAP_BYTES) {
+ return { kind: 'inline', content };
+ }
+ return {
+ kind: 'truncated',
+ byteLength: bytes,
+ hint: 'Converged content exceeds the inline cap — re-read via exec("cat <doc>") for the full document.',
+ };
+}
+
+export function evaluateContentDivergence(
+ actualContent: string,
+ intendedContent: string,
+ label: ContentDivergenceLabel,
+): AgentWriteContentDivergence | undefined {
+ if (actualContent === intendedContent) return undefined;
+ const intendedBytes = byteLength(intendedContent);
+ const actualBytes = byteLength(actualContent);
+ return {
+ intendedBytes,
+ actualBytes,
+ byteDelta: actualBytes - intendedBytes,
+ divergenceType: `${label}-content-mismatch`,
+ currentState: capContent(actualContent),
+ };
+}
+
+const DEFAULT_DIVERGENCE_HINT =
+ 'The converged document differs from the bytes you composed. The write landed; `currentState` carries what is in the document now — re-read only if it is truncated.';
+
+export function toContentDivergenceWarning(
+ d: AgentWriteContentDivergence,
+ hint: string = DEFAULT_DIVERGENCE_HINT,
+): ContentDivergenceWarning {
+ return {
+ kind: 'content-divergence',
+ intendedBytes: d.intendedBytes,
+ actualBytes: d.actualBytes,
+ byteDelta: d.byteDelta,
+ divergenceType: d.divergenceType,
+ currentState: d.currentState,
+ hint,
+ };
+}
diff --git a/packages/server/src/mcp/tools/edit-document.test.ts b/packages/server/src/mcp/tools/edit-document.test.ts
index d015678b8..e6928d7ae 100644
--- a/packages/server/src/mcp/tools/edit-document.test.ts
+++ b/packages/server/src/mcp/tools/edit-document.test.ts
@@ -71,6 +71,7 @@ const requestBodies: unknown[] = [];
let mockSubscriberCount: number | undefined = 1;
let mockSystemSubscriberCount: number | undefined = 1;
let mockErrorEnvelope: { status: number; body: Record<string, unknown> } | undefined;
+let mockWarning: Record<string, unknown> | undefined;
beforeAll(() => {
testServer = Bun.serve({
@@ -100,6 +101,7 @@ beforeAll(() => {
...(mockSystemSubscriberCount !== undefined
? { systemSubscriberCount: mockSystemSubscriberCount }
: {}),
+ ...(mockWarning !== undefined ? { warning: mockWarning } : {}),
});
}
@@ -120,6 +122,7 @@ beforeEach(async () => {
mockSubscriberCount = 1;
mockSystemSubscriberCount = 1;
mockErrorEnvelope = undefined;
+ mockWarning = undefined;
});
afterEach(async () => {
@@ -163,6 +166,56 @@ describe('edit_document MCP tool', () => {
expect(result.content[0]?.text).toBe('Edit applied successfully.');
});
+ test('relays a content-divergence warning as structuredContent.contentDivergence + a text line', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps());
+ mockWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 20,
+ actualBytes: 27,
+ byteDelta: 7,
+ divergenceType: 'patch-content-mismatch',
+ currentState: { kind: 'inline', content: 'what actually landed\nextra\n' },
+ hint: 'currentState carries the converged content.',
+ };
+
+ const result = await getTool().handler({ docName: 'notes', find: 'a', replace: 'b' });
+
+ expect(result.structuredContent?.contentDivergence).toMatchObject({
+ kind: 'content-divergence',
+ byteDelta: 7,
+ divergenceType: 'patch-content-mismatch',
+ currentState: { kind: 'inline', content: 'what actually landed\nextra\n' },
+ });
+ expect(result.content[0]?.text).toContain('⚠ Content divergence');
+ });
+
+ test('drops a malformed server warning at the safeParse boundary', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps());
+ mockWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 20,
+ actualBytes: 27,
+ byteDelta: 'seven',
+ };
+
+ const result = await getTool().handler({ docName: 'notes', find: 'a', replace: 'b' });
+
+ expect(result.structuredContent?.contentDivergence).toBeUndefined();
+ expect(result.content[0]?.text).not.toContain('⚠ Content divergence');
+ });
+
+ test('ignores a non-divergence server warning (preview-attach lives on its own key)', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps());
+ mockWarning = { action: 'attach-preview-once', previewUrl: '/#/notes' };
+
+ const result = await getTool().handler({ docName: 'notes', find: 'a', replace: 'b' });
+
+ expect(result.structuredContent?.contentDivergence).toBeUndefined();
+ });
+
test('omits offset when the caller uses first-match mode', async () => {
const { server, getTool } = createFakeServer();
diff --git a/packages/server/src/mcp/tools/edit-document.ts b/packages/server/src/mcp/tools/edit-document.ts
index 2a4ddfbd5..9ba481fdb 100644
--- a/packages/server/src/mcp/tools/edit-document.ts
+++ b/packages/server/src/mcp/tools/edit-document.ts
@@ -1,4 +1,4 @@
-import { renderInventoryFooter } from '@inkeep/open-knowledge-core';
+import { ContentDivergenceWarningSchema, renderInventoryFooter } from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import { resolveLockDir } from '../../config/paths.ts';
import type { AgentIdentity } from '../agent-identity.ts';
@@ -26,6 +26,8 @@ const BASE_DESCRIPTION = [
'- `replace` — Replacement text.',
'- `offset` — Optional JavaScript string offset of the exact occurrence to patch. Stale offsets return an error; re-fetch via `links({ kind: "suggest", docName })`.',
'- `summary` — Optional one-line user-outcome (≤80 chars). Avoid secrets or PII — persisted to git history.',
+ '',
+ 'Responses may include `structuredContent.contentDivergence` (`{kind: "content-divergence", intendedBytes, actualBytes, byteDelta, divergenceType, currentState, hint}`) when the converged Y.Text doesn\'t match the bytes your splice composed to. The patch still landed; you do NOT need to re-read — `currentState` carries the converged document inline (or a truncation marker over the soft cap).',
].join('\n');
export const DESCRIPTION = `${BASE_DESCRIPTION}\n${renderInventoryFooter()}`;
@@ -118,12 +120,28 @@ export function register(server: ServerInstance, deps: EditDocumentDeps): void {
: undefined;
const summaryHint = typeof summaryResult?.hint === 'string' ? summaryResult.hint : undefined;
+ const contentDivergenceParse = ContentDivergenceWarningSchema.safeParse(result.warning);
+ const contentDivergence = contentDivergenceParse.success
+ ? contentDivergenceParse.data
+ : undefined;
+
const lines: string[] = ['Edit applied successfully.'];
if (noPreviewAnywhere && !preview) lines.push(START_UI_TEXT_HINT);
if (summaryHint) lines.push(summaryHint);
+ if (contentDivergence) {
+ lines.push(
+ `⚠ Content divergence: ${contentDivergence.actualBytes} actual bytes vs ${contentDivergence.intendedBytes} intended (byteDelta=${contentDivergence.byteDelta}). ${contentDivergence.hint ?? 'currentState carries the converged content (re-read only if it is truncated).'}`,
+ );
+ }
const text = lines.join('\n');
- if (!preview && !noPreviewAnywhere && !noPreviewOnThisDoc && !summaryResult) {
+ if (
+ !preview &&
+ !noPreviewAnywhere &&
+ !noPreviewOnThisDoc &&
+ !summaryResult &&
+ !contentDivergence
+ ) {
return textResult(text);
}
@@ -138,6 +156,9 @@ export function register(server: ServerInstance, deps: EditDocumentDeps): void {
if (summaryResult) {
structured.summary = summaryResult;
}
+ if (contentDivergence) {
+ structured.contentDivergence = contentDivergence;
+ }
return textPlusStructured(text, structured);
},
);
diff --git a/packages/server/src/mcp/tools/version.test.ts b/packages/server/src/mcp/tools/version.test.ts
index f95b337ff..e92ec6318 100644
--- a/packages/server/src/mcp/tools/version.test.ts
+++ b/packages/server/src/mcp/tools/version.test.ts
@@ -79,6 +79,7 @@ let baseUrl: string;
let tmpDir: string;
const seenRequests: string[] = [];
const seenBodies: Array<Record<string, unknown>> = [];
+let mockRollbackWarning: Record<string, unknown> | undefined;
beforeAll(() => {
testServer = Bun.serve({
@@ -109,6 +110,7 @@ beforeAll(() => {
return Response.json({
ok: true,
...(summaryShape ? { summary: summaryShape } : {}),
+ ...(mockRollbackWarning !== undefined ? { warning: mockRollbackWarning } : {}),
});
}
return new Response('Not found', { status: 404 });
@@ -125,6 +127,7 @@ beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-version-test-'));
seenRequests.length = 0;
seenBodies.length = 0;
+ mockRollbackWarning = undefined;
});
afterEach(async () => {
@@ -225,6 +228,55 @@ describe('version — action=rollback (per-doc restore)', () => {
expect(result.content[0]?.text).toContain('01234567');
});
+ test('relays a rollback content-divergence warning as structuredContent.contentDivergence + a text line', async () => {
+ bindTestUiLock(tmpDir);
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl, tmpDir));
+ mockRollbackWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 40,
+ actualBytes: 33,
+ byteDelta: -7,
+ divergenceType: 'rollback-content-mismatch',
+ currentState: { kind: 'inline', content: 'restored body bytes\n' },
+ hint: 'currentState carries the converged content.',
+ };
+
+ const result = await getTool().handler({
+ action: 'rollback',
+ docName: 'notes',
+ commitSha: SHA,
+ });
+
+ expect(result.structuredContent?.contentDivergence).toMatchObject({
+ kind: 'content-divergence',
+ byteDelta: -7,
+ divergenceType: 'rollback-content-mismatch',
+ currentState: { kind: 'inline', content: 'restored body bytes\n' },
+ });
+ expect(result.content[0]?.text).toContain('⚠ Content divergence');
+ });
+
+ test('drops a malformed rollback warning at the safeParse boundary', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl, tmpDir));
+ mockRollbackWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 40,
+ actualBytes: 33,
+ byteDelta: 'minus seven',
+ };
+
+ const result = await getTool().handler({
+ action: 'rollback',
+ docName: 'notes',
+ commitSha: SHA,
+ });
+
+ expect(result.structuredContent?.contentDivergence).toBeUndefined();
+ expect(result.content[0]?.text).not.toContain('⚠ Content divergence');
+ });
+
test('normalizes trailing .md from docName before history + rollback requests', async () => {
const { server, getTool } = createFakeServer();
register(server, makeDeps(baseUrl, tmpDir));
diff --git a/packages/server/src/mcp/tools/version.ts b/packages/server/src/mcp/tools/version.ts
index bbfdf5934..d08618e4b 100644
--- a/packages/server/src/mcp/tools/version.ts
+++ b/packages/server/src/mcp/tools/version.ts
@@ -1,3 +1,4 @@
+import { ContentDivergenceWarningSchema } from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import type { AgentIdentity } from '../agent-identity.ts';
import { resolvePreviewUrlForTool } from './preview-url.ts';
@@ -28,6 +29,8 @@ export const DESCRIPTION = [
'- `docName` — Required for `rollback`. Document name, typically without extension; trailing `.md`/`.mdx` is stripped.',
'- `commitSha` — Required for `rollback`. 40-character SHA from the shadow-repo timeline.',
'- `summary` — Optional rollback summary (≤80 chars). If omitted, defaults to "Restored to <sha-short>". Avoid secrets or PII — summaries persist to git history.',
+ '',
+ 'A `rollback` response may include `structuredContent.contentDivergence` (`{kind: "content-divergence", intendedBytes, actualBytes, byteDelta, divergenceType, currentState, hint}`) when the restored `Y.Text` does not byte-match the target-version bytes. The rollback still landed; `currentState` carries the converged document inline (or a truncation marker over the soft cap), so you do NOT need to re-read.',
].join('\n');
export interface VersionDeps {
@@ -158,6 +161,11 @@ async function handleRollback(args: VersionArgs, url: string, cwd: string, deps:
: undefined;
const summaryHint = typeof summaryResult?.hint === 'string' ? summaryResult.hint : undefined;
+ const contentDivergenceParse = ContentDivergenceWarningSchema.safeParse(result.warning);
+ const contentDivergence = contentDivergenceParse.success
+ ? contentDivergenceParse.data
+ : undefined;
+
const author = typeof versionResult.author === 'string' ? versionResult.author : undefined;
const timestamp =
typeof versionResult.timestamp === 'string' ? versionResult.timestamp : undefined;
@@ -166,6 +174,11 @@ async function handleRollback(args: VersionArgs, url: string, cwd: string, deps:
`Restored "${docName}" to version ${args.commitSha.slice(0, 8)}${provenance}. The change has been applied to all connected editors.`,
];
if (summaryHint) textLines.push(summaryHint);
+ if (contentDivergence) {
+ textLines.push(
+ `⚠ Content divergence: ${contentDivergence.actualBytes} actual bytes vs ${contentDivergence.intendedBytes} intended (byteDelta=${contentDivergence.byteDelta}). ${contentDivergence.hint ?? 'currentState carries the converged content (re-read only if it is truncated).'}`,
+ );
+ }
const preview = await resolvePreviewUrlForTool(
docName,
@@ -179,5 +192,6 @@ async function handleRollback(args: VersionArgs, url: string, cwd: string, deps:
previewUrl: preview?.url ?? null,
...(preview ? { previewUrlSource: preview.source } : {}),
...(summaryResult ? { summary: summaryResult } : {}),
+ ...(contentDivergence ? { contentDivergence } : {}),
});
}
diff --git a/packages/server/src/mcp/tools/write-document.test.ts b/packages/server/src/mcp/tools/write-document.test.ts
index 8d998427e..c1aee45cb 100644
--- a/packages/server/src/mcp/tools/write-document.test.ts
+++ b/packages/server/src/mcp/tools/write-document.test.ts
@@ -54,6 +54,7 @@ let mockSubscriberCount: number | undefined = 1;
let mockSystemSubscriberCount: number | undefined = 1;
let lastWriteRequest: Record<string, unknown> | undefined;
let mockErrorEnvelope: { status: number; body: Record<string, unknown> } | undefined;
+let mockWarning: Record<string, unknown> | undefined;
beforeAll(() => {
testServer = Bun.serve({
@@ -72,6 +73,7 @@ beforeAll(() => {
...(mockSystemSubscriberCount !== undefined
? { systemSubscriberCount: mockSystemSubscriberCount }
: {}),
+ ...(mockWarning !== undefined ? { warning: mockWarning } : {}),
});
}
return new Response('Not found', { status: 404 });
@@ -92,6 +94,7 @@ beforeEach(async () => {
mockSystemSubscriberCount = 1;
lastWriteRequest = undefined;
mockErrorEnvelope = undefined;
+ mockWarning = undefined;
});
afterEach(async () => {
@@ -481,6 +484,82 @@ describe('write_document — template instantiation (FR5)', () => {
});
});
+describe('write_document — content-divergence relay', () => {
+ test('single-doc: relays the server warning as structuredContent.contentDivergence + a text line', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps());
+ mockWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 18,
+ actualBytes: 25,
+ byteDelta: 7,
+ divergenceType: 'replace-content-mismatch',
+ currentState: { kind: 'inline', content: 'what actually landed\n' },
+ hint: 'currentState carries the converged content.',
+ };
+
+ const result = await getTool().handler({
+ docName: 'notes',
+ markdown: 'hello',
+ position: 'replace',
+ });
+
+ expect(result.structuredContent?.contentDivergence).toMatchObject({
+ kind: 'content-divergence',
+ byteDelta: 7,
+ divergenceType: 'replace-content-mismatch',
+ currentState: { kind: 'inline', content: 'what actually landed\n' },
+ });
+ expect(result.content[0]?.text).toContain('⚠ Content divergence');
+ });
+
+ test('batch: surfaces per-doc contentDivergence from the r.raw.warning path', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps());
+ mockWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 10,
+ actualBytes: 14,
+ byteDelta: 4,
+ divergenceType: 'append-content-mismatch',
+ currentState: { kind: 'inline', content: 'batch landed\n' },
+ hint: 'currentState carries the converged content.',
+ };
+
+ const result = await getTool().handler({
+ docs: [{ docName: 'docs/test', markdown: 'hello', position: 'append' }],
+ } as Parameters<RegisteredTool['handler']>[0]);
+
+ const s = result.structuredContent as {
+ documents: Array<{ docName: string; contentDivergence?: Record<string, unknown> }>;
+ };
+ expect(s.documents[0]?.contentDivergence).toMatchObject({
+ kind: 'content-divergence',
+ byteDelta: 4,
+ divergenceType: 'append-content-mismatch',
+ });
+ });
+
+ test('drops a malformed server warning at the safeParse boundary (single-doc)', async () => {
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps());
+ mockWarning = {
+ kind: 'content-divergence',
+ intendedBytes: 18,
+ actualBytes: 25,
+ byteDelta: 'seven',
+ };
+
+ const result = await getTool().handler({
+ docName: 'notes',
+ markdown: 'hello',
+ position: 'replace',
+ });
+
+ expect(result.structuredContent?.contentDivergence).toBeUndefined();
+ });
+});
+
describe('write_document — batch (docs)', () => {
test('writes each doc in the batch and reports per-doc results', async () => {
const { server, getTool } = createFakeServer();
diff --git a/packages/server/src/mcp/tools/write-document.ts b/packages/server/src/mcp/tools/write-document.ts
index 54da8adf3..5ad442081 100644
--- a/packages/server/src/mcp/tools/write-document.ts
+++ b/packages/server/src/mcp/tools/write-document.ts
@@ -1,6 +1,7 @@
import { existsSync, readFileSync } from 'node:fs';
import { resolve as resolvePath } from 'node:path';
import {
+ ContentDivergenceWarningSchema,
normalizeBridge,
renderInventoryFooter,
stripFrontmatter,
@@ -44,6 +45,8 @@ const BASE_DESCRIPTION = [
'- `template` — Template name. Mutually exclusive with `markdown`.',
'- `position` — `append` | `prepend` | `replace`. Optional for a new doc (defaults to `replace`); required for an existing doc. Forced to `replace` with `template`.',
'- `summary` — Optional one-line user-outcome (≤80 chars). Avoid secrets or PII — persisted to git history.',
+ '',
+ 'Responses may include a content-divergence warning when the converged Y.Text doesn\'t match the bytes your payload composed to. The write still landed; you do NOT need to re-read — `currentState` carries the converged document inline (`{kind:"inline", content}`, or `{kind:"truncated", byteLength, hint}` over the soft cap). Single-doc shape: `structuredContent.contentDivergence = { kind: "content-divergence", intendedBytes, actualBytes, byteDelta, divergenceType, currentState, hint }`. Batch shape: per-doc `structuredContent.documents[].contentDivergence` with the same field set.',
].join('\n');
export const DESCRIPTION = `${BASE_DESCRIPTION}\n${renderInventoryFooter()}`;
@@ -336,11 +339,14 @@ export function register(server: ServerInstance, deps: WriteDocumentDeps): void
const documents = results.map((r) => {
if (!r.ok) return { docName: r.docName, ok: false as const, error: r.error };
const preview = resolvePreviewUrl(r.docName, { lockDir });
+ const divergenceParse = ContentDivergenceWarningSchema.safeParse(r.raw.warning);
+ const divergence = divergenceParse.success ? divergenceParse.data : undefined;
return {
docName: r.docName,
ok: true as const,
position: r.position,
...(preview ? { previewUrl: preview.url } : {}),
+ ...(divergence ? { contentDivergence: divergence } : {}),
};
});
const okCount = documents.filter((d) => d.ok).length;
@@ -351,7 +357,11 @@ export function register(server: ServerInstance, deps: WriteDocumentDeps): void
if (emptyAppendNoOpNote(r.position, spec.markdown)) {
return `No change to ${spec.docName} — empty ${r.position}, document unchanged.`;
}
- return `Wrote ${spec.docName} (${r.position}).`;
+ const d = documents[i];
+ const base = `Wrote ${spec.docName} (${r.position}).`;
+ return d?.ok && d.contentDivergence
+ ? `${base} ⚠ Content divergence: ${d.contentDivergence.actualBytes} actual vs ${d.contentDivergence.intendedBytes} intended (byteDelta=${d.contentDivergence.byteDelta}).`
+ : base;
});
const perDocNotes = args.docs.flatMap((spec, i) => {
const r = results[i];
@@ -410,6 +420,11 @@ export function register(server: ServerInstance, deps: WriteDocumentDeps): void
: undefined;
const summaryHint = typeof summaryResult?.hint === 'string' ? summaryResult.hint : undefined;
+ const contentDivergenceParse = ContentDivergenceWarningSchema.safeParse(result.warning);
+ const contentDivergence = contentDivergenceParse.success
+ ? contentDivergenceParse.data
+ : undefined;
+
const noOpNote = emptyAppendNoOpNote(w.position, args.markdown);
const lines: string[] = [
noOpNote ??
@@ -427,9 +442,21 @@ export function register(server: ServerInstance, deps: WriteDocumentDeps): void
if (hint.message) lines.push(hint.message);
}
}
+ if (contentDivergence) {
+ lines.push(
+ `⚠ Content divergence: ${contentDivergence.actualBytes} actual bytes vs ${contentDivergence.intendedBytes} intended (byteDelta=${contentDivergence.byteDelta}). ${contentDivergence.hint ?? 'currentState carries the converged content (re-read only if it is truncated).'}`,
+ );
+ }
const text = lines.join('\n');
- if (!preview && !noPreviewAnywhere && !noPreviewOnThisDoc && !hints && !summaryResult) {
+ if (
+ !preview &&
+ !noPreviewAnywhere &&
+ !noPreviewOnThisDoc &&
+ !hints &&
+ !summaryResult &&
+ !contentDivergence
+ ) {
return textResult(text);
}
@@ -447,6 +474,9 @@ export function register(server: ServerInstance, deps: WriteDocumentDeps): void
if (summaryResult) {
structured.summary = summaryResult;
}
+ if (contentDivergence) {
+ structured.contentDivergence = contentDivergence;
+ }
return textPlusStructured(text, structured);
},
);