Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): persist agent writes that only add blank lines (PRD-8526) (#4139)

tim-inkeep15d2b17d9894
diff --git a/.changeset/agent-blank-line-writes-persist.md b/.changeset/agent-blank-line-writes-persist.md
new file mode 100644
index 000000000..7f932d2b5
--- /dev/null
+++ b/.changeset/agent-blank-line-writes-persist.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+`lint({ fix: true })` and `edit` now persist changes that only add blank lines, such as the MD022 fix that inserts a blank line below a heading. Previously the server reported the fix as applied while the file on disk stayed unchanged, because the persistence layer compared the new content against the last on-disk bytes through a normalizer that tolerates missing block separators and concluded nothing had changed. Agent-triggered writes now compare bytes exactly. The exact-byte comparison also survives a store that a concurrent editing burst defers, so a blank-line-only write made during that window still reaches disk on the next flush.
diff --git a/packages/server/src/persistence-agent-blank-line-write.test.ts b/packages/server/src/persistence-agent-blank-line-write.test.ts
new file mode 100644
index 000000000..81b240a05
--- /dev/null
+++ b/packages/server/src/persistence-agent-blank-line-write.test.ts
@@ -0,0 +1,86 @@
+import { appendFileSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig } from './composition-rig.test-helper.ts';
+
+const HEADINGS_WITHOUT_BLANK_LINES =
+ '# Title\nIntro para.\n\n## Section A\nBody A.\n\n## Section B\nBody B.\n';
+let contentDir: string;
+let server: BootedServer;
+let ephemeralDir: string;
+let ephemeralServer: BootedServer;
+
+beforeAll(async () => {
+ contentDir = mkdtempSync(resolve(tmpdir(), 'ok-agent-blank-line-'));
+ writeFileSync(resolve(contentDir, 'lint-target.md'), HEADINGS_WITHOUT_BLANK_LINES, 'utf-8');
+ writeFileSync(resolve(contentDir, 'edit-target.md'), HEADINGS_WITHOUT_BLANK_LINES, 'utf-8');
+ server = await bootCompositionRig(contentDir);
+ await server.ready;
+ appendFileSync(
+ resolve(contentDir, '.ok', 'config.yml'),
+ '\ncontentRules:\n enabled: true\n markdownlint:\n enabled: true\n',
+ );
+
+ ephemeralDir = mkdtempSync(resolve(tmpdir(), 'ok-agent-blank-line-ephemeral-'));
+ writeFileSync(resolve(ephemeralDir, 'note.md'), HEADINGS_WITHOUT_BLANK_LINES, 'utf-8');
+ ephemeralServer = await bootCompositionRig(ephemeralDir, {
+ ephemeral: true,
+ singleDocRelPath: 'note.md',
+ });
+ await ephemeralServer.ready;
+}, 60_000);
+
+afterAll(async () => {
+ await Promise.allSettled([server?.destroy(), ephemeralServer?.destroy()]);
+ await rm(contentDir, { recursive: true, force: true });
+ await rm(ephemeralDir, { recursive: true, force: true });
+});
+
+function post(path: string, body: Record<string, unknown>, target: BootedServer = server) {
+ return fetch(`http://127.0.0.1:${target.port}${path}`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ agentName: 'blank-line-agent', clientName: 'test', ...body }),
+ });
+}
+
+test('lint fix whose only change is blank lines below headings reaches disk', async () => {
+ const res = await post('/api/lint/fix', { docName: 'lint-target' });
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as { fixedCount: number };
+ expect(body.fixedCount).toBeGreaterThan(0);
+ expect(readFileSync(resolve(contentDir, 'lint-target.md'), 'utf-8')).toBe(
+ '# Title\n\nIntro para.\n\n## Section A\n\nBody A.\n\n## Section B\n\nBody B.\n',
+ );
+});
+
+test('agent patch that only inserts a blank line below a heading reaches disk', async () => {
+ const res = await post('/api/agent-patch', {
+ docName: 'edit-target',
+ find: '## Section A\nBody A.',
+ replace: '## Section A\n\nBody A.',
+ });
+ expect(res.status).toBe(200);
+ expect(readFileSync(resolve(contentDir, 'edit-target.md'), 'utf-8')).toBe(
+ '# Title\nIntro para.\n\n## Section A\n\nBody A.\n\n## Section B\nBody B.\n',
+ );
+});
+
+test('agent patch on an ephemeral single-file doc reaches disk with the blank line', async () => {
+ const res = await post(
+ '/api/agent-patch',
+ {
+ docName: 'note',
+ find: '## Section A\nBody A.',
+ replace: '## Section A\n\nBody A.',
+ },
+ ephemeralServer,
+ );
+ expect(res.status).toBe(200);
+ expect(readFileSync(resolve(ephemeralDir, 'note.md'), 'utf-8')).toBe(
+ '# Title\nIntro para.\n\n## Section A\n\nBody A.\n\n## Section B\nBody B.\n',
+ );
+});
diff --git a/packages/server/src/persistence-deferred-store.test.ts b/packages/server/src/persistence-deferred-store.test.ts
index 0a4ccec1e..d29babeab 100644
--- a/packages/server/src/persistence-deferred-store.test.ts
+++ b/packages/server/src/persistence-deferred-store.test.ts
@@ -346,6 +346,34 @@ describe('quiescence gate — deferCount cleanup on disk-write error', () => {
rmSync(tmpDir, { recursive: true, force: true });
});
+ test('a store deferred by non-quiescence keeps the agent-write flag for the next store', async () => {
+ const docName = 'agent-write-flag-survives-defer';
+ const docPath = join(tmpDir, `${docName}.md`);
+ writeFileSync(docPath, 'initial\n', 'utf-8');
+
+ const persistence = createPersistenceExtension({
+ contentDir: tmpDir,
+ projectDir: tmpDir,
+ gitEnabled: false,
+ });
+ const document = new Y.Doc();
+
+ await loadDocument(persistence, document, docName);
+ document.transact(() => replaceDocParagraph(document, 'edited body'), BROWSER_ORIGIN);
+ durabilityState.markAgentWriteStore(docName);
+
+ __setQuiescentOverrideForTests(document, false);
+ try {
+ await storeDocument(persistence, document, docName);
+ expect(readFileSync(docPath, 'utf-8')).toBe('initial\n');
+ } finally {
+ __setQuiescentOverrideForTests(document, undefined);
+ }
+
+ expect(durabilityState.consumeAgentWriteStore(docName)).toBe(true);
+ document.destroy();
+ });
+
test('disk-write error in force-flush path resets deferCount so next cycle resumes the gate', async () => {
const docName = 'force-flush-disk-error';
const docPath = join(tmpDir, `${docName}.md`);
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 6e59c2c6c..686a563d3 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -1150,8 +1150,6 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
'persistence.onStoreDocument',
{ attributes: { 'doc.name': documentName } },
async () => {
- const agentTriggeredStore = durabilityState.consumeAgentWriteStore(documentName);
-
const lifecycleStatus = frozenDocLifecycleStatus(document);
if (lifecycleStatus !== null) {
log.info(
@@ -1191,6 +1189,8 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
incrementPersistenceForceFlushDuringBurst();
}
+ const agentTriggeredStore = durabilityState.consumeAgentWriteStore(documentName);
+
const { sv: stateVectorAtRead, json } = captureDocSnapshotForPersistence(document);
const ytextSnapshot = document.getText('source').toString();
@@ -1256,9 +1256,16 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
const normalizedMarkdown = normalizedSourceForm(ytextSnapshot);
let markdownSemanticallyUnchanged =
currentBase !== undefined &&
- normalizedMarkdown === normalizeBridge(currentBase) &&
- !addsBlankLines(currentBase, markdown);
- if (!markdownSemanticallyUnchanged && ephemeral && currentBase !== undefined) {
+ (agentTriggeredStore
+ ? markdown === currentBase
+ : normalizedMarkdown === normalizeBridge(currentBase) &&
+ !addsBlankLines(currentBase, markdown));
+ if (
+ !markdownSemanticallyUnchanged &&
+ !agentTriggeredStore &&
+ ephemeral &&
+ currentBase !== undefined
+ ) {
const canonicalBase = canonicalizeForEphemeralBaseline(currentBase, documentName);
if (canonicalBase !== null && normalizedMarkdown === canonicalBase) {
markdownSemanticallyUnchanged = true;