openwriter 0.25.0 → 0.26.0

package/dist/server/mcp.js

@@ -229,13 +229,26 @@ 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. 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.`,
+        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 trunc = truncateRead(target.document, READ_PAD_MAX_WORDS);
+            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);
@@ -246,14 +259,29 @@ 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) {
+            // 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. This notice shows once per session — future truncations skip the explanation.]`;
+                    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>';
-                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`
+                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]`;
             }

package/dist/server/peek-outline.js

@@ -273,41 +273,108 @@ export function countWords(nodes) {
         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 a region of a doc, truncated at a top-level node boundary so the
+ *  returned content doesn't exceed `maxWords` (unless `force` is set).
  *
- *  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.
+ *  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, maxWords) {
+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;
-    if (totalWords <= maxWords) {
+    // 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: totalWords,
-            lastNodeId: lastTopId(content[content.length - 1]),
+            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 content) {
+    for (const n of candidate) {
         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);
@@ -320,8 +387,11 @@ export function truncateRead(doc, maxWords) {
         truncated: true,
         totalWords,
         returnedWords: words,
+        firstNodeId: lastTopId(included[0]),
         lastNodeId,
-        remaining: totalWords - words,
+        remaining: candidateTotalWords - words,
+        slice,
+        forced: false,
     };
 }
 /** Find blocks whose text matches the query inside one doc. Returns up to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.25.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.15.0"
+  version: "0.16.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -85,10 +85,18 @@ 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)` — first ~2,000 words of the body, ALWAYS truncated above the cap
+   5. `peek_doc(docId, target)` — windowed node read by nodeId
+   6. `read_pad(docId, ...)` — fixed-window word-position read (default: first ~2,000 words)
 
-   `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.
+   `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.