@molecule/api-ai-tools 1.8.2 → 1.8.3

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -137,6 +137,7 @@ export * from './cut-run.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/sleep-peek.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A leading `sleep` in an executor's command: the seconds it would have waited, and the command
+ * that follows it.
+ *
+ * X1 xr-molecule-flash-m105 (+08:49 → +10:53, 2026-10-17) spent 225 s of its 60-minute clock
+ * inside `exec_command` calls of the shape `sleep N; tail <task log>`. The platform's own launch
+ * note said "peek with exec_command: tail <log>" beside "never sleep", and the only concrete
+ * instruction was the peek, so the executor built the poll by hand. Two of its three sleeps were
+ * provably dead — the task had ended 0.1 s in (`playwright: not found`, exit 127) and another had
+ * already printed `Error: No tests found` — and the third spent 120 s asleep beside a live
+ * 139-test run whose failures were already in the log.
+ *
+ * The platform does not have to answer "what is the task doing" from a sleep: `wait_for_task`
+ * already returns the moment the task ends, early on a proven repeating cause, and with the
+ * progress and failures the log holds. This module answers only the parsing question — is the
+ * command's FIRST statement a `sleep` of {@link MIN_PEEK_SLEEP_SECONDS} seconds or more, and what
+ * follows it — from the package's own shell parse ({@link locatedCommandSegments}), so a `sleep`
+ * named in an argument (`grep -n 'sleep 60' notes.md`) or written after another statement
+ * (`cd x && sleep 60`) is not one.
+ *
+ * @module
+ */
+/**
+ * The shortest leading sleep the platform drops: below it the wall clock it costs is noise, and a
+ * short settle (`sleep 2; curl …`) is a legitimate thing to run.
+ */
+export declare const MIN_PEEK_SLEEP_SECONDS = 5;
+/** The leading `sleep` a command opens with, and the command that follows it. */
+export interface LeadingSleep {
+    /** How many seconds the statement would have slept (GNU sleep sums its operands). */
+    seconds: number;
+    /** What follows the leading statement, trimmed — '' when the sleep was the whole command. */
+    rest: string;
+}
+/**
+ * The leading `sleep` of a command, when the first statement is one and it asks for at least
+ * {@link MIN_PEEK_SLEEP_SECONDS}.
+ *
+ * The statement is read by {@link locatedCommandSegments} — the same parse every other command
+ * classifier uses — so only a `sleep` in command position of the FIRST statement counts. The end
+ * of that statement is then found by walking forward from its own start: the statement is
+ * `sleep <duration>`, whose words carry no quotes and open no substitution, so the first unquoted
+ * `;`, newline or `&` ends it. A `|` is refused: dropping the left side of a pipeline would hand
+ * the right side its stdin instead, and a `||` fallback would run on a success that never did.
+ *
+ * @param command - The shell command the executor sent.
+ * @returns The seconds and the remaining command, or null when the command does not open with a
+ *   long `sleep`.
+ */
+export declare function leadingSleepPeek(command: string): LeadingSleep | null;
+//# sourceMappingURL=sleep-peek.d.ts.map

package/dist/sleep-peek.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-peek.d.ts","sourceRoot":"","sources":["../src/sleep-peek.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAA;IACf,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAyBrE"}

package/dist/sleep-peek.js

@@ -0,0 +1,76 @@
+/**
+ * A leading `sleep` in an executor's command: the seconds it would have waited, and the command
+ * that follows it.
+ *
+ * X1 xr-molecule-flash-m105 (+08:49 → +10:53, 2026-10-17) spent 225 s of its 60-minute clock
+ * inside `exec_command` calls of the shape `sleep N; tail <task log>`. The platform's own launch
+ * note said "peek with exec_command: tail <log>" beside "never sleep", and the only concrete
+ * instruction was the peek, so the executor built the poll by hand. Two of its three sleeps were
+ * provably dead — the task had ended 0.1 s in (`playwright: not found`, exit 127) and another had
+ * already printed `Error: No tests found` — and the third spent 120 s asleep beside a live
+ * 139-test run whose failures were already in the log.
+ *
+ * The platform does not have to answer "what is the task doing" from a sleep: `wait_for_task`
+ * already returns the moment the task ends, early on a proven repeating cause, and with the
+ * progress and failures the log holds. This module answers only the parsing question — is the
+ * command's FIRST statement a `sleep` of {@link MIN_PEEK_SLEEP_SECONDS} seconds or more, and what
+ * follows it — from the package's own shell parse ({@link locatedCommandSegments}), so a `sleep`
+ * named in an argument (`grep -n 'sleep 60' notes.md`) or written after another statement
+ * (`cd x && sleep 60`) is not one.
+ *
+ * @module
+ */
+import { durationSeconds, locatedCommandSegments } from './command-position.js';
+/**
+ * The shortest leading sleep the platform drops: below it the wall clock it costs is noise, and a
+ * short settle (`sleep 2; curl …`) is a legitimate thing to run.
+ */
+export const MIN_PEEK_SLEEP_SECONDS = 5;
+/**
+ * The leading `sleep` of a command, when the first statement is one and it asks for at least
+ * {@link MIN_PEEK_SLEEP_SECONDS}.
+ *
+ * The statement is read by {@link locatedCommandSegments} — the same parse every other command
+ * classifier uses — so only a `sleep` in command position of the FIRST statement counts. The end
+ * of that statement is then found by walking forward from its own start: the statement is
+ * `sleep <duration>`, whose words carry no quotes and open no substitution, so the first unquoted
+ * `;`, newline or `&` ends it. A `|` is refused: dropping the left side of a pipeline would hand
+ * the right side its stdin instead, and a `||` fallback would run on a success that never did.
+ *
+ * @param command - The shell command the executor sent.
+ * @returns The seconds and the remaining command, or null when the command does not open with a
+ *   long `sleep`.
+ */
+export function leadingSleepPeek(command) {
+    if (typeof command !== 'string')
+        return null;
+    const first = locatedCommandSegments(command)[0];
+    if (!first || first.start === null || first.segment === null)
+        return null;
+    if (first.segment.program !== 'sleep')
+        return null;
+    // GNU sleep sums its operands (`sleep 45 15`); every one of them has to be a duration.
+    let seconds = 0;
+    for (const arg of first.segment.args) {
+        const part = durationSeconds(arg);
+        if (part === null)
+            return null;
+        seconds += part;
+    }
+    if (seconds < MIN_PEEK_SLEEP_SECONDS)
+        return null;
+    let end = command.length;
+    for (let i = first.start; i < command.length; i++) {
+        const char = command[i] ?? '';
+        if (char === '|')
+            return null;
+        if (char === ';' || char === '\n' || char === '&') {
+            end = i;
+            break;
+        }
+    }
+    let at = end;
+    while (at < command.length && /[;&\s]/.test(command[at] ?? ''))
+        at += 1;
+    return { seconds, rest: command.slice(at).trim() };
+}

package/dist/tools.d.ts

@@ -60,8 +60,47 @@ export declare const SUITE_OVER_BUDGET_ADVICE: string;
  */
 export declare function moleculeDistReadNote(path: string): string | null;
 /**
- * The refusal for a write whose target is inside an installed package, or null
- * when the path is not under a `node_modules` directory.
+ * What the filesystem says about a write target under `node_modules` — the half
+ * of the decision a path's spelling cannot make.
+ *
+ * @remarks
+ * A path that reads `node_modules` is not necessarily an install: a run links
+ * `node_modules` beside its e2e copy to borrow the hoisted tree, and that link
+ * is its own. X0 xr-molecule-flash-m106 (+07:58) made exactly that link, found
+ * it dangling (everything was hoisted to `/workspace/node_modules`), and was
+ * refused three times for trying to remove it — 40 s and a "3rd time this turn
+ * … ask the user" escalation, in an unattended run, over a broken symlink in
+ * the run's own scratch directory. So the guard asks what is there.
+ */
+export interface InstalledPackageFacts {
+    /** Whether the `node_modules` entry the path goes through is a symbolic link. */
+    readonly symlink: boolean;
+    /** Whether a package is really installed there: a `package.json` resolves under the entry. */
+    readonly installed: boolean;
+}
+/**
+ * Looks at the filesystem for {@link InstalledPackageFacts}.
+ *
+ * The guard cannot `stat` the path itself: the tools act through a backend (a
+ * sandbox over the network for the fleet), so the caller — which holds that
+ * backend — supplies the look. {@link shellInstalledPackageProbe} builds one
+ * from any shell runner.
+ */
+export type InstalledPackageProbe = (path: string) => Promise<InstalledPackageFacts>;
+/**
+ * Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+ * `run`, or a sandbox's `exec`): one command reports whether the entry is a
+ * link and whether a `package.json` resolves under it.
+ *
+ * @param run - Runs a command where the path lives.
+ * @returns The probe.
+ */
+export declare function shellInstalledPackageProbe(run: (command: string) => Promise<{
+    stdout?: string;
+} | null | undefined>): InstalledPackageProbe;
+/**
+ * The refusal for a write whose target is inside an INSTALLED package, or null
+ * when the path is not under `node_modules` or nothing is installed there.
  *
  * `node_modules` is not the project's code: nothing written there survives the
  * next install, no deploy carries it, and a sandbox whose dependency tree is
@@ -74,6 +113,19 @@ export declare function moleculeDistReadNote(path: string): string | null;
  * putting the file back. Reading these files stays allowed (that is how the
  * declarations above are read at all).
  *
+ * What is protected is the INSTALL, not the spelling: the decision comes from
+ * {@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+ * things are the run's own to remove or replace —
+ *
+ * - a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+ *   tree it points at, so a link the run made cannot clobber anything;
+ * - anything under the run's own `.mol-scratch/` directory;
+ * - a `node_modules` with no `package.json` under it (nothing was ever installed).
+ *
+ * A path INSIDE the link is still decided by what resolves there: a link into a
+ * real tree is refused, because removing or writing through it reaches the
+ * install.
+ *
  * The restore route is named because the model that has ALREADY clobbered a file
  * (this refusal is too late for it) is the one who needs it, and because the
  * obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
@@ -81,9 +133,10 @@ export declare function moleculeDistReadNote(path: string): string | null;
  * m91 used, and what both guards leave alone.
  *
  * @param path - An absolute path a tool is about to write.
+ * @param probe - Looks at the filesystem where the path lives.
  * @returns The one-line refusal naming the package, or null when nothing is installed there.
  */
-export declare function installedPackageWriteRefusal(path: string): string | null;
+export declare function installedPackageWriteRefusal(path: string, probe?: InstalledPackageProbe): Promise<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;AA0G9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAyHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAkEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsBxE;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAyzExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAgJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAiOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAu2ExF"}