openwriter 0.24.0 → 0.25.0

package/dist/server/mcp.js

@@ -12,7 +12,7 @@ import { z } from 'zod';
 import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteFileSync } 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, 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 { outline, peek, searchInDoc } from './peek-outline.js';
+import { outline, peek, searchInDoc, truncateRead } from './peek-outline.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
 import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, filenameByDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions, listPendingSorts, sortFooter, buildSortInstructions } from './documents.js';
 import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBacklinksCache } from './backlinks.js';
@@ -215,16 +215,28 @@ function formatCommentsOutput({ byFile, scopeLabel }) {
     }
     return lines.join('\n');
 }
+/** Hard cap on words returned per read_pad call. Above this, the response
+ *  is truncated at a top-level node boundary and a continuation hint is
+ *  appended pointing at peek_doc / outline_doc / search_docs. The cap exists
+ *  so the agent can't accidentally token-blow a 50k-word doc — read_pad's
+ *  contract is "doc opening + handle to continue," not "everything."
+ *  v0.25 — see CHANGELOG. */
+const READ_PAD_MAX_WORDS = 2000;
+/** First-truncation FYI shows once per MCP process lifetime so the agent
+ *  learns the new behavior without repeating the explanation. Resets on
+ *  server restart. */
+let firstTruncationShown = false;
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
-        description: 'Read a document by docId. Returns compact tagged-line format with [type:id] per node, inline markdown formatting. Much more token-efficient than JSON.',
+        description: `Read a document by docId. Returns compact tagged-line format with [type:id] per node. Capped at ~${READ_PAD_MAX_WORDS} words per call — for longer docs you get the opening slice plus a lastNodeId hint. Use peek_doc({ around: lastNodeId, after: N }) to continue linearly, outline_doc to jump by heading, or search_docs({ query, docId }) to find a specific passage. For docs under the cap, returns the full body as before.`,
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
         },
         handler: async ({ docId }) => {
             const target = resolveDocTarget(docId);
-            const compact = toCompactFormat(target.document, target.title, target.wordCount, target.pendingCount, target.docId, target.metadata);
+            const trunc = truncateRead(target.document, READ_PAD_MAX_WORDS);
+            const compact = toCompactFormat(trunc.doc, target.title, trunc.returnedWords, target.pendingCount, target.docId, target.metadata);
             const localCount = getCommentCount(target.filename);
             const { totalComments: otherCount, docCount: otherDocs } = getGlobalCommentSummary(target.filename);
             let hint = '';
@@ -234,6 +246,17 @@ export const TOOL_REGISTRY = [
                 hint += `\n[${otherCount} comment${otherCount !== 1 ? 's' : ''} on ${otherDocs} other document${otherDocs !== 1 ? 's' : ''}]`;
             if (hint)
                 hint += '\n[call get_comments to review]';
+            if (trunc.truncated) {
+                if (!firstTruncationShown) {
+                    hint += `\n\n[FYI: read_pad caps at ~${READ_PAD_MAX_WORDS} words to keep cost predictable. This notice shows once per session — future truncations skip the explanation.]`;
+                    firstTruncationShown = true;
+                }
+                const anchor = trunc.lastNodeId ?? '<no-id>';
+                hint += `\n[TRUNCATED — ${trunc.totalWords.toLocaleString()} words total, ${trunc.returnedWords.toLocaleString()} returned, ${trunc.remaining.toLocaleString()} remain. Continue with:`
+                    + `\n  peek_doc({ docId: "${target.docId}", target: { around: "${anchor}", after: 100 } })  — linear continuation`
+                    + `\n  outline_doc({ docId: "${target.docId}" })  — heading skeleton to jump to a section`
+                    + `\n  search_docs({ query: "...", docId: "${target.docId}" })  — find a specific passage]`;
+            }
             return { content: [{ type: 'text', text: compact + hint }] };
         },
     },

package/dist/server/peek-outline.js

@@ -258,6 +258,72 @@ function findTopLevelIndex(content, id) {
     }
     return -1;
 }
+/** Count whitespace-delimited tokens across every text node in `nodes`.
+ *  Mirrors the convention used elsewhere in the server (extractText + split). */
+export function countWords(nodes) {
+    function collect(node) {
+        if (node.type === 'text' && typeof node.text === 'string')
+            return node.text;
+        if (!node.content)
+            return '';
+        return node.content.map(collect).join(' ');
+    }
+    const text = nodes.map(collect).join(' ').trim();
+    if (!text)
+        return 0;
+    return text.split(/\s+/).length;
+}
+/** Truncate a doc at a top-level node boundary so the returned content
+ *  doesn't exceed `maxWords`. Returns the original doc unchanged if it
+ *  already fits. Always includes at least one top-level node so callers
+ *  never receive an empty body.
+ *
+ *  read_pad's contract: a fixed-window read, not a full-body read. Above
+ *  the cap, the agent gets the doc opening (most context-rich slice —
+ *  title, intro, first few sections) plus the lastNodeId so `peek_doc`
+ *  can continue from the boundary, or `outline_doc` / `search_docs` can
+ *  jump elsewhere.
+ *
+ *  Node-boundary truncation (never splits a top-level block) keeps the
+ *  returned slice structurally valid markdown — list items, blockquotes,
+ *  and code blocks stay intact. */
+export function truncateRead(doc, maxWords) {
+    const content = doc.content || [];
+    const totalWords = countWords(content);
+    const lastTopId = (n) => n?.attrs?.id ?? null;
+    if (totalWords <= maxWords) {
+        return {
+            doc,
+            truncated: false,
+            totalWords,
+            returnedWords: totalWords,
+            lastNodeId: lastTopId(content[content.length - 1]),
+            remaining: 0,
+        };
+    }
+    const included = [];
+    let words = 0;
+    let lastNodeId = null;
+    for (const n of content) {
+        const w = countWords([n]);
+        // Always include at least one node — even if it alone exceeds the cap,
+        // an empty body would be a worse failure mode than a slightly oversize one.
+        if (included.length > 0 && words + w > maxWords)
+            break;
+        included.push(n);
+        words += w;
+        if (n.attrs?.id)
+            lastNodeId = n.attrs.id;
+    }
+    return {
+        doc: { ...doc, content: included },
+        truncated: true,
+        totalWords,
+        returnedWords: words,
+        lastNodeId,
+        remaining: totalWords - words,
+    };
+}
 /** Find blocks whose text matches the query inside one doc. Returns up to
  *  `limit` matches with the matched node's ID, type, and a snippet around
  *  the hit. Case-insensitive substring match, same shape as the workspace-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.24.0",
+  "version": "0.25.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",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.14.1"
+  version: "0.15.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -86,9 +86,11 @@ You are a writing collaborator. You read documents and make edits **exclusively
    3. `outline_doc(docId)` — heading tree (~5 tokens per heading)
    4. `search_docs(query, { docId })` — in-doc content search → matching nodeIds
    5. `peek_doc(docId, target)` — windowed node read
-   6. `read_pad(docId)` — full body (escape hatch for "I need everything")
+   6. `read_pad(docId)` — first ~2,000 words of the body, ALWAYS truncated above the cap
 
-   For a 1000-node doc, steps 1–5 cost combined are typically <2k tokens; `read_pad` would be 80k+. Use the ladder.
+   `read_pad` is a fixed-window tool by contract. Docs ≤ ~2,000 words return in full. Above the cap, you get the doc opening (title + intro + first few sections — the most context-rich slice) plus a `lastNodeId` and a continuation hint pointing at `peek_doc({ around: lastNodeId, after: N })`, `outline_doc`, or `search_docs({ query, docId })`. There is no `force` flag — the cap is the contract.
+
+   **Implication for doc structure:** monolith docs (8k+ words in one file) push you up the ladder on every read. Splitting into chapters, sections, or topic-sized docs makes everything cheaper — outline_doc shows the whole shape, browse_docs returns concept-level summaries, and individual reads come back complete. The cap is friction designed to surface monoliths as the wrong unit for AI-assisted writing in this era.
 
 ## Setup — Which Path?
 
@@ -406,25 +408,34 @@ Cost on an 8,000-word chapter doc: ~1.5k tokens via the ladder vs ~10k via `read
 
 ```
 1. get_pad_status  → check pendingChanges and userSignaledReview
-2. read_pad        → get full document with node IDs + docId
+2. Orient on the doc:
+   - Short doc (≤ ~2,000 words): read_pad returns the full body — node IDs included
+   - Long doc (above the cap): outline_doc({ docId }) for shape, then
+     peek_doc({ around: nodeId, before, after }) around the area you'll edit
+     (only need fresh IDs for the region you're touching)
+   - You already know the anchor (from a prior search_docs or deep-link click):
+     skip straight to peek_doc({ around: anchor }) — no full-body read needed
 3. get_metadata    → check tweetContext/articleContext for URLs, mode, tags
 4. write_to_pad({ docId: "a1b2c3d4", changes: [...] })
 5. Wait            → user accepts/rejects in browser
 ```
 
-For surgical edits (you already know the anchor nodeId from prior orientation), substitute step 2 with `peek_doc({ around: nodeId, before, after })` to grab just the relevant region's current node IDs without re-paying for the whole body.
+`read_pad` always returns the doc opening up to ~2,000 words. For broader work on a long doc, walk the outline + peek pages — never assume you got the whole body from one read_pad call. The truncation response includes a `lastNodeId` and continuation hint pointing at exactly which tool to call next.
 
 **For tweet/article docs:** step 3 gives you the parent tweet URL (in `tweetContext.url`) and mode (`reply`/`quote`/`tweet`). Use this URL with fxtwitter to read the parent tweet for free — never search externally for it.
 
 ### Multi-document
 
 ```
-1. list_documents    → see all docs with title + [docId]
-2. read_pad({ docId: "e5f6a7b8" })  → reads that doc directly, no switch needed
-3. write_to_pad({ docId: "e5f6a7b8", changes: [...] })
-                     → edits go to the identified doc, no view switch needed
+1. list_documents               → see all docs with title + [docId] + wordCount
+2. For each target doc, orient first:
+   - Short doc: read_pad({ docId }) returns full body
+   - Long doc: outline_doc({ docId }) → peek_doc({ docId, target: {...} })
+3. write_to_pad({ docId, changes: [...] })  → edits go to the identified doc
 ```
 
+The wordCount on `list_documents` tells you up-front which docs will return in full from `read_pad` and which will truncate. Use it to plan: a 500-word doc is one round trip; an 8,000-word doc is outline + a peek or two.
+
 ### Creating new content (two-step)
 
 ```