@molecule/api-ai-tools 1.3.0 → 1.4.1

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;AAoB9C,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,CAqxCxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAoB9C,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,CAmzCxF"}

package/dist/tools.js

@@ -379,6 +379,13 @@ export function buildTools(backend, config) {
             // reads in one imported-app build were misses on files that never existed). Return
             // ground truth in the SAME result — what the parent directory actually contains — so
             // the next read uses a real name instead of another guess.
+            // A package's docs are one tool call away wherever node_modules happens to live.
+            const moleculePkg = /node_modules\/(@molecule\/[^/]+)\//.exec(path)?.[1];
+            if (moleculePkg && /No such file or directory/i.test(message)) {
+                return {
+                    error: `No such file: ${path}. Read ${moleculePkg}'s documentation with read_molecule_doc("${moleculePkg}") instead of looking for it in node_modules.`,
+                };
+            }
             if (/No such file or directory/i.test(message)) {
                 const parent = path.replace(/\/[^/]*$/, '') || '/';
                 let listing;
@@ -413,7 +420,26 @@ export function buildTools(backend, config) {
                 return { path, entries: entries.map((e) => ({ name: e.name, type: e.type })) };
             }
             catch (e) {
-                return { error: `Failed to list ${path}: ${e.message}` };
+                const message = e.message;
+                // Same ground-truth answer as read_file's miss: a guessed path gets the parent's
+                // real contents back, so the next call names something that exists.
+                if (/No such file or directory|cannot access/i.test(message)) {
+                    const parent = path.replace(/\/[^/]*$/, '') || '/';
+                    try {
+                        const siblings = await backend.readDir(parent);
+                        return {
+                            error: `No such directory: ${path}. ${parent} contains: ${siblings
+                                .slice(0, 40)
+                                .map((s) => s.name + (s.type === 'directory' ? '/' : ''))
+                                .join(', ') || '(nothing)'}${siblings.length > 40 ? ', …' : ''}.`,
+                        };
+                    }
+                    catch (_parentErr) {
+                        // The parent is missing too; the plain message below says so.
+                        return { error: `No such directory: ${path} (and ${parent} does not exist either).` };
+                    }
+                }
+                return { error: `Failed to list ${path}: ${message}` };
             }
         },
         async read_file(input) {
@@ -664,10 +690,15 @@ export function buildTools(backend, config) {
                                 `indentation — or include more surrounding context to make it unique.`,
                         };
                     }
-                    if (count > 1)
+                    if (count > 1) {
+                        // Say WHERE, so the retry can widen old_string around the one it means.
+                        const lines = [];
+                        for (let at = content.indexOf(oldString); at >= 0 && lines.length < 10; at = content.indexOf(oldString, at + 1))
+                            lines.push(content.slice(0, at).split('\n').length);
                         return {
-                            error: `old_string found ${count} times in ${path} — must be unique. Include more surrounding context.`,
+                            error: `old_string found ${count} times in ${path} (starting at lines ${lines.join(', ')}${count > lines.length ? ', …' : ''}) — must be unique. Include more surrounding context from the one you mean, or make one edit per occurrence.`,
                         };
+                    }
                     // Splice by index rather than `content.replace(oldString, newString)`:
                     // String.replace treats `$&`, `$$`, `` $` ``, `$'` in the REPLACEMENT as
                     // special patterns, so a new_string containing regex-replacement code
@@ -904,7 +935,19 @@ export function buildTools(backend, config) {
             // offset/limit, so a long log is cheap to follow), and an `.exit` file
             // appears when it finishes — so "is it done?" is a read, not a poll that
             // blocks a turn.
-            if (input.run_in_background === true) {
+            // A command that declares its OWN budget larger than this tool's ceiling,
+            // and whose output is withheld until the pipeline ends, would be stopped
+            // at the ceiling having printed nothing. It used to be REFUSED ("Nothing
+            // was run") — which cost the executor a whole step in 48 of 48
+            // conversations that tried one (production analytics, 2026-09-26). It
+            // now runs in the background instead: the step does the work, and the
+            // executor gets a handle to wait on.
+            const ceilingSeconds = commandBudgetMs ? Math.max(1, Math.round(commandBudgetMs / 1000)) : 0;
+            const declaredSeconds = commandBudgetMs ? declaredBudgetSeconds(command, input.timeout) : 0;
+            const overCeiling = commandBudgetMs !== undefined &&
+                declaredSeconds > ceilingSeconds &&
+                outputIsWithheldUntilExit(command);
+            if (input.run_in_background === true || overCeiling) {
                 const id = `mol-bg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
                 const log = `/tmp/${id}.log`;
                 const exitFile = `/tmp/${id}.exit`;
@@ -921,7 +964,11 @@ export function buildTools(backend, config) {
                         taskId: id,
                         log,
                         exitFile,
-                        note: `Started in the background. Its output is being written to ${log} — read it with ` +
+                        note: (overCeiling
+                            ? `This command asks for ${declaredSeconds}s, more than this tool's ${ceilingSeconds}s, and its ` +
+                                'output only appears when it ends — so it was started in the background instead. '
+                            : '') +
+                            `Started in the background. Its output is being written to ${log} — read it with ` +
                             `read_file (use offset/limit to follow a long one). When it finishes, ${exitFile} ` +
                             `appears and holds the exit code. 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 — ` +
@@ -934,28 +981,6 @@ export function buildTools(backend, config) {
                     };
                 }
             }
-            // A command that declares its OWN budget larger than this tool's ceiling,
-            // and whose output is withheld until the pipeline ends, cannot produce
-            // anything: it will be stopped at the ceiling having printed nothing.
-            // Measured across six agent runs, that combination was ten commands and
-            // 49 minutes — 11% of all wall clock — each returning a few hundred bytes.
-            // Refusing in five seconds, naming both ways out, is strictly better than
-            // spending the ceiling to say the same thing afterwards. A command that
-            // declares nothing still RUNS: partial output survives an overrun, so
-            // there is something to learn either way.
-            if (commandBudgetMs) {
-                const ceiling = Math.max(1, Math.round(commandBudgetMs / 1000));
-                const declared = declaredBudgetSeconds(command, input.timeout);
-                if (declared > ceiling && outputIsWithheldUntilExit(command)) {
-                    return {
-                        error: `This command asks for ${declared}s and this tool stops at ${ceiling}s — and its output ` +
-                            'is piped into tail/head/grep, which print nothing until the pipeline ends, so it ' +
-                            'would spend the whole budget and hand you back nothing. Either run a smaller unit ' +
-                            '(one spec file, one build step) that finishes inside the limit, or drop the pipe ' +
-                            'and use a streaming reporter so the output survives being stopped. Nothing was run.',
-                    };
-                }
-            }
             try {
                 // exec_command runs installs/builds/tests — the old 30s hardcap killed
                 // those spuriously; use the (generous, caller-configurable) budget.

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;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,QAA0C,CAAA;AAEtE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU7D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,MAAM,GAAG,IAAI,CAKhB"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}

package/dist/utilities.js

@@ -223,7 +223,8 @@ export function checkBlockedCommand(command) {
     const envDumpSteer = ' 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.';
+        'leaks secrets into the transcript. To check whether ONE variable is set without printing ' +
+        'it: `test -n "$NAME" && echo set || echo missing`.';
     if (BLOCKED_COMMANDS.test(command))
         return `Command blocked: dumping environment variables is not allowed.${envDumpSteer}`;
     if (BLOCKED_PROC_REDIRECT.test(command))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "@molecule/api-ai": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.2.1",
+    "@molecule/api-ai": "1.3.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.11"