@molecule/api-ai-tools 1.6.0 → 1.6.4

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T15:16:34.345Z
+Generated: 2026-10-16T16:49:27.760Z
 -->
 
 # @molecule/api-ai-tools
@@ -644,6 +644,27 @@ function buildAgentPrompt(ctx: PromptContext): string
 
 **Returns:** Fully assembled system prompt text for the coding agent.
 
+#### `taskStopCommand(backend, taskId)`
+
+The command that stops a running background task, read from the sandbox's own pid files.
+
+THE one builder for it, so every note that hands the executor a way to stop a run hands over the
+same pid-only form: a `pkill -f <something>` matches the shell running it (its argv IS the
+command), and `molecule-dev/api/src/ai/pattern-kill-guard.ts` holds exactly that — X1
+xr-molecule-flash-m87's stuck note suggested `kill $(cat /tmp/<id>.pid) 2>/dev/null; pkill -f
+<id>.sh`, which the platform's own guard then refused, and the same shape cost a refused call at
++21:57. The pid tree is the whole of what the pattern was for: the detached shell and every
+process under it.
+
+```typescript
+function taskStopCommand(backend: ExecutionBackend, taskId: string): Promise<string>
+```
+
+- `backend` — The execution backend.
+- `taskId` — The task's `mol-bg-…` handle.
+
+**Returns:** The command to hand the executor — `kill <pids>` — falling back to the task's own pid file when the walk comes back empty (a sandbox without `pgrep`, or a pid file already gone, in which case the pid-file form is still the one the platform's guard names).
+
 #### `moleculeDistReadNote(path)`
 
 The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
@@ -1040,6 +1061,26 @@ function pathArgError(path: unknown, tool: string): string | null
 
 **Returns:** An actionable error string, or null when `path` is a non-empty string.
 
+#### `emptyCallError(input, tool)`
+
+The error for a file tool called with NO arguments at all — `edit_file {}`, the
+shape a truncated provider stream leaves behind.
+
+The path message is the wrong reading of it: "requires a non-empty path
+argument" says the call was understood and the path was left out, so the model
+retries the call it just made instead of sending the whole call again (x0
+flash-m83 +29:32: `edit_file {}`, one round lost). An empty object and a
+missing `path` are different failures and deserve different sentences.
+
+```typescript
+function emptyCallError(input: unknown, tool: string): string | null
+```
+
+- `input` — The raw tool input.
+- `tool` — The tool name, for the message.
+
+**Returns:** The truncation message, or null when the call carried any argument.
+
 #### `directoryReadHint(message, path)`
 
 Detect a "read/edit targeted a directory, not a file" failure from a backend
@@ -1233,9 +1274,11 @@ The cause repeating among a running suite's failures, or null.
 Playwright's `list` reporter prints one line per test as it finishes — its mark, its title
 path and how long it ran — and defers each failure's error to the summary at the end, so
 mid-run the only signature those lines carry is the duration. Where the log carries the
-failure bodies (a `line` reporter's output, or a finished run's summary) the repeated error
-message itself is the signature, which is stronger (it needs no assumption about how long a
-failure should take), so the message is looked for first.
+failure bodies (a `line` reporter's output, or a finished run's summary) the signature is the
+error itself — {@link failureMessage}: the error class plus the locator or the values that
+differ — which is stronger (it needs no assumption about how long a failure should take), so
+the message is looked for first and the duration is then left with the tests whose bodies the
+log does NOT carry.
 
 Either way the point is the same: a suite whose failures repeat one cause spends its whole
 runtime proving that one cause, and the executor watching it can be told so at the third
@@ -1290,9 +1333,11 @@ after another with no statement of which of them share a cause, so a run of 19 f
 bodies to read; X1 flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a
 single cause, two of them found by runs stopped before they walked the rest.
 
-The signature is the failures' own error line where the log carries their bodies (a finished
-run, or a `line` reporter), and how long they took where it does not (a still-running `list`
-log). A test the log printed twice, or failed twice, is one test.
+The signature is the cause itself where the log carries the failures' bodies (a finished run,
+or a `line` reporter) — {@link failureMessage}: the error class plus the locator or the values
+that differ — and how long they took where it does not (a still-running `list` log, which is
+why a duration group is labelled as a duration and not as a proven cause). A test the log
+printed twice, or failed twice, is one test.
 
 ```typescript
 function failuresByCause(log: string): FailureCause[]

package/dist/tools.d.ts

@@ -7,6 +7,24 @@
  * @module
  */
 import type { AITool } from '@molecule/api-ai';
+/**
+ * The command that stops a running background task, read from the sandbox's own pid files.
+ *
+ * THE one builder for it, so every note that hands the executor a way to stop a run hands over the
+ * same pid-only form: a `pkill -f <something>` matches the shell running it (its argv IS the
+ * command), and `molecule-dev/api/src/ai/pattern-kill-guard.ts` holds exactly that — X1
+ * xr-molecule-flash-m87's stuck note suggested `kill $(cat /tmp/<id>.pid) 2>/dev/null; pkill -f
+ * <id>.sh`, which the platform's own guard then refused, and the same shape cost a refused call at
+ * +21:57. The pid tree is the whole of what the pattern was for: the detached shell and every
+ * process under it.
+ *
+ * @param backend - The execution backend.
+ * @param taskId - The task's `mol-bg-…` handle.
+ * @returns The command to hand the executor — `kill <pids>` — falling back to the task's own pid
+ *   file when the walk comes back empty (a sandbox without `pgrep`, or a pid file already gone,
+ *   in which case the pid-file form is still the one the platform's guard names).
+ */
+export declare function taskStopCommand(backend: ExecutionBackend, taskId: string): Promise<string>;
 import type { ExecutionBackend, ToolBuildConfig } from './types.js';
 /**
  * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAkL9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA0DnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAk4DxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAsE9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAwHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA65DxF"}

package/dist/tools.js

@@ -63,13 +63,21 @@ const taskPidsCommand = (taskId) => `R=$(cat /tmp/${taskId}.pid 2>/dev/null); `
 /**
  * The command that stops a running background task, read from the sandbox's own pid files.
  *
+ * THE one builder for it, so every note that hands the executor a way to stop a run hands over the
+ * same pid-only form: a `pkill -f <something>` matches the shell running it (its argv IS the
+ * command), and `molecule-dev/api/src/ai/pattern-kill-guard.ts` holds exactly that — X1
+ * xr-molecule-flash-m87's stuck note suggested `kill $(cat /tmp/<id>.pid) 2>/dev/null; pkill -f
+ * <id>.sh`, which the platform's own guard then refused, and the same shape cost a refused call at
+ * +21:57. The pid tree is the whole of what the pattern was for: the detached shell and every
+ * process under it.
+ *
  * @param backend - The execution backend.
  * @param taskId - The task's `mol-bg-…` handle.
  * @returns The command to hand the executor — `kill <pids>` — falling back to the task's own pid
  *   file when the walk comes back empty (a sandbox without `pgrep`, or a pid file already gone,
  *   in which case the pid-file form is still the one the platform's guard names).
  */
-async function taskStopCommand(backend, taskId) {
+export async function taskStopCommand(backend, taskId) {
     const fallback = `kill $(cat /tmp/${taskId}.pid)`;
     try {
         const r = await backend.run(taskPidsCommand(taskId), { timeout: 10_000 });
@@ -122,7 +130,8 @@ function logProgress(log) {
 /**
  * What a wait knows about the command BESIDES "it has not exited": how long it
  * has been running, whether its output is still growing, how far its own log
- * says it has got, and how much longer that implies.
+ * says it has got, and how much longer that implies — one fact per clause, built
+ * here so the note carrying them cannot state one of them twice.
  *
  * X1 flash-m62 (2026-10-16) spent three 290 s waits on one 8.3-minute suite and
  * every answer read only "Still running after 280s": the run could not tell a
@@ -131,42 +140,78 @@ function logProgress(log) {
  * waiting. The elapsed time comes from the task id, the progress from the log
  * this wait already read, and the time left is the rate so far, said as such.
  *
+ * X1 flash-m87 §+47:20 (2026-10-16): that suite's answer read "Still running
+ * after 342s of waiting, and its output is still growing (71839 bytes) — slow,
+ * not stuck." and then this sentence, which opens with the same growth clause
+ * and gives the same elapsed time in its other format — one answer, two facts,
+ * each said twice. The clauses ARE the facts, and {@link runningNote} is the
+ * only place they become a sentence, so a lead the caller writes itself cannot
+ * repeat one (the way `deployOwedNote` returns one sentence rather than a join).
+ *
  * @param o - The wait's facts: `taskId`, the `slice` of the log it read,
  *   `stillWriting` (the log grew during this wait), `bytes` (the log's size, null
- *   when unreadable), and `ceilingMs` (this call's ceiling, for "one more wait").
- * @returns A sentence to append to a running note, or '' when nothing is known.
+ *   when unreadable), `ceilingMs` (this call's ceiling, for "one more wait"), and
+ *   `waitedMs` (this call's own wait, the elapsed figure when the id carries no
+ *   start stamp).
+ * @returns The clauses in reading order. The first states the elapsed time, so a
+ *   sentence built from them always says something.
  */
-function waitProgressNote(o) {
+function waitProgressClauses(o) {
     const startedAt = taskStartedAt(o.taskId);
-    const elapsedMs = startedAt === null ? null : Math.max(0, Date.now() - startedAt);
-    const parts = [];
-    if (elapsedMs !== null)
-        parts.push(`it has been running ${durationText(elapsedMs)}`);
+    const sinceStart = startedAt === null ? null : Math.max(0, Date.now() - startedAt);
+    // A task id this process minted always carries its start stamp; a synthetic one
+    // does not, and the time this call spent waiting is then the floor for how long
+    // the command has been running — it ran throughout that wait.
+    const clauses = [
+        sinceStart === null
+            ? `it has been running at least ${durationText(o.waitedMs)}`
+            : `it has been running ${durationText(sinceStart)}`,
+    ];
     if (o.stillWriting)
-        parts.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
+        clauses.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
     else if (o.bytes !== null)
-        parts.push(`its log has not grown during this wait (${o.bytes} bytes)`);
+        clauses.push(`its log has not grown during this wait (${o.bytes} bytes)`);
     const counter = logProgress(o.slice);
     if (counter) {
-        parts.push(`its log is at ${counter.done} of ${counter.total}`);
-        if (elapsedMs !== null && counter.done > 0 && counter.done < counter.total) {
-            const leftMs = Math.round((elapsedMs * (counter.total - counter.done)) / counter.done);
-            parts.push(leftMs <= o.ceilingMs
+        clauses.push(`its log is at ${counter.done} of ${counter.total}`);
+        // The rate is the task's own elapsed time, never this call's wait: with no
+        // start stamp, "34 tests in the 290 s I just waited" would be reported as the
+        // speed of a suite that has been walking for ten minutes.
+        if (sinceStart !== null && counter.done > 0 && counter.done < counter.total) {
+            const leftMs = Math.round((sinceStart * (counter.total - counter.done)) / counter.done);
+            clauses.push(leftMs <= o.ceilingMs
                 ? `about ${durationText(leftMs)} left at that rate — one more wait covers it`
                 : `about ${durationText(leftMs)} left at that rate (${Math.ceil(leftMs / o.ceilingMs)} more waits)`);
         }
     }
-    if (!parts.length)
+    return clauses;
+}
+/**
+ * One sentence from clauses: joined by "; ", capitalised and punctuated once.
+ *
+ * @param clauses - The facts to state, each in its own clause.
+ * @returns The sentence, or '' when there is nothing to say.
+ */
+function runningNote(clauses) {
+    if (!clauses.length)
         return '';
-    const sentence = parts.join('; ');
-    return ` ${sentence[0].toUpperCase()}${sentence.slice(1)}.`;
+    const joined = clauses.join('; ');
+    return `${joined[0].toUpperCase()}${joined.slice(1)}.`;
 }
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, 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';
+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
@@ -733,6 +778,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
@@ -833,6 +881,9 @@ export function buildTools(backend, config) {
             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 };
@@ -879,6 +930,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 };
@@ -1544,16 +1598,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.
@@ -1710,8 +1776,8 @@ export function buildTools(backend, config) {
                     status: 'stuck',
                     waitedMs: waitedBefore,
                     note: `You have already waited ${Math.round(waitedBefore / 1000)}s on this command and it ` +
-                        `has not exited — it is stuck, not slow. Kill it (exec_command: kill $(cat /tmp/${taskId}.pid) ` +
-                        `2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
+                        `has not exited — it is stuck, not slow. Kill it (\`exec_command: ` +
+                        `${await taskStopCommand(backend, taskId)}\`) and move on; do not wait on it again.`,
                 };
             }
             // The id names files under /tmp; only an id this tool minted may be used
@@ -1824,13 +1890,19 @@ export function buildTools(backend, config) {
                     // No slice: the notes still say how to peek, and the task id still
                     // carries how long the command has been running.
                 }
-                const progress = waitProgressNote({
+                // ONE sentence of facts, each said once, then what to do next: the lead
+                // this branch used to write ("Still running after 342s of waiting, and its
+                // output is still growing (71839 bytes) — slow, not stuck") restated the
+                // elapsed time and the growth clause these clauses already hold — the same
+                // sentence, twice (X1 flash-m87 §+47:20).
+                const progress = runningNote(waitProgressClauses({
                     taskId,
                     slice: soFar,
                     stillWriting,
                     bytes: grownTo,
                     ceilingMs: ceiling,
-                });
+                    waitedMs: waitedBefore + waitedMs,
+                }));
                 const sliceField = soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {};
                 if (stillWriting && waitedBefore + waitedMs >= stuckAfterMs()) {
                     waitedByTask.set(taskId, 0);
@@ -1839,9 +1911,8 @@ export function buildTools(backend, config) {
                         status: 'running',
                         waitedMs,
                         ...sliceField,
-                        note: `Still running after ${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting, and its ` +
-                            `output is still growing (${grownTo} bytes) — slow, not stuck.${progress} Call wait_for_task ` +
-                            `again to keep waiting; peek with exec_command: tail ${log}.`,
+                        note: `${progress} Call wait_for_task again to keep waiting; peek with exec_command: ` +
+                            `tail ${log}.`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -1851,8 +1922,8 @@ export function buildTools(backend, config) {
                         waitedMs: waitedBefore + waitedMs,
                         note: `${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting and it has not exited — it is ` +
                             `stuck, not slow. See what it printed with exec_command (tail /tmp/${taskId}.log — ` +
-                            `read_file cannot reach /tmp), kill it (exec_command: ` +
-                            `kill $(cat /tmp/${taskId}.pid) 2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
+                            `read_file cannot reach /tmp), kill it (\`exec_command: ` +
+                            `${await taskStopCommand(backend, taskId)}\`) and move on; do not wait on it again.`,
                     };
                 }
                 return {
@@ -1860,7 +1931,10 @@ export function buildTools(backend, config) {
                     status: 'running',
                     waitedMs,
                     ...sliceField,
-                    note: `Still running after ${Math.round(waitedMs / 1000)}s.${progress} Call wait_for_task again to ` +
+                    // No "Still running after Ns" lead here either: the clauses already say
+                    // how long it has been running, and the lead said it a second time in
+                    // the other format (X1 flash-m87 §+47:20).
+                    note: `${progress} Call wait_for_task again to ` +
                         `keep waiting — its result carries the log output. ` +
                         (soFar.trim()
                             ? `outputSoFar is the failure lines so far (up to ${RUNNING_FAILURE_LINES}) and then the end of ` +

package/dist/utilities.d.ts

@@ -286,6 +286,21 @@ export declare function findPatternArgs(pattern: string): string;
  * @returns An actionable error string, or null when `path` is a non-empty string.
  */
 export declare function pathArgError(path: unknown, tool: string): string | null;
+/**
+ * The error for a file tool called with NO arguments at all — `edit_file {}`, the
+ * shape a truncated provider stream leaves behind.
+ *
+ * The path message is the wrong reading of it: "requires a non-empty path
+ * argument" says the call was understood and the path was left out, so the model
+ * retries the call it just made instead of sending the whole call again (x0
+ * flash-m83 +29:32: `edit_file {}`, one round lost). An empty object and a
+ * missing `path` are different failures and deserve different sentences.
+ *
+ * @param input - The raw tool input.
+ * @param tool - The tool name, for the message.
+ * @returns The truncation message, or null when the call carried any argument.
+ */
+export declare function emptyCallError(input: unknown, tool: string): string | null;
 /**
  * Detect a "read/edit targeted a directory, not a file" failure from a backend
  * error message (local fs `EISDIR` or the sandbox's `cat: X: Is a directory`),
@@ -573,9 +588,11 @@ export interface RepeatingFailure {
  * Playwright's `list` reporter prints one line per test as it finishes — its mark, its title
  * path and how long it ran — and defers each failure's error to the summary at the end, so
  * mid-run the only signature those lines carry is the duration. Where the log carries the
- * failure bodies (a `line` reporter's output, or a finished run's summary) the repeated error
- * message itself is the signature, which is stronger (it needs no assumption about how long a
- * failure should take), so the message is looked for first.
+ * failure bodies (a `line` reporter's output, or a finished run's summary) the signature is the
+ * error itself — {@link failureMessage}: the error class plus the locator or the values that
+ * differ — which is stronger (it needs no assumption about how long a failure should take), so
+ * the message is looked for first and the duration is then left with the tests whose bodies the
+ * log does NOT carry.
  *
  * Either way the point is the same: a suite whose failures repeat one cause spends its whole
  * runtime proving that one cause, and the executor watching it can be told so at the third
@@ -652,9 +669,11 @@ export interface FailureCause {
  * bodies to read; X1 flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a
  * single cause, two of them found by runs stopped before they walked the rest.
  *
- * The signature is the failures' own error line where the log carries their bodies (a finished
- * run, or a `line` reporter), and how long they took where it does not (a still-running `list`
- * log). A test the log printed twice, or failed twice, is one test.
+ * The signature is the cause itself where the log carries the failures' bodies (a finished run,
+ * or a `line` reporter) — {@link failureMessage}: the error class plus the locator or the values
+ * that differ — and how long they took where it does not (a still-running `list` log, which is
+ * why a duration group is labelled as a duration and not as a proven cause). A test the log
+ * printed twice, or failed twice, is one test.
  *
  * @param log - The log of a finished or running run.
  * @returns The causes, the one with the most tests first.

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}

package/dist/utilities.js

@@ -730,6 +730,30 @@ export function pathArgError(path, tool) {
         return `${tool} requires a non-empty "path" argument (a file path relative to the project root, e.g. "api/src/handlers/index.ts").`;
     return null;
 }
+/**
+ * The error for a file tool called with NO arguments at all — `edit_file {}`, the
+ * shape a truncated provider stream leaves behind.
+ *
+ * The path message is the wrong reading of it: "requires a non-empty path
+ * argument" says the call was understood and the path was left out, so the model
+ * retries the call it just made instead of sending the whole call again (x0
+ * flash-m83 +29:32: `edit_file {}`, one round lost). An empty object and a
+ * missing `path` are different failures and deserve different sentences.
+ *
+ * @param input - The raw tool input.
+ * @param tool - The tool name, for the message.
+ * @returns The truncation message, or null when the call carried any argument.
+ */
+export function emptyCallError(input, tool) {
+    const empty = input === undefined ||
+        input === null ||
+        (typeof input === 'object' &&
+            !Array.isArray(input) &&
+            Object.keys(input).length === 0);
+    return empty
+        ? `${tool} arrived with no arguments at all — the call was cut short, usually a truncated response. Send the whole call again.`
+        : null;
+}
 /**
  * Detect a "read/edit targeted a directory, not a file" failure from a backend
  * error message (local fs `EISDIR` or the sandbox's `cat: X: Is a directory`),
@@ -1259,23 +1283,106 @@ function failedTests(log) {
  * while running "beforeEach" hook.`), which changes with the hook; the thrown error below it is
  * what repeats verbatim, so it is preferred.
  *
- * @param block - One block from {@link failureBlocks}.
+ * @param body - The block's lines, from {@link failureBody}.
  * @returns The error line, or null when the block has no body.
  */
-function failureMessage(block) {
-    const body = block
+function failureErrorLine(body) {
+    const thrown = body.find((l) => /^[A-Za-z_$][\w.$]*(?:Error|Exception)\b/.test(l));
+    return thrown ?? body[0] ?? null;
+}
+/**
+ * A failure block's own words, one per line: its body without the runner's progress lines (the
+ * `list` reporter interleaves them with the `line` reporter's blocks), without a code frame or an
+ * `at …` line (where the error happened, not what it said), and without the report's file list.
+ *
+ * @param block - One block from {@link failureBlocks}.
+ * @returns The body's lines, ANSI stripped and trimmed.
+ */
+function failureBody(block) {
+    return block
         .split('\n')
         .slice(1)
         .map((l) => l.replace(ANSI_SGR, '').trim())
-        // Progress lines the `list` reporter interleaves with the `line` reporter's blocks are not
-        // the block's own words, and a code frame or an `at …` line is where the error happened, not
-        // what it said.
         .filter((l) => l &&
         !LIST_RESULT_LINE.test(l) &&
         !/^(?:at\s|\d+ \||>\s*\d+ \||\|)/.test(l) &&
         !/^Error Context:/.test(l));
-    const thrown = body.find((l) => /^[A-Za-z_$][\w.$]*(?:Error|Exception)\b/.test(l));
-    return thrown ?? body[0] ?? null;
+}
+/**
+ * What a failure block says the failure is ABOUT, when its error line does not already say it:
+ * the locator it waited for, the navigation it waited on, or the locator and the expected/received
+ * pair of a failed assertion.
+ *
+ * Without this, every `TimeoutError: page.press: Timeout 5000ms exceeded.` in a log is one
+ * message, because that line names the ACTION (`page.press`) and never its subject. X1 flash-m84
+ * (2026-10-16) had four such failures in one run — one waiting on
+ * `button:has-text("Publish Article")`, one on `.article-preview h1`, one on
+ * `.article-preview').first().locator('.author')`, one on a generated `h1:has-text("Test
+ * Article …")` — and the run's summary called them two causes while its mid-run note called them
+ * one. The subject is what separates causes; it is in the block, and nothing else in the block
+ * carries it.
+ *
+ * @param body - The block's lines, from {@link failureBody}.
+ * @returns The detail line, or null when the block names none.
+ */
+function failureDetail(body) {
+    const waited = body.find((l) => /^-?\s*waiting for (?:locator\(|navigation|element|selector)/.test(l));
+    if (waited !== undefined)
+        return waited.replace(/^-\s*/, '');
+    // A failed assertion names its locator and the two values that differ.
+    const locator = body.find((l) => /^Locator:\s/.test(l));
+    if (locator === undefined)
+        return null;
+    const parts = [
+        locator,
+        body.find((l) => /^Expected\b/.test(l)),
+        body.find((l) => /^Received\b/.test(l)),
+    ];
+    return parts.filter((p) => p !== undefined).join(' · ');
+}
+/**
+ * A cause signature with the values that differ between two tests of ONE cause replaced by `<n>`:
+ * a duration, a generated id or timestamp, a host's port.
+ *
+ * The duration is the one that matters. A suite that sets `actionTimeout: 5_000` — the X1
+ * realworld suite does — spends `5 s` plus teardown on every "the locator never appeared"
+ * failure, so `~7 s` is a property of the CONFIG, not of the cause, and four different missing
+ * elements print the same number (X1 flash-m84, 2026-10-16). Two tests waiting on the same
+ * locator for 5 s and for 10 s wait for the same thing; two waiting on different locators do not
+ * become one cause by timing out together.
+ *
+ * @param s - An error line, with its detail.
+ * @returns The signature.
+ */
+function normalizedSignature(s) {
+    return (s
+        // A duration: the suite's own timeout, in whatever unit the runner printed.
+        .replace(/\b\d+(?:\.\d+)?\s*(?:ms|s|m)\b/g, '<n>')
+        // A host's port. The shape is what makes it a port: a bare `:32` is a line number.
+        .replace(/\b(\d{1,3}(?:\.\d{1,3}){3}|localhost|0\.0\.0\.0):\d+/g, '$1:<n>')
+        // A generated id, a timestamp, a serial: five digits or more is no part of a selector.
+        .replace(/\b\d{5,}\b/g, '<n>')
+        .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '<id>'));
+}
+/**
+ * What separates one cause from another in a `playwright test` log: the error CLASS plus the
+ * normalized message — the error line, the thing it waited for or asserted on, and the values
+ * with the test's own data normalized out.
+ *
+ * One test printed twice, or two tests failing the same way, share a signature; two tests whose
+ * errors differ in their locator do not, however alike the rest of the line is.
+ *
+ * @param block - One block from {@link failureBlocks}.
+ * @returns The signature, or null when the block has no body.
+ */
+function failureMessage(block) {
+    const body = failureBody(block);
+    const line = failureErrorLine(body);
+    if (line === null)
+        return null;
+    const detail = failureDetail(body);
+    const signature = detail !== null && !line.includes(detail) ? `${line} — ${detail}` : line;
+    return normalizedSignature(signature);
 }
 /**
  * The largest group of items sharing a key.
@@ -1325,9 +1432,11 @@ function distinctTests(tests) {
  * Playwright's `list` reporter prints one line per test as it finishes — its mark, its title
  * path and how long it ran — and defers each failure's error to the summary at the end, so
  * mid-run the only signature those lines carry is the duration. Where the log carries the
- * failure bodies (a `line` reporter's output, or a finished run's summary) the repeated error
- * message itself is the signature, which is stronger (it needs no assumption about how long a
- * failure should take), so the message is looked for first.
+ * failure bodies (a `line` reporter's output, or a finished run's summary) the signature is the
+ * error itself — {@link failureMessage}: the error class plus the locator or the values that
+ * differ — which is stronger (it needs no assumption about how long a failure should take), so
+ * the message is looked for first and the duration is then left with the tests whose bodies the
+ * log does NOT carry.
  *
  * Either way the point is the same: a suite whose failures repeat one cause spends its whole
  * runtime proving that one cause, and the executor watching it can be told so at the third
@@ -1349,12 +1458,14 @@ export function repeatingFailure(log) {
     // DISTINCT test, so the largest group is the cause the most tests share — not the one whose
     // failures happen to have been printed the most times.
     const byMessage = new Map();
+    const withBody = new Set();
     for (const block of failureBlocks(text)) {
+        const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
+        const { where, title } = splitTitlePath(m?.[1] ?? '');
         const message = failureMessage(block);
         if (message === null)
             continue;
-        const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
-        const { where, title } = splitTitlePath(m?.[1] ?? '');
+        withBody.add(testKey({ where, title, seconds: null }));
         const group = byMessage.get(message);
         if (group)
             group.push({ where, title, seconds: null });
@@ -1372,10 +1483,16 @@ export function repeatingFailure(log) {
             seconds: null,
             tests: messageGroup.members,
         };
-    // Otherwise the durations: the largest set of failures that took the same time to within the
-    // band. A test that runs to its timeout prints slightly different durations on each attempt
-    // (15.6 s, 15.1 s, 15.0 s), so the band is 0.5 s or 5% of the duration, whichever is larger.
-    const tests = distinctTests(failedTests(text));
+    // Otherwise the durations — of the tests the log says nothing ELSE about. A test whose failure
+    // body is in the log has a signature, and how long it took must not overrule it: a suite whose
+    // config sets a timeout makes every failure that waits for anything land on the same number, so
+    // the duration would merge causes the bodies just separated (X1 flash-m84, 2026-10-16 — four
+    // failures at 6.8-7.4 s, four locators, `actionTimeout: 5_000`). What is left is the shape this
+    // was written for: a `list`-only log, or a run whose bodies have not been printed yet, where
+    // the duration is the ONLY signature the log carries. A test that runs to its timeout prints
+    // slightly different durations on each attempt (15.6 s, 15.1 s, 15.0 s), so the band is 0.5 s
+    // or 5% of the duration, whichever is larger.
+    const tests = distinctTests(failedTests(text)).filter((t) => !withBody.has(testKey(t)));
     const withSeconds = tests.filter((t) => t.seconds !== null);
     let best = [];
     for (const t of withSeconds) {
@@ -1395,21 +1512,16 @@ export const REPEATING_FAILURE_LISTED = 5;
 export const FAILURE_CAUSES_LISTED = 5;
 /** How many of one cause's tests that summary names before it says "and N more". */
 export const FAILURE_CAUSE_TESTS_LISTED = 6;
-/**
- * The shortest unambiguous tail of a logged path (`…/specs/e2e/articles.spec.ts:32` →
- * `e2e/articles.spec.ts:32`).
- *
- * @param where - The location the log wrote.
- * @returns The last two path segments, with the line number.
- */
-function shortWhere(where) {
-    const parts = where.split('/');
-    return parts.slice(-2).join('/');
-}
 /**
  * The shortest unambiguous tail of a logged path's FILE (`…/specs/e2e/articles.spec.ts` →
  * `e2e/articles.spec.ts`).
  *
+ * Used only where a COUNT of files is what the sentence needs; every note that names a
+ * test to the executor prints the path the log wrote, because that is the path its own
+ * re-run hint names and the one the executor can paste back into a command (flash-m82
+ * read a shortened `e2e/auth.spec.ts:19` as a file the app owned, and rewrote its config
+ * over a suite path that was already right).
+ *
  * @param file - A path as {@link specFile} returns it.
  * @returns The last two path segments.
  */
@@ -1512,9 +1624,11 @@ export function universalCause(log, found) {
  * bodies to read; X1 flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a
  * single cause, two of them found by runs stopped before they walked the rest.
  *
- * The signature is the failures' own error line where the log carries their bodies (a finished
- * run, or a `line` reporter), and how long they took where it does not (a still-running `list`
- * log). A test the log printed twice, or failed twice, is one test.
+ * The signature is the cause itself where the log carries the failures' bodies (a finished run,
+ * or a `line` reporter) — {@link failureMessage}: the error class plus the locator or the values
+ * that differ — and how long they took where it does not (a still-running `list` log, which is
+ * why a duration group is labelled as a duration and not as a proven cause). A test the log
+ * printed twice, or failed twice, is one test.
  *
  * @param log - The log of a finished or running run.
  * @returns The causes, the one with the most tests first.
@@ -1576,11 +1690,15 @@ export function failureCausesNote(log) {
         return null;
     const listed = causes.slice(0, FAILURE_CAUSES_LISTED);
     const lines = listed.map((c, i) => {
-        const tests = c.tests
-            .slice(0, FAILURE_CAUSE_TESTS_LISTED)
-            .map((t) => shortWhere(t.where) || t.title);
+        // The path the log itself wrote, never a shortened one: it is relative to the command's own
+        // cwd, so it is the form the executor can paste back (X1 flash-m82 read a shortened
+        // `e2e/auth.spec.ts:19` as the suite's own stale starter spec, rewrote its Playwright config
+        // over it and deleted the app's tests — 4 minutes of a 60-minute run on a working config).
+        const tests = c.tests.slice(0, FAILURE_CAUSE_TESTS_LISTED).map((t) => t.where || t.title);
         const more = c.tests.length > tests.length ? `, … and ${c.tests.length - tests.length} more` : '';
-        const signature = c.message !== null ? `\`${c.message}\`` : `each after ~${c.seconds}s`;
+        const signature = c.message !== null
+            ? `\`${c.message}\``
+            : `each after ~${c.seconds}s (a shared duration, not a proven cause)`;
         const files = new Set(c.tests.map((t) => specFile(t.where)).filter(Boolean)).size;
         return (`  ${i + 1}. ${signature} — ${c.tests.length} test${c.tests.length === 1 ? '' : 's'} ` +
             `in ${files} file${files === 1 ? '' : 's'}: ${tests.join(', ')}${more}`);
@@ -1611,12 +1729,26 @@ export function failureCausesNote(log) {
  */
 export function repeatingFailureNote(found, o) {
     const listed = found.tests.slice(0, REPEATING_FAILURE_LISTED);
+    // Every row names its test by the SAME path the re-run hint below uses (`shortWhere`
+    // would print this one file under two names: X1 flash-m82 read `✘ e2e/auth.spec.ts:19`
+    // here against `Re-run fixtures/realworld/specs/e2e/auth.spec.ts:19 alone` three lines
+    // down, took the suite-relative form for "the project's own stale starter spec" and
+    // rewrote its Playwright config over it, deleted the app's tests and wrote its own —
+    // 4 minutes of a 60-minute run, on a run whose config was right). The path the log
+    // wrote is relative to the command's own cwd, so it is the one the executor can paste
+    // back into a command.
     const rows = listed
-        .map((t) => `  ✘ ${[t.where && shortWhere(t.where), t.title].filter(Boolean).join(' › ')}` +
+        .map((t) => `  ✘ ${[t.where, t.title].filter(Boolean).join(' › ')}` +
         (t.seconds === null ? '' : ` (${t.seconds}s)`))
         .join('\n');
     const more = found.count > listed.length ? `\n  … and ${found.count - listed.length} more` : '';
-    const signature = found.message !== null
+    // Two signatures, and only ONE of them is a cause. An error repeating verbatim is the cause
+    // itself; a duration repeating is what a suite's own `actionTimeout` does to every failure that
+    // waits for anything, so the note must not call it one cause (X1 flash-m84, 2026-10-16: four
+    // failures at 6.8-7.4 s, four different missing elements, and this sentence told the executor
+    // "one cause is repeating").
+    const isCause = found.message !== null;
+    const signature = isCause
         ? `every one with \`${found.message}\``
         : `each after ~${found.seconds}s — the same duration to within half a second`;
     const first = found.tests[0];
@@ -1637,14 +1769,21 @@ export function repeatingFailureNote(found, o) {
             `repeats this one cause. Stop it and fix that cause first: \`exec_command: ${o.stop}\`, ` +
             `then run the whole suite again. It is still going (${where}).${reproduce}`);
     }
-    return (`${found.count} different tests in this run have already failed the same way — ${signature} — ` +
-        `so one cause is repeating:\n${rows}${more}\n` +
-        `Start fixing it now, while the run keeps walking.${reproduce} ` +
-        `Let the rest of the run finish — it is the only thing that will name the causes that are NOT ` +
+    const keepGoing = `Let the rest of the run finish — it is the only thing that will name the causes that are NOT ` +
         `this one, and a run stopped at its first repeating cause costs a second whole run to find ` +
         `them. Stop it only if every test it walks fails this same way (the app unreachable, a 5xx on ` +
         `every request, the same selector timing out on every test of every file so far). ` +
-        `It is still going (${where}).`);
+        `It is still going (${where}).`;
+    if (isCause)
+        return (`${found.count} different tests in this run have already failed the same way — ${signature} — ` +
+            `so one cause is repeating:\n${rows}${more}\n` +
+            `Start fixing it now, while the run keeps walking.${reproduce} ${keepGoing}`);
+    return (`${found.count} different tests in this run each failed after ~${found.seconds}s — the same ` +
+        `duration to within half a second. A shared duration is a lead, not a cause: a suite whose ` +
+        `config sets a timeout spends that timeout on every failure that waits for anything, so ` +
+        `different missing elements land on the same number. Read these failures before fixing one ` +
+        `of them:\n${rows}${more}\n` +
+        `Start on them now, while the run keeps walking.${reproduce} ${keepGoing}`);
 }
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.6.0",
+  "version": "1.6.4",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "@molecule/api-ai": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.3.2",
+    "@molecule/api-ai": "1.3.3",
     "@types/node": "26.1.2",
     "esbuild": "0.28.2",
     "typescript": "6.0.3",