@molecule/api-ai-tools 1.11.1 → 1.13.0

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-21T08:55:11.822Z
+Generated: 2026-10-22T00:38:26.332Z
 -->
 
 # @molecule/api-ai-tools
@@ -360,6 +360,101 @@ interface RunnerOutputFilter {
 }
 ```
 
+#### `PlaywrightReportAttachment`
+
+One artifact the runner saved for one test, as the report records it.
+
+```typescript
+interface PlaywrightReportAttachment {
+  /** The attachment's name (`trace`, `screenshot`, …). */
+  name: string
+  /** Its media type, when the runner recorded one. */
+  contentType: string | null
+  /** Where the runner saved it, as the report wrote the path. */
+  path: string
+}
+```
+
+#### `PlaywrightReportTest`
+
+One failing (or flaky) test's identity and evidence, as the runner recorded them.
+
+The identity fields are Playwright's own — never reconstructed from printed headings — so a
+reader can tell exactly which test an attachment belongs to.
+
+```typescript
+interface PlaywrightReportTest {
+  /** The spec's stable id, when the report carries one. */
+  id: string | null
+  /** The Playwright project the test ran in. */
+  project: string | null
+  /** The spec file, relative to the config's root directory as the report writes it. */
+  file: string
+  /** The test's declaration line. */
+  line: number
+  /** The test's declaration column. */
+  column: number
+  /** The full title path (`['describe', …, 'test title']`), empty when none is readable. */
+  titlePath: string[]
+  /** The test's own title (the last entry of {@link titlePath}). */
+  title: string
+  /** Playwright's outcome for the test: `unexpected`, `flaky`, `skipped` or `expected`. */
+  status: string
+  /** How many attempts the runner made (1 when it was not retried). */
+  attempts: number
+  /** The retry index of the attempt whose evidence is reported (0 when not retried). */
+  retry: number
+  /** That attempt's own duration, in milliseconds. */
+  durationMs: number
+  /** That attempt's error message, bounded and redacted, or null. */
+  error: string | null
+  /** The artifacts the runner saved for THAT attempt — `trace` first. */
+  attachments: PlaywrightReportAttachment[]
+}
+```
+
+#### `PlaywrightReportStats`
+
+The runner's own tally, read straight from the report. Never a verdict this module derives.
+
+```typescript
+interface PlaywrightReportStats {
+  /** Tests that ended as expected. */
+  expected: number
+  /** Tests the runner skipped. */
+  skipped: number
+  /** Tests that did not end as expected. */
+  unexpected: number
+  /** Tests that failed and then passed on a retry. */
+  flaky: number
+  /** The run's own duration, in milliseconds. */
+  durationMs: number
+}
+```
+
+#### `PlaywrightRunReport`
+
+What one run's standard machine report says, bounded for a tool result.
+
+A reader that needs evidence this record does not carry reads {@link path} in the sandbox.
+
+```typescript
+interface PlaywrightRunReport {
+  /** How much of the report was read — see {@link PlaywrightReportStatus}. */
+  status: PlaywrightReportStatus
+  /** Where the report file is, for the full evidence. Always the runner's own file. */
+  path: string
+  /** One short phrase saying why a record is not `complete`, when it is not. */
+  reason?: string
+  /** The runner's tally, or null when the report did not carry one. */
+  stats: PlaywrightReportStats | null
+  /** The failing and flaky tests, in report order, bounded by {@link MAX_REPORTED_FAILURES}. */
+  failures: PlaywrightReportTest[]
+  /** How many failing tests did not fit the bound above. */
+  omittedFailures: number
+}
+```
+
 #### `ToolSchema`
 
 JSON-schema-backed definition for a single agent tool.
@@ -444,6 +539,35 @@ interface DiagnosisRunContext {
 }
 ```
 
+#### `DeferredToolCatalogOptions`
+
+Options for exposing a small tool set while retaining access to other allowed tools.
+
+```typescript
+interface DeferredToolCatalogOptions {
+  /** The caller's current permission/mode-filtered tools. Discovery never grants access. */
+  available: () => readonly AITool[]
+  /** Tools that should be offered without a discovery call. */
+  initialNames: ReadonlySet<string>
+  /** Previously loaded names, in load order; useful across turns and compaction. */
+  loadedNames?: readonly string[]
+  /** Persist names after a successful load. No tool content is passed to this callback. */
+  onLoad?: (names: string[]) => void
+}
+```
+
+#### `DeferredToolCatalog`
+
+A provider-independent deferred catalog. The caller still executes and authorizes tools.
+
+```typescript
+interface DeferredToolCatalog {
+  loader: AITool
+  /** Initial tools, loader, then requested tools in stable load order. */
+  select: () => AITool[]
+}
+```
+
 #### `InstalledPackageFacts`
 
 What the filesystem says about a write target under `node_modules` — the half
@@ -914,6 +1038,18 @@ interface TraceArtifact {
    * Absent when no group reached the threshold, and on traces read before this field existed.
    */
   repeated?: TraceRequestRepeat[]
+  /**
+   * The directory the trace was read from, relative to the root the reader was given.
+   *
+   * Playwright saves one directory per test attempt under the run's `outputDir`, and every artifact
+   * of that attempt — `trace.zip` included — sits in it. The run's own machine report records each
+   * test that wrote a trace with its attachment path, so this relative directory is the exact mark
+   * binding THIS artifact to the test that wrote it, with no join by spec line needed
+   * ({@link ./playwright-report.js}).
+   *
+   * Absent on traces read before this field existed.
+   */
+  dir?: string
 }
 ```
 
@@ -1533,6 +1669,23 @@ What the transport did when a request never got an answer.
 type ConnectionFailureKind = 'timeout' | 'refused' | 'reset' | 'dns' | 'tls' | 'empty'
 ```
 
+#### `PlaywrightReportStatus`
+
+How much of a report this module could account for.
+
+- `complete` — the runner's stats and its suite tree both parsed: every test entry is present.
+- `partial` — a report was written but is not a whole run (Playwright's own `errors` are present,
+  the suite tree is missing, or the file is past {@link MAX_REPORT_PARSE_CHARS}). What is listed
+  is real; what is missing must be read at {@link PlaywrightRunReport.path}.
+- `malformed` — the file exists but is not a Playwright JSON report (truncated, wrong shape).
+  Nothing in it may be treated as runner data.
+- `missing` — the run left no report (killed before `onEnd`, not a run this wrapper rewrote, or
+  the file was removed). Nothing may be inferred from its absence.
+
+```typescript
+type PlaywrightReportStatus = 'complete' | 'partial' | 'malformed' | 'missing'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -1763,6 +1916,43 @@ function statementArgumentEnd(
 
 **Returns:** The offset to write the option at, or null when the statement cannot be placed here.
 
+#### `statementBoundary(command, start, end)`
+
+Where a statement's own text ends, and whether it leaves a group open.
+
+A statement can be written inside a subshell or a brace group, and the tokenizer attaches an
+adjacent closer to its last word because no separator comes between them: `( … | tail -25)`
+parses its last stage as `tail` with the argument `-25)`. {@link LocatedCommandSegment.end}
+therefore says one past the `)`, and a caller cutting that stage out of the command takes the
+group's closer with it — the rewritten command is then `( … 2>&1`, which no shell parses
+(xr-molecule-flash-m418 +23:31: a heredoc config plus a parenthesized Playwright pipeline came
+back as `end of file unexpected` from the background runner).
+
+The parse's own group depths answer which closers belong to an enclosing group: the depth a
+statement was written at is its first character's depth (an opener is recorded at the depth
+BEFORE it opens), and every character of that statement's own words is at that depth or deeper.
+A closer at a LOWER depth closes a group opened before the statement, so it is not the
+statement's text. A character inside a quote (`-1`) is literal text and stops the walk: `grep
+'a)b'` ends on its own quote, not on a closer.
+
+The same depths answer the other dangerous cut: a stage that OPENS a group it does not close
+(`| { cat` when the `}` follows a `;`) has its closer outside the stage, so dropping the stage
+alone leaves that closer dangling.
+
+```typescript
+function statementBoundary(
+  command: string,
+  start: number | null,
+  end: number | null,
+): { textEnd: number; leavesGroupOpen: boolean } | null
+```
+
+- `command` — The shell command.
+- `start` — The statement's first character ({@link LocatedCommandSegment.start}).
+- `end` — One past the statement's last character ({@link LocatedCommandSegment.end}).
+
+**Returns:** The offset of the first character that is not the statement's own text, and whether the statement leaves a group it opened still open; null when it cannot be placed in this command.
+
 #### `commandTimeoutSeconds(command)`
 
 The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
@@ -2226,12 +2416,112 @@ function pipelineExitCodeNote(command: string, exitCode: number, output: string)
 
 **Returns:** One sentence naming the stage the code came from, or null.
 
+#### `reportCarriesIdentities(status)`
+
+The report statuses for which the report's own per-test identities and attachments may be used.
+
+`partial` is included because a partial report's suite tree, where it parsed, is still the
+runner's own record of which test owns which attachment; `malformed` and `missing` are not,
+because nothing about them is runner data.
+
+```typescript
+function reportCarriesIdentities(status: PlaywrightReportStatus): boolean
+```
+
+- `status` — One record's {@link PlaywrightReportStatus}.
+
+**Returns:** True when the record's tests and attachments are the runner's own.
+
+#### `reportTestAttachmentPaths(test)`
+
+The attachment paths a stored test record carries, `trace` first.
+
+```typescript
+function reportTestAttachmentPaths(test: PlaywrightReportTest): string[]
+```
+
+- `test` — One entry of {@link PlaywrightRunReport.failures}, as stored.
+
+**Returns:** Every saved path the record can prove, in its own order.
+
+#### `reportTestArtifactDir(test)`
+
+The directory a test result's own artifacts were saved in, or null when the report names none.
+
+Playwright writes one directory per test attempt under the run's `outputDir`, and every artifact
+of that attempt — `trace.zip` included — sits in it. The directory is therefore the exact
+ownership mark for a trace: two tests' traces are never in one another's directory. A damaged
+record whose attachment entries carry no path answers null, so nothing is claimed from it.
+
+```typescript
+function reportTestArtifactDir(test: PlaywrightReportTest): string | null
+```
+
+- `test` — One entry of {@link PlaywrightRunReport.failures}, as stored.
+
+**Returns:** The posix-normalized directory, or null.
+
+#### `summarizePlaywrightReport(text, options)`
+
+Summarize one Playwright `json` report into the bounded record a tool result carries.
+
+Pure text in, record out: the caller reads the file (and decides whether it may), so this is
+testable against genuine reports and against malformed controls alike.
+
+```typescript
+function summarizePlaywrightReport(
+  text: string,
+  options: { path: string; sanitize?: (text: string) => string },
+): PlaywrightRunReport
+```
+
+- `text` — The report file's text, exactly as written.
+- `options` — Where the file is, and the consumer's redactor for error text.
+- `options.path` — The report file's path, carried on the record for full evidence.
+- `options.sanitize` — Redactor applied to error text (defaults to the identity).
+
+**Returns:** The bounded record; never a verdict.
+
+#### `commandWritesReportTo(command, expectedPath)`
+
+The report path a command was launched with, when it is the one this platform sets.
+
+Read back from the launched script (and from a completed task's own command) so a record written
+before an API restart is still found: the path is the task's own id derived by
+{@link playwrightReportPathFor}, never a path parsed out of the executor's command.
+
+```typescript
+function commandWritesReportTo(command: string, expectedPath: string): boolean
+```
+
+- `command` — The command as it was launched.
+- `expectedPath` — The one path this task's report may be at.
+
+**Returns:** True when the command sets {@link PLAYWRIGHT_REPORT_ENV} to that exact path.
+
+#### `playwrightReportPathFor(taskId)`
+
+The report file a background task's own scratch files live beside.
+
+Derived from the task id, never from the command: the id is unique per launch, so two runs can
+never read one another's report, and the path survives a process restart the same way the task's
+log and exit file do.
+
+```typescript
+function playwrightReportPathFor(taskId: string): string
+```
+
+- `taskId` — The `mol-bg-…` handle the launch returned.
+
+**Returns:** The report file's absolute path.
+
 #### `startsServerProgram(command)`
 
 Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
 
 The over-budget reader's shape: at that point the command has already run, and only its text is
-left to say whether "run a smaller unit" was ever the right advice.
+left to say whether "run a smaller unit" was ever the right advice. Inline/stdin programs
+remain unclassified and use the normal bounded command runner.
 
 ```typescript
 function startsServerProgram(command: string): boolean
@@ -2244,7 +2534,9 @@ function startsServerProgram(command: string): boolean
 #### `foregroundServerCommand(command, readScript)`
 
 A FOREGROUND command that starts a server, including one that only names a script whose SOURCE
-imports the app's server and calls its `create()`/`listen()`.
+imports the app's server and calls its `create()`/`listen()`. Inline/stdin programs
+(`node -e …`, `python3 -c …`) use normal bounded execution: interpreting arbitrary
+program text is outside this filename/script preflight's contract.
 
 The script read is best-effort: a path the backend will not answer for is a command this reading
 cannot classify, never a refusal. A backgrounded launch, a test runner and a test file are all
@@ -2539,6 +2831,24 @@ function buildAgentPrompt(ctx: PromptContext): string
 
 **Returns:** Fully assembled system prompt text for the coding agent.
 
+#### `createDeferredToolCatalog(options)`
+
+Offer common tools and let the model load other schemas by exact name.
+
+This is ordinary allowlist selection, not semantic routing or authorization.
+Pass tools already filtered by the current mode and permissions. Loading never
+executes a tool; the caller must keep its normal execution-time guards. Loaded
+schemas append in request order and stay available, avoiding an LRU that changes
+the schema prefix on every request. Only names need persistence across turns.
+
+```typescript
+function createDeferredToolCatalog(options: DeferredToolCatalogOptions): DeferredToolCatalog
+```
+
+- `options` — Allowed tools, initial selection and optional durable load state.
+
+**Returns:** A loader tool and the current provider-facing selection.
+
 #### `taskStopCommand(backend, taskId)`
 
 The command that stops a running background task, read from the sandbox's own pid files.
@@ -2996,6 +3306,24 @@ function redactSecretsInCode(s: string): string
 
 **Returns:** A redacted copy that preserves ordinary code verbatim.
 
+#### `addedRedactionMask(next, previous)`
+
+The redaction mask `next` adds over `previous`, or null when it adds none.
+
+`previous` is the file's previous content for `write_file`, and the replacement's own
+`old_string` for `edit_file` — an edit that carries an existing mask through (a file that
+already had one, read back and rewritten) adds no occurrence. A new occurrence may
+be copied output or intentional source; the caller declares the latter explicitly.
+
+```typescript
+function addedRedactionMask(next: string, previous: string): string | null
+```
+
+- `next` — The content about to be written (or the replacement's `new_string`).
+- `previous` — The content it replaces, already on disk (or the `old_string`).
+
+**Returns:** The added mask as written (`'[REDACTED]'`, `"[REDACTED]"`, `=[REDACTED]`), or null.
+
 #### `printsOnlySource(command)`
 
 Whether a shell command only PRINTS source files (`cat a.tsx`, `sed -n '1,40p' x.ts`,
@@ -3012,6 +3340,35 @@ function printsOnlySource(command: string): boolean
 
 **Returns:** True when the command prints source files, with only literal headings and filters.
 
+#### `isReadOnlyInspection(command)`
+
+Whether a shell command only INSPECTS the workspace WITHOUT printing a file's contents:
+it prints source files (a pure literal read, {@link printsOnlySource}), lists names
+(`ls`, `find`), or counts lines (`wc`) — joined by `;`, `&&` or `|`, with literal
+`echo`/`printf` headings and `cd`.
+
+Its output is code or names, not an env dump, so it gets the code-safe redaction
+({@link redactSecretsInCode}) instead of the name-keyed env-dump passes. Without this,
+ordinary code values such as `tokenKey: 'jwtToken'` in a mixed source read and
+`ls | head` command would be masked by the environment-dump rules.
+
+A RECURSIVE SEARCH IS NOT INSPECTION (`grep -rn x .`, `rg x src/`): its output is the
+content of whichever files matched, including `.env` files and JSON secret dumps, so it
+keeps the full grade. A path with no extension is not evidence that it is a directory —
+`/dev/stdin` and an ordinary `secrets` file read the same way.
+
+Env dumps keep the full grade: `.env` anywhere in the command, `env`/`printenv`, a
+non-literal or redirecting form, and an interpreter one-liner (`node -e`, `python -c`)
+all return false.
+
+```typescript
+function isReadOnlyInspection(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when the command only reads or lists workspace content.
+
 #### `isEnvFilePath(path)`
 
 Whether a path is an env file, for which {@link redactSecrets}' full env-dump
@@ -3087,7 +3444,7 @@ function outputRedirectTarget(command: string): string | null
 
 **Returns:** The target, or null (`/dev/null` and `&1`/`&2` are not files).
 
-#### `streamingBackgroundCommand(command, context)`
+#### `streamingBackgroundCommand(command, context, reportPath)`
 
 Rewrite a command about to run in the background so its log grows while it
 runs. Two shapes left the log empty until exit, and an empty log is what
@@ -3116,13 +3473,44 @@ _(description truncated — read the full text in `node_modules/@molecule/api-ai
 function streamingBackgroundCommand(
   command: string,
   context?: DiagnosisRunContext,
-): { command: string; changes: string[]; error?: string }
+  reportPath?: string,
+): { command: string; changes: string[]; reportPath?: string; error?: string }
 ```
 
 - `command` — The command as the executor sent it.
 - `context` — What the caller knows beyond the command: the tests the person's request excludes by name ({@link DiagnosisRunContext}). A `--grep-invert` of exactly those is the request's own scope, not a diagnosis, so it keeps the suite's retries on a deployed proof (xr-molecule-flash-m170 +33:16).
+- `reportPath` — Where this run should write Playwright's standard `json` report, when the caller keeps one ({@link ./playwright-report.js}). The reporter is added to the run's own reporter set, never in place of one, and its output goes to that file through `PLAYWRIGHT_JSON_OUTPUT_FILE` — so the log, the executors' own reporters and every verdict stay exactly as they are. Omitted, or a run whose reporter set is not this function's to place (already names `json`, sets the variable itself, or whose runner cannot be located), leaves the command untouched and the result's `reportPath` unset.
+
+**Returns:** The command to run, one sentence per change made (empty when none), and the report path when one was actually wired — or `error` when the command starts the suite more than once.
 
-**Returns:** The command to run and one sentence per change made (empty when none), or `error` when the command starts the suite more than once.
+#### `withPlaywrightRunReport(command, reportPath)`
+
+Put Playwright's standard `json` report on a FOREGROUND run that already names its own reporters.
+
+A background run is rewritten onto the platform's reporter anyway ({@link
+streamingBackgroundCommand}), so adding the machine report there costs nothing. A foreground run
+is not: its reporters are either the command's own flags or the suite's config, and replacing a
+config reporter would stop writing the artifact the executor configured. So this only ever
+APPENDS `json` to a `--reporter` set the command already wrote — the log keeps every printing
+reporter it had, the executor's file reporters keep their place, and the standard report goes to
+{@link PLAYWRIGHT_REPORT_ENV}'s file.
+
+A command that names no reporter at all is left exactly as written: its reporters are the suite
+config's, and this tool does not rewrite those. A command that already names `json`, or sets
+`PLAYWRIGHT_JSON_OUTPUT_FILE` itself, already has a report of its own — a path the executor chose
+is never overwritten.
+
+```typescript
+function withPlaywrightRunReport(
+  command: string,
+  reportPath: string,
+): { command: string; reportPath: string | null }
+```
+
+- `command` — The command the executor sent, after every other rewrite.
+- `reportPath` — The file this run's machine report should be written to.
+
+**Returns:** The command to run and the report path when one was wired; `reportPath` is null when the run was left untouched and no report may be expected.
 
 #### `suiteRunStatements(command)`
 
@@ -3291,6 +3679,10 @@ run writes still holds every failure (xr-molecule-flash-m121 — a `| tail -5; e
 tail, and a 95-second walk's log held only the tally while the platform's own hold had handed
 that command back).
 
+The command around the dropped stages is left as written: a group they sit in keeps its closer
+(`( … | tail -25)` → `( … )`, never `( …` — xr-molecule-flash-m418 +23:31), and a stage the cut
+would leave a closer dangling inside is not dropped at all.
+
 ```typescript
 function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 ```
@@ -4288,6 +4680,59 @@ is a runaway detector, not a performance budget.
 const INLINE_SCRIPT_BUDGET_MS: 20000
 ```
 
+#### `PLAYWRIGHT_REPORT_ENV`
+
+The environment variable Playwright's built-in `json` reporter takes its output path from
+(`resolveOutputFile("JSON", …)`), resolved against the runner's own working directory. An
+absolute path is used here, so the file lands in the run's scratch area whatever directory the
+suite runs from.
+
+```typescript
+const PLAYWRIGHT_REPORT_ENV: 'PLAYWRIGHT_JSON_OUTPUT_FILE'
+```
+
+#### `PLAYWRIGHT_REPORT_SUFFIX`
+
+The file name a background task's report is written to, beside its own log.
+
+```typescript
+const PLAYWRIGHT_REPORT_SUFFIX: '.playwright.json'
+```
+
+#### `MAX_REPORT_PARSE_CHARS`
+
+How big a report may be before this module refuses to summarize it. The file stays readable at
+its path; the record only says so. A whole 139-test suite's report is well under a megabyte; a
+report past this is not one a tool result should carry.
+
+```typescript
+const MAX_REPORT_PARSE_CHARS: 8000000
+```
+
+#### `MAX_REPORTED_FAILURES`
+
+How many failing tests a record lists before the rest are counted in `omittedFailures`.
+
+```typescript
+const MAX_REPORTED_FAILURES: 12
+```
+
+#### `MAX_REPORTED_ATTACHMENTS`
+
+How many attachments one failing test keeps in the record (`trace` first).
+
+```typescript
+const MAX_REPORTED_ATTACHMENTS: 4
+```
+
+#### `MAX_REPORTED_ERROR_CHARS`
+
+How much of one failure's own error text the record keeps.
+
+```typescript
+const MAX_REPORTED_ERROR_CHARS: 400
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.
@@ -4310,7 +4755,10 @@ const BACKGROUNDED: RegExp
 A program that SERVES: the scaffold's entry (`server.ts`/`server.js`), a package manager's
 `start`/`dev`/`serve`/`preview` script, a Vite dev or preview server, `next start|dev`, or a
 Python WSGI server. Matched against a command segment's own text, and against a script's SOURCE
-when the command only names the script file.
+when the command only names the script file — but NEVER against an inline program's code
+(`node -e …`, `python3 -c …`), where this text is the user's program rather than a file being
+run: `require('…/node_modules/vite')` imports a module, it does not start a dev server
+(xr-molecule-flash-m391 +13:13, refused as "node starts a server" for exactly that line).
 
 ```typescript
 const SERVER_PROGRAM: RegExp
@@ -4915,6 +5363,11 @@ Peer dependencies:
   as a broken tool and routes around, taking its verification with it. Use
   `guardAITool` to give tools built elsewhere the same treatment, passing
   `redactError` so a thrown message is masked by your own redactor.
+- **Defer occasional tools** with `createDeferredToolCatalog`: pass your current
+  permission-filtered tools and a small initial name set, offer `catalog.select()`
+  to the model, and execute `catalog.loader` like any other tool. Loading only
+  exposes schemas, never grants permission or runs a tool. Persist its loaded
+  names with `onLoad` to keep them available across turns and compaction.
 - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
   should not receive `write_file`/`exec_command`.
 - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches

package/dist/command-position.d.ts

@@ -205,6 +205,39 @@ export declare function locatedCommandSegments(command: string): LocatedCommandS
  * @returns The offset to write the option at, or null when the statement cannot be placed here.
  */
 export declare function statementArgumentEnd(command: string, start: number | null, end: number | null): number | null;
+/**
+ * Where a statement's own text ends, and whether it leaves a group open.
+ *
+ * A statement can be written inside a subshell or a brace group, and the tokenizer attaches an
+ * adjacent closer to its last word because no separator comes between them: `( … | tail -25)`
+ * parses its last stage as `tail` with the argument `-25)`. {@link LocatedCommandSegment.end}
+ * therefore says one past the `)`, and a caller cutting that stage out of the command takes the
+ * group's closer with it — the rewritten command is then `( … 2>&1`, which no shell parses
+ * (xr-molecule-flash-m418 +23:31: a heredoc config plus a parenthesized Playwright pipeline came
+ * back as `end of file unexpected` from the background runner).
+ *
+ * The parse's own group depths answer which closers belong to an enclosing group: the depth a
+ * statement was written at is its first character's depth (an opener is recorded at the depth
+ * BEFORE it opens), and every character of that statement's own words is at that depth or deeper.
+ * A closer at a LOWER depth closes a group opened before the statement, so it is not the
+ * statement's text. A character inside a quote (`-1`) is literal text and stops the walk: `grep
+ * 'a)b'` ends on its own quote, not on a closer.
+ *
+ * The same depths answer the other dangerous cut: a stage that OPENS a group it does not close
+ * (`| { cat` when the `}` follows a `;`) has its closer outside the stage, so dropping the stage
+ * alone leaves that closer dangling.
+ *
+ * @param command - The shell command.
+ * @param start - The statement's first character ({@link LocatedCommandSegment.start}).
+ * @param end - One past the statement's last character ({@link LocatedCommandSegment.end}).
+ * @returns The offset of the first character that is not the statement's own text, and whether
+ *   the statement leaves a group it opened still open; null when it cannot be placed in this
+ *   command.
+ */
+export declare function statementBoundary(command: string, start: number | null, end: number | null): {
+    textEnd: number;
+    leavesGroupOpen: boolean;
+} | null;
 /**
  * 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.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;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;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAynBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;CACb;AAmFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;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":"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"}