@molecule/api-ai-tools 1.9.6 → 1.9.8

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-17T20:38:26.582Z
+Generated: 2026-10-18T02:50:39.697Z
 -->
 
 # @molecule/api-ai-tools
@@ -133,6 +133,18 @@ interface LocatedCommandSegment {
    * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
    */
   separator: string
+  /**
+   * The separator that ENDED this statement — `&` when the shell backgrounds it (so the process
+   * writes its own output, not the command's), '' for the last statement of a command.
+   */
+  terminator: string
+  /**
+   * The file this statement sends its own output to (`> out.log`, `>> log`, `&> run.log`,
+   * `| tee file`), or null. Only a redirect written at the command's own level counts: one
+   * inside a `( … )` / `{ … }` group writes through that group, and one that feeds a heredoc's
+   * file (`cat > cfg.ts <<'EOF'`) is writing a config (X1 flash-m44, flash-m136).
+   */
+  redirectTarget: string | null
 }
 ```
 
@@ -175,6 +187,14 @@ interface CutRun {
   seconds: number
   /** Whether this tool's budget stopped it or the `timeout` the command carried. */
   stoppedBy: CutBy
+  /**
+   * Whether this was a detached background task, read with no budget of this tool's own
+   * ({@link commandCutRun}'s `budgetSeconds` is 0). A background run is bounded by what its own
+   * command carries — so a `command-timeout` cut there is that prefix killing the walk, and the
+   * executor must be told to drop the prefix, never to start the run in the background it is
+   * already in (X1 xr-molecule-flash-m143 +24:45).
+   */
+  background: boolean
   /**
    * The exit code the run's own process reported, or null when the code in the result belongs to
    * the pipeline's filter (`… | tail`) rather than to the run — the case that read as success.
@@ -388,6 +408,16 @@ interface TraceArtifact {
   line: number
   /** The requests the page made, the interesting ones first ({@link traceArtifactsScript}). */
   requests: TraceRequest[]
+  /**
+   * The request the failing step itself sent: the trace's LAST `fetch`/`xhr` in recording order
+   * (a click's own call), else its document request. It leads the note's row, because a click that
+   * changed nothing is explained by the request the click sent and what came back — xr-molecule-
+   * flash-m135's Follow click sent `DELETE /api/profiles/x/follow → 200` (its `following` state was
+   * stale) and the note listed only the test's earlier, answered requests.
+   *
+   * Absent when the trace recorded neither, and on traces read before this field existed.
+   */
+  lead?: TraceRequest
   /** The console errors and page errors the page raised. */
   console: string[]
   /**
@@ -728,6 +758,21 @@ interface UniversalCause {
   count: number
   /** The distinct spec files they live in, in the order the log named them. */
   files: string[]
+  /**
+   * The cause is that the page rendered NOTHING: every failure so far is a wait for an element
+   * the page never painted, whatever the selector asked for ({@link emptyPageCause}). One cause
+   * is failing every test even though no two failures share an error signature, so the note says
+   * so in the page's terms instead of naming one locator as the signature.
+   */
+  pageRendersNothing?: true
+  /** The page's own uncaught error, when the run printed one. */
+  pageError?: string
+  /**
+   * The distinct failures this cause covers, in log order — the rows a note lists for
+   * {@link pageRendersNothing}. Absent for a signature cause, whose rows are the repeating
+   * failure's own tests.
+   */
+  tests?: FailedTest[]
 }
 ```
 
@@ -983,6 +1028,35 @@ function commandTimeoutSeconds(command: string): number | null
 
 **Returns:** The seconds the command allows itself, or null.
 
+#### `withoutTimeoutWrapper(command, which)`
+
+The command with the `timeout <N>` wrapper lifted off the statements `which` selects, and the
+largest bound that was lifted.
+
+The platform moves a run to the background precisely because its own bound cannot fit this
+tool's ceiling, and a background task has no ceiling — its wait is bounded by `wait_for_task`
+and the turn's deadline. The `timeout N` an executor wrote to fit the ceiling therefore keeps
+killing the run at N in the background, where nothing needed it: X1 xr-molecule-flash-m143
+(+24:45) wrote `timeout 280` for a 31-test walk, the tool backgrounded it, and the prefix stopped
+the walk with no tally — then the cut sentence told the executor to "run it in the background",
+which is where it already was.
+
+The wrapper is found by the same parse every other command reader uses ({@link commandStart}):
+`timeout` in an argument bounds nothing, and the wrapper's own flags (`-k`/`--kill-after`,
+`-s`/`--signal`) are stepped over, so `timeout -k 5 280 …` is `280`.
+
+```typescript
+function withoutTimeoutWrapper(
+  command: string,
+  which: (segment: CommandSegment) => boolean,
+): { command: string; seconds: number | null }
+```
+
+- `command` — The shell command.
+- `which` — The statements to lift the wrapper from (a suite run, for the background path).
+
+**Returns:** The rewritten command, and the largest lifted bound (null when nothing was lifted).
+
 #### `runsInCommandPosition(command, pattern)`
 
 Whether any segment of the command runs a program whose command-position text matches
@@ -1259,6 +1333,28 @@ function guardAITool(tool: T, options?: GuardOptions): T
 
 **Returns:** A copy with a guarded `execute`.
 
+#### `diffLineCount(oldLines, newLines)`
+
+Count truly added/removed lines between two line arrays using LCS.
+
+Bounded by construction, so a whole-file edit cannot allocate a quadratic
+table here: the longest common prefix and suffix are trimmed first (exact —
+those lines belong to every optimal diff, and on the usual small edit they
+shrink the table to the edited span), and what is left is capped (see
+{@link lcsLength}).
+
+```typescript
+function diffLineCount(
+  oldLines: readonly string[],
+  newLines: readonly string[],
+): { added: number; removed: number }
+```
+
+- `oldLines` — The original lines array.
+- `newLines` — The modified lines array.
+
+**Returns:** An object with the number of added and removed lines.
+
 #### `commandRunsNoTests(command)`
 
 Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
@@ -1721,7 +1817,29 @@ function unansweredRequest(request: TraceRequest): boolean
 
 **Returns:** True when the request is still in flight and worth naming.
 
-#### `failureTraceNote(items, target, earlierFailures)`
+#### `stalledDocumentSubresource(request)`
+
+Whether a trace recorded a DOCUMENT SUBRESOURCE that never finished: a stylesheet, script or
+other asset the page itself loads, with no response and no error text — still in flight when
+the navigation timed out.
+
+The page shell's own incidental requests (`/sw.js`, the manifest, a favicon, a font) are
+excepted for the reason {@link isStaticAssetRequest} documents: m125's run was sent to write a
+caching service worker by an aborted `/sw.js`. A pending `/assets/*.css` is different — the
+navigation blocks on it, so it is the reason `page.goto` ran out of time rather than one of the
+app's API calls (xr-molecule-flash-m135 +34:10: three deployed `page.goto` timeouts on tests that
+pass locally, one 88 KB stylesheet fetch measured at 27 s, and the failing tests' traces each
+held the never-answered CSS while the note said "the cause is in the page").
+
+```typescript
+function stalledDocumentSubresource(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request is a document subresource that never finished.
+
+#### `failureTraceNote(items, target, earlierFailures, apiPrefixes)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
 what came back.
@@ -1742,8 +1860,8 @@ A 4xx request carries what the page SENT beside its status, so a wrapped body is
 line rather than inferred from the status; when one of those bodies is an object whose only key
 is `data`, the note names the call shape that produces it (xr-molecule-flash-m111 +11:36).
 
-WHICH rows it spends is evidence, not artifact order (xr-molecule-flash-m112 +53:46): a row
-needs a recorded response, a real failure or a console error ({@link traceRowEvidence}), rows are
+Every row opens with the request the failing step ITSELF sent ({@link TraceArtifact.lead}) and
+its response — whatever its status — because the question a `waiting for locator` failure asks
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
 
@@ -1752,12 +1870,14 @@ function failureTraceNote(
   items: readonly TraceArtifact[],
   target: string,
   earlierFailures?: readonly string[],
+  apiPrefixes?: readonly string[],
 ): string | null
 ```
 
 - `items` — The traces {@link parseTraceArtifacts} read.
 - `target` — Where the run went — the deployed host, as the note names it.
 - `earlierFailures` — The failing `file:line`s earlier walks of this suite left, so a repeat is ranked above a one-off. Empty when the caller knows of no earlier walk.
+- `apiPrefixes` — The API path prefixes the app's client config names (`['/api']`), read from the app by the caller. Empty when the caller could not read one; the traces' own requests may still supply it. Never a hard-coded literal.
 
 **Returns:** The note, or null when no trace held a recorded response, a real failure or a console error.
 
@@ -1947,13 +2067,24 @@ The file a command sends its own output to, when it redirects it (`> out.txt`,
 this leaves its task log empty, so the log is the wrong place to look and an empty
 log proves nothing (X1 flash-m29).
 
+Which redirect counts is decided by the command's own shell structure, from the same
+parse every other command reader uses: a redirect written in a BACKGROUNDED statement
+(`… &`) or inside a `( … )` / `{ … }` group writes that process's or group's output, not
+the command's. The platform's own preview launch is exactly that — the preview server is
+started with `>/tmp/mol-preview-4173.log 2>&1 &` inside the build/serve prelude, and the
+suite's foreground command follows it — so a reader that took the last `>` in the whole
+text told a run its output went to the PREVIEW's log (X1 flash-m136 +18:31).
+
+The target comes back without its shell quotes: `> '/tmp/x.log'` is `/tmp/x.log`, and
+the callers resolve a relative one against the command's cwd.
+
 ```typescript
 function outputRedirectTarget(command: string): string | null
 ```
 
 - `command` — The shell command.
 
-**Returns:** The target as written, or null (`/dev/null` and `&1`/`&2` are not files).
+**Returns:** The target, or null (`/dev/null` and `&1`/`&2` are not files).
 
 #### `streamingBackgroundCommand(command)`
 
@@ -2005,6 +2136,24 @@ function isSuiteRunCommand(command: string): boolean
 
 **Returns:** True when the command starts one of those runners.
 
+#### `withoutSuiteTimeout(command)`
+
+The command with the `timeout <N>` wrapper lifted off the statement that runs the suite, and the
+bound that was lifted.
+
+Used where the platform moves a run to the background: the executor wrote the bound to fit this
+tool's foreground ceiling, and in the background that ceiling no longer applies — the task is
+bounded by `wait_for_task` and the turn's deadline — so the prefix only kills the walk
+({@link withoutTimeoutWrapper}; X1 xr-molecule-flash-m143 +24:45).
+
+```typescript
+function withoutSuiteTimeout(command: string): { command: string; seconds: number | null }
+```
+
+- `command` — The shell command.
+
+**Returns:** The rewritten command, and the largest lifted bound (null when nothing was lifted).
+
 #### `isPlaywrightRunCommand(command)`
 
 Whether a command starts a Playwright run — a `playwright test` in command position, in a form
@@ -2624,13 +2773,13 @@ alongside the others.
 ```typescript
 function universalCause(
   log: string,
-  found: RepeatingFailure,
+  found: RepeatingFailure | null,
   command?: string | null,
 ): UniversalCause | null
 ```
 
 - `log` — The log so far.
-- `found` — The repeating cause {@link repeatingFailure} found in it.
+- `found` — The repeating cause {@link repeatingFailure} found in it, or null when no two failures share a signature (a page that renders nothing fails each spec at its own first locator — {@link emptyPageCause} still reads that run).
 - `command` — How the run was started, when the caller knows it: its spec-file selection scales the file threshold ({@link specFilesSelected}).
 
 **Returns:** The cause's count and files, or null when the run is not failing whole.
@@ -2661,12 +2810,12 @@ _(description truncated — read the full text in `node_modules/@molecule/api-ai
 
 ```typescript
 function earlyReturnCause(
-  found: RepeatingFailure,
+  found: RepeatingFailure | null,
   universal: UniversalCause | null | undefined,
 ): UniversalCause | null
 ```
 
-- `found` — What {@link repeatingFailure} found mid-run.
+- `found` — What {@link repeatingFailure} found mid-run, or null when no signature repeats.
 - `universal` — What {@link universalCause} found for it, if anything.
 
 **Returns:** The cause to stop the run over, or null — in which case nothing may be stopped, the wait keeps going, and the finding rides the run's result as a note.
@@ -3046,6 +3195,16 @@ How much of the response body the note prints — the API's first error line.
 const TRACE_NOTE_GOT_CHARS: 120
 ```
 
+#### `TRACE_NOTE_LEAD_GOT_CHARS`
+
+How much of the FAILING STEP's response body the note prints. Longer than
+{@link TRACE_NOTE_GOT_CHARS}: it is the one line that answers "what did the click actually get
+back", and an app's own body (`{"profile":{…}}`) can carry the answer past its first clause.
+
+```typescript
+const TRACE_NOTE_LEAD_GOT_CHARS: 200
+```
+
 #### `DIAGNOSIS_TRACE_FLAG`
 
 The `--trace` flag this platform adds, and the only value it adds it with.
@@ -3363,6 +3522,16 @@ property of the run rather than of a page.
 const UNIVERSAL_CAUSE_FILES: 3
 ```
 
+#### `EMPTY_PAGE_CAUSE_TESTS`
+
+How many tests a run must have walked — with nothing passing since its first failure — before
+"the page renders nothing" can be its one cause. A handful of failures is a handful of bugs;
+a page that never painted fails every spec that reaches it, and m141's walk had 36 by +20:30.
+
+```typescript
+const EMPTY_PAGE_CAUSE_TESTS: 15
+```
+
 #### `CONNECTION_CAUSE_TESTS`
 
 How many tests a connection-class cause must cover before the run is stopped even when they

package/dist/command-position.d.ts

@@ -114,6 +114,18 @@ export interface LocatedCommandSegment {
      * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
      */
     separator: string;
+    /**
+     * The separator that ENDED this statement — `&` when the shell backgrounds it (so the process
+     * writes its own output, not the command's), '' for the last statement of a command.
+     */
+    terminator: string;
+    /**
+     * The file this statement sends its own output to (`> out.log`, `>> log`, `&> run.log`,
+     * `| tee file`), or null. Only a redirect written at the command's own level counts: one
+     * inside a `( … )` / `{ … }` group writes through that group, and one that feeds a heredoc's
+     * file (`cat > cfg.ts <<'EOF'`) is writing a config (X1 flash-m44, flash-m136).
+     */
+    redirectTarget: string | null;
 }
 /**
  * Every statement of a command, with its own assignments and where it sits — assignment-only
@@ -160,6 +172,30 @@ export declare function statementArgumentEnd(command: string, start: number | nu
  * @returns The seconds the command allows itself, or null.
  */
 export declare function commandTimeoutSeconds(command: string): number | null;
+/**
+ * The command with the `timeout <N>` wrapper lifted off the statements `which` selects, and the
+ * largest bound that was lifted.
+ *
+ * The platform moves a run to the background precisely because its own bound cannot fit this
+ * tool's ceiling, and a background task has no ceiling — its wait is bounded by `wait_for_task`
+ * and the turn's deadline. The `timeout N` an executor wrote to fit the ceiling therefore keeps
+ * killing the run at N in the background, where nothing needed it: X1 xr-molecule-flash-m143
+ * (+24:45) wrote `timeout 280` for a 31-test walk, the tool backgrounded it, and the prefix stopped
+ * the walk with no tally — then the cut sentence told the executor to "run it in the background",
+ * which is where it already was.
+ *
+ * The wrapper is found by the same parse every other command reader uses ({@link commandStart}):
+ * `timeout` in an argument bounds nothing, and the wrapper's own flags (`-k`/`--kill-after`,
+ * `-s`/`--signal`) are stepped over, so `timeout -k 5 280 …` is `280`.
+ *
+ * @param command - The shell command.
+ * @param which - The statements to lift the wrapper from (a suite run, for the background path).
+ * @returns The rewritten command, and the largest lifted bound (null when nothing was lifted).
+ */
+export declare function withoutTimeoutWrapper(command: string, which: (segment: CommandSegment) => boolean): {
+    command: string;
+    seconds: number | null;
+};
 /**
  * Whether any segment of the command runs a program whose command-position text matches
  * `pattern` — the one question a runner-kind table asks.

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAqND;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AA+cD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAqND;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAmjBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AAwFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}