@molecule/api-ai-tools 1.5.18 → 1.5.20

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-16T09:30:45.054Z
+Generated: 2026-10-16T12:46:49.316Z
 -->
 
 # @molecule/api-ai-tools
@@ -242,6 +242,23 @@ interface ToolBuildConfig {
    */
   searchExcludedDirs?: string[]
 
+  /**
+   * Whether a LARGE HTML document should come back as its OUTLINE — the head's
+   * tags and the tags that open each body section, one line each, plus a note
+   * naming the offset/limit that returns the whole document — instead of its
+   * whole text. Over {@link MAX_HTML_INLINE_CHARS}, and only when the read named
+   * no line window.
+   *
+   * A getter, not a boolean, because the answer belongs to the TURN, not to the
+   * tool set: a host that plans first and builds after wants an outline while the
+   * executor is researching (where a read it cannot act on is pure context cost)
+   * and the document itself while it is writing the page. Unset means every big
+   * HTML read returns its text, which is what a host with no such phases wants.
+   *
+   * @returns True when a large HTML read should be outlined rather than returned.
+   */
+  outlineLargeHtml?: () => boolean
+
   /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
   onAfterWrite?: (path: string) => Promise<void>
 
@@ -320,6 +337,38 @@ interface PromptContext {
 }
 ```
 
+#### `FailedTest`
+
+One failed test, as a running suite's log names it.
+
+```typescript
+interface FailedTest {
+  /** The location the log writes (`specs/e2e/articles.spec.ts:32`), or '' when it writes none. */
+  where: string
+  /** The test's own title — the last segment of its title path. */
+  title: string
+  /** How long it ran before failing, in seconds, or null when the log does not say. */
+  seconds: number | null
+}
+```
+
+#### `RepeatingFailure`
+
+A cause repeating among a running suite's failures.
+
+```typescript
+interface RepeatingFailure {
+  /** How many failures share the signature. */
+  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. */
+  tests: FailedTest[]
+}
+```
+
 ### Types
 
 #### `DiscoveredSkill` _(deprecated)_
@@ -450,6 +499,27 @@ function guardAITool(tool: T, options?: GuardOptions): T
 
 **Returns:** A copy with a guarded `execute`.
 
+#### `commandRunsNoTests(command)`
+
+Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
+command runs no test at all.
+
+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.
+
+A command that also runs tests is false however it is spelled: `npx playwright install &&
+npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
+reading a real run.
+
+```typescript
+function commandRunsNoTests(command: string): boolean
+```
+
+- `command` — The shell command as the executor sent it.
+
+**Returns:** True when the command invokes a runner only to print.
+
 #### `discoverSkills(backend)`
 
 Discover skills from a project directory.
@@ -689,7 +759,12 @@ killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
   `[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.
 
-Only the command's last step is touched, and only its reporter.
+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
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
 ```typescript
 function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
@@ -699,6 +774,73 @@ function streamingBackgroundCommand(command: string): { command: string; changes
 
 **Returns:** The command to run and one sentence per change made (empty when none).
 
+#### `isSuiteRunCommand(command)`
+
+Whether a command runs a whole test suite — a Playwright, Vitest or Hurl run
+— rather than a build, an install or a one-off script.
+
+A command that invokes a runner only to print is not one of these
+({@link commandRunsNoTests}): `npx playwright test --list` prints the tests it would run and
+exits, and `npx playwright install`, `vitest list` and `hurl --help` start no test either.
+
+```typescript
+function isSuiteRunCommand(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when the command starts one of those runners.
+
+#### `isPlaywrightRunCommand(command)`
+
+Whether a command starts a Playwright run — `playwright test` 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.
+
+```typescript
+function isPlaywrightRunCommand(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when the command starts a Playwright run.
+
+#### `suiteRunPriorityLaunch(command, launch)`
+
+Start a background suite run at lower CPU and IO priority, so the sandbox it
+shares with everything else stays responsive to what the executor does next.
+
+A whole-suite Playwright run saturates the one container the app's Vite
+server, its API process and every other command also live in: on X1 flash-m75
+the model backgrounded a 139-test run at +36:23 and the two-word shell
+command it sent next — tick its plan file — returned nothing for 2 min 40 s,
+measured on the chat payload and on the live-stream follower independently.
+The backgrounding note is right that the executor should go do other work;
+what it cannot promise is that the sandbox will let it.
+
+`nice -n 10` lowers the run's CPU share and `ionice -c3` its IO class. Both
+are PROBED in the sandbox by RUNNING them, not with `command -v`: a syscall a
+container's seccomp policy refuses leaves `-v` passing while the real run
+fails. Each is applied only if its probe passed, so a sandbox with neither,
+or with only one, runs the suite exactly as it did before. Playwright's own
+workers are children of this shell and inherit both (niceness and IO class
+are inherited across fork/exec).
+
+Only a command the caller has already detached reaches this: foreground
+commands are never touched.
+
+```typescript
+function suiteRunPriorityLaunch(command: string, launch: string): { launch: string; note: string }
+```
+
+- `command` — The command as the executor sent it; the suite detection reads this.
+- `launch` — The shell line that would start it, with no prefix of its own.
+
+**Returns:** The line to run, and one sentence for the tool note ('' when unchanged).
+
 #### `checkBlockedCommand(command)`
 
 Check if a command is blocked for security reasons. Returns error message or null if allowed.
@@ -766,6 +908,32 @@ function isValidGlob(pattern: string): boolean
 
 **Returns:** `true` when the pattern contains only allowed characters.
 
+#### `findPatternArgs(pattern)`
+
+The `find` predicate for a `find_files` pattern.
+
+`find -name` compares a pattern against a file's BASENAME, so a pattern
+containing a slash (`helpers/*`, `e2e/*.spec.ts`, `src` + `**` + `/App.tsx`)
+can never match and the tool answers `[]` (xr-molecule-flash-m77, on two
+calls in one run). Such a pattern is matched with `-path` instead: an fnmatch
+glob over the whole printed path, whose `*` crosses `/` — the rule
+`.gitignore` uses, and the reason a bare `helpers/*` means "a `helpers/`
+directory anywhere below the root". The pattern is anchored with a leading
+`*` then `/` ("any parent") so the search root — an absolute
+`/workspace/<app>` in a sandbox — need not be spelled out.
+
+A doubled-star directory segment keeps its usual meaning of ZERO or more
+directories; `-path` alone would demand at least one, so the pattern is also
+emitted with each such segment removed.
+
+```typescript
+function findPatternArgs(pattern: string): string
+```
+
+- `pattern` — A pattern already accepted by {@link isValidGlob}.
+
+**Returns:** A `find` predicate: `-name '…'` for a bare name, else one or more `-path '…'` alternatives, ORed inside parens when there is more than one.
+
 #### `pathArgError(path, tool)`
 
 Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -821,6 +989,36 @@ function sliceLines(
 
 **Returns:** The window plus its position, or null when neither was given.
 
+#### `looksLikeHtml(text)`
+
+Whether `text` is an HTML document (a doctype or an `<html` root tag).
+
+```typescript
+function looksLikeHtml(text: string): boolean
+```
+
+#### `htmlOutline(text, label)`
+
+An OUTLINE of an HTML document: its head's tags and the tags that open each
+body section, one per line, with line numbers.
+
+Line-based on purpose — a parser would be a dependency and an attack surface
+for a read that only has to be _navigable_. A line is shown when it starts with
+`<` after trimming, which is what keeps the inside of a `<style>` block, a
+`<script>` body or a prerendered text section out of the outline while keeping
+every tag the document is built from. Long lines (a minified tag, a data URI)
+are cut, and the whole outline is capped, so a pathological document cannot
+turn one read into another wall of text.
+
+```typescript
+function htmlOutline(text: string, label?: string): string | null
+```
+
+- `text` — The document's full text.
+- `label` — What to call the document in the outline's header (its path).
+
+**Returns:** The outline — or null when `text` is not an HTML document.
+
 #### `truncate(s, maxLength)`
 
 Truncate a string to a max length with a truncation notice.
@@ -887,6 +1085,70 @@ function runningOutputSliceCommand(log: string, own?: string): string
 
 **Returns:** The shell command, safe to hand to the execution backend as-is.
 
+#### `runningCauseCommand(log, own)`
+
+The shell command whose stdout is enough of a running log to tell whether one cause is
+repeating: its tail, {@link REPEATING_CAUSE_TAIL_BYTES} of it.
+
+{@link runningOutputSliceCommand} is the wrong read for this: it keeps only the FIRST 40
+failure lines plus 1 000 bytes, so on a run whose failures print a body each — which is what
+a `line` reporter does, and the only form that names the cause as an error message rather than
+a duration — three bodies do not fit, and the repeat is invisible. This read is not shown to
+anyone; it is parsed.
+
+```typescript
+function runningCauseCommand(log: string, own?: string): string
+```
+
+- `log` — The task log path.
+- `own` — A file the command redirects its own output to, if any.
+
+**Returns:** The shell command, safe to hand to the execution backend as-is.
+
+#### `repeatingFailure(log)`
+
+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.
+
+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.
+
+```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.
+
+#### `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.
+
+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.
+
+```typescript
+function repeatingFailureNote(
+  found: RepeatingFailure,
+  o: { taskId: string; log: string; stop: string },
+): 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).
+
+**Returns:** The note.
+
 #### `whitespaceTolerantReplace(content, oldString, newString)`
 
 Attempt a whitespace-tolerant replacement when an exact `old_string` match
@@ -1053,6 +1315,38 @@ file under it "fits in ONE call", and a smaller bound here broke that promise (X
 const SMALL_FILE_WHOLE_CHARS: number
 ```
 
+#### `MAX_HTML_INLINE_CHARS`
+
+How large an HTML document must be before a whole-file read is replaced by its
+outLINE — much smaller than {@link MAX_READ_RETURN_CHARS}, because the cost of
+an HTML read is almost never worth it.
+
+An entry document is boilerplate the reader rarely needs in full: meta tags,
+stylesheet and preload links, a `<style>` block, and a handful of `<script>`
+tags. The parts an executor acts on — the body's structure, where a script is
+loaded — are all visible in an outline of one line per tag. X0 flash-m77 paid
+63,735 chars for one such read: ~60 KB of it was the IDE's own preview bridges,
+and the read pushed the transcript past its context cap, so the e2e specs the
+executor had just read were trimmed to summaries and it read the whole suite
+again — twice (findings, +01:23 and +02:56). The scaffold now keeps those
+bridges in separate files, but a template's own head is still ~5-12 KB, and a
+static-site or SSR entry can be far more.
+
+The outline is not a truncation: the note beside it names the exact
+offset/limit that returns the whole document in one call.
+
+```typescript
+const MAX_HTML_INLINE_CHARS: number
+```
+
+#### `MAX_HTML_OUTLINE_LINES`
+
+Most lines an HTML outline prints before it stops and says so.
+
+```typescript
+const MAX_HTML_OUTLINE_LINES: 200
+```
+
 #### `MAX_SEARCH_RESULTS`
 
 Max search results.
@@ -1118,6 +1412,30 @@ numbered block header, and a runner's own error lines. Matched with `grep -E`.
 const RUNNING_FAILURE_LINE_RE: '^[[:space:]]*(✘|✗|×|✖|✕|[0-9]+\\)|[0-9]+ (passed|failed|flaky|skipped|did not run)|FAIL|FAILED|ERROR|Error:|error:|Traceback|AssertionError)'
 ```
 
+#### `REPEATING_CAUSE_TAIL_BYTES`
+
+Bytes of a running log a repeating-cause look reads back.
+
+```typescript
+const REPEATING_CAUSE_TAIL_BYTES: 40000
+```
+
+#### `REPEATING_FAILURE_MIN`
+
+Failures that must share one signature before a running suite's repeating cause is named.
+
+```typescript
+const REPEATING_FAILURE_MIN: 3
+```
+
+#### `REPEATING_FAILURE_LISTED`
+
+How many of a repeating cause's failures the note lists before it says "and N more".
+
+```typescript
+const REPEATING_FAILURE_LISTED: 5
+```
+
 #### `PARSE_CHECKABLE`
 
 Files a parse check can vouch for cheaply right after a write.

package/dist/index.d.ts

@@ -117,6 +117,7 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './input-normalizer.js';
+export * from './no-test-run.js';
 export * from './schemas.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -117,6 +117,7 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './input-normalizer.js';
+export * from './no-test-run.js';
 export * from './schemas.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/no-test-run.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The runner invocations that print information and run no test — the one classifier every
+ * site asks before it treats a command as a test run.
+ *
+ * A Playwright CLI has subcommands and flags that never start a test: `playwright test --list`
+ * prints the tests it would run and exits, `show-report`/`show-trace` open a saved report,
+ * `codegen` records one, `install` fetches browsers, `merge-reports` joins blobs, and
+ * `--help`/`--version` print and exit. Vitest lists with `vitest list` / `--list` and hurl
+ * prints with `--help`/`--version`, the same way.
+ *
+ * Every check in the platform read such a command as a whole-suite run, because each one
+ * matched the runner's NAME. X1 xr-molecule-flash-m79's first Playwright command was a config
+ * check — a config written to `/tmp`, `cp`'d beside the suite and used with `--list` — and it
+ * came back HELD, `status: not_run`, with a ~4 KB `suiteNote` telling it to send the same
+ * command with `--max-failures=15` ("uncapped it walks every test … 8–13 minutes"), beside an
+ * environment block saying the run "ran on their defaults" and an import note about a path the
+ * `cp` had already fixed. Nothing ran. The model gave up on the approach, wrote a second
+ * config, and its next command was held again (flash-m74's "same command three times" shape):
+ * two holds, zero tests, and the config check it asked for never answered.
+ *
+ * So the classifiers live here, in one place, and callers ask them instead of their own
+ * regexes: {@link commandRunsNoTests} answers for a whole command, and the runner-specific
+ * sites (molecule-dev's suite checks, `streamingBackgroundCommand`, `isSuiteRunCommand`) route
+ * through it. A command that runs no test is never held, never noted, and never rewritten
+ * (`--retries`, `--reporter`) as if it were a run.
+ *
+ * @module
+ */
+/**
+ * Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
+ * command runs no test at all.
+ *
+ * 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.
+ *
+ * A command that also runs tests is false however it is spelled: `npx playwright install &&
+ * npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
+ * reading a real run.
+ *
+ * @param command - The shell command as the executor sent it.
+ * @returns True when the command invokes a runner only to print.
+ */
+export declare function commandRunsNoTests(command: string): boolean;
+//# sourceMappingURL=no-test-run.d.ts.map

package/dist/no-test-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-test-run.d.ts","sourceRoot":"","sources":["../src/no-test-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA6EH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAY3D"}

package/dist/no-test-run.js

@@ -0,0 +1,125 @@
+/**
+ * The runner invocations that print information and run no test — the one classifier every
+ * site asks before it treats a command as a test run.
+ *
+ * A Playwright CLI has subcommands and flags that never start a test: `playwright test --list`
+ * prints the tests it would run and exits, `show-report`/`show-trace` open a saved report,
+ * `codegen` records one, `install` fetches browsers, `merge-reports` joins blobs, and
+ * `--help`/`--version` print and exit. Vitest lists with `vitest list` / `--list` and hurl
+ * prints with `--help`/`--version`, the same way.
+ *
+ * Every check in the platform read such a command as a whole-suite run, because each one
+ * matched the runner's NAME. X1 xr-molecule-flash-m79's first Playwright command was a config
+ * check — a config written to `/tmp`, `cp`'d beside the suite and used with `--list` — and it
+ * came back HELD, `status: not_run`, with a ~4 KB `suiteNote` telling it to send the same
+ * command with `--max-failures=15` ("uncapped it walks every test … 8–13 minutes"), beside an
+ * environment block saying the run "ran on their defaults" and an import note about a path the
+ * `cp` had already fixed. Nothing ran. The model gave up on the approach, wrote a second
+ * config, and its next command was held again (flash-m74's "same command three times" shape):
+ * two holds, zero tests, and the config check it asked for never answered.
+ *
+ * So the classifiers live here, in one place, and callers ask them instead of their own
+ * regexes: {@link commandRunsNoTests} answers for a whole command, and the runner-specific
+ * sites (molecule-dev's suite checks, `streamingBackgroundCommand`, `isSuiteRunCommand`) route
+ * through it. A command that runs no test is never held, never noted, and never rewritten
+ * (`--retries`, `--reporter`) as if it were a run.
+ *
+ * @module
+ */
+/**
+ * A runner's name as a statement invokes it, from the start of its own arguments. The trailing
+ * guard is what separates the runner from a FILE named after it — `-c playwright.local.config.ts`
+ * names a config, not a second invocation, and reading it as one would give that "invocation" no
+ * `--list` of its own and un-do the answer for the real one.
+ */
+const INVOCATIONS = [
+    ['playwright', /(?:^|[\s;&|(])(?:npx\s+(?:--no-install\s+)?)?(?:\S*\/)?playwright(?![\w.-])/g],
+    ['vitest', /(?:^|[\s;&|(])(?:npx\s+(?:--no-install\s+)?)?(?:\S*\/)?vitest(?![\w.-])/g],
+    ['hurl', /(?:^|[\s;&|(])(?:\S*\/)?hurl(?![\w.-])/g],
+];
+/** Playwright's subcommands that start no test. */
+const PLAYWRIGHT_INFO_SUBCOMMANDS = [
+    'show-report',
+    'show-trace',
+    'codegen',
+    'install',
+    'merge-reports',
+];
+/** Vitest's subcommand that prints what a run would collect. */
+const VITEST_LIST_SUBCOMMAND = 'list';
+/**
+ * The flags that put a runner in an information mode: it prints and exits. `-h` is `--help`
+ * for all three (hurl's manual documents `-h, --help`; Playwright's and Vitest's CLIs follow
+ * the same convention), and the value-taking flags beside them are why each is matched as a
+ * whole token — hurl's `-H` is a header, not help.
+ */
+const NO_RUN_FLAGS = {
+    playwright: [
+        /(?:^|\s)--list(?=\s|$)/,
+        /(?:^|\s)--dry-run(?=\s|$)/,
+        /(?:^|\s)--help(?=\s|$)/,
+        /(?:^|\s)-h(?=\s|$)/,
+        /(?:^|\s)--version(?=\s|$)/,
+    ],
+    vitest: [
+        /(?:^|\s)--list(?=\s|$)/,
+        /(?:^|\s)--help(?=\s|$)/,
+        /(?:^|\s)-h(?=\s|$)/,
+        /(?:^|\s)--version(?=\s|$)/,
+    ],
+    hurl: [/(?:^|\s)--help(?=\s|$)/, /(?:^|\s)-h(?=\s|$)/, /(?:^|\s)--version(?=\s|$)/],
+};
+/** Statements of a shell command, the way the suite checks split them. */
+const STATEMENT_SEP = /\s*(?:&&|\|\||;|\||\n)\s*/;
+/**
+ * A heredoc body is data a command writes, not what it runs: a `playwright test --list` inside
+ * the config a command writes is not a run of this command either way. The pattern consumes the
+ * writer's own line prefix, the same shape `outputRedirectTarget` reads.
+ */
+const HEREDOC = /[^\n;&|]*<<-?\s*(['"]?)(\w+)\1[\s\S]*?\n\s*\2\b/g;
+/**
+ * Whether this runner's invocation — the text from just after its name to the end of its
+ * statement — only prints.
+ *
+ * @param runner - The runner the statement invokes.
+ * @param after - Everything after the runner's name in that statement.
+ * @returns True when the invocation starts no test.
+ */
+function informational(runner, after) {
+    const first = after.trimStart().split(/\s+/)[0] ?? '';
+    if (runner === 'playwright' && PLAYWRIGHT_INFO_SUBCOMMANDS.includes(first))
+        return true;
+    if (runner === 'vitest' && first === VITEST_LIST_SUBCOMMAND)
+        return true;
+    return NO_RUN_FLAGS[runner].some((re) => re.test(after));
+}
+/**
+ * Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
+ * command runs no test at all.
+ *
+ * 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.
+ *
+ * A command that also runs tests is false however it is spelled: `npx playwright install &&
+ * npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
+ * reading a real run.
+ *
+ * @param command - The shell command as the executor sent it.
+ * @returns True when the command invokes a runner only to print.
+ */
+export function commandRunsNoTests(command) {
+    if (typeof command !== 'string' || !command.trim())
+        return false;
+    let invocations = 0;
+    for (const statement of command.replace(HEREDOC, ' ').split(STATEMENT_SEP)) {
+        for (const [runner, re] of INVOCATIONS) {
+            for (const m of statement.matchAll(re)) {
+                invocations += 1;
+                if (!informational(runner, statement.slice((m.index ?? 0) + m[0].length)))
+                    return false;
+            }
+        }
+    }
+    return invocations > 0;
+}

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAgU1C,CAAA"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAmU1C,CAAA"}

package/dist/schemas.js

@@ -143,13 +143,13 @@ export const TOOL_SCHEMAS = {
     },
     find_files: {
         name: 'find_files',
-        description: "Find files by name or glob pattern recursively. Excludes node_modules and .git. Use for discovering files by name (e.g. '*.tsx', 'Dashboard*', 'index.*').",
+        description: "Find files by name or glob pattern recursively. Excludes node_modules and .git. Use for discovering files by name (e.g. '*.tsx', 'Dashboard*', 'index.*'). A pattern containing '/' matches the path instead: 'e2e/*.spec.ts', 'src/**/App.tsx', '**/SELECTORS.md'.",
         parameters: {
             type: 'object',
             properties: {
                 pattern: {
                     type: 'string',
-                    description: "File name or glob pattern (e.g. '*.tsx', 'Dashboard*').",
+                    description: "File name or glob pattern (e.g. '*.tsx', 'Dashboard*'). A pattern containing '/' is matched against the file's path, so 'src/**/App.tsx' and 'e2e/*.spec.ts' work.",
                 },
                 path: {
                     type: 'string',
@@ -247,7 +247,9 @@ export const TOOL_SCHEMAS = {
             'code. Blocks until it finishes or the time budget runs out, then returns — one call, ' +
             'no polling. Use it the moment you need that result to continue; never `sleep` and ' +
             'read the log by hand. If it is still running when the budget ends, the result says so ' +
-            'and you can call it again.',
+            'and you can call it again. A suite whose failures keep repeating one cause comes back ' +
+            'EARLY with that cause named, the tests it hit and the command that stops the run — act ' +
+            'on it instead of waiting for the rest.',
         parameters: {
             type: 'object',
             properties: {

package/dist/system-prompt.js

@@ -15,7 +15,7 @@ const TOOL_DESCRIPTIONS = {
     write_file: 'Create or overwrite files (full content)',
     edit_file: 'Make targeted search-and-replace edits (preferred for small changes)',
     search_files: 'Search for text patterns across files (grep)',
-    find_files: 'Find files by name/glob pattern recursively',
+    find_files: 'Find files by name/glob pattern recursively (a pattern with "/" matches the path)',
     create_directory: 'Create directories (with parents)',
     rename_file: 'Rename or move files and directories',
     delete_file: 'Remove files',

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;AA0H9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA6CnE;;;;;;;;;;;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,CAutDxF"}
+{"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;AAqDnE;;;;;;;;;;;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,CA0zDxF"}