@molecule/api-ai-tools 1.10.6 → 1.10.7

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-19T13:08:52.848Z
+Generated: 2026-10-19T22:30:20.727Z
 -->
 
 # @molecule/api-ai-tools
@@ -58,6 +58,28 @@ npm install @molecule/api-ai-tools @molecule/api-ai
 
 ### Interfaces
 
+#### `BrowserProbeLeak`
+
+A browser launch bound to a variable, proven to have no cleanup path.
+
+```typescript
+interface BrowserProbeLeak {
+  /** The variable the launched browser is bound to (`browser` in the m257 probe). */
+  readonly variable: string
+}
+```
+
+#### `ForegroundBrowserProbe`
+
+A foreground command that directly executes such a script.
+
+```typescript
+interface ForegroundBrowserProbe extends BrowserProbeLeak {
+  /** The script file as the command named it. */
+  readonly script: string
+}
+```
+
 #### `CommandSegment`
 
 One statement or pipeline stage of a shell command: what it runs, and with what.
@@ -222,6 +244,13 @@ interface CutRun {
    * is slow, so the sentence must not send it to the background (xr-molecule-flash-m200 +03:45).
    */
   inlineScript?: string | null
+  /**
+   * The variable a leaked standalone browser launch is bound to, when the command ran such a probe
+   * and the cut reader could only classify it after the run (xr-molecule-flash-m257). A leaked
+   * handle is not a slow workload: the background is the one place it must not be sent, so the
+   * sentence names the close instead.
+   */
+  browserProbe?: string | null
 }
 ```
 
@@ -1469,6 +1498,58 @@ function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): Execu
 
 **Returns:** A backend that proxies all filesystem calls into the sandbox.
 
+#### `standaloneBrowserLeak(source)`
+
+The browser variable a standalone script launches and never closes, when that can be proven from
+the source alone.
+
+The proof is a closed world: one plain TOP-LEVEL launch binding whose engine is genuinely
+Playwright's, every reference to it a known non-closing method call, and no cleanup, escape or
+persistent-process path anywhere in the source. A source with two launches is read one binding
+at a time — a proven leak in either one is enough, because that handle alone keeps Node alive.
+
+```typescript
+function standaloneBrowserLeak(source: string): BrowserProbeLeak | null
+```
+
+- `source` — The script's source, as read from disk.
+
+**Returns:** The leaking binding, or null when the script is clean or ambiguous.
+
+#### `browserProbeRefusal(probe, budgetSeconds, piped)`
+
+The refusal for a foreground command that would run a leaking browser probe: it never returns,
+and the one move that makes it return is closing the browser (or letting the Playwright runner
+own it), never moving the leak to the background.
+
+```typescript
+function browserProbeRefusal(
+  probe: ForegroundBrowserProbe,
+  budgetSeconds: number,
+  piped?: boolean,
+): string
+```
+
+- `probe` — The leaked probe, from `foregroundBrowserProbe`.
+- `budgetSeconds` — The tool's budget, which the probe would consume whole.
+- `piped` — Whether the command pipes through `tail`/`head`, which withholds the probe's output.
+
+**Returns:** The refusal sentence.
+
+#### `browserProbeOverBudgetAdvice(probe)`
+
+The over-budget advice for a leak discovered at cut time (the preflight could not read the script
+before the run — e.g. the same command wrote it). It names the lifecycle fix and says explicitly
+that the background is not one: a leaked handle hangs there too.
+
+```typescript
+function browserProbeOverBudgetAdvice(probe: ForegroundBrowserProbe): string
+```
+
+- `probe` — The leaked probe.
+
+**Returns:** The sentence the cut result carries.
+
 #### `durationSeconds(word)`
 
 The seconds a duration word stands for.
@@ -1790,7 +1871,12 @@ function allConnectionFailures(failures: readonly (RunFailureClass | null)[]): b
 The interpreter of an INLINE program that only reads and writes local files — the shape that gets
 {@link INLINE_SCRIPT_BUDGET_MS} instead of the tool's command budget.
 
-An inline program with any external effect keeps the full budget: no network, install, test
+EVERY statement of the command must be proven local, not just one of them: each is either an
+inline interpreter program or a plain file utility ({@link LOCAL_UTILITY}). A statement that runs
+a script FILE (`node smoke.mjs`, `python3 x.py`, `bash x.sh`) or names a program this module does
+not know can do anything at all, so the command keeps the full budget.
+
+An inline program with any external effect keeps the full budget too: no network, install, test
 runner, build or server verb may appear anywhere in the command ({@link EXTERNAL_EFFECT}), and
 the command must not be a suite run or a foreground server (the platform's own classifiers).
 
@@ -2033,6 +2119,29 @@ function foregroundServerCommand(
 
 **Returns:** The serving program, or null when the command starts no server in the foreground.
 
+#### `foregroundBrowserProbe(command, readScript)`
+
+A FOREGROUND command that directly runs a standalone script which launches a browser and never
+closes it — the same never-returns lifecycle class as {@link foregroundServerCommand}, read from
+the script's SOURCE by {@link standaloneBrowserLeak}.
+
+The boundaries are the server preflight's, so the two readers cannot disagree about what they are
+allowed to touch: a backgrounded launch, a test runner and a test file are left alone, and a
+script the backend will not answer for is a command this reading cannot classify, never a
+refusal. A Playwright suite is owned by its runner's browser fixture and is never read here.
+
+```typescript
+function foregroundBrowserProbe(
+  command: string,
+  readScript: (path: string) => Promise<string>,
+): Promise<ForegroundBrowserProbe | null>
+```
+
+- `command` — The command as the executor sent it.
+- `readScript` — Reads a script file the command names (`backend.readFile`).
+
+**Returns:** The leaked probe's variable and script path, or null when the command is not one.
+
 #### `serverCommandRefusal(server, budgetSeconds)`
 
 The refusal for a foreground command that starts a server: why it would never return, and the

package/dist/browser-probe.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A standalone Playwright probe that launches a browser and never closes it — the
+ * resource-lifecycle hang `exec_command` did not yet classify.
+ *
+ * X1 xr-molecule-flash-m257 (+10:44 → +15:34) ran
+ * `cd /workspace/my-app/app && node /workspace/.mol-scratch/fav-probe.mjs 2>&1 | tail -5`. The
+ * 30-line script binds `const browser = await chromium.launch()`, walks a real page, reaches its
+ * last `console.log`, and ends without `browser.close()`, `disconnect()`, a disposal scope or
+ * `process.exit()`. Chromium is a live handle, so Node never exits: the tool waited its whole 290 s
+ * budget, returned `status: cut_at_budget` with empty stdout (the `| tail` held it), and then
+ * advised "run it in the background" — advice for a slow workload, not for a leaked handle.
+ *
+ * That is the same lifecycle class {@link foregroundServerCommand} already refuses: a foreground
+ * process that never returns. So the same preflight seam reads it, with a deliberately narrow
+ * closed-world proof:
+ *
+ * - the script is DIRECTLY executed (`node`/`tsx`/`bun`/`deno` naming a script file, never a
+ *   test-runner invocation or a test/fixture file — those are the runner's business);
+ * - the source, with comments and string/template/regex literals blanked, binds a browser by a
+ *   TOP-LEVEL (brace depth 0) `const|let|var <x> = await chromium|firefox|webkit.launch(`
+ *   assignment, where the engine (or its namespace) is imported/required from `playwright`,
+ *   `playwright-core` or `@playwright/test` — a locally bound stub is not Playwright;
+ * - every reference to `<x>` is a known browser method that does NOT close it (`newPage`,
+ *   `newContext`, `on`, `version`, …), and the binding is never aliased, passed to a helper, or
+ *   read as a property;
+ * - nothing in the source is a cleanup path (any `.close(`/`.disconnect(`/`.dispose(`, a `using`
+ *   scope, a cleanup-named import), an escape (`process.exit`, `eval`, `new Function`, dynamic
+ *   `import`), or a persistent-process intent (`launchServer`, `connect`, a server `.listen`, a
+ *   timer or signal handler).
+ *
+ * Anything ambiguous is left alone. A wrong refusal costs a valid probe — the review that found
+ * the m257 leak also proved five harmless scripts a raw substring match would refuse (a local
+ * engine stub, the launch text in a string, in a comment, in a template literal, and inside a
+ * function that is never called) — and a missed leak costs the same budget the tool already had.
+ * This is a lifecycle diagnostic, never an egress or security gate.
+ *
+ * @module
+ */
+/** A browser launch bound to a variable, proven to have no cleanup path. */
+export interface BrowserProbeLeak {
+    /** The variable the launched browser is bound to (`browser` in the m257 probe). */
+    readonly variable: string;
+}
+/** A foreground command that directly executes such a script. */
+export interface ForegroundBrowserProbe extends BrowserProbeLeak {
+    /** The script file as the command named it. */
+    readonly script: string;
+}
+/**
+ * The browser variable a standalone script launches and never closes, when that can be proven from
+ * the source alone.
+ *
+ * The proof is a closed world: one plain TOP-LEVEL launch binding whose engine is genuinely
+ * Playwright's, every reference to it a known non-closing method call, and no cleanup, escape or
+ * persistent-process path anywhere in the source. A source with two launches is read one binding
+ * at a time — a proven leak in either one is enough, because that handle alone keeps Node alive.
+ *
+ * @param source - The script's source, as read from disk.
+ * @returns The leaking binding, or null when the script is clean or ambiguous.
+ */
+export declare function standaloneBrowserLeak(source: string): BrowserProbeLeak | null;
+/**
+ * The refusal for a foreground command that would run a leaking browser probe: it never returns,
+ * and the one move that makes it return is closing the browser (or letting the Playwright runner
+ * own it), never moving the leak to the background.
+ *
+ * @param probe - The leaked probe, from `foregroundBrowserProbe`.
+ * @param budgetSeconds - The tool's budget, which the probe would consume whole.
+ * @param piped - Whether the command pipes through `tail`/`head`, which withholds the probe's output.
+ * @returns The refusal sentence.
+ */
+export declare function browserProbeRefusal(probe: ForegroundBrowserProbe, budgetSeconds: number, piped?: boolean): string;
+/**
+ * The over-budget advice for a leak discovered at cut time (the preflight could not read the script
+ * before the run — e.g. the same command wrote it). It names the lifecycle fix and says explicitly
+ * that the background is not one: a leaked handle hangs there too.
+ *
+ * @param probe - The leaked probe.
+ * @returns The sentence the cut result carries.
+ */
+export declare function browserProbeOverBudgetAdvice(probe: ForegroundBrowserProbe): string;
+//# sourceMappingURL=browser-probe.d.ts.map

package/dist/browser-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-probe.d.ts","sourceRoot":"","sources":["../src/browser-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,iEAAiE;AACjE,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AA6aD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAyB7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,sBAAsB,EAC7B,aAAa,EAAE,MAAM,EACrB,KAAK,UAAQ,GACZ,MAAM,CAaR;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CASlF"}