@molecule/api-ai-tools 1.13.0 → 1.14.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-22T00:38:26.332Z
+Generated: 2026-10-23T00:59:47.543Z
 -->
 
 # @molecule/api-ai-tools
@@ -140,6 +140,13 @@ still names the deployed host (xr-molecule-flash-m103 +28:08).
 
 ```typescript
 interface LocatedCommandSegment {
+  /**
+   * Directory-scope ancestry supplied by the existing shell parse, outermost first.
+   * Parenthesized groups and nested `sh -c` strings have their own shell directory;
+   * braces share their parent's. Identities are opaque and local to this invocation.
+   * Absent for ordinary statements in the outer shell, preserving their existing shape.
+   */
+  shellScope?: readonly string[]
   /**
    * 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
@@ -148,6 +155,13 @@ interface LocatedCommandSegment {
   segment: CommandSegment | null
   /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
   assignments: readonly string[]
+  /**
+   * Assignments whose values expand at this source statement, when different from
+   * inherited environment bindings. A nested `sh -c` carries outer bindings into
+   * every entry, but expands its caller's assignment values only before its first
+   * command. Absent when the ordinary `assignments` list is also the source list.
+   */
+  sourceAssignments?: 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
@@ -1491,6 +1505,19 @@ interface SuiteRunPipelinePlacement {
 }
 ```
 
+#### `RunningLogRead`
+
+A bounded, contiguous read of a running task's own log.
+
+```typescript
+interface RunningLogRead {
+  /** The log's last {@link RUNNING_LOG_READ_BYTES} bytes, contiguous, as one string. */
+  text: string
+  /** How many bytes the WHOLE log holds, or null when the read did not answer its size. */
+  bytes: number | null
+}
+```
+
 #### `FailedTest`
 
 One failed test, as a running suite's log names it.
@@ -1845,6 +1872,23 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `commandSubstitutions(command)`
+
+The direct executable command-substitution bodies in shell text, in source order.
+
+Uses the same quote, comment and heredoc boundaries as {@link executedCommands}.
+Single-quoted and escaped text is inert. Nested substitutions stay inside their
+parent's body so a caller can recurse with a separate working-directory scope
+for each body; a `cd` inside one must not affect its sibling or the outer shell.
+
+```typescript
+function commandSubstitutions(command: string): string[]
+```
+
+- `command` — The shell text to read, including any leading assignments.
+
+**Returns:** Each direct `$(…)` or backtick body, without its delimiters.
+
 #### `executedCommands(command)`
 
 Every command a shell command actually executes, at any depth — the statements themselves, the
@@ -2683,13 +2727,17 @@ function withSuiteConfig(command: string, config: string | null | undefined): st
 #### `scopedRerunCommand(command, locations, excluded, config, cwd, env)`
 
 The whole-suite command made scoped to the tests it should re-run instead: the same
-invocation — same directory, same settings — with the named `file:line`s in place of the whole
-suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
+invocation — same launcher, same settings — with the named `file:line`s in place of every
+positional selection the run carried (a spec file, a suite directory or a regex filter),
+`--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
 `--retries=0` set (a re-run of a known failure does not need to pay for retries).
 
 The re-run keeps the run's `> <file>` redirect only in the sense of keeping its OUTPUT there:
-the target is rewritten to a fresh sibling ({@link redirectToFreshFile}), so a re-run never
-overwrites the log the run itself is the evidence for (xr-molecule-flash-m173).
+the target is rewritten to a fresh sibling ({@link redirectRunnerOutputsToFreshFiles}), so a
+re-run never overwrites the log the run itself is the evidence for (xr-molecule-flash-m173) —
+and the setup around the run keeps its own file writes untouched (xr-molecule-flash-m429). A
+`tail`/`head`/`cat`/`grep` chained after the run that reads that exact log is shown the fresh
+sibling instead, so the re-run displays the run it performed (xr-molecule-flash-o03).
 
 `config` is the config the run was measured under ({@link withSuiteConfig}): the narrowed re-run
 carries it whenever the command itself does not, so a run that dropped `--config` cannot be
@@ -2888,6 +2936,26 @@ function moleculeDistReadNote(path: string): string | null
 
 **Returns:** The note, or null when the path is not inside a package's `dist`.
 
+#### `registeredTaskLogCommand(taskId)`
+
+The command that reads a REGISTERED background task's own log as one bounded contiguous window
+({@link runningLogReadCommand}), with the file its launch redirects to when the launch recorded
+one.
+
+The task id is the ownership: it is the handle `wait_for_task` returned, `/tmp/${taskId}.log` is
+the log this platform's launcher writes for it, and the redirect target is the file this
+process's own launch registered for that id — never a path parsed out of a command by the
+caller. A diagnosis that reads a running walk must not build a `/tmp` path of its own
+(xr-molecule-flash-l07: the wait's DISPLAY was diagnosed as if it were the log).
+
+```typescript
+function registeredTaskLogCommand(taskId: string): string | null
+```
+
+- `taskId` — The `mol-bg-…` handle the wait returned.
+
+**Returns:** The read command, or null when the handle is not a task id this platform minted.
+
 #### `shellInstalledPackageProbe(run)`
 
 Build an {@link InstalledPackageProbe} from a shell runner (a backend's
@@ -4211,6 +4279,42 @@ function runningCauseCommand(log: string, own?: string): string
 
 **Returns:** The shell command, safe to hand to the execution backend as-is.
 
+#### `runningLogReadCommand(log, own)`
+
+The shell command whose stdout is a bounded CONTIGUOUS read of a running task's own log: the
+log's byte size, then its last {@link RUNNING_LOG_READ_BYTES} bytes.
+
+{@link runningOutputSliceCommand} is the wrong read for a diagnosis, and l07 is the finding: it
+stitches the first 40 grep-selected failure lines to the last 1 000 bytes with a blank line
+between, so the tail is DISJOINT from the headers above it. Read as one log, the last numbered
+header absorbs whatever the tail starts with — a clipped skipped-test title became the cause of
+a genuine failure (xr-molecule-flash-l07). A contiguous window can only ever hold real
+neighbouring lines of one log.
+
+The size rides along so a caller can say when the window is only the log's end
+({@link parseRunningLogRead}); without it a tail reads as the whole run.
+
+```typescript
+function runningLogReadCommand(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.
+
+#### `parseRunningLogRead(stdout)`
+
+The two parts of {@link runningLogReadCommand}'s answer.
+
+```typescript
+function parseRunningLogRead(stdout: string): RunningLogRead | null
+```
+
+- `stdout` — The command's stdout.
+
+**Returns:** The window and the whole log's byte size, or null when the size line is absent (the read did not run, so nothing may be said about the log).
+
 #### `repeatingFailure(log)`
 
 The cause repeating among a running suite's failures, or null.
@@ -4614,7 +4718,9 @@ function whitespaceTolerantReplace(
 
 The shell command that parses one file and exits non-zero with the error
 when it does not parse: `node --check` for JavaScript, `JSON.parse` for
-JSON, esbuild's transform (present wherever Vite is) for TypeScript.
+ordinary JSON, TypeScript's config parser for `tsconfig`/`jsconfig` files
+(which are JSONC), esbuild's transform (present wherever Vite is) for
+TypeScript.
 
 ```typescript
 function parseCheckCommand(path: string): string | null
@@ -5181,6 +5287,14 @@ Bytes of a running log a repeating-cause look reads back.
 const REPEATING_CAUSE_TAIL_BYTES: 40000
 ```
 
+#### `RUNNING_LOG_READ_BYTES`
+
+Bytes of a running log a diagnostic note reads back: one {@link REPEATING_CAUSE_TAIL_BYTES} window.
+
+```typescript
+const RUNNING_LOG_READ_BYTES: 40000
+```
+
 #### `REPEATING_FAILURE_MIN`
 
 DISTINCT tests that must share one signature before a running suite's repeating cause is named.

package/dist/command-position.d.ts

@@ -90,6 +90,18 @@ export interface ExecutedCommand {
     /** The program and its arguments as one line, what a pattern anchored at the program matches. */
     text: string;
 }
+/**
+ * The direct executable command-substitution bodies in shell text, in source order.
+ *
+ * Uses the same quote, comment and heredoc boundaries as {@link executedCommands}.
+ * Single-quoted and escaped text is inert. Nested substitutions stay inside their
+ * parent's body so a caller can recurse with a separate working-directory scope
+ * for each body; a `cd` inside one must not affect its sibling or the outer shell.
+ *
+ * @param command - The shell text to read, including any leading assignments.
+ * @returns Each direct `$(…)` or backtick body, without its delimiters.
+ */
+export declare function commandSubstitutions(command: string): string[];
 /**
  * Every command a shell command actually executes, at any depth — the statements themselves, the
  * body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
@@ -122,6 +134,13 @@ export declare function executedCommands(command: string): ExecutedCommand[];
  * still names the deployed host (xr-molecule-flash-m103 +28:08).
  */
 export interface LocatedCommandSegment {
+    /**
+     * Directory-scope ancestry supplied by the existing shell parse, outermost first.
+     * Parenthesized groups and nested `sh -c` strings have their own shell directory;
+     * braces share their parent's. Identities are opaque and local to this invocation.
+     * Absent for ordinary statements in the outer shell, preserving their existing shape.
+     */
+    shellScope?: readonly string[];
     /**
      * 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
@@ -130,6 +149,13 @@ export interface LocatedCommandSegment {
     segment: CommandSegment | null;
     /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
     assignments: readonly string[];
+    /**
+     * Assignments whose values expand at this source statement, when different from
+     * inherited environment bindings. A nested `sh -c` carries outer bindings into
+     * every entry, but expands its caller's assignment values only before its first
+     * command. Absent when the ordinary `assignments` list is also the source list.
+     */
+    sourceAssignments?: 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

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;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;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAynBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;CACb;AAmFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;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;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA6BtD;AA4GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;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;;;;;OAKG;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;AAghBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAmoBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAyGD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;CACb;AAmFD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAW9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;AAiBD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC;;;;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;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA6BtD;AA0HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiD7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}