@vincemakes/kiso-tools-node 0.51.1 → 0.53.0

package/dist/index.d.ts

@@ -174,6 +174,15 @@ export interface WorkspaceToolsOptions {
         readonly maxForegroundMs?: number;
     };
 }
+/** WR-1: does this read_file call, with the result it got, show the file from its first
+ *  line to its last? It starts at the top (no offset, or offset 1) and carries none of the
+ *  three notices that say more remains: the continuation note, the output cap, the
+ *  over-long-line cap. A `limit` that covers the file is fine, because a short one always
+ *  leaves the continuation note. The hosts' observed-revision rule uses this for the
+ *  whole-file overwrite; it lives beside the notices so the two cannot drift apart. */
+export declare function readShowsWholeFile(input: {
+    readonly offset?: unknown;
+}, body: string): boolean;
 export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{
     path: string;
     offset?: number;
@@ -264,6 +273,8 @@ export interface ShellTasks {
         ready(match: string): void;
         ended(exitCode: number | null, signal: string | null): void;
         unconfirmed(pids: readonly number[]): void;
+        /** the hand-over failed after the task was recorded; absent in a manager that predates it */
+        handoverFailed?(reason: string): void;
     };
     stop(id: string, by: "model"): boolean;
     get(id: string): {

package/dist/index.js

@@ -19,7 +19,7 @@
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, linkSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, linkSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import { killTree, NO_BASH, processStartTime, RotatingOutput, startCommand } from "./process.js";
@@ -89,6 +89,12 @@ const DEFAULT_MAX_FOREGROUND_MS = 300_000;
 const TASK_OUTPUT_CAP = 64 * 1024 * 1024;
 /** A task's stop: SIGTERM, this long, then the confirmed sweep. */
 const TASK_STOP_GRACE_MS = 5_000;
+/** The shell exited but its pipes did not close: how long after the exit (or
+ *  the last byte that followed it) before a descendant is taken to hold them. */
+const EXIT_DRAIN_MS = 300;
+/** ...and the most it may be renewed: a descendant that writes every few
+ *  hundred ms must not keep a finished command in the foreground. */
+const EXIT_DRAIN_MAX_MS = 2_000;
 /** ADR-0058 Amendment 7: how long task_stop waits for the end it reports —
  *  the runner's journal poll, TERM, the grace, KILL and the sweep. */
 const TASK_STOP_WAIT_MS = 8_000;
@@ -372,6 +378,18 @@ function moreLinesNote(nextOffset, remaining, limit) {
     // 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})`;
 }
+/** WR-1: does this read_file call, with the result it got, show the file from its first
+ *  line to its last? It starts at the top (no offset, or offset 1) and carries none of the
+ *  three notices that say more remains: the continuation note, the output cap, the
+ *  over-long-line cap. A `limit` that covers the file is fine, because a short one always
+ *  leaves the continuation note. The hosts' observed-revision rule uses this for the
+ *  whole-file overwrite; it lives beside the notices so the two cannot drift apart. */
+export function readShowsWholeFile(input, body) {
+    const offset = input.offset;
+    if (offset !== undefined && !(typeof offset === "number" && offset <= 1))
+        return false;
+    return !body.includes("(call again with offset=") && !body.includes("[output capped at") && !/\[a line near .* exceeds the \d+-char cap/.test(body);
+}
 export function readFileTool(opts) {
     return defineTool({
         name: "read_file",
@@ -907,7 +925,7 @@ export function writeFileTool(opts) {
                 // the trajectory audit: after ranged reads the model retried this
                 // in a loop — say that only a WHOLE read lets it replace the file
                 if (expectedRevision === undefined)
-                    return precondition(`write_file: ${path} already exists — to replace it, first read the whole file (read_file with no offset or limit; a ranged read is not enough), or change part of it with edit_file`);
+                    return precondition(`write_file: ${path} already exists — to replace it, first read the whole file from its first line (a read that starts later or stops early is not enough; for a long file pass a limit that covers it), or change part of it with edit_file`);
             }
             // WR-1 — the observed-revision stale-write guard. The decision
             // lattice runs BEFORE any bytes move; every refusal is a
@@ -953,8 +971,39 @@ export function writeFileTool(opts) {
                     return precondition(opts.observedRevision !== undefined ? `write_file: ${path} changed since you last observed it — read it again, then re-apply the change` : `write_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
                 }
             }
+            // A new file may sit under directories that do not exist yet. The
+            // containment check above already walked the missing tail up to its
+            // deepest existing ancestor, so creating the tail cannot leave the
+            // workspace; the directories this call creates are removed again
+            // if the file never lands.
+            let createdDirs;
+            if (!exists) {
+                try {
+                    createdDirs = mkdirSync(dirname(full), { recursive: true });
+                }
+                catch (err) {
+                    return precondition(`write_file: cannot create the directory for ${path} — ${describeFsError(err, path)}`);
+                }
+            }
+            const dropCreatedDirs = () => {
+                if (createdDirs === undefined)
+                    return;
+                for (let dir = dirname(full); dir.length >= createdDirs.length; dir = dirname(dir)) {
+                    try {
+                        rmdirSync(dir);
+                    }
+                    catch {
+                        return; // not empty or not ours — leave it
+                    }
+                    if (dir === createdDirs)
+                        return;
+                }
+            };
             const tmp = `${full}.kiso-tmp-${process.pid}-${crypto.randomUUID()}`;
             let preservedMode;
+            // Nothing reaches the target before the commit step below, so a
+            // failure while staging the temp file leaves the world as it was.
+            let committing = false;
             try {
                 // E group: SAFE REPLACEMENT — write a temp file next to the
                 // target and rename it over the directory entry. A hard link
@@ -969,12 +1018,15 @@ export function writeFileTool(opts) {
                 writeFileSync(tmp, content, "utf8");
                 if (preservedMode !== undefined)
                     chmodSync(tmp, preservedMode);
+                committing = true;
                 if (!exists) {
                     // WR-1A ②: link(2) or refusal — atomic no-clobber, fail
                     // closed. No rename fallback: "absent" is a contract.
                     const refused = publishNewFile(tmp, full, path);
-                    if (refused !== null)
+                    if (refused !== null) {
+                        dropCreatedDirs();
                         return refused;
+                    }
                 }
                 else {
                     // WR-1A ③: the world must STILL match the citation right
@@ -1019,11 +1071,21 @@ export function writeFileTool(opts) {
                 }
                 if (err instanceof PathEscapeError)
                     return escapeResult(err.message);
-                return { content: `write_file failed: ${err.message}`, isError: true, errorKind: "fatal" };
+                if (!committing) {
+                    dropCreatedDirs();
+                    return precondition(`write_file: could not write ${path} — ${describeFsError(err, path)}; nothing was changed`);
+                }
+                return { content: `write_file failed: ${describeFsError(err, path)}`, isError: true, errorKind: "fatal" };
             }
         },
     });
 }
+/** An fs error as the model should read it: the file it asked for, not the
+ *  `.kiso-tmp-*` staging name the failing syscall happened to see. */
+function describeFsError(err, path) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.replace(/'[^']*\.kiso-tmp-[^']*'/g, `'${path}'`);
+}
 /** ACI-2: every offset where `search` occurs, OVERLAPPING ones included —
  *  "aa" occurs twice in "aaa", and the two resolutions differ, so the call
  *  is ambiguous. A scan that steps past each match by its own length
@@ -1212,7 +1274,7 @@ export function editFileTool(opts) {
             if (expectedRevision === undefined && opts.observedRevision !== undefined) {
                 expectedRevision = opts.observedRevision(ctx?.sessionId, full);
                 if (expectedRevision === undefined)
-                    return precondition(`edit_file: ${path} — read it first; there is no observation of it in this session`);
+                    return precondition(`edit_file: ${path} — read it first with read_file; there is no observation of it in this session (shell output does not count)`);
             }
             // WR-1: edits always target an existing file — the revision is
             // not optional here, and the refusal teaches the protocol.
@@ -1346,7 +1408,7 @@ export function editFileTool(opts) {
                 catch {
                     // already renamed or never created
                 }
-                return { content: `edit_file failed: ${err.message}`, isError: true, errorKind: "fatal" };
+                return { content: `edit_file failed: ${describeFsError(err, path)}`, isError: true, errorKind: "fatal" };
             }
         },
     });
@@ -1516,6 +1578,22 @@ export function shellTool(opts) {
                 let promoted = null;
                 let stopping = false;
                 let readySeen = false;
+                /** the top-level shell's own exit, once seen: `close` waits for every holder of its pipes */
+                let exitSeen = null;
+                let drainTimer;
+                let exitAtMs = 0;
+                /** the command had exited when the manager took its pipes: its root is gone, so a stop can reach only the descendants it can find */
+                let rootGone = false;
+                /** the stop of a hand-over was recorded unconfirmed: the sink stays open for whatever still holds the pipes, and closes with them */
+                let stopLeftHolders = false;
+                /** after the shell's exit: one more drain window from now (a byte that follows the exit renews it) */
+                const armDrain = () => {
+                    if (exitSeen === null)
+                        return;
+                    clearTimeout(drainTimer);
+                    drainTimer = setTimeout(onDrainExpired, Math.max(0, Math.min(EXIT_DRAIN_MS, exitAtMs + EXIT_DRAIN_MAX_MS - Date.now())));
+                    drainTimer.unref?.();
+                };
                 /** 3e: the unregister of this command's detach — while it runs in the foreground */
                 let undetachable = () => { };
                 let recent = ""; // the tail readyWhen is matched against
@@ -1565,6 +1643,7 @@ export function shellTool(opts) {
                     undetachable();
                     dropProgress();
                     clearTimeout(timer);
+                    clearTimeout(drainTimer);
                     // E group: the abort listener is removed once settled — it
                     // must not accumulate across runs.
                     ctx.signal.removeEventListener("abort", onAbort);
@@ -1578,6 +1657,7 @@ export function shellTool(opts) {
                     const r = capAccumulate(stdout, text);
                     stdout = r.text;
                     stdoutDropped += r.dropped;
+                    armDrain();
                     if (tasks !== undefined && matchReady(text))
                         promote("ready");
                 });
@@ -1589,6 +1669,7 @@ export function shellTool(opts) {
                     const r = capAccumulate(stderr, text);
                     stderr = r.text;
                     stderrDropped += r.dropped;
+                    armDrain();
                     if (tasks !== undefined && matchReady(text))
                         promote("ready");
                 });
@@ -1602,6 +1683,11 @@ export function shellTool(opts) {
                     ? ""
                     : `\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 combinedOutput = () => (stdout + overflowNote(stdoutDropped, "stdout") + (stderr ? `\n[stderr] ${stderr}` : "") + overflowNote(stderrDropped, "stderr")).trim();
+                /** the output captured so far, for a timeout or abort verdict: bounded like a normal result (the same caps and notes) */
+                const partialOutput = () => {
+                    const o = combinedOutput();
+                    return o === "" ? "" : `\n${o}`;
+                };
                 let exitInfo = null;
                 child.on("close", (code, signal) => {
                     if (promoted !== null) {
@@ -1611,6 +1697,9 @@ export function shellTool(opts) {
                             promoted.out.close();
                             promoted.task.ended(code, signal);
                         }
+                        else if (stopLeftHolders) {
+                            promoted.out.close();
+                        }
                         return;
                     }
                     if (killing)
@@ -1620,6 +1709,44 @@ export function shellTool(opts) {
                         ? { content: combined || "(no output)", isError: false }
                         : { content: `exit ${code}: ${combined}`, isError: true, errorKind: "fatal" });
                 });
+                // The shell's own exit arrives before `close` whenever a descendant keeps
+                // its stdout/stderr open (a daemon started by the command): `close` then
+                // waits for the descendant, not for the command. The exit is recorded;
+                // after a short drain window with no `close`, a manager takes the
+                // descendants over (below). It is never read as "done" on its own.
+                child.on("exit", (code, signal) => {
+                    // our own kill (timeout, abort) is not the command's exit
+                    if (killing)
+                        return;
+                    exitAtMs = Date.now();
+                    exitSeen = { code, signal, afterMs: exitAtMs - spawnedAt };
+                    if (settled || promoted !== null)
+                        return;
+                    armDrain();
+                });
+                const exitHow = () => (exitSeen === null ? "" : exitSeen.signal !== null ? `signal ${exitSeen.signal}` : `code ${exitSeen.code}`);
+                /** a timeout/abort verdict on a command that had already exited says so */
+                const exitNote = () => exitSeen === null ? "" : `; the command itself had already exited (${exitHow()}, after ${exitSeen.afterMs} ms) but processes it started still held its output`;
+                const onDrainExpired = () => {
+                    if (settled || killing || promoted !== null || exitSeen === null)
+                        return;
+                    // No manager: nothing can own the descendants, so the call is NOT complete
+                    // and is not reported as such — it keeps waiting for `close` under the
+                    // same kill timeout and abort.
+                    if (tasks === undefined)
+                        return;
+                    // win32: `taskkill /T` walks from a live root, so a stop could not reach
+                    // the descendants of an exited one. Not handed over there until it can.
+                    if (process.platform === "win32")
+                        return;
+                    try {
+                        promote("exited");
+                    }
+                    catch {
+                        // the hand-over was refused: keep waiting. Success is never reported for
+                        // work no manager owns.
+                    }
+                };
                 // The kernel's abort reaches the command AND its whole tree.
                 // The listener is removed by settle (E group).
                 const uncertainVerdict = (unconfirmed) => unconfirmed.length > 0
@@ -1628,7 +1755,7 @@ export function shellTool(opts) {
                 const onAbort = () => {
                     killing = true;
                     void killTree(child).then(({ unconfirmed }) => settle({
-                        content: `shell aborted${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}`,
+                        content: `shell aborted${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}${exitNote()}${partialOutput()}`,
                         isError: true,
                         errorKind: "fatal",
                     }));
@@ -1649,12 +1776,47 @@ export function shellTool(opts) {
                         startedAt: spawnedAt,
                         stop: () => stopPromoted(),
                     });
-                    const out = new RotatingOutput(task.outputPath, TASK_OUTPUT_CAP);
+                    // the task is in the journal from here. If its output cannot be prepared the
+                    // hand-over failed and NOTHING about the command ended: it still runs under
+                    // this call. The record says only that the task's outcome is not known (no
+                    // terminal is invented: the journal has no record for a failed hand-over, see
+                    // ADR-0058 Amendment 17); the failure is the caller's to see.
+                    let out;
                     const sofar = combinedOutput();
-                    if (sofar !== "")
-                        out.write(Buffer.from(`${sofar}\n`));
+                    try {
+                        out = new RotatingOutput(task.outputPath, TASK_OUTPUT_CAP);
+                        if (sofar !== "")
+                            out.write(Buffer.from(`${sofar}\n`));
+                    }
+                    catch (err) {
+                        try {
+                            out?.close();
+                        }
+                        catch {
+                            // nothing more to release
+                        }
+                        if (task.handoverFailed !== undefined)
+                            task.handoverFailed(err instanceof Error ? err.message : String(err));
+                        else
+                            task.unconfirmed([]);
+                        throw err;
+                    }
+                    rootGone = reason === "exited";
                     promoted = { task, out };
                     const tail = sofar.length > 2048 ? `…${sofar.slice(-2048)}` : sofar;
+                    if (reason === "exited" && exitSeen !== null) {
+                        // the command is done; what the manager now owns is whatever it left running on its pipes
+                        const failed = exitSeen.signal !== null || exitSeen.code !== 0;
+                        settle({
+                            content: `the command exited (${exitHow()}, after ${exitSeen.afterMs} ms)${failed ? " and FAILED" : ""}, but processes it started are still running and hold its output` +
+                                `${failed ? " — its side effects may be incomplete" : ""}; ` +
+                                `they continue as background task ${task.id} (not killed — it keeps running). ${taskNote(task.outputPath)}` +
+                                (tail !== "" ? `\nOutput so far:\n${tail}` : ""),
+                            isError: failed,
+                            ...(failed ? { errorKind: "fatal" } : {}),
+                        });
+                        return;
+                    }
                     settle({
                         content: (reason === "ready"
                             ? `ready — the output contains "${readyWhen}"; `
@@ -1688,6 +1850,18 @@ export function shellTool(opts) {
                             promoted.task.unconfirmed(unconfirmed);
                             return;
                         }
+                        // A root that had already exited leaves nothing to enumerate a descendant
+                        // from if that descendant left its group and was reparented, and the pipes
+                        // closing proves nothing about it: it may have closed its stdout/stderr and
+                        // lived on. What the sweep found is gone; that nothing else is left cannot be
+                        // shown, so the stop is recorded as unconfirmed and never as stopped.
+                        if (rootGone) {
+                            promoted.task.unconfirmed([]);
+                            stopLeftHolders = true;
+                            if (exitInfo !== null)
+                                promoted.out.close();
+                            return;
+                        }
                         const waitClose = Date.now() + 1_000;
                         while (exitInfo === null && Date.now() < waitClose)
                             await new Promise((r) => setTimeout(r, 25));
@@ -1708,7 +1882,7 @@ export function shellTool(opts) {
                     }
                     killing = true;
                     void killTree(child).then(({ unconfirmed }) => settle({
-                        content: `shell timed out after ${timeout}ms${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}`,
+                        content: `shell timed out after ${timeout}ms${uncertainVerdict(unconfirmed) ? ` — ${uncertainVerdict(unconfirmed)}` : ""}${exitNote()}${partialOutput()}`,
                         isError: true,
                         errorKind: "fatal",
                     }));

package/dist/process-backend.d.ts

@@ -14,6 +14,11 @@ export interface ProcessTaskBackendOptions {
     readonly runnerPath?: string;
     /** How long the runner has to record itself. Default 10 s. */
     readonly startTimeoutMs?: number;
+    /** Environment for the RUNNER process only. The command the runner starts
+     *  does not inherit it. A host whose `process.execPath` is not node (an
+     *  Electron app: `ELECTRON_RUN_AS_NODE=1` makes the runner a plain node
+     *  process and keeps it out of the Dock) says so here. */
+    readonly runnerEnv?: Readonly<Record<string, string>>;
 }
 export interface ProcessTaskBackend {
     spawn(spec: {

package/dist/process-backend.js

@@ -22,7 +22,12 @@ export function processTaskBackend(options = {}) {
             for (const [k, v] of Object.entries(env))
                 if (v !== undefined)
                     clean[k] = v;
-            const child = spawn(process.execPath, [runnerPath, dir], { detached: true, windowsHide: true, stdio: "ignore", env: clean });
+            // the runner hands its own environment to the command; the names it
+            // was given for itself are listed so it can take them out again
+            const own = options.runnerEnv ?? {};
+            const ownNames = Object.keys(own);
+            const runnerEnv = ownNames.length === 0 ? clean : { ...clean, ...own, KISO_TASK_RUNNER_OWN_ENV: ownNames.join(",") };
+            const child = spawn(process.execPath, [runnerPath, dir], { detached: true, windowsHide: true, stdio: "ignore", env: runnerEnv });
             child.unref();
             const journal = join(dir, "journal.jsonl");
             const deadline = Date.now() + (options.startTimeoutMs ?? 10_000);

package/dist/task-runner.js

@@ -105,6 +105,11 @@ function main(dir) {
     delete env.KISO_TASK_RUNNER_PAUSE_AFTER;
     delete env.KISO_TASK_RUNNER_STOP_UNCONFIRMED;
     delete env.KISO_TASK_OUTPUT_CAP;
+    // names the backend set for the runner alone (processTaskBackend runnerEnv)
+    for (const name of (env.KISO_TASK_RUNNER_OWN_ENV ?? "").split(","))
+        if (name !== "")
+            delete env[name];
+    delete env.KISO_TASK_RUNNER_OWN_ENV;
     // "" when the start time cannot be read: the identity is then the pid
     // alone, and the backend treats it as unverifiable, never as dead
     const self = processStartTime(process.pid);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.51.1",
+	"version": "0.53.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.51.1",
+		"@vincemakes/kiso-core": "0.53.0",
 		"ignore": "^7.0.9"
 	},
 	"devDependencies": {