@molecule/api-ai-tools 1.5.20 → 1.6.2

package/dist/tools.js

@@ -161,12 +161,20 @@ function waitProgressNote(o) {
     const sentence = parts.join('; ');
     return ` ${sentence[0].toUpperCase()}${sentence.slice(1)}.`;
 }
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, findPatternArgs, fusedLine, htmlOutline, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPriorityLaunch, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, emptyCallError, failureCausesNote, findPatternArgs, fusedLine, htmlOutline, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isValidGlob, linesWithinSerialized, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPriorityLaunch, truncateMiddle, universalCause, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * How long exec_command waits for a command it backgrounded only because the
  * command asked for more than the tool's ceiling, before handing back a task id.
  */
 const OVER_CEILING_GRACE_MS = 45_000;
+/**
+ * The share of its budget a command must use before the "you asked for more than
+ * this tool's ceiling" note is worth attaching. Below it the clamp changed nothing
+ * about the run, and the line read as a warning about work that had already
+ * finished (xr-molecule-flash-m83 +53:11: a Hurl run of 25 s against a 290 s
+ * ceiling carried the note).
+ */
+const CEILING_NOTE_MIN_USED = 0.5;
 /**
  * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
  * redirect below fires only when the read FAILS, so a model that knows the hoisted
@@ -488,36 +496,22 @@ export function buildTools(backend, config) {
      * listing, ENOENT parent listing, empty-read classification). Shared by the
      * single-path and batched forms of the tool.
      *
-     * @param rawPath - The path as the model sent it.
-     * @returns The same result shape read_file returns for one file.
-     */
-    /**
-     * How many leading lines of a file fit in a char budget.
-     *
-     * @param content - The file text.
-     * @param chars - The budget in chars.
-     * @returns The line count, at least one.
-     */
-    function linesWithin(content, chars) {
-        let used = 0;
-        let lines = 0;
-        for (const line of content.split('\n')) {
-            used += line.length + 1;
-            if (used > chars && lines > 0)
-                break;
-            lines++;
-        }
-        return Math.max(1, lines);
-    }
-    /**
-     * Read one file for the model: symlink-checked, size-bounded, optionally
-     * windowed by line, and never more than MAX_READ_RETURN_CHARS at once.
+     * Symlink-checked, size-bounded, optionally windowed by line, and never more
+     * than `ceiling` SERIALIZED chars at once (a window of raw text grows by its
+     * own newlines once the result is JSON — see {@link serializedChars}).
      *
      * @param rawPath - The path as the model sent it.
      * @param window - Optional `offset`/`limit` in lines.
+     * @param ceiling - The most this read may return, in serialized chars
+     *   ({@link MAX_READ_RETURN_CHARS} when the call has the whole result to
+     *   itself; a batched call passes what it has left, so the read stops short of
+     *   the request-side cut instead of being cut by it). A read that comes back
+     *   short carries `truncated: true`, which is how the batch tells a whole file
+     *   from a window of one.
      * @returns The file content (or a window of it) or a model-readable error.
      */
-    async function readOneFile(rawPath, window) {
+    async function readOneFile(rawPath, window, ceiling) {
+        const maxChars = ceiling ?? MAX_READ_RETURN_CHARS;
         const argErr = pathArgError(rawPath, 'read_file');
         if (argErr)
             return { error: argErr };
@@ -589,8 +583,8 @@ export function buildTools(backend, config) {
             // No window asked for and the file is bigger than one call should hand
             // back: return its first window, sized to the ceiling, and say so. The
             // model can read on with offset/limit; it cannot un-send 300k tokens.
-            const effectiveWindow = !sliceLines(content, window) && content.length > MAX_READ_RETURN_CHARS
-                ? { offset: 1, limit: linesWithin(content, MAX_READ_RETURN_CHARS) }
+            const effectiveWindow = !sliceLines(content, window) && serializedChars(content) > maxChars
+                ? { offset: 1, limit: linesWithinSerialized(content, maxChars) }
                 : window;
             // A SECOND window of the same small file: hand back all of it (one window is a targeted read). X1 flash-m50 paged files that fit in one
             // call 13 times in a row, each window answered with "read it again with no offset/limit".
@@ -606,7 +600,7 @@ export function buildTools(backend, config) {
             if (small?.truncated &&
                 pagedBefore &&
                 !sentWhole &&
-                content.length <= SMALL_FILE_WHOLE_CHARS) {
+                serializedChars(content) <= Math.min(SMALL_FILE_WHOLE_CHARS, maxChars)) {
                 wholeReturned.set(path, content);
                 return noted({
                     path,
@@ -625,6 +619,10 @@ export function buildTools(backend, config) {
                     offset: windowed.offset,
                     lines: windowed.lines,
                     totalLines: windowed.totalLines,
+                    // What the model has is PART of the file. Named on the result, not only
+                    // in the note: a batched read keeps whole files and lists the rest, and
+                    // this is how it tells the two apart (see the `paths` branch).
+                    ...(windowed.truncated ? { truncated: true } : {}),
                     // The note decides the executor's next call. Observed (X0 run x7): a
                     // 44 KB README read as seven 300-line windows, one round trip each,
                     // because the note only ever said "read another window" — when the
@@ -635,7 +633,7 @@ export function buildTools(backend, config) {
                             note: sentWhole
                                 ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ${windowed.totalLines}; ` +
                                     'the whole file, unchanged, was returned earlier in this conversation.'
-                                : content.length <= MAX_READ_RETURN_CHARS
+                                : serializedChars(content) <= MAX_READ_RETURN_CHARS
                                     ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
                                         `${windowed.totalLines}. The whole file is ${Math.round(content.length / 1024)} KB ` +
                                         `and fits in ONE call — read it again with no offset/limit instead of paging.`
@@ -743,6 +741,9 @@ export function buildTools(backend, config) {
             }
         },
         async read_file(input) {
+            const emptyErr = emptyCallError(input, 'read_file');
+            if (emptyErr)
+                return { error: emptyErr };
             // Several paths in ONE call. The executor issues one tool call per model
             // round-trip 89% of the time (X0: 464 assistant messages, 515 tool calls,
             // a ~10s mean gap), so a turn's wall clock IS its round-trip count — and
@@ -759,32 +760,93 @@ export function buildTools(backend, config) {
                     };
                 }
                 const files = [];
-                let budget = MAX_BATCH_READ_BYTES;
-                let stoppedAt = null;
+                // The paths this call does NOT return, in request order, each with the
+                // reason it is missing. Never a partial file in their place: a batch
+                // that broke off mid-file is what MAX_READ_CALL_CHARS exists to stop —
+                // the request side cuts a longer block through its middle, between two
+                // `"content"` values, so whole files vanish and the note says only
+                // "N characters cut here" (X0 flash-m81).
+                const notReturned = [];
+                const explicitWindow = input.offset !== undefined || input.limit !== undefined;
+                // Every entry names its file the way a returned entry does — resolved —
+                // so a path out of this list can go straight back into the next call.
+                const missing = (requestedPath, reason) => {
+                    notReturned.push({ path: resolve(requestedPath), reason });
+                };
                 for (const [index, requestedPath] of requested.entries()) {
-                    if (index >= MAX_BATCH_READ_FILES || budget <= 0) {
-                        stoppedAt = requestedPath;
-                        break;
+                    if (index >= MAX_BATCH_READ_FILES) {
+                        missing(requestedPath, 'count');
+                        continue;
+                    }
+                    // What this file's read may still carry: the call's ceiling less the
+                    // envelope, which has to hold the note and one entry per missing path.
+                    const room = MAX_READ_CALL_CHARS - JSON.stringify(files).length - READ_RESULT_ENVELOPE_CHARS;
+                    if (room <= 0) {
+                        missing(requestedPath, 'budget');
+                        continue;
+                    }
+                    const one = (await readOneFile(requestedPath, input, room));
+                    // A window is not a batch entry. It is returned only when the caller
+                    // asked for a window, or when the FIRST file alone is bigger than the
+                    // whole call — then a window with its own offset/limit note is the only
+                    // answer available, and everything after it is listed anyway.
+                    if (one.truncated === true && !explicitWindow && files.length > 0) {
+                        missing(requestedPath, 'budget');
+                        continue;
                     }
-                    const one = (await readOneFile(requestedPath, input));
                     files.push(one);
-                    if (typeof one.content === 'string')
-                        budget -= one.content.length;
                 }
-                return {
-                    files,
-                    ...(stoppedAt
-                        ? {
-                            note: `Stopped after ${files.length} of ${requested.length} files (limit: ${MAX_BATCH_READ_FILES} ` +
-                                `files or ${Math.round(MAX_BATCH_READ_BYTES / 1024)}KB per call). Call read_file again ` +
-                                `starting at ${stoppedAt}.`,
-                        }
-                        : {}),
+                const entryError = (reason) => reason === 'count'
+                    ? `not returned: one read_file call returns at most ${MAX_BATCH_READ_FILES} files. Read this file in its own read_file call.`
+                    : `not returned: this call goes in order and has reached the ${Math.round(MAX_READ_CALL_CHARS / 1024)} KB one read_file result carries. Read this file in its own read_file call.`;
+                const build = (returned) => {
+                    let returnedChars = 0;
+                    let windowed = 0;
+                    for (const f of returned) {
+                        const entry = f;
+                        if (typeof entry.content === 'string')
+                            returnedChars += entry.content.length;
+                        if (entry.truncated === true)
+                            windowed++;
+                    }
+                    const size = `${Math.round(returnedChars / 1024)} KB of the ` +
+                        `${Math.round(MAX_READ_CALL_CHARS / 1024)} KB one read_file result carries`;
+                    return {
+                        files: [
+                            ...returned,
+                            ...notReturned.map(({ path, reason }) => ({ path, error: entryError(reason) })),
+                        ],
+                        ...(notReturned.length
+                            ? {
+                                note: (windowed > 0
+                                    ? `Returned ${returned.length} of ${requested.length} files (${size}); the ` +
+                                        `${windowed} marked truncated is a first window — its own note names the next one. `
+                                    : `Returned whole: ${returned.length} of ${requested.length} files (${size}). `) +
+                                    'Not returned — read these next, in this order, in further read_file calls: ' +
+                                    `${notReturned.map((n) => n.path).join(', ')}.`,
+                            }
+                            : {}),
+                    };
                 };
+                let result = build(files);
+                // The envelope is measured, not estimated: if the note and the entries for
+                // the missing paths take more than their share, whole files — from the end
+                // — move to the missing list until the result fits.
+                while (notReturned.length > 0 &&
+                    files.length > 0 &&
+                    JSON.stringify(result).length > MAX_READ_CALL_CHARS) {
+                    const last = files.pop();
+                    notReturned.unshift({ path: String(last?.path ?? ''), reason: 'budget' });
+                    result = build(files);
+                }
+                return result;
             }
             return readOneFile(input.path, input);
         },
         async write_file(input) {
+            const emptyErr = emptyCallError(input, 'write_file');
+            if (emptyErr)
+                return { error: emptyErr };
             const argErr = pathArgError(input.path, 'write_file');
             if (argErr)
                 return { error: argErr };
@@ -831,6 +893,9 @@ export function buildTools(backend, config) {
             }
         },
         async edit_file(input) {
+            const emptyErr = emptyCallError(input, 'edit_file');
+            if (emptyErr)
+                return { error: emptyErr };
             const argErr = pathArgError(input.path, 'edit_file');
             if (argErr)
                 return { error: argErr };
@@ -1496,16 +1561,28 @@ export function buildTools(backend, config) {
                 const effectiveBudgetMs = Number.isFinite(requestedMs) && requestedMs > 0 && commandBudgetMs
                     ? Math.min(requestedMs, commandBudgetMs)
                     : commandBudgetMs;
-                const ceilingNote = wantsMore && budgetSeconds
-                    ? `You asked for ${Math.round(requestedMs / 1000)}s; this tool's ceiling is ${budgetSeconds}s. ` +
-                        'Split the work into smaller commands (one test file, one build step) rather than ' +
-                        're-running the same long one.'
-                    : null;
+                const startedAt = Date.now();
                 const result = await backend.run(command, {
                     cwd,
                     timeout: execTimeoutMs,
                     ...(effectiveBudgetMs ? { budgetMs: effectiveBudgetMs } : {}),
                 });
+                const elapsedMs = Date.now() - startedAt;
+                // The clamped ask is only worth a line when the clamp was felt: a command
+                // that asked for 600 s and finished in 25 s says nothing about splitting
+                // work, and the note read as a warning about a run that had already
+                // finished cleanly (xr-molecule-flash-m83 +53:11 — a Hurl run, 25 s).
+                // Half the budget is the line; below it no smaller unit would have been
+                // chosen any differently. A run that actually hit the ceiling is answered
+                // by the exit-124 message below, not by this note.
+                const ceilingNote = wantsMore &&
+                    budgetSeconds &&
+                    effectiveBudgetMs &&
+                    elapsedMs >= effectiveBudgetMs * CEILING_NOTE_MIN_USED
+                    ? `You asked for ${Math.round(requestedMs / 1000)}s; this tool's ceiling is ${budgetSeconds}s. ` +
+                        'Split the work into smaller commands (one test file, one build step) rather than ' +
+                        're-running the same long one.'
+                    : null;
                 // truncateMiddle (not truncate): a failing build/test/migration puts its
                 // error at the TAIL, so keep the head AND the tail — head-only truncation
                 // strands the executor with passing progress and no failure reason.
@@ -1698,7 +1775,11 @@ export function buildTools(backend, config) {
             // from the finished log: X1 flash-m76 waited out 4.0 minutes of 15 tests where every
             // failure was the same `TimeoutError: page.waitForURL` from one missing `navigate('/')`,
             // and then fixed it in 51 s. The task is NOT stopped — the executor is handed the cause and
-            // its own pid command and decides.
+            // decides, and the note tells it to let the run finish because the run's other causes only
+            // surface in it (X1 flash-m83 stopped eight runs at their first repeating cause and never
+            // finished one). Only a cause that is failing the WHOLE run — every failure sharing it,
+            // across `UNIVERSAL_CAUSE_FILES` files or more, with nothing passing since the first —
+            // comes with a stop command.
             let lastCauseLookAt = startedAt - repeatingCauseLookMs();
             let exitCode = await readExit();
             while (exitCode === null && Date.now() - startedAt < budgetMs) {
@@ -1727,6 +1808,9 @@ export function buildTools(backend, config) {
                 const found = repeatingFailure(causeLog);
                 if (!found)
                     continue;
+                // Only a cause that is failing the whole run gets a stop command — and only then is the
+                // pid walk paid for.
+                const universal = universalCause(causeLog, found);
                 repeatingCauseNoted.add(taskId);
                 const earlyMs = Date.now() - startedAt;
                 waitedByTask.set(taskId, waitedBefore + earlyMs);
@@ -1737,7 +1821,8 @@ export function buildTools(backend, config) {
                     note: repeatingFailureNote(found, {
                         taskId,
                         log,
-                        stop: await taskStopCommand(backend, taskId),
+                        stop: universal ? await taskStopCommand(backend, taskId) : '',
+                        universal,
                     }),
                 };
             }
@@ -1837,12 +1922,20 @@ export function buildTools(backend, config) {
                     // The file is gone or unreadable: the task log is the whole result, as before.
                 }
             }
+            // Every cause a finished run found, one line each, so ONE round of fixes covers all of
+            // them. A Playwright report prints its failures in sequence with nothing saying which of
+            // them share a cause, so a run's other causes are read only by reading every failure: X1
+            // flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a single cause, and
+            // the second and third were found by runs stopped before they walked the rest. Null for
+            // anything that is not a run with failures in it.
+            const causes = failureCausesNote(output);
             // Same shaping as a foreground exec result, so the executor reads both
             // the same way.
             return {
                 taskId,
                 exitCode,
                 waitedMs,
+                ...(causes ? { note: causes } : {}),
                 stdout: sanitizeOutput(truncateMiddle(output, MAX_OUTPUT_SIZE)),
                 ...(output.length > MAX_OUTPUT_SIZE ? { truncated: true, fullOutput: log } : {}),
             };