@molecule/api-ai-tools 1.0.9 → 1.1.0

package/dist/utilities.d.ts

@@ -64,6 +64,31 @@ export declare function redactSecretsInCode(s: string): string;
  * @returns `true` when the file is an env file.
  */
 export declare function isEnvFilePath(path: string): boolean;
+/**
+ * The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
+ * anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
+ * larger. Zero when it declares none.
+ *
+ * @param command - The shell command.
+ * @param timeoutParam - The tool call's `timeout` input, in milliseconds.
+ * @returns The declared budget in seconds, or 0.
+ */
+export declare function declaredBudgetSeconds(command: string, timeoutParam: unknown): number;
+/**
+ * Whether a command's output reaches the tool only when the whole pipeline
+ * ends — a pipe into `tail`, `grep`, `sort`, `wc` and friends, which
+ * block-buffer when stdout is not a terminal.
+ *
+ * It matters only in combination with an overrun: a command stopped at the
+ * tool's ceiling normally hands back everything it printed, but behind one of
+ * these it printed nothing, so the whole budget is spent for no information.
+ * Measured across six real agent runs: ten such commands, every one of them
+ * piped, 49 minutes returning a few hundred bytes each.
+ *
+ * @param command - The shell command.
+ * @returns True when a kill would return no useful output.
+ */
+export declare function outputIsWithheldUntilExit(command: string): boolean;
 /**
  * Check if a command is blocked for security reasons. Returns error message or null if allowed.
  *
@@ -127,6 +152,60 @@ export declare const MAX_READ_SIZE: number;
 export declare const MAX_WRITE_SIZE: number;
 /** Max command output size (100KB per stream). */
 export declare const MAX_OUTPUT_SIZE: number;
+/**
+ * Most lines of surrounding context `search_files` will return per match.
+ * Bounded so a broad pattern with a generous context cannot pull a whole tree
+ * into one reply.
+ */
+export declare const MAX_SEARCH_CONTEXT_LINES = 40;
+/**
+ * Return a line window of `content`, or null when no window was asked for.
+ *
+ * `read_file` returned whole files only, so an executor that wanted part of one
+ * shelled out: across six real agent runs, 260 of 377 shell-inspection commands
+ * (69%) were `head`/`tail`/`sed -n` windowing a file the tool could have
+ * windowed itself. `offset` is 1-based, matching the line numbers every other
+ * tool reports and what `grep -n` prints.
+ *
+ * @param content - The file's full text.
+ * @param window - The requested `offset` (1-based) and `limit` (line count).
+ * @returns The window plus its position, or null when neither was given.
+ */
+export declare function sliceLines(content: string, window?: {
+    offset?: unknown;
+    limit?: unknown;
+}): {
+    text: string;
+    offset: number;
+    lines: number;
+    totalLines: number;
+    truncated: boolean;
+} | null;
+/** Max search results. */
+/**
+ * Most files one batched `read_file` call returns. The cap exists so a survey
+ * of a large tree cannot swallow the turn's context in one result; the tool
+ * reports where it stopped so the model continues from there.
+ */
+export declare const MAX_BATCH_READ_FILES = 25;
+/**
+ * Total content bytes one batched `read_file` call returns, across all files.
+ * The per-file {@link MAX_READ_SIZE} still applies to each one.
+ */
+export declare const MAX_BATCH_READ_BYTES: number;
+/**
+ * The most one read_file call returns for ONE file when no window was asked
+ * for, in chars. Larger files come back as their first window with a note
+ * saying how to read the rest.
+ *
+ * MAX_READ_SIZE (5 MB) is a bound on what the tool will open, not on what it
+ * should hand a model: a single batched read that returned a 1.2 MB README
+ * put the next three provider calls at 366k tokens (~330k of them fresh)
+ * against a 120k-token context cap (X0 run x5, call 26). ~80 KB is ~20–25k
+ * tokens — a fifth of that cap, and more than any one file read usually
+ * needs.
+ */
+export declare const MAX_READ_RETURN_CHARS: number;
 /** Max search results. */
 export declare const MAX_SEARCH_RESULTS = 50;
 /** Max find results. */

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

package/dist/utilities.js

@@ -153,6 +153,42 @@ export function isEnvFilePath(path) {
     const base = path.split('/').pop() ?? '';
     return base === '.env' || base.startsWith('.env.') || base.endsWith('.env');
 }
+/**
+ * The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
+ * anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
+ * larger. Zero when it declares none.
+ *
+ * @param command - The shell command.
+ * @param timeoutParam - The tool call's `timeout` input, in milliseconds.
+ * @returns The declared budget in seconds, or 0.
+ */
+export function declaredBudgetSeconds(command, timeoutParam) {
+    let declared = 0;
+    for (const m of command.matchAll(/(?:^|[;&|]\s*|\s)timeout\s+(?:-[a-zA-Z-]+\s+)*(\d+)(?![\d.])/g)) {
+        declared = Math.max(declared, Number(m[1]));
+    }
+    const asMs = Number(timeoutParam);
+    if (Number.isFinite(asMs) && asMs > 0)
+        declared = Math.max(declared, Math.round(asMs / 1000));
+    return declared;
+}
+/**
+ * Whether a command's output reaches the tool only when the whole pipeline
+ * ends — a pipe into `tail`, `grep`, `sort`, `wc` and friends, which
+ * block-buffer when stdout is not a terminal.
+ *
+ * It matters only in combination with an overrun: a command stopped at the
+ * tool's ceiling normally hands back everything it printed, but behind one of
+ * these it printed nothing, so the whole budget is spent for no information.
+ * Measured across six real agent runs: ten such commands, every one of them
+ * piped, 49 minutes returning a few hundred bytes each.
+ *
+ * @param command - The shell command.
+ * @returns True when a kill would return no useful output.
+ */
+export function outputIsWithheldUntilExit(command) {
+    return /\|\s*(?:tail|head|grep|egrep|fgrep|sort|uniq|wc|jq)\b/.test(command);
+}
 // ── Command blocking ──────────────────────────────────────────────────────────
 /**
  * Commands that dump environment variables — blocked to prevent secret leakage.
@@ -236,7 +272,13 @@ export function resolvePath(path, projectRoot) {
  * @returns `true` when the pattern contains only allowed characters.
  */
 export function isValidGlob(pattern) {
-    return /^[A-Za-z0-9*?._/()[\]-]+$/.test(pattern);
+    // `@` is in the set because every package in this ecosystem is scoped:
+    // measured on a live build, the executor tried
+    // `node_modules/@molecule/app-ui/*` twice and was refused both times, so in
+    // a molecule project it could not glob its own dependencies. The character
+    // is inert here — patterns are shell-quoted before they reach find/grep, and
+    // `@` has no meaning to either.
+    return /^[A-Za-z0-9@*?._/()[\]-]+$/.test(pattern);
 }
 /**
  * Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -276,6 +318,80 @@ export const MAX_READ_SIZE = 5 * 1024 * 1024;
 export const MAX_WRITE_SIZE = 10 * 1024 * 1024;
 /** Max command output size (100KB per stream). */
 export const MAX_OUTPUT_SIZE = 100 * 1024;
+/**
+ * Most lines of surrounding context `search_files` will return per match.
+ * Bounded so a broad pattern with a generous context cannot pull a whole tree
+ * into one reply.
+ */
+export const MAX_SEARCH_CONTEXT_LINES = 40;
+/**
+ * Return a line window of `content`, or null when no window was asked for.
+ *
+ * `read_file` returned whole files only, so an executor that wanted part of one
+ * shelled out: across six real agent runs, 260 of 377 shell-inspection commands
+ * (69%) were `head`/`tail`/`sed -n` windowing a file the tool could have
+ * windowed itself. `offset` is 1-based, matching the line numbers every other
+ * tool reports and what `grep -n` prints.
+ *
+ * @param content - The file's full text.
+ * @param window - The requested `offset` (1-based) and `limit` (line count).
+ * @returns The window plus its position, or null when neither was given.
+ */
+export function sliceLines(content, window) {
+    const rawOffset = Number(window?.offset);
+    const rawLimit = Number(window?.limit);
+    const hasOffset = Number.isFinite(rawOffset) && rawOffset !== 0;
+    const hasLimit = Number.isFinite(rawLimit) && rawLimit > 0;
+    if (!hasOffset && !hasLimit)
+        return null;
+    const all = content.split('\n');
+    const totalLines = all.length;
+    // A NEGATIVE offset counts from the end, the `tail -N` convention. Without it
+    // "show me the last 30 lines" has no expression here, and the executor either
+    // reads the whole file or goes back to the shell — measured: asked for a
+    // file's tail with these tools available, it read the entire file 3 times out
+    // of 3 until this existed.
+    const fromEnd = hasOffset && rawOffset < 0;
+    const offset = fromEnd
+        ? Math.max(1, totalLines + Math.trunc(rawOffset) + 1)
+        : hasOffset
+            ? Math.min(Math.trunc(rawOffset), totalLines)
+            : 1;
+    const limit = hasLimit ? Math.trunc(rawLimit) : totalLines - offset + 1;
+    const picked = all.slice(offset - 1, offset - 1 + limit);
+    return {
+        text: picked.join('\n'),
+        offset,
+        lines: picked.length,
+        totalLines,
+        truncated: offset > 1 || offset - 1 + picked.length < totalLines,
+    };
+}
+/** Max search results. */
+/**
+ * Most files one batched `read_file` call returns. The cap exists so a survey
+ * of a large tree cannot swallow the turn's context in one result; the tool
+ * reports where it stopped so the model continues from there.
+ */
+export const MAX_BATCH_READ_FILES = 25;
+/**
+ * Total content bytes one batched `read_file` call returns, across all files.
+ * The per-file {@link MAX_READ_SIZE} still applies to each one.
+ */
+export const MAX_BATCH_READ_BYTES = 200 * 1024;
+/**
+ * The most one read_file call returns for ONE file when no window was asked
+ * for, in chars. Larger files come back as their first window with a note
+ * saying how to read the rest.
+ *
+ * MAX_READ_SIZE (5 MB) is a bound on what the tool will open, not on what it
+ * should hand a model: a single batched read that returned a 1.2 MB README
+ * put the next three provider calls at 366k tokens (~330k of them fresh)
+ * against a 120k-token context cap (X0 run x5, call 26). ~80 KB is ~20–25k
+ * tokens — a fifth of that cap, and more than any one file read usually
+ * needs.
+ */
+export const MAX_READ_RETURN_CHARS = 80 * 1024;
 /** Max search results. */
 export const MAX_SEARCH_RESULTS = 50;
 /** Max find results. */
@@ -367,7 +483,19 @@ export function truncateMiddle(s, maxLength) {
  * @returns The new content if a unique fuzzy run matched, else null.
  */
 export function whitespaceTolerantReplace(content, oldString, newString) {
-    const norm = (s) => s.replace(/\s+/g, ' ').trim();
+    // Per-line normalization: runs of whitespace become one space, and spaces
+    // next to punctuation are dropped entirely. The second rule is for the edit
+    // a weak executor makes from memory with one space missing —
+    // `readdirSync,readFileSync` against a file that reads
+    // `readdirSync, readFileSync` (X0 run x6: 15 of 48 edits failed, most of
+    // them this shape, after the file's exact text had left the context). A
+    // missing space is zero whitespace, which the runs rule cannot see. This
+    // only decides WHERE the block is; the replacement text is applied
+    // verbatim, and uniqueness is still required.
+    const norm = (s) => s
+        .replace(/\s*([,;:{}()[\]=<>.])\s*/g, '$1')
+        .replace(/\s+/g, ' ')
+        .trim();
     const fileLines = content.split('\n');
     const normOld = oldString.split('\n').map(norm);
     // Refuse a degenerate all-blank search block (would match any blank run).

package/package.json

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