@vincemakes/kiso-tools-node 0.24.5 → 0.26.0

package/dist/index.d.ts

@@ -91,14 +91,36 @@ export interface WorkspaceToolsOptions {
      * STRIPPED — a shell command must not inherit the agent's API keys (a
      * nested kiso would hit the REAL provider and blow up faux e2e runs;
      * the keys are an exposure surface for any command).
+     *
+     * ADR-0031 Amendment 1: a RECORD is the third shape — the STRIPPED
+     * environment plus these explicit entries, the entries winning (the
+     * MCP surface's decision 2, applied here). An embedding host injects
+     * what its tools need without a temp file and without opening the
+     * whole environment; an entry may deliberately re-add a stripped
+     * name — explicit beats the heuristic, as it does for MCP servers.
      */
-    readonly shellEnv?: "inherit";
+    readonly shellEnv?: "inherit" | Readonly<Record<string, 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
      * kiso over an unusually large or unusually small tree can move them,
      * and the gate can set them low enough to observe the stop.
      */
+    /**
+     * DC-49 — roots a WALK may not descend into, as realpaths.
+     *
+     * The CLI passes `$KISO_HOME`. With the workspace at `~` the walks
+     * otherwise report the user's own session logs as though they were
+     * their work — and `~/.kiso` escapes the dot-name skip only by
+     * accident, so a KISO_HOME anywhere else is walked in full.
+     *
+     * DISCOVERY, NOT ACCESS. This removes a directory from what a walk
+     * FINDS when it descends from above. A path the user or the model
+     * NAMES is still served, at the root or inside it: the exclusion is
+     * not a permission, and anything the model can name it can still
+     * read.
+     */
+    readonly excludeRoots?: readonly string[];
     readonly limits?: {
         /** search_text: skip a file larger than this (default 1 MiB). */
         readonly searchMaxFileBytes?: number;

package/dist/index.js

@@ -562,7 +562,35 @@ export function searchTextTool(opts) {
             // the call budget: a silent skip is a result the model cannot
             // tell is incomplete.
             let skippedFiles = 0;
+            let excludedDirs = 0;
             let filesSeen = 0;
+            // DC-49 — realpath on BOTH sides, so a symlinked HOME still
+            // matches (the reviewer's constraint (d): `/tmp` is a symlink to
+            // `/private/tmp` on darwin, and a raw string compare there is a
+            // gate that passes on one machine and not another).
+            //
+            // A root that CONTAINS the search root is not an exclusion: the
+            // caller pointed at it, and refusing would make an explicit path
+            // unservable. That is the reviewer's constraint (c), expressed
+            // where it belongs — in the predicate, not in four call sites.
+            const realOrSelf = (p) => {
+                try {
+                    return realpathSync(p);
+                }
+                catch {
+                    return p;
+                }
+            };
+            const searchRootReal = realOrSelf(root);
+            const excluded = (opts.excludeRoots ?? [])
+                .map(realOrSelf)
+                .filter((ex) => !(searchRootReal === ex || searchRootReal.startsWith(`${ex}/`)));
+            const isExcluded = (dir) => {
+                if (excluded.length === 0)
+                    return false;
+                const r = realOrSelf(dir);
+                return excluded.some((ex) => r === ex || r.startsWith(`${ex}/`));
+            };
             // An explicit flag, NOT `stoppedAt > 0`: a wall-clock budget can
             // expire before the first file is scanned, and a zero-valued
             // sentinel would then read as "never stopped" — the walk would
@@ -742,8 +770,18 @@ export function searchTextTool(opts) {
                     if (entry.name.startsWith(".") || entry.name === "node_modules")
                         continue;
                     const full = join(dir, entry.name);
-                    if (entry.isDirectory())
+                    if (entry.isDirectory()) {
+                        // DC-49 — a walk does not DESCEND into an excluded root.
+                        // Reaching it from above is what is refused; being
+                        // pointed at it is not (see `excluded` below, which is
+                        // seeded from the SEARCH ROOT and therefore empty when
+                        // the root is itself excluded).
+                        if (isExcluded(full)) {
+                            excludedDirs += 1;
+                            continue;
+                        }
                         await walk(full, depth + 1);
+                    }
                     else if (entry.isFile())
                         await scanFile(full);
                 }
@@ -766,6 +804,12 @@ export function searchTextTool(opts) {
                 content += `\n… ${unreadableDirs} unreadable ${unreadableDirs === 1 ? "directory" : "directories"} skipped`;
             // DC-54 — one merged sentence, and only when it happened. A note
             // that always fires says nothing.
+            // DC-49 — what a WALK did not enter, in the same discipline the
+            // file skips already follow: a scoped result that reads as total
+            // is one the model cannot tell is scoped.
+            if (excludedDirs > 0) {
+                content += `\n… ${excludedDirs} ${excludedDirs === 1 ? "directory" : "directories"} excluded`;
+            }
             if (skippedFiles > 0 || stopped) {
                 const parts = [];
                 if (skippedFiles > 0)
@@ -803,6 +847,7 @@ export function writeFileTool(opts) {
         promptSnippet: "write_file — create or replace a whole file",
         promptGuidelines: ["write/edit: cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
         execute: async ({ path, content, expectedRevision: citedRevision }) => {
+            const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             // WR-1-F2: normalize every plausible copy of the token FIRST —
             // tolerance in the reader, strictness in the comparison.
             const expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
@@ -838,6 +883,19 @@ export function writeFileTool(opts) {
                 if (!exists) {
                     return precondition(`write_file: ${path} no longer exists — pass expectedRevision:"absent" to create it`);
                 }
+                // DC-54 owed (R14) — the ceiling, before the read.
+                //
+                // `read_file` got this bound in 0.24.5; these two did not,
+                // and they read the WHOLE file to compute a revision BEFORE
+                // the comparison that would reject the call — so the freeze
+                // happened on the way to the refusal rather than instead of
+                // it. Same ceiling, same precondition shape, same reason: a
+                // revision over a prefix could never match, so there is
+                // nothing to compute and nothing to compare.
+                const wSize = statSync(full).size;
+                if (wSize > maxReadBytes) {
+                    return precondition(`write_file: ${path} is ${mib(wSize)} — too large to read (ceiling ${mib(maxReadBytes)}); use shell with sed/head to take a range`);
+                }
                 const current = contentRevision(readFileSync(full));
                 if (current !== expectedRevision) {
                     return precondition(`write_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
@@ -937,6 +995,7 @@ export function editFileTool(opts) {
         promptSnippet: "edit_file — replace an exact old_string block (never rewrite whole files)",
         promptGuidelines: ["write/edit: cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
         execute: async ({ path, search, replace, edits, expectedRevision: citedRevision }) => {
+            const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             // WR-1-F2: normalize the citation (see write_file).
             const expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
             // WR-1E2 — the form XOR (the draft-07 subset has no oneOf; the
@@ -983,6 +1042,19 @@ export function editFileTool(opts) {
                 // what was edited (the external validation→replacement window
                 // remains and is the narrowed claim). Staleness reports BEFORE
                 // the pattern search: the truer cause first.
+                // DC-54 owed (R14) — the ceiling, before the read.
+                //
+                // `read_file` got this bound in 0.24.5; these two did not,
+                // and they read the WHOLE file to compute a revision BEFORE
+                // the comparison that would reject the call — so the freeze
+                // happened on the way to the refusal rather than instead of
+                // it. Same ceiling, same precondition shape, same reason: a
+                // revision over a prefix could never match, so there is
+                // nothing to compute and nothing to compare.
+                const eSize = statSync(full).size;
+                if (eSize > maxReadBytes) {
+                    return precondition(`edit_file: ${path} is ${mib(eSize)} — too large to read (ceiling ${mib(maxReadBytes)}); use shell with sed/head to take a range`);
+                }
                 const bytes = readFileSync(full);
                 const current = contentRevision(bytes);
                 if (current !== expectedRevision) {
@@ -1105,13 +1177,16 @@ export function shellTool(opts) {
                 // not just the outer shell (Area 4). cwd is the workspace.
                 // bootstrap #3 (finding #7): the shell child NEVER inherits kiso's own
                 // provider credentials by default — only the explicit
-                // shellEnv: "inherit" opt-in keeps them.
+                // shellEnv: "inherit" opt-in keeps them. A record (ADR-0031
+                // Amendment 1) rides on the STRIPPED base and wins per key.
                 const child = spawn(command, {
                     shell: true,
                     detached: true,
                     cwd: opts.workspaceRoot,
                     stdio: ["ignore", "pipe", "pipe"],
-                    env: opts.shellEnv === "inherit" ? process.env : strippedShellEnv(process.env),
+                    env: opts.shellEnv === "inherit"
+                        ? process.env
+                        : { ...strippedShellEnv(process.env), ...(opts.shellEnv ?? {}) },
                 });
                 let stdout = "";
                 let stderr = "";

package/package.json

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