@molecule/api-ai-tools 1.5.18 → 1.5.19

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:22:32.984Z
 -->
 
 # @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)_
@@ -689,7 +738,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 +753,52 @@ 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.
+
+```typescript
+function isSuiteRunCommand(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when the command starts one of those runners.
+
+#### `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 +866,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 +947,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 +1043,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 +1273,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 +1370,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/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;AAoDnE;;;;;;;;;;;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,CAuzDxF"}

package/dist/tools.js

@@ -32,6 +32,58 @@ const outputFileByTask = new Map();
  * would re-read the task's script on every single wait.
  */
 const outputFileProbed = new Set();
+/**
+ * How often a wait looks at a running task's log for a cause repeating among its failures.
+ * Env-tunable so a test can exercise it.
+ */
+const repeatingCauseLookMs = () => Number(process.env.MOL_AI_BG_CAUSE_LOOK_MS) || 10_000;
+/**
+ * Task ids a wait has already named a repeating cause for. The note is news once; a second wait
+ * on the same run has nothing to add to it, and re-sending it would spend the executor's turns
+ * telling it what it has already been told.
+ */
+const repeatingCauseNoted = new Set();
+/**
+ * The shell command that stops a background task by pid: the pid the platform wrote when it
+ * detached the run, plus every process under it.
+ *
+ * Both halves matter and neither is a pattern. Killing only the pid file's entry can leave the
+ * runner (`sh -c` wraps the command here) orphaned and still driving the app, and a
+ * `pkill -f <something>` is the shape that matches the shell running the kill itself — the
+ * platform holds that command once with the processes it would hit named
+ * (`molecule-dev/api/src/ai/pattern-kill-guard.ts`). `pgrep -P` walks to a real pid list, which
+ * is what the guard's own note sends the executor to.
+ *
+ * @param taskId - The task's `mol-bg-…` handle (format already checked by the caller).
+ * @returns The pids, space-separated, or '' when the pid file is gone.
+ */
+const taskPidsCommand = (taskId) => `R=$(cat /tmp/${taskId}.pid 2>/dev/null); ` +
+    'all() { echo "$1"; for c in $(pgrep -P "$1" 2>/dev/null); do all "$c"; done; }; ' +
+    'all "$R" | tr "\\n" " "';
+/**
+ * The command that stops a running background task, read from the sandbox's own pid files.
+ *
+ * @param backend - The execution backend.
+ * @param taskId - The task's `mol-bg-…` handle.
+ * @returns The command to hand the executor — `kill <pids>` — falling back to the task's own pid
+ *   file when the walk comes back empty (a sandbox without `pgrep`, or a pid file already gone,
+ *   in which case the pid-file form is still the one the platform's guard names).
+ */
+async function taskStopCommand(backend, taskId) {
+    const fallback = `kill $(cat /tmp/${taskId}.pid)`;
+    try {
+        const r = await backend.run(taskPidsCommand(taskId), { timeout: 10_000 });
+        const pids = String(r.stdout ?? '')
+            .split(/\s+/)
+            .filter((p) => /^\d+$/.test(p));
+        return pids.length ? `kill ${pids.join(' ')}` : fallback;
+    }
+    catch (_error) {
+        // The sandbox would not answer the pid walk. The pid-file form below is what the platform
+        // tells the executor to use anyway, so there is nothing to report and nothing to lose.
+        return fallback;
+    }
+}
 /** A millisecond span the way a model reads it: seconds under 90, else minutes. */
 function durationText(ms) {
     const s = Math.max(0, Math.round(ms / 1000));
@@ -109,7 +161,7 @@ function waitProgressNote(o) {
     const sentence = parts.join('; ');
     return ` ${sentence[0].toUpperCase()}${sentence.slice(1)}.`;
 }
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, fusedLine, isEnvFilePath, isOutsideRoot, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, redactSecrets, redactSecretsInCode, resolvePath, RUNNING_FAILURE_LINES, runningOutputSliceCommand, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, findPatternArgs, fusedLine, htmlOutline, isEnvFilePath, isOutsideRoot, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPriorityLaunch, truncateMiddle, 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.
@@ -145,7 +197,7 @@ export function moleculeDistReadNote(path) {
  * @returns Array of AITool objects ready to pass to an AI provider
  */
 export function buildTools(backend, config) {
-    const { include, exclude, pathGuards = true, symlinkGuards = false, redactSecrets: doRedact = true, blockDangerousCommands = false, blockCommand, execTimeoutMs = 120_000, commandBudgetMs, overCeilingGraceMs = OVER_CEILING_GRACE_MS, searchExcludedDirs, onAfterWrite, onFileDiff, onFileChange, } = config ?? {};
+    const { include, exclude, pathGuards = true, symlinkGuards = false, redactSecrets: doRedact = true, blockDangerousCommands = false, blockCommand, execTimeoutMs = 120_000, commandBudgetMs, overCeilingGraceMs = OVER_CEILING_GRACE_MS, searchExcludedDirs, outlineLargeHtml, onAfterWrite, onFileDiff, onFileChange, } = config ?? {};
     const root = backend.projectRoot;
     // A host-filesystem backend with escape guards off is the combination the
     // audit flagged: `pathGuards` off lets `..` paths out of the workspace,
@@ -499,6 +551,41 @@ export function buildTools(backend, config) {
                 return {
                     error: `File too large (${Math.round(content.length / 1024)}KB). Maximum is ${MAX_READ_SIZE / 1024 / 1024}MB.`,
                 };
+            // A LARGE HTML document comes back as its OUTLINE, not its text, when the
+            // host asks for that (a plan-mode turn: see `outlineLargeHtml`). X0
+            // flash-m77 paid 63,735 chars for one `read_file` of `app/index.html` —
+            // ~60 KB of it the IDE's own preview bridges — and that read alone took the
+            // transcript past its context cap, so the e2e specs it had just read were
+            // trimmed to summaries and it read the whole suite again, twice (+01:23,
+            // +02:56). An outline is not a truncation: the note names the exact
+            // offset/limit that returns the whole document, and any line range works.
+            if (!sliceLines(content, window) &&
+                content.length > MAX_HTML_INLINE_CHARS &&
+                outlineLargeHtml?.()) {
+                const outline = htmlOutline(content, path);
+                if (outline) {
+                    const totalLines = content.split('\n').length;
+                    return noted({
+                        path,
+                        // Same redaction every other read goes through: an outline is made of
+                        // the document's own lines, and a meta tag can carry a key.
+                        content: sanitizeFileContent(outline, path),
+                        outline: true,
+                        bytes: content.length,
+                        totalLines,
+                        note: `Outlined, not returned whole: a ${Math.round(content.length / 1024)} KB HTML document is ` +
+                            `its tags plus a lot of plumbing, and the tags are what matter. ` +
+                            `The whole file is ONE call — read_file {path, offset: 1, limit: ${totalLines}} — ` +
+                            `and any line range works the same way.` +
+                            // The IDE's own preview scripts are in this document but are not the
+                            // app's behaviour, and an executor that reads them pays 60 KB for
+                            // something it must never edit (flash-m77). Named only when present.
+                            (/<!--\s*mol:[a-z0-9-]+-(?:bridge|shim)/.test(content)
+                                ? ' The `mol:*-bridge` scripts the IDE injects belong to the platform, not to the app: leave them as they are.'
+                                : ''),
+                    });
+                }
+            }
             // No window asked for and the file is bigger than one call should hand
             // back: return its first window, sized to the ceiling, and say so. The
             // model can read on with offset/limit; it cannot un-send 300k tokens.
@@ -1162,9 +1249,18 @@ export function buildTools(backend, config) {
             if (symlinkErr)
                 return { error: symlinkErr };
             try {
-                const result = await backend.run(`find ${shellQuote(path)} ${findPruneArgs(path)} -name ${shellQuote(pattern)} -print 2>/dev/null | head -${MAX_FIND_RESULTS}`, { timeout: 10000 });
+                // `findPatternArgs`, not `-name`: a pattern with a `/` in it
+                // (`helpers/*`, `e2e/*.spec.ts`) matched nothing at all, because `-name`
+                // compares it against the basename (xr-molecule-flash-m77).
+                const result = await backend.run(`find ${shellQuote(path)} ${findPruneArgs(path)} ${findPatternArgs(pattern)} -print 2>/dev/null | head -${MAX_FIND_RESULTS}`, { timeout: 10000 });
                 const files = result.stdout.trim().split('\n').filter(Boolean);
-                return { pattern, path, files };
+                // A slash changes what the pattern means — the whole path, not the file
+                // name — and an empty result does not say so, so the model reads it as
+                // "no such file" and goes looking elsewhere. Name the rule on the miss.
+                const note = files.length === 0 && pattern.includes('/')
+                    ? `"${pattern}" contains a "/", so it was matched against each file's PATH below ${path} (a leading "*/" is implicit), not against the file name — no path matched it. list_files shows the real entries.`
+                    : undefined;
+                return { pattern, path, files, ...(note ? { note } : {}) };
             }
             catch (e) {
                 return { error: `Find failed: ${e.message}` };
@@ -1294,6 +1390,11 @@ export function buildTools(backend, config) {
                     // Keep the log growing while it runs (see streamingBackgroundCommand):
                     // an empty log is what wait_for_task reads as stuck.
                     const streaming = streamingBackgroundCommand(command);
+                    // A whole-suite run starves the sandbox it shares with the app and with
+                    // every command the executor sends next, so it starts at lower CPU and
+                    // IO priority (see suiteRunPriorityLaunch). Foreground runs are never
+                    // touched, and a sandbox without the tools runs it unchanged.
+                    const prioritized = suiteRunPriorityLaunch(streaming.command, `sh ${script} > ${log} 2>&1; echo $? > ${exitFile}`);
                     const ownTarget = outputRedirectTarget(streaming.command);
                     const ownFile = ownTarget
                         ? ownTarget.startsWith('/')
@@ -1303,7 +1404,7 @@ export function buildTools(backend, config) {
                     if (ownFile)
                         outputFileByTask.set(id, ownFile);
                     await backend.writeFile(script, `${streaming.command}\n`);
-                    await backend.run(`nohup sh -c ${shellQuote(`sh ${script} > ${log} 2>&1; echo $? > ${exitFile}`)} ` +
+                    await backend.run(`nohup sh -c ${shellQuote(prioritized.launch)} ` +
                         `> /dev/null 2>&1 & echo $! > /tmp/${id}.pid`, { cwd, timeout: 15_000 });
                     // A command backgrounded only for the budget it ASKED for often ends in
                     // seconds (a Hurl suite: 37 ms). Handing it back as a task cost a
@@ -1360,6 +1461,7 @@ export function buildTools(backend, config) {
                             `check back. If you need this result before you can continue, call wait_for_task ` +
                             `with this taskId — never sleep and read the log by hand.` +
                             (streaming.changes.length ? ` ${streaming.changes.join(' ')}` : '') +
+                            (prioritized.note ? ` ${prioritized.note}` : '') +
                             (ownFile
                                 ? ` This command writes its own output to ${ownFile}, so the task log stays empty: peek with exec_command: tail ${ownFile}.`
                                 : ''),
@@ -1588,10 +1690,53 @@ export function buildTools(backend, config) {
                     return null;
                 }
             };
+            // A running SUITE whose failures repeat one cause is named at the third of them. The run
+            // would otherwise spend its whole clock proving that cause, and the executor only learns it
+            // from the finished log: X1 flash-m76 waited out 4.0 minutes of 15 tests where every
+            // failure was the same `TimeoutError: page.waitForURL` from one missing `navigate('/')`,
+            // and then fixed it in 51 s. The task is NOT stopped — the executor is handed the cause and
+            // its own pid command and decides.
+            let lastCauseLookAt = startedAt - repeatingCauseLookMs();
             let exitCode = await readExit();
             while (exitCode === null && Date.now() - startedAt < budgetMs) {
                 await new Promise((r) => setTimeout(r, Math.min(2_000, budgetMs - (Date.now() - startedAt))));
                 exitCode = await readExit();
+                // The exit file is read first, so a run that finishes between two looks still returns
+                // its real result instead of a note about it.
+                if (exitCode !== null)
+                    break;
+                if (repeatingCauseNoted.has(taskId))
+                    continue;
+                if (Date.now() - lastCauseLookAt < repeatingCauseLookMs())
+                    continue;
+                lastCauseLookAt = Date.now();
+                let causeLog;
+                try {
+                    const r = await backend.run(runningCauseCommand(log, outputFileByTask.get(taskId)), {
+                        timeout: 10_000,
+                    });
+                    causeLog = r.stdout ?? '';
+                }
+                catch (_error) {
+                    // No look at the log this tick; the next one asks again.
+                    continue;
+                }
+                const found = repeatingFailure(causeLog);
+                if (!found)
+                    continue;
+                repeatingCauseNoted.add(taskId);
+                const earlyMs = Date.now() - startedAt;
+                waitedByTask.set(taskId, waitedBefore + earlyMs);
+                return {
+                    taskId,
+                    status: 'repeating_failure',
+                    waitedMs: earlyMs,
+                    note: repeatingFailureNote(found, {
+                        taskId,
+                        log,
+                        stop: await taskStopCommand(backend, taskId),
+                    }),
+                };
             }
             const waitedMs = Date.now() - startedAt;
             waitedByTask.set(taskId, waitedBefore + waitedMs);

package/dist/types.d.ts

@@ -112,6 +112,22 @@ export interface ToolBuildConfig {
      * setting so every search surface shares ONE synchronized set.
      */
     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>;
     /** Diff tracking callback. Called before writes with old/new content. */

package/dist/types.d.ts.map

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