@vincemakes/kiso-tools-node 0.36.0 → 0.37.0

package/dist/index.js

@@ -29,6 +29,7 @@ import { defineTool } from "@vincemakes/kiso-core";
 // WR-1/WR-1A — the revision-guard primitives (unit-tested in wr1a-coda):
 import { strippedShellEnv } from "./secret-env.js";
 import { contentRevision, normalizeRevision, postEffectEscape, precondition, publishNewFile, revalidateBeforeRename } from "./wr1.js";
+import { describeSearchMiss } from "./search-miss.js";
 /**
  * TUI2-R1 (C) — THE SHELL PROGRESS SIDECAR.
  *
@@ -76,6 +77,12 @@ const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 // red line: every truncation names its continuation — the model always
 // has a path to the full content.
 const DEFAULT_READ_LINES = 200;
+/** The default window's SECOND bound, and the one lines cannot express: 200
+ *  lines of minified source is megabytes, 200 lines of prose is a few KB.
+ *  Whichever binds first wins, and the cut is always at a line boundary. An
+ *  explicit `limit` is the caller saying what they want and is not capped
+ *  here — the 100k output cap still applies to it. */
+const DEFAULT_READ_CHARS = 16_000;
 /** R3: how many files a search may read before it hands the event loop
  *  back. Small enough that the 200ms motion cadence never misses a beat,
  *  large enough that the yield costs nothing on a small tree. */
@@ -305,13 +312,17 @@ const INODE_SCAN_MS = 2_000;
 /** The "… N more lines" note — the actionable continuation: the exact
  *  line the next read must start at, so the model can always reach the
  *  full content in ranges (the red line). */
-function moreLinesNote(nextOffset, remaining) {
-    return `\n… ${remaining} more ${remaining === 1 ? "line" : "lines"} (call again with offset=${nextOffset})`;
+function moreLinesNote(nextOffset, remaining, limit) {
+    // BOTH parameters. Naming only `offset` was an instruction to read the
+    // rest of the file: with `limit` absent the read runs to EOF, so a model
+    // following its own continuation note defeated the window from the second
+    // read onward. Measured before the fix: 7.3% of real reads took that path.
+    return `\n… ${remaining} more ${remaining === 1 ? "line" : "lines"} (call again with offset=${nextOffset} limit=${limit})`;
 }
 export function readFileTool(opts) {
     return defineTool({
         name: "read_file",
-        description: "Read a workspace file or a range (offset/limit; default: the first 200 lines, with a continuation note). The final [rev:X] line identifies the version read.",
+        description: "Read a workspace file or a range. Without `limit`: 200 lines or 16000 chars from `offset` (default 1), whichever binds, then a note naming the next offset and limit. The final [rev:X] line identifies the version read.",
         parameters: {
             type: "object",
             properties: {
@@ -398,21 +409,44 @@ export function readFileTool(opts) {
                         errorKind: "invalid_input",
                     };
                 }
-                const end = limit === undefined ? total : Math.min(start + limit - 1, total);
-                // DEFAULT: the head 200 lines; a larger file ends with the
-                // honest continuation note (small files ≤ 200 lines are
-                // byte-identical to the pre-token-round behavior).
+                // THE DEFAULT WINDOW applies whenever `limit` is ABSENT, from
+                // `offset ?? 1`. It used to apply only when BOTH were absent,
+                // so an offset alone read to the end of the file — and since
+                // the note named only `offset`, a model following its own
+                // continuation note left the window behind after one read.
                 let text;
                 let note = "";
-                if (offset === undefined && limit === undefined) {
-                    text = total <= DEFAULT_READ_LINES ? content : parts.slice(0, DEFAULT_READ_LINES).join("\n");
-                    if (total > DEFAULT_READ_LINES)
-                        note = moreLinesNote(DEFAULT_READ_LINES + 1, total - DEFAULT_READ_LINES);
+                if (limit === undefined) {
+                    const lastLine = Math.min(start + DEFAULT_READ_LINES - 1, total);
+                    const slice = parts.slice(start - 1, lastLine);
+                    let body = slice.join("\n");
+                    let shown = slice.length;
+                    if (body.length > DEFAULT_READ_CHARS) {
+                        const cut = body.lastIndexOf("\n", DEFAULT_READ_CHARS);
+                        if (cut > 0) {
+                            body = body.slice(0, cut);
+                            shown = body.split("\n").length;
+                        }
+                        else {
+                            // No newline inside the budget: the first line alone
+                            // is over it. One WHOLE line is the smallest honest
+                            // answer — a cut mid-line is a lie about the file.
+                            body = slice[0] ?? "";
+                            shown = 1;
+                        }
+                    }
+                    // The whole file from line 1 is returned VERBATIM, trailing
+                    // newline included: `parts.join` would drop it.
+                    text = start === 1 && shown === total ? content : body;
+                    const next = start + shown;
+                    if (next <= total)
+                        note = moreLinesNote(next, total - next + 1, DEFAULT_READ_LINES);
                 }
                 else {
+                    const end = Math.min(start + limit - 1, total);
                     text = parts.slice(start - 1, end).join("\n");
                     if (end < total)
-                        note = moreLinesNote(end + 1, total - end);
+                        note = moreLinesNote(end + 1, total - end, limit);
                 }
                 // The output cap's cut must STAY actionable: cut at a line
                 // boundary and name the exact next offset (the generic cap()
@@ -663,7 +697,12 @@ export function searchTextTool(opts) {
             // CX-1 F4 (audit F4): the walk-and-match runs on its OWN thread, which
             // the deadline and the abort both TERMINATE. A catastrophic regex used
             // to block this loop — no budget check, timer or abort could run.
-            const outcome = await runSearchWorker({ token: 0, root: searchRootReal, single, pattern, flags, excluded, maxFileBytes, maxFiles, deadline, maxMatches: MAX_SEARCH_MATCHES, sniffBytes: BINARY_SNIFF_BYTES }, deadline, ctx.signal);
+            const outcome = await runSearchWorker(
+            // The workspace root is realpath'd with the SAME helper the search
+            // root uses: `full` is walked from a realpath'd root, and making
+            // a path relative between a resolved and an unresolved base
+            // yields `../..` the moment a symlink sits between them.
+            { token: 0, root: searchRootReal, workspaceRoot: realOrSelf(opts.workspaceRoot), single, pattern, flags, excluded, maxFileBytes, maxFiles, deadline, maxMatches: MAX_SEARCH_MATCHES, sniffBytes: BINARY_SNIFF_BYTES }, deadline, ctx.signal);
             if (outcome.kind === "aborted")
                 return { content: "search_text aborted", isError: true, errorKind: "fatal" };
             if (outcome.kind === "error")
@@ -946,7 +985,14 @@ export function editFileTool(opts) {
                         // WR-1A ④: the WORLD lacks the pattern (the input is
                         // fine) and nothing ran — precondition; the note never
                         // rides an edit that wrote nothing.
-                        return precondition(hunks.length === 1 && edits === undefined ? `edit_file: pattern not found in ${path}` : `edit_file: pattern not found in ${path} (hunk ${i + 1})`);
+                        // The headline says WHAT failed; the detail says WHERE.
+                        // A refusal that names the divergence costs one line
+                        // here and saves a whole file read at the caller.
+                        const headline = hunks.length === 1 && edits === undefined
+                            ? `edit_file: pattern not found in ${path}`
+                            : `edit_file: pattern not found in ${path} (hunk ${i + 1})`;
+                        const detail = describeSearchMiss(text, h.search);
+                        return precondition(detail ? `${headline}\n${detail}` : headline);
                     }
                     spans.push({ start: at, end: at + h.search.length, replace: h.replace });
                 }

package/dist/search-miss.d.ts

@@ -0,0 +1,24 @@
+/**
+ * When a search does not match, say WHERE it stopped matching.
+ *
+ * `edit_file: pattern not found in src/report.js (hunk 2)` is true and
+ * useless. The tool has already established, by failing, that the text is
+ * not there — but it also knows, or can cheaply find out, how much of the
+ * search DID match and what the file has instead. Withholding that leaves
+ * one recourse: read the whole file again.
+ *
+ * This is not a guess about what callers need. Ten refused edits in one
+ * measured session were all `pattern not found`, none stale, none
+ * overlapping, and in every one of them a long prefix matched before the
+ * search ran into text the caller had not written yet — 93 of 223
+ * characters, 94 of 286, 306 of 913. Four more searched for an import
+ * line with the new symbol ALREADY IN IT. The failure has one shape: the
+ * search describes the file as it will be, not as it is. A message that
+ * names the divergence answers that in one line; the current one costs a
+ * whole file read to discover.
+ */
+/**
+ * The detail lines for a failed search, or "" when there is nothing useful
+ * to say. The caller owns the headline; this is what follows it.
+ */
+export declare function describeSearchMiss(text: string, search: string): string;

package/dist/search-miss.js

@@ -0,0 +1,89 @@
+/**
+ * When a search does not match, say WHERE it stopped matching.
+ *
+ * `edit_file: pattern not found in src/report.js (hunk 2)` is true and
+ * useless. The tool has already established, by failing, that the text is
+ * not there — but it also knows, or can cheaply find out, how much of the
+ * search DID match and what the file has instead. Withholding that leaves
+ * one recourse: read the whole file again.
+ *
+ * This is not a guess about what callers need. Ten refused edits in one
+ * measured session were all `pattern not found`, none stale, none
+ * overlapping, and in every one of them a long prefix matched before the
+ * search ran into text the caller had not written yet — 93 of 223
+ * characters, 94 of 286, 306 of 913. Four more searched for an import
+ * line with the new symbol ALREADY IN IT. The failure has one shape: the
+ * search describes the file as it will be, not as it is. A message that
+ * names the divergence answers that in one line; the current one costs a
+ * whole file read to discover.
+ */
+/** The longest prefix of `needle` that occurs in `hay`, by length.
+ *
+ *  Monotone — if a prefix occurs then so does every shorter one — so this
+ *  binary-searches instead of walking. A linear walk is O(m) substring
+ *  searches, which on a large file and a long search is the kind of cost
+ *  that turns a better error message into a worse tool.
+ */
+function longestMatchingPrefix(hay, needle) {
+    let lo = 0;
+    let hi = needle.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (hay.includes(needle.slice(0, mid)))
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/** 1-based line number of an offset. */
+function lineAt(text, offset) {
+    let n = 1;
+    for (let i = 0; i < offset && i < text.length; i += 1)
+        if (text.charCodeAt(i) === 10)
+            n += 1;
+    return n;
+}
+/** A fragment for a one-line message: escaped, and bounded. */
+function fragment(s, max = 60) {
+    const cut = s.slice(0, max);
+    const shown = JSON.stringify(cut).slice(1, -1); // drop the quotes, keep \n and \t visible
+    return s.length > max ? `${shown}…` : shown;
+}
+/**
+ * The detail lines for a failed search, or "" when there is nothing useful
+ * to say. The caller owns the headline; this is what follows it.
+ */
+export function describeSearchMiss(text, search) {
+    if (search.length === 0)
+        return "";
+    const matched = longestMatchingPrefix(text, search);
+    if (matched === 0) {
+        const firstLine = search.split("\n", 1)[0] ?? "";
+        return `  no part of it appears in the file — it begins "${fragment(firstLine)}"`;
+    }
+    // First occurrence, matching the tool's own first-occurrence semantics.
+    const at = text.indexOf(search.slice(0, matched));
+    const endOfMatch = at + matched;
+    const line = lineAt(text, at);
+    const endLine = lineAt(text, endOfMatch);
+    const head = `  ${matched} of ${search.length} characters matched, from line ${line} to line ${endLine}`;
+    const rest = search.slice(matched);
+    // RUNNING PAST THE END IS THE COMMON CASE AND ITS OWN SENTENCE. Four of
+    // the ten refusals in the measured session ended exactly here, and
+    // rendering that as `the file then has: ""` buries the one fact worth
+    // having: there is no more file. A caller that appended what it meant
+    // to ADD onto the end of what it meant to FIND reads its own mistake
+    // off this line.
+    if (endOfMatch >= text.length) {
+        return [
+            head,
+            `  the file ENDS there — your search continues for ${rest.length} more characters: "${fragment(rest)}"`,
+        ].join("\n");
+    }
+    return [
+        head,
+        `  the file then has:  "${fragment(text.slice(endOfMatch))}"`,
+        `  your search wanted: "${fragment(rest)}"`,
+    ].join("\n");
+}

package/dist/search-worker.d.ts

@@ -18,6 +18,12 @@
 export interface SearchRequest {
     readonly token: number;
     readonly root: string;
+    /** The WORKSPACE root, which is not always the search root: a search under
+     *  `packages/runtime` must still name `packages/runtime/src/run.ts` so the
+     *  result can be handed to `read_file` unchanged. Realpath'd by the
+     *  caller, because `full` is walked from a realpath'd root and a mixed
+     *  pair produces `../..` the moment a symlink is involved. */
+    readonly workspaceRoot: string;
     /** a single file to scan instead of walking `root` */
     readonly single: string | null;
     readonly pattern: string;

package/dist/search-worker.js

@@ -16,7 +16,7 @@
  * message from a superseded worker is ignored.
  */
 import { open, readdir } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
 import { isMainThread, parentPort } from "node:worker_threads";
 export async function runSearch(req) {
     const regex = new RegExp(req.pattern, req.flags);
@@ -77,8 +77,11 @@ export async function runSearch(req) {
             for (const [i, line] of text.split("\n").entries()) {
                 if (regex.test(line)) {
                     totalMatches += 1;
+                    // WORKSPACE-RELATIVE, not absolute: `read_file` refuses an
+                    // absolute path, so an absolute hit here is a result the
+                    // model cannot feed back without rewriting it by hand.
                     if (matches.length < req.maxMatches)
-                        matches.push(`${full}:${i + 1}: ${line.trim().slice(0, 160)}`);
+                        matches.push(`${relative(req.workspaceRoot, full) || basename(full)}:${i + 1}: ${line.trim().slice(0, 160)}`);
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.36.0",
+	"version": "0.37.0",
 	"description": "kiso coding tools for Node hosts \u2014 read file, list directory, search text, write/edit file, shell command.",
 	"type": "module",
 	"license": "MIT",
@@ -25,7 +25,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.36.0"
+		"@vincemakes/kiso-core": "0.37.0"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",