@molecule/api-ai-tools 1.9.8 → 1.9.9

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-18T02:50:39.697Z
+Generated: 2026-10-18T04:56:57.682Z
 -->
 
 # @molecule/api-ai-tools
@@ -278,6 +278,25 @@ interface GuardOptions {
 }
 ```
 
+#### `RunnerOutputFilter`
+
+A cutting stage that follows the runner, and the command with the whole pipe removed.
+
+```typescript
+interface RunnerOutputFilter {
+  /** The stage exactly as the runner's command wrote it — `tail -6`. */
+  stage: string
+  /** The pipe as a sentence names it — `| tail -6`. */
+  pipe: string
+  /**
+   * The command with the pipe and the stage removed — `hurl --variable uid=… --test /tmp/t.hurl
+   * 2>&1`. This is a command to send again as written, not a re-typing of it: it is a slice of the
+   * original with the filter's own range cut out, so every other word, quote and redirect stays.
+   */
+  command: string
+}
+```
+
 #### `ToolSchema`
 
 JSON-schema-backed definition for a single agent tool.
@@ -1382,6 +1401,27 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `outputFilterAfterRunner(command, runs)`
+
+The output filter that follows the runner in `command`, or null when there is none.
+
+Only a stage of the runner's OWN pipeline counts (its separator is `|`), and only when it is the
+LAST stage of that pipeline: a `| grep … | wc -l` chain would leave a dangling pipe if the
+middle stage were cut out, so a chain is not answered here at all. A filter before the runner
+(`cat run.log | tail -20 && hurl …`) reads something else's output and is not this.
+
+```typescript
+function outputFilterAfterRunner(
+  command: string,
+  runs: (segment: CommandSegment) => boolean,
+): RunnerOutputFilter | null
+```
+
+- `command` — The command as the executor sent it.
+- `runs` — Whether a segment is the runner this run is about (the caller knows its own kind: {@link CommandSegment.program} is the program, once wrapper words like `timeout 280` and `npx` are taken away).
+
+**Returns:** The filter and the unfiltered command, or null.
+
 #### `pipelineExitCodeNote(command, exitCode, output)`
 
 The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a

package/dist/index.d.ts

@@ -138,6 +138,7 @@ export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './line-diff.js';
 export * from './no-test-run.js';
+export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
 export * from './schemas.js';
 export * from './sleep-peek.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -138,6 +138,7 @@ export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './line-diff.js';
 export * from './no-test-run.js';
+export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
 export * from './schemas.js';
 export * from './sleep-peek.js';

package/dist/output-filter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A run whose own command piped its output through `tail`/`head`/`grep`/`sed`/`awk`/`cut`, so the
+ * failure the runner printed is not in what came back.
+ *
+ * xr-molecule-flash-m147 (+10:12) sent `hurl --variable uid=… --test /tmp/t.hurl 2>&1 | tail -6`.
+ * The six lines that survived are Hurl's closing tally; the failed assertion was above the cut.
+ * The platform, seeing a red run with no assertion block, said the cause was "the transport or the
+ * run itself" — a sentence that sends the reader at the network for a status assertion it never
+ * saw. The command was in the platform's hands the whole time: the pipe is the reader's own filter,
+ * not a fact about the run.
+ *
+ * This module answers the one question that lets a caller say so: is an output-slicing stage of
+ * THIS command's pipeline sitting after the runner, and what is the command without it? The parse
+ * is the package's own shell reader ({@link locatedCommandSegments}), so a `|` inside quotes or a
+ * heredoc is not a stage, and only a stage of the runner's own pipeline is considered.
+ *
+ * @module
+ */
+import { type CommandSegment } from './command-position.js';
+/** A cutting stage that follows the runner, and the command with the whole pipe removed. */
+export interface RunnerOutputFilter {
+    /** The stage exactly as the runner's command wrote it — `tail -6`. */
+    stage: string;
+    /** The pipe as a sentence names it — `| tail -6`. */
+    pipe: string;
+    /**
+     * The command with the pipe and the stage removed — `hurl --variable uid=… --test /tmp/t.hurl
+     * 2>&1`. This is a command to send again as written, not a re-typing of it: it is a slice of the
+     * original with the filter's own range cut out, so every other word, quote and redirect stays.
+     */
+    command: string;
+}
+/**
+ * The output filter that follows the runner in `command`, or null when there is none.
+ *
+ * Only a stage of the runner's OWN pipeline counts (its separator is `|`), and only when it is the
+ * LAST stage of that pipeline: a `| grep … | wc -l` chain would leave a dangling pipe if the
+ * middle stage were cut out, so a chain is not answered here at all. A filter before the runner
+ * (`cat run.log | tail -20 && hurl …`) reads something else's output and is not this.
+ *
+ * @param command - The command as the executor sent it.
+ * @param runs - Whether a segment is the runner this run is about (the caller knows its own kind:
+ *   {@link CommandSegment.program} is the program, once wrapper words like `timeout 280` and
+ *   `npx` are taken away).
+ * @returns The filter and the unfiltered command, or null.
+ */
+export declare function outputFilterAfterRunner(command: string, runs: (segment: CommandSegment) => boolean): RunnerOutputFilter | null;
+//# sourceMappingURL=output-filter.d.ts.map

package/dist/output-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-filter.d.ts","sourceRoot":"","sources":["../src/output-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,uBAAuB,CAAA;AASnF,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GACzC,kBAAkB,GAAG,IAAI,CAkB3B"}

package/dist/output-filter.js

@@ -0,0 +1,64 @@
+/**
+ * A run whose own command piped its output through `tail`/`head`/`grep`/`sed`/`awk`/`cut`, so the
+ * failure the runner printed is not in what came back.
+ *
+ * xr-molecule-flash-m147 (+10:12) sent `hurl --variable uid=… --test /tmp/t.hurl 2>&1 | tail -6`.
+ * The six lines that survived are Hurl's closing tally; the failed assertion was above the cut.
+ * The platform, seeing a red run with no assertion block, said the cause was "the transport or the
+ * run itself" — a sentence that sends the reader at the network for a status assertion it never
+ * saw. The command was in the platform's hands the whole time: the pipe is the reader's own filter,
+ * not a fact about the run.
+ *
+ * This module answers the one question that lets a caller say so: is an output-slicing stage of
+ * THIS command's pipeline sitting after the runner, and what is the command without it? The parse
+ * is the package's own shell reader ({@link locatedCommandSegments}), so a `|` inside quotes or a
+ * heredoc is not a stage, and only a stage of the runner's own pipeline is considered.
+ *
+ * @module
+ */
+import { locatedCommandSegments } from './command-position.js';
+/**
+ * The programs whose job is to re-shape what an earlier stage printed and that can DROP lines —
+ * the reader's own cut, never part of the run. `tee`, `sort` and `wc` are output plumbing too, but
+ * they do not hide a failure, so they are not read as the cause of a missing one.
+ */
+const CUTTING_FILTERS = new Set(['awk', 'cut', 'grep', 'head', 'sed', 'tail']);
+/**
+ * The output filter that follows the runner in `command`, or null when there is none.
+ *
+ * Only a stage of the runner's OWN pipeline counts (its separator is `|`), and only when it is the
+ * LAST stage of that pipeline: a `| grep … | wc -l` chain would leave a dangling pipe if the
+ * middle stage were cut out, so a chain is not answered here at all. A filter before the runner
+ * (`cat run.log | tail -20 && hurl …`) reads something else's output and is not this.
+ *
+ * @param command - The command as the executor sent it.
+ * @param runs - Whether a segment is the runner this run is about (the caller knows its own kind:
+ *   {@link CommandSegment.program} is the program, once wrapper words like `timeout 280` and
+ *   `npx` are taken away).
+ * @returns The filter and the unfiltered command, or null.
+ */
+export function outputFilterAfterRunner(command, runs) {
+    if (typeof command !== 'string' || command.trim() === '')
+        return null;
+    const entries = locatedCommandSegments(command);
+    const runnerAt = entries.findIndex((entry) => entry.segment !== null && runs(entry.segment));
+    if (runnerAt < 0 || runnerAt + 1 >= entries.length)
+        return null;
+    const runner = entries[runnerAt];
+    const filter = entries[runnerAt + 1];
+    // The stage must be fed by the runner's own pipe, and nothing may be piped out of the filter:
+    // those are the two positions where cutting it out leaves a command that still runs the run.
+    if (!runner || !filter || filter.separator.trim() !== '|')
+        return null;
+    if (!filter.segment || !CUTTING_FILTERS.has(filter.segment.program))
+        return null;
+    if (filter.terminator.trim() === '|')
+        return null;
+    if (runner.end === null || filter.start === null || filter.end === null)
+        return null;
+    return {
+        stage: command.slice(filter.start, filter.end),
+        pipe: `| ${command.slice(filter.start, filter.end)}`,
+        command: `${command.slice(0, runner.end)}${command.slice(filter.end)}`,
+    };
+}

package/package.json

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