smcreader 0.1.2 → 0.1.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "smcreader",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SMC Reader (Save My Context Reader): large tool outputs are spilled to disk and replaced by a short pointer; the model pulls only the lines it needs via reader_ask / reader_peek.",
   "author": { "name": "bulatko" },
   "homepage": "https://github.com/bulatko/SMCReader",

package/.mcp.json

@@ -2,6 +2,6 @@
   "smcreader": {
     "type": "stdio",
     "command": "npx",
-    "args": ["-y", "--omit=optional", "--package=smcreader@0.1.2", "smcreader-mcp"]
+    "args": ["-y", "--omit=optional", "--package=smcreader@0.1.4", "smcreader-mcp"]
   }
 }

package/README.md

@@ -213,6 +213,20 @@ received, not from what it said: (1) the Bash `tool_result` contains `[READER ct
 
 </details>
 
+## What it runs and sends
+
+- **The hook** (`bin/smcreader-hook`, no dependencies, no network) reads the tool output that Claude
+  Code passes to it. If the output is large, the hook writes it to `READER_DIR`
+  (default `~/.cache/smcreader`) and returns the pointer in its place.
+- **The MCP server** comes from the npm registry: the plugin starts it with `npx`
+  (`smcreader@<version>` and its dependencies), and later starts run from npm's cache.
+- **`reader_ask`** sends the document and your question to Claude Haiku through your own Claude
+  Code (`claude`, your credentials), like a subagent would. Those Haiku sessions keep their
+  transcripts under `READER_WORK_DIR`. `reader_open`, `reader_peek`, `reader_list` and
+  `reader_close` run locally.
+- Documents expire 48 h after their last use. There is no telemetry, and nothing else leaves your
+  machine.
+
 ## Limitations
 
 - Needs a Claude Code version that applies `hookSpecificOutput.updatedToolOutput` from command

package/lib/intercept-hook.js

@@ -97,6 +97,23 @@ function headTail(text) {
   return body;
 }
 
+/**
+ * Head of an intercepted Read: whole file lines only, as is. The engine numbers the replacement
+ * like cat -n starting at file.startLine, so file lines must come first — a [READER] header on top
+ * shifted every number by +1, and a tail after "… omitted …" got numbers that are not in the file
+ * (the last line of a 160-line file was shown as line 14). Agents edit by these numbers.
+ */
+function fileHead(text) {
+  const out = [];
+  let size = 0;
+  for (const l of text.split('\n').slice(0, HEAD_LINES)) {
+    if (size + l.length + 1 > POINTER_BODY_CAP) break;
+    out.push(l);
+    size += l.length + 1;
+  }
+  return out;
+}
+
 function describeInput(toolName, toolInput) {
   try {
     if (toolName === 'Bash' && toolInput?.command) return toolInput.command.slice(0, 200);
@@ -149,10 +166,15 @@ function createInterceptHook({ store, threshold = DEFAULT_THRESHOLD, allowlist =
       const docOwner = input.agent_id
         ? `${owner !== undefined ? `${owner}/` : ''}agent:${input.agent_id}`
         : owner;
+      // A Read excerpt (offset) starts at file line startLine: the reader (peek, ask) keeps FILE
+      // numbers, not excerpt numbers.
+      const fileStart = shape === 'file' ? input.tool_response.file.startLine : 1;
+      const startLine = Number.isInteger(fileStart) && fileStart > 1 ? fileStart : 1;
       const r = store.open({ text }, briefing, {
         tool_name: toolName,
         tool_input: inputDesc,
         ...(docOwner !== undefined ? { owner: docOwner } : {}),
+        ...(startLine > 1 ? { lineBase: startLine } : {}),
       });
 
       // Eviction MUST be visible right here: the pointer is the only thing the agent
@@ -162,11 +184,25 @@ function createInterceptHook({ store, threshold = DEFAULT_THRESHOLD, allowlist =
       const evictedNote = r.evicted
         ? `\n(evicted ${r.evicted}${cap ? ` — ${cap}/${cap} open` : ' — reader limit reached'}; close with mcp__reader__reader_close)`
         : '';
-      const pointer =
-        `[READER ${r.id}] ${toolName} output intercepted: ${r.size} bytes, ${r.lines} lines (>${threshold} chars).${evictedNote}\n` +
-        `${headTail(text)}\n` +
-        (typeof askHint === 'function' ? askHint(r.id)
-          : `Full output is in reader ${r.id}: mcp__reader__reader_ask(id, question) to analyze, reader_peek(id, start_line, end_line) for exact lines, reader_close(id) when done.`);
+      const hint = typeof askHint === 'function' ? askHint(r.id)
+        : `Full output is in reader ${r.id}: mcp__reader__reader_ask(id, question) to analyze, reader_peek(id, start_line, end_line) for exact lines, reader_close(id) when done.`;
+      let pointer;
+      if (shape === 'file') {
+        // File lines first, at their real numbers; then one [READER] line that says the numbering
+        // stops being file numbering from here. No tail: it would get numbers that are not in the file.
+        const head = fileHead(text);
+        const last = startLine + r.lines - 1;
+        const hidden = startLine + head.length;
+        pointer = (head.length ? `${head.join('\n')}\n` : '')
+          + `[READER ${r.id}] ${toolName} output intercepted: ${r.size} bytes, file lines ${startLine}–${last} (>${threshold} chars).${evictedNote} `
+          + (head.length ? `Above: file lines ${startLine}–${hidden - 1} verbatim, real numbers. ` : '')
+          + (hidden <= last ? `From this line on the numbers are NOT file lines. Lines ${hidden}–${last} are in the reader; reader_peek takes file line numbers.\n` : '\n')
+          + hint;
+      } else {
+        pointer =
+          `[READER ${r.id}] ${toolName} output intercepted: ${r.size} bytes, ${r.lines} lines (>${threshold} chars).${evictedNote}\n` +
+          `${headTail(text)}\n` + hint;
+      }
 
       // The replacement MUST match the tool's shape — otherwise the engine silently keeps the original.
       const replacement = buildReplacement(input.tool_response, shape, pointer);

package/lib/reader-model.js

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { lineBaseOf } = require('./reader-store');
 
 // cwd for Haiku sessions: their transcripts go to a separate Claude Code project, not the agent's project.
 // The directory is created on the first question, not at module load (the hook and tests don't need it).
@@ -116,6 +117,8 @@ const defaultRunQuery = createRunQuery();
 // accurate. The line text is filled in by the SERVER from the file (store.peek), so it is verbatim
 // by construction: Haiku does not retype or distort code.
 const LINES_CAP = 160;   // lines shown verbatim in one answer; the rest are listed as ranges for reader_peek
+const LINES_BYTES_CAP = 16 * 1024;   // and bytes: long lines (minified JSON, one-line logs) must not flood the agent's window
+const LINE_CHARS_CAP = 2000;         // a longer line is shown by its start, marked as truncated
 
 // NOTICED is not requested in lines mode: scanning the whole document for "anything else suspicious"
 // made the first answer take 12–16 s versus 7–9 s without it, while subagents typically ask a document
@@ -141,10 +144,12 @@ function extractJson(raw) {
 function renderLines(store, entry, raw) {
   const j = extractJson(raw);
   if (!j || !Array.isArray(j.ranges)) return `(answer not in lines format — shown as is)\n${raw}`;
-  const total = entry.meta.lines;
+  // Source numbers (lineBase of a Read excerpt with offset): Haiku saw them in numberLines.
+  const base = lineBaseOf(entry);
+  const last = base + entry.meta.lines - 1;
   const rs = j.ranges
     .map(r => (Array.isArray(r) ? r : [r, r]))
-    .map(([a, b]) => [Math.max(1, Math.floor(Number(a))), Math.min(total, Math.floor(Number(b ?? a)))])
+    .map(([a, b]) => [Math.max(base, Math.floor(Number(a))), Math.min(last, Math.floor(Number(b ?? a)))])
     .filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b) && a <= b)
     .sort((x, y) => x[0] - y[0]);
   const merged = [];
@@ -153,26 +158,44 @@ function renderLines(store, entry, raw) {
     if (last && r[0] <= last[1] + 1) last[1] = Math.max(last[1], r[1]); else merged.push([...r]);
   }
   let budget = LINES_CAP;
+  let bytes = LINES_BYTES_CAP;
+  let byBytes = false;
   const parts = [];
   const cut = [];
   for (const [a, b] of merged) {
-    if (budget <= 0) { cut.push(`${a}-${b}`); continue; }
+    if (budget <= 0 || bytes <= 0) { cut.push(`${a}-${b}`); continue; }
     const e = Math.min(b, a + budget - 1);
-    parts.push(store.peek(entry.id, a, e));
-    budget -= e - a + 1;
-    if (e < b) cut.push(`${e + 1}-${b}`);
+    // A byte cap too: 160 lines of minified JSON are hundreds of KB in one answer — exactly what
+    // the reader exists to keep out of the window. A line longer than LINE_CHARS_CAP is shown by
+    // its start with an explicit mark, so it is never passed off as verbatim.
+    const kept = [];
+    for (const row of store.peek(entry.id, a, e).split('\n')) {
+      if (bytes <= 0) { byBytes = true; break; }
+      const shown = row.length > LINE_CHARS_CAP
+        ? `${row.slice(0, LINE_CHARS_CAP)}… [line truncated: ${row.length - LINE_CHARS_CAP} more chars — reader_peek]` : row;
+      kept.push(shown);
+      bytes -= Buffer.byteLength(shown, 'utf8') + 1;
+    }
+    parts.push(kept.join('\n'));
+    budget -= kept.length;
+    const shownEnd = a + kept.length - 1;
+    if (shownEnd < b) cut.push(`${shownEnd + 1}-${b}`);
   }
   let out = j.note ? String(j.note).trim() : '';
-  out += parts.length ? `\n\n${parts.join('\n…\n')}` : '\n\n(no lines given — not in document)';
-  if (cut.length) out += `\n\n(not shown due to the ${LINES_CAP}-line limit: ${cut.join(', ')} — use reader_peek)`;
+  // Ranges were named but none is usable (outside the document, "12-20" instead of [12,20]) — that
+  // is not "not in document": the reader's answer is broken, and the agent must see it.
+  out += parts.length ? `\n\n${parts.join('\n…\n')}`
+    : j.ranges.length ? `\n\n(the reader named lines ${JSON.stringify(j.ranges).slice(0, 120)}, but the document has no such lines — it has lines ${base}–${last}; ask again or use reader_peek)`
+      : '\n\n(no lines given — not in document)';
+  if (cut.length) out += `\n\n(not shown due to the ${LINES_CAP}-line${byBytes || bytes <= 0 ? ` or ${LINES_BYTES_CAP}-byte` : ''} limit: ${cut.join(', ')} — use reader_peek)`;
   if (Array.isArray(j.noticed)) {
     out += j.noticed.length ? `\n\nNOTICED:\n${j.noticed.map(x => `- ${x}`).join('\n')}` : '\n\nNOTICED: nothing new';
   }
   return out.trim();
 }
 
-function numberLines(text) {
-  return text.split('\n').map((l, i) => `${i + 1}\t${l}`).join('\n');
+function numberLines(text, base = 1) {
+  return text.split('\n').map((l, i) => `${i + base}\t${l}`).join('\n');
 }
 
 /**
@@ -203,9 +226,11 @@ async function ask(store, entry, question, runQuery = defaultRunQuery, opts = {}
     const q = lines ? question + linesInstruction() : question;
     let prompt;
     if (!base) {
-      const doc = numberLines(store.readRaw(entry.id));
+      const lb = lineBaseOf(entry);
+      const doc = numberLines(store.readRaw(entry.id), lb);
       const note = entry.rehydrated ? '\n(Note: a previous dialog about this document was reset by a server restart.)' : '';
-      prompt = `${READER_FRAMING}\n\nBRIEFING from the main agent: ${entry.meta.briefing}${note}\n\n--- DOCUMENT ${entry.id} (${entry.meta.lines} lines, ${entry.meta.size} bytes, source: ${entry.meta.source.path || 'inline text'}) ---\n${doc}\n--- END DOCUMENT ---\n\nFirst question: ${q}`;
+      const span = lb > 1 ? `, source lines ${lb}–${lb + entry.meta.lines - 1}` : '';
+      prompt = `${READER_FRAMING}\n\nBRIEFING from the main agent: ${entry.meta.briefing}${note}\n\n--- DOCUMENT ${entry.id} (${entry.meta.lines} lines${span}, ${entry.meta.size} bytes, source: ${entry.meta.source.path || 'inline text'}) ---\n${doc}\n--- END DOCUMENT ---\n\nFirst question: ${q}`;
     } else {
       prompt = q;
     }
@@ -227,4 +252,4 @@ async function ask(store, entry, question, runQuery = defaultRunQuery, opts = {}
   return run.finally(() => { entry.inFlight--; });
 }
 
-module.exports = { ask, createRunQuery, defaultRunQuery, resolveClaudeExecutable, READER_FRAMING, numberLines, renderLines, extractJson, LINES_CAP };
+module.exports = { ask, createRunQuery, defaultRunQuery, resolveClaudeExecutable, READER_FRAMING, numberLines, renderLines, extractJson, LINES_CAP, LINES_BYTES_CAP, LINE_CHARS_CAP };

package/lib/reader-store.js

@@ -39,6 +39,15 @@ const PREVIEW_TAIL = 10;
 const PREVIEW_CHAR_CAP = 1500;
 const PEEK_MAX_LINES = 400;
 
+/**
+ * Source line number the document starts at: an intercepted Read(offset=219) holds file lines
+ * 219…, and meta.lineBase = 219 keeps peek/ask/lines answers in FILE numbers. Default 1.
+ */
+function lineBaseOf(entry) {
+  const b = entry && entry.meta && Number(entry.meta.lineBase);
+  return Number.isInteger(b) && b > 1 ? b : 1;
+}
+
 function createReaderStore({ dir, now = Date.now, log = console.log } = {}) {
   if (!dir) throw new Error('createReaderStore requires {dir}');
   fs.mkdirSync(dir, { recursive: true });
@@ -233,18 +242,24 @@ function createReaderStore({ dir, now = Date.now, log = console.log } = {}) {
     }
   }
 
-  /** Verbatim numbered slice from DISK. 1-based, inclusive; clamped to bounds. */
+  /**
+   * Verbatim numbered slice from DISK. Inclusive; clamped to bounds.
+   * Numbers are SOURCE numbers: for an excerpt Read(offset=219) the first document line is file
+   * line 219 (meta.lineBase), and peek(id, 219, 219) returns it. Without lineBase — from 1.
+   */
   function peek(id, startLine, endLine) {
     const entry = get(id);
     if (!entry) throw new Error(`no reader '${id}'`);
     const lines = fs.readFileSync(entry.rawPath, 'utf8').split('\n');
-    const start = Math.max(1, Math.min(startLine, lines.length));
-    const end = Math.max(1, Math.min(endLine, lines.length));
+    const base = lineBaseOf(entry);
+    const last = base + lines.length - 1;
+    const start = Math.max(base, Math.min(startLine, last));
+    const end = Math.max(base, Math.min(endLine, last));
     if (start > end) throw new Error(`start_line ${startLine} > end_line ${endLine}`);
     if (end - start + 1 > PEEK_MAX_LINES) {
       throw new Error(`span is ${end - start + 1} lines (max ${PEEK_MAX_LINES}). Narrow the range`);
     }
-    return lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join('\n');
+    return lines.slice(start - base, end - base + 1).map((l, i) => `${start + i}\t${l}`).join('\n');
   }
 
   /** Read the whole raw file (for the haiku reader on the first ask). */
@@ -303,7 +318,9 @@ function createReaderStore({ dir, now = Date.now, log = console.log } = {}) {
     if (entry.meta.tooLargeForAsk) {
       return { ok: false, reason: `document is ${entry.meta.size} bytes (ask limit ${ASK_MAX}). Use reader_peek for verbatim ranges, Grep the source, or open a smaller excerpt with {text}` };
     }
-    if (entry.asks >= MAX_ASKS) {
+    // In-flight questions count: asks grows only when a question completes, so a batch of
+    // parallel questions used to pass this check all at once (asks=19 + 8 parallel → 27 of 20).
+    if (entry.asks + (entry.inFlight || 0) >= MAX_ASKS) {
       return { ok: false, reason: `ask limit reached (${MAX_ASKS}) for this reader. Close it and reopen with a fresh briefing` };
     }
     return { ok: true };
@@ -313,4 +330,4 @@ function createReaderStore({ dir, now = Date.now, log = console.log } = {}) {
   return { open, get, peek, readRaw, close, list, canAsk, sweep, limits: { OPEN_MAX, ASK_MAX, MAX_OPEN, MAX_ASKS, PEEK_MAX_LINES } };
 }
 
-module.exports = { createReaderStore };
+module.exports = { createReaderStore, lineBaseOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smcreader",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SMC Reader (Save My Context Reader): pull-model reading of large tool outputs for Claude Code. A PostToolUse hook spills big outputs to disk and leaves a short pointer; an MCP server returns only the lines or answers the model asks for.",
   "license": "MIT",
   "author": "bulatko",