@cerebriline/core 4.100.240

package/dist/extensions/tools/executors/document-extract.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Document Extract Executor
+ *
+ * Turns a document (PDF, Office old and new, OpenDocument, RTF, ebooks) into
+ * markdown or plain text, and writes the pictures inside it out as files.
+ * Pure JavaScript and WebAssembly only: it runs in the extension and the CLI
+ * alike, with no converter installed on the machine.
+ */
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import type { ExtractDocumentExecutor } from "../types";
+import type { DocumentReaderSettings } from "./document/ocr";
+import { type DescribeImages } from "./document/recognition";
+/** Where extractions go when the call names no `output_dir`. */
+export declare const DEFAULT_EXTRACTION_DIR: string;
+export interface DocumentExtractExecutorOptions {
+    /** The workspace; relative paths resolve against it and output stays in it. */
+    cwd?: string;
+    /** A delegated agent's overlay: reads fall through, writes stay private. */
+    overlay?: AgentOverlay;
+    /** @default 200 MB */
+    maxFileSizeBytes?: number;
+    /** The user's Document Reader settings: how scanned pages are read, and descriptions. */
+    reader?: DocumentReaderSettings;
+    /**
+     * The session's vision model (the Vision tab, or the CLI's
+     * `--vision-model`), when there is one: it reads scanned pages for
+     * `ocr: "vision"` and describes pictures.
+     */
+    describeImages?: DescribeImages;
+}
+/**
+ * The executor options a session's configuration gives the tool: the user's
+ * settings and the session's vision model. The same for the lead and every
+ * agent it delegates to, so a delegated agent reads a scan the way the lead
+ * would.
+ */
+export declare function documentReaderExecutorOptions(config: {
+    enableExtractDocument?: boolean;
+    documentReader?: DocumentReaderSettings;
+    describeImages?: DescribeImages;
+}): DocumentExtractExecutorOptions | undefined;
+/**
+ * Markdown as plain text: the words, without the markup.
+ *
+ * Pictures stay as a bracketed file name, because the file is where the
+ * picture went and the text around it may refer to it.
+ */
+export declare function markdownToText(markdown: string): string;
+/**
+ * The same tidy for every reader's markdown: heading ids (`{#intro}`), lines
+ * holding only indentation, and runs of blank lines. None of it is content,
+ * and all of it is tokens.
+ */
+export declare function tidyMarkdown(markdown: string): string;
+export declare function createDocumentExtractExecutor(options?: DocumentExtractExecutorOptions): ExtractDocumentExecutor;

package/dist/extensions/tools/executors/editor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Editor Executor
+ *
+ * Built-in implementation for filesystem editing operations.
+ */
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import type { EditorExecutor } from "../types";
+import { type ReadReceipts } from "./read-receipts";
+/**
+ * Options for the editor executor
+ */
+export interface EditorExecutorOptions {
+    /**
+     * File encoding used for read/write operations
+     * @default "utf-8"
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Restrict relative-path file operations to paths inside cwd.
+     * Absolute paths are always accepted as-is.
+     * @default true
+     */
+    restrictToCwd?: boolean;
+    /**
+     * Maximum number of diff lines in str_replace output
+     * @default 200
+     */
+    maxDiffLines?: number;
+    /**
+     * Shared record of what has been read, used to refuse an edit aimed at
+     * lines the model has never seen.
+     *
+     * Optional, and the guard is off when it is absent: an executor built on
+     * its own has no reader to pair with, and failing every edit would be the
+     * wrong default for an embedder wiring the tools up one at a time.
+     */
+    receipts?: ReadReceipts;
+    /**
+     * A delegated agent's private overlay. When present every path is resolved
+     * through it: edits copy the workspace file up and write the agent's copy,
+     * so the lead's tree is never touched. Absent for the lead itself.
+     */
+    overlay?: AgentOverlay;
+}
+/**
+ * Marker that opens every "this edit asks for nothing" refusal.
+ *
+ * Imported rather than copied wherever the outcome has to be recognised, so the
+ * detector cannot drift from the message. The loop tracker uses it: a call the
+ * tool has compared against the file and found identical is the one kind of
+ * failure that provably cannot succeed on a retry.
+ */
+export declare const NO_CHANGE_ERROR_PREFIX = "No change: ";
+/**
+ * Marker that opens every "this replacement would duplicate" refusal.
+ *
+ * The same kind of outcome as `NO_CHANGE_ERROR_PREFIX` and recognised the same
+ * way: both are reached by comparing the payload against the file, so both are
+ * answerable in advance for an identical retry. Only the no-op one was marked,
+ * which is why a duplicating edit took the ordinary six-strike ladder --
+ * measured live, the same 4,991-character replacement at line 84 seven times
+ * before the run was stopped.
+ */
+export declare const DUPLICATED_RANGE_ERROR_PREFIX = "Duplicated instead of replaced: ";
+/**
+ * Create an editor executor using Node.js fs module
+ */
+export declare function createEditorExecutor(options?: EditorExecutorOptions): EditorExecutor;

package/dist/extensions/tools/executors/file-locks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Serialise this process's own access to a file.
+ *
+ * There was no locking of any kind before this: `editor`, `sed -i` and the
+ * snapshot engine all called `fs.writeFile` directly, and `read_files` read
+ * directly. Two agents running in parallel could interleave anywhere, and the
+ * shape of the damage is not a torn byte — it is a lost update:
+ *
+ *   A reads the file        (100 lines)
+ *   B reads the file        (100 lines)
+ *   A writes its edit       (101 lines)
+ *   B writes its edit       (101 lines, built from what it read before A wrote)
+ *
+ * B's write is complete and well-formed and silently contains none of A's work.
+ * Nothing reports it, because nothing failed. An edit is a read-modify-write
+ * and its three steps have to be one step with respect to other writers, which
+ * is what this does.
+ *
+ * **In-process only, and that bound is the honest part.** A lock held in a Map
+ * says nothing to a second VS Code window, a `git` process, or the user's own
+ * editor. Those are caught after the fact by the file stamps in
+ * `read-receipts.ts` — the model is told its view is stale and made to look
+ * again — which is detection rather than exclusion. The two are complementary
+ * and neither replaces the other: this one prevents the race it can see, the
+ * stamps notice the one it cannot.
+ *
+ * **Why not an OS lock.** An advisory lock file would cover the cross-process
+ * case, and it brings the problem it is famous for: a crashed holder leaves a
+ * lock nobody will ever release, so it needs staleness detection, which needs a
+ * timeout, which is a guess that either deadlocks a slow write or breaks a
+ * correct one. The parallel agents this repository actually runs are in one
+ * process. The cross-process case is rarer, already detected, and not worth
+ * buying a class of hang for.
+ *
+ * Fair and FIFO: waiters are served in arrival order, because the chain is a
+ * promise chain. A lock is released even when the work throws — the failure
+ * path is the one where holding a lock forever would be worst.
+ */
+export declare function withFileLock<T>(filePath: string, run: () => Promise<T>): Promise<T>;
+/** Whether anything is queued for this path. For tests and diagnostics. */
+export declare function isFileLocked(filePath: string): boolean;

package/dist/extensions/tools/executors/file-read.d.ts

@@ -0,0 +1,136 @@
+/**
+ * File Read Executor
+ *
+ * Built-in implementation for reading files using Node.js fs module.
+ */
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import type { FileReadExecutor } from "../types";
+import { type ReadReceipts } from "./read-receipts";
+import type { ReadLedger } from "./unchanged-reads";
+/**
+ * Options for the file read executor
+ */
+export interface FileReadExecutorOptions {
+    /**
+     * Characters past which a read window is refused instead of returned.
+     * Defaults to {@link MAX_READ_REFUSAL_CHARS}. Raised by tests that need to
+     * exercise the windowing and line-counting paths, which still run for every
+     * read that fits.
+     */
+    maxReadChars?: number;
+    /**
+     * Ledger of what has already been returned, so an unchanged re-read can be
+     * answered with a pointer instead of a second copy. Omit and every read
+     * returns the content, which is the behaviour this had before.
+     */
+    readLedger?: ReadLedger;
+    /**
+     * Maximum file size to read in bytes
+     * @default 10_000_000 (10MB)
+     */
+    maxFileSizeBytes?: number;
+    /**
+     * File encoding
+     * @default "utf-8"
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Whether to include line numbers in output
+     * @default false
+     */
+    includeLineNumbers?: boolean;
+    /**
+     * The directory a relative path is resolved against.
+     *
+     * The workspace, not the process. These are the same thing only when the
+     * agent was launched from the directory it is working in, and in the two
+     * hosts that matter they are not: the extension host's `process.cwd()` is
+     * wherever VS Code was started, and the CLI takes its workspace as `--cwd`
+     * while running from wherever the shell was.
+     *
+     * Measured on a harness run started one directory above its workspace: a
+     * model that sends bare filenames -- `manic_miner.html` rather than the
+     * full path -- had 56 reads land in the parent and fail with ENOENT, then
+     * 19 edits refused because the file it was editing had never been read,
+     * then the loop guard stopped the run six times over. Three hours, four
+     * applied edits. Five earlier runs on a different model never saw it, for
+     * the single reason that that model always sent absolute paths.
+     *
+     * Falls back to `process.cwd()`, which is what this did unconditionally
+     * before, so an embedder that wires the executor up alone is unaffected.
+     */
+    cwd?: string;
+    /**
+     * Shared record of what has been read. Paired with the same object on the
+     * editor executor, this is what lets an edit require a prior read.
+     */
+    receipts?: ReadReceipts;
+    /**
+     * A delegated agent's private overlay. When present, a read resolves through
+     * it: the agent's own version if it wrote one, otherwise the lead's, and a
+     * file the agent deleted reads as absent.
+     */
+    overlay?: AgentOverlay;
+    /**
+     * Whether `extract_document` is offered beside this reader. A binary
+     * document (PDF, Office, OpenDocument, ebook) is never returned as text;
+     * this decides whether the explanation points at the tool or at the
+     * setting that turns it on.
+     */
+    documentReader?: boolean;
+}
+/** A read's text together with the line span it actually returned. */
+/**
+ * Where a read's lines come from.
+ *
+ * A path, for every read but one: the change protocol serves `revision:
+ * "base"` out of the transaction's snapshot, which is held in memory and has
+ * no path to stream from. Both go through the same windowing, so a base read
+ * is capped, numbered and reported exactly like the working read it exists to
+ * be compared against — a base revision that paginated differently would be
+ * unreadable next to the file it is a revision of.
+ */
+export type ReadTextSource = {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
+export interface ReadWindow {
+    text: string;
+    firstLine: number;
+    lastLine: number;
+}
+/**
+ * Create a file read executor using Node.js fs module
+ *
+ * @example
+ * ```typescript
+ * const readFile = createFileReadExecutor({
+ *   maxFileSizeBytes: 5_000_000, // 5MB limit
+ *   includeLineNumbers: true,
+ * })
+ *
+ * const content = await readFile({ path: "/path/to/file.ts" }, context)
+ * ```
+ */
+export declare function createFileReadExecutor(options?: FileReadExecutorOptions): FileReadExecutor;
+/**
+ * Window a string exactly as a read of the same file on disk would.
+ *
+ * For content that has no path to stream from — the change protocol's
+ * transaction snapshot, which holds what each file said when the transaction
+ * opened. Sharing the windowing with the disk path is the whole point: a base
+ * revision that numbered or truncated its lines differently could not be laid
+ * next to the working file, which is the only reason to read one.
+ */
+export declare function readTextWindowFromText(options: {
+    text: string;
+    includeLineNumbers?: boolean;
+    startLine?: number | null;
+    endLine?: number | null;
+    signal?: AbortSignal;
+    /** Defaults to {@link MAX_READ_REFUSAL_CHARS}, as the file executor does. */
+    maxReadChars?: number;
+}): Promise<ReadWindow>;

package/dist/extensions/tools/executors/grep.d.ts

@@ -0,0 +1,35 @@
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import { type ReadReceipts } from "./read-receipts";
+export interface GrepInput {
+    pattern: string;
+    /** Files or directories. Defaults to the working directory. */
+    paths?: string[];
+    /** `-i` */
+    ignore_case?: boolean;
+    /** `-v` */
+    invert?: boolean;
+    /** `-F`: the pattern is literal text. */
+    fixed?: boolean;
+    /** `-w`: match whole words only. */
+    word?: boolean;
+    /** `-E`: extended regular expressions. grep defaults to basic, and so does this. */
+    extended?: boolean;
+    /** `-c`: print a count per file instead of the matching lines. */
+    count?: boolean;
+    /** `-l`: print only the names of files with a match. */
+    files_with_matches?: boolean;
+    /** `-n`: prefix each line with its number. On by default, unlike grep. */
+    line_numbers?: boolean;
+    /** `-C`: lines of context either side. */
+    context?: number;
+    /** `-m`: stop after this many matches per file. */
+    max_count?: number;
+}
+export interface GrepExecutorOptions {
+    cwd?: string;
+    receipts?: ReadReceipts;
+    maxOutputChars?: number;
+    /** A delegated agent's overlay; grep walks and reads the merged view. */
+    overlay?: AgentOverlay;
+}
+export declare function createGrepExecutor(options?: GrepExecutorOptions): (input: GrepInput, callCwd?: string) => Promise<string>;

package/dist/extensions/tools/executors/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Built-in Executor Implementations
+ *
+ * This module provides ready-to-use implementations of the tool executors
+ * using Node.js built-in modules. These can be used directly or as references
+ * for custom implementations.
+ */
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import type { ToolExecutors } from "../types";
+import { type ApplyPatchExecutorOptions } from "./apply-patch";
+import { type AwkExecutorOptions } from "./awk";
+import { type ShellExecutorOptions } from "./bash";
+import { type DocumentExtractExecutorOptions } from "./document-extract";
+import { type EditorExecutorOptions } from "./editor";
+import { type FileReadExecutorOptions } from "./file-read";
+import { type GrepExecutorOptions } from "./grep";
+import { type ReadReceipts } from "./read-receipts";
+import { type SearchExecutorOptions } from "./search";
+import { type SedExecutorOptions } from "./sed";
+import { type WebFetchExecutorOptions } from "./web-fetch";
+export { type ApplyPatchExecutorOptions, computePatchChanges, createApplyPatchExecutor, type PatchFileChange, } from "./apply-patch";
+export { PATCH_MARKERS, PatchActionType } from "./apply-patch-parser";
+export { type AwkExecutorOptions, createAwkExecutor } from "./awk";
+export { CommandExitError, createShellExecutor, type ShellExecutorOptions, } from "./bash";
+export { DOCUMENT_EXTENSIONS } from "./document/formats";
+export { createDocumentExtractExecutor, DEFAULT_EXTRACTION_DIR, type DocumentExtractExecutorOptions, } from "./document-extract";
+export { createEditorExecutor, type EditorExecutorOptions } from "./editor";
+export { createFileReadExecutor, type FileReadExecutorOptions, } from "./file-read";
+export { createGrepExecutor, type GrepExecutorOptions } from "./grep";
+export { createReadReceipts, type ReadReceipts } from "./read-receipts";
+export { RunCommandExecutionController, type RunningCommandRegistration, } from "./run-command-execution-controller";
+export { createSearchExecutor, type SearchExecutorOptions } from "./search";
+export { createSedExecutor, type SedExecutorOptions } from "./sed";
+export { createReadLedger, REFRESH_EVERY, type ReadLedger, } from "./unchanged-reads";
+export { createWebFetchExecutor, type WebFetchExecutorOptions, } from "./web-fetch";
+/**
+ * Options for creating default executors
+ */
+export interface DefaultExecutorsOptions {
+    fileRead?: FileReadExecutorOptions;
+    search?: SearchExecutorOptions;
+    bash?: ShellExecutorOptions;
+    webFetch?: WebFetchExecutorOptions;
+    applyPatch?: ApplyPatchExecutorOptions;
+    editor?: EditorExecutorOptions;
+    grep?: GrepExecutorOptions;
+    sed?: SedExecutorOptions;
+    awk?: AwkExecutorOptions;
+    extractDocument?: DocumentExtractExecutorOptions;
+    /**
+     * Record of what has been read, shared by the reader and the editor.
+     * Supply one to observe it or to span several executor sets; omit it and
+     * each set gets its own, which is the right scope for a session.
+     */
+    receipts?: ReadReceipts;
+    /**
+     * A delegated agent's private overlay of the workspace. When present, every
+     * file executor — read, editor, apply_patch, grep, sed, awk — resolves its
+     * paths through it, so the agent's reads fall through to the lead's tree but
+     * its writes, deletes and renames stay in the overlay. Threaded here in one
+     * place on purpose: an executor left pointing at the real workspace is a
+     * silent escape, so the wiring is not left to each call site.
+     *
+     * The agent's shell commands are a separate concern: they are rooted at the
+     * native sandbox launcher via `bash.wrapSpawn`, and a caller that has no
+     * launcher for the platform withholds the shell rather than letting a command
+     * run against the workspace.
+     */
+    overlay?: AgentOverlay;
+}
+/**
+ * Create the default shell executor for the current platform.
+ *
+ * This is factored out from {@link createDefaultExecutors} so host integrations
+ * can reuse the SDK's cross-platform shell selection while supplying their own
+ * tool wrapper.
+ */
+export declare function createDefaultShellExecutor(options?: ShellExecutorOptions): import("..").ShellExecutor;
+/**
+ * Create all default executors with optional configuration
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultTools, createDefaultExecutors } from "@cerebriline/core"
+ *
+ * const executors = createDefaultExecutors({
+ *   bash: { timeoutMs: 60000 },
+ *   search: { maxResults: 50 },
+ * })
+ *
+ * const tools = createDefaultTools({
+ *   executors,
+ *   cwd: "/path/to/project",
+ * })
+ * ```
+ */
+export declare function createDefaultExecutors(options?: DefaultExecutorsOptions): ToolExecutors;

package/dist/extensions/tools/executors/line-endings.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Line-ending helpers shared by the file-writing executors (editor,
+ * apply_patch). Internal to the executors.
+ *
+ * Models emit LF-only text (reads strip "\r", so they never see a file's
+ * CRLF endings). Existing files keep their own detected EOL, but a new file
+ * has no EOL to preserve: use CRLF on Windows unless the content already
+ * contains a "\r" and thereby chose its own endings
+ * (github.com/cline/cline/issues/13504). No-op on LF platforms.
+ */
+export declare function normalizeNewFileLineEndings(content: string): string;
+export type LineEnding = "\r\n" | "\n";
+/**
+ * Returns "\r\n" if "\r\n" appears anywhere in the content, otherwise "\n" —
+ * including for content with no line breaks at all. Files are uniformly CRLF
+ * or uniformly LF in practice; the mixed case that matters is a CRLF file
+ * with LF-only lines inserted by earlier releases of these tools, and any
+ * surviving "\r\n" — wherever it sits — should pull such a file back to
+ * CRLF, which is why this checks for "\r\n" anywhere rather than looking at
+ * the first line break.
+ */
+export declare function detectLineEnding(content: string): LineEnding;
+export declare function normalizeLineEndings(text: string, eol: LineEnding): string;

package/dist/extensions/tools/executors/output-limits.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared caps for how much tool output may enter the conversation. Every
+ * character returned by an executor is re-sent to the model on each
+ * subsequent request, so oversized outputs cost quadratically over the
+ * remaining run. Limits are measured in characters (UTF-16 code units),
+ * which tracks token cost more closely than bytes and is what JS strings
+ * measure exactly. Executors enforce these caps; tool descriptions
+ * reference them so the model pages or narrows instead of retrying.
+ *
+ * Truncation notices always live in the preserved head/tail of an entry,
+ * never in the elided middle. Provider-request building may re-truncate
+ * long strings with its own (possibly tighter) middle-cut backstop
+ * (session/services/message-builder.ts); keeping the notices at the edges
+ * means the recovery guidance survives that cut too.
+ */
+/** Max characters of command output kept; beyond this the middle is elided. */
+export declare const MAX_COMMAND_OUTPUT_CHARS = 48000;
+export declare function truncateCommandOutput(text: string, options?: {
+    maxChars?: number;
+    totalChars?: number;
+}): string;
+/** Max lines returned per file read when the range is larger or absent. */
+export declare const MAX_READ_LINES = 2000;
+/** Max characters kept per line in file reads (defangs minified files). */
+export declare const MAX_LINE_CHARS = 2000;
+/** Max characters returned per file read window. */
+export declare const MAX_READ_OUTPUT_CHARS = 48000;
+/**
+ * The size past which a file read is refused rather than truncated.
+ *
+ * Truncation is the wrong answer for a read. A capped read hands back part of
+ * a file with a notice the model routinely ignores, and it then reasons about
+ * the file it was given as though it were the file that exists -- editing
+ * against line numbers it never saw. The cost is also permanent: a tool result
+ * is re-sent on every subsequent request, so one oversized read is paid for by
+ * the whole rest of the run, which is how a transcript reaches the compaction
+ * trigger in twenty turns.
+ *
+ * Refusing costs one turn and produces the read the model should have made.
+ * The message names `start_line`/`end_line`, points at grep, and says how many
+ * lines *would* fit, because a refusal that does not say what to do instead is
+ * just a failed call — and one that does not say how much is too much makes the
+ * model guess, invariably downwards.
+ *
+ * 24,000 chars is roughly 6,000 tokens: about 9% of a 65,536-token window, or
+ * an eighth of what is left of one after the fixed price. One read that size is
+ * affordable; a habit of them is what compaction is for.
+ *
+ * It was 2,048 in 4.100.138, which is around fifty lines of ordinary source —
+ * so a whole small file was refused, and the model answered the way the message
+ * invited it to: by crawling the file in tiny windows. Reported the same day as
+ * "a huge amount of small reads". The size to refuse is the one that costs a
+ * meaningful share of the window for the rest of the run, not the one that is
+ * larger than a screenful.
+ */
+export declare const MAX_READ_REFUSAL_CHARS = 24000;
+/** Max characters returned per search query; beyond this the middle is elided. */
+export declare const MAX_SEARCH_OUTPUT_CHARS = 48000;

package/dist/extensions/tools/executors/overlay-receipts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read receipts -- and what the agent is shown -- for a delegated agent
+ * working over an overlay.
+ *
+ * The agent reads a file where it currently lives -- the lead's workspace until
+ * the agent first writes it, its own overlay copy after -- and the editor
+ * checks the path it is about to write, which is always the overlay copy. Keyed
+ * by the raw path, the read and the edit are two different files: every first
+ * edit of an existing file was refused as "not read", and the refusal sent the
+ * agent to read the overlay path itself, a directory it was never meant to see.
+ *
+ * So every path is keyed by the workspace file it stands for, and the copy-up
+ * carries the read's stamp across: the copy is a new file on disk, and without
+ * this the stale-read guard reads its fresh mtime as someone else's write. The
+ * stamp moves only when the workspace file is still what the agent read -- if
+ * the lead changed it in between, the edit is refused as it should be.
+ */
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import { type ReadReceipts } from "./read-receipts";
+export declare function overlayReadReceipts(receipts: ReadReceipts, overlay: AgentOverlay): ReadReceipts;
+/**
+ * `executor`, with every path into the overlay in what it returns or throws
+ * rewritten to the workspace path it stands for. See {@link AgentOverlay.redact}.
+ */
+export declare function withoutOverlayPaths<F extends (...args: never[]) => Promise<unknown>>(executor: F, overlay: AgentOverlay): F;

package/dist/extensions/tools/executors/posix-regex.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Translate POSIX regular expressions into JavaScript ones.
+ *
+ * `grep`, `sed` and `awk` are being offered because a coding model already
+ * knows them — that is the whole reason they exist here rather than a bespoke
+ * search tool. Which means the *dialect* has to be the one it knows. A model
+ * that writes `sed 's/\(foo\)bar/\1/'` and gets a JavaScript regex error has
+ * learned that the tool is unreliable, and will go back to guessing with
+ * `editor`.
+ *
+ * Three dialects are in play and they disagree in ways that silently change
+ * what a pattern means, rather than failing loudly:
+ *
+ *   BRE (grep, sed by default)   `\(group\)`  `\{2,3\}`  `\|`  and a literal
+ *                                `(`, `)`, `{`, `}`, `+`, `?`, `|`
+ *   ERE (grep -E, sed -E, awk)   `(group)`    `{2,3}`    `|`   and a literal
+ *                                `\(`, `\)`
+ *   JavaScript                   ERE-like, but with no POSIX classes and
+ *                                different rules for an unescaped `{`
+ *
+ * So BRE's `a+` matches "a+" literally while ERE's matches one or more "a" —
+ * the same three characters, two different answers, no error either way. That
+ * is the class of bug this module exists to prevent.
+ */
+export interface PosixRegexOptions {
+    /** ERE (grep -E, sed -E, awk) rather than BRE (grep, sed). */
+    extended?: boolean;
+    /** Case-insensitive matching (`-i`, or an `I` flag on a sed `s///`). */
+    ignoreCase?: boolean;
+    /** Match whole words only (`grep -w`). */
+    wordBoundary?: boolean;
+    /** Treat the pattern as literal text (`grep -F`). */
+    fixed?: boolean;
+    /** Replace every occurrence rather than the first. */
+    global?: boolean;
+}
+/**
+ * Convert a POSIX pattern to JavaScript regex source.
+ *
+ * The two dialects are handled in one pass because they differ only in which
+ * characters carry the special meaning and which carry the literal one — in BRE
+ * a backslash *adds* meaning to `(){}|`, in ERE it *removes* it. Writing it
+ * twice would be two places for that inversion to drift.
+ */
+export declare function posixToJsSource(pattern: string, options?: PosixRegexOptions): string;
+/**
+ * Compile a POSIX pattern, reporting failures in the tool's own terms.
+ *
+ * A JavaScript `SyntaxError` quoting a translated pattern is unreadable to a
+ * model that wrote a POSIX one — it would be shown source it never typed.
+ */
+export declare function compilePosixRegex(pattern: string, options?: PosixRegexOptions): RegExp;