@molecule/api-ai-tools 1.6.0 → 1.6.2

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-16T15:37:48.365Z
 -->
 
 # @molecule/api-ai-tools
@@ -1040,6 +1040,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 +1253,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 +1312,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.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;AAkL9C,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,CAm5DxF"}

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, 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 +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
@@ -833,6 +844,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 +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 };
@@ -1544,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.

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":"AAAA;;;;;GAKG;AAOH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAEE,CAAA;AAuGhD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAKD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsCzD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAUpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWnE;AAuDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG;IAC3D,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,CA6FA;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAalC;AA4BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBlE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAOxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIvD;AAkCD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAID,yCAAyC;AACzC,eAAO,MAAM,aAAa,QAAkB,CAAA;AAC5C,8CAA8C;AAC9C,eAAO,MAAM,cAAc,QAAmB,CAAA;AAC9C,kDAAkD;AAClD,eAAO,MAAM,eAAe,QAAa,CAAA;AACzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA6BhG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAY5E;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAA;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,QAAmD,CAAA;AAErF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAwB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,QAAY,CAAA;AAE9C,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAKzC,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,GAAG,IAAI,CAyC3E;AAED,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,mHAW/B,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOnE;AAmFD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBjD;AAED,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,KAAK,CAAA;AAEvC,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,0KAC4G,CAAA;AAEhJ;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED,gEAAgE;AAChE,eAAO,MAAM,0BAA0B,QAAS,CAAA;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,gGAAgG;IAChG,KAAK,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;IACb,qFAAqF;IACrF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,sFAAsF;IACtF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,sDAAsD;IACtD,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAuID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAuCrE;AAED,2FAA2F;AAC3F,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,oFAAoF;AACpF,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAoE3C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,cAAc,GAAG,IAAI,CAiB1F;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,gGAAgG;IAChG,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,yFAAyF;IACzF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,kEAAkE;IAClE,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAmC3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwB5D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gBAAgB,EACvB,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;CAAE,GAClF,MAAM,CA6CR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAsCf;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,QAA0C,CAAA;AAEtE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB7D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,MAAM,GAAG,IAAI,CAKhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgBvC"}
+{"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,17 +1512,6 @@ 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`).
@@ -1512,9 +1618,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 +1684,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 +1723,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 +1763,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.2",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",