@molecule/api-ai-tools 1.9.1 → 1.9.2

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-17T07:58:25.504Z
+Generated: 2026-10-17T09:38:26.898Z
 -->
 
 # @molecule/api-ai-tools
@@ -1227,6 +1227,30 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `pipelineExitCodeNote(command, exitCode, output)`
+
+The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a
+pipeline's last stage rather than to the check that printed the output.
+
+Two shapes, both from a hand-run check with an unguarded pipe:
+
+- the code says 0 and the output carries failures (`tsc | head` reports `head`'s 0);
+- the code is non-zero and the checker printed no failures (`tsc | head && tail missing.log`
+  reports `tail`'s 1, and the checker was clean).
+
+A command with no pipe, a pipe guarded by `pipefail`, a pipeline where no checker runs, or a
+code and an output that agree all return null.
+
+```typescript
+function pipelineExitCodeNote(command: string, exitCode: number, output: string): string | null
+```
+
+- `command` — The command as the executor sent it.
+- `exitCode` — The code the shell reported (the pipeline's last stage's).
+- `output` — The command's raw stdout and stderr, for the checker's own text.
+
+**Returns:** One sentence naming the stage the code came from, or null.
+
 #### `leadingSleepPeek(command)`
 
 The leading `sleep` of a command, when the first statement is one and it asks for at least

package/dist/index.d.ts

@@ -137,6 +137,7 @@ export * from './cut-run.js';
 export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
+export * from './pipeline-exit-note.js';
 export * from './schemas.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.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,kBAAkB,CAAA;AAChC,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,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"}

package/dist/index.js

@@ -137,6 +137,7 @@ export * from './cut-run.js';
 export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
+export * from './pipeline-exit-note.js';
 export * from './schemas.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';

package/dist/pipeline-exit-note.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The exit code a hand-run check's result carries is the pipeline's LAST stage's, and a weak
+ * executor reads the number as the check's verdict.
+ *
+ * `npx tsc --noEmit 2>&1 | head -40` reports `head`'s 0 while the output above it carries a type
+ * error, and `… | head -40 && tail -30 missing.log` reports `tail`'s 1 while the checker was clean —
+ * both measured in xr-molecule-flash-m117 (+04:06, +08:05). A model that trusts the code concludes
+ * "clean" and ships a build that does not compile, or hunts an error that is not there. This module
+ * says which stage produced the code, and what the output actually carries, in one sentence beside
+ * `exitCode`.
+ *
+ * The parse is the package's own shell reader ({@link locatedCommandSegments}), so a `|` inside
+ * quotes or a heredoc is not a stage, and `set -o pipefail` (where it really runs) turns the note
+ * off: then the code IS the check's.
+ *
+ * @module
+ */
+/**
+ * The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a
+ * pipeline's last stage rather than to the check that printed the output.
+ *
+ * Two shapes, both from a hand-run check with an unguarded pipe:
+ *
+ * - the code says 0 and the output carries failures (`tsc | head` reports `head`'s 0);
+ * - the code is non-zero and the checker printed no failures (`tsc | head && tail missing.log`
+ *   reports `tail`'s 1, and the checker was clean).
+ *
+ * A command with no pipe, a pipe guarded by `pipefail`, a pipeline where no checker runs, or a
+ * code and an output that agree all return null.
+ *
+ * @param command - The command as the executor sent it.
+ * @param exitCode - The code the shell reported (the pipeline's last stage's).
+ * @param output - The command's raw stdout and stderr, for the checker's own text.
+ * @returns One sentence naming the stage the code came from, or null.
+ */
+export declare function pipelineExitCodeNote(command: string, exitCode: number, output: string): string | null;
+//# sourceMappingURL=pipeline-exit-note.d.ts.map

package/dist/pipeline-exit-note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-exit-note.d.ts","sourceRoot":"","sources":["../src/pipeline-exit-note.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2GH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAsCf"}

package/dist/pipeline-exit-note.js

@@ -0,0 +1,154 @@
+/**
+ * The exit code a hand-run check's result carries is the pipeline's LAST stage's, and a weak
+ * executor reads the number as the check's verdict.
+ *
+ * `npx tsc --noEmit 2>&1 | head -40` reports `head`'s 0 while the output above it carries a type
+ * error, and `… | head -40 && tail -30 missing.log` reports `tail`'s 1 while the checker was clean —
+ * both measured in xr-molecule-flash-m117 (+04:06, +08:05). A model that trusts the code concludes
+ * "clean" and ships a build that does not compile, or hunts an error that is not there. This module
+ * says which stage produced the code, and what the output actually carries, in one sentence beside
+ * `exitCode`.
+ *
+ * The parse is the package's own shell reader ({@link locatedCommandSegments}), so a `|` inside
+ * quotes or a heredoc is not a stage, and `set -o pipefail` (where it really runs) turns the note
+ * off: then the code IS the check's.
+ *
+ * @module
+ */
+import { locatedCommandSegments } from './command-position.js';
+/** The shells whose `-o pipefail` makes a pipeline report its first failing stage. */
+const PIPEFAIL_SHELLS = new Set(['ash', 'bash', 'dash', 'ksh', 'sh', 'zsh']);
+/**
+ * The programs a pipeline may end with when all they do is read what was printed and print it
+ * again — the stages that hand back their own status in place of the check's.
+ */
+const OUTPUT_ONLY_FILTERS = new Set([
+    'awk',
+    'cat',
+    'column',
+    'cut',
+    'egrep',
+    'fgrep',
+    'fmt',
+    'fold',
+    'grep',
+    'head',
+    'jq',
+    'nl',
+    'rg',
+    'sed',
+    'sort',
+    'tail',
+    'tr',
+    'uniq',
+    'wc',
+]);
+/** `1 type error` / `2 type errors`. */
+const plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/**
+ * The failure count a runner's tally names. Vitest prints two tallies — `Test Files  1 failed`
+ * above `Tests  2 failed` — and the last one is the tests, which is the number the note means.
+ *
+ * @param output - The runner's output.
+ * @returns The count in the last `N failed` tally, or 0.
+ */
+const failedTally = (output) => {
+    const tallies = [...output.matchAll(/\b(\d+) failed\b/g)];
+    return Number(tallies.at(-1)?.[1] ?? 0);
+};
+/** The checkers whose output says pass or fail in text of its own. */
+const CHECKERS = [
+    {
+        name: 'tsc',
+        runs: (program) => program === 'tsc' || program === 'vue-tsc',
+        failures: (output) => {
+            const errors = output.match(/\berror TS\d+/g)?.length ?? 0;
+            if (errors > 0)
+                return errors;
+            const found = /\bFound (\d+) errors?/.exec(output);
+            return found ? Number(found[1]) : 0;
+        },
+        label: (count) => plural(count, 'type error', 'type errors'),
+    },
+    {
+        name: 'eslint',
+        runs: (program) => program === 'eslint',
+        failures: (output) => {
+            const problems = /✖\s*(\d+)\s+problems?/.exec(output);
+            return problems ? Number(problems[1]) : 0;
+        },
+        label: (count) => plural(count, 'lint problem', 'lint problems'),
+    },
+    {
+        name: 'vitest',
+        runs: (program) => program === 'vitest',
+        failures: failedTally,
+        label: (count) => plural(count, 'failing test', 'failing tests'),
+    },
+    {
+        name: 'playwright',
+        runs: (_program, text) => /^playwright\s+test\b/.test(text),
+        failures: failedTally,
+        label: (count) => plural(count, 'failing test', 'failing tests'),
+    },
+];
+/** Whether the command turns on `pipefail`, so a pipeline reports the check's own status. */
+function guardedByPipefail(segments) {
+    return segments.some(({ program, args }) => (program === 'set' || PIPEFAIL_SHELLS.has(program)) && args.includes('pipefail'));
+}
+/**
+ * The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a
+ * pipeline's last stage rather than to the check that printed the output.
+ *
+ * Two shapes, both from a hand-run check with an unguarded pipe:
+ *
+ * - the code says 0 and the output carries failures (`tsc | head` reports `head`'s 0);
+ * - the code is non-zero and the checker printed no failures (`tsc | head && tail missing.log`
+ *   reports `tail`'s 1, and the checker was clean).
+ *
+ * A command with no pipe, a pipe guarded by `pipefail`, a pipeline where no checker runs, or a
+ * code and an output that agree all return null.
+ *
+ * @param command - The command as the executor sent it.
+ * @param exitCode - The code the shell reported (the pipeline's last stage's).
+ * @param output - The command's raw stdout and stderr, for the checker's own text.
+ * @returns One sentence naming the stage the code came from, or null.
+ */
+export function pipelineExitCodeNote(command, exitCode, output) {
+    const running = locatedCommandSegments(command).filter((entry) => entry.segment !== null);
+    if (running.length < 2)
+        return null;
+    if (!running.some((entry) => entry.separator.trim() === '|'))
+        return null;
+    const segments = running.map((entry) => entry.segment);
+    if (guardedByPipefail(segments))
+        return null;
+    let checkerAt = -1;
+    for (let i = segments.length - 1; i >= 0; i -= 1) {
+        const segment = segments[i];
+        if (CHECKERS.some((checker) => checker.runs(segment.program, segment.text))) {
+            checkerAt = i;
+            break;
+        }
+    }
+    if (checkerAt < 0)
+        return null;
+    // The check's own status is lost only when a stage of the SAME pipeline follows it; a `&&` after
+    // the check already reports a real failure of its own, and a check followed by nothing reports
+    // its own code.
+    if (running[checkerAt + 1]?.separator.trim() !== '|')
+        return null;
+    const checkerSegment = segments[checkerAt];
+    const checker = CHECKERS.find((candidate) => candidate.runs(checkerSegment.program, checkerSegment.text));
+    const last = segments[segments.length - 1];
+    const failures = checker.failures(output);
+    if (exitCode === 0 && failures > 0) {
+        return (`the exit code 0 is the last stage's (${last.program}), not ${checker.name}'s — ` +
+            `the output carries ${checker.label(failures)}`);
+    }
+    if (exitCode !== 0 && failures === 0 && OUTPUT_ONLY_FILTERS.has(last.program)) {
+        return (`the exit code ${exitCode} is the last stage's (${last.program}), not ${checker.name}'s — ` +
+            'the checker printed no errors');
+    }
+    return null;
+}

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;AAgJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAiOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAu2ExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAiJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAiOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAy3ExF"}

package/dist/tools.js

@@ -9,6 +9,7 @@
 import { commandCutRun, CUT_AT_BUDGET, cutRunSentence, suiteRunExitCode } from './cut-run.js';
 import { addChangeSpan, changedSpan, countLines, renderEditExcerpt, renderSmallFile, } from './edit-excerpt.js';
 import { guardToolExecute, missingParamError, ToolInputError } from './input-normalizer.js';
+import { pipelineExitCodeNote } from './pipeline-exit-note.js';
 import { TOOL_SCHEMAS } from './schemas.js';
 import { leadingSleepPeek } from './sleep-peek.js';
 /**
@@ -2172,6 +2173,12 @@ export function buildTools(backend, config) {
                                 const placement = suiteRunPipelinePlacement(streaming.command);
                                 const reported = suiteRunExitCode(code, output, placement.piped);
                                 const exitNote = suiteExitCodeNote(placement, reported);
+                                // The same question the foreground path asks: when the code is a filter's, say
+                                // which stage produced it (and what the output carries) rather than leaving a
+                                // 0 beside a printed error.
+                                const pipeNote = reported === null
+                                    ? null
+                                    : pipelineExitCodeNote(streaming.command, reported, output);
                                 const notes = [
                                     ...(sleepNote ? [sleepNote] : []),
                                     ...streaming.changes,
@@ -2181,6 +2188,7 @@ export function buildTools(backend, config) {
                                     stdout,
                                     stderr: '',
                                     exitCode: reported,
+                                    ...(pipeNote === null ? {} : { exitCodeNote: pipeNote }),
                                     ...(output.length > MAX_OUTPUT_SIZE ? { truncated: true, fullOutput: log } : {}),
                                     ...(notes.length ? { note: notes.join(' ') } : {}),
                                 };
@@ -2305,10 +2313,16 @@ export function buildTools(backend, config) {
                             (isSuiteRunCommand(command) ? SUITE_OVER_BUDGET_ADVICE : SPLIT_WORK_ADVICE),
                     };
                 }
+                // A pipeline reports its LAST stage's code: `tsc | head` says 0 beside a printed type
+                // error, and `tsc | head && tail missing.log` says 1 beside a clean check. Name the
+                // stage the number came from (pipeline-exit-note.ts) — the field the executor trusts
+                // most must not contradict the text it can read.
+                const exitCodeNote = pipelineExitCodeNote(command, result.exitCode, `${result.stdout}\n${result.stderr}`);
                 return {
                     stdout,
                     stderr,
                     exitCode: result.exitCode,
+                    ...(exitCodeNote === null ? {} : { exitCodeNote }),
                     ...(peekedTask?.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
                     ...(sleepNote || ceilingNote || traced.change
                         ? {

package/package.json

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