@vincemakes/kiso-tools-node 0.1.30 → 0.1.32

package/dist/index.d.ts

@@ -12,9 +12,10 @@
  * context.
  *
  * the token round: reads are RANGEABLE (read_file offset/limit, default head 200
- * lines) and search/list are capped (50 / 200) — every truncation carries
- * an actionable continuation note (deterministic per file state), so the
- * model always has a path to the full content.
+ * lines), search/list are capped (50 / 200), shell output is capped — every
+ * truncation carries an actionable continuation note in the N of M form and
+ * states what was dropped (deterministic per file state), so the model
+ * always has a path to the full content.
  */
 import { type Tool, type ToolResult } from "@vincemakes/kiso-core";
 /**

package/dist/index.js

@@ -12,9 +12,10 @@
  * context.
  *
  * the token round: reads are RANGEABLE (read_file offset/limit, default head 200
- * lines) and search/list are capped (50 / 200) — every truncation carries
- * an actionable continuation note (deterministic per file state), so the
- * model always has a path to the full content.
+ * lines), search/list are capped (50 / 200), shell output is capped — every
+ * truncation carries an actionable continuation note in the N of M form and
+ * states what was dropped (deterministic per file state), so the model
+ * always has a path to the full content.
  */
 import { execFileSync, spawn } from "node:child_process";
 import { chmodSync, existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
@@ -33,6 +34,17 @@ const MAX_DIR_ENTRIES = 200;
 function cap(text) {
     return text.length > OUTPUT_CAP ? `${text.slice(0, OUTPUT_CAP)}\n…[truncated]` : text;
 }
+/**
+ * R-C item 2: chunked accumulation under the cap that COUNTS what it drops —
+ * the shell overflow note names the dropped bytes and the recovery path
+ * (the W10 continuation, made model-facing: what was dropped, how many).
+ */
+function capAccumulate(current, chunk) {
+    const room = OUTPUT_CAP - current.length;
+    if (room >= chunk.length)
+        return { text: current + chunk, dropped: 0 };
+    return { text: room <= 0 ? current : current + chunk.slice(0, room), dropped: chunk.length - Math.max(room, 0) };
+}
 /**
  * A path that the workspace boundary refuses — never attempted, reported as
  * a precondition (the tool COULD run it, the gate refused it).
@@ -178,7 +190,7 @@ function moreLinesNote(nextOffset, remaining) {
 export function readFileTool(opts) {
     return defineTool({
         name: "read_file",
-        description: "Read a file's content from disk. Relative to the workspace root. Returns the first 200 lines by default; a file with more lines appends a note with the exact count and the offset to continue from. Pass offset (1-based first line) and/or limit (line count) to read a range.",
+        description: "Read a file's content from disk (the workspace reader — prefer it over shell cat/head/tail). Relative to the workspace root. Returns the first 200 lines by default; a file with more lines appends a note with the exact count and the offset to continue from. Pass offset (1-based first line) and/or limit (line count) to read a range.",
         parameters: {
             type: "object",
             properties: {
@@ -189,6 +201,8 @@ export function readFileTool(opts) {
             required: ["path"],
         },
         idempotent: true,
+        promptSnippet: "read_file — whole files or offset/limit ranges, workspace-relative paths",
+        promptGuidelines: ["read only the range you need — offset/limit beat whole-file reads"],
         execute: async ({ path, offset, limit }) => {
             try {
                 const full = resolveWithinRoot(opts.workspaceRoot, path);
@@ -273,6 +287,8 @@ export function listDirTool(opts) {
             properties: { path: { type: "string", description: "Workspace-relative directory to list" } },
         },
         idempotent: true,
+        promptSnippet: "list_dir — directory entries (the workspace ls)",
+        promptGuidelines: ["narrow to a subdirectory when the listing caps at 200 entries"],
         execute: async ({ path }) => {
             try {
                 const dir = resolveWithinRoot(opts.workspaceRoot, path ?? ".");
@@ -282,7 +298,9 @@ export function listDirTool(opts) {
                 });
                 let content = entries.length ? cap(entries.slice(0, MAX_DIR_ENTRIES).join("\n")) : "(empty directory)";
                 if (entries.length > MAX_DIR_ENTRIES) {
-                    content += `\n… +${entries.length - MAX_DIR_ENTRIES} more entries (narrow to a subdirectory)`;
+                    // R-C item 2: the N of M form — the cap names its
+                    // continuation (narrow to a subdirectory for more).
+                    content += `\n… ${MAX_DIR_ENTRIES} of ${entries.length} entries shown (narrow to a subdirectory for more)`;
                 }
                 return { content, isError: false };
             }
@@ -297,7 +315,7 @@ export function listDirTool(opts) {
 export function searchTextTool(opts) {
     return defineTool({
         name: "search_text",
-        description: "Search files under a workspace directory (recursive) for a regular expression. Returns matching file:line excerpts, capped at 50 — an overflow note states the count of further matches (narrow the pattern to see them).",
+        description: "Search files under a workspace directory (recursive) for a regular expression (the workspace grep — prefer it over shell grep/rg). Returns matching file:line excerpts, capped at 50 — an overflow note states the count of further matches (narrow the pattern to see them).",
         parameters: {
             type: "object",
             properties: {
@@ -307,6 +325,8 @@ export function searchTextTool(opts) {
             required: ["pattern"],
         },
         idempotent: true,
+        promptSnippet: "search_text — regex search over workspace files",
+        promptGuidelines: ["narrow the pattern when the result caps — never re-run a broad search"],
         execute: async ({ pattern, path }) => {
             let root;
             try {
@@ -366,8 +386,11 @@ export function searchTextTool(opts) {
                 return { content: `search_text failed: ${err.message}`, isError: true, errorKind: "fatal" };
             }
             let content = matches.length ? cap(matches.join("\n")) : "(no matches)";
-            if (totalMatches > matches.length)
-                content += `\n… +${totalMatches - matches.length} more matches (narrow the pattern)`;
+            if (totalMatches > matches.length) {
+                // R-C item 2: the N of M form — the cap names its
+                // continuation (narrow the pattern for more).
+                content += `\n… ${matches.length} of ${totalMatches} matches shown (narrow the pattern for more)`;
+            }
             return { content, isError: false };
         },
     });
@@ -384,6 +407,7 @@ export function writeFileTool(opts) {
             },
             required: ["path", "content"],
         },
+        promptSnippet: "write_file — write a whole file (creates parent directories)",
         execute: async ({ path, content }) => {
             let full;
             try {
@@ -450,6 +474,8 @@ export function editFileTool(opts) {
             },
             required: ["path", "search", "replace"],
         },
+        promptSnippet: "edit_file — replace an exact old_string block (never rewrite whole files)",
+        promptGuidelines: ["the search text must match the file EXACTLY — read the target first"],
         execute: async ({ path, search, replace }) => {
             let full;
             try {
@@ -532,6 +558,8 @@ export function shellTool(opts) {
             },
             required: ["command"],
         },
+        promptSnippet: "shell — real system commands only (builds, tests, git)",
+        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;
             // E group: a PRE-aborted signal never spawns the command.
@@ -554,6 +582,8 @@ export function shellTool(opts) {
                 });
                 let stdout = "";
                 let stderr = "";
+                let stdoutDropped = 0;
+                let stderrDropped = 0;
                 let exited = false;
                 let settled = false;
                 let killing = false;
@@ -665,10 +695,14 @@ export function shellTool(opts) {
                     });
                 });
                 child.stdout?.on("data", (d) => {
-                    stdout = cap(stdout + d.toString());
+                    const r = capAccumulate(stdout, d.toString());
+                    stdout = r.text;
+                    stdoutDropped += r.dropped;
                 });
                 child.stderr?.on("data", (d) => {
-                    stderr = cap(stderr + d.toString());
+                    const r = capAccumulate(stderr, d.toString());
+                    stderr = r.text;
+                    stderrDropped += r.dropped;
                 });
                 child.on("error", (err) => {
                     settle({ content: `shell failed: ${err.message}`, isError: true, errorKind: "fatal" });
@@ -677,7 +711,16 @@ export function shellTool(opts) {
                     exited = true;
                     if (killing)
                         return; // the timeout/abort verdict owns the result
-                    const combined = (stdout + (stderr ? `\n[stderr] ${stderr}` : "")).trim();
+                    // R-C item 2: the overflow note names WHAT was dropped and
+                    // the recovery path — a silent tail-cut would be the exact
+                    // destructive class this round kills (W10 made model-facing).
+                    const overflowNote = (dropped, stream) => dropped === 0
+                        ? ""
+                        : `\n… [${stream} capped at ${OUTPUT_CAP} chars — ${dropped} more chars dropped; capture to a file and read it with read_file, or narrow the command]`;
+                    const combined = (stdout +
+                        overflowNote(stdoutDropped, "stdout") +
+                        (stderr ? `\n[stderr] ${stderr}` : "") +
+                        overflowNote(stderrDropped, "stderr")).trim();
                     settle(code === 0
                         ? { content: combined || "(no output)", isError: false }
                         : { content: `exit ${code}: ${combined}`, isError: true, errorKind: "fatal" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tools-node",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "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.1.29"
+    "@vincemakes/kiso-core": "0.1.31"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",