@molecule/api-ai-tools 1.8.3 → 1.9.1

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-17T05:02:46.912Z
+Generated: 2026-10-17T07:58:25.504Z
 -->
 
 # @molecule/api-ai-tools
@@ -197,6 +197,23 @@ interface CutRun {
 }
 ```
 
+#### `RunFailureClass`
+
+One failure a runner printed, classified by the layer that failed.
+
+```typescript
+interface RunFailureClass {
+  /** The layer that failed. */
+  kind: RunFailureKind
+  /** For a `connection` failure, what the transport did. */
+  connection?: ConnectionFailureKind
+  /** How long the request waited before the transport gave up, in seconds, when printed. */
+  seconds?: number
+  /** The `file:line` the runner printed for the failure, when it printed one. */
+  at?: string
+}
+```
+
 #### `NormalizableSchema`
 
 The JSON-Schema-ish shape every tool in this package declares.
@@ -313,8 +330,43 @@ interface TraceRequest {
   method: string
   /** The request's path (`/api/articles/x/favorite`), or the whole URL when it is cross-origin. */
   path: string
-  /** The response status, or 0 when the request never got a response. */
+  /**
+   * The response status as the trace recorded it. Playwright writes `-1` when a request was never
+   * answered (its HAR entry starts at `-1` and only a response event overwrites it); `0` is the
+   * same absence when the snapshot carried no response at all. Neither is a server failure.
+   */
   status: number
+  /**
+   * Playwright's own error text for a request that failed WITHOUT a response
+   * (`net::ERR_CONNECTION_REFUSED`) — a real failure. A request that got no response and recorded
+   * no text was aborted or still in flight when the test ended (the page closed under it), so it
+   * says nothing about the server (xr-molecule-flash-m112 +30:45).
+   */
+  failure?: string
+  /**
+   * What the page SENT, for a 4xx answered by the app's own API — bounded (see
+   * {@link MAX_TRACED_BODY_CHARS}). A body wrapped as `{"data":{…}}` is visible here in one line:
+   * app-http's verbs take the body as their second argument, so a helper that passes
+   * `{ data: body }` there ships the wrapper (xr-molecule-flash-m111 +11:36).
+   */
+  sent?: string
+  /** What came back for that 4xx, bounded the same way — the API's own error body. */
+  got?: string
+}
+```
+
+#### `TraceAction`
+
+One action the traced page performed, with the trace's own timing for it.
+
+```typescript
+interface TraceAction {
+  /** The Playwright API the entry names: `Frame.goto`, `Locator.fill`, `Locator.click`. */
+  api: string
+  /** When the action started, on the trace's own monotonic clock (ms). */
+  start: number
+  /** When it finished, or null when the run ended before it did. */
+  end: number | null
 }
 ```
 
@@ -332,6 +384,12 @@ interface TraceArtifact {
   requests: TraceRequest[]
   /** The console errors and page errors the page raised. */
   console: string[]
+  /**
+   * The page's own actions in the order the trace recorded them, bounded — what a test that ran
+   * out of a per-test budget spends its time on. A test that repeats one action prints it once per
+   * repeat, so the gap between two starts is one repeat's measured cost.
+   */
+  actions: TraceAction[]
 }
 ```
 
@@ -685,6 +743,20 @@ interface FailureCause {
    * for a duration group, whose blocks carried no bodies.
    */
   evidence: string[]
+  /**
+   * The suite's own per-test budget in ms, when the cause is the test-budget kill
+   * (`Test timeout of 15000ms exceeded`). The signature normalizes the number away
+   * ({@link normalizedSignature}) so equal causes group, and that number is the one fact that
+   * predicts a test spending its budget on a repeated action (xr-molecule-flash-m110 +20:44).
+   */
+  budgetMs?: number
+  /**
+   * The layer the failure came from ({@link classifyRunFailure}). A `connection` cause never
+   * reached the app, so it is NOT a cause the app's code can fix: the note says to re-run it
+   * once and read the app's log on a repeat, instead of sending a fix at a handler
+   * (xr-molecule-flash-m110 +18:42 rewrote a CORS middleware for a 20 s connection timeout).
+   */
+  kind: RunFailureKind
 }
 ```
 
@@ -716,6 +788,23 @@ type CutBy =
   | 'process-stop'
 ```
 
+#### `RunFailureKind`
+
+The layer a failure came from: the transport (no answer at all), the response's status, or an
+assertion over a response that arrived.
+
+```typescript
+type RunFailureKind = 'connection' | 'status' | 'assertion'
+```
+
+#### `ConnectionFailureKind`
+
+What the transport did when a request never got an answer.
+
+```typescript
+type ConnectionFailureKind = 'timeout' | 'refused' | 'reset' | 'dns' | 'tls' | 'empty'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -1001,6 +1090,36 @@ function cutRunSentence(run: CutRun): string
 
 **Returns:** The sentence.
 
+#### `classifyRunFailure(text)`
+
+Classify ONE failure's text — a Hurl `error:` block, or a Playwright failure message/body.
+
+The transport is read first: a block that carries a connection error AND an assertion is a
+request whose assertion never ran, so it is a connection failure. Only a block that carries no
+failure signature at all answers null — unknown is never a connection failure, because a
+misread transport hides a real app failure behind "just re-run it".
+
+```typescript
+function classifyRunFailure(text: string): RunFailureClass | null
+```
+
+- `text` — One failure's text, as the runner printed it.
+
+**Returns:** The classification, or null when the text carries no failure this reads.
+
+#### `allConnectionFailures(failures)`
+
+Whether every one of the classified failures is a connection failure — the only shape in which
+no response the app produced was measured.
+
+```typescript
+function allConnectionFailures(failures: readonly (RunFailureClass | null)[]): boolean
+```
+
+- `failures` — The run's classifications, in printed order.
+
+**Returns:** True when there is at least one and none of them is the app's.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -1160,24 +1279,68 @@ function suiteCommandTarget(command: string): string
 
 **Returns:** The target key.
 
-#### `scopedRerunCommand(command, locations, excluded)`
+#### `namesSuiteConfig(command)`
+
+Whether a Playwright statement names its own config — the reading {@link withSuiteConfig} and
+{@link scopedRerunCommand} share, so neither adds a second `--config` to a command that has one.
+
+```typescript
+function namesSuiteConfig(command: string): boolean
+```
+
+- `command` — A command, or the Playwright statement inside it.
+
+**Returns:** True when the statement loads a config of its own.
+
+#### `withSuiteConfig(command, config)`
+
+The command with a `--config` added to the Playwright invocation it starts — or unchanged when
+it already names one, or starts no Playwright run.
+
+The flag rides the same statement the runner does: a `cd`, an env prefix and a `timeout` before
+it are left exactly as they were, and so is everything chained after the run (`| tail -50`).
+
+xr-molecule-flash-m113 (+19:09): the model's fix-round re-run dropped the
+`--config playwright.conduit.config.ts` both earlier runs had carried, so Playwright started with
+NO base URL and all 10 failures were `page.goto: Cannot navigate to invalid URL` — a failure list
+that says nothing about the app. The platform composes commands back to the executor too (the
+narrowed re-run of a finished run's failures), and a command it hands back has to carry the
+config the run was measured under, never the shape that caused that finding.
+
+```typescript
+function withSuiteConfig(command: string, config: string | null | undefined): string
+```
+
+- `command` — The command as the executor sent it.
+- `config` — The config the run loads, when the caller knows it.
+
+**Returns:** The command with the flag, or the command unchanged.
+
+#### `scopedRerunCommand(command, locations, excluded, config)`
 
 The whole-suite command made scoped to the tests it should re-run instead: the same
 invocation — same directory, same settings — with the named `file:line`s in place of the whole
 suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
 `--retries=0` set (a re-run of a known failure does not need to pay for retries).
 
+`config` is the config the run was measured under ({@link withSuiteConfig}): the narrowed re-run
+carries it whenever the command itself does not, so a run that dropped `--config` cannot be
+handed back a command with the same defect (xr-molecule-flash-m113: every failing test was
+`Cannot navigate to invalid URL` because the re-run loaded no base URL).
+
 ```typescript
 function scopedRerunCommand(
   command: string,
   locations: readonly string[],
   excluded?: readonly string[],
+  config?: string | null,
 ): string
 ```
 
 - `command` — The whole-suite run's command.
 - `locations` — The failing `file:line`s to re-run, as the run's own log printed them — or, for a run that started outside the suite, the absolute form Playwright matches each file argument against.
 - `excluded` — The test titles the request carves out. They are inverted out (`--grep-invert`) so a re-run of the failing locations cannot report one of them again — xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about a test the request had already said does not count.
+- `config` — The config the run loaded, when the caller knows it; added when the command does not name one.
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
@@ -1395,10 +1558,17 @@ on `unzip` would make the read fail on every sandbox that has none. The zip is r
 central directory and `zlib.inflateRawSync` — about forty lines, and the only thing that has to
 be true of a `trace.zip` is that it IS one.
 
-A request is kept over a static asset when it failed (`status >= 400`) or never answered
-(`status === 0`), and over anything else when it is the page talking to the app
-(`fetch`/`xhr`/`document`): a failing test's trace holds the whole page load, and the answer is
-always at the end of it.
+A request is kept over a static asset when it failed — a `status >= 400`, or no response at all
+together with Playwright's own error text (`-1` plus `_failureText`, a refused connection) — and
+over anything else when it is the page talking to the app (`fetch`/`xhr`/`document`): a failing
+test's trace holds the whole page load. A request with no response and NO error text was aborted
+or still in flight when the test ended; it is kept too, but as what it is, not as a failure.
+
+A request answered 4xx by the app's OWN API also keeps what the page SENT and the first of what
+came back: Playwright stores either inline (`text`) or in a resource entry (`_file`), and both
+are read. That is where a wrapped body shows: xr-molecule-flash-m111's helper passed
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
 
 ```typescript
 function traceArtifactsScript(): string
@@ -1421,7 +1591,7 @@ function parseTraceArtifacts(stdout: string): TraceArtifact[]
 
 **Returns:** One entry per trace it printed.
 
-#### `failureTraceNote(items, target)`
+#### `failureTraceNote(items, target, earlierFailures)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
 what came back.
@@ -1432,14 +1602,34 @@ with them: read the handler the route reaches, not the selector. It is BOUNDED t
 {@link MAX_TRACE_NOTE_TESTS} tests with {@link MAX_TRACE_NOTE_REQUESTS} requests each, because it
 rides in a result the model pays for.
 
+The three kinds are kept apart, because they mean different things. A FAILED request (4xx/5xx, or
+a network error with Playwright's own text) is a cause. A request with NO RESPONSE RECORDED —
+Playwright's `-1`, no error text — was still in flight when the test ended (the page closed under
+it); listing it as a failure sent a run hunting an API that never answered anything wrong
+(xr-molecule-flash-m112 +30:45). The rest are the page's last answered requests.
+
+A 4xx request carries what the page SENT beside its status, so a wrapped body is visible in one
+line rather than inferred from the status; when one of those bodies is an object whose only key
+is `data`, the note names the call shape that produces it (xr-molecule-flash-m111 +11:36).
+
+WHICH rows it spends is evidence, not artifact order (xr-molecule-flash-m112 +53:46): a row
+needs a recorded response, a real failure or a console error ({@link traceRowEvidence}), rows are
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
+
 ```typescript
-function failureTraceNote(items: readonly TraceArtifact[], target: string): string | null
+function failureTraceNote(
+  items: readonly TraceArtifact[],
+  target: string,
+  earlierFailures?: readonly string[],
+): string | null
 ```
 
 - `items` — The traces {@link parseTraceArtifacts} read.
 - `target` — Where the run went — the deployed host, as the note names it.
+- `earlierFailures` — The failing `file:line`s earlier walks of this suite left, so a repeat is ranked above a one-off. Empty when the caller knows of no earlier walk.
 
-**Returns:** The note, or null when no trace held a request or a console error.
+**Returns:** The note, or null when no trace held a recorded response, a real failure or a console error.
 
 #### `suiteRecordsTraces(configText)`
 
@@ -2382,17 +2572,21 @@ the caller knows how the run was started, the note also hands over the narrowed
 exactly those tests ({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the
 whole suite.
 
+A run whose failures are ALL {@link NO_BASE_URL_ERROR} is not a set of causes at all: it is one
+configuration failure, said in one line ({@link noBaseUrlConfigNote}) rather than a list that
+reads as ten defects in the app.
+
 ```typescript
 function failureCausesNote(
   log: string,
   excluded?: readonly string[],
-  run?: { command: string; cwd?: string; log?: string },
+  run?: { command: string; cwd?: string; log?: string; config?: string | null },
 ): string | null
 ```
 
 - `log` — The finished run's output.
 - `excluded` — The test titles the request carves out, if the caller knows them.
-- `run` — How the run was started, when the caller knows it: the narrowed re-run is built from `command`/`cwd`, and `log` (the path the output was written to) is what the "left out" sentence greps when more causes exist than the result has room for.
+- `run` — How the run was started, when the caller knows it: the narrowed re-run is built from `command`/`cwd`/`config`, and `log` (the path the output was written to) is what the "left out" sentence greps when more causes exist than the result has room for.
 
 **Returns:** The note, or null.
 
@@ -2411,13 +2605,13 @@ the same app and database, and that is exactly what is refused while the run wal
 
 ```typescript
 function rerunOfRunningSuite(
-  run: { command: string; cwd?: string },
+  run: { command: string; cwd?: string; config?: string | null },
   locations: readonly string[],
   excluded?: readonly string[],
 ): string | null
 ```
 
-- `run` — The run in flight: the command it was started with, as it was run, and the directory that command ran in.
+- `run` — The run in flight: the command it was started with, as it was run, the directory that command ran in, and the config it loaded when the caller knows it.
 - `locations` — The failing `file:line`s to re-run, as the run's log printed them.
 - `excluded` — The test titles the request carves out: the re-run inverts them out (`--grep-invert`) so it cannot report them again.
 
@@ -2622,6 +2816,22 @@ How many console errors one test's trace contributes.
 const MAX_TRACED_CONSOLE: 4
 ```
 
+#### `MAX_TRACED_ACTIONS`
+
+How many of the page's own actions one test's trace contributes, the LAST ones.
+
+```typescript
+const MAX_TRACED_ACTIONS: 40
+```
+
+#### `MAX_TRACED_BODY_CHARS`
+
+How much of a 4xx request's sent body (or its response body) the trace read keeps.
+
+```typescript
+const MAX_TRACED_BODY_CHARS: 300
+```
+
 #### `MAX_TRACE_NOTE_TESTS`
 
 How many tests the note in a run's result names.
@@ -2646,6 +2856,22 @@ How long a URL the note prints, before the middle is cut.
 const TRACE_NOTE_URL_CHARS: 96
 ```
 
+#### `TRACE_NOTE_SENT_CHARS`
+
+How much of the sent body the note prints — enough to see a `{"data":…}` wrapper.
+
+```typescript
+const TRACE_NOTE_SENT_CHARS: 160
+```
+
+#### `TRACE_NOTE_GOT_CHARS`
+
+How much of the response body the note prints — the API's first error line.
+
+```typescript
+const TRACE_NOTE_GOT_CHARS: 120
+```
+
 #### `DIAGNOSIS_TRACE_FLAG`
 
 The `--trace` flag this platform adds, and the only value it adds it with.

package/dist/failure-kind.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What a failing request actually hit, read off the runner's own output.
+ *
+ * Three layers fail in three different ways, and only one of them is the app's code:
+ *
+ * - **connection** — the request never got an answer at all: the transport timed out, was
+ *   refused, reset, or could not resolve the name or negotiate TLS. Nothing about a handler,
+ *   a header or CORS was measured, so a re-run is the only thing that tells a cold start (a
+ *   machine deployed minutes ago whose boot finishes after the URL is live) from a real outage.
+ * - **status** — a response arrived and the HTTP status disagreed with what the suite asserts.
+ * - **assertion** — a response arrived and an assertion over its body failed.
+ *
+ * X0 xr-molecule-flash-m110 (+18:42 → +20:09) is the case this exists for: one Hurl file on the
+ * freshly deployed URL failed with `(28) Operation timed out … 0 bytes received` while the other
+ * twelve passed and 138 requests executed, and every note on the result read it as an assertion.
+ * The executor rewrote a CORS middleware, bisected a second server and latency-compared the two,
+ * then re-ran the same file — which passed in 3 s. A single re-run was the whole fix, and the one
+ * fact that would have said so is the failure's LAYER.
+ *
+ * ONE classifier, used by the causes note ({@link ./utilities.ts} `failureCausesNote`) and by the
+ * platform's own proof result (`molecule-dev` `suite-proof.ts`), so the two can never disagree
+ * about whether a failure was the app's to fix.
+ *
+ * @module
+ */
+/**
+ * The layer a failure came from: the transport (no answer at all), the response's status, or an
+ * assertion over a response that arrived.
+ */
+export type RunFailureKind = 'connection' | 'status' | 'assertion';
+/** What the transport did when a request never got an answer. */
+export type ConnectionFailureKind = 'timeout' | 'refused' | 'reset' | 'dns' | 'tls' | 'empty';
+/** One failure a runner printed, classified by the layer that failed. */
+export interface RunFailureClass {
+    /** The layer that failed. */
+    kind: RunFailureKind;
+    /** For a `connection` failure, what the transport did. */
+    connection?: ConnectionFailureKind;
+    /** How long the request waited before the transport gave up, in seconds, when printed. */
+    seconds?: number;
+    /** The `file:line` the runner printed for the failure, when it printed one. */
+    at?: string;
+}
+/**
+ * Classify ONE failure's text — a Hurl `error:` block, or a Playwright failure message/body.
+ *
+ * The transport is read first: a block that carries a connection error AND an assertion is a
+ * request whose assertion never ran, so it is a connection failure. Only a block that carries no
+ * failure signature at all answers null — unknown is never a connection failure, because a
+ * misread transport hides a real app failure behind "just re-run it".
+ *
+ * @param text - One failure's text, as the runner printed it.
+ * @returns The classification, or null when the text carries no failure this reads.
+ */
+export declare function classifyRunFailure(text: string): RunFailureClass | null;
+/**
+ * Whether every one of the classified failures is a connection failure — the only shape in which
+ * no response the app produced was measured.
+ *
+ * @param failures - The run's classifications, in printed order.
+ * @returns True when there is at least one and none of them is the app's.
+ */
+export declare function allConnectionFailures(failures: ReadonlyArray<RunFailureClass | null>): failures is ReadonlyArray<RunFailureClass & {
+    kind: 'connection';
+}>;
+//# sourceMappingURL=failure-kind.d.ts.map

package/dist/failure-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-kind.d.ts","sourceRoot":"","sources":["../src/failure-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAA;AAElE,iEAAiE;AACjE,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAA;AAE7F,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,cAAc,CAAA;IACpB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,qBAAqB,CAAA;IAClC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AA0ED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAoBvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,aAAa,CAAC,eAAe,GAAG,IAAI,CAAC,GAC9C,QAAQ,IAAI,aAAa,CAAC,eAAe,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAErE"}

package/dist/failure-kind.js

@@ -0,0 +1,134 @@
+/**
+ * What a failing request actually hit, read off the runner's own output.
+ *
+ * Three layers fail in three different ways, and only one of them is the app's code:
+ *
+ * - **connection** — the request never got an answer at all: the transport timed out, was
+ *   refused, reset, or could not resolve the name or negotiate TLS. Nothing about a handler,
+ *   a header or CORS was measured, so a re-run is the only thing that tells a cold start (a
+ *   machine deployed minutes ago whose boot finishes after the URL is live) from a real outage.
+ * - **status** — a response arrived and the HTTP status disagreed with what the suite asserts.
+ * - **assertion** — a response arrived and an assertion over its body failed.
+ *
+ * X0 xr-molecule-flash-m110 (+18:42 → +20:09) is the case this exists for: one Hurl file on the
+ * freshly deployed URL failed with `(28) Operation timed out … 0 bytes received` while the other
+ * twelve passed and 138 requests executed, and every note on the result read it as an assertion.
+ * The executor rewrote a CORS middleware, bisected a second server and latency-compared the two,
+ * then re-ran the same file — which passed in 3 s. A single re-run was the whole fix, and the one
+ * fact that would have said so is the failure's LAYER.
+ *
+ * ONE classifier, used by the causes note ({@link ./utilities.ts} `failureCausesNote`) and by the
+ * platform's own proof result (`molecule-dev` `suite-proof.ts`), so the two can never disagree
+ * about whether a failure was the app's to fix.
+ *
+ * @module
+ */
+/**
+ * Transport-level failures, most specific first: the patterns curl/Hurl and Chromium/Node print
+ * for a request that never got an answer. A message can carry more than one (`page.goto: Timeout
+ * 30000ms exceeded … net::ERR_CONNECTION_REFUSED`), and the more specific reading wins.
+ */
+const CONNECTION_FAILURES = [
+    // Hurl/curl's numbered errors (curl's exit codes, printed as `(28) Operation timed out …`).
+    ['empty', /\(\s*52\)\s*Empty reply from server/],
+    ['timeout', /\(\s*28\)\s*Operation timed out|Operation timed out after \d+/],
+    ['dns', /\(\s*6\)\s*Could not resolve host|Could not resolve host/],
+    [
+        'tls',
+        /\(\s*(?:35|51|58|59|60|77|83|90|91)\)\s|SSL connect error|SSL certificate problem|self[- ]signed certificate|UNABLE_TO_VERIFY_LEAF_SIGNATURE|CERT_HAS_EXPIRED/i,
+    ],
+    [
+        'refused',
+        /\(\s*7\)\s*(?:Failed to connect|Couldn't connect)|Failed to connect to\s|Couldn't connect to server/,
+    ],
+    ['reset', /\(\s*5[56]\)\s*(?:Recv|Send) failure|Connection reset by peer|socket hang up/],
+    // The browser's own net errors, and the Node errors underneath them.
+    ['timeout', /net::ERR_(?:CONNECTION_)?TIMED_OUT|\bETIMEDOUT\b/],
+    ['dns', /net::ERR_NAME_(?:NOT_RESOLVED|RESOLUTION_FAILED)|\bENOTFOUND\b|\bEAI_AGAIN\b/],
+    ['refused', /net::ERR_CONNECTION_REFUSED|\bECONNREFUSED\b/],
+    ['empty', /net::ERR_EMPTY_RESPONSE/],
+    ['reset', /net::ERR_CONNECTION_(?:RESET|CLOSED|ABORTED)|\bECONNRESET\b/],
+    ['tls', /net::ERR_(?:CERT|SSL|BAD_SSL)\w*/i],
+];
+/** A status assertion: the response arrived and its code is what failed. */
+const STATUS_FAILURE = /^\s*error:\s*Assert status code\b|actual value is <\d{3}>|\bHTTP(?:\/[\d.]+)?\s+[1-5]\d{2}\b|Expected[: ]+[1-5]\d{2}\b|\.status\(\)/m;
+/** Any other assertion over a response that arrived. */
+const ASSERTION_FAILURE = /^\s*error:\s*Assert\b|\bAssertionError\b|\bexpect\(|\bExpected[: ]|\bReceived[: ]|\bjsonpath\b|^\s*Error:/m;
+/** Hurl's `--> file:line:col`, the location of the failing request or assertion. */
+const HURL_AT = /-->\s+(\S+?):(\d+)(?::\d+)?\s*$/m;
+/** A spec file and line, the location a Playwright block names. */
+const SPEC_AT = /([\w./~-]+\.(?:spec|test)\.[cm]?[jt]sx?):(\d+)(?::\d+)?/;
+/** How long a request waited, as curl prints it (`Operation timed out after 20002 milliseconds`). */
+const WAITED_MS = /Operation timed out after (\d+) milliseconds/;
+/** How long a request waited, as Playwright prints it (`Timeout 30000ms exceeded`). */
+const WAITED_PLAYWRIGHT = /(?<!Test )\bTimeout (\d+)ms exceeded/;
+/**
+ * The `file:line` a failure block names, when it names one.
+ *
+ * @param text - The failure block.
+ * @returns The location, or undefined when the block carries none.
+ */
+function failureLocation(text) {
+    const hurl = HURL_AT.exec(text);
+    if (hurl)
+        return `${hurl[1]}:${hurl[2]}`;
+    const spec = SPEC_AT.exec(text);
+    return spec ? `${spec[1]}:${spec[2]}` : undefined;
+}
+/**
+ * How long the request waited before it gave up, in seconds, when the runner printed it.
+ *
+ * @param text - The failure block.
+ * @returns The seconds, rounded, or undefined.
+ */
+function waitedSeconds(text) {
+    const ms = WAITED_MS.exec(text) ?? WAITED_PLAYWRIGHT.exec(text);
+    return ms ? Math.round(Number(ms[1]) / 1000) : undefined;
+}
+/**
+ * Classify ONE failure's text — a Hurl `error:` block, or a Playwright failure message/body.
+ *
+ * The transport is read first: a block that carries a connection error AND an assertion is a
+ * request whose assertion never ran, so it is a connection failure. Only a block that carries no
+ * failure signature at all answers null — unknown is never a connection failure, because a
+ * misread transport hides a real app failure behind "just re-run it".
+ *
+ * @param text - One failure's text, as the runner printed it.
+ * @returns The classification, or null when the text carries no failure this reads.
+ */
+export function classifyRunFailure(text) {
+    const body = String(text ?? '');
+    if (body.trim().length === 0)
+        return null;
+    for (const [connection, pattern] of CONNECTION_FAILURES) {
+        if (!pattern.test(body))
+            continue;
+        const result = { kind: 'connection', connection };
+        const at = failureLocation(body);
+        if (at !== undefined)
+            result.at = at;
+        const seconds = waitedSeconds(body);
+        if (seconds !== undefined)
+            result.seconds = seconds;
+        return result;
+    }
+    const at = failureLocation(body);
+    const kind = STATUS_FAILURE.test(body)
+        ? 'status'
+        : ASSERTION_FAILURE.test(body)
+            ? 'assertion'
+            : null;
+    if (kind === null)
+        return null;
+    return at === undefined ? { kind } : { kind, at };
+}
+/**
+ * Whether every one of the classified failures is a connection failure — the only shape in which
+ * no response the app produced was measured.
+ *
+ * @param failures - The run's classifications, in printed order.
+ * @returns True when there is at least one and none of them is the app's.
+ */
+export function allConnectionFailures(failures) {
+    return failures.length > 0 && failures.every((failure) => failure?.kind === 'connection');
+}

package/dist/index.d.ts

@@ -134,6 +134,7 @@ export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
 export * from './cut-run.js';
+export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.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,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"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,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

@@ -134,6 +134,7 @@ export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
 export * from './cut-run.js';
+export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';