@molecule/api-ai-tools 1.9.6 → 1.9.8

package/dist/command-position.js

@@ -541,6 +541,26 @@ function splitSegments(command) {
     let buffer = '';
     /** The offset in the command of the current buffer's first character. */
     let bufferStart = 0;
+    /** How many `( … )` / `{ … }` groups are open at the current position. */
+    let groupDepth = 0;
+    /** The depth each character of `buffer` was written at, aligned with it (-1 when quoted). */
+    let depths = [];
+    /**
+     * Append shell text to the statement being read, recording the depth it was written at.
+     * Text inside a quote or a command substitution is recorded as -1: a `>` there is a literal
+     * character or a nested command's business, never the outer command's redirect.
+     */
+    const put = (text, depth = groupDepth) => {
+        for (let n = 0; n < text.length; n++)
+            depths.push(depth);
+        buffer += text;
+    };
+    /** Close the statement being read at `after`. */
+    const end = (after) => {
+        parts.push({ text: buffer, start: bufferStart, after, depths });
+        buffer = '';
+        depths = [];
+    };
     /** The nestings this position sits inside, outermost first. */
     const stack = [];
     for (let i = 0; i < source.length; i++) {
@@ -550,7 +570,7 @@ function splitSegments(command) {
         // A single-quoted string expands nothing at all: no escape, no substitution, and no quote
         // but its own ends it.
         if (top === 'single') {
-            buffer += char;
+            put(char, -1);
             if (char === "'")
                 stack.pop();
             continue;
@@ -559,7 +579,7 @@ function splitSegments(command) {
         // inside single quotes (handled above). The `(` is consumed here so the depth is counted once.
         if (char === '$' && next === '(') {
             stack.push('sub');
-            buffer += '$(';
+            put('$(', -1);
             i += 1;
             continue;
         }
@@ -569,21 +589,21 @@ function splitSegments(command) {
             if (char === '"')
                 stack.pop();
             else if (char === '\\' && next !== undefined) {
-                buffer += char + next;
+                put(char + next, -1);
                 i += 1;
                 continue;
             }
-            buffer += char;
+            put(char, -1);
             continue;
         }
         if (char === '"') {
             stack.push('double');
-            buffer += char;
+            put(char, -1);
             continue;
         }
         if (char === "'") {
             stack.push('single');
-            buffer += char;
+            put(char, -1);
             continue;
         }
         // Inside a substitution or a subshell of one: its own parentheses nest, its `|`/`;`/`&&`
@@ -593,41 +613,53 @@ function splitSegments(command) {
                 stack.push('sub');
             else if (char === ')')
                 stack.pop();
-            buffer += char;
+            put(char, -1);
             continue;
         }
         if (char === '\\' && next !== undefined) {
-            buffer += char + next;
+            // An escaped character is a literal (`\>` writes no file).
+            put(char + next, -1);
             i += 1;
             continue;
         }
+        // Grouping belongs to the shell, not to a word: a statement written inside `( … )` or
+        // `{ … }` writes through that group, so the depth travels with every character a caller
+        // reading a redirect may ask about.
+        if (char === '(' || char === '{') {
+            put(char);
+            groupDepth += 1;
+            continue;
+        }
+        if (char === ')' || char === '}') {
+            groupDepth = Math.max(0, groupDepth - 1);
+            put(char);
+            continue;
+        }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
-            parts.push({ text: buffer, start: bufferStart, after: char + next });
-            buffer = '';
+            end(char + next);
             i += 1;
             bufferStart = i + 1;
             continue;
         }
         if (char === ';' || char === '|' || char === '\n') {
-            parts.push({ text: buffer, start: bufferStart, after: char });
-            buffer = '';
+            end(char);
             bufferStart = i + 1;
             continue;
         }
         if (char === '&' && source[i - 1] !== '>' && next !== '>') {
-            parts.push({ text: buffer, start: bufferStart, after: '&' });
-            buffer = '';
+            end('&');
             bufferStart = i + 1;
             continue;
         }
-        buffer += char;
+        put(char);
     }
-    parts.push({ text: buffer, start: bufferStart, after: '' });
+    end('');
     const out = [];
     // The separator of the last part, kept across the empty ones so a statement's own separator
     // survives the blank lines around it (`a &&\n b` and a heredoc's blanked body alike).
     let lastAfter = null;
     for (const part of parts) {
+        const trimStart = part.text.length - part.text.trimStart().length;
         const text = part.text.trim();
         if (text === '') {
             lastAfter = part.after;
@@ -635,14 +667,63 @@ function splitSegments(command) {
         }
         out.push({
             text,
-            start: part.start + (part.text.length - part.text.trimStart().length),
+            start: part.start + trimStart,
             after: part.after,
             before: lastAfter ?? '',
+            depths: part.depths.slice(trimStart),
         });
         lastAfter = part.after;
     }
     return out;
 }
+/** A redirect's target word: a quoted one keeps its spaces (`tee 'out file.txt'`). */
+const REDIRECT_TARGET_WORD = String.raw `(?:'[^']*'|"[^"]*"|[^\s;&|]+)`;
+/**
+ * A `>`, `>>` or `&>` redirect written at a statement's own level, with the word it writes to.
+ * The lookbehind is what keeps `2>&1` out: the `>` of a descriptor redirect follows a digit.
+ */
+const REDIRECT_AND_TARGET = new RegExp(String.raw `(?<![0-9&>])(?:&>|1?>>?)\s*(${REDIRECT_TARGET_WORD})`, 'g');
+/** A word with one layer of MATCHING shell quotes removed (`'out file.txt'` → `out file.txt`). */
+function unquotedWord(word) {
+    return word.replace(/^(['"])(.*)\1$/, '$2');
+}
+/**
+ * The file a statement sends its own output to, when it redirects it at the command's own level.
+ *
+ * Three shapes are deliberately not one: a redirect inside a `( … )` / `{ … }` group (it writes
+ * through that group, not through the command's own shell), a statement that feeds a heredoc's
+ * file (`cat > cfg.ts <<'EOF'` writes a config), and `/dev/null` or a descriptor (`2>&1`).
+ *
+ * @param text - The statement's text, as the tokenizer split it.
+ * @param depths - The depth each character of `text` was written at: the open-group count, 0 at
+ *   the command's own level, -1 inside a quote or a command substitution.
+ * @param program - The word in command position (`tee` writes through its own file argument).
+ * @param args - The statement's words after the program.
+ * @returns The target with one layer of quotes removed, or null.
+ */
+function redirectTargetOf(text, depths, program, args) {
+    // A heredoc's own file is a config the command WRITES, never where the run's output goes
+    // (X1 flash-m44).
+    if (/(?:^|\s)<<(?![<])-?/.test(text))
+        return null;
+    // `| tee file` is a statement of its own: the pipe is a statement separator here.
+    if (program === 'tee') {
+        const target = args.find((arg) => !arg.startsWith('-'));
+        return target === undefined ? null : unquotedWord(target);
+    }
+    let last = null;
+    for (const match of text.matchAll(REDIRECT_AND_TARGET)) {
+        const word = unquotedWord(match[1] ?? '');
+        // Only the command's own level counts: not a group's redirect (depth > 0), and not one
+        // written inside a quote or a command substitution (depth -1).
+        if ((depths[match.index ?? 0] ?? 0) !== 0)
+            continue;
+        if (word === '/dev/null' || word.startsWith('&'))
+            continue;
+        last = word;
+    }
+    return last;
+}
 /**
  * One segment's words: quotes kept whole, grouping parentheses dropped, and a `(` written
  * against the first word taken off it (`(npx playwright test)`).
@@ -912,6 +993,9 @@ function locatedSegmentsOf(command, depth) {
             assignmentOffset: part.start + leading.end,
             programOffset: words[start.at] === undefined ? null : part.start + (wordOffset(part.text, start.at) ?? 0),
         };
+        const program = words[start.at] === undefined ? '' : programName(words[start.at] ?? '');
+        const args = words.slice(start.at + 1);
+        const redirectTarget = redirectTargetOf(part.text, part.depths, program, args);
         if (start.nested !== null) {
             const inner = locatedSegmentsOf(start.nested, depth + 1);
             for (let i = 0; i < inner.length; i += 1) {
@@ -927,6 +1011,12 @@ function locatedSegmentsOf(command, depth) {
                     end: null,
                     assignmentOffset: null,
                     programOffset: null,
+                    // `sh -c '…' &` backgrounds the command inside the string too.
+                    terminator: part.after === '&' ? '&' : entry.terminator,
+                    // A redirect written OUTSIDE the string (`sh -c '…' > run.log`) carries the nested
+                    // command's output, so the first nested statement holds it — unless that statement
+                    // redirects on its own, which takes the output away from the outer file.
+                    redirectTarget: i === 0 && entry.redirectTarget === null ? redirectTarget : entry.redirectTarget,
                     separator: i === 0 ? part.before : entry.separator,
                 });
             }
@@ -943,11 +1033,11 @@ function locatedSegmentsOf(command, depth) {
                     ...placed,
                     programOffset: null,
                     separator: part.before,
+                    terminator: part.after,
+                    redirectTarget,
                 });
             continue;
         }
-        const program = programName(word);
-        const args = words.slice(start.at + 1);
         out.push({
             segment: {
                 program,
@@ -958,6 +1048,8 @@ function locatedSegmentsOf(command, depth) {
             assignments: leading.words,
             ...placed,
             separator: part.before,
+            terminator: part.after,
+            redirectTarget,
         });
     }
     return out;
@@ -984,6 +1076,87 @@ export function commandTimeoutSeconds(command) {
     }
     return bound;
 }
+/**
+ * The command with the `timeout <N>` wrapper lifted off the statements `which` selects, and the
+ * largest bound that was lifted.
+ *
+ * The platform moves a run to the background precisely because its own bound cannot fit this
+ * tool's ceiling, and a background task has no ceiling — its wait is bounded by `wait_for_task`
+ * and the turn's deadline. The `timeout N` an executor wrote to fit the ceiling therefore keeps
+ * killing the run at N in the background, where nothing needed it: X1 xr-molecule-flash-m143
+ * (+24:45) wrote `timeout 280` for a 31-test walk, the tool backgrounded it, and the prefix stopped
+ * the walk with no tally — then the cut sentence told the executor to "run it in the background",
+ * which is where it already was.
+ *
+ * The wrapper is found by the same parse every other command reader uses ({@link commandStart}):
+ * `timeout` in an argument bounds nothing, and the wrapper's own flags (`-k`/`--kill-after`,
+ * `-s`/`--signal`) are stepped over, so `timeout -k 5 280 …` is `280`.
+ *
+ * @param command - The shell command.
+ * @param which - The statements to lift the wrapper from (a suite run, for the background path).
+ * @returns The rewritten command, and the largest lifted bound (null when nothing was lifted).
+ */
+export function withoutTimeoutWrapper(command, which) {
+    if (typeof command !== 'string' || !command.trim())
+        return { command, seconds: null };
+    /** The spans to remove, as offsets in the command — applied back to front. */
+    const removals = [];
+    let seconds = null;
+    for (const located of locatedSegmentsOf(command, 0)) {
+        const segment = located.segment;
+        if (segment === null || segment.timeoutSeconds === null)
+            continue;
+        // A statement inside a nested `sh -c '…'` has no offsets here: its positions are positions in
+        // that string, so nothing may be spliced at them.
+        if (located.start === null || located.programOffset === null)
+            continue;
+        if (!which(segment))
+            continue;
+        // Every word in front of the program: the assignments and the wrappers. The duration belongs
+        // to the wrapper, so the walk has to see the words, not just the parse's total bound.
+        const prefix = command.slice(located.start, located.programOffset);
+        const words = [];
+        const at = new RegExp(WORD.source, 'g');
+        for (let match = at.exec(prefix); match !== null; match = at.exec(prefix)) {
+            words.push({
+                text: match[0],
+                start: located.start + match.index,
+                end: located.start + match.index + match[0].length,
+            });
+        }
+        for (let i = 0; i < words.length; i += 1) {
+            const word = words[i];
+            if (word === undefined || programName(word.text) !== 'timeout')
+                continue;
+            // The wrapper's own flags, then the duration — the same walk {@link commandStart} makes.
+            const withValue = WRAPPER_VALUE_FLAGS.timeout ?? [];
+            let next = i + 1;
+            while (next < words.length && (words[next]?.text ?? '').startsWith('-')) {
+                const flag = unquoted(words[next]?.text ?? '');
+                next += !flag.includes('=') && withValue.includes(flag) ? 2 : 1;
+            }
+            const duration = words[next];
+            const bound = duration === undefined ? null : durationSeconds(unquoted(duration.text));
+            if (duration === undefined || bound === null)
+                continue;
+            seconds = seconds === null ? bound : Math.max(seconds, bound);
+            // The whitespace between the duration and the program goes too, so the command does not
+            // carry a double space where the wrapper stood.
+            let end = duration.end;
+            while (end < command.length && /\s/.test(command[end] ?? ''))
+                end += 1;
+            removals.push({ start: word.start, end });
+            i = next;
+        }
+    }
+    if (removals.length === 0)
+        return { command, seconds: null };
+    let out = command;
+    for (const removal of removals.sort((a, b) => b.start - a.start)) {
+        out = out.slice(0, removal.start) + out.slice(removal.end);
+    }
+    return { command: out, seconds };
+}
 /**
  * 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/cut-run.d.ts

@@ -134,6 +134,14 @@ export interface CutRun {
     seconds: number;
     /** Whether this tool's budget stopped it or the `timeout` the command carried. */
     stoppedBy: CutBy;
+    /**
+     * Whether this was a detached background task, read with no budget of this tool's own
+     * ({@link commandCutRun}'s `budgetSeconds` is 0). A background run is bounded by what its own
+     * command carries — so a `command-timeout` cut there is that prefix killing the walk, and the
+     * executor must be told to drop the prefix, never to start the run in the background it is
+     * already in (X1 xr-molecule-flash-m143 +24:45).
+     */
+    background: boolean;
     /**
      * 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.

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

@@ -1 +1 @@
-{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,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;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,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;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAgFf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgB1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuBlD"}
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,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;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAuFf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAiB1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiClD"}

package/dist/cut-run.js

@@ -296,6 +296,9 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
     // 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);
+    // No budget of this tool's in force is what a background reader is: the task was detached, and
+    // nothing bounded it but what its own command carries.
+    const background = budgetSeconds === 0;
     // `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
@@ -308,6 +311,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
         return {
             seconds: ownFired ? declared : budgetSeconds,
             stoppedBy: ownFired ? 'command-timeout' : 'tool-budget',
+            background,
             exitCode,
             ...progress,
             doing,
@@ -317,6 +321,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
         return {
             seconds: declared,
             stoppedBy: 'command-timeout',
+            background,
             // A code the filter produced is not the run's: `… | tail` handed back 0 forever (m93).
             exitCode: withheld || exitCode === 0 ? null : exitCode,
             ...progress,
@@ -329,6 +334,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
         return {
             seconds: budgetSeconds,
             stoppedBy: 'tool-budget',
+            background,
             exitCode: exitCode === 0 ? null : exitCode,
             ...progress,
             doing,
@@ -344,6 +350,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
         return {
             seconds: usedBudget ? budgetSeconds : Math.max(1, Math.round(elapsedMs / 1000)),
             stoppedBy: usedBudget ? 'tool-budget' : 'process-stop',
+            background,
             exitCode: withheld || exitCode === 0 ? null : exitCode,
             ...progress,
             doing,
@@ -377,6 +384,7 @@ export function cutRunFacts(result) {
     return {
         seconds: c.seconds,
         stoppedBy: c.stoppedBy,
+        background: c.background === true,
         exitCode: typeof c.exitCode === 'number' ? c.exitCode : null,
         ran: typeof c.ran === 'number' ? c.ran : null,
         total: typeof c.total === 'number' ? c.total : null,
@@ -401,9 +409,19 @@ export function cutRunSentence(run) {
     const by = run.stoppedBy === 'tool-budget'
         ? "this tool's limit"
         : run.stoppedBy === 'command-timeout'
-            ? `its own \`timeout ${run.seconds}\``
+            ? run.background
+                ? `the command's own \`timeout ${run.seconds}\`, which killed it at ${run.seconds} s`
+                : `its own \`timeout ${run.seconds}\``
             : 'a process kill outside this tool (no `timeout` of its own and no limit of this tool had fired)';
-    const background = 'run it in the background (run_in_background + wait_for_task)';
+    // What the reader must do next. A run that was ALREADY a background task has nothing to gain
+    // from being sent to the background again — when its own `timeout` is what stopped it, that
+    // prefix is the thing to drop (X1 xr-molecule-flash-m143 +24:45: three cut sentences in one run
+    // told a background walk to "run it in the background", which is where it already was).
+    const background = run.background
+        ? run.stoppedBy === 'command-timeout'
+            ? `drop the \`timeout\` prefix and send it again — in the background a run is bounded by \`wait_for_task\` and the turn's deadline, not by this tool's ceiling, so the bound you wrote is what killed it`
+            : 'send it again when you are ready'
+        : 'run it in the background (run_in_background + wait_for_task)';
     const missing = run.ran !== null && run.total !== null ? run.total - run.ran : null;
     const lead = missing !== null
         ? `Ran ${run.ran} of ${run.total} ${run.noun} in ${run.seconds} s and was stopped by ${by} — the ${missing} it never reached ${missing === 1 ? 'has' : 'have'} not run; ${background}`

package/dist/index.d.ts

@@ -136,6 +136,7 @@ export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';
 export * from './input-normalizer.js';
+export * from './line-diff.js';
 export * from './no-test-run.js';
 export * from './pipeline-exit-note.js';
 export * from './schemas.js';

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,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,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"}
+{"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,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,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

@@ -136,6 +136,7 @@ export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';
 export * from './input-normalizer.js';
+export * from './line-diff.js';
 export * from './no-test-run.js';
 export * from './pipeline-exit-note.js';
 export * from './schemas.js';

package/dist/line-diff.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Real added/removed LINE counts for the `diff` a file-writing tool reports.
+ *
+ * The count is a diff, not an arithmetic delta: replacing one line with another
+ * leaves the line count unchanged, so `new.length - old.length` is 0 for the
+ * edit that changed the file — a result that reads to the model as "your write
+ * did nothing" (X0 xr-molecule-flash-m141 +09:56: `write_file` rewrote
+ * `ArticlePreview.tsx`'s favorite label and reported
+ * `"linesAdded":0,"linesRemoved":0`). The lines an edit actually changed are
+ * found with the same longest-common-subsequence line diff the IDE's tool cards
+ * use (`@molecule/app-ide-react`'s `diffLineCount`); it is mirrored here because
+ * the API and App halves of the workspace cannot import each other (AGENTS.md
+ * Rule 11, enforced by ESLint). Keep the two in step if either changes.
+ *
+ * @module
+ */
+/**
+ * Count truly added/removed lines between two line arrays using LCS.
+ *
+ * Bounded by construction, so a whole-file edit cannot allocate a quadratic
+ * table here: the longest common prefix and suffix are trimmed first (exact —
+ * those lines belong to every optimal diff, and on the usual small edit they
+ * shrink the table to the edited span), and what is left is capped (see
+ * {@link lcsLength}).
+ *
+ * @param oldLines - The original lines array.
+ * @param newLines - The modified lines array.
+ * @returns An object with the number of added and removed lines.
+ */
+export declare function diffLineCount(oldLines: readonly string[], newLines: readonly string[]): {
+    added: number;
+    removed: number;
+};
+//# sourceMappingURL=line-diff.d.ts.map

package/dist/line-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-diff.d.ts","sourceRoot":"","sources":["../src/line-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmGH;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAuBpC"}

package/dist/line-diff.js

@@ -0,0 +1,150 @@
+/**
+ * Real added/removed LINE counts for the `diff` a file-writing tool reports.
+ *
+ * The count is a diff, not an arithmetic delta: replacing one line with another
+ * leaves the line count unchanged, so `new.length - old.length` is 0 for the
+ * edit that changed the file — a result that reads to the model as "your write
+ * did nothing" (X0 xr-molecule-flash-m141 +09:56: `write_file` rewrote
+ * `ArticlePreview.tsx`'s favorite label and reported
+ * `"linesAdded":0,"linesRemoved":0`). The lines an edit actually changed are
+ * found with the same longest-common-subsequence line diff the IDE's tool cards
+ * use (`@molecule/app-ide-react`'s `diffLineCount`); it is mirrored here because
+ * the API and App halves of the workspace cannot import each other (AGENTS.md
+ * Rule 11, enforced by ESLint). Keep the two in step if either changes.
+ *
+ * @module
+ */
+/**
+ * Largest LCS table the exact diff may build, in cells (old × new). A whole-file
+ * edit can be thousands of lines per side, i.e. tens of millions of cells —
+ * gigabytes of heap for a summary that only needs two numbers. Above this cap
+ * the answer comes from {@link orderedCommonLines}, a provable, order-respecting
+ * common subsequence in O(n log n); below it the result is exact. 1 << 22 cells
+ * is a few milliseconds, and the two-row table keeps memory at O(min(old, new)).
+ */
+const MAX_DIFF_CELLS = 1 << 22;
+/**
+ * Longest common subsequence length of two line arrays, in bounded time and
+ * memory: two rows of the recurrence instead of the whole table, and — once the
+ * table would exceed {@link MAX_DIFF_CELLS} — the order-respecting lower bound
+ * from {@link orderedCommonLines}.
+ *
+ * @param a - The first line array.
+ * @param b - The second line array.
+ * @returns The common subsequence length (a lower bound for the capped inputs).
+ */
+function lcsLength(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    if (a.length * b.length > MAX_DIFF_CELLS)
+        return orderedCommonLines(a, b);
+    // The recurrence needs only the previous row, and a row is `cols` wide — so
+    // the SHORTER array belongs on the `cols` axis, which bounds every row by
+    // min(a, b) and is what the memory claim above rests on. The recurrence is
+    // symmetric, so the length it returns is the same either way.
+    let rows = a;
+    let cols = b;
+    if (cols.length > rows.length) {
+        rows = b;
+        cols = a;
+    }
+    let previous = new Array(cols.length + 1).fill(0);
+    let current = new Array(cols.length + 1).fill(0);
+    for (let i = 1; i <= rows.length; i++) {
+        const line = rows[i - 1];
+        for (let j = 1; j <= cols.length; j++) {
+            if (line === cols[j - 1]) {
+                current[j] = previous[j - 1] + 1;
+            }
+            else {
+                const above = previous[j];
+                const left = current[j - 1];
+                current[j] = above >= left ? above : left;
+            }
+        }
+        const swap = previous;
+        previous = current;
+        current = swap;
+    }
+    return previous[cols.length];
+}
+/**
+ * How many lines the two arrays share IN ORDER, for inputs too large for the
+ * exact table: the longest run of lines that appear in the same relative order
+ * on both sides, found among the lines that occur exactly once in `a` (their
+ * position is unambiguous) by reducing their `b` positions to a longest
+ * strictly increasing run — the standard patience LIS, O(n log n).
+ *
+ * Order is the whole point. Counting the lines as a multiset (order thrown
+ * away) is only an UPPER bound on the LCS, so it under-reports changes: a
+ * 3000-line file whose two halves were swapped shares every line, and the
+ * multiset count would report the replacement as `+0 −0` — a result claiming a
+ * real edit changed nothing. Every line counted here is a real in-order match,
+ * so the answer is a LOWER bound on the LCS and the change count it feeds can
+ * only ever be over-stated, never denied.
+ *
+ * @param a - The first line array.
+ * @param b - The second line array.
+ * @returns A common subsequence length.
+ */
+function orderedCommonLines(a, b) {
+    const occurrences = new Map();
+    for (const line of a)
+        occurrences.set(line, (occurrences.get(line) ?? 0) + 1);
+    const position = new Map();
+    a.forEach((line, index) => {
+        if (occurrences.get(line) === 1)
+            position.set(line, index);
+    });
+    // Patience: `tails[i]` is the smallest `b`-position that ends an increasing
+    // run of length `i + 1`.
+    const tails = [];
+    for (const line of b) {
+        const at = position.get(line);
+        if (at === undefined)
+            continue;
+        let lo = 0;
+        let hi = tails.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (tails[mid] < at)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        tails[lo] = at;
+    }
+    return tails.length;
+}
+/**
+ * Count truly added/removed lines between two line arrays using LCS.
+ *
+ * Bounded by construction, so a whole-file edit cannot allocate a quadratic
+ * table here: the longest common prefix and suffix are trimmed first (exact —
+ * those lines belong to every optimal diff, and on the usual small edit they
+ * shrink the table to the edited span), and what is left is capped (see
+ * {@link lcsLength}).
+ *
+ * @param oldLines - The original lines array.
+ * @param newLines - The modified lines array.
+ * @returns An object with the number of added and removed lines.
+ */
+export function diffLineCount(oldLines, newLines) {
+    const oldLength = oldLines.length;
+    const newLength = newLines.length;
+    const shared = Math.min(oldLength, newLength);
+    // Longest common prefix / suffix. `suffix` is bounded by `shared - prefix`, so
+    // the two trimmed runs can never overlap each other.
+    let prefix = 0;
+    while (prefix < shared && oldLines[prefix] === newLines[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < shared - prefix &&
+        oldLines[oldLength - 1 - suffix] === newLines[newLength - 1 - suffix]) {
+        suffix++;
+    }
+    const common = prefix +
+        suffix +
+        lcsLength(oldLines.slice(prefix, oldLength - suffix), newLines.slice(prefix, newLength - suffix));
+    return { added: newLength - common, removed: oldLength - common };
+}

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;AAiJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkOD,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;AA8ED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAk6ExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAkJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAqEnE;;;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;AA8ED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAk9ExF"}