@molecule/api-ai-tools 1.5.3 → 1.5.5

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-15T00:28:10.570Z
+Generated: 2026-10-15T20:27:42.092Z
 -->
 
 # @molecule/api-ai-tools
@@ -750,6 +750,28 @@ function sliceLines(
 
 **Returns:** The window plus its position, or null when neither was given.
 
+#### `streamingBackgroundCommand(command)`
+
+Rewrite a command about to run in the background so its log grows while it
+runs. Two shapes left the log empty until exit, and an empty log is what
+`wait_for_task` reads as "stuck", so working suites were reported stuck and
+killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
+
+- a trailing `| tail -N`, which holds everything back until the command ends.
+  It is dropped: `wait_for_task` already returns the end of the log.
+- `playwright test` with no `--reporter`, which runs the config's reporter —
+  often `html`, which prints nothing per test. `--reporter=line` is added
+  when the playwright run is the command's last step and nothing is piped or
+  redirected from it ( aside); the results are the same, printed as they happen.
+
+```typescript
+function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
+```
+
+- `command` — The command as the executor sent it.
+
+**Returns:** The command to run and one sentence per change made (empty when none).
+
 #### `stripControlChars(s)`
 
 Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB

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;AA2B9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAgCnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAs6CxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA2B9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAiCnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA06CxF"}

package/dist/tools.js

@@ -23,7 +23,7 @@ const waitedByTask = new Map();
  * m21, 2026-10-15).
  */
 const logBytesByTask = new Map();
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, isOutsideRoot, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, parseCheckCommand, parseCheckProblem, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, sliceLines, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, isOutsideRoot, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, parseCheckCommand, parseCheckProblem, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, sliceLines, streamingBackgroundCommand, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -1021,7 +1021,10 @@ export function buildTools(backend, config) {
                     // an executor's commands routinely carry quotes, heredocs and
                     // newlines, and re-quoting them into a detached `sh -c` is how a
                     // background runner corrupts the very thing it is running.
-                    await backend.writeFile(script, `${command}\n`);
+                    // Keep the log growing while it runs (see streamingBackgroundCommand):
+                    // an empty log is what wait_for_task reads as stuck.
+                    const streaming = streamingBackgroundCommand(command);
+                    await backend.writeFile(script, `${streaming.command}\n`);
                     await backend.run(`nohup sh -c ${shellQuote(`sh ${script} > ${log} 2>&1; echo $? > ${exitFile}`)} ` +
                         `> /dev/null 2>&1 & echo $! > /tmp/${id}.pid`, { cwd, timeout: 15_000 });
                     return {
@@ -1036,7 +1039,8 @@ export function buildTools(backend, config) {
                             `stdout of wait_for_task when the command finishes (read_file cannot reach /tmp — ` +
                             `to peek mid-run, exec_command: tail ${log}). If you have other work, do it and ` +
                             `check back. If you need this result before you can continue, call wait_for_task ` +
-                            `with this taskId — never sleep and read the log by hand.`,
+                            `with this taskId — never sleep and read the log by hand.` +
+                            (streaming.changes.length ? ` ${streaming.changes.join(' ')}` : ''),
                     };
                 }
                 catch (e) {

package/dist/utilities.d.ts

@@ -89,6 +89,26 @@ export declare function declaredBudgetSeconds(command: string, timeoutParam: unk
  * @returns True when a kill would return no useful output.
  */
 export declare function outputIsWithheldUntilExit(command: string): boolean;
+/**
+ * Rewrite a command about to run in the background so its log grows while it
+ * runs. Two shapes left the log empty until exit, and an empty log is what
+ * `wait_for_task` reads as "stuck", so working suites were reported stuck and
+ * killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
+ *
+ * - a trailing `| tail -N`, which holds everything back until the command ends.
+ *   It is dropped: `wait_for_task` already returns the end of the log.
+ * - `playwright test` with no `--reporter`, which runs the config's reporter —
+ *   often `html`, which prints nothing per test. `--reporter=line` is added
+ *   when the playwright run is the command's last step and nothing is piped or
+ *   redirected from it ( aside); the results are the same, printed as they happen.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns The command to run and one sentence per change made (empty when none).
+ */
+export declare function streamingBackgroundCommand(command: string): {
+    command: string;
+    changes: string[];
+};
 /**
  * Check if a command is blocked for security reasons. Returns error message or null if allowed.
  *

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}

package/dist/utilities.js

@@ -189,6 +189,44 @@ export function declaredBudgetSeconds(command, timeoutParam) {
 export function outputIsWithheldUntilExit(command) {
     return /\|\s*(?:tail|head|grep|egrep|fgrep|sort|uniq|wc|jq)\b/.test(command);
 }
+/** A trailing `| tail -N` / `| tail -n N` (stderr redirects before it stay). */
+const TRAILING_TAIL = /\s*\|\s*tail(?:\s+-n)?\s+[-+]?\d+\s*$/;
+/**
+ * Rewrite a command about to run in the background so its log grows while it
+ * runs. Two shapes left the log empty until exit, and an empty log is what
+ * `wait_for_task` reads as "stuck", so working suites were reported stuck and
+ * killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
+ *
+ * - a trailing `| tail -N`, which holds everything back until the command ends.
+ *   It is dropped: `wait_for_task` already returns the end of the log.
+ * - `playwright test` with no `--reporter`, which runs the config's reporter —
+ *   often `html`, which prints nothing per test. `--reporter=line` is added
+ *   when the playwright run is the command's last step and nothing is piped or
+ *   redirected from it ( aside); the results are the same, printed as they happen.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns The command to run and one sentence per change made (empty when none).
+ */
+export function streamingBackgroundCommand(command) {
+    const changes = [];
+    let out = command;
+    const tail = TRAILING_TAIL.exec(out);
+    if (tail) {
+        out = out.slice(0, tail.index);
+        changes.push(`Dropped the trailing \`${tail[0].trim()}\`: it holds all output back until the command ends, ` +
+            'and wait_for_task returns the end of the log anyway.');
+    }
+    const lastStep = out.split(/&&|\|\||;/).at(-1) ?? '';
+    if (/\bplaywright\s+test\b/.test(lastStep) &&
+        !/--reporter\b/.test(lastStep) &&
+        // `2>&1` only joins stderr to the log; any other pipe or redirect sends the output elsewhere.
+        !/[|>]/.test(lastStep.replace(/\d?>&\d/g, ''))) {
+        out = `${out.trimEnd()} --reporter=line`;
+        changes.push('Added `--reporter=line` so each test result is written to the log as it finishes ' +
+            '(the config reporter may print nothing until the end).');
+    }
+    return { command: out, changes };
+}
 // ── Command blocking ──────────────────────────────────────────────────────────
 /**
  * Commands that dump environment variables — blocked to prevent secret leakage.
@@ -220,7 +258,11 @@ export function checkBlockedCommand(command) {
     // These blocks fire when the executor tries to DUMP the environment (usually to discover
     // what managed services are configured). Don't just refuse — redirect: the values are
     // already in the process environment, so it never needs to print them.
-    const envDumpSteer = ' You do NOT need to dump it: the managed service values (DATABASE_URL, etc.) are already ' +
+    // A blocked command runs NONE of its parts: X1 run m53 lost the `mkdir -p …`
+    // chained before a blocked env read and only found out from the retry.
+    const envDumpSteer = ' Nothing in this command ran — none of its other parts either, so run those again ' +
+        'without the dump.' +
+        ' You do NOT need to dump it: the managed service values (DATABASE_URL, etc.) are already ' +
         'in the process environment — read them IN CODE via process.env / your config loader, or ' +
         "check the project's provisioned env file to see WHICH services exist. Printing them only " +
         'leaks secrets into the transcript. To check whether ONE variable is set without printing ' +

package/package.json

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