@molecule/api-ai-tools 1.8.1 → 1.8.3

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-17T02:50:55.123Z
+Generated: 2026-10-17T05:02:46.912Z
 -->
 
 # @molecule/api-ai-tools
@@ -115,6 +115,24 @@ interface LocatedCommandSegment {
    * inside a nested `sh -c` string, for the same reason as {@link start}.
    */
   assignmentOffset: number | null
+  /**
+   * The offset in the command one past the statement's last word — where an option of this
+   * statement's program belongs, before whatever closes it. Null inside a nested `sh -c` string.
+   */
+  end: number | null
+  /**
+   * The offset in the command of the word in command position — the program, once every wrapper
+   * in front of it is taken away (`npx --prefix /app <here>playwright test`). Null inside a
+   * nested `sh -c` string, and for a statement that only sets variables.
+   */
+  programOffset: number | null
+  /**
+   * The separator the shell split at immediately before this statement — `|`, `||`, `&&`, `;`,
+   * a newline or `&` — or '' when it is the first statement of the command. It is the parse's own
+   * answer, so it is known even where the offsets are not, and a caller deciding whether two
+   * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
+   */
+  separator: string
 }
 ```
 
@@ -235,6 +253,19 @@ interface ToolSchema {
 }
 ```
 
+#### `LeadingSleep`
+
+The leading `sleep` a command opens with, and the command that follows it.
+
+```typescript
+interface LeadingSleep {
+  /** How many seconds the statement would have slept (GNU sleep sums its operands). */
+  seconds: number
+  /** What follows the leading statement, trimmed — '' when the sleep was the whole command. */
+  rest: string
+}
+```
+
 #### `SuiteRunInFlight`
 
 One suite run, as the rule that decides whether a second may start beside it reads it.
@@ -258,6 +289,20 @@ interface SuiteRunInFlight {
 }
 ```
 
+#### `InstalledPackageFacts`
+
+What the filesystem says about a write target under `node_modules` — the half
+of the decision a path's spelling cannot make.
+
+```typescript
+interface InstalledPackageFacts {
+  /** Whether the `node_modules` entry the path goes through is a symbolic link. */
+  readonly symlink: boolean
+  /** Whether a package is really installed there: a `package.json` resolves under the entry. */
+  readonly installed: boolean
+}
+```
+
 #### `TraceRequest`
 
 One request a traced page made, as `*.network` records it.
@@ -553,6 +598,27 @@ interface SuiteFilterStrip {
 }
 ```
 
+#### `SuiteRunPipelinePlacement`
+
+Whether a finished run's exit code belongs to a stage after the suite runner.
+
+```typescript
+interface SuiteRunPipelinePlacement {
+  /**
+   * True when a pipe this tool must not drop still follows the suite runner: the code in the
+   * result is that stage's, not the run's.
+   */
+  piped: boolean
+  /**
+   * True when the suite (or a stage of its pipeline) sits inside a nested `sh -c '<command>'`
+   * string, so the parse cannot place it in the command's own text. The caller then says so
+   * plainly instead of implying a stage it can point at — and keeps the command's own code when
+   * no pipe follows the runner, because on that command the pipeline's last stage IS the run.
+   */
+  unplaced: boolean
+}
+```
+
 #### `FailedTest`
 
 One failed test, as a running suite's log names it.
@@ -658,6 +724,19 @@ Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
 type DiscoveredSkill = SkillEntry
 ```
 
+#### `InstalledPackageProbe`
+
+Looks at the filesystem for {@link InstalledPackageFacts}.
+
+The guard cannot `stat` the path itself: the tools act through a backend (a
+sandbox over the network for the fleet), so the caller — which holds that
+backend — supplies the look. {@link shellInstalledPackageProbe} builds one
+from any shell runner.
+
+```typescript
+type InstalledPackageProbe = (path: string) => Promise<InstalledPackageFacts>
+```
+
 ### Classes
 
 #### `ToolInputError`
@@ -1029,6 +1108,26 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `leadingSleepPeek(command)`
+
+The leading `sleep` of a command, when the first statement is one and it asks for at least
+{@link MIN_PEEK_SLEEP_SECONDS}.
+
+The statement is read by {@link locatedCommandSegments} — the same parse every other command
+classifier uses — so only a `sleep` in command position of the FIRST statement counts. The end
+of that statement is then found by walking forward from its own start: the statement is
+`sleep <duration>`, whose words carry no quotes and open no substitution, so the first unquoted
+`;`, newline or `&` ends it. A `|` is refused: dropping the left side of a pipeline would hand
+the right side its stdin instead, and a `||` fallback would run on a success that never did.
+
+```typescript
+function leadingSleepPeek(command: string): LeadingSleep | null
+```
+
+- `command` — The shell command the executor sent.
+
+**Returns:** The seconds and the remaining command, or null when the command does not open with a long `sleep`.
+
 #### `withoutHeredocs(command)`
 
 A command with its heredoc bodies removed: the runs, kills and hosts it names in a file it
@@ -1213,10 +1312,26 @@ function moleculeDistReadNote(path: string): string | null
 
 **Returns:** The note, or null when the path is not inside a package's `dist`.
 
-#### `installedPackageWriteRefusal(path)`
+#### `shellInstalledPackageProbe(run)`
 
-The refusal for a write whose target is inside an installed package, or null
-when the path is not under a `node_modules` directory.
+Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+`run`, or a sandbox's `exec`): one command reports whether the entry is a
+link and whether a `package.json` resolves under it.
+
+```typescript
+function shellInstalledPackageProbe(
+  run: (command: string) => Promise<{ stdout?: string } | null | undefined>,
+): InstalledPackageProbe
+```
+
+- `run` — Runs a command where the path lives.
+
+**Returns:** The probe.
+
+#### `installedPackageWriteRefusal(path, probe)`
+
+The refusal for a write whose target is inside an INSTALLED package, or null
+when the path is not under `node_modules` or nothing is installed there.
 
 `node_modules` is not the project's code: nothing written there survives the
 next install, no deploy carries it, and a sandbox whose dependency tree is
@@ -1229,17 +1344,29 @@ answered `ok: true`, and 18 s went to noticing, `npm pack`-ing the package and
 putting the file back. Reading these files stays allowed (that is how the
 declarations above are read at all).
 
-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 what
-m91 used, and what both guards leave alone.
+What is protected is the INSTALL, not the spelling: the decision comes from
+{@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+things are the run's own to remove or replace —
+
+- a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+  tree it points at, so a link the run made cannot clobber anything;
+- anything under the run's own `.mol-scratch/` directory;
+- a `node_modules` with no `package.json` under it (nothing was ever installed).
+
+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
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/tools.d.ts`.)_
 
 ```typescript
-function installedPackageWriteRefusal(path: string): string | null
+function installedPackageWriteRefusal(
+  path: string,
+  probe?: InstalledPackageProbe,
+): Promise<string | null>
 ```
 
 - `path` — An absolute path a tool is about to write.
+- `probe` — Looks at the filesystem where the path lives.
 
 **Returns:** The one-line refusal naming the package, or null when nothing is installed there.
 
@@ -1602,23 +1729,40 @@ function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 
 **Returns:** The rewritten command and the stages dropped.
 
+#### `suiteRunPipelinePlacement(command)`
+
+Where the suite runner's exit code comes from: the runner itself, or a stage piped after it.
+
+{@link suiteRunPipedAfterRunner}'s one question, with the honest third answer kept apart. The
+code a finished run reports is its LAST pipeline stage's, so a stage after the runner makes the
+code the stage's — but only when such a stage EXISTS. The platform used to report "piped" for
+any run whose statements it could not place in the text, which one heredoc body was enough to
+cause: on X1 xr-molecule-flash-m105 (+08:12) a config written in the same `exec_command` made
+the run come back with no exit code at all, and the note under it claimed a stage after the
+runner that was not there. The parse now places every statement (`locatedCommandSegments`), so
+"unplaced" is the rare, named case rather than a guess dressed as an answer.
+
+```typescript
+function suiteRunPipelinePlacement(command: string): SuiteRunPipelinePlacement
+```
+
+- `command` — The shell command, after the streaming rewrite when one was applied.
+
+**Returns:** Whether a stage follows the runner, and whether the run could be placed at all.
+
 #### `suiteRunPipedAfterRunner(command)`
 
 Whether the command's last step runs a suite whose output still passes through a stage after
 the runner — one {@link stripTrailingSuiteFilters} could not prove is output-only (`| tee log`,
 `| xargs …`). The pipeline's exit status is that stage's, not the run's.
 
-A command whose stages cannot be placed in the text (irregular whitespace inside the run) is
-reported as piped too: whether a pipe follows the runner is then UNKNOWN, and an unknown exit
-code that gets trusted is a failing run read as a pass — the failure this rule exists to stop.
-
 ```typescript
 function suiteRunPipedAfterRunner(command: string): boolean
 ```
 
 - `command` — The shell command, after the streaming rewrite when one was applied.
 
-**Returns:** True when a pipe this tool must not drop still follows the suite runner, or when the command runs a suite the parse cannot place.
+**Returns:** True when a pipe this tool must not drop still follows the suite runner.
 
 #### `suiteRunPriorityLaunch(command, launch)`
 
@@ -2231,9 +2375,12 @@ executor reads, so one round of fixes covers all of them rather than the one cau
 stopped early happened to reach.
 
 A test the request excludes is not one of the causes — it is dropped and named once, at the
-end, so a result never asks to fix a test it also says to ignore. Where the caller knows how
-the run was started, the note also hands over the narrowed re-run of exactly those tests
-({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the whole suite.
+end, so a result never asks to fix a test it also says to ignore. A test the runner itself
+declared `flaky` (it failed once and passed on its config retry) is not a cause either: it is
+named apart from them, once, as what the tally called it ({@link flakyTestsDeclared}). Where
+the caller knows how the run was started, the note also hands over the narrowed re-run of
+exactly those tests ({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the
+whole suite.
 
 ```typescript
 function failureCausesNote(
@@ -2414,6 +2561,15 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `MIN_PEEK_SLEEP_SECONDS`
+
+The shortest leading sleep the platform drops: below it the wall clock it costs is noise, and a
+short settle (`sleep 2; curl …`) is a legitimate thing to run.
+
+```typescript
+const MIN_PEEK_SLEEP_SECONDS: 5
+```
+
 #### `SPLIT_WORK_ADVICE`
 
 The closing advice on an over-budget message for a command that is not a test

package/dist/command-position.d.ts

@@ -21,8 +21,14 @@
  * Not command position, and therefore not an invocation: a runner named as an argument
  * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
  * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
- * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
- * stripper first (`withoutHeredocs`, in `./suite-overlap.js`).
+ * WRITES is not a command it runs, so the bodies are blanked to spaces before anything is split
+ * ({@link blankHeredocBodies}); offsets stay exact, because the blanking preserves every position.
+ *
+ * The parser also answers WHERE each statement sits ({@link locatedCommandSegments}): `start`,
+ * `end`, `programOffset` and `assignmentOffset` are the offsets a caller splices at. They are
+ * token positions from this walk, never a search for re-joined text — the words are joined back
+ * with single spaces for matching, so `command.indexOf(segment.text)` fails on irregular spacing,
+ * on grouping braces, and on anything a heredoc body shifts (xr-molecule-flash-m105 +08:12).
  *
  * @module
  */
@@ -58,6 +64,66 @@ export declare function durationSeconds(word: string): number | null;
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/**
+ * One statement of a shell command, with where it sits and the variables it sets for itself.
+ *
+ * `commandSegments` answers WHAT runs; this answers where, and what the shell binds to it — the
+ * two things a caller that WRITES into a command needs. The platform composes a run from the
+ * executor's own command in more than one place, and a value written for the runner belongs in
+ * the runner's own statement: `APP_BASE=https://… cd app && npx playwright test` sets the variable
+ * for `cd` alone, so the Playwright config falls back to the local app while the command line
+ * still names the deployed host (xr-molecule-flash-m103 +28:08).
+ */
+export interface LocatedCommandSegment {
+    /**
+     * What the statement runs, or null when it only sets variables (`BASE=http://…` on its own):
+     * that shape persists in the shell, so a caller following assignments across `;`/`&&` has to
+     * see it.
+     */
+    segment: CommandSegment | null;
+    /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
+    assignments: readonly string[];
+    /**
+     * The offset in the command of the statement's first word, or null for a segment inside a
+     * nested `sh -c '<command>'` string — its positions are offsets in THAT string, not in this
+     * command, so nothing may be spliced at them.
+     */
+    start: number | null;
+    /**
+     * The offset in the command just before the word the statement runs — after its own leading
+     * `NAME=value` words and their whitespace. A `NAME=value` written here is in the environment of
+     * the program the statement runs (`… TEST_MODE=fullstack <here>npx playwright test`). Null
+     * inside a nested `sh -c` string, for the same reason as {@link start}.
+     */
+    assignmentOffset: number | null;
+    /**
+     * The offset in the command one past the statement's last word — where an option of this
+     * statement's program belongs, before whatever closes it. Null inside a nested `sh -c` string.
+     */
+    end: number | null;
+    /**
+     * The offset in the command of the word in command position — the program, once every wrapper
+     * in front of it is taken away (`npx --prefix /app <here>playwright test`). Null inside a
+     * nested `sh -c` string, and for a statement that only sets variables.
+     */
+    programOffset: number | null;
+    /**
+     * The separator the shell split at immediately before this statement — `|`, `||`, `&&`, `;`,
+     * a newline or `&` — or '' when it is the first statement of the command. It is the parse's own
+     * answer, so it is known even where the offsets are not, and a caller deciding whether two
+     * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
+     */
+    separator: string;
+}
+/**
+ * Every statement of a command, with its own assignments and where it sits — assignment-only
+ * statements included, because the variables those persist are exactly what a later statement of
+ * the same command reads.
+ *
+ * @param command - The shell command.
+ * @returns One entry per statement or pipeline stage, in order.
+ */
+export declare function locatedCommandSegments(command: string): LocatedCommandSegment[];
 /**
  * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
  * under (`timeout 280 hurl --test …` → 280), or null when it carries none.

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

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAuSD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AA+cD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AA4ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}