@molecule/api-ai-tools 1.5.16 → 1.5.18

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-16T07:29:43.225Z
+Generated: 2026-10-16T09:30:45.054Z
 -->
 
 # @molecule/api-ai-tools
@@ -488,6 +488,24 @@ function buildAgentPrompt(ctx: PromptContext): string
 
 **Returns:** Fully assembled system prompt text for the coding agent.
 
+#### `moleculeDistReadNote(path)`
+
+The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
+redirect below fires only when the read FAILS, so a model that knows the hoisted
+layout reads `node_modules/@molecule/<pkg>/dist/*.js` happily and never learns the
+documented API is one call away (X0 flash-m70: 24 such reads in 57 s, no note on
+any of them). Carried as `distNote` rather than merged into `note` so a host that
+has read_molecule_doc (molecule-dev's cadence note, which also names the functions)
+can supersede it without string-matching.
+
+```typescript
+function moleculeDistReadNote(path: string): string | null
+```
+
+- `path` — The resolved path that was read.
+
+**Returns:** The note, or null when the path is not inside a package's `dist`.
+
 #### `buildTools(backend, config)`
 
 Build a complete set of AI agent tools bound to an execution backend.
@@ -1027,7 +1045,9 @@ const MAX_READ_RETURN_CHARS: number
 
 #### `SMALL_FILE_WHOLE_CHARS`
 
-A file this small is returned whole even when a window is asked for (paging it costs a call each).
+A file this small is returned whole on a second window of it (paging it costs a call each).
+The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
+file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
 
 ```typescript
 const SMALL_FILE_WHOLE_CHARS: number

package/dist/tools.d.ts

@@ -8,6 +8,19 @@
  */
 import type { AITool } from '@molecule/api-ai';
 import type { ExecutionBackend, ToolBuildConfig } from './types.js';
+/**
+ * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
+ * redirect below fires only when the read FAILS, so a model that knows the hoisted
+ * layout reads `node_modules/@molecule/<pkg>/dist/*.js` happily and never learns the
+ * documented API is one call away (X0 flash-m70: 24 such reads in 57 s, no note on
+ * any of them). Carried as `distNote` rather than merged into `note` so a host that
+ * has read_molecule_doc (molecule-dev's cadence note, which also names the functions)
+ * can supersede it without string-matching.
+ *
+ * @param path - The resolved path that was read.
+ * @returns The note, or null when the path is not inside a package's `dist`.
+ */
+export declare function moleculeDistReadNote(path: string): string | null;
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *

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;AA8B9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA6CnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAupDxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA0H9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA6CnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAutDxF"}

package/dist/tools.js

@@ -25,12 +25,118 @@ const waitedByTask = new Map();
 const logBytesByTask = new Map();
 /** The file a background command writes its own output to, when it redirects it. */
 const outputFileByTask = new Map();
+/**
+ * Task ids whose own-output file has already been looked for this process.
+ * {@link outputFileByTask} is empty for every task after a restart — it is
+ * process memory and the task is not — so without this the recovery below
+ * would re-read the task's script on every single wait.
+ */
+const outputFileProbed = new Set();
+/** A millisecond span the way a model reads it: seconds under 90, else minutes. */
+function durationText(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    const mins = Math.floor(s / 60);
+    return s < 90 ? `${s} s` : s % 60 ? `${mins} min ${s % 60} s` : `${mins} min`;
+}
+/**
+ * When a background command started, read from its own id: the handle is minted
+ * as `mol-bg-${Date.now().toString(36)}-…`, so the start stamp is in the id and
+ * no new state has to be kept to have it.
+ *
+ * @param taskId - The handle a run_in_background command returned.
+ * @returns Epoch ms, or null when the id carries no usable stamp (a hand-written
+ * or synthetic id) — a wrong number in a note is worse than none.
+ */
+function taskStartedAt(taskId) {
+    const stamp = Number.parseInt(taskId.split('-')[2] ?? '', 36);
+    const now = Date.now();
+    return Number.isFinite(stamp) && stamp > now - 24 * 3600_000 && stamp < now + 60_000
+        ? stamp
+        : null;
+}
+/**
+ * The progress a run reports in its own log: the last `[done/total]` counter a
+ * Playwright reporter writes (`[86/139] [chromium] › e2e/settings.spec.ts:…`).
+ *
+ * @param log - The log slice this wait read.
+ * @returns The counter, or null when the log carries none.
+ */
+function logProgress(log) {
+    const last = [...log.matchAll(/\[(\d+)\/(\d+)\]/g)].at(-1);
+    const done = Number(last?.[1]);
+    const total = Number(last?.[2]);
+    return last && total > 0 && done >= 0 && done <= total ? { done, total } : null;
+}
+/**
+ * What a wait knows about the command BESIDES "it has not exited": how long it
+ * has been running, whether its output is still growing, how far its own log
+ * says it has got, and how much longer that implies.
+ *
+ * X1 flash-m62 (2026-10-16) spent three 290 s waits on one 8.3-minute suite and
+ * every answer read only "Still running after 280s": the run could not tell a
+ * suite with 30 s left from one with 6 minutes left, so the wait cadence — not
+ * the suite — set the pace, and the run learned nothing for its 14 minutes of
+ * waiting. The elapsed time comes from the task id, the progress from the log
+ * this wait already read, and the time left is the rate so far, said as such.
+ *
+ * @param o - The wait's facts: `taskId`, the `slice` of the log it read,
+ *   `stillWriting` (the log grew during this wait), `bytes` (the log's size, null
+ *   when unreadable), and `ceilingMs` (this call's ceiling, for "one more wait").
+ * @returns A sentence to append to a running note, or '' when nothing is known.
+ */
+function waitProgressNote(o) {
+    const startedAt = taskStartedAt(o.taskId);
+    const elapsedMs = startedAt === null ? null : Math.max(0, Date.now() - startedAt);
+    const parts = [];
+    if (elapsedMs !== null)
+        parts.push(`it has been running ${durationText(elapsedMs)}`);
+    if (o.stillWriting)
+        parts.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
+    else if (o.bytes !== null)
+        parts.push(`its log has not grown during this wait (${o.bytes} bytes)`);
+    const counter = logProgress(o.slice);
+    if (counter) {
+        parts.push(`its log is at ${counter.done} of ${counter.total}`);
+        if (elapsedMs !== null && counter.done > 0 && counter.done < counter.total) {
+            const leftMs = Math.round((elapsedMs * (counter.total - counter.done)) / counter.done);
+            parts.push(leftMs <= o.ceilingMs
+                ? `about ${durationText(leftMs)} left at that rate — one more wait covers it`
+                : `about ${durationText(leftMs)} left at that rate (${Math.ceil(leftMs / o.ceilingMs)} more waits)`);
+        }
+    }
+    if (!parts.length)
+        return '';
+    const sentence = parts.join('; ');
+    return ` ${sentence[0].toUpperCase()}${sentence.slice(1)}.`;
+}
 import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, fusedLine, 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, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, redactSecrets, redactSecretsInCode, resolvePath, RUNNING_FAILURE_LINES, runningOutputSliceCommand, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * How long exec_command waits for a command it backgrounded only because the
  * command asked for more than the tool's ceiling, before handing back a task id.
  */
 const OVER_CEILING_GRACE_MS = 45_000;
+/**
+ * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
+ * redirect below fires only when the read FAILS, so a model that knows the hoisted
+ * layout reads `node_modules/@molecule/<pkg>/dist/*.js` happily and never learns the
+ * documented API is one call away (X0 flash-m70: 24 such reads in 57 s, no note on
+ * any of them). Carried as `distNote` rather than merged into `note` so a host that
+ * has read_molecule_doc (molecule-dev's cadence note, which also names the functions)
+ * can supersede it without string-matching.
+ *
+ * @param path - The resolved path that was read.
+ * @returns The note, or null when the path is not inside a package's `dist`.
+ */
+export function moleculeDistReadNote(path) {
+    const pkg = /node_modules\/@molecule\/([a-z0-9-]+)\/dist\//.exec(path)?.[1];
+    if (!pkg)
+        return null;
+    return (`This is @molecule/${pkg}'s compiled dist, not its API: read_molecule_doc("@molecule/${pkg}") ` +
+        'returns its README.md — the functions, options and bond wiring — in one call.' +
+        (/\.d\.ts$/.test(path)
+            ? ' The declarations above are generated from it.'
+            : ' For one signature, read the matching .d.ts file.'));
+}
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -135,6 +241,8 @@ export function buildTools(backend, config) {
     }
     /** Paths read with a window in this tool set, to tell paging from one targeted read. */
     const windowedReads = new Set();
+    /** The text each path was last handed back WHOLE as, so that correction fires once per version. */
+    const wholeReturned = new Map();
     /**
      * Verify that `path` does not symlink outside the project root when guards are enabled.
      *
@@ -365,6 +473,10 @@ export function buildTools(backend, config) {
         const symlinkErr = await checkSymlink(path);
         if (symlinkErr)
             return { error: symlinkErr };
+        // Carried on every successful read of a package's built output, so no dist read
+        // goes out unsteered (see moleculeDistReadNote).
+        const distNote = moleculeDistReadNote(path);
+        const noted = (r) => distNote ? { ...r, distNote } : r;
         try {
             const content = await backend.readFile(path);
             // A read that produced no usable text is verified against the file's real
@@ -376,12 +488,12 @@ export function buildTools(backend, config) {
                 const verdict = await classifyEmptyRead(path, 'read_file');
                 if ('error' in verdict)
                     return verdict;
-                return {
+                return noted({
                     path,
                     content: sanitizeFileContent(verdict.content, path),
                     ...(verdict.content === '' ? { empty: true } : {}),
                     ...(verdict.note ? { note: verdict.note } : {}),
-                };
+                });
             }
             if (content.length > MAX_READ_SIZE)
                 return {
@@ -395,21 +507,32 @@ export function buildTools(backend, config) {
                 : window;
             // A SECOND window of the same small file: hand back all of it (one window is a targeted read). X1 flash-m50 paged files that fit in one
             // call 13 times in a row, each window answered with "read it again with no offset/limit".
+            // The bound is the one that note states (SMALL_FILE_WHOLE_CHARS = MAX_READ_RETURN_CHARS): 24 KB left
+            // RealWorld's 24,935-byte openapi.yml paged nine times under "fits in ONE call" (flash-m67).
             const small = sliceLines(content, window);
             const pagedBefore = small?.truncated ? windowedReads.has(path) : false;
             if (small?.truncated)
                 windowedReads.add(path);
-            if (small?.truncated && pagedBefore && content.length <= SMALL_FILE_WHOLE_CHARS) {
-                return {
+            // Once per version of the file: after the whole text went back, a later window is a
+            // targeted read and gets its window (X1 flash-m67: 25 firings, 8 byte-identical repeats).
+            const sentWhole = wholeReturned.get(path) === content;
+            if (small?.truncated &&
+                pagedBefore &&
+                !sentWhole &&
+                content.length <= SMALL_FILE_WHOLE_CHARS) {
+                wholeReturned.set(path, content);
+                return noted({
                     path,
                     content: sanitizeFileContent(content, path),
+                    offset: 1,
+                    lines: small.totalLines,
                     totalLines: small.totalLines,
                     note: `The whole file is returned (${Math.round(content.length / 1024)} KB, ${small.totalLines} lines): a file this small fits in one call, so it is not paged.`,
-                };
+                });
             }
             const windowed = sliceLines(content, effectiveWindow);
             if (windowed) {
-                return {
+                return noted({
                     path,
                     content: sanitizeFileContent(windowed.text, path),
                     offset: windowed.offset,
@@ -422,18 +545,21 @@ export function buildTools(backend, config) {
                     // exact next window so the executor does not have to compute it.
                     ...(windowed.truncated
                         ? {
-                            note: content.length <= MAX_READ_RETURN_CHARS
-                                ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
-                                    `${windowed.totalLines}. The whole file is ${Math.round(content.length / 1024)} KB ` +
-                                    `and fits in ONE call — read it again with no offset/limit instead of paging.`
-                                : `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
-                                    `${windowed.totalLines}. Next window: offset ${windowed.offset + windowed.lines}, ` +
-                                    `limit ${windowed.lines}.`,
+                            note: sentWhole
+                                ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ${windowed.totalLines}; ` +
+                                    'the whole file, unchanged, was returned earlier in this conversation.'
+                                : content.length <= MAX_READ_RETURN_CHARS
+                                    ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
+                                        `${windowed.totalLines}. The whole file is ${Math.round(content.length / 1024)} KB ` +
+                                        `and fits in ONE call — read it again with no offset/limit instead of paging.`
+                                    : `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
+                                        `${windowed.totalLines}. Next window: offset ${windowed.offset + windowed.lines}, ` +
+                                        `limit ${windowed.lines}.`,
                         }
                         : {}),
-                };
+                });
             }
-            return { path, content: sanitizeFileContent(content, path) };
+            return noted({ path, content: sanitizeFileContent(content, path) });
         }
         catch (e) {
             // Backends (e.g. the docker provider's `cat`) already prefix "Failed to read <path>: ";
@@ -1366,6 +1492,33 @@ export function buildTools(backend, config) {
         // server-side costs no round trip and no context.
         async wait_for_task(input) {
             const taskId = typeof input.taskId === 'string' ? input.taskId.trim() : '';
+            // Where a task writes its own output is process memory; the task is not.
+            // An API process swapped mid-run (a release, a patch, a crash) leaves the
+            // command running in the sandbox with nothing left that remembers the file
+            // it redirects to — and then `wait_for_task` returns the task's near-empty
+            // log as the command's whole result, which is the X1 flash-m48 loss all
+            // over again (X1 flash-m63's +43:20 restart: the public walk's handle
+            // outlived the process, its redirect target did not). The script the task
+            // was started from is still on disk and carries the command, so read the
+            // target back from there. The id is format-checked before any /tmp path is
+            // built from it, exactly as the reads below are.
+            if (!outputFileByTask.has(taskId) &&
+                !outputFileProbed.has(taskId) &&
+                /^mol-bg-[a-z0-9]+-[a-z0-9]+$/.test(taskId)) {
+                outputFileProbed.add(taskId);
+                try {
+                    const target = outputRedirectTarget(await backend.readFile(`/tmp/${taskId}.sh`));
+                    // A relative target was written against the command's own cwd, which
+                    // the handle does not carry; the project root is where a background
+                    // command runs unless the caller passed one.
+                    if (target)
+                        outputFileByTask.set(taskId, target.startsWith('/') ? target : `${root}/${target}`);
+                }
+                catch (_error) {
+                    // No script under that id: this process did not start the task, so
+                    // there is nothing to recover. The log stays the whole result.
+                }
+            }
             // A command that has been waited on for stuckAfterMs() in total without
             // exiting is not going to: on one run the executor waited five times,
             // 120 s each, on an e2e suite that could never start (no browser page
@@ -1447,16 +1600,44 @@ export function buildTools(backend, config) {
                 const lastSize = logBytesByTask.get(taskId);
                 if (grownTo !== null)
                     logBytesByTask.set(taskId, grownTo);
+                // Evidence of liveness, read the same way by every answer below: a log
+                // that grew during THIS wait means the command is working. On the first
+                // wait any output at all counts (there is no earlier size to compare).
                 const stillWriting = grownTo !== null && (lastSize === undefined ? grownTo > 0 : grownTo > lastSize);
+                // The log's own slice, read ONCE for whichever answer follows: it is what
+                // the progress sentence is built from, and a wait that showed nothing was
+                // waited blind (X1 flash-m50: 4m42s across two waits on an 11-minute run).
+                // The slice leads with the failure lines, not the last bytes — a suite's
+                // tail is its progress lines (X1 flash-m61: the last 3 000 bytes of a
+                // 139-test walk were the skip list).
+                const own = outputFileByTask.get(taskId);
+                let soFar = '';
+                try {
+                    const r = await backend.run(runningOutputSliceCommand(log, own), { timeout: 5_000 });
+                    soFar = r.stdout ?? '';
+                }
+                catch (_error) {
+                    // No slice: the notes still say how to peek, and the task id still
+                    // carries how long the command has been running.
+                }
+                const progress = waitProgressNote({
+                    taskId,
+                    slice: soFar,
+                    stillWriting,
+                    bytes: grownTo,
+                    ceilingMs: ceiling,
+                });
+                const sliceField = soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {};
                 if (stillWriting && waitedBefore + waitedMs >= stuckAfterMs()) {
                     waitedByTask.set(taskId, 0);
                     return {
                         taskId,
                         status: 'running',
                         waitedMs,
+                        ...sliceField,
                         note: `Still running after ${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting, and its ` +
-                            `output is still growing (${grownTo} bytes) — slow, not stuck. Call wait_for_task again to ` +
-                            `keep waiting; peek with exec_command: tail ${log}.`,
+                            `output is still growing (${grownTo} bytes) — slow, not stuck.${progress} Call wait_for_task ` +
+                            `again to keep waiting; peek with exec_command: tail ${log}.`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -1470,26 +1651,12 @@ export function buildTools(backend, config) {
                             `kill $(cat /tmp/${taskId}.pid) 2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
                     };
                 }
-                // The output so far rides the result: a wait that shows nothing was waited blind
-                // (X1 flash-m50: 4m42s across two waits on an 11-minute run). The slice leads with the
-                // failure lines, not the last bytes — a suite's tail is its progress lines
-                // (X1 flash-m61: the last 3 000 bytes of a 139-test walk were the skip list).
-                const own = outputFileByTask.get(taskId);
-                let soFar;
-                try {
-                    const r = await backend.run(runningOutputSliceCommand(log, own), { timeout: 5_000 });
-                    soFar = r.stdout ?? '';
-                }
-                catch (_error) {
-                    // No slice: the note still says how to peek.
-                    soFar = '';
-                }
                 return {
                     taskId,
                     status: 'running',
                     waitedMs,
-                    ...(soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {}),
-                    note: `Still running after ${Math.round(waitedMs / 1000)}s. Call wait_for_task again to ` +
+                    ...sliceField,
+                    note: `Still running after ${Math.round(waitedMs / 1000)}s.${progress} Call wait_for_task again to ` +
                         `keep waiting — its result carries the log output. ` +
                         (soFar.trim()
                             ? `outputSoFar is the failure lines so far (up to ${RUNNING_FAILURE_LINES}) and then the end of ` +

package/dist/utilities.d.ts

@@ -267,7 +267,11 @@ export declare const MAX_BATCH_READ_BYTES: number;
  * needs.
  */
 export declare const MAX_READ_RETURN_CHARS: number;
-/** A file this small is returned whole even when a window is asked for (paging it costs a call each). */
+/**
+ * A file this small is returned whole on a second window of it (paging it costs a call each).
+ * The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
+ * file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
+ */
 export declare const SMALL_FILE_WHOLE_CHARS: number;
 /** Max search results. */
 export declare const MAX_SEARCH_RESULTS = 50;

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

@@ -345,6 +345,15 @@ export function streamingBackgroundCommand(command) {
         changes.push('Added `--reporter=list` so each test result is written to the log as it finishes ' +
             '(the config reporter may print nothing until the end).');
     }
+    // A diagnosis or a re-run (capped, last-failed, grepped, or named files) walks each failure
+    // once: the suite's own `retries` doubled every failure of X1 flash-m71's first whole run,
+    // which had dropped the `--retries=0` it used one command earlier. The uncapped proof run
+    // keeps the suite's retries.
+    const iterating = /--max-failures\b|--last-failed\b|(?:^|\s)(?:-g|--grep)\b|\S+\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+)?\b/.test(lastStep);
+    if (finalPlaywrightRun && iterating && !/--retries\b/.test(lastStep)) {
+        out = `${out.trimEnd()} --retries=0`;
+        changes.push('Added `--retries=0`: a diagnosis or re-run walks each failure once; keep the suite’s retries for the proof run.');
+    }
     return { command: out, changes };
 }
 // ── Command blocking ──────────────────────────────────────────────────────────
@@ -577,8 +586,12 @@ export const MAX_BATCH_READ_BYTES = 200 * 1024;
  * needs.
  */
 export const MAX_READ_RETURN_CHARS = 80 * 1024;
-/** A file this small is returned whole even when a window is asked for (paging it costs a call each). */
-export const SMALL_FILE_WHOLE_CHARS = 24 * 1024;
+/**
+ * A file this small is returned whole on a second window of it (paging it costs a call each).
+ * The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
+ * file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
+ */
+export const SMALL_FILE_WHOLE_CHARS = MAX_READ_RETURN_CHARS;
 /** Max search results. */
 export const MAX_SEARCH_RESULTS = 50;
 /** Max find results. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.5.16",
+  "version": "1.5.18",
   "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.3.0",
+    "@molecule/api-ai": "1.3.1",
     "@types/node": "26.1.2",
     "esbuild": "0.28.2",
     "typescript": "6.0.3",