Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsindex 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.tsindex 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 = zsystemSubscriberCount: 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 = zsubscriberCount: 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.tsindex 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 = zrestoredFrom: 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.tsnew file mode 100644index 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.mdindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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>['crereturn _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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): voidconst 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): voidif (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): voidif (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): voidif (summaryResult) {structured.summary = summaryResult;}+ if (contentDivergence) {+ structured.contentDivergence = contentDivergence;+ }return textPlusStructured(text, structured);},);