@wrongstack/tools 0.265.1 → 0.267.0

package/dist/index.js

@@ -1,9 +1,9 @@
 import * as fs4 from 'node:fs/promises';
+import { toErrorMessage } from '@wrongstack/core/utils';
 import * as path from 'node:path';
 import { resolve, sep, dirname, join } from 'node:path';
 import * as Core from '@wrongstack/core';
-import { atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, expectDefined, buildChildEnv, isPrivateIPv4, isPrivateIPv6, loadPlan, setPlanItemStatus, savePlan, loadTasks, saveTasks, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, mutateTasks, formatTaskList, formatPlan, recordPackageAction, detectPackageEcosystem, computeTaskItemProgress, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
-import { toErrorMessage } from '@wrongstack/core/utils';
+import { atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, expectDefined, buildChildEnv, isPrivateIPv4, isPrivateIPv6, loadPlan, setPlanItemStatus, savePlan, loadTasks, saveTasks, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, mutateTasks, formatTaskList, formatPlan, assessCommitSafety, recordPackageAction, detectPackageEcosystem, computeTaskItemProgress, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import { spawn, execFileSync, spawnSync } from 'node:child_process';
 import * as os from 'node:os';
 import * as fs7 from 'node:fs';
@@ -168,6 +168,8 @@ function normalizeCommandOutput(raw, opts = {}) {
   text = text.replace(/\n{3,}/g, "\n\n");
   return truncateHeadTail(text, opts.maxBytes ?? COMMAND_OUTPUT_MAX_BYTES);
 }
+
+// src/read.ts
 var MAX_BYTES = 5 * 1024 * 1024;
 var readTool = {
   name: "read",
@@ -194,6 +196,11 @@ var readTool = {
       limit: {
         type: "integer",
         description: "Maximum number of lines to return (default is 2000)."
+      },
+      mode: {
+        type: "string",
+        enum: ["content", "summary"],
+        description: "Return full line-numbered content (default) or a compact file summary with imports/exports/symbols."
       }
     },
     required: ["path"]
@@ -207,14 +214,27 @@ var readTool = {
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") throw new Error(`read: file not found "${input.path}"`);
-      throw new Error(
-        `read: failed to stat "${input.path}": ${toErrorMessage(err)}`
-      );
+      throw new Error(`read: failed to stat "${input.path}": ${toErrorMessage(err)}`);
     }
     if (!stat11.isFile()) throw new Error(`read: "${input.path}" is not a regular file`);
     if (stat11.size > MAX_BYTES) {
       throw new Error(`read: file too large (${stat11.size} bytes, limit ${MAX_BYTES})`);
     }
+    const offset = Math.max(1, input.offset ?? 1);
+    const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
+    const prior = getReadRangeRecord(ctx, absPath);
+    const requestedEnd = prior ? Math.min(offset + limit - 1, prior.totalLines) : offset + limit - 1;
+    if (input.mode !== "summary" && limit > 0 && prior && coversRange(prior, stat11.mtimeMs, offset, requestedEnd)) {
+      ctx.recordRead(absPath, stat11.mtimeMs);
+      return {
+        text: `[unchanged since previous read: "${input.path}" mtime=${Math.round(stat11.mtimeMs)}; requested lines ${offset}-${requestedEnd} were already shown. Use offset/limit for a new range if needed.]`,
+        total_lines: prior.totalLines,
+        encoding: "utf8",
+        truncated: requestedEnd < prior.totalLines,
+        cached: true,
+        note: "Repeated read suppressed to save tokens."
+      };
+    }
     const buf = await fs4.readFile(absPath);
     if (isBinaryBuffer(buf)) {
       throw new Error(`read: "${input.path}" appears to be binary`);
@@ -222,17 +242,38 @@ var readTool = {
     const text = buf.toString("utf8");
     const allLines = text.split(/\r\n|\r|\n/);
     const total = allLines.length;
-    const offset = Math.max(1, input.offset ?? 1);
-    const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
+    if (input.mode === "summary") {
+      ctx.recordRead(absPath, stat11.mtimeMs);
+      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, 1, Math.min(total, 200));
+      return {
+        text: summarizeFile(input.path, stat11.size, allLines),
+        total_lines: total,
+        encoding: "utf8",
+        truncated: total > 200,
+        note: "Summary mode returned compact structure instead of full file content."
+      };
+    }
     if (limit === 0) {
       ctx.recordRead(absPath, stat11.mtimeMs);
+      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, 1, 0);
       return { text: "", total_lines: total, encoding: "utf8", truncated: total > 0 };
     }
+    if (offset > total) {
+      ctx.recordRead(absPath, stat11.mtimeMs);
+      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, total + 1, total + 1);
+      return {
+        text: `[offset ${offset} is past end of file "${input.path}" \u2014 file has ${total} line(s). Do not retry this offset.]`,
+        total_lines: total,
+        encoding: "utf8",
+        truncated: false
+      };
+    }
     const slice = allLines.slice(offset - 1, offset - 1 + limit);
     const truncated = offset - 1 + slice.length < total;
     const width = String(offset + slice.length - 1).length;
     const numbered = slice.map((line, i) => `${String(offset + i).padStart(width, " ")}\u2192${line}`).join("\n");
     ctx.recordRead(absPath, stat11.mtimeMs);
+    rememberReadRange(ctx, absPath, stat11.mtimeMs, total, offset, offset + slice.length - 1);
     return {
       text: numbered,
       total_lines: total,
@@ -241,6 +282,62 @@ var readTool = {
     };
   }
 };
+var READ_RANGES_META_KEY = "tools.read.ranges.v1";
+function getReadRanges(ctx) {
+  const existing = ctx.meta[READ_RANGES_META_KEY];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+    return existing;
+  }
+  const next = {};
+  ctx.meta[READ_RANGES_META_KEY] = next;
+  return next;
+}
+function getReadRangeRecord(ctx, absPath) {
+  return getReadRanges(ctx)[absPath];
+}
+function rememberReadRange(ctx, absPath, mtimeMs, totalLines, start, end) {
+  if (end < start) return;
+  const ranges = getReadRanges(ctx);
+  const prior = ranges[absPath];
+  const nextRanges = prior && Math.abs(prior.mtimeMs - mtimeMs) <= 1 ? prior.ranges.slice() : [];
+  nextRanges.push({ start, end });
+  ranges[absPath] = {
+    mtimeMs,
+    totalLines,
+    ranges: mergeRanges(nextRanges)
+  };
+}
+function coversRange(record, mtimeMs, start, end) {
+  if (Math.abs(record.mtimeMs - mtimeMs) > 1) return false;
+  return record.ranges.some((range) => range.start <= start && range.end >= end);
+}
+function mergeRanges(ranges) {
+  const sorted = ranges.slice().sort((a, b) => a.start - b.start);
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    if (!last || range.start > last.end + 1) {
+      merged.push({ ...range });
+      continue;
+    }
+    last.end = Math.max(last.end, range.end);
+  }
+  return merged;
+}
+function summarizeFile(filePath, bytes, lines) {
+  const interesting = lines.map((line, index) => ({ line: line.trim(), number: index + 1 })).filter(
+    ({ line }) => /^(import\s|export\s|class\s|interface\s|type\s|function\s|const\s+\w+\s*=|let\s+\w+\s*=|var\s+\w+\s*=|def\s+|async\s+function\s)/.test(
+      line
+    )
+  ).slice(0, 80).map(({ line, number }) => `${number}: ${line}`);
+  return [
+    `summary: ${filePath}`,
+    `bytes=${bytes}`,
+    `total_lines=${lines.length}`,
+    interesting.length > 0 ? `symbols/imports:
+${interesting.join("\n")}` : "symbols/imports: (none detected)"
+  ].join("\n");
+}
 var writeTool = {
   name: "write",
   category: "Filesystem",
@@ -309,8 +406,8 @@ var writeTool = {
 var editTool = {
   name: "edit",
   category: "Filesystem",
-  description: "Perform a precise, surgical text replacement in a file. This is the preferred tool for modifying existing code. It requires that you have previously called `read` on the file in the current session. Fails safely if the `old_string` appears more than once unless `replace_all` is set.",
-  usageHint: "MANDATORY WORKFLOW:\n1. Call `read` on the target file first (in the same conversation).\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nThis tool is much safer than `write` for existing files because it works against the last-read version.",
+  description: "Perform a precise, surgical text replacement in a file. This is the preferred tool for modifying existing code. It works best after a prior `read`, but can auto-read the current file when the replacement is still unambiguous. Fails safely if the `old_string` appears more than once unless `replace_all` is set.",
+  usageHint: "RECOMMENDED WORKFLOW:\n1. Prefer calling `read` on the target file first when planning an edit.\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nIf no prior read is recorded, the tool auto-reads the current file and only applies the edit after the same ambiguity checks pass.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -339,9 +436,7 @@ var editTool = {
       throw err;
     });
     if (!stat11.isFile()) throw new Error(`edit: "${input.path}" is not a regular file`);
-    if (!ctx.hasRead(absPath)) {
-      throw new Error(`edit: file "${input.path}" was not read in this session. Read it first.`);
-    }
+    const autoRead = !ctx.hasRead(absPath);
     const original = await fs4.readFile(absPath, "utf8");
     const updated = await fs4.stat(absPath);
     const mtimeTolerance = process.platform === "win32" ? 2e3 : 1;
@@ -349,15 +444,21 @@ var editTool = {
     if (lastReadMtime !== void 0 && updated.mtimeMs > lastReadMtime + mtimeTolerance) {
       throw new Error(`edit: file "${input.path}" was modified externally. Re-read it first.`);
     }
+    if (autoRead && updated.mtimeMs > stat11.mtimeMs + mtimeTolerance) {
+      throw new Error(`edit: file "${input.path}" changed while being auto-read. Retry the edit.`);
+    }
+    const autoReadNote = autoRead ? `No prior read was recorded for "${input.path}"; edit auto-read the current file and applied the replacement only after the ambiguity checks passed.` : void 0;
     const style = detectNewlineStyle(original);
     const fileLf = normalizeToLf(original);
     const oldLf = normalizeToLf(input.old_string);
     const newLf = normalizeToLf(input.new_string);
     if (oldLf === newLf) {
+      if (autoRead) ctx.recordRead(absPath, updated.mtimeMs);
       return {
         path: absPath,
         replacements: 0,
-        diff: "(no-op: old and new are identical)"
+        diff: "(no-op: old and new are identical)",
+        note: autoReadNote
       };
     }
     let count = 0;
@@ -398,7 +499,8 @@ var editTool = {
     return {
       path: absPath,
       replacements: input.replace_all ? count : 1,
-      diff
+      diff,
+      note: autoReadNote
     };
   }
 };
@@ -3167,7 +3269,7 @@ var gitTool = {
   name: "git",
   category: "Git",
   description: "Safe wrapper around common git operations. Supports status, log, diff, commit, branch, checkout, stash, push, pull, fetch, reset, worktree, etc. This is the preferred way to interact with git instead of using the raw `bash` or `exec` tools.",
-  usageHint: "ALWAYS prefer this tool over raw shell git commands.\n\nKey fields:\n- `command`: one of the supported subcommands (status, log, diff, commit, etc.)\n- Use `message` only for commit operations.\n- Use `files` array for operations that take paths (status, diff, add, etc.).\n- Non-mutating commands (status, log, diff, branch, fetch) are still permission:confirm for safety.\nNever pass raw git flags through `args` for dangerous operations \u2014 use the structured fields.",
+  usageHint: "ALWAYS prefer this tool over raw shell git commands.\n\nKey fields:\n- `command`: one of the supported subcommands (status, log, diff, commit, etc.)\n- Use `message` only for commit operations.\n- Use `files` array for operations that take paths (status, diff, add, etc.).\n- Non-mutating commands (status, log, diff, branch, fetch) are still permission:confirm for safety.\n- For `commit` in a possibly-shared working tree, pass an explicit `files` list scoped to what YOU changed. A bare commit (no `files`) includes ALL staged changes and may capture another agent's half-done work. Heed the `warning` field on the result.\nNever pass raw git flags through `args` for dangerous operations \u2014 use the structured fields.",
   permission: "confirm",
   icon: "git",
   // Conservative: any of these may mutate. The non-mutating commands
@@ -3256,6 +3358,22 @@ var gitTool = {
       };
     }
     const args = buildArgs(input);
+    let safetyWarning;
+    if (input.command === "commit") {
+      try {
+        const report = await assessCommitSafety({
+          cwd: ctx.cwd,
+          projectRoot: ctx.projectRoot,
+          sessionId: ctx.session?.id,
+          signal: opts.signal
+        });
+        if (report.warning) {
+          const scopeNote = input.files ? "" : "\nNote: this commit has no explicit `files` list, so it will include ALL staged changes. Pass `files` to scope the commit to only what you changed.";
+          safetyWarning = report.warning + scopeNote;
+        }
+      } catch {
+      }
+    }
     let stagedDiff;
     if (input.command === "commit" && !input.dry_run) {
       try {
@@ -3269,6 +3387,7 @@ var gitTool = {
     }
     const result = await runGit(args, gitDir, opts.signal);
     if (stagedDiff !== void 0) result.diff = stagedDiff;
+    if (safetyWarning !== void 0) result.warning = safetyWarning;
     return result;
   }
 };
@@ -4839,12 +4958,15 @@ var outdatedTool = {
   // fixed four sibling tools (mcp_control, shellcheck, shellcheck_scan,
   // web_search) but missed this one; applying the same contract here.
   mutating: true,
-  // Capability is just "network" — the tool only hits the package
+  // Capability is outbound network — the tool only hits the package
   // registry over HTTP, never touches the filesystem or runs shell.
+  // Use the canonical `net.outbound` capability (not the non-existent
+  // `network` string) so the subagent allowlist recognises it and
+  // permits read-only registry lookups under a director.
   // The H7 invariant test requires this array to be non-empty for
   // any mutating:true tool (meta-tools whitelisted). See
   // tests/permission-mutating-invariant.test.ts:92.
-  capabilities: ["network"],
+  capabilities: ["net.outbound"],
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -9566,8 +9688,8 @@ var TOOL_ICON_CONFIG = {
   // emerald
   folder: { icon: "folder", color: "#8b5cf6" },
   // violet
-  terminal: { icon: "terminal", color: "#ef4444" },
-  // red
+  terminal: { icon: "terminal", color: "#fb923c" },
+  // orange
   web: { icon: "web", color: "#06b6d4" },
   // cyan
   git: { icon: "git", color: "#f97316" },