@vincemakes/kiso-tools-node 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -18,6 +18,42 @@
  * always has a path to the full content.
  */
 import { type Tool, type ToolResult } from "@vincemakes/kiso-core";
+/**
+ * TUI2-R1 (C) — THE SHELL PROGRESS SIDECAR.
+ *
+ * The tool contract returns output at completion; there is no
+ * incremental channel, and the ① probe pinned that adding one would be
+ * a core change this round may not make. So the shell tool ALSO writes
+ * what it sees to a temp file, and the terminal — which is a different
+ * process concern entirely — tails it. The trace-sidecar precedent
+ * governs: an observation file never feeds correctness.
+ *
+ * Four properties make that claim true rather than hopeful:
+ *
+ *   1. THE FILE IS NOT DURABLE STATE. It lives in the OS temp dir, never
+ *      under KISO_HOME. Recovery is computed from the event log; a file
+ *      the session store has never heard of cannot reach it.
+ *   2. IT IS REMOVED AT SETTLE — every settle: success, non-zero exit,
+ *      timeout, abort. A kill -9 can leave one behind, which is why (3).
+ *   3. IT IS TRUNCATED, NEVER APPENDED TO, AT THE START. A leftover from
+ *      a killed run is cleared before the first chunk, so a ghost can
+ *      never be read as this run's output.
+ *   4. EVERY FILE OPERATION IS BEST-EFFORT. A full disk, a read-only
+ *      temp dir, a racing remover — none may cost the command its
+ *      result. A degraded sidecar costs the tail and nothing else.
+ *
+ * THE KEY IS DERIVED, not the executionId: finding ①c is that the
+ * executionId is allocated kernel-side at the drain and is not reachable
+ * from inside a tool. Both sides instead hold the two facts the key is
+ * built from — the sessionId the contract already carries into execute,
+ * and the command itself, which the terminal has verbatim in the running
+ * cell's input.
+ */
+export declare const SHELL_PROGRESS_DIR: string;
+/** The sidecar path for one shell call — the same path from either side,
+ *  derived from facts both sides already have. A digest, so a command
+ *  full of slashes and dots can never become a path. */
+export declare function shellProgressPath(sessionId: string | undefined, command: string): string;
 /**
  * A path that the workspace boundary refuses — never attempted, reported as
  * a precondition (the tool COULD run it, the gate refused it).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tools-node",
-  "version": "0.7.0",
+  "version": "0.9.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.7.0"
+    "@vincemakes/kiso-core": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",