@vincemakes/kiso-tools-node 0.49.0 → 0.50.0

package/dist/index.d.ts

@@ -61,7 +61,8 @@ export declare function shellProgressPath(sessionId: string | undefined, command
 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);
+ * - an absolute input is taken as the workspace-relative path it names when
+ *   it lies inside the root, and refused otherwise;
  * - `..` components cannot escape because the joined path is re-checked
  *   against the canonical root;
  * - SYMLINKS cannot escape: the deepest existing ancestor is realpath'd
@@ -117,6 +118,12 @@ export interface WorkspaceToolsOptions {
      *  serves the session's task outputs. Absent: today's shell, its schema
      *  byte for byte. */
     readonly tasks?: (sessionId: string | undefined) => ShellTasks | undefined;
+    /** O1 — the hidden observed revision. When present, edit_file and
+     *  write_file take no expectedRevision (the model-facing schema drops
+     *  it): the host returns the revision the model last OBSERVED for the
+     *  file (undefined: never observed — the call is refused). Absent:
+     *  the explicit expectedRevision protocol, its schema byte for byte. */
+    readonly observedRevision?: (sessionId: string | undefined, full: string, kind?: "edit" | "write") => string | undefined;
     /**
      * DC-54 — the bounds that keep a tool call finite. Every field is
      * optional and defaults to the constant beside it; a host embedding
@@ -160,6 +167,11 @@ export interface WorkspaceToolsOptions {
          *  the default wait). A shorter `foregroundMs` is raised to it; 0
          *  keeps the model's value as asked (ADR-0058 Amendment 10). */
         readonly minForegroundMs?: number;
+        /** shell, with tasks wired: the longest foreground wait (default 5
+         *  min). A longer `foregroundMs` is lowered to it — the command is
+         *  promoted to a task, never killed; it never goes below the floor;
+         *  0 keeps the model's value as asked (ADR-0058 Amendment 15). */
+        readonly maxForegroundMs?: number;
     };
 }
 export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{

package/dist/index.js

@@ -82,6 +82,9 @@ const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 /** ADR-0058 §3: with tasks, how long the shell waits before a command
  *  continues as a task (the model's own value wins). */
 const DEFAULT_FOREGROUND_MS = 60_000;
+/** ADR-0058 Amendment 15: with tasks, the longest foreground wait. A longer
+ *  `foregroundMs` still promotes here; the command is never killed. */
+const DEFAULT_MAX_FOREGROUND_MS = 300_000;
 /** A promoted task's output file rotates here, as a runner's does. */
 const TASK_OUTPUT_CAP = 64 * 1024 * 1024;
 /** A task's stop: SIGTERM, this long, then the confirmed sweep. */
@@ -164,7 +167,8 @@ function isWithin(root, target) {
 }
 /**
  * Resolve an input path strictly inside the workspace (Area 5):
- * - absolute inputs are refused (paths are workspace-relative);
+ * - an absolute input is taken as the workspace-relative path it names when
+ *   it lies inside the root, and refused otherwise;
  * - `..` components cannot escape because the joined path is re-checked
  *   against the canonical root;
  * - SYMLINKS cannot escape: the deepest existing ancestor is realpath'd
@@ -198,10 +202,18 @@ function resolveReadable(opts, input, sessionId) {
     return { full: resolveWithinRoot(opts.workspaceRoot, input), root: opts.workspaceRoot };
 }
 export function resolveWithinRoot(root, input) {
+    const rootReal = realpathSync(root);
     if (isAbsolute(input)) {
-        throw new PathEscapeError(`absolute paths are not allowed — use workspace-relative paths: ${input}`);
+        // an absolute path that names a place inside the workspace — as the
+        // root is written or as it resolves — is that workspace-relative
+        // path, and takes the same canonical checks below (symlinks, `..`)
+        for (const base of [root, rootReal]) {
+            const rel = relative(base, input);
+            if (!rel.startsWith("..") && !isAbsolute(rel))
+                return resolveWithinRoot(root, rel === "" ? "." : rel);
+        }
+        throw new PathEscapeError(`absolute path outside the workspace: ${input} — the workspace root is ${rootReal}; use a path inside it`);
     }
-    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.
@@ -369,7 +381,7 @@ export function readFileTool(opts) {
             properties: {
                 path: { type: "string", description: "Workspace-relative path of the file to read" },
                 offset: { type: "number", description: "1-based first line to read (default: 1)" },
-                limit: { type: "number", description: "Maximum number of lines to read (default: to the end of the file)" },
+                limit: { type: "number", description: "Maximum lines; omit for the default bounded window" },
             },
             required: ["path"],
             additionalProperties: false,
@@ -854,27 +866,29 @@ export function searchTextTool(opts) {
 export function writeFileTool(opts) {
     return defineTool({
         name: "write_file",
-        description: "Create or replace a whole workspace file. expectedRevision is the file's latest revision token, or \"absent\" to create a new file.",
+        description: opts.observedRevision !== undefined
+            ? "Create or replace a whole workspace file. Replacing a file needs an earlier read of it."
+            : "Create or replace a whole workspace file. expectedRevision is the file's latest revision token, or \"absent\" to create a new file.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Workspace-relative file to write" },
                 content: { type: "string", description: "Full new content" },
-                expectedRevision: {
-                    type: "string",
-                    description: 'The latest revision token, or "absent" to create',
-                },
+                ...(opts.observedRevision !== undefined ? {} : { expectedRevision: {
+                        type: "string",
+                        description: 'The latest revision token, or "absent" to create',
+                    } }),
             },
-            required: ["path", "content", "expectedRevision"],
+            required: opts.observedRevision !== undefined ? ["path", "content"] : ["path", "content", "expectedRevision"],
             additionalProperties: false,
         },
         promptSnippet: "write_file — write a whole file",
-        promptGuidelines: ["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 }) => {
+        ...(opts.observedRevision !== undefined ? {} : { promptGuidelines: ["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 }, ctx) => {
             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);
+            let expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
             let full;
             try {
                 full = resolveWithinRoot(opts.workspaceRoot, path);
@@ -887,6 +901,14 @@ export function writeFileTool(opts) {
             const guard = protectedIdentity(opts.protectedFiles);
             if (isProtectedPath(full, guard))
                 return precondition(protectedRefusalText("write_file", path));
+            // O1: bind the observed revision (never the disk's latest)
+            if (expectedRevision === undefined && opts.observedRevision !== undefined && existsSync(full)) {
+                expectedRevision = opts.observedRevision(ctx?.sessionId, full, "write");
+                // 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`);
+            }
             // WR-1 — the observed-revision stale-write guard. The decision
             // lattice runs BEFORE any bytes move; every refusal is a
             // precondition with one actionable sentence. What it proves:
@@ -928,7 +950,7 @@ export function writeFileTool(opts) {
                     return precondition(protectedRefusalText("write_file", path));
                 const current = contentRevision(held);
                 if (current !== expectedRevision) {
-                    return precondition(`write_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
+                    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`);
                 }
             }
             const tmp = `${full}.kiso-tmp-${process.pid}-${crypto.randomUUID()}`;
@@ -977,7 +999,14 @@ export function writeFileTool(opts) {
                 // WR-1: the result returns the NEW revision — the model just
                 // authored these bytes; a legal new world witness for chained
                 // edits without a wasted re-read.
-                return { content: `wrote ${path} (${content.length} chars)\n[${contentRevision(Buffer.from(content, "utf8"))}]`, isError: false };
+                // O1: with no "absent" in the input, the "created" tag tells
+                // the host's card a creation from a rewrite — a product tag,
+                // never sent to the model.
+                return {
+                    content: `wrote ${path} (${content.length} chars)\n[${contentRevision(Buffer.from(content, "utf8"))}]`,
+                    isError: false,
+                    ...(opts.observedRevision !== undefined && !exists ? { tags: ["created"] } : {}),
+                };
             }
             catch (err) {
                 // round 8: a failed write never leaves a temp file with the FULL
@@ -1129,7 +1158,9 @@ function editHunksOf(input) {
 export function editFileTool(opts) {
     return defineTool({
         name: "edit_file",
-        description: "Edit a file at its latest revision (expectedRevision): exact replacements, applied in order, all or nothing. Batch changes to this file that are already known into one call. A refusal ends on its [rev:X].",
+        description: opts.observedRevision !== undefined
+            ? "Edit a file you have read: exact replacements, applied in order, all or nothing. Batch changes to this file that are already known into one call."
+            : "Edit a file at its latest revision (expectedRevision): exact replacements, applied in order, all or nothing. Batch changes to this file that are already known into one call. A refusal ends on its [rev:X].",
         parameters: {
             type: "object",
             properties: {
@@ -1149,18 +1180,18 @@ export function editFileTool(opts) {
                     minItems: 1,
                     maxItems: 32,
                 },
-                expectedRevision: { type: "string", description: "The file's latest revision token" },
+                ...(opts.observedRevision !== undefined ? {} : { expectedRevision: { type: "string", description: "The file's latest revision token" } }),
             },
-            required: ["path", "edits", "expectedRevision"],
+            required: opts.observedRevision !== undefined ? ["path", "edits"] : ["path", "edits", "expectedRevision"],
             additionalProperties: false,
         },
         promptSnippet: "edit_file — replace oldText with newText",
-        promptGuidelines: ["cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
-        execute: async (input) => {
+        ...(opts.observedRevision !== undefined ? {} : { promptGuidelines: ["cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"] }),
+        execute: async (input, ctx) => {
             const { path, expectedRevision: citedRevision } = input;
             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);
+            let expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
             const shape = editHunksOf(input);
             if (typeof shape === "string")
                 return { content: shape, isError: true, errorKind: "invalid_input" };
@@ -1177,6 +1208,12 @@ export function editFileTool(opts) {
             const guard = protectedIdentity(opts.protectedFiles);
             if (isProtectedPath(full, guard))
                 return precondition(protectedRefusalText("edit_file", path));
+            // O1: bind the observed revision (never the disk's latest)
+            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`);
+            }
             // WR-1: edits always target an existing file — the revision is
             // not optional here, and the refusal teaches the protocol.
             if (expectedRevision === undefined) {
@@ -1218,7 +1255,9 @@ export function editFileTool(opts) {
                     // ACI-3: the refusal carries the file as it is where each hunk
                     // should land, and its current revision last — the retry needs
                     // no read. The headline is unchanged (bench parsers read it).
-                    return precondition(`edit_file: ${path} changed since ${expectedRevision} — the file as it is now is below; re-apply the change against it, citing the [rev:…] on the last line\n${staleReport(text, hunks, single)}\n[${current}]`);
+                    return precondition(opts.observedRevision !== undefined
+                        ? `edit_file: ${path} changed since you last observed it — the file as it is now is below; re-apply the change against it\n${staleReport(text, hunks, single)}\n[${current}]`
+                        : `edit_file: ${path} changed since ${expectedRevision} — the file as it is now is below; re-apply the change against it, citing the [rev:…] on the last line\n${staleReport(text, hunks, single)}\n[${current}]`);
                 }
                 // ACI-3 (superseding WR-1E2's one-snapshot rule): the hunks apply
                 // IN ORDER, each against the result of the ones before it — the
@@ -1240,7 +1279,12 @@ export function editFileTool(opts) {
                 for (let i = 0; i < hunks.length; i += 1) {
                     const h = { search: lf(hunks[i].search), replace: lf(hunks[i].replace) };
                     const { count, offsets } = occurrencesOf(edited, h.search);
-                    const which = single ? "" : i === 0 ? " (hunk 1)" : ` (hunk ${i + 1}, after ${i === 1 ? "hunk 1" : `hunks 1–${i}`} applied)`;
+                    // a batch's later hunk is matched against the text the earlier
+                    // ones made IN MEMORY; "after hunk 1 applied" read as written,
+                    // and the model repaired a hunk that never landed (the TB20
+                    // trajectory audit) — so a batch refusal says nothing changed
+                    const which = single ? "" : i === 0 ? " (hunk 1)" : ` (hunk ${i + 1}, matched after ${i === 1 ? "hunk 1" : `hunks 1–${i}`})`;
+                    const untouched = hunks.length > 1 ? ` — nothing was written, ${path} is unchanged` : "";
                     if (count === 0) {
                         // WR-1A ④: the WORLD lacks the pattern (the input is
                         // fine) and nothing ran — precondition; the note never
@@ -1257,7 +1301,7 @@ export function editFileTool(opts) {
                         const swap = h.replace.length > 0 && occurrencesOf(edited, h.replace).count === 1
                             ? "\n  newText is already in the file once and oldText is not: either this change is already applied, or oldText and newText are swapped"
                             : "";
-                        return precondition(`edit_file: pattern not found in ${path}${which}${detail ? `\n${detail}` : ""}${swap}${block}\n[${current}]`);
+                        return precondition(`edit_file: pattern not found in ${path}${which}${untouched}${detail ? `\n${detail}` : ""}${swap}${block}\n[${current}]`);
                     }
                     // ACI-2: more than one resolution is a QUESTION, not an edit.
                     // Taking the first one wrote the wrong place and reported
@@ -1267,7 +1311,7 @@ export function editFileTool(opts) {
                     if (count > 1) {
                         const lines = describeMatchLines(edited, offsets, count <= ACI2_OFFSETS_KEPT);
                         const where = which === "" ? lines : `${which.slice(2, -1)}, ${lines}`;
-                        return precondition(`edit_file: pattern matches ${count} places in ${path} (${where}) — include enough surrounding text to make it unique\n[${current}]`);
+                        return precondition(`edit_file: pattern matches ${count} places in ${path} (${where}) — include enough surrounding text to make it unique${untouched !== "" ? `; nothing was written, ${path} is unchanged` : ""}\n[${current}]`);
                     }
                     edited = edited.slice(0, offsets[0]) + h.replace + edited.slice(offsets[0] + h.search.length);
                 }
@@ -1409,11 +1453,14 @@ export function shellTool(opts) {
             // ADR-0058 Amendment 10: with tasks wired a wait shorter than the
             // floor only moves the command to the background sooner, so the
             // model may lengthen the wait, never shorten it. Without tasks the
-            // wait is a kill timeout and is kept as asked.
+            // wait is a kill timeout and is kept as asked. Amendment 15: a
+            // wait past the ceiling only holds the turn — the command is
+            // promoted there and the model is notified when it ends.
             const asked = [foregroundMs, timeoutMs].find((v) => typeof v === "number" && Number.isFinite(v));
-            const timeout = tasks !== undefined
-                ? Math.max(asked ?? DEFAULT_FOREGROUND_MS, opts.limits?.minForegroundMs ?? DEFAULT_FOREGROUND_MS)
-                : (asked ?? DEFAULT_SHELL_TIMEOUT_MS);
+            const floor = opts.limits?.minForegroundMs ?? DEFAULT_FOREGROUND_MS;
+            const ceiling = opts.limits?.maxForegroundMs ?? DEFAULT_MAX_FOREGROUND_MS;
+            const raised = Math.max(asked ?? DEFAULT_FOREGROUND_MS, floor);
+            const timeout = tasks !== undefined ? (ceiling > 0 ? Math.min(raised, Math.max(ceiling, floor)) : raised) : (asked ?? DEFAULT_SHELL_TIMEOUT_MS);
             // E group: a PRE-aborted signal never spawns the command.
             if (ctx.signal.aborted) {
                 return { content: "shell aborted before start", isError: true, errorKind: "fatal" };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.49.0",
+	"version": "0.50.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.49.0",
+		"@vincemakes/kiso-core": "0.50.0",
 		"ignore": "^7.0.9"
 	},
 	"devDependencies": {