@molecule/api-ai-tools 1.1.0 → 1.2.1

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-09-22T18:02:23.461Z
+Generated: 2026-09-22T21:57:22.227Z
 -->
 
 # @molecule/api-ai-tools
@@ -581,6 +581,37 @@ function outputIsWithheldUntilExit(command: string): boolean
 
 **Returns:** True when a kill would return no useful output.
 
+#### `parseCheckCommand(path)`
+
+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.
+
+```typescript
+function parseCheckCommand(path: string): string | null
+```
+
+- `path` — The file's absolute path.
+
+**Returns:** The command, or null when the file type has no cheap parser.
+
+#### `parseCheckProblem(result)`
+
+What a failed parse check says to the executor, or null when the check
+passed or could not run (no parser available is not a syntax error).
+
+```typescript
+function parseCheckProblem(result: {
+  stdout: string
+  stderr: string
+  exitCode: number
+}): string | null
+```
+
+- `result` — The check command's result.
+
+**Returns:** The message for the tool result, or null.
+
 #### `pathArgError(path, tool)`
 
 Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -881,6 +912,14 @@ Max content size for write_file (10MB).
 const MAX_WRITE_SIZE: number
 ```
 
+#### `PARSE_CHECKABLE`
+
+Files a parse check can vouch for cheaply right after a write.
+
+```typescript
+const PARSE_CHECKABLE: RegExp
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.

package/dist/backends/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,sFAAsF;AACtF,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC,CAAA;IACnF,mEAAmE;IAEnE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,WAAW,SAAe,GACzB,gBAAgB,CA2ClB"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,sFAAsF;AACtF,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC,CAAA;IACnF,mEAAmE;IAEnE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,WAAW,SAAe,GACzB,gBAAgB,CAmDlB"}

package/dist/backends/sandbox.js

@@ -42,9 +42,17 @@ export function createSandboxBackend(sandbox, projectRoot = '/workspace') {
             // printed still comes back, with exit code 124. Wrapping only the inner
             // command would run it in a child shell that never sees unexported variables
             // the consumer's sourcing set.
+            // Its output goes to files that are printed once the shell exits, never to
+            // the exec's own pipe: `cd app && server > log &` backgrounds a SUBSHELL whose
+            // stdout is still that pipe (the redirect covers the server only), and the
+            // exec waits for every holder of the pipe — past the budget, which kills the
+            // shell but not the detached subshell, until the caller's outer timeout
+            // throws the output away. Measured: three 300 s calls in two runs (X0 x31,
+            // x33). A background child now holds a file, and the call returns when the
+            // command does.
             const budgetSeconds = opts?.budgetMs ? Math.max(1, Math.round(opts.budgetMs / 1000)) : 0;
             const fullCommand = budgetSeconds
-                ? `timeout -k 5 ${budgetSeconds} bash -c ${shellQuote(anchored)}`
+                ? `o=$(mktemp); e=$(mktemp); timeout -k 5 ${budgetSeconds} bash -c ${shellQuote(anchored)} > "$o" 2> "$e" < /dev/null; c=$?; cat "$o"; cat "$e" >&2; rm -f "$o" "$e"; exit $c`
                 : anchored;
             // sandbox.exec is the Sandbox interface method — runs inside Docker, inherently sandboxed
             const result = await sandbox.exec(fullCommand, { timeout: opts?.timeout });

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

package/dist/tools.js

@@ -15,7 +15,7 @@ import { TOOL_SCHEMAS } from './schemas.js';
 const stuckAfterMs = () => Number(process.env.MOL_AI_BG_STUCK_AFTER_MS) || 5 * 60 * 1000;
 /** Cumulative wait_for_task time per task id, this process. */
 const waitedByTask = new Map();
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, 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, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, sliceLines, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, 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';
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -51,6 +51,29 @@ export function buildTools(backend, config) {
     const grepExcludeArgs = excludedDirs.map((d) => `--exclude-dir=${shellQuote(d)}`).join(' ');
     const findExcludeArgs = excludedDirs.map((d) => `-not -path ${shellQuote(`*/${d}/*`)}`).join(' ');
     // ── Path helpers ───────────────────────────────────────────────
+    /**
+     * After a write or edit, parse the file and hand the error back IN THE SAME
+     * RESULT. An edit that leaves a file unparsable used to surface only at the
+     * next build or type-check, minutes and many calls later — x13 (2026-09-22)
+     * mangled a template literal in `scripts/prerender.mjs`, the site stopped
+     * building, and the fix round spent 500 calls on the fallout. `node --check`
+     * is ~50 ms; the executor sees the exact line while the edit is still in
+     * front of it.
+     */
+    async function syntaxErrorAfterWrite(path) {
+        const command = parseCheckCommand(path);
+        if (!command)
+            return {};
+        const result = await backend
+            .run(command, { cwd: path.slice(0, path.lastIndexOf('/')) || '/', timeout: 15_000 })
+            .catch(() => null);
+        const problem = result ? parseCheckProblem(result) : null;
+        return problem
+            ? {
+                syntaxError: `The file no longer parses after this change — fix it before anything else, every build and test fails until it does:\n${problem}`,
+            }
+            : {};
+    }
     /**
      * Resolve a workspace-relative path using optional path guards.
      *
@@ -464,7 +487,7 @@ export function buildTools(backend, config) {
                 const diff = computeDiff(oldContent, finalContent);
                 if (onFileChange)
                     onFileChange({ type: oldContent === null ? 'created' : 'modified', path });
-                return { path, ok: true, diff };
+                return { path, ok: true, diff, ...(await syntaxErrorAfterWrite(path)) };
             }
             catch (e) {
                 return { error: `Failed to write ${path}: ${e.message}` };
@@ -504,6 +527,7 @@ export function buildTools(backend, config) {
                     content = verdict.content;
                 }
                 const oldContent = content;
+                let alreadyApplied = 0;
                 for (const { old_string: oldString, new_string: newString } of replacements) {
                     // Validate each replacement is well-formed BEFORE touching content. A
                     // weak model sometimes emits a batch element missing a field or with a
@@ -516,6 +540,19 @@ export function buildTools(backend, config) {
                         };
                     }
                     const count = content.split(oldString).length - 1;
+                    // The edit is ALREADY in the file: old_string is gone and a distinctive
+                    // new_string is there exactly once. The executor re-sends an edit it
+                    // made a few calls ago (it works from its memory of the file), and the
+                    // "not found" error cost it a read_file plus a retry each time — 6 to 11
+                    // times a build in X0 x30/x34. Report it as applied instead. Short or
+                    // repeated new_strings still error: they could be there by coincidence.
+                    if (count === 0 &&
+                        newString !== oldString &&
+                        newString.trim().length >= 20 &&
+                        content.split(newString).length - 1 === 1) {
+                        alreadyApplied++;
+                        continue;
+                    }
                     if (count === 0) {
                         // A bare "old_string not found" gives the model nothing to correct, so
                         // it retries blindly (the #1 edit_file failure mode). Diagnose WHY the
@@ -625,6 +662,12 @@ export function buildTools(backend, config) {
                     const at = content.indexOf(oldString);
                     content = content.slice(0, at) + newString + content.slice(at + oldString.length);
                 }
+                const alreadyNote = alreadyApplied > 0
+                    ? `${alreadyApplied} of these edits ${alreadyApplied === 1 ? 'was' : 'were'} already in the file (its new_string is there and its old_string is not) — nothing to do for ${alreadyApplied === 1 ? 'it' : 'them'}.`
+                    : null;
+                if (content === oldContent) {
+                    return { path, ok: true, replacementsApplied: 0, alreadyApplied, note: alreadyNote };
+                }
                 if (onFileDiff)
                     onFileDiff({ path, oldContent, newContent: content });
                 await backend.writeFile(path, content);
@@ -632,7 +675,13 @@ export function buildTools(backend, config) {
                     await onAfterWrite(path).catch(() => { });
                 if (onFileChange)
                     onFileChange({ type: 'modified', path });
-                return { path, ok: true, replacementsApplied: replacements.length };
+                return {
+                    path,
+                    ok: true,
+                    replacementsApplied: replacements.length - alreadyApplied,
+                    ...(alreadyApplied > 0 ? { alreadyApplied, note: alreadyNote } : {}),
+                    ...(await syntaxErrorAfterWrite(path)),
+                };
             }
             catch (e) {
                 return { error: `Failed to edit ${path}: ${e.message}` };

package/dist/utilities.d.ts

@@ -263,4 +263,27 @@ export declare function truncateMiddle(s: string, maxLength: number): string;
  * @returns The new content if a unique fuzzy run matched, else null.
  */
 export declare function whitespaceTolerantReplace(content: string, oldString: string, newString: string): string | null;
+/** Files a parse check can vouch for cheaply right after a write. */
+export declare const PARSE_CHECKABLE: RegExp;
+/**
+ * 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.
+ *
+ * @param path - The file's absolute path.
+ * @returns The command, or null when the file type has no cheap parser.
+ */
+export declare function parseCheckCommand(path: string): string | null;
+/**
+ * What a failed parse check says to the executor, or null when the check
+ * passed or could not run (no parser available is not a syntax error).
+ *
+ * @param result - The check command's result.
+ * @returns The message for the tool result, or null.
+ */
+export declare function parseCheckProblem(result: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}): string | null;
 //# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAEE,CAAA;AAyFhD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAUpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAElE;AA2BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBlE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAID,yCAAyC;AACzC,eAAO,MAAM,aAAa,QAAkB,CAAA;AAC5C,8CAA8C;AAC9C,eAAO,MAAM,cAAc,QAAmB,CAAA;AAC9C,kDAAkD;AAClD,eAAO,MAAM,eAAe,QAAa,CAAA;AACzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA6BhG;AAED,0BAA0B;AAC1B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAa,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,QAAY,CAAA;AAE9C,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,mHAW/B,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAsCf"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}

package/dist/utilities.js

@@ -521,3 +521,39 @@ export function whitespaceTolerantReplace(content, oldString, newString) {
     const start = matches[0];
     return [...fileLines.slice(0, start), newString, ...fileLines.slice(start + normOld.length)].join('\n');
 }
+/** Files a parse check can vouch for cheaply right after a write. */
+export const PARSE_CHECKABLE = /\.(m?js|cjs|jsx|ts|tsx|mts|cts|json)$/;
+/**
+ * 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.
+ *
+ * @param path - The file's absolute path.
+ * @returns The command, or null when the file type has no cheap parser.
+ */
+export function parseCheckCommand(path) {
+    if (!PARSE_CHECKABLE.test(path))
+        return null;
+    const q = shellQuote(path);
+    if (/\.(m?js|cjs)$/.test(path))
+        return `node --check ${q}`;
+    if (/\.json$/.test(path))
+        return `node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" ${q}`;
+    return (`node -e "const p=process.argv[1];const src=require('fs').readFileSync(p,'utf8');` +
+        `require('esbuild').transformSync(src,{loader:p.endsWith('x')?'tsx':'ts',logLevel:'silent'})" ${q}`);
+}
+/**
+ * What a failed parse check says to the executor, or null when the check
+ * passed or could not run (no parser available is not a syntax error).
+ *
+ * @param result - The check command's result.
+ * @returns The message for the tool result, or null.
+ */
+export function parseCheckProblem(result) {
+    if (result.exitCode === 0)
+        return null;
+    const text = (result.stderr || result.stdout).trim();
+    if (/Cannot find module|not found/i.test(text) && !/SyntaxError/.test(text))
+        return null;
+    return text.slice(0, 1200);
+}

package/package.json

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