openwriter 0.36.3 → 0.37.0

package/dist/server/mcp.js

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteFileSync, readConfig } from './helpers.js';
 import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, setAgentLockActive, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, getIsTemp, extractText, countPending, addDocTag, removeDocTag, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, getCanonical, cloneWithPendingReverted, bumpDocVersion, setSortProposalOnFile, clearSortRequestOnFile, } from './state.js';
 import { tiptapToBlocks } from './node-blocks.js';
+import { readBlame, summarizeBlame } from './attribution.js';
 import { outline, peek, searchInDoc, truncateRead } from './peek-outline.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
 import { resolveTypeMeta } from './content-type-meta.js';
@@ -551,7 +552,7 @@ export const TOOL_REGISTRY = [
                         wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                     }
                     const newDocId = getDocId();
-                    save();
+                    save('agent');
                     broadcastDocumentsChanged();
                     broadcastWorkspacesChanged();
                     broadcastDocumentSwitched(getDocument(), getTitle(), getActiveFilename(), getMetadata());
@@ -692,7 +693,7 @@ export const TOOL_REGISTRY = [
                 }
                 updateDocument(doc);
                 updatePendingCacheForActiveDoc();
-                save();
+                save('agent');
                 // Broadcast sidebar updates first (deferred from create_document) so the doc
                 // entry and spinner removal arrive in the same render cycle
                 broadcastDocumentsChanged();
@@ -880,6 +881,31 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: Object.keys(target.metadata).length > 0 ? JSON.stringify(target.metadata) : '{}' }] };
         },
     },
+    {
+        name: 'get_attribution',
+        description: 'Get human-vs-agent author attribution for a document. Returns the char-weighted composition (% human / % agent / % unknown) plus per-node coarse origin (human | agent | mixed | unknown). Attribution is captured automatically at save time and anchored to sentence content, so it survives edits, splits, and paste-back. "unknown" = content authored before attribution tracking began. Use to report how much of a doc is genuinely author-written vs agent-scaffolded.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            const blocks = tiptapToBlocks(target.document);
+            const blame = readBlame(docId);
+            const summary = summarizeBlame(blame, blocks);
+            const nodeCounts = { human: 0, agent: 0, mixed: 0, unknown: 0 };
+            for (const origin of Object.values(summary.nodes))
+                nodeCounts[origin] = (nodeCounts[origin] ?? 0) + 1;
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            docId,
+                            percent: summary.percent,
+                            chars: summary.chars,
+                            nodeOrigins: summary.nodes,
+                            nodeCounts,
+                            tracked: blame !== null,
+                            attributionSince: blame?.attributionSince ?? null,
+                        }) }] };
+        },
+    },
     {
         name: 'set_metadata',
         description: 'Update frontmatter metadata on a document. Merges with existing metadata — only provided keys are changed. Use for summaries, character lists, tags, arc notes, or any organizational data. Saves to disk immediately. Lifecycle convention (v0.19.0): use `set_metadata({ status: "canonical" })` when a doc commits to the workspace spine (Beats locks, Research Note becomes load-bearing); use `set_metadata({ status: "draft" })` when a doc is superseded or demoted. Status is the agent\'s field — the enrichment minion never writes it.',
@@ -923,7 +949,7 @@ export const TOOL_REGISTRY = [
                 const meta = getMetadata();
                 for (const key of removed)
                     delete meta[key];
-                save();
+                save('agent');
                 broadcastMetadataChanged(getMetadata());
                 if (cleaned.title) {
                     // Reached only on temp-file creation titling — hot promote.
@@ -1015,7 +1041,7 @@ export const TOOL_REGISTRY = [
                         for (const k of LEGACY_FIELDS_TO_RETIRE)
                             delete liveMeta[k];
                         bumpDocVersion();
-                        save();
+                        save('agent');
                         broadcastMetadataChanged(getMetadata());
                     }
                     else {
@@ -1647,7 +1673,7 @@ export const TOOL_REGISTRY = [
                         doc.content.push(pendingImage);
                     }
                     updateDocument(doc);
-                    save();
+                    save('agent');
                     setAgentLockActive();
                     broadcastDocumentSwitched(doc, getTitle(), getActiveFilename(), getMetadata());
                     return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, lastNodeId: imgId }) }] };
@@ -1668,7 +1694,7 @@ export const TOOL_REGISTRY = [
                     articleContext.coverImage = src;
                     articleContext.coverImages = existing;
                     setMetadata({ articleContext });
-                    save();
+                    save('agent');
                     broadcastMetadataChanged(getMetadata());
                     return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, coverSet: true }) }] };
                 }
@@ -1970,7 +1996,7 @@ export const TOOL_REGISTRY = [
                 // Active doc: mutate state.metadata and let save() persist the frontmatter.
                 // save()'s writeToDisk path invalidates the backlinks cache.
                 setMetadata({ references: newReferences });
-                save();
+                save('agent');
                 broadcastMetadataChanged(getMetadata());
             }
             else {

package/dist/server/state.js

@@ -10,6 +10,8 @@ import { tiptapToMarkdown, tiptapToMarkdownChecked, tiptapToBody, markdownToTipt
 import { applyTextEditsToNode } from './text-edit.js';
 import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath, canonicalizeIdentifier } from './helpers.js';
 import { snapshotIfNeeded, ensureDocId, forceSnapshot } from './versions.js';
+import { captureAttribution, bindBlameToVersion } from './attribution.js';
+import { scheduleAgentCommit } from './commits.js';
 import { syncReferencesFromProse, invalidateBacklinksCache, writeFrontmatter } from './backlinks.js';
 import { isAutoAcceptInheritedForDoc } from './workspaces.js';
 import { matchNodes } from './node-matcher.js';
@@ -1087,12 +1089,29 @@ export function resetDocVersion() {
 // adr: adr/pending-overlay-model.md
 let saveTimer = null;
 const SAVE_DEBOUNCE_MS = 500;
-export function debouncedSave() {
+// The actor whose edits are sitting in the current debounce window. Set at
+// schedule time (NOT flush time) so attribution can't bleed across actors.
+// adr: adr/document-history-attribution.md (invariant 3 — no module-global shim;
+// this is save-scoped: it tracks the SCHEDULER of the pending batch and is
+// cleared the moment that batch flushes).
+let pendingSaveActor = null;
+export function debouncedSave(actor = 'human') {
+    // If a save is already pending under a DIFFERENT actor, flush that batch now
+    // under ITS actor before this actor's edits join the window — otherwise the
+    // single coalesced flush would attribute both actors' new sentences to one.
+    if (saveTimer && pendingSaveActor && pendingSaveActor !== actor) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+        save(pendingSaveActor);
+    }
+    pendingSaveActor = actor;
     if (saveTimer)
         clearTimeout(saveTimer);
     saveTimer = setTimeout(() => {
         saveTimer = null;
-        save();
+        const a = pendingSaveActor ?? 'human';
+        pendingSaveActor = null;
+        save(a);
     }, SAVE_DEBOUNCE_MS);
 }
 /** Cancel any pending debounced save. Call before doc switch (which does its own save). */
@@ -1101,6 +1120,7 @@ export function cancelDebouncedSave() {
         clearTimeout(saveTimer);
         saveTimer = null;
     }
+    pendingSaveActor = null;
 }
 export function applyChanges(changes) {
     // Bump version BEFORE applying so new overlay entries created by
@@ -1120,8 +1140,10 @@ export function applyChanges(changes) {
     for (const listener of listeners) {
         listener(processed, version);
     }
-    // Debounced save — coalesces rapid agent writes into a single disk write
-    debouncedSave();
+    // Debounced save — coalesces rapid agent writes into a single disk write.
+    // applyChanges is an AGENT door (MCP write tools land here); tag the batch
+    // so the flush attributes its new content to the agent.
+    debouncedSave('agent');
     // Update pending doc cache for the active document
     updatePendingCacheForActiveDoc();
     // Find the last created node ID for chaining inserts
@@ -2129,7 +2151,7 @@ export function getPendingDocInfo() {
 // ============================================================================
 // PERSISTENCE
 // ============================================================================
-function writeToDisk() {
+function writeToDisk(actor = 'human') {
     // No-op gate: when the in-memory document hasn't been mutated since the
     // last successful write (or byte-equality skip), bail before any work.
     // Skips the full serialize + matcher pipeline (~50ms on medium docs), the
@@ -2270,6 +2292,34 @@ function writeToDisk() {
         // The serializer no longer emits `meta.pending` (overlay handles that).
         const result = tiptapToMarkdownChecked(canonical, state.title, metaWithGraveyard);
         markdown = result.markdown;
+        // Author attribution (Tier A + Tier B). MUST run here — alongside the
+        // overlay save and BEFORE the "content identical" / external-write /
+        // destructive-save guards below. An agent that adds ONLY pending content
+        // leaves the canonical body byte-identical, so those guards short-circuit
+        // the disk write; but the MERGED state (state.document) DID change and was
+        // just persisted to the overlay sidecar — so its attribution must be
+        // captured too. Capture from the MERGED doc (NOT canonical) so an agent's
+        // pending proposals are stamped 'agent' at write time; because blame is
+        // anchored to the sentence content hash, a later human ACCEPT leaves the
+        // hash unchanged and the agent origin holds (accept never launders).
+        // The version binding happens after the body write (a pending-only save
+        // produces no new snapshot, which is correct — it isn't a new version).
+        // adr: adr/document-history-attribution.md
+        if (state.docId) {
+            try {
+                captureAttribution(state.docId, tiptapToBlocks(state.document), actor, Date.now());
+                // Agent-finished commit trigger (debounced, per-doc). Fires from the
+                // CAPTURE site — the only place that reliably sees every agent edit tool
+                // (write_to_pad/populate/edit_text) with the exact target docId. The
+                // spinner broadcast (broadcastWritingFinished) was the wrong hook: not
+                // all write tools fire it. adr: adr/document-history-attribution.md
+                if (actor === 'agent' && state.filePath)
+                    scheduleAgentCommit(state.docId, state.filePath);
+            }
+            catch (err) {
+                console.error('[Attribution] capture failed:', err);
+            }
+        }
     }
     if (existsSync(state.filePath)) {
         // Skip write if content is identical (prevents phantom git changes on doc switch)
@@ -2342,11 +2392,22 @@ function writeToDisk() {
     // Record that disk now matches in-memory at this docVersion. Subsequent
     // save() calls without further mutations will bail at the top-level gate.
     lastSavedDocVersion = docVersion;
-    // Best-effort version snapshot — never blocks saves
+    // Best-effort version snapshot — never blocks saves. Returns the cut ts
+    // (or null if throttled/unchanged) so attribution can bind to this version.
+    // Attribution itself was already captured in the else branch above (so a
+    // pending-only save, which skips the body write, is still attributed); here
+    // we just stamp the blame with the version cut when a real snapshot landed.
+    let snapshotTs = null;
     try {
-        snapshotIfNeeded(state.docId, state.filePath);
+        snapshotTs = snapshotIfNeeded(state.docId, state.filePath);
     }
     catch { /* ignore */ }
+    if (snapshotTs && !isExternalDoc(state.filePath) && state.docId) {
+        try {
+            bindBlameToVersion(state.docId, snapshotTs);
+        }
+        catch { /* best-effort */ }
+    }
     // Auto-sync references from prose: legacy `doc:` prose links still render
     // (PadLink extension), but the graph/crawl/backlinks-panel read the
     // structural `references:` field. After every save, scan the body for
@@ -2370,7 +2431,22 @@ function writeToDisk() {
         invalidateBacklinksCache();
     }
 }
-export function save() {
+export function save(actor) {
+    // Resolve the save-scoped actor. Explicit arg wins; else fall back to the
+    // actor who scheduled the pending debounce batch this save is flushing; else
+    // 'human' (system/user-initiated saves that don't author prose produce no
+    // attribution spans anyway). adr: adr/document-history-attribution.md
+    // If an explicit actor differs from a pending-batch actor, flush that batch
+    // first under its own actor so this save never absorbs another actor's edits.
+    if (actor && saveTimer && pendingSaveActor && pendingSaveActor !== actor) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+        const prior = pendingSaveActor;
+        pendingSaveActor = null;
+        writeToDisk(prior);
+    }
+    const resolvedActor = actor ?? pendingSaveActor ?? 'human';
+    pendingSaveActor = null;
     // Auto-title from body content if the title is still default/empty.
     // Runs BEFORE filePath assignment so a brand-new doc lands at its
     // derived-title filename directly (no temp-file detour). For already-
@@ -2406,7 +2482,7 @@ export function save() {
             state.isTemp = false;
         }
     }
-    writeToDisk();
+    writeToDisk(resolvedActor);
 }
 export function load() {
     ensureDataDir();
@@ -2809,6 +2885,23 @@ export function saveDocToFile(filename, doc) {
         if (docId) {
             const overlay = extractOverlay(doc);
             saveOverlay(docId, overlay);
+            // This routes a BROWSER doc-update to a non-active file — the content is
+            // the human's. Snapshot + attribute as 'human'. adr: adr/document-history-attribution.md
+            if (!isExternalDoc(targetPath)) {
+                let snapshotTs = null;
+                try {
+                    snapshotTs = snapshotIfNeeded(docId, targetPath);
+                }
+                catch { /* ignore */ }
+                try {
+                    captureAttribution(docId, tiptapToBlocks(doc), 'human', Date.now());
+                    if (snapshotTs)
+                        bindBlameToVersion(docId, snapshotTs);
+                }
+                catch (err) {
+                    console.error('[Attribution] saveDocToFile capture failed:', err);
+                }
+            }
         }
         // Backlinks cache invalidate — browser sent a doc-update for a non-active
         // doc; the prose-link set on that doc may have changed.
@@ -3041,6 +3134,29 @@ function flushDocToFile(filename, doc, title, metadata) {
     if (docId) {
         const overlay = extractOverlay(doc);
         saveOverlay(docId, overlay);
+        // Door 3: non-active agent writes (populate_document / write_to_pad /
+        // edit_text targeting a non-active doc). This path bypasses writeToDisk
+        // and historically produced NO snapshot — so it had neither a restore
+        // floor nor attribution. Add both. This door is ALWAYS the agent (humans
+        // only edit the active doc in the browser), so actor is 'agent'.
+        // adr: adr/document-history-attribution.md
+        if (!isExternalDoc(targetPath)) {
+            let snapshotTs = null;
+            try {
+                snapshotTs = snapshotIfNeeded(docId, targetPath);
+            }
+            catch { /* ignore */ }
+            try {
+                captureAttribution(docId, tiptapToBlocks(doc), 'agent', Date.now());
+                if (snapshotTs)
+                    bindBlameToVersion(docId, snapshotTs);
+                // Door 3 is always an agent write (non-active). Schedule its commit.
+                scheduleAgentCommit(docId, targetPath);
+            }
+            catch (err) {
+                console.error('[Attribution] door-3 capture failed:', err);
+            }
+        }
     }
     setPendingCacheEntry(filename, countPending(doc.content));
     // Backlinks cache invalidation — non-active write paths (populate_document on

package/dist/server/versions.js

@@ -70,30 +70,46 @@ function seedLastSnapshot(docId) {
     const content = readFileSync(join(dir, `${latest}.md`), 'utf-8');
     lastSnapshot.set(docId, { time: latest, hash: contentHash(content) });
 }
+/**
+ * Pick a free, strictly-increasing integer timestamp for a new snapshot file.
+ * Two snapshots in the same millisecond would collide on `${Date.now()}.md`;
+ * bumping (rather than adding a `-N` suffix) keeps the filename a parseable
+ * integer so listVersions/seedLastSnapshot's parseInt never yields NaN.
+ */
+function freeSnapshotTs(docId) {
+    const dir = docDir(docId);
+    let now = Date.now();
+    while (existsSync(join(dir, `${now}.md`)))
+        now++;
+    return now;
+}
 /**
  * Snapshot after every writeToDisk() — skips if content unchanged or within throttle window.
- * Called in best-effort mode (caller wraps in try/catch).
+ * Called in best-effort mode (caller wraps in try/catch). Returns the timestamp
+ * written (so attribution can bind the blame state to this version cut), or
+ * null when the snapshot was skipped.
  */
 export function snapshotIfNeeded(docId, filePath) {
     if (!docId || !filePath || !existsSync(filePath))
-        return;
+        return null;
     seedLastSnapshot(docId);
     const markdown = readFileSync(filePath, 'utf-8');
     const hash = contentHash(markdown);
-    const now = Date.now();
     const last = lastSnapshot.get(docId);
     if (last) {
         // Skip if content hasn't changed (regardless of time)
         if (hash === last.hash)
-            return;
+            return null;
         // Skip if within minimum interval even if content changed
-        if ((now - last.time) < MIN_INTERVAL_MS)
-            return;
+        if ((Date.now() - last.time) < MIN_INTERVAL_MS)
+            return null;
     }
     ensureDocDir(docId);
+    const now = freeSnapshotTs(docId);
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
     pruneVersions(docId);
+    return now;
 }
 /**
  * Force a snapshot regardless of dedup. Used before restores as a safety net.
@@ -103,8 +119,8 @@ export function forceSnapshot(docId, filePath) {
         return;
     const markdown = readFileSync(filePath, 'utf-8');
     const hash = contentHash(markdown);
-    const now = Date.now();
     ensureDocDir(docId);
+    const now = freeSnapshotTs(docId);
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
 }
@@ -120,8 +136,15 @@ export function writeSnapshotMarkdown(docId, markdown) {
     if (!docId)
         return 0;
     const hash = contentHash(markdown);
-    const now = Date.now();
+    // Dedup: if the most recent snapshot already holds this exact content, reuse
+    // its timestamp instead of writing a duplicate .md. Prevents a commit
+    // snapshot from duplicating the auto-snapshot the same save just wrote.
+    seedLastSnapshot(docId);
+    const last = lastSnapshot.get(docId);
+    if (last && last.hash === hash)
+        return last.time;
     ensureDocDir(docId);
+    const now = freeSnapshotTs(docId);
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
     return now;

package/dist/server/ws.js

@@ -5,6 +5,7 @@ import { WebSocketServer, WebSocket } from 'ws';
 import { updateDocument, syncBrowserDocUpdate, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, debouncedSave, cancelDebouncedSave, onChanges, onIdRewrites, isAgentLocked, setAgentLockActive, getDocVersion, isVersionCurrent, getPendingDocInfo, updatePendingCacheForActiveDoc, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, onExternalWriteConflict, onDocumentReloaded, onAutoTitleApplied, isAgentStub, unmarkAgentStub, } from './state.js';
 import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile, listDocuments, acceptPendingTitle, rejectPendingTitle, getPendingTitle } from './documents.js';
 import { removeDocFromAllWorkspaces } from './workspaces.js';
+import { commitFromFile } from './commits.js';
 import { canonicalizeIdentifier } from './helpers.js';
 import { nodeTextPreview, diagLog } from './pending-overlay.js';
 import { generateRequestId, withRequestId } from './logger.js';
@@ -294,7 +295,7 @@ export function setupWebSocket(server) {
                         const result = syncBrowserDocUpdate(msg.document, browserVersion);
                         diagLog(`[WS] doc-update SYNC-MERGED stale v${browserVersion}→v${serverVersion} preservedServerEntries=${result.preservedServerEntries}`);
                         updatePendingCacheForActiveDoc();
-                        debouncedSave();
+                        debouncedSave('human');
                     }
                     else if (browserFilename && browserFilename !== getActiveFilename()) {
                         // Browser sent a doc-update for a different document (race: server switched away).
@@ -321,7 +322,7 @@ export function setupWebSocket(server) {
                         diagLog(`[WS] doc-update ACCEPTED (browser: ${nodeCount} nodes, cleaned: ${cleanedCount}, server: ${currentNodeCount} nodes)`);
                         updateDocument(msg.document);
                         updatePendingCacheForActiveDoc(); // Keep cache in sync after browser edits/reject-all
-                        debouncedSave();
+                        debouncedSave('human');
                     }
                 }
                 // Browser requests fresh state on reconnect (instead of pushing stale state)
@@ -351,7 +352,7 @@ export function setupWebSocket(server) {
                         broadcastDocumentsChanged();
                     }
                     else {
-                        debouncedSave();
+                        debouncedSave('human');
                         debouncedBroadcastDocumentsChanged();
                     }
                 }
@@ -512,6 +513,19 @@ export function setupWebSocket(server) {
                         stripPendingAttrs();
                         save();
                         updatePendingCacheForActiveDoc(); // Sync cache after strip (prevents stale "has changes" indicator)
+                        // Commit trigger: accepting agent changes is a version boundary.
+                        // Bundles the agent's attributed edit-events into a commit (the
+                        // changeset actors reflect who authored; trigger records the accept).
+                        // adr: adr/document-history-attribution.md
+                        if (action === 'accept') {
+                            try {
+                                const did = getDocId();
+                                const fp = getFilePath();
+                                if (did && fp)
+                                    commitFromFile(did, fp, { trigger: 'accept', actor: 'human', nowTs: Date.now() });
+                            }
+                            catch { /* best-effort */ }
+                        }
                     }
                     else {
                         // Race path: resolved doc is NOT the active one (server switched away).
@@ -691,6 +705,11 @@ activityDocId) {
     });
     return writeKey;
 }
+// NOTE: the agent-finished commit trigger lives at the CAPTURE site
+// (state.ts writeToDisk / flushDocToFile via scheduleAgentCommit), NOT here.
+// broadcastWritingFinished is the spinner mechanism and is not fired by every
+// agent edit tool (write_to_pad never calls it), so it was the wrong hook.
+// adr: adr/document-history-attribution.md
 // key omitted → clear all (legacy single-write flows). Pass a key for multi-doc.
 export function broadcastWritingFinished(key) {
     if (key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.36.3",
+  "version": "0.37.0",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",