@molecule/api-ai-tools 1.6.5 → 1.6.6

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-16T19:48:43.608Z
+Generated: 2026-10-16T21:18:13.332Z
 -->
 
 # @molecule/api-ai-tools
@@ -73,6 +73,37 @@ 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
+}
+```
+
+#### `CutRun`
+
+A run a budget stopped, as its result reports it.
+
+```typescript
+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
 }
 ```
 
@@ -443,6 +474,22 @@ interface FailureCause {
 
 ### Types
 
+#### `CommandRunState`
+
+What a command's result records: a run that ended, or one a budget stopped.
+
+```typescript
+type CommandRunState = 'ran' | typeof CUT_AT_BUDGET
+```
+
+#### `CutBy`
+
+What stopped a run.
+
+```typescript
+type CutBy = 'tool-budget' | 'command-timeout'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -491,6 +538,18 @@ function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): Execu
 
 **Returns:** A backend that proxies all filesystem calls into the sandbox.
 
+#### `durationSeconds(word)`
+
+The seconds a duration word stands for.
+
+```typescript
+function durationSeconds(word: string): number | null
+```
+
+- `word` — A duration (`280`, `20s`, `1m`).
+
+**Returns:** The seconds, or null when the word is not a duration.
+
 #### `commandSegments(command)`
 
 The segments of a command, each with its program and arguments — the answer every classifier
@@ -504,6 +563,25 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `commandTimeoutSeconds(command)`
+
+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}).
+
+```typescript
+function commandTimeoutSeconds(command: string): number | null
+```
+
+- `command` — The shell command.
+
+**Returns:** The seconds the command allows itself, or null.
+
 #### `runsInCommandPosition(command, pattern)`
 
 Whether any segment of the command runs a program whose command-position text matches
@@ -522,6 +600,102 @@ function runsInCommandPosition(command: string, pattern: RegExp): boolean
 
 **Returns:** True when a segment in command position matches.
 
+#### `commandRunState(result)`
+
+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.
+
+```typescript
+function commandRunState(result: unknown): CommandRunState
+```
+
+- `result` — The exec_command / wait_for_task result.
+
+**Returns:** The state the result records.
+
+#### `suiteTally(text)`
+
+Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+
+```typescript
+function suiteTally(text: string): boolean
+```
+
+- `text` — The run's stdout and stderr.
+
+**Returns:** True when the runner's own end-of-run summary is there.
+
+#### `commandCutRun(command, result, elapsedMs, budgetSeconds)`
+
+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.
+
+```typescript
+function commandCutRun(
+  command: string,
+  result: unknown,
+  elapsedMs: number,
+  budgetSeconds?: number,
+): CutRun | null
+```
+
+- `command` — The command the executor sent.
+- `result` — Its result.
+- `elapsedMs` — How long the command ran, in ms.
+- `budgetSeconds` — This tool's foreground budget, in seconds (0 when it has none).
+
+**Returns:** The stopped run, or null.
+
+#### `cutRunFacts(result)`
+
+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}).
+
+```typescript
+function cutRunFacts(result: unknown): CutRun | null
+```
+
+- `result` — The exec_command / wait_for_task result.
+
+**Returns:** The facts the result carries, or null when it records no stopped run.
+
+#### `cutRunSentence(run)`
+
+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.
+
+```typescript
+function cutRunSentence(run: CutRun): string
+```
+
+- `run` — The stopped run.
+
+**Returns:** The sentence.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -1199,6 +1373,105 @@ function findPatternArgs(pattern: string): string
 
 **Returns:** A `find` predicate: `-name '…'` for a bare name, else one or more `-path '…'` alternatives, ORed inside parens when there is more than one.
 
+#### `findPathArgs(pattern)`
+
+The `-path` alternatives of {@link findPatternArgs}, for a pattern whose
+directory the caller has already rooted the search at.
+
+`find_files` narrows the search root itself when the pattern spells its own
+directory out (see {@link literalDirPrefix}) — `node_modules` plus
+`@molecule/api-resource-user/dist/*.d.ts` searched that one directory. The
+remainder (`*.d.ts`) must then keep the `-path` form rather than collapsing to
+`-name`: `*` crosses `/` in an fnmatch glob, so the `-path` form still finds a
+declaration file in a `dist/utilities/` subdirectory, which `-name '*.d.ts'`
+would drop (a silent partial answer, which is worse than the timeout it
+replaced).
+
+```typescript
+function findPathArgs(pattern: string): string
+```
+
+- `pattern` — The pattern's remainder, with a `/` in it or not.
+
+**Returns:** One or more `-path '…'` alternatives, ORed inside parens when there is more than one.
+
+#### `literalDirPrefix(pattern)`
+
+The directory a GLOB pattern spells out, when it spells one out: everything
+before the pattern's first glob character, trimmed back to the last `/`.
+
+A pattern is matched against the whole path with a leading "any parent"
+anchor ({@link findPatternArgs}), so `find` visits every entry below the
+search root. Handed `/workspace/node_modules` and
+`@molecule/api-resource-user/dist/*.d.ts` — a directory named outright —
+`find` walked the sandbox's entire dependency tree and hit the tool's 10 s
+deadline without printing a result (xr-molecule-flash-m94: the one directory
+the model meant answered a `list_files` in 0 s). The literal prefix is that
+directory, and rooting the search at it is what keeps the call instant.
+
+A BARE first segment (`helpers/*`, `bonds/*`, `e2e/*.spec.ts`) is NOT one:
+`helpers/*` means "a `helpers/` directory anywhere below the root", which the
+tool documents and a live run relied on (xr-molecule-flash-m77 — a path
+pattern is not anchored to one depth). Rooting those at
+`<root>/helpers` would answer with a SUBSET, silently: the nested
+`api/src/helpers/` matches would disappear, and a missing file reads as
+"no such file". So a prefix is returned only when it names a path of two or
+more segments (`@molecule/api-resource-user/dist`), which is the shape that
+is a directory rather than a directory name.
+
+```typescript
+function literalDirPrefix(pattern: string): string | null
+```
+
+- `pattern` — A pattern already accepted by {@link isValidGlob}.
+
+**Returns:** The literal directory prefix, without a trailing slash, or null when the pattern has no glob character, no `/`, or only a bare name before one.
+
+#### `isCommandTimeout(error)`
+
+Whether a backend error is the sandbox's own command deadline.
+
+The E2B SDK answers a timed-out `exec` with its generic text —
+`[deadline_exceeded] the operation timed out: … It can be modified by passing
+'timeoutMs' when making the request. Use '0' to disable the timeout.` — which
+names an option the executor cannot set and says nothing about the search
+that died. Handing that sentence to the model is what xr-molecule-flash-m94
+read after `find_files` spent 10 s walking `node_modules`; the tool answers
+the deadline in its own words instead (see {@link searchTimeoutError}).
+
+```typescript
+function isCommandTimeout(error: unknown): boolean
+```
+
+- `error` — The error the backend threw.
+
+**Returns:** True when the error reads as a timeout or a deadline.
+
+#### `searchTimeoutError(tool, searched, pattern, seconds, hint)`
+
+The answer a search tool gives when the backend's deadline fires: what was
+searched, for what, how long the tool allowed, and the two ways to get an
+answer — a narrower `path`, or a listing. Never the vendor's `timeoutMs`
+sentence (see {@link isCommandTimeout}).
+
+```typescript
+function searchTimeoutError(
+  tool: string,
+  searched: string,
+  pattern: string,
+  seconds: number,
+  hint: string,
+): string
+```
+
+- `tool` — The tool that timed out (`find_files`, `search_files`).
+- `searched` — The directory the search actually covered.
+- `pattern` — The pattern it was searching for.
+- `seconds` — The tool's own limit, in seconds.
+- `hint` — What to do differently — the narrower target or the listing tool.
+
+**Returns:** The message's text.
+
 #### `pathArgError(path, tool)`
 
 Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -1664,6 +1937,15 @@ function fusedLine(content: string, newString: string): { line: number; text: st
 
 ### Constants
 
+#### `CUT_AT_BUDGET`
+
+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.
+
+```typescript
+const CUT_AT_BUDGET: 'cut_at_budget'
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.
@@ -1672,6 +1954,34 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `SPLIT_WORK_ADVICE`
+
+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.
+
+```typescript
+const SPLIT_WORK_ADVICE: string
+```
+
+#### `SUITE_OVER_BUDGET_ADVICE`
+
+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.
+
+```typescript
+const SUITE_OVER_BUDGET_ADVICE: string
+```
+
 #### `MAX_READ_SIZE`
 
 Max file size for read_file (5MB).

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"}