@molecule/api-ai-tools 1.10.2 → 1.10.4

package/dist/inline-script.d.ts

@@ -0,0 +1,49 @@
+/**
+ * An inline interpreter program (`python3 -c`, `python3 - <<EOF`, `node -e`) that only touches local
+ * files — work that takes milliseconds or never ends, never minutes of honest progress.
+ *
+ * xr-molecule-flash-m200 (+03:45, 2026-10-19) spent 291 s of a 60-minute cap on
+ * `python3 - <<'EOF' … re.findall(r'([^{}]*:before[^{}]*)\{content:"[^"]*"\}', s) … EOF` rewriting a
+ * minified CSS file whose first rule is one ~25 KB selector list: the pattern's two unbounded
+ * `[^{}]*` around a literal backtrack cubically, printed nothing, and was stopped by the tool's
+ * full 290 s budget. The step was also unnecessary. Nothing in the tool distinguished that program
+ * — a local text transform that either finishes at once or is stuck — from a build that is genuinely
+ * slow, so it was given a build's budget and a build's advice ("run it in the background"), which
+ * only turns a hang into a longer hang.
+ *
+ * So an inline interpreter program with no network, install, test-runner, build or server verb gets
+ * a short budget ({@link INLINE_SCRIPT_BUDGET_MS}), and a cut says what happened: a runaway
+ * transform, not slow work ({@link inlineScriptRunawaySentence}).
+ *
+ * @module
+ */
+/**
+ * How long an inline interpreter program that only reads and writes local files may run.
+ *
+ * Such work finishes in milliseconds; if it has not finished in twenty seconds it never will
+ * (a backtracking regex on a large file, a loop waiting on something that is not coming), so this
+ * is a runaway detector, not a performance budget.
+ */
+export declare const INLINE_SCRIPT_BUDGET_MS = 20000;
+/**
+ * The interpreter of an INLINE program that only reads and writes local files — the shape that gets
+ * {@link INLINE_SCRIPT_BUDGET_MS} instead of the tool's command budget.
+ *
+ * An inline program with any external effect keeps the full budget: no network, install, test
+ * runner, build or server verb may appear anywhere in the command ({@link EXTERNAL_EFFECT}), and
+ * the command must not be a suite run or a foreground server (the platform's own classifiers).
+ *
+ * @param command - The command as the executor sent it.
+ * @returns The interpreter's name (`python3`, `node`, …), or null when this is not the shape.
+ */
+export declare function inlineLocalScriptCommand(command: string): string | null;
+/**
+ * What a cut inline program's result says instead of the background advice: the work never was
+ * slow, it is stuck, and re-running it — here or in the background — cannot help.
+ *
+ * @param interpreter - The interpreter the program ran under (`python3`, `node`, …).
+ * @param seconds - The short budget it was stopped at, in seconds.
+ * @returns The sentence the result carries.
+ */
+export declare function inlineScriptRunawaySentence(interpreter: string, seconds: number): string;
+//# sourceMappingURL=inline-script.d.ts.map

package/dist/inline-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-script.d.ts","sourceRoot":"","sources":["../src/inline-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAsD7C;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxF"}

package/dist/inline-script.js

@@ -0,0 +1,115 @@
+/**
+ * An inline interpreter program (`python3 -c`, `python3 - <<EOF`, `node -e`) that only touches local
+ * files — work that takes milliseconds or never ends, never minutes of honest progress.
+ *
+ * xr-molecule-flash-m200 (+03:45, 2026-10-19) spent 291 s of a 60-minute cap on
+ * `python3 - <<'EOF' … re.findall(r'([^{}]*:before[^{}]*)\{content:"[^"]*"\}', s) … EOF` rewriting a
+ * minified CSS file whose first rule is one ~25 KB selector list: the pattern's two unbounded
+ * `[^{}]*` around a literal backtrack cubically, printed nothing, and was stopped by the tool's
+ * full 290 s budget. The step was also unnecessary. Nothing in the tool distinguished that program
+ * — a local text transform that either finishes at once or is stuck — from a build that is genuinely
+ * slow, so it was given a build's budget and a build's advice ("run it in the background"), which
+ * only turns a hang into a longer hang.
+ *
+ * So an inline interpreter program with no network, install, test-runner, build or server verb gets
+ * a short budget ({@link INLINE_SCRIPT_BUDGET_MS}), and a cut says what happened: a runaway
+ * transform, not slow work ({@link inlineScriptRunawaySentence}).
+ *
+ * @module
+ */
+import { commandSegments } from './command-position.js';
+import { startsServerProgram } from './server-command.js';
+import { isSuiteRunCommand } from './utilities.js';
+/**
+ * How long an inline interpreter program that only reads and writes local files may run.
+ *
+ * Such work finishes in milliseconds; if it has not finished in twenty seconds it never will
+ * (a backtracking regex on a large file, a loop waiting on something that is not coming), so this
+ * is a runaway detector, not a performance budget.
+ */
+export const INLINE_SCRIPT_BUDGET_MS = 20_000;
+/** The interpreters a model writes an inline program in. */
+const INLINE_INTERPRETERS = new Set([
+    'python',
+    'node',
+    'nodejs',
+    'perl',
+    'ruby',
+    'php',
+]);
+/** `python3`, `python3.12`, `python` — every spelling of the same interpreter in command position. */
+const PYTHON = /^python(?:3(?:\.\d+)?)?$/;
+/**
+ * A flag that makes the interpreter read its PROGRAM from the command line (or stdin) instead of a
+ * script file: `-c`, `-e`, `--eval`, `--print`.
+ */
+const INLINE_FLAG = /^(?:-[A-Za-z]*[ce]|--(?:eval|print)(?:=|$))/;
+/** A heredoc operator whose delimiter follows it: `<<'EOF'`, `<<EOF`, `<<-EOF`. Not a here-string. */
+const HEREDOC = /^<<-?\s*['"]?[A-Za-z_]/;
+/**
+ * Effects that make an inline program something OTHER than a local text transform, so it keeps the
+ * tool's full budget: the network, an install, a test runner, a build, a container. Matched against
+ * the whole command, heredoc body included — a `urllib` import inside the program is exactly the
+ * case this list exists for.
+ *
+ * Every listed word is a false NEGATIVE when it appears in a comment or a string (the program keeps
+ * the long budget and the old advice). That is the safe direction: this list must never shrink the
+ * budget of a command that reaches outside the box.
+ */
+const EXTERNAL_EFFECT = /\b(?:curl|wget|aria2c|rsync|scp|sftp|ftp|ssh|urllib3?|httpx|aiohttp|axios|requests|fetch|XMLHttpRequest|socket|net\.connect|https?:\/\/|npm|npx|pnpm|yarn|bun|pip3?|conda|cargo|gem|composer|playwright|vitest|jest|hurl|vite|tsc|webpack|esbuild|rollup|docker|cmake|gradle|mvn|make|subprocess|Popen|child_process|execSync|spawnSync|git|psql|mysql|mongosh?|redis-cli|sqlite3)\b|\bos\.system\b|\b(?:http\.server|flask|fastapi|uvicorn|gunicorn)\b/i;
+/**
+ * Whether one parsed statement runs an interpreter program written inline.
+ *
+ * The heredoc body is already blanked by the parser, so `python3 - <<'EOF'` reads as the program
+ * `python3` with the arguments `-` and `<<'EOF'` — the two shapes a program on stdin is written in.
+ *
+ * @param segment - One statement of the command.
+ * @returns The interpreter's name when the statement is an inline program, otherwise null.
+ */
+function inlineProgram(segment) {
+    const name = segment.program.replace(/^.*\//, '');
+    if (!PYTHON.test(name) && !INLINE_INTERPRETERS.has(name))
+        return null;
+    const args = segment.args.map((arg) => arg.replace(/^(["'])(.*)\1$/, '$2'));
+    const inline = args.some((arg) => arg === '-' || HEREDOC.test(arg) || INLINE_FLAG.test(arg));
+    return inline ? name : null;
+}
+/**
+ * The interpreter of an INLINE program that only reads and writes local files — the shape that gets
+ * {@link INLINE_SCRIPT_BUDGET_MS} instead of the tool's command budget.
+ *
+ * An inline program with any external effect keeps the full budget: no network, install, test
+ * runner, build or server verb may appear anywhere in the command ({@link EXTERNAL_EFFECT}), and
+ * the command must not be a suite run or a foreground server (the platform's own classifiers).
+ *
+ * @param command - The command as the executor sent it.
+ * @returns The interpreter's name (`python3`, `node`, …), or null when this is not the shape.
+ */
+export function inlineLocalScriptCommand(command) {
+    if (typeof command !== 'string' || !command.trim())
+        return null;
+    if (EXTERNAL_EFFECT.test(command))
+        return null;
+    if (isSuiteRunCommand(command) || startsServerProgram(command))
+        return null;
+    for (const segment of commandSegments(command)) {
+        const interpreter = inlineProgram(segment);
+        if (interpreter !== null)
+            return interpreter;
+    }
+    return null;
+}
+/**
+ * What a cut inline program's result says instead of the background advice: the work never was
+ * slow, it is stuck, and re-running it — here or in the background — cannot help.
+ *
+ * @param interpreter - The interpreter the program ran under (`python3`, `node`, …).
+ * @param seconds - The short budget it was stopped at, in seconds.
+ * @returns The sentence the result carries.
+ */
+export function inlineScriptRunawaySentence(interpreter, seconds) {
+    return (`${interpreter} ran ${seconds} s without finishing on a local text transform — that is a ` +
+        'runaway (e.g. regex backtracking on a large file), not slow work; do not move it to the ' +
+        'background. Rewrite the transform (a non-backtracking pattern, or a plain string split), ' +
+        'or check whether the step is needed at all.');
+}

package/dist/no-test-run.d.ts

@@ -49,7 +49,9 @@
  *
  * A command that also runs tests is false however it is spelled: `npx playwright install &&
  * npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
- * reading a real run.
+ * reading a real run. So is a command carrying a segment this reader cannot place (a script it
+ * does not know, which may start a suite): only the runners and the {@link NO_TEST_PROGRAMS}
+ * table can be accounted for, and "only prints" is a claim about the WHOLE command.
  *
  * @param command - The shell command as the executor sent it.
  * @returns True when the command invokes a runner only to print.

package/dist/no-test-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"no-test-run.d.ts","sourceRoot":"","sources":["../src/no-test-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA0EH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAU3D"}
+{"version":3,"file":"no-test-run.d.ts","sourceRoot":"","sources":["../src/no-test-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAiLH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAiB3D"}

package/dist/no-test-run.js

@@ -75,6 +75,108 @@ const NO_RUN_FLAGS = {
     ],
     hurl: [/(?:^|\s)--help(?=\s|$)/, /(?:^|\s)-h(?=\s|$)/, /(?:^|\s)--version(?=\s|$)/],
 };
+/**
+ * The programs that start no test — the shell's own bookkeeping (`cd`, `export`, `echo`), and the
+ * readers, printers and file commands an executor uses to look at what is already there (`cat`,
+ * `ls`, `cp`, `tail`, …).
+ *
+ * A segment whose program is neither a runner nor one of these is a program this reader cannot
+ * account for: the suite's own script (`./run-api-tests-hurl.sh`), a wrapper the executor wrote,
+ * anything that may itself start a suite. {@link commandRunsNoTests} answers false for a command
+ * carrying one — "every invocation only prints" is not a claim an unknown step can support.
+ * X1 xr-molecule-flash-m197 (+05:18) sent
+ * `hurl --version | head -2 && HOST=http://localhost:4000 ./run-api-tests-hurl.sh 2>&1 | tail -60`,
+ * the suite passed 13/13, and the supplied script was the one segment nobody could place: the
+ * whole command read as a version probe, so every "has the suite run?" reader said no for the
+ * rest of the run and the early deploy was held to the end of the list.
+ */
+const NO_TEST_PROGRAMS = new Set([
+    '[',
+    '[[',
+    ':',
+    'awk',
+    'base64',
+    'basename',
+    'case',
+    'cat',
+    'cd',
+    'chmod',
+    'chown',
+    'column',
+    'comm',
+    'cp',
+    'cut',
+    'date',
+    'df',
+    'diff',
+    'dirname',
+    'do',
+    'done',
+    'du',
+    'echo',
+    'egrep',
+    'else',
+    'env',
+    'esac',
+    'export',
+    'expr',
+    'false',
+    'fgrep',
+    'fi',
+    'file',
+    'fold',
+    'for',
+    'grep',
+    'head',
+    'hostname',
+    'id',
+    'if',
+    'jq',
+    'kill',
+    'less',
+    'ln',
+    'ls',
+    'md5sum',
+    'mkdir',
+    'mktemp',
+    'more',
+    'mv',
+    'nl',
+    'od',
+    'paste',
+    'printf',
+    'pwd',
+    'readlink',
+    'realpath',
+    'rev',
+    'rm',
+    'rmdir',
+    'seq',
+    'set',
+    'sha256sum',
+    'sleep',
+    'sort',
+    'stat',
+    'tac',
+    'tail',
+    'tee',
+    'test',
+    'then',
+    'touch',
+    'tr',
+    'true',
+    'type',
+    'uname',
+    'uniq',
+    'unset',
+    'until',
+    'wait',
+    'wc',
+    'which',
+    'while',
+    'whoami',
+    'xxd',
+]);
 /**
  * A heredoc body is data a command writes, not what it runs: a `playwright test --list` inside
  * the config a command writes is not a run of this command either way. The pattern consumes the
@@ -113,7 +215,9 @@ function informational(runner, after) {
  *
  * A command that also runs tests is false however it is spelled: `npx playwright install &&
  * npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
- * reading a real run.
+ * reading a real run. So is a command carrying a segment this reader cannot place (a script it
+ * does not know, which may start a suite): only the runners and the {@link NO_TEST_PROGRAMS}
+ * table can be accounted for, and "only prints" is a claim about the WHOLE command.
  *
  * @param command - The shell command as the executor sent it.
  * @returns True when the command invokes a runner only to print.
@@ -123,9 +227,16 @@ export function commandRunsNoTests(command) {
         return false;
     let invocations = 0;
     for (const segment of commandSegments(command.replace(HEREDOC, ' '))) {
-        const runner = RUNNERS[segment.program];
-        if (!runner)
+        // An own key only: `constructor` is a program name (`constructor --version`) and a
+        // prototype key is not a runner.
+        const runner = Object.hasOwn(RUNNERS, segment.program) ? RUNNERS[segment.program] : undefined;
+        if (runner === undefined) {
+            // A program this reader cannot place may start a suite of its own; only a known
+            // non-test program lets the command keep reading as "prints only".
+            if (!NO_TEST_PROGRAMS.has(segment.program))
+                return false;
             continue;
+        }
         invocations += 1;
         if (!informational(runner, segment.args.join(' ')))
             return false;

package/dist/schemas.js

@@ -147,13 +147,13 @@ export const TOOL_SCHEMAS = {
     },
     find_files: {
         name: 'find_files',
-        description: "Find files by name or glob pattern recursively. Excludes node_modules and .git. Use for discovering files by name (e.g. '*.tsx', 'Dashboard*', 'index.*'). A pattern containing '/' matches the path instead: 'e2e/*.spec.ts', 'src/**/App.tsx', '**/SELECTORS.md'.",
+        description: "Find files by name or glob pattern recursively. Excludes node_modules and .git. Use for discovering files by name (e.g. '*.tsx', 'Dashboard*', 'index.*'). A pattern containing '/' matches the path instead: 'e2e/*.spec.ts', 'src/**/App.tsx', '**/SELECTORS.md'. Several extensions go in one brace group: '*.{ts,tsx}'.",
         parameters: {
             type: 'object',
             properties: {
                 pattern: {
                     type: 'string',
-                    description: "File name or glob pattern (e.g. '*.tsx', 'Dashboard*'). A pattern containing '/' is matched against the file's path, so 'src/**/App.tsx' and 'e2e/*.spec.ts' work.",
+                    description: "File name or glob pattern (e.g. '*.tsx', 'Dashboard*'). A pattern containing '/' is matched against the file's path, so 'src/**/App.tsx' and 'e2e/*.spec.ts' work. Several extensions go in one brace group of comma-separated alternatives: '*.{ts,tsx,yml}' (up to 16).",
                 },
                 path: {
                     type: 'string',

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA4K9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AA6ZD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsHnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA2ElF;;;;;;;;;;;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;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAyvFxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA8N9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkaD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA8HnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA2DlF;;;;;;;;;;;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;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA40FxF"}