@molecule/api-ai-tools 1.6.5 → 1.7.0

package/dist/command-position.d.ts

@@ -37,7 +37,19 @@ export interface CommandSegment {
     args: readonly string[];
     /** The program and its arguments as one line — what a runner pattern is matched against. */
     text: string;
+    /**
+     * The seconds the segment's own `timeout` wrapper allows the command it runs
+     * (`timeout 280 hurl --test …` → 280), or null when it carries none.
+     */
+    timeoutSeconds: number | null;
 }
+/**
+ * The seconds a duration word stands for.
+ *
+ * @param word - A duration (`280`, `20s`, `1m`).
+ * @returns The seconds, or null when the word is not a duration.
+ */
+export declare function durationSeconds(word: string): number | null;
 /**
  * The segments of a command, each with its program and arguments — the answer every classifier
  * that reads a command as "this runs the suite" is asking for.
@@ -46,6 +58,20 @@ export interface CommandSegment {
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/**
+ * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
+ * under (`timeout 280 hurl --test …` → 280), or null when it carries none.
+ *
+ * This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
+ * finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
+ * other command reader uses, rather than matched as text: `timeout` in an argument
+ * (`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
+ * the bound ({@link WRAPPER_VALUE_FLAGS}).
+ *
+ * @param command - The shell command.
+ * @returns The seconds the command allows itself, or null.
+ */
+export declare function commandTimeoutSeconds(command: string): number | null;
 /**
  * Whether any segment of the command runs a program whose command-position text matches
  * `pattern` — the one question a runner-kind table asks.

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;CACb;AA8TD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAmFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAyPD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -92,6 +92,22 @@ const WRAPPER_VALUE_FLAGS = {
 const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 /** A wrapper's own duration — `timeout 280 …`, `timeout 1m …` — which is not a flag. */
 const DURATION = /^\d+(?:\.\d+)?[smhd]?$/;
+/** The seconds a `timeout` duration word names (`280`, `1m`, `1.5h`), or null when it is none. */
+const DURATION_UNITS = { s: 1, m: 60, h: 3600, d: 86_400 };
+/**
+ * The seconds a duration word stands for.
+ *
+ * @param word - A duration (`280`, `20s`, `1m`).
+ * @returns The seconds, or null when the word is not a duration.
+ */
+export function durationSeconds(word) {
+    if (!DURATION.test(word))
+        return null;
+    const [, number = '', unit = 's'] = /^(\d+(?:\.\d+)?)([smhd]?)$/.exec(word) ?? [];
+    const scale = DURATION_UNITS[unit] ?? 1;
+    const seconds = Number(number) * scale;
+    return Number.isFinite(seconds) ? seconds : null;
+}
 /**
  * A word without its shell quotes.
  *
@@ -155,14 +171,16 @@ function nestedCommand(words, from) {
     return null;
 }
 /**
- * Where the program starts in one segment's words.
+ * Where the program starts in one segment's words, and the bound the segment puts on itself.
  *
  * @param words - The segment's words, quotes kept.
  * @returns The index of the word in command position (one past the end when the segment runs
- *   nothing), and the command string of a `sh -c '<command>'` this segment turns out to be.
+ *   nothing), the command string of a `sh -c '<command>'` this segment turns out to be, and the
+ *   seconds its own `timeout` wrapper allows that command (`timeout 280 hurl …` → 280) or null.
  */
 function commandStart(words) {
     let at = 0;
+    let timeoutSeconds = null;
     for (let guard = 0; guard < MAX_WRAPPERS && at < words.length; guard++) {
         const word = words[at] ?? '';
         if (ENV_ASSIGNMENT.test(word)) {
@@ -178,7 +196,7 @@ function commandStart(words) {
         if (SHELLS.has(name)) {
             const nested = nestedCommand(words, at + 1);
             if (nested !== null)
-                return { at, nested };
+                return { at, nested, timeoutSeconds };
             at += 1 + flagWords(words, at + 1, name);
             continue;
         }
@@ -192,12 +210,14 @@ function commandStart(words) {
             continue;
         }
         if (!LAUNCHERS.has(name))
-            return { at, nested: null };
+            return { at, nested: null, timeoutSeconds };
         at += 1 + flagWords(words, at + 1, name);
-        if (name === 'timeout' && DURATION.test(words[at] ?? ''))
+        if (name === 'timeout' && DURATION.test(words[at] ?? '')) {
+            timeoutSeconds = durationSeconds(words[at] ?? '');
             at += 1;
+        }
     }
-    return { at, nested: null };
+    return { at, nested: null, timeoutSeconds };
 }
 /**
  * A command's statements and pipeline stages, split where the shell splits them — inside quotes
@@ -335,6 +355,28 @@ function segmentWords(text) {
 export function commandSegments(command) {
     return segmentsOf(command, 0);
 }
+/**
+ * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
+ * under (`timeout 280 hurl --test …` → 280), or null when it carries none.
+ *
+ * This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
+ * finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
+ * other command reader uses, rather than matched as text: `timeout` in an argument
+ * (`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
+ * the bound ({@link WRAPPER_VALUE_FLAGS}).
+ *
+ * @param command - The shell command.
+ * @returns The seconds the command allows itself, or null.
+ */
+export function commandTimeoutSeconds(command) {
+    let bound = null;
+    for (const segment of segmentsOf(command, 0)) {
+        if (segment.timeoutSeconds === null)
+            continue;
+        bound = bound === null ? segment.timeoutSeconds : Math.max(bound, segment.timeoutSeconds);
+    }
+    return bound;
+}
 /**
  * {@link commandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
  * {@link MAX_NESTING} allows.
@@ -362,7 +404,12 @@ function segmentsOf(command, depth) {
             continue;
         const program = programName(word);
         const args = words.slice(start.at + 1);
-        out.push({ program, args, text: [program, ...args].join(' ') });
+        out.push({
+            program,
+            args,
+            text: [program, ...args].join(' '),
+            timeoutSeconds: start.timeoutSeconds,
+        });
     }
     return out;
 }

package/dist/cut-run.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A command that a budget stopped before it finished, and the state its result carries so no
+ * reader can mistake it for a run that ended.
+ *
+ * X1 xr-molecule-flash-m93 (2026-10-16, +12:37) sent the supplied RealWorld suite as
+ * `timeout 280 hurl --test --continue-on-error --jobs 1 … hurl/*.hurl 2>&1 | tail -60` and got
+ * back `exitCode: 0`, four finished files' lines and nothing else. Two lies in one result: the
+ * `timeout 280` killed the run at 280 s, and the `| tail` made the pipeline's status the status —
+ * so the executor read a suite that stopped at its fifth file as a suite that ran and nearly
+ * passed, fixed one message, and immediately sent the same 280-second command again (the run's
+ * third, ~14 minutes of a 60-minute cap across three of them).
+ *
+ * So the tool never reports a stopped run as `exitCode: 0`. Such a result carries
+ * `status: 'cut_at_budget'` and an exit code that is `null` whenever the number the pipeline
+ * reported belongs to the filter rather than to the run, and every reader of a run's verdict reads
+ * the state through {@link commandRunState} — a cut run is NOT RUN, never a pass.
+ *
+ * Two things stop a run, and both are read from the command and the result, never inferred:
+ *
+ * 1. **Its own bound** — a `timeout <N>` the command carries ({@link commandTimeoutSeconds}). The
+ *    run used it, so the run was killed at it; with no closing tally in the output, the run did
+ *    not finish. This is m93's shape.
+ * 2. **This tool's budget** — the backend runs the command under `timeout` (see
+ *    `backends/sandbox.ts`), which reports 124 whatever the pipeline did, and returns everything
+ *    printed until then. The budget is the tool's own, so its number belongs to the tool.
+ *
+ * @module
+ */
+/**
+ * The state a result carries when a budget stopped its command: a run that did not finish is not a
+ * run that passed, and no reader may treat it as one.
+ */
+export declare const CUT_AT_BUDGET = "cut_at_budget";
+/** What a command's result records: a run that ended, or one a budget stopped. */
+export type CommandRunState = 'ran' | typeof CUT_AT_BUDGET;
+/**
+ * The state a command's result records — THE reader every verdict about a run goes through.
+ *
+ * A result that carries no state is a run that ended: the state is written where the run is
+ * stopped ({@link commandCutRun}), so a result without it was never stopped by a budget this
+ * platform set or can see. Results produced before this state existed read the same way, which is
+ * what keeps a past turn's tally readable.
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The state the result records.
+ */
+export declare function commandRunState(result: unknown): CommandRunState;
+/**
+ * Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+ *
+ * @param text - The run's stdout and stderr.
+ * @returns True when the runner's own end-of-run summary is there.
+ */
+export declare function suiteTally(text: string): boolean;
+/** What stopped a run. */
+export type CutBy = 'tool-budget' | 'command-timeout';
+/** A run a budget stopped, as its result reports it. */
+export interface CutRun {
+    /** The bound the run was allowed, in seconds. */
+    seconds: number;
+    /** Whether this tool's budget stopped it or the `timeout` the command carried. */
+    stoppedBy: CutBy;
+    /**
+     * The exit code the run's own process reported, or null when the code in the result belongs to
+     * the pipeline's filter (`… | tail`) rather than to the run — the case that read as success.
+     */
+    exitCode: number | null;
+    /** How many files or tests the runner's own output shows finishing, or null when it shows none. */
+    ran: number | null;
+    /** How many the run was walking, when the runner printed it (Playwright's `[n/K]`), or null. */
+    total: number | null;
+    /** The noun the runner counts in. */
+    noun: 'files' | 'tests';
+    /** The last thing the run printed — the line a reader looks at first. */
+    doing: string | null;
+}
+/**
+ * The run a command's result records as stopped by a budget, or null when the result is a run that
+ * ended (or says nothing about a run).
+ *
+ * Evidence, in order — never a guess:
+ *
+ * - `timeout`'s own 124 (the code the backend's wrapper returns whenever the TOOL's budget fired,
+ *   whatever the pipeline ended with) — and, when the clock says the command's own smaller bound
+ *   ran out first and less than the budget, that bound instead.
+ * - the command carried its own `timeout <N>`, N is inside this tool's budget (a larger one never
+ *   fires — the tool's does), the run used N, and no runner printed a closing summary: the run was
+ *   killed at its own bound. Its exit code, when the pipeline handed one back, is the filter's.
+ * - the run used this tool's whole budget behind a filter that withheld its output, and printed no
+ *   closing summary: the budget stopped it, and no code in the result is the run's.
+ *
+ * @param command - The command the executor sent.
+ * @param result - Its result.
+ * @param elapsedMs - How long the command ran, in ms.
+ * @param budgetSeconds - This tool's foreground budget, in seconds (0 when it has none).
+ * @returns The stopped run, or null.
+ */
+export declare function commandCutRun(command: string, result: unknown, elapsedMs: number, budgetSeconds?: number): CutRun | null;
+/**
+ * The facts a result records about the run a budget stopped it in — what a reader needs to say
+ * how far the run got WITHOUT re-reading its log or re-deriving the counts.
+ *
+ * The numbers are read from the runner's own output where it printed them (Hurl's per-file lines,
+ * Playwright's `[n/K]`), so a caller that can also see the suite itself — the file count of the
+ * `*.hurl` directory the run walked — fills in the `total` this could not know, and both then say
+ * the same sentence ({@link cutRunSentence}).
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The facts the result carries, or null when it records no stopped run.
+ */
+export declare function cutRunFacts(result: unknown): CutRun | null;
+/**
+ * The first line of a stopped run's result: how long it was allowed, what stopped it, how far it
+ * got, and the last thing it printed.
+ *
+ * Written to be quotable by the model in one sentence and to leave no room for "nearly passing":
+ * the counts come from the runner's own output ({@link runProgress}), and a `total` the caller
+ * read elsewhere (the suite's own file count) fills in the "M of K" it can then state.
+ *
+ * @param run - The stopped run.
+ * @returns The sentence.
+ */
+export declare function cutRunSentence(run: CutRun): string;
+//# sourceMappingURL=cut-run.d.ts.map

package/dist/cut-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AA0BD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK,GAAG,aAAa,GAAG,iBAAiB,CAAA;AAErD,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,mGAAmG;IACnG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,gGAAgG;IAChG,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AA2CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,GAChB,MAAM,GAAG,IAAI,CA2Df;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgB1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBlD"}

package/dist/cut-run.js

@@ -0,0 +1,267 @@
+/**
+ * A command that a budget stopped before it finished, and the state its result carries so no
+ * reader can mistake it for a run that ended.
+ *
+ * X1 xr-molecule-flash-m93 (2026-10-16, +12:37) sent the supplied RealWorld suite as
+ * `timeout 280 hurl --test --continue-on-error --jobs 1 … hurl/*.hurl 2>&1 | tail -60` and got
+ * back `exitCode: 0`, four finished files' lines and nothing else. Two lies in one result: the
+ * `timeout 280` killed the run at 280 s, and the `| tail` made the pipeline's status the status —
+ * so the executor read a suite that stopped at its fifth file as a suite that ran and nearly
+ * passed, fixed one message, and immediately sent the same 280-second command again (the run's
+ * third, ~14 minutes of a 60-minute cap across three of them).
+ *
+ * So the tool never reports a stopped run as `exitCode: 0`. Such a result carries
+ * `status: 'cut_at_budget'` and an exit code that is `null` whenever the number the pipeline
+ * reported belongs to the filter rather than to the run, and every reader of a run's verdict reads
+ * the state through {@link commandRunState} — a cut run is NOT RUN, never a pass.
+ *
+ * Two things stop a run, and both are read from the command and the result, never inferred:
+ *
+ * 1. **Its own bound** — a `timeout <N>` the command carries ({@link commandTimeoutSeconds}). The
+ *    run used it, so the run was killed at it; with no closing tally in the output, the run did
+ *    not finish. This is m93's shape.
+ * 2. **This tool's budget** — the backend runs the command under `timeout` (see
+ *    `backends/sandbox.ts`), which reports 124 whatever the pipeline did, and returns everything
+ *    printed until then. The budget is the tool's own, so its number belongs to the tool.
+ *
+ * @module
+ */
+import { commandTimeoutSeconds } from './command-position.js';
+import { isSuiteRunCommand } from './utilities.js';
+/**
+ * The state a result carries when a budget stopped its command: a run that did not finish is not a
+ * run that passed, and no reader may treat it as one.
+ */
+export const CUT_AT_BUDGET = 'cut_at_budget';
+/**
+ * The state a command's result records — THE reader every verdict about a run goes through.
+ *
+ * A result that carries no state is a run that ended: the state is written where the run is
+ * stopped ({@link commandCutRun}), so a result without it was never stopped by a budget this
+ * platform set or can see. Results produced before this state existed read the same way, which is
+ * what keeps a past turn's tally readable.
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The state the result records.
+ */
+export function commandRunState(result) {
+    if (result === null || typeof result !== 'object')
+        return 'ran';
+    return result.status === CUT_AT_BUDGET ? CUT_AT_BUDGET : 'ran';
+}
+/**
+ * The gap between a bound and the elapsed time a run killed at it reports. Zero, and deliberately
+ * not a tolerance: a command killed at its bound reports AT LEAST the bound (the shell's own
+ * bookkeeping runs after the kill, and this tool's round trip is on top), so any slack would only
+ * make a SHORT bound fire on a run that finished inside it (`timeout 5 curl …` answering in 3 s).
+ * A run that finished near its bound carried its runner's closing summary — {@link suiteTally}.
+ *
+ * @param boundSeconds - The bound the run was allowed.
+ * @returns The elapsed ms a run stopped at that bound reports at least.
+ */
+function atBoundMs(boundSeconds) {
+    return boundSeconds * 1000;
+}
+/**
+ * A runner's closing summary, printed only by a run that walked its whole suite: Hurl's
+ * `Executed files:` block and the `N passed` / `N failed` / `N flaky` line Playwright and Vitest
+ * print when they finish.
+ *
+ * This is what separates "stopped at the bound" from "used the bound and finished": a suite that
+ * printed its summary ran to its end, and is read as the run it was.
+ */
+const SUITE_TALLY = /\bExecuted files:\s*\d+|\b\d+\s+(?:passed|failed|flaky|skipped)\b/;
+/**
+ * Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+ *
+ * @param text - The run's stdout and stderr.
+ * @returns True when the runner's own end-of-run summary is there.
+ */
+export function suiteTally(text) {
+    return SUITE_TALLY.test(text);
+}
+/** The last thing a run printed: its last non-blank line, as one line and short enough to quote. */
+function lastPrinted(text) {
+    const lines = text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = (lines[i] ?? '').trim();
+        if (line)
+            return line.length > 180 ? `${line.slice(0, 177)}…` : line;
+    }
+    return null;
+}
+/** Hurl's per-file line: `Success hurl/articles.hurl (17 request(s) in 318 ms)`. */
+const HURL_FILE_LINE = /^(?:Success|Failure)\s+(\S+)/gm;
+/** Playwright's progress line — `[5/13] specs/auth.spec.ts:10:5 › signs up`. */
+const PROGRESS_LINE = /^\s*\[(\d+)\/(\d+)\]/gm;
+/**
+ * What the runner's own output says the run got through.
+ *
+ * Hurl prints a line per finished file and no total unless it finished; Playwright's line reporter
+ * prints `[n/K]` with both numbers. Neither is inferred from the command — a run that printed
+ * nothing says nothing, which is what `null` means here.
+ *
+ * @param text - The run's stdout and stderr.
+ * @param suite - Whether the command runs a suite.
+ * @returns How many finished, how many the run was walking, and the noun.
+ */
+function runProgress(text, suite) {
+    const files = new Set();
+    for (const m of text.matchAll(HURL_FILE_LINE))
+        files.add(m[1] ?? '');
+    if (files.size > 0)
+        return { ran: files.size, total: null, noun: 'files' };
+    let ran = null;
+    let total = null;
+    for (const m of text.matchAll(PROGRESS_LINE)) {
+        ran = Number(m[1]);
+        total = Number(m[2]);
+    }
+    if (ran !== null)
+        return { ran, total, noun: 'tests' };
+    return { ran: null, total: null, noun: suite ? 'tests' : 'files' };
+}
+/**
+ * The run a command's result records as stopped by a budget, or null when the result is a run that
+ * ended (or says nothing about a run).
+ *
+ * Evidence, in order — never a guess:
+ *
+ * - `timeout`'s own 124 (the code the backend's wrapper returns whenever the TOOL's budget fired,
+ *   whatever the pipeline ended with) — and, when the clock says the command's own smaller bound
+ *   ran out first and less than the budget, that bound instead.
+ * - the command carried its own `timeout <N>`, N is inside this tool's budget (a larger one never
+ *   fires — the tool's does), the run used N, and no runner printed a closing summary: the run was
+ *   killed at its own bound. Its exit code, when the pipeline handed one back, is the filter's.
+ * - the run used this tool's whole budget behind a filter that withheld its output, and printed no
+ *   closing summary: the budget stopped it, and no code in the result is the run's.
+ *
+ * @param command - The command the executor sent.
+ * @param result - Its result.
+ * @param elapsedMs - How long the command ran, in ms.
+ * @param budgetSeconds - This tool's foreground budget, in seconds (0 when it has none).
+ * @returns The stopped run, or null.
+ */
+export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0) {
+    if (typeof command !== 'string' || !command.trim())
+        return null;
+    if (result === null || typeof result !== 'object')
+        return null;
+    if (!Number.isFinite(elapsedMs))
+        return null;
+    const r = result;
+    const exitCode = typeof r.exitCode === 'number' ? r.exitCode : null;
+    const text = `${String(r.stdout ?? '')}\n${String(r.stderr ?? '')}`;
+    // A suite that printed its summary ran to its end, whatever it was wrapped in.
+    if (suiteTally(text))
+        return null;
+    const suite = isSuiteRunCommand(command);
+    const withheld = /\|\s*(?:tail|head|grep|egrep|fgrep|sort|uniq|wc|jq)\b/.test(command);
+    const progress = runProgress(text, suite);
+    const doing = lastPrinted(text);
+    const declared = commandTimeoutSeconds(command);
+    // A command whose own bound is inside this tool's budget is stopped by ITS bound: a larger one
+    // never gets the chance — the backend's `timeout` fires first (see the module doc). With no
+    // tool budget at all (a reader re-reading a background run) the command's own bound is the only
+    // one there is.
+    const ownBoundStops = budgetSeconds === 0 || (declared !== null && declared < budgetSeconds);
+    // `timeout`'s own 124 — the code the backend's wrapper returns when the TOOL's budget fires,
+    // whatever the pipeline ended with (`backends/sandbox.ts`). Which of the two bounds fired is the
+    // clock's to say: a run killed at the tool's budget reports at least the budget, and one killed
+    // at its own bound reports at least that bound and less than the budget.
+    if (budgetSeconds > 0 && exitCode === 124) {
+        const ownFired = declared !== null &&
+            ownBoundStops &&
+            elapsedMs >= atBoundMs(declared) &&
+            elapsedMs < atBoundMs(budgetSeconds);
+        return {
+            seconds: ownFired ? declared : budgetSeconds,
+            stoppedBy: ownFired ? 'command-timeout' : 'tool-budget',
+            exitCode,
+            ...progress,
+            doing,
+        };
+    }
+    if (declared !== null && ownBoundStops && elapsedMs >= atBoundMs(declared)) {
+        return {
+            seconds: declared,
+            stoppedBy: 'command-timeout',
+            // A code the filter produced is not the run's: `… | tail` handed back 0 forever (m93).
+            exitCode: withheld || exitCode === 0 ? null : exitCode,
+            ...progress,
+            doing,
+        };
+    }
+    // The tool's budget with its code masked: the run used the whole budget and the pipeline left
+    // nothing readable of it — no code of its own, and no runner's closing summary.
+    if (budgetSeconds > 0 && withheld && elapsedMs >= atBoundMs(budgetSeconds)) {
+        return {
+            seconds: budgetSeconds,
+            stoppedBy: 'tool-budget',
+            exitCode: exitCode === 0 ? null : exitCode,
+            ...progress,
+            doing,
+        };
+    }
+    return null;
+}
+/**
+ * The facts a result records about the run a budget stopped it in — what a reader needs to say
+ * how far the run got WITHOUT re-reading its log or re-deriving the counts.
+ *
+ * The numbers are read from the runner's own output where it printed them (Hurl's per-file lines,
+ * Playwright's `[n/K]`), so a caller that can also see the suite itself — the file count of the
+ * `*.hurl` directory the run walked — fills in the `total` this could not know, and both then say
+ * the same sentence ({@link cutRunSentence}).
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The facts the result carries, or null when it records no stopped run.
+ */
+export function cutRunFacts(result) {
+    if (result === null || typeof result !== 'object')
+        return null;
+    if (commandRunState(result) !== CUT_AT_BUDGET)
+        return null;
+    const cut = result.cutRun;
+    if (cut === null || typeof cut !== 'object')
+        return null;
+    const c = cut;
+    if (typeof c.seconds !== 'number' || typeof c.stoppedBy !== 'string')
+        return null;
+    return {
+        seconds: c.seconds,
+        stoppedBy: c.stoppedBy,
+        exitCode: typeof c.exitCode === 'number' ? c.exitCode : null,
+        ran: typeof c.ran === 'number' ? c.ran : null,
+        total: typeof c.total === 'number' ? c.total : null,
+        noun: c.noun === 'tests' ? 'tests' : 'files',
+        doing: typeof c.doing === 'string' && c.doing ? c.doing : null,
+    };
+}
+/**
+ * The first line of a stopped run's result: how long it was allowed, what stopped it, how far it
+ * got, and the last thing it printed.
+ *
+ * Written to be quotable by the model in one sentence and to leave no room for "nearly passing":
+ * the counts come from the runner's own output ({@link runProgress}), and a `total` the caller
+ * read elsewhere (the suite's own file count) fills in the "M of K" it can then state.
+ *
+ * @param run - The stopped run.
+ * @returns The sentence.
+ */
+export function cutRunSentence(run) {
+    const by = run.stoppedBy === 'tool-budget' ? "this tool's limit" : `its own \`timeout ${run.seconds}\``;
+    const lead = `This run was stopped after ${run.seconds}s (${by})`;
+    const count = run.ran !== null && run.total !== null
+        ? `: ${run.ran} of ${run.total} ${run.noun} ran, the rest did not run`
+        : run.ran !== null
+            ? `: ${run.ran} ${run.noun} ran and the rest did not run`
+            : ' before it finished';
+    const doing = run.doing ? `; the last thing it was doing: ${run.doing}` : '';
+    // Why the result carries no code: without this the model reads the missing field as an
+    // omission, and the number it used to read there was the pipeline's own 0.
+    const code = run.exitCode === null
+        ? ' It has no exit code of its own to report — the one this pipeline produced belongs to the filter, not to the run.'
+        : '';
+    return `${lead}${count}${doing}.${code}`;
+}

package/dist/index.d.ts

@@ -133,12 +133,14 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
+export * from './cut-run.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';
+export * from './trace-artifacts.js';
 export * from './types.js';
 export * from './utilities.js';
 //# sourceMappingURL=index.d.ts.map

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,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,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,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

@@ -133,11 +133,13 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
+export * from './cut-run.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';
+export * from './trace-artifacts.js';
 export * from './types.js';
 export * from './utilities.js';

package/dist/tools.d.ts

@@ -26,6 +26,26 @@ import type { AITool } from '@molecule/api-ai';
  */
 export declare function taskStopCommand(backend: ExecutionBackend, taskId: string): Promise<string>;
 import type { ExecutionBackend, ToolBuildConfig } from './types.js';
+/**
+ * The closing advice on an over-budget message for a command that is not a test
+ * suite: the work it was chaining is what to split.
+ */
+export declare const SPLIT_WORK_ADVICE: string;
+/**
+ * The closing advice on an over-budget message for a command that IS a suite run
+ * (Playwright, Vitest, a `hurl` run — {@link isSuiteRunCommand}): its files are not
+ * a bigger unit to break up.
+ *
+ * X1 flash-m36 asked for this half and the message kept saying "run a smaller unit"
+ * for two months. It is the wrong direction for a suite, and measurably: a run
+ * stopped here reports NO tally, so nothing in the result says which test or request
+ * hung — the run has to be sent again in the background (off this budget, its output
+ * written to a log that can be read mid-run) or, when a consumer knows the runner's
+ * per-request limit, with each request bounded. xr-molecule-flash-m93 (+06:22,
+ * 2026-10-16) lost 4.8 minutes to a Hurl run whose ONE unanswered request had hurl's
+ * 300 s default per request holding the file, ten seconds past this tool's budget.
+ */
+export declare const SUITE_OVER_BUDGET_ADVICE: string;
 /**
  * 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

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;AAiF9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAwHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEnE;;;;;;;;;;;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;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAgjExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA+F9C;;;;;;;;;;;;;;;;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;AAiEnE;;;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,CAovExF"}