@vincemakes/kiso-tools-node 0.34.0 → 0.37.0

package/dist/index.d.ts

@@ -100,6 +100,12 @@ export interface WorkspaceToolsOptions {
      * name — explicit beats the heuristic, as it does for MCP servers.
      */
     readonly shellEnv?: "inherit" | Readonly<Record<string, string>>;
+    /** Astra F7: the env var NAMES the configured profiles authenticate with.
+     *  The strip's suffix rules (`_API_KEY`, `_AUTH_TOKEN`) cannot see a name
+     *  like `REVIEW_PROVIDER_TOKEN`, and only the config knows which names are
+     *  secrets — so it says so. Ignored when `shellEnv` is "inherit", which is
+     *  an explicit opt-in to the whole environment. */
+    readonly secretEnvNames?: readonly string[];
     /**
      * DC-54 — the bounds that keep a tool call finite. Every field is
      * optional and defaults to the constant beside it; a host embedding
@@ -166,6 +172,7 @@ export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<{
     }[];
     expectedRevision?: string;
 }>;
+export { SHELL_STRIP_EXACT, strippedShellEnv } from "./secret-env.js";
 export declare function shellTool(opts: WorkspaceToolsOptions): Tool<{
     command: string;
     timeoutMs?: number;

package/dist/index.js

@@ -27,7 +27,9 @@ import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 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.
  *
@@ -75,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. */
@@ -304,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: {
@@ -397,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()
@@ -662,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")
@@ -945,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 });
                 }
@@ -995,37 +1042,15 @@ export function editFileTool(opts) {
         },
     });
 }
-/**
- * bootstrap #3 (finding #7): the explicit credential list stripped from shell
- * children — the agent's own provider surface (both families' keys, base
- * URLs, and model choices) plus the generic API-key / auth-token patterns
- * that cover other providers. Everything else in the environment passes
- * through untouched.
- */
-const SHELL_STRIP_EXACT = new Set([
-    "ANTHROPIC_API_KEY",
-    "OPENAI_API_KEY",
-    "ANTHROPIC_BASE_URL",
-    "OPENAI_BASE_URL",
-    "ANTHROPIC_MODEL",
-    "OPENAI_MODEL",
-]);
-function strippedShellEnv(env) {
-    const out = {};
-    for (const [key, value] of Object.entries(env)) {
-        if (SHELL_STRIP_EXACT.has(key))
-            continue;
-        if (key.endsWith("_API_KEY") || key.endsWith("_AUTH_TOKEN"))
-            continue;
-        if (value !== undefined)
-            out[key] = value;
-    }
-    return out;
-}
+// Astra F7: the strip is ONE implementation, shared with the MCP
+// extension's stdio children (./secret-env.ts). It used to live here
+// with a hand-kept copy over there; the copy never learned the
+// declared names, which is how MCP children kept leaking.
+export { SHELL_STRIP_EXACT, strippedShellEnv } from "./secret-env.js";
 export function shellTool(opts) {
     return defineTool({
         name: "shell",
-        description: "Run a shell command with the workspace as the working directory. A side effect — approval required. Fails loudly on timeout or non-zero exit.",
+        description: "Run a shell command through /bin/sh with the workspace root as the working directory: builds, tests, git, package managers, curl for HTTP APIs, system queries. Side effects are real; the human may be asked to approve the run. Fails loudly on timeout or non-zero exit.",
         parameters: {
             type: "object",
             properties: {
@@ -1035,7 +1060,7 @@ export function shellTool(opts) {
             required: ["command"],
             additionalProperties: false,
         },
-        promptSnippet: "shell — real system commands only (builds, tests, git)",
+        promptSnippet: "shell — any command the task needs (builds, tests, git, curl, system queries)",
         promptGuidelines: ["commands run in the workspace root; on failure read the error and adjust — never repeat blindly"],
         execute: async ({ command, timeoutMs }, ctx) => {
             const timeout = timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
@@ -1058,7 +1083,7 @@ export function shellTool(opts) {
                     stdio: ["ignore", "pipe", "pipe"],
                     env: opts.shellEnv === "inherit"
                         ? process.env
-                        : { ...strippedShellEnv(process.env), ...(opts.shellEnv ?? {}) },
+                        : { ...strippedShellEnv(process.env, opts.secretEnvNames), ...(opts.shellEnv ?? {}) },
                 });
                 let stdout = "";
                 let stderr = "";

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/dist/secret-env.d.ts

@@ -0,0 +1,27 @@
+/**
+ * THE child-environment strip — ONE implementation, both children.
+ *
+ * bootstrap #3 (finding #7) established the rule for shell children: the
+ * agent's own provider surface (both families' keys, base URLs and model
+ * choices) plus the generic API-key / auth-token patterns that cover other
+ * providers. Everything else passes through untouched.
+ *
+ * Astra F7 then showed the rule was incomplete AND duplicated. Incomplete:
+ * a profile's `apiKeyEnv` can be ANY name — `REVIEW_PROVIDER_TOKEN` ends in
+ * neither suffix — so the key a profile authenticates with survived into
+ * the child. Duplicated: the MCP extension carried its own copy of the list
+ * with a "keep in sync" comment, and a comment is not a mechanism; the copy
+ * did not learn the declared names and MCP stdio children kept leaking.
+ *
+ * The names must come from the caller because only the config knows which
+ * env vars are secrets. No names declared = exactly the pre-F7 behaviour,
+ * which is what a standalone extension load gets.
+ *
+ * This module imports NOTHING on purpose: the MCP extension is an esbuild
+ * bundle, and a shared rule must not drag a package graph across with it.
+ */
+/** The explicit credential list stripped from every child. */
+export declare const SHELL_STRIP_EXACT: ReadonlySet<string>;
+/** The environment a child process may see: `env` minus the exact list,
+ *  minus every DECLARED secret name, minus the two suffix families. */
+export declare function strippedShellEnv(env: Record<string, string | undefined>, secretNames?: readonly string[]): Record<string, string | undefined>;

package/dist/secret-env.js

@@ -0,0 +1,48 @@
+/**
+ * THE child-environment strip — ONE implementation, both children.
+ *
+ * bootstrap #3 (finding #7) established the rule for shell children: the
+ * agent's own provider surface (both families' keys, base URLs and model
+ * choices) plus the generic API-key / auth-token patterns that cover other
+ * providers. Everything else passes through untouched.
+ *
+ * Astra F7 then showed the rule was incomplete AND duplicated. Incomplete:
+ * a profile's `apiKeyEnv` can be ANY name — `REVIEW_PROVIDER_TOKEN` ends in
+ * neither suffix — so the key a profile authenticates with survived into
+ * the child. Duplicated: the MCP extension carried its own copy of the list
+ * with a "keep in sync" comment, and a comment is not a mechanism; the copy
+ * did not learn the declared names and MCP stdio children kept leaking.
+ *
+ * The names must come from the caller because only the config knows which
+ * env vars are secrets. No names declared = exactly the pre-F7 behaviour,
+ * which is what a standalone extension load gets.
+ *
+ * This module imports NOTHING on purpose: the MCP extension is an esbuild
+ * bundle, and a shared rule must not drag a package graph across with it.
+ */
+/** The explicit credential list stripped from every child. */
+export const SHELL_STRIP_EXACT = new Set([
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "ANTHROPIC_BASE_URL",
+    "OPENAI_BASE_URL",
+    "ANTHROPIC_MODEL",
+    "OPENAI_MODEL",
+]);
+/** The environment a child process may see: `env` minus the exact list,
+ *  minus every DECLARED secret name, minus the two suffix families. */
+export function strippedShellEnv(env, secretNames = []) {
+    const declared = new Set(secretNames);
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (SHELL_STRIP_EXACT.has(key))
+            continue;
+        if (declared.has(key))
+            continue;
+        if (key.endsWith("_API_KEY") || key.endsWith("_AUTH_TOKEN"))
+            continue;
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}

package/package.json

@@ -1,13 +1,17 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.34.0",
-	"description": "kiso coding tools for Node hosts — read file, list directory, search text, write/edit file, shell command.",
+	"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",
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
+		},
+		"./secret-env": {
+			"types": "./dist/secret-env.d.ts",
+			"default": "./dist/secret-env.js"
 		}
 	},
 	"files": [
@@ -21,7 +25,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.34.0"
+		"@vincemakes/kiso-core": "0.37.0"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",