Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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): PersisincrementPersistenceForceFlushDuringBurst();}+ 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): Persisconst 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;