@vincemakes/kiso-tools-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @vincemakes/kiso-tools-node
+
+Coding tools for Node hosts, bound to an explicit workspace root:
+read_file, list_dir, search_text (idempotent reads), write_file,
+edit_file (safe replacement — external hard links are never
+overwritten), and shell (process-tree kill on timeout/abort).
+
+See the repository README for the framework overview.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * kiso coding tools — the reference toolset for Node hosts.
+ *
+ * Exactly-once discipline (ADR-0024): reads, listing, and search are
+ * `idempotent` (safe to repeat); write, edit, and shell are NOT — the
+ * kernel replays a confirmed success and blocks an interrupted attempt.
+ * The CLI puts write/edit/shell behind the approval policy.
+ *
+ * Everything is relative to the process cwd; results are text (the model's
+ * only medium). No shell flags the kernel doesn't need: `shell` carries an
+ * explicit timeout and an output cap so a runaway command cannot flood the
+ * context.
+ */
+import { type Tool, type ToolResult } from "@vincemakes/kiso-core";
+/**
+ * A path that the workspace boundary refuses — never attempted, reported as
+ * a precondition (the tool COULD run it, the gate refused it).
+ */
+export declare function escapeResult(reason: string): ToolResult;
+/**
+ * Resolve an input path strictly inside the workspace (Area 5):
+ * - absolute inputs are refused (paths are workspace-relative);
+ * - `..` components cannot escape because the joined path is re-checked
+ *   against the canonical root;
+ * - SYMLINKS cannot escape: the deepest existing ancestor is realpath'd
+ *   and must stay inside the canonical root (this covers symlinked files,
+ *   symlinked directories, and the parents of files to be created);
+ * - returns the canonical absolute path, or throws PathEscapeError.
+ */
+export declare class PathEscapeError extends Error {
+    constructor(message: string);
+}
+export declare function resolveWithinRoot(root: string, input: string): string;
+/**
+ * 十: the canonical path a tool will actually touch, as an ABSOLUTE path.
+ * Symlinks in the deepest EXISTING ancestor are resolved — a file to be
+ * created under a symlinked directory lands in the TARGET, not in the
+ * link — and the not-yet-existing tail is re-appended. Shared by the
+ * tools (which then re-verify the workspace boundary) and the CLI
+ * approval UI, so the human and the tool see THE SAME path.
+ */
+export declare function canonicalTargetPath(input: string): string;
+export interface WorkspaceToolsOptions {
+    /** The workspace the tools may touch; everything else is refused. */
+    readonly workspaceRoot: string;
+}
+export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{
+    path: string;
+}>;
+export declare function listDirTool(opts: WorkspaceToolsOptions): Tool<{
+    path?: string;
+}>;
+export declare function searchTextTool(opts: WorkspaceToolsOptions): Tool<{
+    pattern: string;
+    path?: string;
+}>;
+export declare function writeFileTool(opts: WorkspaceToolsOptions): Tool<{
+    path: string;
+    content: string;
+}>;
+export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<{
+    path: string;
+    search: string;
+    replace: string;
+}>;
+export declare function shellTool(opts: WorkspaceToolsOptions): Tool<{
+    command: string;
+    timeoutMs?: number;
+}>;
+/** The full coding toolset, bound to one workspace root (Area 5). */
+export declare function createCodingTools(opts: WorkspaceToolsOptions): readonly Tool<any>[];

package/dist/index.js

@@ -0,0 +1,665 @@
+/**
+ * kiso coding tools — the reference toolset for Node hosts.
+ *
+ * Exactly-once discipline (ADR-0024): reads, listing, and search are
+ * `idempotent` (safe to repeat); write, edit, and shell are NOT — the
+ * kernel replays a confirmed success and blocks an interrupted attempt.
+ * The CLI puts write/edit/shell behind the approval policy.
+ *
+ * Everything is relative to the process cwd; results are text (the model's
+ * only medium). No shell flags the kernel doesn't need: `shell` carries an
+ * explicit timeout and an output cap so a runaway command cannot flood the
+ * context.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { defineTool } from "@vincemakes/kiso-core";
+const OUTPUT_CAP = 100_000; // chars of output a tool result may carry
+const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
+function cap(text) {
+    return text.length > OUTPUT_CAP ? `${text.slice(0, OUTPUT_CAP)}\n…[truncated]` : text;
+}
+/**
+ * A path that the workspace boundary refuses — never attempted, reported as
+ * a precondition (the tool COULD run it, the gate refused it).
+ */
+export function escapeResult(reason) {
+    return { content: `[path denied] ${reason}`, isError: true, errorKind: "precondition" };
+}
+function isWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Resolve an input path strictly inside the workspace (Area 5):
+ * - absolute inputs are refused (paths are workspace-relative);
+ * - `..` components cannot escape because the joined path is re-checked
+ *   against the canonical root;
+ * - SYMLINKS cannot escape: the deepest existing ancestor is realpath'd
+ *   and must stay inside the canonical root (this covers symlinked files,
+ *   symlinked directories, and the parents of files to be created);
+ * - returns the canonical absolute path, or throws PathEscapeError.
+ */
+export class PathEscapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PathEscapeError";
+    }
+}
+export function resolveWithinRoot(root, input) {
+    if (isAbsolute(input)) {
+        throw new PathEscapeError(`absolute paths are not allowed — use workspace-relative paths: ${input}`);
+    }
+    const rootReal = realpathSync(root);
+    const candidate = resolve(root, input);
+    // Walk up to the deepest EXISTING ancestor (files to be created have a
+    // not-yet-existing tail), then canonicalize it.
+    let ancestor = candidate;
+    const missingTail = [];
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        missingTail.unshift(basename(ancestor));
+        ancestor = parent;
+    }
+    const ancestorReal = realpathSync(ancestor);
+    if (!isWithin(rootReal, ancestorReal)) {
+        throw new PathEscapeError(`path escapes the workspace (${input})`);
+    }
+    const canonical = missingTail.length > 0 ? join(ancestorReal, ...missingTail) : ancestorReal;
+    if (!isWithin(rootReal, canonical)) {
+        throw new PathEscapeError(`path escapes the workspace (${input})`);
+    }
+    return canonical;
+}
+/**
+ * 十: the canonical path a tool will actually touch, as an ABSOLUTE path.
+ * Symlinks in the deepest EXISTING ancestor are resolved — a file to be
+ * created under a symlinked directory lands in the TARGET, not in the
+ * link — and the not-yet-existing tail is re-appended. Shared by the
+ * tools (which then re-verify the workspace boundary) and the CLI
+ * approval UI, so the human and the tool see THE SAME path.
+ */
+export function canonicalTargetPath(input) {
+    const candidate = resolve(input);
+    let ancestor = candidate;
+    const missingTail = [];
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        missingTail.unshift(basename(ancestor));
+        ancestor = parent;
+    }
+    let ancestorReal;
+    try {
+        ancestorReal = realpathSync(ancestor);
+    }
+    catch {
+        return candidate; // unresolvable — show the plain resolved path
+    }
+    return missingTail.length > 0 ? join(ancestorReal, ...missingTail) : ancestorReal;
+}
+/**
+ * The inode-boundary policy for READS (八): a hard link inside the workspace
+ * may point at an inode whose OTHER links live outside (e.g. /etc/passwd) —
+ * reading it would silently exfiltrate external content. Policy:
+ *   - regular, single-link files: read;
+ *   - multi-link files whose EVERY link is inside the workspace: read;
+ *   - multi-link files with ANY link outside the workspace: refused
+ *     (fail-closed when the link count cannot be verified);
+ *   - non-regular files (sockets, devices, fifos): refused.
+ * Returns a denial reason, or null when the file is safe to read.
+ */
+function inodeReadPolicy(root, full) {
+    const st = statSync(full);
+    if (!st.isFile())
+        return `not a regular file — refusing to read (${full})`;
+    if (st.nlink <= 1)
+        return null;
+    // 第四轮: the link count is verified STRUCTURALLY, never by counting
+    // newline-split text. `find -print0` emits NUL-separated paths — a file
+    // named "inside\nspoof" is ONE path, not two — and every match is then
+    // re-statted and checked for the EXACT dev+ino pair (an inode number
+    // alone is not identity across devices). Any failure to verify every
+    // link is fail-closed: the file is refused.
+    // 第五轮(P2-3): the workspace root is CANONICALIZED before the scan —
+    // find on a symlinked root would not follow the symlink into the real
+    // tree, undercounting the in-workspace links and misjudging a legal
+    // hard link as an external escape.
+    let inside = 0;
+    try {
+        const rootReal = realpathSync(root);
+        const out = execFileSync("find", [rootReal, "-xdev", "-inum", String(st.ino), "-print0"], { encoding: "utf8", maxBuffer: 1 << 20 });
+        for (const path of out.split("\0")) {
+            if (path === "")
+                continue;
+            try {
+                const match = statSync(path);
+                if (match.dev === st.dev && match.ino === st.ino)
+                    inside += 1;
+            }
+            catch {
+                inside = -1; // an unverifiable match — fail closed
+                break;
+            }
+        }
+    }
+    catch {
+        inside = -1; // cannot verify — refuse (fail-closed)
+    }
+    if (inside < 0 || inside < st.nlink) {
+        const verified = inside < 0 ? "unverifiable" : `${inside}/${st.nlink}`;
+        return `file has hard links outside the workspace (${verified} inside) — refusing to read (${full})`;
+    }
+    return null;
+}
+export function readFileTool(opts) {
+    return defineTool({
+        name: "read_file",
+        description: "Read a file's content from disk. Relative to the workspace root.",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string", description: "Workspace-relative path of the file to read" } },
+            required: ["path"],
+        },
+        idempotent: true,
+        execute: async ({ path }) => {
+            try {
+                const full = resolveWithinRoot(opts.workspaceRoot, path);
+                const denied = inodeReadPolicy(opts.workspaceRoot, full);
+                if (denied !== null)
+                    return escapeResult(denied);
+                const content = readFileSync(full, "utf8");
+                return { content: cap(content), isError: false };
+            }
+            catch (err) {
+                if (err instanceof PathEscapeError)
+                    return escapeResult(err.message);
+                return { content: `read_file failed: ${err.message}`, isError: true, errorKind: "fatal" };
+            }
+        },
+    });
+}
+export function listDirTool(opts) {
+    return defineTool({
+        name: "list_dir",
+        description: "List the entries of a directory. Omit path to list the workspace root.",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string", description: "Workspace-relative directory to list" } },
+        },
+        idempotent: true,
+        execute: async ({ path }) => {
+            try {
+                const dir = resolveWithinRoot(opts.workspaceRoot, path ?? ".");
+                const entries = readdirSync(dir, { withFileTypes: true }).map((e) => {
+                    const isDir = e.isDirectory();
+                    return `${isDir ? "dir " : "file"} ${e.name}${isDir ? "/" : ""}`;
+                });
+                return { content: entries.length ? cap(entries.join("\n")) : "(empty directory)", isError: false };
+            }
+            catch (err) {
+                if (err instanceof PathEscapeError)
+                    return escapeResult(err.message);
+                return { content: `list_dir failed: ${err.message}`, isError: true, errorKind: "fatal" };
+            }
+        },
+    });
+}
+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.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "Regular expression to search for" },
+                path: { type: "string", description: "Workspace-relative root directory (default: workspace root)" },
+            },
+            required: ["pattern"],
+        },
+        idempotent: true,
+        execute: async ({ pattern, path }) => {
+            let root;
+            try {
+                root = resolveWithinRoot(opts.workspaceRoot, path ?? ".");
+            }
+            catch (err) {
+                if (err instanceof PathEscapeError)
+                    return escapeResult(err.message);
+                throw err;
+            }
+            const regex = new RegExp(pattern, "i");
+            const matches = [];
+            const walk = (dir, depth) => {
+                if (depth > 8 || matches.length > 200)
+                    return;
+                for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                    if (entry.name.startsWith(".") || entry.name === "node_modules")
+                        continue;
+                    const full = join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        walk(full, depth + 1);
+                    }
+                    else if (entry.isFile()) {
+                        try {
+                            // 八: same inode boundary as read_file — a hard link
+                            // to an external inode is not searched. 第四轮(对抗):
+                            // the link count is verified against the WORKSPACE
+                            // root, not the search subroot — a link that lives
+                            // inside the workspace but outside the search dir is
+                            // legal and must not be silently skipped.
+                            if (inodeReadPolicy(opts.workspaceRoot, full) !== null)
+                                continue;
+                            const text = readFileSync(full, "utf8");
+                            for (const [i, line] of text.split("\n").entries()) {
+                                if (regex.test(line)) {
+                                    matches.push(`${full}:${i + 1}: ${line.trim().slice(0, 160)}`);
+                                    if (matches.length >= 200)
+                                        return;
+                                }
+                            }
+                        }
+                        catch {
+                            // unreadable file — skip
+                        }
+                    }
+                }
+            };
+            try {
+                walk(root, 0);
+            }
+            catch (err) {
+                return { content: `search_text failed: ${err.message}`, isError: true, errorKind: "fatal" };
+            }
+            return { content: matches.length ? cap(matches.join("\n")) : "(no matches)", isError: false };
+        },
+    });
+}
+export function writeFileTool(opts) {
+    return defineTool({
+        name: "write_file",
+        description: "Write content to a file inside the workspace, replacing it entirely. A side effect — approval required.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Workspace-relative file to write" },
+                content: { type: "string", description: "Full new content" },
+            },
+            required: ["path", "content"],
+        },
+        execute: async ({ path, content }) => {
+            let full;
+            try {
+                full = resolveWithinRoot(opts.workspaceRoot, path);
+            }
+            catch (err) {
+                if (err instanceof PathEscapeError)
+                    return escapeResult(err.message);
+                throw err;
+            }
+            const tmp = `${full}.kiso-tmp-${process.pid}-${crypto.randomUUID()}`;
+            let preservedMode;
+            try {
+                // E 组: SAFE REPLACEMENT — write a temp file next to the
+                // target and rename it over the directory entry. A hard link
+                // inside the workspace that shares an EXTERNAL inode is
+                // therefore never overwritten: rename replaces the entry,
+                // not the shared inode.
+                // 八: an existing file keeps its mode — a 0755 script stays
+                // 0755 after replacement (rename drops the temp's default
+                // mode, so it is copied onto the temp first).
+                if (existsSync(full))
+                    preservedMode = statSync(full).mode & 0o7777;
+                writeFileSync(tmp, content, "utf8");
+                if (preservedMode !== undefined)
+                    chmodSync(tmp, preservedMode);
+                renameSync(tmp, full);
+                // Post-write re-check (review finding 8): if a concurrent
+                // swap turned the verified path into a symlink mid-write,
+                // the write landed outside the workspace — say so instead of
+                // claiming success. (The write itself cannot be undone.)
+                const written = realpathSync(full);
+                if (!isWithin(realpathSync(opts.workspaceRoot), written)) {
+                    return escapeResult(`write escaped the workspace via a swapped path (${path})`);
+                }
+                return { content: `wrote ${path} (${content.length} chars)`, isError: false };
+            }
+            catch (err) {
+                // 八: a failed write never leaves a temp file with the FULL
+                // content behind — it is unlinked in every failure path.
+                try {
+                    unlinkSync(tmp);
+                }
+                catch {
+                    // already renamed or never created
+                }
+                if (err instanceof PathEscapeError)
+                    return escapeResult(err.message);
+                return { content: `write_file failed: ${err.message}`, isError: true, errorKind: "fatal" };
+            }
+        },
+    });
+}
+export function editFileTool(opts) {
+    return defineTool({
+        name: "edit_file",
+        description: "Replace the FIRST occurrence of a literal string in a workspace file. A side effect — approval required.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Workspace-relative file" },
+                search: { type: "string", description: "Exact literal text to find" },
+                replace: { type: "string", description: "Replacement text" },
+            },
+            required: ["path", "search", "replace"],
+        },
+        execute: async ({ path, search, replace }) => {
+            let full;
+            try {
+                full = resolveWithinRoot(opts.workspaceRoot, path);
+            }
+            catch (err) {
+                if (err instanceof PathEscapeError)
+                    return escapeResult(err.message);
+                throw err;
+            }
+            const tmp = `${full}.kiso-tmp-${process.pid}-${crypto.randomUUID()}`;
+            let preservedMode;
+            try {
+                const text = readFileSync(full, "utf8");
+                const index = text.indexOf(search);
+                if (index === -1) {
+                    return { content: `edit_file: pattern not found in ${path}`, isError: true, errorKind: "invalid_input" };
+                }
+                // E 组: safe replacement — never rewrite a shared external inode via a hard link.
+                // 八: the edited file keeps its mode.
+                preservedMode = statSync(full).mode & 0o7777;
+                writeFileSync(tmp, text.slice(0, index) + replace + text.slice(index + search.length), "utf8");
+                chmodSync(tmp, preservedMode);
+                renameSync(tmp, full);
+                const written = realpathSync(full);
+                if (!isWithin(realpathSync(opts.workspaceRoot), written)) {
+                    return escapeResult(`edit escaped the workspace via a swapped path (${path})`);
+                }
+                return { content: `edited ${path}`, isError: false };
+            }
+            catch (err) {
+                // 八: a failed edit never leaves a temp file behind.
+                try {
+                    unlinkSync(tmp);
+                }
+                catch {
+                    // already renamed or never created
+                }
+                return { content: `edit_file failed: ${err.message}`, isError: true, errorKind: "fatal" };
+            }
+        },
+    });
+}
+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.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "The command to run" },
+                timeoutMs: { type: "number", description: "Timeout in ms (default 30000)" },
+            },
+            required: ["command"],
+        },
+        execute: async ({ command, timeoutMs }, ctx) => {
+            const timeout = timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+            // E 组: a PRE-aborted signal never spawns the command.
+            if (ctx.signal.aborted) {
+                return { content: "shell aborted before start", isError: true, errorKind: "fatal" };
+            }
+            return new Promise((resolvePromise) => {
+                // detached: the command gets its OWN process group, so a
+                // timeout/abort can kill the WHOLE TREE (children included),
+                // not just the outer shell (Area 4). cwd is the workspace.
+                const child = spawn(command, {
+                    shell: true,
+                    detached: true,
+                    cwd: opts.workspaceRoot,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                let stdout = "";
+                let stderr = "";
+                let exited = false;
+                let settled = false;
+                let killing = false;
+                const settle = (result) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    // E 组: the abort listener is removed once settled — it
+                    // must not accumulate across runs.
+                    ctx.signal.removeEventListener("abort", onAbort);
+                    resolvePromise(result);
+                };
+                /**
+                 * Kill the whole tree and CONFIRM it exited (八/十一):
+                 *
+                 * 1. FREEZE the root (SIGSTOP) FIRST — a stopped shell cannot
+                 *    fork new descendants while we enumerate;
+                 * 2. repeatedly discover AND freeze descendants (pid-table
+                 *    sweep — the only way to see a setsid()-escaped process)
+                 *    until the set is STABLE (two identical scans), so the
+                 *    enumeration cannot miss a mid-sweep fork;
+                 * 3. SIGKILL the process group and every tracked pid;
+                 * 4. poll every tracked pid to death. If ANY tracked pid is
+                 *    still alive at the deadline, the verdict is NOT
+                 *    "aborted"/"timed out" — it is an explicit UNCERTAIN
+                 *    error naming the survivors: the side effect may have
+                 *    outlived the tool, and the caller must not assume it
+                 *    was killed.
+                 */
+                const killTree = () => new Promise((resolveKill) => {
+                    const tracked = new Set();
+                    // 十一(对抗): the ROOT itself is tracked too — the
+                    // verdict must not read "aborted" while the root
+                    // survives. DOCUMENTED LIMITS: (1) a process that
+                    // forks between SIGSTOP delivery and the next scan,
+                    // setsids, and is then reparented when its parent is
+                    // killed can escape the enumeration entirely — it is
+                    // untracked and unknowable from the pid table; the
+                    // platform cannot confirm it. (2) if THIS process is
+                    // killed between the first SIGSTOP and the SIGKILL
+                    // sweep, the stopped descendants stay permanently
+                    // stopped (nobody SIGCONTs orphans) — the inherent
+                    // cost of freeze-first. Both limits are recorded here
+                    // so no claim of "the whole tree is gone" is ever
+                    // stronger than what the platform can prove.
+                    if (child.pid !== undefined && child.pid > 0) {
+                        tracked.add(child.pid);
+                        try {
+                            process.kill(child.pid, "SIGSTOP"); // freeze the root
+                        }
+                        catch {
+                            // already gone
+                        }
+                    }
+                    // Stable discovery: freeze as we go; stop when two
+                    // consecutive scans are identical.
+                    let previous = new Set();
+                    for (let i = 0; i < 10; i++) {
+                        const current = new Set(descendantsOf(child.pid ?? 0));
+                        for (const pid of current) {
+                            tracked.add(pid);
+                            try {
+                                process.kill(pid, "SIGSTOP"); // freeze each descendant
+                            }
+                            catch {
+                                // already gone
+                            }
+                        }
+                        if (current.size === previous.size && [...current].every((pid) => previous.has(pid))) {
+                            break;
+                        }
+                        previous = current;
+                    }
+                    // The process group (E 组: never kill an undefined/0
+                    // pid), which also takes the frozen root down.
+                    if (child.pid !== undefined && child.pid > 0) {
+                        try {
+                            process.kill(-child.pid, "SIGKILL");
+                        }
+                        catch {
+                            try {
+                                child.kill("SIGKILL");
+                            }
+                            catch {
+                                // already gone
+                            }
+                        }
+                    }
+                    for (const pid of tracked) {
+                        try {
+                            process.kill(pid, "SIGKILL");
+                        }
+                        catch {
+                            // already gone
+                        }
+                    }
+                    const confirm = () => {
+                        void waitAllDead([...tracked]).then((unconfirmed) => resolveKill({ unconfirmed }));
+                    };
+                    if (exited) {
+                        confirm();
+                        return;
+                    }
+                    const fallback = setTimeout(confirm, 2000);
+                    child.once("close", () => {
+                        clearTimeout(fallback);
+                        confirm();
+                    });
+                });
+                child.stdout?.on("data", (d) => {
+                    stdout = cap(stdout + d.toString());
+                });
+                child.stderr?.on("data", (d) => {
+                    stderr = cap(stderr + d.toString());
+                });
+                child.on("error", (err) => {
+                    settle({ content: `shell failed: ${err.message}`, isError: true, errorKind: "fatal" });
+                });
+                child.on("close", (code) => {
+                    exited = true;
+                    if (killing)
+                        return; // the timeout/abort verdict owns the result
+                    const combined = (stdout + (stderr ? `\n[stderr] ${stderr}` : "")).trim();
+                    settle(code === 0
+                        ? { content: combined || "(no output)", isError: false }
+                        : { content: `exit ${code}: ${combined}`, isError: true, errorKind: "fatal" });
+                });
+                // The kernel's abort reaches the command AND its whole tree.
+                // The listener is removed by settle (E 组).
+                const uncertainVerdict = (unconfirmed) => unconfirmed.length > 0
+                    ? `could not confirm ${unconfirmed.length} descendant(s) exited (pids ${unconfirmed.join(", ")}) — treat the side effect as UNCERTAIN`
+                    : "";
+                const onAbort = () => {
+                    killing = true;
+                    void killTree().then(({ unconfirmed }) => settle({
+                        content: `shell aborted${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}`,
+                        isError: true,
+                        errorKind: "fatal",
+                    }));
+                };
+                ctx.signal.addEventListener("abort", onAbort);
+                const timer = setTimeout(() => {
+                    killing = true;
+                    void killTree().then(({ unconfirmed }) => settle({
+                        content: `shell timed out after ${timeout}ms${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}`,
+                        isError: true,
+                        errorKind: "fatal",
+                    }));
+                }, timeout);
+                timer.unref?.();
+            });
+        },
+    });
+}
+/**
+ * All live pids whose ancestor chain includes `pid`, from the pid table
+ * (八: `ps -axo pid=,ppid=` — the ONLY way to see a setsid()-escaped
+ * process, which is in its own group and invisible to a group kill).
+ */
+function descendantsOf(pid) {
+    if (pid <= 0)
+        return [];
+    let table;
+    try {
+        table = execFileSync("ps", ["-axo", "pid=,ppid="], { encoding: "utf8", maxBuffer: 1 << 20 });
+    }
+    catch {
+        return [];
+    }
+    const children = new Map();
+    for (const line of table.split("\n")) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)$/);
+        if (m === null)
+            continue;
+        const child = Number(m[1]);
+        const parent = Number(m[2]);
+        if (!children.has(parent))
+            children.set(parent, []);
+        children.get(parent).push(child);
+    }
+    const out = [];
+    const queue = [pid];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const c of children.get(current) ?? []) {
+            out.push(c);
+            queue.push(c);
+        }
+    }
+    return out;
+}
+/**
+ * Poll the pid table until NONE of the tracked pids is alive (bounded).
+ * Returns the pids still alive at the deadline — the caller MUST NOT
+ * report "aborted"/"timed out" while any tracked pid survives (十一).
+ */
+function waitAllDead(pids) {
+    if (pids.length === 0)
+        return Promise.resolve([]);
+    return new Promise((resolve) => {
+        const deadline = Date.now() + 2000;
+        const poll = () => {
+            const alive = [];
+            for (const pid of pids) {
+                try {
+                    process.kill(pid, 0);
+                    alive.push(pid);
+                }
+                catch (err) {
+                    if (err.code === "EPERM")
+                        alive.push(pid);
+                    // ESRCH — gone
+                }
+            }
+            if (alive.length === 0 || Date.now() > deadline)
+                return resolve(alive);
+            setTimeout(poll, 50);
+        };
+        poll();
+    });
+}
+/** The full coding toolset, bound to one workspace root (Area 5). */
+export function createCodingTools(opts) {
+    return [
+        readFileTool(opts),
+        listDirTool(opts),
+        searchTextTool(opts),
+        writeFileTool(opts),
+        editFileTool(opts),
+        shellTool(opts),
+    ];
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vincemakes/kiso-tools-node",
+  "version": "0.1.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"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vincemakes/kiso-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vincemakes/kiso.git",
+    "directory": "packages/tools-node"
+  },
+  "bugs": {
+    "url": "https://github.com/vincemakes/kiso/issues"
+  },
+  "homepage": "https://github.com/vincemakes/kiso/tree/main/packages/tools-node#readme"
+}