@molecule/api-ai-tools 1.5.20 → 1.6.0

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-16T12:46:49.316Z
+Generated: 2026-10-16T15:16:34.345Z
 -->
 
 # @molecule/api-ai-tools
@@ -58,6 +58,24 @@ npm install @molecule/api-ai-tools @molecule/api-ai
 
 ### Interfaces
 
+#### `CommandSegment`
+
+One statement or pipeline stage of a shell command: what it runs, and with what.
+
+```typescript
+interface CommandSegment {
+  /**
+   * The word in command position, its directory removed (`/usr/bin/hurl` → `hurl`): the program
+   * the shell would run once whatever wrappers stood in front of it are taken away.
+   */
+  program: string
+  /** The words after it, as written — quotes kept, so a quoted `"a|b"` is one word. */
+  args: readonly string[]
+  /** The program and its arguments as one line — what a runner pattern is matched against. */
+  text: string
+}
+```
+
 #### `NormalizableSchema`
 
 The JSON-Schema-ish shape every tool in this package declares.
@@ -358,13 +376,44 @@ A cause repeating among a running suite's failures.
 
 ```typescript
 interface RepeatingFailure {
-  /** How many failures share the signature. */
+  /**
+   * How many DISTINCT tests share the signature — a test printed twice (two reporters in the
+   * log) or failed twice (a retry) is one test.
+   */
   count: number
   /** The shared error line, when the log carries the failures' bodies (`line` reporter). */
   message: string | null
   /** The shared duration in seconds, when the failures line up by how long they ran. */
   seconds: number | null
-  /** The failures that share it, in log order. */
+  /** The distinct tests that share it, in log order. */
+  tests: FailedTest[]
+}
+```
+
+#### `UniversalCause`
+
+A repeating cause that is failing the WHOLE run — see {@link universalCause}.
+
+```typescript
+interface UniversalCause {
+  /** How many distinct tests share it. */
+  count: number
+  /** The distinct spec files they live in, in the order the log named them. */
+  files: string[]
+}
+```
+
+#### `FailureCause`
+
+One cause of failure in a run, and the tests it hit.
+
+```typescript
+interface FailureCause {
+  /** The error line its tests all reported, or null when only the duration ties them together. */
+  message: string | null
+  /** The duration they shared in seconds, or null when the error line is the signature. */
+  seconds: number | null
+  /** The distinct tests it hit, in the order the log named them. */
   tests: FailedTest[]
 }
 ```
@@ -419,6 +468,37 @@ function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): Execu
 
 **Returns:** A backend that proxies all filesystem calls into the sandbox.
 
+#### `commandSegments(command)`
+
+The segments of a command, each with its program and arguments — the answer every classifier
+that reads a command as "this runs the suite" is asking for.
+
+```typescript
+function commandSegments(command: string): CommandSegment[]
+```
+
+- `command` — The shell command.
+
+**Returns:** One entry per statement or pipeline stage that runs something, in order.
+
+#### `runsInCommandPosition(command, pattern)`
+
+Whether any segment of the command runs a program whose command-position text matches
+`pattern` — the one question a runner-kind table asks.
+
+The pattern is matched against `program` and its arguments as one line, so it must be
+anchored at `^`; it must not carry the `g` flag (a pattern shared between calls would then
+carry its own match position from one segment to the next).
+
+```typescript
+function runsInCommandPosition(command: string, pattern: RegExp): boolean
+```
+
+- `command` — The shell command.
+- `pattern` — An anchored pattern for the runner's invocation.
+
+**Returns:** True when a segment in command position matches.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -504,6 +584,12 @@ function guardAITool(tool: T, options?: GuardOptions): T
 Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
 command runs no test at all.
 
+A runner counts only where a shell would RUN it ({@link commandSegments}): the word in command
+position of a segment, after its wrapper prefixes. A runner named in an argument is not an
+invocation — `head -30 run-api-tests-hurl.sh` and `grep -n playwright e2e/README.md` name a
+file to read, and a `--list` written inside a file the command writes is not a flag anyone runs
+with (flash-m81).
+
 A command that invokes no runner is NOT one of these (false): "the command runs no test" is
 then true for `ls`, which is not the question any caller is asking. The question is whether
 the runner invocation each caller read as a run is one.
@@ -753,16 +839,15 @@ killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
   often `html`, which prints nothing per test. `--reporter=list` is added
   when the playwright run is the command's last step and nothing is piped or
   redirected from it: it writes each result as it finishes, and it is the
-  shape the platform reads a background suite back in (`suite-fail-fast.ts`'s
-  fail-fast note and the Tests bar both parse `list` lines). A run that names
-  `--reporter=line` is switched to `list` for the same reason — `line` writes
-  `[n/N] <title>` with no ✓/✘ mark and no duration, so on X1 flash-m62 an
-  8.3-minute walk of one suite could never trip the fail-fast note.
+  shape the platform reads a background suite back in.
 
-A run being ITERATED on (capped, narrowed, or by file) gets `list,line` instead
-of `list` alone. `list` holds every failure's error for the summary at the end,
-so mid-run its log says only how long each failure took; `line` writes the body
-as the failure happens, and a look at a running suite (`wait_for_task`'s
+The run ends up with exactly ONE reporter that prints each failure — `list`. A run that names
+any other printing reporter has it REPLACED, never joined: two of them write every test result
+into the log twice, which on X1 flash-m83 (2026-10-16) made a `--reporter=list,line` run (its
+`line` added by this function one run earlier) report two distinct failures as "4 of this run's
+tests have already failed the same way", and the executor stopped a 139-test walk at test 21
+with a single cause in hand. `line` alone is no use either: it writes `[n/N] <title>` with no
+✓/✘ mark and no duration, so on X1 flash-m62 an 8.3-minute walk of one suite could never trip
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
@@ -793,13 +878,17 @@ function isSuiteRunCommand(command: string): boolean
 
 #### `isPlaywrightRunCommand(command)`
 
-Whether a command starts a Playwright run — `playwright test` in a form that runs something.
+Whether a command starts a Playwright run — a `playwright test` in command position, in a form
+that runs something.
 
 `npx playwright test --list` matched every `\bplaywright\s+test\b` test in the platform and was
 then treated as a run: held (flash-m79's config check), backgrounded for a run that outlasts
 the tool's ceiling, and rewritten with `--reporter`. A list takes two seconds, prints its lines
 and exits, so it is none of those; {@link commandRunsNoTests} is what decides.
 
+A `playwright test` named as an argument is not a run either (`head -30 run-tests.sh`,
+`grep -n "playwright test" e2e/README.md`): the command that runs is the reader.
+
 ```typescript
 function isPlaywrightRunCommand(command: string): boolean
 ```
@@ -989,6 +1078,38 @@ function sliceLines(
 
 **Returns:** The window plus its position, or null when neither was given.
 
+#### `serializedChars(text)`
+
+A file's text as the request counts it: the length of its JSON string.
+
+JSON escaping (`\n` → `\\n`, `"` → `\"`) costs characters, and the request
+side counts the SERIALIZED tool result. A window of 59,000 characters of
+source — 1,200 lines — arrives as ~60,200 characters of JSON, over the
+ceiling it was sized for, so a window is measured with this rather than by
+its raw text length.
+
+```typescript
+function serializedChars(text: string): number
+```
+
+- `text` — The text.
+
+**Returns:** Its serialized length, without the surrounding quotes.
+
+#### `linesWithinSerialized(content, chars)`
+
+How many leading lines of a file fit inside a budget of SERIALIZED chars,
+the way `read_file` sizes a window (see {@link serializedChars}).
+
+```typescript
+function linesWithinSerialized(content: string, chars: number): number
+```
+
+- `content` — The file's full text.
+- `chars` — The budget in serialized chars.
+
+**Returns:** The line count, at least one.
+
 #### `looksLikeHtml(text)`
 
 Whether `text` is an HTML document (a doctype or an `<html` root tag).
@@ -1111,41 +1232,117 @@ 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. A `line` reporter prints the
-failure bodies as they happen, and there 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.
+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.
 
 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
 failure instead of at the last. X1 flash-m76 walked 15 tests in 4.0 minutes where 15.6 s
 each was the test timeout and one missing `navigate('/')` was the cause of all of them.
 
+The quorum is of DISTINCT tests — {@link REPEATING_FAILURE_MIN} of them — because a log that
+prints each failure twice (a second reporter, a retry) had X1 flash-m83 told that four of its
+tests had failed the same way when two had, so the executor stopped a 139-test walk at test 21
+with one cause in hand (2026-10-16).
+
 ```typescript
 function repeatingFailure(log: string): RepeatingFailure | null
 ```
 
 - `log` — The log so far.
 
-**Returns:** The repeating cause, or null when no signature has {@link REPEATING_FAILURE_MIN} failures behind it.
+**Returns:** The repeating cause, or null when no signature has {@link REPEATING_FAILURE_MIN} distinct tests behind it.
+
+#### `universalCause(log, found)`
+
+Whether a repeating cause is failing the whole run — the one case where stopping it is the
+right call.
+
+The test is: the cause accounts for every failure the log names, it has hit
+{@link UNIVERSAL_CAUSE_FILES} spec files or more, and nothing has passed since its first
+failure. An app that is not up, a 5xx on every request, or a selector that is missing on every
+page all look like that, and every remaining test will fail the same way — so the run's
+remaining minutes measure nothing. Anything less is NOT this: a cause that stops at one file,
+or that leaves other tests passing, or that shares the run with failures of another shape,
+leaves the run with something to say, and the run is the only thing that will say it. X1
+flash-m83 (2026-10-16) stopped eight local runs at their first repeating cause over 14.5
+minutes and never finished one; three of its deploys each fixed a single cause that a finished
+run would have listed alongside the others.
+
+```typescript
+function universalCause(log: string, found: RepeatingFailure): UniversalCause | null
+```
+
+- `log` — The log so far.
+- `found` — The repeating cause {@link repeatingFailure} found in it.
+
+**Returns:** The cause's count and files, or null when the run is not failing whole.
+
+#### `failuresByCause(log)`
+
+Every failure a run names, grouped by the cause behind it — one group per cause, with the
+tests it hit.
+
+The point is that ONE run yields EVERY cause. A Playwright report prints its failures one
+after another with no statement of which of them share a cause, so a run of 19 failures is 19
+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.
+
+```typescript
+function failuresByCause(log: string): FailureCause[]
+```
+
+- `log` — The log of a finished or running run.
+
+**Returns:** The causes, the one with the most tests first.
+
+#### `failureCausesNote(log)`
+
+The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
+than two of them.
+
+This is what makes a run worth finishing: every cause the run found, in the result the
+executor reads, so one round of fixes covers all of them rather than the one cause a run
+stopped early happened to reach.
+
+```typescript
+function failureCausesNote(log: string): string | null
+```
+
+- `log` — The finished run's output.
+
+**Returns:** The note, or null.
 
 #### `repeatingFailureNote(found, o)`
 
-The sentence that names a cause repeating among a running suite's failures, and the command
-that stops the run so the cause can be fixed first.
+The sentence that names a cause repeating among a running suite's failures, mid-run.
 
 Kept here, beside {@link repeatingFailure}, so the two stay in step: every word below is about
-what that function could actually see in the log.
+what that function could actually see in the log — including the count, which is of DISTINCT
+tests, so the note never names one or two tests as a cause.
+
+The note names the cause early so the executor can START FIXING while the run keeps walking,
+and it asks for the run to be stopped only when {@link universalCause} says the cause is
+failing the whole run. X1 flash-m76 (2026-10-16) spent 4.0 minutes walking 15 tests whose one
+cause was certain at the third, 47 s in, and the note answers exactly that; X1 flash-m83 then
+stopped eight runs at their first repeating cause in 14.5 minutes and never finished one, so
+the note must not say to stop when the run still has other causes to name.
 
 ```typescript
 function repeatingFailureNote(
   found: RepeatingFailure,
-  o: { taskId: string; log: string; stop: string },
+  o: { taskId: string; log: string; stop: string; universal?: UniversalCause | null },
 ): string
 ```
 
 - `found` — What {@link repeatingFailure} found.
-- `o` — The run's facts: its `taskId`, its `log` path, and `stop` — the shell command that stops it (the pids the platform's own pid file leads to).
+- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for a {@link UniversalCause} — and `universal`, what {@link universalCause} found (absent means the run is not failing whole).
 
 **Returns:** The note.
 
@@ -1272,34 +1469,67 @@ const MAX_SEARCH_CONTEXT_LINES: 40
 #### `MAX_BATCH_READ_FILES`
 
 Most files one batched `read_file` call returns. The cap exists so a survey
-of a large tree cannot swallow the turn's context in one result; the tool
-reports where it stopped so the model continues from there.
+of a large tree cannot swallow the turn's context in one result; every path
+past it is named in the result's `note` and listed with its own `error`, so
+the model continues from there.
 
 ```typescript
 const MAX_BATCH_READ_FILES: 25
 ```
 
-#### `MAX_BATCH_READ_BYTES`
+#### `MAX_READ_CALL_CHARS`
+
+The most one `read_file` RESULT may carry, in chars of its JSON — every file
+the call returns, the envelope and the note included. That is how the request
+side counts a tool result, so it is how this tool counts one too
+({@link serializedChars}).
+
+One tool result is ONE block in the request, and the request side caps a
+block: molecule-dev cuts any block over `MAX_TAIL_BLOCK_CHARS` (60,000) in
+place, keeping ~30 KB of each end. A batched read that crossed it lost its
+MIDDLE — the cut lands between two `"content"` values, so whole files fell
+out and the note in their place said only "N characters cut here" — while
+this tool's own note had promised each of those files that it "fits in one
+call, so it is not paged": X0 flash-m81 (2026-10-16) read ten e2e specs in
+one call (121,467 chars), lost the middle six, and bought them again in six
+further calls (52,908 chars).
+
+So the CALL gets the ceiling the request gives it. Whole files are returned
+up to it; the paths that did not fit are named in `note` and listed in
+`files` with their own `error`, the shape every other entry has. No file is
+ever cut, and no read result reaches the request-side cut. A test in
+molecule-dev's `context-fit` asserts the two ceilings still agree.
+
+```typescript
+const MAX_READ_CALL_CHARS: 60000
+```
+
+#### `READ_RESULT_ENVELOPE_CHARS`
 
-Total content bytes one batched `read_file` call returns, across all files.
-The per-file {@link MAX_READ_SIZE} still applies to each one.
+Room inside one read result for what is not file content: the `path`, the
+offset/line fields, and the note.
+
+A batch sizes each file against what the call has left
+({@link MAX_READ_CALL_CHARS} less this), so the entry that does not fit is
+caught here rather than by the request-side cut.
 
 ```typescript
-const MAX_BATCH_READ_BYTES: number
+const READ_RESULT_ENVELOPE_CHARS: 1000
 ```
 
 #### `MAX_READ_RETURN_CHARS`
 
 The most one read_file call returns for ONE file when no window was asked
-for, in chars. Larger files come back as their first window with a note
-saying how to read the rest.
+for, in serialized chars: larger files come back as their first window, with
+a note saying how to read the rest.
 
 MAX_READ_SIZE (5 MB) is a bound on what the tool will open, not on what it
 should hand a model: a single batched read that returned a 1.2 MB README
 put the next three provider calls at 366k tokens (~330k of them fresh)
-against a 120k-token context cap (X0 run x5, call 26). ~80 KB is ~20–25k
-tokens — a fifth of that cap, and more than any one file read usually
-needs.
+against a 120k-token context cap (X0 run x5, call 26). This is the call's
+own ceiling ({@link MAX_READ_CALL_CHARS}) less the room its envelope takes,
+so one read result — one file or twenty-five — fits inside what the request
+side carries without being cut.
 
 ```typescript
 const MAX_READ_RETURN_CHARS: number
@@ -1422,7 +1652,8 @@ const REPEATING_CAUSE_TAIL_BYTES: 40000
 
 #### `REPEATING_FAILURE_MIN`
 
-Failures that must share one signature before a running suite's repeating cause is named.
+DISTINCT tests that must share one signature before a running suite's repeating cause is named.
+A test the log prints twice, or a test that failed twice, is still one test.
 
 ```typescript
 const REPEATING_FAILURE_MIN: 3
@@ -1436,6 +1667,35 @@ How many of a repeating cause's failures the note lists before it says "and N mo
 const REPEATING_FAILURE_LISTED: 5
 ```
 
+#### `FAILURE_CAUSES_LISTED`
+
+How many causes a finished run's summary lists before it says "and N more".
+
+```typescript
+const FAILURE_CAUSES_LISTED: 5
+```
+
+#### `FAILURE_CAUSE_TESTS_LISTED`
+
+How many of one cause's tests that summary names before it says "and N more".
+
+```typescript
+const FAILURE_CAUSE_TESTS_LISTED: 6
+```
+
+#### `UNIVERSAL_CAUSE_FILES`
+
+Distinct spec FILES a repeating cause must span — with every failure sharing it and nothing
+passing since — before a run is called broken for the whole suite.
+
+One file's failures can be that file's own setup, so a cause confined to one file is never
+this. Across {@link UNIVERSAL_CAUSE_FILES} files, on the other hand, whatever it is is a
+property of the run rather than of a page.
+
+```typescript
+const UNIVERSAL_CAUSE_FILES: 3
+```
+
 #### `PARSE_CHECKABLE`
 
 Files a parse check can vouch for cheaply right after a write.
@@ -1470,9 +1730,13 @@ Peer dependencies:
 - **`read_file` takes `paths` as well as `path`.** An agent that issues one
   tool call per model round-trip pays a full round-trip per file, so a project
   survey costs minutes; batched, the same reads cost one call each 25 files
-  (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
-  stopped). Each entry carries its own content or its own error, so one bad
-  path never fails the batch.
+  (`MAX_BATCH_READ_FILES`). One result is capped at `MAX_READ_CALL_CHARS`, the
+  ceiling the request side puts on a single tool result: whole files are
+  returned up to it and every path past that is named in `note` and listed as
+  `not returned`, so a file is never handed back in part — the shape that lost
+  the middle of a ten-file batch to the request-side cut (X0 flash-m81). Each
+  entry carries its own content or its own error, so one bad path never fails
+  the batch.
 - **`edit_file` shows the result, so the model need not re-read.** A
   successful edit returns `excerpt`: each edited region as it now reads, with
   1-based line numbers (`N: text`) and a few lines of context, capped at

package/dist/command-position.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Command position: which program a shell segment actually RUNS, and which words are only
+ * arguments to something else.
+ *
+ * Every classifier that read a command as "this runs the suite" matched the runner's NAME
+ * anywhere in the text, so a runner named in an argument was read as an invocation: X1
+ * xr-molecule-flash-m81 (+20:03) sent
+ * `cd /workspace/fixtures/realworld/specs/api && ls && head -30 run-api-tests-hurl.sh` — two
+ * reads of a file that was already there — and the suite-overlap hold answered "a Playwright
+ * suite is already running against this app and database … wait for it", costing a minute of
+ * forced idling on a command that writes nothing and runs nothing. `cat`, `grep`, `sed -n`,
+ * `wc`, `ls` and `git show` of a runner script are the same shape.
+ *
+ * So this parser answers it in one place, for every caller: split the command at its pipeline
+ * and statement separators, take each segment's word in command position — after the wrapper
+ * prefixes a shell puts in front of it (`HOST=x sudo nice -n 10 npx`, `bash`, `timeout 280`) —
+ * and let the caller match its runner against THAT segment's text, never against the raw
+ * command. `{@link commandSegments}` returns the segments, and
+ * {@link runsInCommandPosition} asks one anchored pattern of them all.
+ *
+ * Not command position, and therefore not an invocation: a runner named as an argument
+ * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
+ * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
+ * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
+ * stripper first (`withoutHeredocs` in molecule-dev's suite checks).
+ *
+ * @module
+ */
+/** One statement or pipeline stage of a shell command: what it runs, and with what. */
+export interface CommandSegment {
+    /**
+     * The word in command position, its directory removed (`/usr/bin/hurl` → `hurl`): the program
+     * the shell would run once whatever wrappers stood in front of it are taken away.
+     */
+    program: string;
+    /** The words after it, as written — quotes kept, so a quoted `"a|b"` is one word. */
+    args: readonly string[];
+    /** The program and its arguments as one line — what a runner pattern is matched against. */
+    text: string;
+}
+/**
+ * The segments of a command, each with its program and arguments — the answer every classifier
+ * that reads a command as "this runs the suite" is asking for.
+ *
+ * @param command - The shell command.
+ * @returns One entry per statement or pipeline stage that runs something, in order.
+ */
+export declare function commandSegments(command: string): CommandSegment[];
+/**
+ * Whether any segment of the command runs a program whose command-position text matches
+ * `pattern` — the one question a runner-kind table asks.
+ *
+ * The pattern is matched against `program` and its arguments as one line, so it must be
+ * anchored at `^`; it must not carry the `g` flag (a pattern shared between calls would then
+ * carry its own match position from one segment to the next).
+ *
+ * @param command - The shell command.
+ * @param pattern - An anchored pattern for the runner's invocation.
+ * @returns True when a segment in command position matches.
+ */
+export declare function runsInCommandPosition(command: string, pattern: RegExp): boolean;
+//# sourceMappingURL=command-position.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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;CACb;AAqRD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}