openwriter 0.24.0 → 0.26.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,41 @@ 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. Default: first ~${READ_PAD_MAX_WORDS} words. Three knobs for longer docs:\n• \`slice: { from, to }\` — read a percentile range (floats in [0,1]). \`{from:0.5, to:1}\` = back half, \`{from:0.25, to:0.75}\` = middle 50%, \`{from:0.0, to:0.1}\` then \`{from:0.1, to:0.2}\` … = sequential 10% chunks. Snaps to top-level node boundaries; subject to the word cap unless force is set.\n• \`force: true\` — bypass the cap, return the full requested region (whole doc or whole slice). Use for full-doc audits/rewrites where you've accepted the cost.\n• When the cap kicks in, the response includes \`lastNodeId\` + continuation hints to \`peek_doc\` / \`outline_doc\` / \`search_docs\` / another \`read_pad\` slice.`,
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
-        },
-        handler: async ({ docId }) => {
+            // Schemas use z.preprocess to coerce string inputs — some MCP clients
+            // serialize complex / boolean params as JSON strings rather than native
+            // types. Accepting both forms means agents work regardless of client.
+            slice: z.preprocess((v) => (typeof v === 'string' && v.trim().startsWith('{')) ? (() => { try {
+                return JSON.parse(v);
+            }
+            catch {
+                return v;
+            } })() : v, z.object({
+                from: z.number().min(0).max(1).describe('Start of the slice as a fraction of total word count (0 = beginning).'),
+                to: z.number().min(0).max(1).describe('End of the slice as a fraction of total word count (1 = end). Must be > from.'),
+            }).optional()).describe('Percentile range to read instead of the doc opening. Snaps to top-level node boundaries. Examples: { from: 0.5, to: 1 } = back half; { from: 0.25, to: 0.75 } = middle 50%.'),
+            force: z.preprocess((v) => (typeof v === 'string') ? v === 'true' : v, z.boolean().optional()).describe(`Bypass the ~${READ_PAD_MAX_WORDS}-word cap. Returns the full requested region in one call. Use for full-doc audits and rewrites where the cost is acknowledged.`),
+        },
+        handler: async ({ docId, slice, force }) => {
             const target = resolveDocTarget(docId);
-            const compact = toCompactFormat(target.document, target.title, target.wordCount, target.pendingCount, target.docId, target.metadata);
+            const trunc = truncateRead(target.document, { maxWords: READ_PAD_MAX_WORDS, slice, force });
+            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 +259,32 @@ 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]';
+            // Label forced / sliced reads so the response is self-describing.
+            if (trunc.forced) {
+                const region = trunc.slice
+                    ? `forced slice ${(trunc.slice.from * 100).toFixed(0)}–${(trunc.slice.to * 100).toFixed(0)}%`
+                    : 'forced full read';
+                hint += `\n[${region.toUpperCase()} — ${trunc.returnedWords.toLocaleString()} words returned of ${trunc.totalWords.toLocaleString()} total. Cap bypassed.]`;
+            }
+            else if (trunc.slice && !trunc.truncated) {
+                hint += `\n[SLICE ${(trunc.slice.from * 100).toFixed(0)}–${(trunc.slice.to * 100).toFixed(0)}% — ${trunc.returnedWords.toLocaleString()} of ${trunc.totalWords.toLocaleString()} words. Adjacent slices: read_pad({ docId: "${target.docId}", slice: { from: ${trunc.slice.to.toFixed(2)}, to: ${Math.min(1, trunc.slice.to + (trunc.slice.to - trunc.slice.from)).toFixed(2)} } }) for the next region.]`;
+            }
+            else if (trunc.truncated) {
+                if (!firstTruncationShown) {
+                    hint += `\n\n[FYI: read_pad caps at ~${READ_PAD_MAX_WORDS} words to keep cost predictable. Override per-call with force:true, or read a specific region with slice:{from,to}. This notice shows once per session.]`;
+                    firstTruncationShown = true;
+                }
+                const anchor = trunc.lastNodeId ?? '<no-id>';
+                const sliceLabel = trunc.slice
+                    ? ` of slice ${(trunc.slice.from * 100).toFixed(0)}–${(trunc.slice.to * 100).toFixed(0)}%`
+                    : '';
+                hint += `\n[TRUNCATED — ${trunc.totalWords.toLocaleString()} words total, ${trunc.returnedWords.toLocaleString()} returned${sliceLabel}, ${trunc.remaining.toLocaleString()} remain. Continue with:`
+                    + `\n  read_pad({ docId: "${target.docId}", slice: { from: 0.5, to: 1 } })  — read the back half (or any percentile range)`
+                    + `\n  read_pad({ docId: "${target.docId}", force: true })  — entire body, cap bypassed`
+                    + `\n  peek_doc({ docId: "${target.docId}", target: { around: "${anchor}", after: 100 } })  — linear continuation by node`
+                    + `\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,142 @@ 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;
+}
+/** Read a region of a doc, truncated at a top-level node boundary so the
+ *  returned content doesn't exceed `maxWords` (unless `force` is set).
+ *
+ *  Three modes:
+ *  - **Default** (no slice, no force) — first N words of the doc, capped at
+ *    `maxWords`. read_pad's original contract: doc opening + continuation hint.
+ *  - **Slice** (`{ from, to }`) — words in the percentile range. Snaps to top-level
+ *    node boundaries so blocks aren't split mid-sentence. Still subject to
+ *    `maxWords` unless `force` is set; an agent walking 10% chunks of a large
+ *    doc gets predictable per-call cost.
+ *  - **Force** — bypass the cap. Returns the full requested region (whole doc
+ *    if no slice, the whole slice if sliced). Use for full-doc audits and
+ *    rewrites where the agent has explicitly accepted the cost.
+ *
+ *  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, options = {}) {
+    const maxWords = options.maxWords ?? 2000;
+    const force = !!options.force;
+    const sliceIn = options.slice ?? null;
+    // Clamp/validate slice — clamp to [0,1], silently fix swapped or degenerate inputs.
+    let slice = null;
+    if (sliceIn) {
+        const from = Math.max(0, Math.min(1, sliceIn.from));
+        const to = Math.max(0, Math.min(1, sliceIn.to));
+        slice = from < to ? { from, to } : { from: 0, to: 1 };
+    }
+    const content = doc.content || [];
+    const totalWords = countWords(content);
+    const lastTopId = (n) => n?.attrs?.id ?? null;
+    // Empty doc — nothing to slice or truncate.
+    if (content.length === 0) {
+        return {
+            doc,
+            truncated: false,
+            totalWords: 0,
+            returnedWords: 0,
+            firstNodeId: null,
+            lastNodeId: null,
+            remaining: 0,
+            slice,
+            forced: force,
+        };
+    }
+    // Step 1: pick the candidate node range based on slice (or all nodes if no slice).
+    // Word-position-based: walk top-level nodes, snap to boundaries that contain
+    // the slice's word range. A node is included if any of its words fall inside
+    // [fromWord, toWord) — rounds outward, agent always gets whole blocks.
+    let candidateStart = 0;
+    let candidateEnd = content.length;
+    let candidateTotalWords = totalWords;
+    if (slice) {
+        const fromWord = Math.floor(slice.from * totalWords);
+        const toWord = Math.ceil(slice.to * totalWords);
+        let cum = 0;
+        let startIdx = -1;
+        let endIdx = content.length;
+        for (let i = 0; i < content.length; i++) {
+            const w = countWords([content[i]]);
+            const nodeStart = cum;
+            const nodeEnd = cum + w;
+            // Include node if its word span overlaps [fromWord, toWord).
+            if (startIdx === -1 && nodeEnd > fromWord)
+                startIdx = i;
+            if (startIdx !== -1 && nodeStart >= toWord) {
+                endIdx = i;
+                break;
+            }
+            cum += w;
+        }
+        if (startIdx === -1)
+            startIdx = content.length - 1;
+        candidateStart = startIdx;
+        candidateEnd = endIdx;
+        candidateTotalWords = countWords(content.slice(candidateStart, candidateEnd));
+    }
+    // Step 2: apply maxWords cap to the candidate range (unless forced).
+    const candidate = content.slice(candidateStart, candidateEnd);
+    if (force || candidateTotalWords <= maxWords) {
+        const firstNodeId = lastTopId(candidate[0]);
+        const lastNodeId = lastTopId(candidate[candidate.length - 1]);
+        return {
+            doc: { ...doc, content: candidate },
+            truncated: false,
+            totalWords,
+            returnedWords: candidateTotalWords,
+            firstNodeId,
+            lastNodeId,
+            remaining: 0,
+            slice,
+            forced: force,
+        };
+    }
+    // Step 3: candidate exceeds cap — truncate from the start of the candidate
+    // range, including whole top-level blocks until adding the next would exceed
+    // the cap. Always include at least one node.
+    const included = [];
+    let words = 0;
+    let lastNodeId = null;
+    for (const n of candidate) {
+        const w = countWords([n]);
+        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,
+        firstNodeId: lastTopId(included[0]),
+        lastNodeId,
+        remaining: candidateTotalWords - words,
+        slice,
+        forced: false,
+    };
+}
 /** 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.26.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.16.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -85,10 +85,20 @@ You are a writing collaborator. You read documents and make edits **exclusively
    2. `browse_docs({ workspaceFile })` — concept-level shelf scan (~60 tokens per doc)
    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")
+   5. `peek_doc(docId, target)` — windowed node read by nodeId
+   6. `read_pad(docId, ...)` — fixed-window word-position read (default: first ~2,000 words)
 
-   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 default but accepts two knobs for full control:
+
+   - **Default** — `read_pad({ docId })` returns the first ~2,000 words. Docs at or under the cap return in full.
+   - **Slice** — `read_pad({ docId, slice: { from: 0.5, to: 1 } })` reads a percentile range. `{from:0.5, to:1}` = back half, `{from:0.25, to:0.75}` = middle 50%, sequential `{from:0.0,to:0.1}` → `{from:0.1,to:0.2}` … = 10% chunks for whole-doc coverage at predictable per-call cost. Snaps to top-level node boundaries; subject to the cap unless `force` is set.
+   - **Force** — `read_pad({ docId, force: true })` bypasses the cap and returns the full requested region. Use for full-doc audits, rewrites, or anywhere you've explicitly accepted the cost.
+
+   Slice vs peek: peek anchors to a known nodeId (good for "read around this hit"); slice anchors to a word-position percentile (good for "give me the back half" or "walk this doc in 10% chunks"). Use the one that matches your intent — neither is strictly better.
+
+   When the cap kicks in, the response includes `lastNodeId` plus continuation hints for all four follow-up tools (read_pad slice, read_pad force, peek_doc, outline_doc).
+
+   **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 +416,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)
 
 ```