@cerebriline/core 4.100.274 → 4.100.277

package/dist/extensions/lsp/lsp-host.d.ts

@@ -0,0 +1,134 @@
+import type { HostFileDiagnostics } from "../diagnostics/types";
+import type { CodeIntelProvider } from "../tools/ask-lsp";
+import { type LspServerSpec } from "./lsp-connection";
+/**
+ * The language servers of a host that has no editor to ask.
+ *
+ * In the extension, `ask_lsp`, `check_file` and the post-edit report read VS
+ * Code, which already runs a server for every language in the workspace. A
+ * terminal runs none, so this resolves a server per language, starts it on
+ * the first question about a file of it, keeps it for the session, and keeps
+ * what it publishes as the editor keeps it.
+ *
+ * The tools' contract is what makes this tractable: an operation that cannot
+ * be answered returns nothing, and the tool says so plainly. So a language
+ * with no server installed is a quiet "no answer" rather than an error -- the
+ * same outcome the extension produces for a language whose extension the user
+ * never installed.
+ */
+/** LSP language ids, by the extension that implies them. */
+export declare const LANGUAGE_BY_EXTENSION: Readonly<Record<string, string>>;
+export declare function languageIdFor(filePath: string): string | undefined;
+/**
+ * A TypeScript installation this machine already has, for servers that need one.
+ *
+ * Only the globally installed one is considered: a workspace that has its own
+ * is found by the server without help, and this exists for the case where there
+ * is nothing to find. `tsserver.js` rather than the package root, because the
+ * 7.x `typescript` package is a native wrapper that ships no `tsserver` at all
+ * and would otherwise be handed over as if it were usable.
+ */
+export declare function findGlobalTypescriptLib(): string | undefined;
+/**
+ * What VS Code's HTML extension hands its server, and what it answers when
+ * the server asks: the script and the style of a page are checked as
+ * JavaScript and CSS. The server's script mode reads
+ * `js/ts.implicitProjectConfig` with no guard, so it is given VS Code's
+ * defaults rather than left to fail.
+ */
+export declare const HTML_SERVER_SETTINGS: Record<string, unknown>;
+/**
+ * The servers this host will try, and what each one answers for.
+ *
+ * Resolution is by what is actually on the machine: the first spec whose
+ * command exists and whose language list covers the file wins. Nothing is
+ * installed on demand -- a host that pulled down a language server mid-turn
+ * would be a surprise, and the tools degrade honestly without one. A host
+ * with its own install prefix (automaticum's runner) passes its own specs.
+ */
+export declare const DEFAULT_LSP_SERVERS: LspServerSpec[];
+/**
+ * Whether a command can be run, without running it.
+ *
+ * A PATH walk rather than `which`: spawning a shell to ask about ten servers
+ * costs more than reading ten directories, and this runs before the first
+ * question is answered.
+ */
+export declare function commandExists(command: string): boolean;
+/** Whether a spec's server is on this machine. */
+export declare function isServerInstalled(spec: LspServerSpec): boolean;
+export interface HtmlServerTypescriptGap {
+    /** Where the server reads TypeScript's `lib.*.d.ts` from. */
+    expected: string;
+    /** A TypeScript beside the server that would fill it, if there is one. */
+    typescript?: string;
+}
+/**
+ * Whether the HTML server of `vscode-langservers-extracted` will find
+ * TypeScript's library files.
+ *
+ * Its bundle (4.10.0) computes them as `<prefix>/node_modules/node_modules/
+ * typescript/lib` -- one `node_modules` too many -- so in a normal install
+ * they are never there, and a page's script is checked with no types: hover
+ * says `any`. Nothing the client sends changes the path. Returns the gap, or
+ * nothing when the server is not that one or the files are there.
+ */
+export declare function findHtmlServerTypescriptGap(spec: LspServerSpec): HtmlServerTypescriptGap | undefined;
+/**
+ * Fill the gap with a link to the TypeScript beside the server.
+ *
+ * Writes into the server's install prefix, so it is never done implicitly: a
+ * host calls this when its owner has said so (automaticum's image does the
+ * same at build time). Returns whether the link now exists.
+ */
+export declare function repairHtmlServerTypescript(gap: HtmlServerTypescriptGap): boolean;
+/** The languages of a workspace's files, looked for at most `limit` entries deep. */
+export declare function workspaceLanguages(root: string, limit?: number): string[];
+export interface LspServerStatus {
+    server: string;
+    languages: string[];
+    installed: boolean;
+    started?: boolean;
+    failed?: string;
+    /** Something the server needs that this machine lacks. */
+    warning?: string;
+}
+export interface LspHostOptions {
+    /** The workspace root the servers start in. */
+    cwd: string;
+    /** Tried in order; the first installed one for a language wins. */
+    servers?: LspServerSpec[];
+    onError?: (message: string, error: unknown) => void;
+    /** Whether a spec's server is installed. Defaults to a PATH/probe check. */
+    isInstalled?: (spec: LspServerSpec) => boolean;
+}
+export interface LspHost {
+    /** `ask_lsp`'s host half. */
+    provider: CodeIntelProvider;
+    /**
+     * Hand the file's server the file as it is on disk (`save`: as just
+     * written). Undefined when no server answers for it or it cannot be read.
+     */
+    touch(filePath: string, options?: {
+        save?: boolean;
+    }): Promise<{
+        languageId: string;
+    } | undefined>;
+    /** Whether an installed server answers for this file's language. */
+    serves(filePath: string): boolean;
+    /**
+     * Every file a server has reported on, with `pending` set when the file
+     * changed after the server last reported on it.
+     */
+    readDiagnostics(): Promise<HostFileDiagnostics[]>;
+    /** Start the servers for these languages (default: the workspace's) now. */
+    prewarm(languages?: string[]): string[];
+    /** Which server answers for which language, and in what state. */
+    status(): LspServerStatus[];
+    dispose(): Promise<void>;
+}
+/**
+ * The session's language servers, behind `ask_lsp`, `check_file` and the
+ * post-edit report.
+ */
+export declare function createLspHost(options: LspHostOptions): LspHost;

package/dist/extensions/tools/ask-lsp.d.ts

@@ -35,7 +35,7 @@ import { type AgentTool } from "@cerebriline/shared";
 export declare const ASK_LSP_TOOL_NAME = "ask_lsp";
 export declare const ASK_LSP_OPERATIONS: readonly ["definition", "references", "implementations", "type_definition", "hover", "document_symbols", "workspace_symbols", "callers"];
 export type AskLspOperation = (typeof ASK_LSP_OPERATIONS)[number];
-export declare const ASK_LSP_TOOL_DESCRIPTION = "Ask the language servers \u2014 the LSP \u2014 about a symbol. If you are reaching for an LSP tool or an MCP server that wraps one, this is it: the same protocol, already running against this workspace and its open files, with no server to start. This answers questions a text search cannot, because it understands the code: it distinguishes a definition from a mention, and this class's method from another class's method of the same name.\n\nUse this before falling back to `search_codebase` for anything about a symbol. It is faster, exact, and does not need you to read files to interpret the result.\n\nReach for it the moment you are about to do one of these by hand:\n- search for a name to find where it is defined -> `definition`\n- search for a name to find what uses it, or what would break -> `references` or `callers`\n- open a file just to read a signature, type or doc comment -> `hover`\n- scroll a file, or count brackets, to work out its structure -> `document_symbols`\n- grep the repo to find which file something lives in -> `workspace_symbols`\n\nOperations:\n- `definition` \u2014 where a symbol is defined.\n- `references` \u2014 every place it is actually used.\n- `implementations` \u2014 the classes or functions implementing an interface or abstract method.\n- `type_definition` \u2014 where the type of an expression is defined.\n- `hover` \u2014 the signature, type and documentation, as an editor shows on hover.\n- `document_symbols` \u2014 an outline of one file: its classes, functions and methods.\n- `workspace_symbols` \u2014 find a symbol by name across the whole project when you do not know which file it is in.\n- `callers` \u2014 what calls this function.\n\nHow to address a symbol:\n- Usually: `path` plus `symbol` \u2014 the name as it appears in that file.\n- If you know the exact position: `path`, `line` and `character` (both 1-based).\n- If you do not know the file: `symbol` alone, with `operation: \"workspace_symbols\"`.\n\nOutput: plain text, one result per line as `file:line:column` followed by that source line, so you can go straight to the one you want rather than reading each candidate. `hover` returns the signature and documentation as text instead, and `document_symbols` and `workspace_symbols` name each symbol's kind.\n\nAn empty answer is a real answer once the symbol resolved: for `definition`, `references`, `implementations`, `type_definition`, `callers` and `hover` the server understood the symbol and nothing matched, so a text search for the same question will not find more. `workspace_symbols` is the exception, and says so when it comes back empty: it reads a project-wide index that covers the languages a server is installed for and does not index script embedded in `.html` or other template files, so nothing there is not proof of nothing anywhere. And when the file does not parse, every answer about it opens with that line \u2014 while it is there, the server is answering from a partial parse and you are reading guesses.";
+export declare const ASK_LSP_TOOL_DESCRIPTION = "Ask the language servers \u2014 the LSP \u2014 about a symbol. If you are reaching for an LSP tool or an MCP server that wraps one, this is it: the same protocol, already running against this workspace and its open files, with no server to start. This answers questions a text search cannot, because it understands the code: it distinguishes a definition from a mention, and this class's method from another class's method of the same name.\n\nUse this before falling back to `search_codebase` for anything about a symbol. It is faster, exact, and does not need you to read files to interpret the result.\n\nReach for it the moment you are about to do one of these by hand:\n- search for a name to find where it is defined -> `definition`\n- search for a name to find what uses it, or what would break -> `references` or `callers`\n- open a file just to read a signature, type or doc comment -> `hover`\n- scroll a file, or count brackets, to work out its structure -> `document_symbols`\n- grep the repo to find which file something lives in -> `workspace_symbols`\n\nOperations:\n- `definition` \u2014 where a symbol is defined.\n- `references` \u2014 every place it is actually used.\n- `implementations` \u2014 the classes or functions implementing an interface or abstract method.\n- `type_definition` \u2014 where the type of an expression is defined.\n- `hover` \u2014 the signature, type and documentation, as an editor shows on hover.\n- `document_symbols` \u2014 an outline of one file: its classes, functions and methods.\n- `workspace_symbols` \u2014 find a symbol by name across the whole project when you do not know which file it is in.\n- `callers` \u2014 what calls this function.\n\nHow to address a symbol:\n- Usually: `path` plus `symbol` \u2014 the name as it appears in that file.\n- If you know the exact position: `path`, `line` and `character` (both 1-based).\n- If you do not know the file: `symbol` alone, with `operation: \"workspace_symbols\"`.\n\nOutput: plain text, one result per line as `file:line:column` followed by that source line, so you can go straight to the one you want rather than reading each candidate. `hover` returns the signature and documentation as text instead, and `document_symbols` and `workspace_symbols` name each symbol's kind.\n\nAn empty answer once the symbol resolved means the server understood the symbol and found nothing for it \u2014 within what it can see. It does not see uses it cannot resolve statically (`obj[name]`, a name built in a string, reflection), files it does not load, or other languages, so for `references` and `callers` above all, a text search can still find uses the server missed; run one when the answer decides an edit. `workspace_symbols` says so when it comes back empty too: it reads a project-wide index that covers the languages a server is installed for and does not index script embedded in `.html` or other template files, so nothing there is not proof of nothing anywhere. And when a JavaScript or HTML file does not parse, every answer about it opens with that line \u2014 while it is there, the server is answering from a partial parse and you are reading guesses. Other languages are not parsed here, so no such line is no promise for them.";
 /** Exported for the same reason as `CHECK_FILE_TOOL_INPUT_SCHEMA`. */
 export declare const ASK_LSP_TOOL_INPUT_SCHEMA: {
     readonly type: "object";

package/dist/extensions/tools/browser.d.ts

@@ -41,7 +41,7 @@ export declare const BROWSER_TOOL_NAME = "browser";
  * user. So the description says, in the place the model is standing when it is
  * about to ask, that the answer is available without them.
  */
-export declare const BROWSER_TOOL_DESCRIPTION = "Open a page in a real browser and report what it printed to the console and what it threw. This is how you check that a page works. Do not ask the user whether it works \u2014 open it and read the errors yourself.\n\nUse it after editing any HTML, CSS or JavaScript the page loads, and before reporting a task finished. `check_file` cannot answer this: no language server checks the script inside an `.html` file, and a file that parses can still throw the moment it runs.\n\nActions:\n- `open` \u2014 go to `url` and report the console output. Launches the browser on first use. A local file is a URL: pass the absolute path and it is converted for you.\n- `click` \u2014 click at `coordinate` (\"x,y\" in page pixels, from the screenshot).\n- `type` \u2014 type `text` at the current focus.\n- `scroll_down`, `scroll_up` \u2014 one viewport.\n- `close` \u2014 shut the browser down. Do this when finished with it.\n\nEvery action reports the console messages and uncaught errors produced while it ran, so a syntax error, a failed fetch or a null dereference comes back as text you can act on. `[error]` and `[Page Error]` lines are real failures. A page that says nothing printed nothing \u2014 that is a pass, not a failed call, and for a local file it is checked: a silent console over a file that does not parse is reported as the failure it is, not as a pass.\n\nA parse error from the browser names no line, because the script never ran. For a local file a `Delimiter scan` section follows it and names the line to edit and how many brackets that line is out by \u2014 one line per place the trouble starts, since a file can be broken in several spots at once. Fix every line it lists in one edit and reload once, rather than one edit and one reload per line. Edit those lines instead of counting brackets yourself: counting a whole file by hand costs more thinking than you have, and the scan skips strings, comments and regex literals, which counting does not.\n\nThe browser stays open between calls, so `open` once and then interact. Only one page is open at a time; `open` again to go elsewhere.";
+export declare const BROWSER_TOOL_DESCRIPTION = "Open a page in a real browser and report what it printed to the console and what it threw. This is how you check that a page works. Do not ask the user whether it works \u2014 open it and read the errors yourself.\n\nUse it after editing any HTML, CSS or JavaScript the page loads, and before reporting a task finished. `check_file` cannot answer this: no language server checks the script inside an `.html` file, and a file that parses can still throw the moment it runs.\n\nActions:\n- `open` \u2014 go to `url` and report the console output. Launches the browser on first use. A local file is a URL: pass the absolute path and it is converted for you.\n- `click` \u2014 click at `coordinate` (\"x,y\" in page pixels, from the screenshot).\n- `type` \u2014 type `text` at the current focus.\n- `scroll_down`, `scroll_up` \u2014 one viewport.\n- `close` \u2014 shut the browser down. Do this when finished with it.\n\nEvery action reports the console messages and uncaught errors produced while it ran, so a syntax error, a failed fetch or a null dereference comes back as text you can act on. `[error]` and `[Page Error]` lines are real failures. A page that says nothing printed nothing \u2014 that is a pass, not a failed call, and for a local file it is checked: the page's own scripts and the local scripts it loads by `src` are parsed, and a silent console over one that does not parse is reported as the failure it is, not as a pass. Silence says nothing threw; it does not say the page drew what it should.\n\nA parse error from the browser often names no line. For a local file the parser's own answer follows, with where it stopped, and a `Delimiter scan` section names the lines where brackets stop pairing up \u2014 one per place the trouble starts, since a file can be broken in several spots at once. Where the parser stops is where it gave up, which is not always where the mistake is, and a count says where brackets stop pairing, not which one is wrong: read the code at those lines, fix every place listed, and reload once. Do not count brackets yourself \u2014 the scan skips strings, comments and regex literals, which counting by hand does not.\n\nThe browser stays open between calls, so `open` once and then interact. Only one page is open at a time; `open` again to go elsewhere.";
 /**
  * Exported so the template generator can state this tool's real call shape.
  *

package/dist/extensions/tools/check-file.d.ts

@@ -27,6 +27,7 @@
  * therefore forces a much weaker check on the CLI than the words suggest.
  */
 import type { AgentTool } from "@cerebriline/shared";
+import { type ScriptGoal } from "./delimiter-balance";
 export declare const CHECK_FILE_TOOL_NAME = "check_file";
 /**
  * Written at the model that gets this wrong.
@@ -36,7 +37,7 @@ export declare const CHECK_FILE_TOOL_NAME = "check_file";
  * otherwise type are named here, in the description of the tool that replaces
  * them, which is where the model is standing when it is about to type one.
  */
-export declare const CHECK_FILE_TOOL_DESCRIPTION = "Check files for syntax errors and unbalanced brackets. **This is the syntax check.** Whichever word the question uses \u2014 parse error, syntax error, \"is it valid\", \"is it clean now\", \"what is still broken\" \u2014 this is the tool that answers it, for the files you name, in milliseconds, without running anything.\n\nAsk this instead of running `node --check`, `python -m py_compile`, `tsc --noEmit` or a bracket-counting script of your own. It parses the file without executing it, so it is safe on a page that would otherwise start a game or a server.\n\nWhen to call it:\n- After editing a file, to confirm the edit is valid before moving on.\n- Before reporting a task finished, on every file you changed. An edit you have not looked at is not a change you can report as done.\n- On a file you are about to change, to see what was already wrong with it.\n\nPass every file you want checked in one call.\n\nFor `.html` files each `<script>` block is parsed as JavaScript and the line numbers reported are the line numbers in the HTML file, not in the block.\n\nRead the bound carefully. This reports **syntax**, not meaning: a file that parses may still call a function that does not exist, and this will not say so. It is not a type checker, it does not run tests, and it does not know your project's lint rules \u2014 for those, use `run_commands`.\n\nOutput: JSON, in the shape a language server answers in. `files` holds one entry per path you named, each with `uri`, `checked` and `diagnostics`. There is no `success` field \u2014 diagnostics being listed is this tool working, not failing.\n\n`checked` says which check actually ran, and you have to read it before calling a file clean: `parsed` a real parser was satisfied, `delimiters` only the bracket scan reads this language so anything past brackets is unchecked, `none` nothing here reads this file type at all \u2014 empty `diagnostics` there means nothing was checked, not that the file is sound.\n\nEach diagnostic carries `range` (zero-based line and character), `severity` (1 = error) and `message`. `located: false` means the parser could not name a position, so the range is a placeholder rather than a claim about the top of the file. `complexity` appears on a file big enough to be worth a word about \u2014 a note to you, not a diagnostic.\n\nWhen a file's brackets do not match, a diagnostic names the line to edit and how many brackets that line is out by, one line per place the trouble starts \u2014 a file can be broken in several spots at once, so work through every line it lists before re-checking rather than re-checking after each one. Edit the lines it names; do not re-derive the balance by hand or with a script you write, which costs more thinking than you have and counts brackets inside strings, comments and regex literals that this scan skips. A parse error is always reported where the parser gave up, which is the closing bracket; the line named here is the one the error cannot name. The scan reads the whole file from line 1, and names each bracket by its line, its column and the text just before it: find it by that text rather than by counting columns.";
+export declare const CHECK_FILE_TOOL_DESCRIPTION = "Check files for syntax errors and unbalanced brackets. **This is the syntax check.** Whichever word the question uses \u2014 parse error, syntax error, \"is it valid\", \"is it clean now\", \"what is still broken\" \u2014 this is the tool that answers it, for the files you name, in milliseconds, without running anything.\n\nAsk this instead of running `node --check`, `python -m py_compile`, `tsc --noEmit` or a bracket-counting script of your own. It parses the file without executing it, so it is safe on a page that would otherwise start a game or a server.\n\nWhen to call it:\n- After editing a file, to confirm the edit is valid before moving on.\n- Before reporting a task finished, on every file you changed. An edit you have not looked at is not a change you can report as done.\n- On a file you are about to change, to see what was already wrong with it.\n\nPass every file you want checked in one call.\n\nFor `.html` files each `<script>` block is parsed as JavaScript and the line numbers reported are the line numbers in the HTML file, not in the block.\n\nRead the bound carefully. This reports **syntax**, not meaning: a file that parses may still call a function that does not exist, and this will not say so. It is not a type checker, it does not run tests, and it does not know your project's lint rules \u2014 for those, use `run_commands`.\n\nOutput: JSON, in the shape a language server answers in. `files` holds one entry per path you named, each with `uri`, `checked` and `diagnostics`. There is no `success` field \u2014 diagnostics being listed is this tool working, not failing.\n\n`checked` says which check actually ran, and you have to read it before calling a file clean: `parsed` a real parser was satisfied, `delimiters` only the bracket scan reads this language so anything past brackets is unchecked, `none` nothing here reads this file type at all \u2014 empty `diagnostics` there means nothing was checked, not that the file is sound.\n\nEach diagnostic carries `range` (zero-based line and character), `severity` (1 = error) and `message`. `located: false` means the parser could not name a position, so the range is a placeholder rather than a claim about the top of the file. `complexity` appears on a file big enough to be worth a word about \u2014 a note to you, not a diagnostic.\n\nA parse error is reported where the parser gave up. That is where the code stopped making sense to it, which is often but not always where the mistake is: a bracket left open earlier makes it give up later. When a file's brackets do not match, the bracket scan adds the lines where they stop pairing up and how many each line is out by, one line per place the trouble starts \u2014 read both before you edit, and work through every line listed before re-checking. A count says where brackets stop pairing, not which bracket is wrong, so read the code at those lines rather than editing them blind; do not re-derive the balance by hand or with a script of your own, which counts brackets inside strings, comments and regex literals that this scan skips. The scan names each bracket by its line, its column and the text just before it: find it by that text rather than by counting columns.";
 /**
  * The description when the host has a real checker to point at.
  *
@@ -96,12 +97,26 @@ export interface CheckFinding {
      */
     sourceText?: string;
 }
-/** Compile without running, and say what and where. */
-export declare function compileCheck(code: string, label: string, lineOffset?: number): CheckFinding | undefined;
+/**
+ * Compile without running, and say what and where.
+ *
+ * The parse the delimiter scan gates its edits on, so the two never disagree.
+ * The parse this had of its own threw nothing under Bun, which parses
+ * `vm.Script` lazily, so it never named a line there (automaticum audit
+ * 2026-11-08, B1); turned off on any line starting `import`, so a broken ES
+ * module was "No syntax errors" (B5); and refused a `#!` line and top-level
+ * `await`, which are correct (B6).
+ *
+ * `undefined` when the code parses, and equally when nothing here can tell --
+ * {@link parseVerdict} is the one that tells those apart.
+ */
+export declare function compileCheck(code: string, _label: string, lineOffset?: number, goal?: ScriptGoal): CheckFinding | undefined;
 /** A `<script>` body, and the line the body starts on. */
 export interface ScriptBlock {
     code: string;
     startLine: number;
+    /** `type="module"`: parsed by a module's rules. */
+    module?: boolean;
 }
 /**
  * The inline scripts of an HTML page.

package/dist/extensions/tools/command-guard.d.ts

@@ -12,9 +12,10 @@
  * so they cannot false-positive), split on shell separators, and the leading
  * command word of each part is compared against the lists below; output
  * redirection to files is also rejected. It will not catch every possible
- * mutation (e.g. `python -c "open(..., 'w')"` or commands hidden inside a
- * quoted `bash -c` string) — it exists to stop the common ways models edit
- * files from the shell, and entries are easy to add.
+ * mutation (e.g. `python -c "open(..., 'w')"`, or a command assembled at run
+ * time from variables) — it exists to stop the common ways models edit files
+ * from the shell, and entries are easy to add. A quoted `bash -c` / `eval`
+ * string is read as the command line it is.
  */
 import type { StructuredCommandInput } from "./schemas";
 /**

package/dist/extensions/tools/delimiter-balance.d.ts

@@ -72,6 +72,56 @@ export declare function scanDelimiters(text: string, origin?: Cursor): Delimiter
  * in code and skips every one in a string.
  */
 export declare function scanWithBalance(text: string, origin?: Cursor): DelimiterScan;
+/**
+ * Where a real parser stops on one script, in the file's own coordinates.
+ *
+ * The scan counts brackets. It cannot say which one is wrong, and an edit it
+ * worked out from the count alone was offered as checked when it fixed
+ * nothing. Measured on the manic_miner seed: line 95 holds a spare `}` that
+ * closes `class Level` early. Once line 90 was fixed the count no longer saw
+ * line 95 at all -- the class's own closing brace on line 97 was the one left
+ * over -- and the scan offered to delete that brace, with the exact editor
+ * call. The parser had stopped at line 96 the whole time, and the edit left it
+ * there. Every manic_miner gate from 2026-10-25 on was handed that edit.
+ *
+ * So no edit is offered unless the parser agrees it helped, and the line the
+ * parser stops on is named whatever the count says.
+ *
+ * `line` and `column` are absent where the runtime does not say: Bun 1.3
+ * names the line and no column, and a parse that only succeeds or fails, such
+ * as top-level `await` or JSON, names neither. On the same line without a
+ * column, an edit is offered only when the whole script parses after it.
+ */
+export interface ParseStop {
+    message: string;
+    line?: number;
+    column?: number;
+}
+/** Which grammar a span is read under. `either` is a `.js` file: a script, unless its own syntax says module. */
+export type ScriptGoal = "script" | "module" | "either";
+/**
+ * Parse one script and say where the parser stops: nothing when it parses,
+ * and null when this cannot tell.
+ *
+ * `goal` is what the span is: `script` a classic `<script>`, `module` a module
+ * script or `.mjs`, `either` a `.js` file, which is a script unless its own
+ * syntax says module. A script is parsed as a function body, so for a `.js`
+ * file a top-level `return` passes, as it does in CommonJS; a classic
+ * `<script>` is held to the stricter rule. What a real file holds and a
+ * parser here does not accept as written:
+ *
+ * - a `#!` line, which Node runs, is blanked with the line count kept;
+ * - top-level `await` in a `.js` file is parsed as an async body;
+ * - `import` or `export` in a `.js` file makes it a module, read by
+ *   {@link moduleAsScript}'s rules. In a classic `<script>` it is the error a
+ *   browser reports.
+ *
+ * `vm.compileFunction` throws on a broken body under Node and Bun alike (Bun's
+ * `vm.Script` parses lazily and throws nothing), and names the line in its
+ * stack: V8 and Bun 1.4 as `<filename>:<line>` over the source line and a
+ * caret, Bun 1.3 as `at <parse> (<filename>:<line>)`.
+ */
+export declare function findParseStop(body: string, origin?: Cursor, goal?: ScriptGoal): ParseStop | null | undefined;
 /**
  * How a prescribed repair opens, so a caller can tell a scan that names the
  * exact call from one that only names the line.

package/dist/extensions/tools/edit-verification.d.ts

@@ -73,6 +73,14 @@ export declare class EditVerificationTracker {
     private key;
     /** Whether this tracker can ever have anything to say. */
     get armed(): boolean;
+    /** Whether calls to this tool verify files. */
+    isCheckTool(toolName: string): boolean;
+    /**
+     * A checker call that returned: the files its answer reported on are
+     * checked, or every file the call named when the answer says nothing a
+     * file-by-file reading can use.
+     */
+    recordCheckResult(input: unknown, output: unknown): void;
     recordToolCall(toolName: string, input: unknown): void;
     /**
      * Files a checker reported on outside a checker call: the one a failing
@@ -99,9 +107,10 @@ export declare function isEditVerificationWrapped(tool: object): boolean;
 /**
  * Watch a tool's calls without changing what it does.
  *
- * Only the call is observed — not the result. A failed edit still counts as
- * having touched the file: the tool may have written part of it, and a guard
- * that trusted `success` would be answering a different question than "is this
- * file in a state anyone has looked at".
+ * An edit is observed at the call, not the result. A failed edit still counts
+ * as having touched the file: the tool may have written part of it, and a
+ * guard that trusted `success` would be answering a different question than
+ * "is this file in a state anyone has looked at". A check is the opposite: it
+ * counts only once it has answered, for the files the answer covers.
  */
 export declare function withEditVerificationCapture<TInput, TOutput>(tool: AgentTool<TInput, TOutput>, tracker: EditVerificationTracker): AgentTool<TInput, TOutput>;

package/dist/extensions/tools/error-locations.d.ts

@@ -2,7 +2,7 @@
  * The files a command's output blames, whatever produced the output.
  *
  * A model that runs the build gets told *that* something is broken and where
- * the tool gave up. A checker tells it *which line to edit*. Measured across
+ * the tool gave up. A checker reads the whole file and tells it where. Measured across
  * four transactions on three builds of the harness arm: the model that had the
  * first and not the second wrote its own analyser rather than asking for the
  * second — `find_error.js`, then five checkers in one transaction, then

package/dist/extensions/tools/executors/awk-parser.d.ts

@@ -104,6 +104,11 @@ export type Expr = {
 } | {
     type: "grouping";
     inner: Expr;
+}
+/** `(a, b)`: only after `print` or before `in`. */
+ | {
+    type: "exprList";
+    items: Expr[];
 };
 export type Stmt = {
     type: "print";

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

@@ -1,8 +1,20 @@
 import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
 import { type Rule } from "./awk-parser";
 import { type ReadReceipts } from "./read-receipts";
-/** An awk value: a number, a string, or a string that looks like a number. */
-type Value = string | number;
+/**
+ * Input that looks like a number: a field, a `split` part, a `-v` value.
+ *
+ * awk's strnum. It tests and compares as a number and prints as it was
+ * written. A string *constant* is never one: `x = "0"` is true and
+ * `$1 == "1.0"` compares text. With the two the same, both were judged by
+ * whether the text looked numeric (automaticum audit 2026-11-08, readers 21).
+ */
+declare class StrNum {
+    readonly text: string;
+    constructor(text: string);
+}
+/** An awk value: a number, a string, or input that looks like a number. */
+type Value = string | number | StrNum;
 export declare function awkSprintf(format: string, args: Value[]): string;
 export interface RunAwkOptions {
     /** `-F`: the field separator. */

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

@@ -148,6 +148,8 @@ export interface ShellExecutorOptions {
 export declare function createDetachedLog(retentionMs: number, marker: DetachedCommandMarker): {
     path: string;
     write(text: string): void;
+    /** Lifecycle lines -- the exit, a failure -- which the cap never drops. */
+    note(text: string): void;
     complete: () => void;
 };
 /**

package/dist/extensions/tools/executors/document/formats.d.ts

@@ -94,6 +94,8 @@ export interface DocumentReadResult {
     };
     /** Chapter titles for an ebook, in reading order. */
     contents?: string[];
+    /** Every contents entry, of which `contents` holds the first 200. */
+    contentsTotal?: number;
     /** Pages whose text is an image of text, for OCR. */
     scannedPages?: number[];
     /** Scanned pages whose text was recognized here, by `ReadOptions.recognize`. */
@@ -102,6 +104,8 @@ export interface DocumentReadResult {
     ocrLayerPages?: number[];
     /** Pages drawn as shapes: no text and no pictures to read. */
     vectorPages?: number[];
+    /** PDF pages with no text and no picture found on them. */
+    emptyPages?: number[];
     notes?: string[];
 }
 /**

package/dist/extensions/tools/executors/document/images.d.ts

@@ -22,7 +22,7 @@ export interface ExtractedImage {
     /** What the vision model saw in it, when descriptions were asked for. */
     description?: string;
     /**
-     * Set for a format no model can view (EMF, WMF, PICT, TIFF, BMP): the file is
+     * Set for a format no model can view (EMF, WMF, PICT, TIFF, BMP, JPEG 2000, …): the file is
      * kept, but it is not a picture anyone downstream can look at as it is.
      */
     notViewable?: boolean;
@@ -30,6 +30,11 @@ export interface ExtractedImage {
 }
 /** The formats a vision model is sent, which is what `inline` can attach. */
 export declare const VIEWABLE_MEDIA_TYPES: Set<string>;
+/**
+ * What to call an image's format in a sentence: the extension it was saved
+ * with, or its media type when it has none of its own.
+ */
+export declare function formatName(mediaType: string): string;
 /**
  * The media type of an image, from its first bytes.
  *

package/dist/extensions/tools/executors/document/legacy.d.ts

@@ -15,6 +15,15 @@
  * office_oxide reads whole.
  */
 import type { DocumentReadResult, ReadOptions } from "./formats";
+/**
+ * Whether a compound file is a password-protected .docx, .xlsx or .pptx.
+ *
+ * Encrypting an OOXML file wraps it in the same container as a 97-2003 one,
+ * so the bytes and often the name both say "legacy"; the old reader then
+ * reported "WordDocument stream not found" about a file that only needed its
+ * password (automaticum audit 2026-11-08, readers 28).
+ */
+export declare function isEncryptedOoxml(data: Uint8Array): Promise<boolean>;
 /** Complete PNG and JPEG images inside a compound file's streams. */
 export declare function scanCompoundImages(data: Uint8Array): Promise<Uint8Array[]>;
 export declare function readLegacyOffice(data: Uint8Array, format: "doc" | "xls" | "ppt", options: ReadOptions): Promise<DocumentReadResult>;

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

@@ -79,6 +79,19 @@ export interface FileReadExecutorOptions {
      */
     documentReader?: boolean;
 }
+/**
+ * How far the reader keeps counting lines after it has stopped capturing them,
+ * so that every read can report how long the file is.
+ *
+ * A ranged read used to stop at `end_line` and never learn the file's length,
+ * which left no way to ask the question at all. Measured on a 265-message
+ * session: five consecutive shell commands trying to find a line count —
+ * `wc -l` (not a Windows command), `type | find`, and three spellings of
+ * `(Get-Content).Count` — followed by two `editor` calls sending
+ * `end_line: 9999` as a guess at EOF. Counting the remaining lines costs one
+ * stream pass with no capture and no allocation.
+ */
+export declare const MAX_LINE_COUNT_SCAN = 500000;
 /** A read's text together with the line span it actually returned. */
 /**
  * Where a read's lines come from.
@@ -112,6 +125,8 @@ export interface ReadWindow {
     }[];
     /** The file holds no lines at all: seeing that is seeing all of it. */
     empty?: true;
+    /** Every line of the file is in this window. */
+    whole?: true;
 }
 /**
  * Create a file read executor using Node.js fs module

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

@@ -17,6 +17,7 @@
  * be taken must not be allowed to invent a change.
  */
 export type FileStamp = string;
+export declare const ABSENT_STAMP: FileStamp;
 export declare function readFileStamp(filePath: string): Promise<FileStamp | undefined>;
 /**
  * The stamp of a file as the caller sees it: through an agent's overlay, the
@@ -180,3 +181,12 @@ export interface OwnedReadReceipts extends ReadReceipts {
     clear(): void;
 }
 export declare function createReadReceipts(): OwnedReadReceipts;
+/**
+ * Record the lines a tool printed as read, one receipt per unbroken run.
+ *
+ * A receipt must cover an edit's whole range in one read, so runs are kept
+ * apart: lines 3 and 9 shown do not make 3-9 seen.
+ */
+export declare function creditShown(receipts: {
+    noteRead(filePath: string, first: number, last: number): void;
+} | undefined, filePath: string, lineNumbers: readonly number[]): void;

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

@@ -9,8 +9,8 @@ import type { SearchExecutor } from "../types";
  */
 export interface SearchExecutorOptions {
     /**
-     * File extensions to include in search (without dot)
-     * @default common code extensions
+     * File extensions the built-in search is limited to (without dot).
+     * @default every text file; ripgrep is never limited by this
      */
     includeExtensions?: string[];
     /**

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

@@ -10,6 +10,26 @@ type Address = {
     regex: RegExp;
 } | {
     kind: "every";
+}
+/** `first~step`: every step-th line from first (GNU). */
+ | {
+    kind: "step";
+    first: number;
+    step: number;
+}
+/** `0` as a range start: the range is open before line 1 (GNU `0,/re/`). */
+ | {
+    kind: "zero";
+}
+/** `+N` as a range end: N lines after the line that opened it (GNU). */
+ | {
+    kind: "relative";
+    count: number;
+}
+/** `~N` as a range end: up to the next line that is a multiple of N (GNU). */
+ | {
+    kind: "multiple";
+    of: number;
 };
 interface Command {
     start?: Address;
@@ -32,6 +52,10 @@ interface Command {
     text?: string;
     /** Range state while executing. */
     active?: boolean;
+    /** For a range whose end is a line count: the line it closes on. */
+    closesAt?: number;
+    /** Set by `selects`: this line is the last one of the command's range. */
+    closing?: boolean;
 }
 /**
  * Parse a sed script into commands.
@@ -45,6 +69,22 @@ export interface RunSedResult {
     output: string;
     /** Whether any command changed the text. */
     changed: boolean;
+    /**
+     * Whether any command selected a line and acted on it: an `s` that matched
+     * but wrote the same text back matched something, and "matched nothing"
+     * was a false account of it.
+     */
+    matched: boolean;
+    /**
+     * Input lines whose text reached the output, in order and once each: what
+     * a read-only run showed, and so what it may credit as read.
+     */
+    shown: number[];
+    /**
+     * Input lines the script changed: rewritten, deleted, replaced, or with
+     * text put before or after them. What an in-place run must have seen.
+     */
+    touched: number[];
 }
 /** Run a parsed script over text. Pure: no filesystem, so it is easy to test. */
 export declare function runSedScript(input: string, commands: Command[], quiet?: boolean): RunSedResult;

package/dist/extensions/tools/executors/unchanged-reads.d.ts

@@ -36,6 +36,12 @@ export interface ReadKeyParts {
     firstLine: number;
     lastLine: number;
     withLineNumbers: boolean;
+    /**
+     * The window was the whole file. Otherwise the comparison says nothing
+     * about the lines outside it, and "has not changed" claimed it did
+     * (automaticum audit 2026-11-08, readers 15).
+     */
+    wholeFile?: boolean;
 }
 export interface ReadLedger {
     /**

package/dist/extensions/tools/executors/web-fetch.d.ts

@@ -38,6 +38,18 @@ export interface WebFetchExecutorOptions {
      */
     maxRedirects?: number;
 }
+/**
+ * Decode character references in one pass, so `<` is the text
+ * `&lt;` -- decoded entity by entity it became `<`, and `&#x27;` or an emoji
+ * above U+FFFF was not decoded at all (automaticum audit 2026-11-08,
+ * readers 28).
+ */
+export declare function decodeEntities(text: string): string;
+/**
+ * Extract text content from HTML: tags stripped, block elements as line
+ * breaks, `<pre>` kept as written, entities decoded once.
+ */
+export declare function htmlToText(html: string): string;
 /**
  * Create a web fetch executor using native fetch
  *

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

@@ -15,11 +15,16 @@ export declare const MAX_TEXT_STREAM_BYTES = 100000000;
 export declare const BINARY_SNIFF_BYTES = 8000;
 /** Why a file is not read whole: too large, or not text. */
 export interface WholeFileRefusal {
-    kind: "size" | "binary";
+    kind: "size" | "binary" | "utf16";
     message: string;
 }
 /**
  * Why `filePath` must not be read whole, or nothing when it may. A path that
  * cannot be opened is left to the caller's own read, which says why.
  */
-export declare function wholeFileRefusal(filePath: string, tool: string): Promise<WholeFileRefusal | undefined>;
+export declare function wholeFileRefusal(filePath: string, tool: string, 
+/** How the refusal opens: what did not happen to the file. */
+outcome?: string): Promise<WholeFileRefusal | undefined>;
+/** The UTF-16 byte order a file's byte-order mark names, if it has one. */
+export declare function utf16ByteOrder(head: Uint8Array): "utf-16le" | "utf-16be" | undefined;
+export declare function readHead(filePath: string, bytes: number): Promise<Uint8Array>;