@molecule/api-ai-tools 1.16.3 → 1.16.4

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-11-04T11:19:09.206Z
+Generated: 2026-11-04T14:19:49.511Z
 -->
 
 # @molecule/api-ai-tools
@@ -1266,165 +1266,76 @@ Allows consumers to customize security, callbacks, and tool selection.
 
 ```typescript
 interface ToolBuildConfig {
-  /** Which tools to include. Defaults to all. */
+  /** Which tools to include. */
   include?: string[]
 
-  /** Which tools to exclude. Applied after include. */
+  /** Which tools to exclude. */
   exclude?: string[]
 
-  /** Whether to validate paths stay within projectRoot. Default: true. */
+  /** Whether to validate paths stay within projectRoot. */
   pathGuards?: boolean
 
-  /** Whether to check symlinks resolve within projectRoot. Default: false (sandbox-only). */
+  /** Whether to check symlinks resolve within projectRoot. */
   symlinkGuards?: boolean
 
-  /** Whether to redact secrets in file reads and command output. Default: true. */
+  /** Whether to redact secrets in file reads and command output. */
   redactSecrets?: boolean
 
-  /** Whether to block dangerous shell commands (env dumps, /proc access). Default: false. */
+  /** Whether to block dangerous shell commands (env dumps, /proc access). */
   blockDangerousCommands?: boolean
 
-  /**
-   * Consumer-specific command guard for `exec_command`, checked BEFORE execution (after
-   * the built-in dangerous-command check). Return an error string to block the command —
-   * it is returned to the model verbatim, so make it actionable (say what to do instead) —
-   * or `null`/`undefined` to allow it. Keeps environment-specific rules (e.g. an IDE
-   * sandbox forbidding installs that would break its preinstalled library) out of this
-   * shared package.
-   *
-   * @param command - The shell command the model asked to run.
-   * @param cwd - The resolved working directory it would run in.
-   * @returns An error string to block, or null/undefined to allow.
-   */
+  /** Consumer-specific command guard for `exec_command`, checked BEFORE execution (after the built-in dangerous-command check). */
   blockCommand?: (command: string, cwd: string) => string | null | undefined
 
-  /**
-   * Timeout (ms) for a single `exec_command` run. `exec_command` legitimately
-   * runs LONG — `npm install`, a production build, a test suite — so the default
-   * is generous (2 min); the old 30 s hardcap killed those spuriously. A consumer
-   * that wraps tool calls in its own outer timeout should set this to match (or
-   * slightly exceed) that budget so its own timeout is the effective bound and
-   * produces the nicer "tool timed out" message. Quick commands are unaffected —
-   * this is only the ceiling before a wedged command is killed.
-   */
+  /** Timeout (ms) for a single `exec_command` run. */
   execTimeoutMs?: number
 
-  /**
-   * Budget (ms) for a single `exec_command`, passed to `backend.run` as
-   * `budgetMs`: the backend runs the command under `timeout` in its own shell,
-   * so when it overruns it is stopped there and the tool still returns
-   * everything it printed until then (exit code 124 plus an `error` naming
-   * the limit). Without this, an outer per-tool timeout races the run and
-   * discards minutes of build or test output along with the result. Set it a
-   * little under that outer timeout. Unset = no budget.
-   */
+  /** Budget (ms) for a single `exec_command`, passed to `backend.run` as `budgetMs`: the backend runs the command under `timeout` in its own shell, so when it overr… */
   commandBudgetMs?: number
 
-  /**
-   * Maximum time (ms) one `wait_for_task` call may wait, independently of the foreground
-   * {@link commandBudgetMs}. The caller's requested `timeout` is honoured up to this budget.
-   * Leave unset to keep the legacy ceiling: `commandBudgetMs` (or 290 s) less a 10 s result
-   * margin. A host that raises this must also give the tool call a longer outer watchdog.
-   */
+  /** Maximum time (ms) one `wait_for_task` call may wait, independently of the foreground {@link commandBudgetMs}. */
   waitBudgetMs?: number
 
-  /**
-   * Opt in to one partial diagnostic return for a task driving this known deployed URL.
-   * Return null when the task already returned a wait result or its history is unknown.
-   * Only a real suite command with a complete inline failure report can yield; it remains
-   * running, with no exit code or completed proof. Absent leaves ordinary waits unchanged.
-   */
+  /** Opt in to one partial diagnostic return for a task driving this known deployed URL. */
   yieldOnFirstFailureFor?: (taskId: string) => string | null
 
-  /**
-   * How long (ms) exec_command waits for a command it backgrounded only because the
-   * command asked for more than {@link commandBudgetMs}, before handing back a task
-   * id; one that finishes inside it returns like a foreground run. Default 45000.
-   */
+  /** How long (ms) exec_command waits for a command it backgrounded only because the command asked for more than {@link commandBudgetMs}, before handing back a task… */
   overCeilingGraceMs?: number
 
-  /**
-   * Directory names `search_files` and `find_files` skip (VS Code
-   * `search.exclude` semantics). Defaults to `DEFAULT_SEARCH_EXCLUDED_DIRS`
-   * (node_modules, VCS dirs, build output). Pass the consumer's per-project
-   * setting so every search surface shares ONE synchronized set.
-   */
+  /** Directory names `search_files` and `find_files` skip (VS Code `search.exclude` semantics). */
   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.
-   */
+  /** 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… */
   outlineLargeHtml?: () => boolean
 
-  /**
-   * The test titles the person's request EXCLUDES by name (molecule-dev's `excludedTestTitles`),
-   * asked when a finished suite run's cause note is built. Their failures are not causes to fix:
-   * the note drops them, says so at the end, and inverts them out of the narrowed re-run it hands
-   * over — a result must never name a test beside "it does not count" (an executor once spent a
-   * turn and an edit on the excluded test).
-   *
-   * A getter, not an array, because the request is read per turn while the tool set is built
-   * once. Unset means no test is excluded.
-   *
-   * @returns The quoted titles the request carves out.
-   */
+  /** The test titles the person's request EXCLUDES by name (molecule-dev's `excludedTestTitles`), asked when a finished suite run's cause note is built. */
   excludedTestTitles?: () => readonly string[]
 
-  /**
-   * The `NAME=value` settings the person's request REQUIRES of a suite run (molecule-dev's
-   * `requiredRunSettings` — its mode, say), asked when the cause note composes a narrowed re-run
-   * of a finished run's failures. A re-run composed from the executor's own command inherits what
-   * that command set — and nothing it left out, so a run that measured the suite in `spa` handed
-   * back a re-run that would measure `spa` again (the request names `TEST_MODE=fullstack`, and
-   * both the run and its re-run omitted it).
-   *
-   * A getter, not an array: the request is read per turn while the tool set is built once, and
-   * what the suite's own files read is the consumer's reading. Unset answers "nothing required".
-   *
-   * @param command - The command the finished run was started with.
-   * @param cwd - The resolved working directory it ran in.
-   * @returns The settings to put on a re-run of that command.
-   */
+  /** The `NAME=value` settings the person's request REQUIRES of a suite run (molecule-dev's `requiredRunSettings` — its mode, say), asked when the cause note compos… */
   requiredSuiteEnv?: (
     command: string,
     cwd: string,
   ) => Promise<readonly { name: string; value: string }[] | null | undefined>
 
-  /**
-   * The supplied suite's own budget, when the Playwright config a command would load sets
-   * different settings, asked BEFORE the run executes. The consumer knows where the suite and its
-   * base config live; this shared package does not, so the reading is the consumer's and the
-   * mechanics — putting the flags on the runner's own arguments, before the pipeline and outside
-   * any redirect or group closer, and pointing `--config` at the derived config that carries the
-   * settings no flag can — are this tool's.
-   *
-   * Called for a Playwright suite command only, and only the LAST suite step is touched. A run
-   * that already keeps the suite's settings, or a sandbox with no supplied suite, answers `null`.
-   * Unset (or a hook that throws) changes nothing: the command runs as the model wrote it.
-   *
-   * @param command - The shell command, as the model sent it.
-   * @param cwd - The resolved working directory it will run in.
-   * @returns The flags, the derived config and the sentence, or null when nothing is put back.
-   */
+  /** The supplied suite's own budget, when the Playwright config a command would load sets different settings, asked BEFORE the run executes. */
   suiteBudget?: (command: string, cwd: string) => Promise<SuiteBudgetPin | null | undefined>
 
-  /**
-   * A whole walk's duration in ms, as the consumer measured it. A suite run the executor detached
-// … truncated — the full declaration is in node_modules/@molecule/api-ai-tools/dist/types.d.ts
+  /** A whole walk's duration in ms, as the consumer measured it. */
+  suiteRunMs?: (command: string, cwd: string) => Promise<number | null | undefined>
+
+  /** Post-write hook (e.g. auto-format via Prettier/ESLint). */
+  onAfterWrite?: (path: string) => Promise<void>
+
+  /** Diff tracking callback. */
+  onFileDiff?: (event: FileDiffEvent) => void
+
+  /** Structural change callback. */
+  onFileChange?: (event: FileChangeEvent) => void
+}
 ```
 
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/api-ai-tools/dist/types.d.ts`.)_
+
 #### `FileDiffEvent`
 
 Payload emitted when a tracked file changes contents.
@@ -2936,8 +2847,24 @@ deployed URL, where a network blip is likeliest and the retries it dropped are t
 absorb it).
 
 `--max-failures=0` is Playwright's own "no cap" ({@link boundsFailures}), so it is not a
-
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/suite-overlap.d.ts`.)_
+diagnosis. A command that starts no Playwright run is not one either (false): the question is
+about a run already read as a Playwright suite.
+
+A `--grep-invert` is only a narrowing when it excludes MORE than the request already excludes.
+When the caller passes those approved titles ({@link DiagnosisRunContext}) and the inverted
+pattern names one of them — the request's own "except …" scope written as the flag, which
+molecule-dev's `invertDecision` reads the same way — the run still walks the whole proof scope,
+and it is not a diagnosis. The deployed proof carried exactly
+that exclusion, the rewriter added `--retries=0` to it, and the run lost the suite's retries on
+the one walk where a network blip is likeliest.
+
+A command the PLATFORM composed and launched AS the graded proof keeps the suite's retries for
+the SELECTION it composed — the failures a redeploy re-runs, named as files and `file:line`
+({@link DiagnosisRunContext} `platformProof`). Only that selection is excused: a cap, a title
+filter, a last-failed set and a local targeted selection stay diagnoses, so the mark cannot turn a walk of
+part of the suite into the graded measurement. Which targets are local is
+{@link suiteCommandTarget}'s answer, and the launch rewrite asks it on the same reading
+({@link ./utilities.js} `streamingBackgroundCommand`).
 
 ```typescript
 function isDiagnosisRun(command: string, context?: DiagnosisRunContext): boolean
@@ -3128,7 +3055,11 @@ A path INSIDE the link is still decided by what resolves there: a link into a
 real tree is refused, because removing or writing through it reaches the
 install.
 
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/tools.d.ts`.)_
+The restore route is named because the model that has ALREADY clobbered a file
+(this refusal is too late for it) is the one who needs it, and because the
+obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
+sandbox. `npm pack` + a `tar` extraction over the package directory is the
+repair both guards leave alone.
 
 ```typescript
 function installedPackageWriteRefusal(
@@ -3176,8 +3107,15 @@ or still in flight when the test ended; it is kept too, but as what it is, not a
 A trace.zip holds ONE trace member per browser context the test used (beside the runner's own
 `test.trace`), and the archive's member order is not the test's chronology. Each member is read
 as its own context: actions and requests keep their context id, requests and frame snapshots
+keep the pageId Playwright records, and the failing assertion's page — the page its own step id
+ran on — decides which actions, snapshots and requests become the test's row. What the test's
+other browser contexts recorded is reported apart, as `otherContexts`.
 
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
+A request answered 4xx by the app's OWN API also keeps what the page SENT and the first of what
+came back: Playwright stores either inline (`text`) or in a resource entry (`_file`), and both
+are read. That is where a wrapped body shows: a helper passed
+`{ data: body }` as app-http's second argument, so every POST/PUT was `{"data":{…}}` and the API
+validated `{}`. Status alone said only "422".
 
 ```typescript
 function traceArtifactsScript(): string
@@ -3362,6 +3300,38 @@ is `data`, the note names the call shape that produces it.
 Every row opens with the test's LAST user action before the failing assertion and the requests
 that action caused ({@link TraceArtifact.lastAction}) — started after it, before the assertion,
 the app's own API calls first, each with its status and the first 200 characters of its response,
+then where the page went next. The trace's action clock and each request's `_monotonicTime` are
+the same clock, so "caused" is the trace's own fact rather than a guess from recording order.
+A run failed 13 then 12 tests on one unnamed cause while every row led with
+`GET /api/tags → 200` — the Home page's own fetch after the redirect — and filled its answered
+slots with the PWA's `/workbox-*.js` and its `/icons/*.svg`; the register `POST /api/users`
+(answered 201, the page still rendering signed-out) never appeared. With no action clock, the
+row falls back to {@link TraceArtifact.lead}: the page's last answered fetch/xhr.
+
+The action, the URL and the requests are the FAILING ASSERTION'S PAGE's ({@link
+TraceArtifact.lastAction}), never the archive's last context: a test that creates its data in a
+second browser context writes that context's click and `/editor` snapshot into the same zip, and
+reading the concatenation made them the failing page. The other
+contexts' requests are named separately as set-up work. When the trace holds more than one used
+context and the assertion's page cannot be identified, the note lists the requests and makes NO
+causal claim — no "the test's last action", no "the page stayed at …" — instead of merging them.
+
+A field the test filled and the page submitted EMPTY ({@link formResetOf}) leads the note: the
+trace holds both facts — the value typed into `textarea[name="bio"]` and the `PUT /api/user`
+whose body carried `"bio": ""` — so the form's state was reset between the typing and the
+submit. The note names the effect that re-seeds a form from data whose identity changed and the
+fix at the source (seed the form once). A deploy-and-walk cycle is lost to this on the
+deployed URL only, where the background session verification lands later than it does locally.
+
+A write whose response said a boolean field is true and a LATER GET of the same resource that
+said it is false leads the note first ({@link readContradictionSentence}): the read route never
+saw the viewer, so the fix is on that route's middleware, not in the page. Rewriting the
+profile component over exactly that pair costs ~8 minutes — the write answered
+`{"following":true}` and the next profile GET answered `false`.
+
+WHICH rows it spends is evidence, not artifact order: a row
+needs a recorded response, a real failure or a console line ({@link traceRowEvidence}), rows are
+deduplicated by the test's location, and they are ordered real failure → repeated from an
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
 
@@ -3437,8 +3407,22 @@ between passing and timing out. This flag was added for exactly that failure: it
 deployed proof run left only an `error-context.md` because the suite traces
 `on-first-retry` and the run had no retries. That need is met without the flag — the graded
 deployed run keeps the suite's own retries, so a failing test leaves its retry's trace — and
+the platform's re-run note carries `--trace=on` for a run that did leave none.
 
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
+Which runs are proof-capable is {@link suiteCommandTarget}'s answer: a run against a deployed
+URL. A LOCAL run is never left to its config, because the launcher gives every local run
+`--retries=0` (`@molecule/api-ai-tools` `streamingBackgroundCommand`), so its retry trace would
+never happen. A run that pins `--retries=0` itself is in the same position, whatever its target.
+
+A proof-capable run is left alone WHATEVER its config traces. `--trace` is a per-run override of
+the suite's own `use.trace` (Playwright merges the CLI's `use` into every project's), and a test
+record carries the project settings it ran under: a run with the flag is not the suite's own
+measurement, so it can never count as deployed proof. Added to a deployed walk, the flag made the
+walk unprovable, and the platform's own answer — "run the current selection" — was a command this
+same rewrite then flagged again: X1 P140–P173 had 22 deployed walks the executor started, and
+not one moved the native proof counts (xr-molecule-flash-l1255 walked 73/73 green twice, at
++18.2 and +22.9, and neither counted). A failure in a suite that keeps no trace at all is still
+readable: the platform's re-run note carries `--trace=on` for a run that left none.
 
 ```typescript
 function diagnosisTraceCommand(args: {
@@ -3684,8 +3668,38 @@ killed (one run lost 20 of its 60 minutes this way):
   machine `json` report stays on the last invocation.
 
 The run ends up with exactly ONE reporter that prints each failure — `list`. A run that names
-
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+any other printing reporter has it REPLACED, never joined: two of them write every test result
+into the log twice, which 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 an 8.3-minute walk of one suite could never trip
+the fail-fast note. A reporter set that writes a machine format to a file (`json`, `html`,
+`junit`) is the
+executor's own and is left exactly as it is — so is any reporter this build does not know.
+
+Every background command that is not a no-test invocation is also given
+{@link PLAYWRIGHT_FAILURES_INLINE_ENV} (inert except for Playwright's `list` reporter), so each
+failure's own error is in the log as that test fails rather than only at the end: a suite that is
+still walking is exactly when the executor reads the log, and without it a running log carries
+`✘` rows and nothing else (~90 s went to greps of one, then to fixing what was
+guessed; a wrapper-launched run lost 6.5 minutes to the same shape).
+
+Only the step that runs the suite is touched, and only its reporter, and only when that step
+runs something: `npx playwright test --list` takes two seconds and writes nothing per test, so
+neither reporter nor `--retries=0` is added to it ({@link isPlaywrightRunCommand}). A trailing
+status step (`; echo EXIT $?`, `&& true`) is not the run and is skipped when the run step is
+found ({@link isStatusOnlyStep}); a run whose output is redirected to a file is still readable
+through that file, which the launch records as the task's own output.
+
+A command that starts the suite MORE THAN ONCE is not launched at all: every run it carries is
+a whole walk of the same suite against the same app, and only the last step is rewritten, so the
+earlier walks run unmeasured for nothing. Two whole walks of one 138-test suite chained with
+`;` — 4.5 minutes each — measured nothing the first had not. The platform refuses a second CONCURRENT run against one app and database by the
+ONE rule ({@link suiteRunInTheWay}) — for every pair, whatever uid a run mints — and this is the
+same hazard inside one command ({@link suiteRunStatements}). `error` then carries the refusal,
+naming each suite step and the ONE command to send instead (the last suite step, rewritten as
+this function rewrites a run), and nothing is launched.
 
 ```typescript
 function streamingBackgroundCommand(
@@ -4167,8 +4181,13 @@ is a directory rather than a directory name.
 
 An npm SCOPE as the first segment, under a `node_modules` root, is the one
 exception that parameter `root` enables: npm installs a scope only directly
-
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+inside a `node_modules` directory, and the walk already prunes every nested
+`node_modules` (see `findPruneArgs`), so the whole-tree form can only ever
+match `<root>/@molecule/…` — the scope directory IS the directory the pattern
+names. Left un-narrowed, a scoped-package pattern walked the sandbox's entire
+dependency tree and hit the 10 s deadline with no result at all. A bare NAME stays a
+directory name at any depth:
+`helpers/*` is unchanged even under a `node_modules` root.
 
 ```typescript
 function literalDirPrefix(pattern: string, root?: string): string | null
@@ -4507,8 +4526,7 @@ each was the test timeout and one missing `navigate('/')` was the cause of all o
 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) has told a run that four of its
 tests failed the same way when two had, so the executor stopped a 139-test walk at test 21
-
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+with one cause in hand.
 
 ```typescript
 function repeatingFailure(log: string): RepeatingFailure | null
@@ -4641,7 +4659,11 @@ Both halves are load-bearing, each of them learned from a run that lost minutes
   — read the early return as "stop waiting, edit now", and voided a run that was still walking;
   the second cost a 224 s wait that ended with no result at all.
 
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+Neither half alone is enough, and {@link repeatingFailure} finding a signature is not either:
+that answers "is a cause repeating among this run's failures", which is worth telling the
+executor mid-run as a NOTE while the wait goes on. This answers the narrower question the wait
+needs — is the run over as a measuring instrument — and it is THE one predicate behind both
+that decision and the note's wording, so the two cannot come to different verdicts.
 
 ```typescript
 function earlyReturnCause(
@@ -4854,9 +4876,12 @@ for — never as a verdict with a stop command in it.
 The run is STILL WALKING while this note is written — both callers produce it mid-run — so a
 re-run of one of its tests is a second run against the same app and database, and the platform
 refuses that ({@link suiteRunInTheWay}, the same rule its overlap hold answers with):
-an executor read *"Start on them now, while the run keeps walking.
-
-_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+an executor read _"Start on them now, while the run keeps walking.
+`null-fields.spec.ts:53` alone reproduces the first one."_ and sent exactly that re-run 23 s
+later, where the hold answered _"A playwright suite is already running against this app and
+database … Wait for it."_ The note therefore hands over the read-and-fix to do NOW and the
+re-run for after the run ends — the exact command where the caller knows how the run was
+started ({@link rerunOfRunningSuite}), the timing alone where it does not.
 
 ```typescript
 function repeatingFailureNote(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.16.3",
+  "version": "1.16.4",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",