@nxuss/lemma 1.8.0 → 1.9.0

package/dist/esm/mcp/tools.js

@@ -38,6 +38,8 @@ import { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/C
 import { findMatch, reindentReplacement } from "../utils/PatchMatcher.js";
 import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch.js";
 import { checkAlreadySent, recordSent } from "../utils/ReadWorkspaceCache.js";
+import { mapSqueezedToOriginal, withLineNumbers, sequentialNumbers } from "../utils/LineNumberMap.js";
+import { fileOutline, formatOutline } from "../utils/FileOutline.js";
 import { getCachedSearch, setCachedSearch } from "../utils/SearchCache.js";
 // ── Pro License Gate ──────────────────────────────────────────────────────────
 const LICENSE_FILE = path.join(os.homedir(), '.lemma-cache', 'license.json');
@@ -163,13 +165,16 @@ const toolDefinitions = [
     },
     {
         name: "read_workspace_file",
-        description: "Read a file inside the workspace. Automatically compresses comments/whitespace and scrubs API keys. If this exact file (same compact mode) was already read this session and hasn't changed on disk, returns a short UNCHANGED marker instead of resending the full content — reuse your existing copy. Pass force:true to always get the full content.",
+        description: "Read a file inside the workspace. Compresses comments/whitespace and scrubs API keys. Every line carries its REAL line number in the original file (compression removes lines, it never renumbers them), so you can cite file:line and patch precisely without re-reading. The header lists which imports were compressed away. Use offset/limit to read a line range of a large file. If this exact view was already read this session and hasn't changed on disk, returns an UNCHANGED marker plus a symbol outline — reuse your copy, or pass force:true if it's no longer in your context.",
         inputSchema: {
             type: "object",
             properties: {
                 filePath: { type: "string", description: "Path relative to the project root" },
                 compact: { type: "boolean", description: "Whether to compress comments and whitespace", default: true },
                 force: { type: "boolean", description: "Bypass the unchanged-file short-circuit and always return full content", default: false },
+                lineNumbers: { type: "boolean", description: "Prefix each line with its real line number in the original file", default: true },
+                offset: { type: "number", description: "First line to read (1-indexed). Omit to start at the beginning." },
+                limit: { type: "number", description: "How many lines to read from offset. Omit to read to the end." },
             },
             required: ["filePath"],
         },
@@ -213,7 +218,7 @@ const toolDefinitions = [
     },
     {
         name: "run_workspace_command",
-        description: "Execute a bash command in the workspace root (15s timeout). Captures both stdout and stderr. Long test/build/lint output is distilled deterministically — for jest, vitest and tsc it returns the failing tests or diagnostics with their locations and reasons, dropping code frames and node_modules stack frames; anything else falls back to head/tail plus error-matching lines. The complete output is always stored first and the reply carries a handle: nothing is lost, use output_region to retrieve any part verbatim. Pass raw:true to skip distillation.",
+        description: "Execute a bash command in the workspace root. Default timeout 120s — raise it with timeoutMs for a full test or build run (max 600s). Captures both stdout and stderr, and returns whatever was produced even if the command times out. Long test/build/lint output is distilled deterministically — for jest, vitest and tsc it returns the failing tests or diagnostics with their locations and reasons, dropping code frames and node_modules stack frames; anything else falls back to head/tail plus error-matching lines. The complete output is always stored first and the reply carries a handle: nothing is lost, use output_region to retrieve any part verbatim. Pass raw:true to skip distillation.",
         inputSchema: {
             type: "object",
             properties: {
@@ -223,6 +228,11 @@ const toolDefinitions = [
                     description: "Return the complete untouched output instead of the distilled view",
                     default: false,
                 },
+                timeoutMs: {
+                    type: "number",
+                    description: "Milliseconds before the command is killed (default 120000, max 600000)",
+                    default: 120000,
+                },
             },
             required: ["command"],
         },
@@ -1044,7 +1054,15 @@ const allToolDefinitions = [
 ];
 // Narrow what gets advertised to what this project can actually use. Hidden tools stay
 // registered in `toolHandlers` and callable — both directly and through `lemma_toolbox`.
-const _toolSurface = resolveToolSurface(allToolDefinitions, process.cwd());
+//
+// The entitlement filter matters as much as the project filter: without it a free session
+// advertised the full core surface — read, search, patch, run, AST — and refused fourteen of
+// those twenty tools at call time. That is the worst of both, paying the per-turn schema cost
+// for capabilities the session cannot use. They remain listed in `lemma_toolbox`, so the
+// capability is still discoverable and the upgrade path is still visible.
+const _toolSurface = resolveToolSurface(allToolDefinitions, process.cwd(), {
+    isEntitled: (name) => isProUser() || FREE_TOOLS.has(name),
+});
 const toolDefinitionsArray = _toolSurface.advertised;
 const hiddenToolDefinitions = _toolSurface.hidden;
 /** Serialized size of every tool schema sent to the client, for cost accounting. */
@@ -1437,14 +1455,28 @@ async function handleReadWorkspaceFile(args) {
     const filePath = args?.filePath;
     const compact = args?.compact !== false;
     const force = !!args?.force;
+    const lineNumbers = args?.lineNumbers !== false;
+    const offset = typeof args?.offset === "number" && args.offset > 0 ? Math.floor(args.offset) : undefined;
+    const limit = typeof args?.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : undefined;
     if (!filePath)
         throw new Error("filePath is required");
     const workspaceRoot = process.cwd();
     try {
         const { resolved } = safeResolvePath(workspaceRoot, filePath);
-        let content = fs.readFileSync(resolved, "utf8");
+        const fullContent = fs.readFileSync(resolved, "utf8");
+        const view = { compact, lineNumbers, offset, limit };
+        // The range is applied to the original file, before any compression: `offset` means the
+        // line the user would see in an editor, not a position in the squeezed output.
+        const allLines = fullContent.split("\n");
+        const startIndex = offset ? Math.min(offset - 1, allLines.length) : 0;
+        const endIndex = limit ? Math.min(startIndex + limit, allLines.length) : allLines.length;
+        const ranged = offset || limit ? allLines.slice(startIndex, endIndex).join("\n") : fullContent;
+        const rangeHeader = offset || limit
+            ? `[lines ${startIndex + 1}-${endIndex} of ${allLines.length} in ${filePath}]\n`
+            : "";
+        let content = ranged;
         const originalSize = content.length;
-        const dedup = checkAlreadySent(resolved, compact, content);
+        const dedup = checkAlreadySent(resolved, view, content);
         if (!force && dedup.unchanged) {
             reportSavings({
                 source: "contextSqueeze",
@@ -1453,17 +1485,32 @@ async function handleReadWorkspaceFile(args) {
                 toolName: "read_workspace_file",
                 filePath,
             });
+            // A hash alone is not actionable: the model's context may have been compacted since,
+            // in which case it no longer holds the copy this marker tells it to reuse. The outline
+            // costs ~50 tokens and is enough to either locate what it needs or decide to re-fetch.
+            const outline = formatOutline(fileOutline(content), allLines.length);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `UNCHANGED: ${filePath} is identical to what you already read this session (hash ${dedup.hash.slice(0, 12)}) — reuse your existing copy. Pass force:true to re-fetch anyway.`,
+                        text: [
+                            `UNCHANGED: ${filePath} is identical to what you already read this session (hash ${dedup.hash.slice(0, 12)}) — reuse your existing copy.`,
+                            `If it is no longer in your context, re-fetch with force:true. Structure:`,
+                            outline,
+                        ].join("\n"),
                     },
                 ],
             };
         }
+        // Line numbers are computed against the pre-squeeze text and carried through, so a
+        // compressed read still reports the position the code actually occupies on disk.
+        let numbers = null;
         if (compact) {
-            content = squeezeCode(content);
+            const squeezed = squeezeCode(content);
+            if (lineNumbers) {
+                numbers = mapSqueezedToOriginal(content, squeezed).map((n) => (n === null ? null : n + startIndex));
+            }
+            content = squeezed;
             if (content.length < originalSize) {
                 reportSavings({
                     source: "contextSqueeze",
@@ -1474,16 +1521,26 @@ async function handleReadWorkspaceFile(args) {
                 });
             }
         }
+        else if (lineNumbers) {
+            numbers = sequentialNumbers(content, startIndex + 1);
+        }
         try {
             const scrubber = new SemanticScrubber();
             const { maskedPrompt } = scrubber.mask(content);
+            // Masking must not change the line count, or every number after a masked secret would
+            // be off. If it ever does, drop the gutter rather than print numbers that lie.
+            if (numbers && maskedPrompt.split("\n").length !== content.split("\n").length) {
+                numbers = null;
+            }
             content = maskedPrompt;
         }
         catch (err) {
             logWarn("read_workspace_file", "SemanticScrubber failed, returning raw content");
         }
-        recordSent(resolved, compact, dedup.hash);
-        return { content: [{ type: "text", text: content }] };
+        if (numbers)
+            content = withLineNumbers(content, numbers);
+        recordSent(resolved, view, dedup.hash);
+        return { content: [{ type: "text", text: rangeHeader + content }] };
     }
     catch (err) {
         logError("read_workspace_file", err);
@@ -1535,13 +1592,35 @@ async function handleCreateWorkspaceFile(args) {
         return { content: [{ type: "text", text: `Error creating file: ${err.message}` }] };
     }
 }
+/**
+ * `read_workspace_file` now returns a "123| code" gutter, which makes it easy to paste a block
+ * back into a patch with the numbers still attached. That block matches nothing on disk, so the
+ * patch fails for a reason that has nothing to do with the edit. Strip the gutter when *every*
+ * non-empty line carries one — a uniform prefix is a gutter; a lone "12| " inside real code is
+ * not, and must be left alone.
+ */
+function stripLineNumberGutter(text) {
+    const lines = text.split("\n");
+    const nonEmpty = lines.filter((l) => l.trim().length > 0);
+    if (nonEmpty.length === 0)
+        return text;
+    const GUTTER = /^\s*\d+\|\s?/;
+    if (!nonEmpty.every((l) => GUTTER.test(l)))
+        return text;
+    return lines.map((l) => l.replace(GUTTER, "")).join("\n");
+}
 async function handleApplyWorkspacePatch(args) {
     const filePath = args?.filePath;
-    const searchContent = args?.searchContent;
-    const replaceContent = args?.replaceContent;
-    if (!filePath || !searchContent || replaceContent === undefined) {
+    const rawSearch = args?.searchContent;
+    const rawReplace = args?.replaceContent;
+    if (!filePath || !rawSearch || rawReplace === undefined) {
         throw new Error("filePath, searchContent, and replaceContent are required");
     }
+    const searchContent = stripLineNumberGutter(rawSearch);
+    // Only strip the replacement's gutter when the search block had one too: that pairing means
+    // the model was working from a numbered read. Stripping unconditionally would mangle a
+    // replacement that legitimately contains "1| " (a table, a doc block).
+    const replaceContent = searchContent !== rawSearch ? stripLineNumberGutter(rawReplace) : rawReplace;
     const workspaceRoot = process.cwd();
     try {
         const { resolved } = safeResolvePath(workspaceRoot, filePath);
@@ -1581,10 +1660,19 @@ async function handleApplyWorkspacePatch(args) {
             };
         }
         const match = matchResult[0];
-        const contentLines = originalContent.split("\n");
-        const finalReplace = match.strategy === "exact" ? replaceContent : reindentReplacement(replaceContent, searchContent, contentLines[match.startLine]);
-        const updatedLines = [...contentLines.slice(0, match.startLine), ...finalReplace.split("\n"), ...contentLines.slice(match.endLine + 1)];
-        fs.writeFileSync(resolved, updatedLines.join("\n"), "utf8");
+        let updatedContent;
+        if (match.strategy === "exact" && match.charStart !== undefined && match.charEnd !== undefined) {
+            // Splice by character offset — the search block may be a mid-line fragment, and
+            // a whole-line splice would discard everything else sharing that line.
+            updatedContent = originalContent.slice(0, match.charStart) + replaceContent + originalContent.slice(match.charEnd);
+        }
+        else {
+            const contentLines = originalContent.split("\n");
+            const finalReplace = reindentReplacement(replaceContent, searchContent, contentLines[match.startLine]);
+            const updatedLines = [...contentLines.slice(0, match.startLine), ...finalReplace.split("\n"), ...contentLines.slice(match.endLine + 1)];
+            updatedContent = updatedLines.join("\n");
+        }
+        fs.writeFileSync(resolved, updatedContent, "utf8");
         const note = match.strategy === "exact" ? "" : ` (matched via ${match.strategy}, score ${match.score.toFixed(2)})`;
         return { content: [{ type: "text", text: `Success: Patch successfully applied to ${filePath}${note}` }] };
     }
@@ -1626,32 +1714,38 @@ async function handleRunWorkspaceCommand(args) {
         // stdio is overridden, which silently dropped the output of every tool that reports on
         // stderr (jest and tsc both do) on a successful run. It also gives us stdout, stderr and
         // the exit code through one code path instead of a throw-on-failure split.
+        // 15s was below the runtime of the commands this tool exists for: a real `npm test` or
+        // `tsc --noEmit` always tripped it, so the distillation pipeline never ran on the output
+        // it was built for and the call was pure overhead before falling back to a plain shell.
+        const DEFAULT_TIMEOUT_MS = 120000;
+        const MAX_TIMEOUT_MS = 600000;
+        const requested = typeof args?.timeoutMs === "number" && args.timeoutMs > 0 ? args.timeoutMs : DEFAULT_TIMEOUT_MS;
+        const timeoutMs = Math.min(Math.floor(requested), MAX_TIMEOUT_MS);
         const result = spawnSync(command, {
             cwd: workspaceRoot,
             shell: true,
             encoding: "utf8",
-            timeout: 15000,
+            timeout: timeoutMs,
             maxBuffer: 20 * 1024 * 1024,
             env: { ...process.env },
         });
-        if (result.error) {
-            const timedOut = result.error.code === "ETIMEDOUT";
+        const timedOut = !!result.error && result.error.code === "ETIMEDOUT";
+        if (result.error && !timedOut) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: timedOut
-                            ? `Command timed out after 15s: ${command}`
-                            : `Command could not be executed: ${result.error.message}`,
-                    },
-                ],
+                content: [{ type: "text", text: `Command could not be executed: ${result.error.message}` }],
             };
         }
         const stdout = result.stdout || "";
         const stderr = result.stderr || "";
         const combined = [stdout, stderr].filter((s) => s.trim().length > 0).join("\n");
         const status = result.status ?? 0;
-        const header = status === 0 ? "Command completed successfully." : `Command failed with exit code ${status}.`;
+        // A timed-out run still produced output, and that partial output is normally where the
+        // failure is. Discarding it forced the whole command to be re-run somewhere else.
+        const header = timedOut
+            ? `Command timed out after ${Math.round(timeoutMs / 1000)}s (killed): ${command}\nOutput produced before the kill is below — it may be incomplete. Re-run with a higher timeoutMs if it was still making progress.`
+            : status === 0
+                ? "Command completed successfully."
+                : `Command failed with exit code ${status}.`;
         if (!combined.trim()) {
             return { content: [{ type: "text", text: `${header}\n\n(no output)` }] };
         }