@cerebriline/core 4.100.274 → 4.100.277

package/dist/extensions/browser/chrome-browser-driver.d.ts

@@ -0,0 +1,50 @@
+import type { BrowserDriver } from "../tools/browser";
+/** The extension's local-mode user agent. */
+export declare const CHROME_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36";
+/**
+ * Where Chrome usually is, in the order a Linux or macOS box tends to have it.
+ * Built on each call so an environment set after import is read.
+ */
+export declare function chromeCandidates(): string[];
+/**
+ * The browser this machine already has. No download: a host that silently
+ * pulled 150 MB on the first tool call would be a worse surprise than a clear
+ * message saying which paths were tried.
+ */
+export declare function findChrome(): string | undefined;
+export declare class MissingChromeError extends Error {
+    constructor();
+}
+/**
+ * How a host hands over puppeteer: `() => import("puppeteer-core")` written in
+ * the host's own code, so its bundler sees the import and includes the module.
+ */
+export type PuppeteerLoader = () => Promise<unknown>;
+/**
+ * Load puppeteer-core, or say what is missing. Kept in one place so both
+ * drivers fail the same way when a host was installed without it.
+ */
+export declare function loadPuppeteer(loader?: PuppeteerLoader): Promise<unknown>;
+export interface ChromeBrowserDriverOptions {
+    headless?: boolean;
+    /** Chrome's executable. Defaults to the first of `chromeCandidates()` that exists. */
+    chromePath?: string;
+    launchTimeoutMs?: number;
+    /**
+     * Arguments Chrome starts with. The default disables the sandbox, because
+     * a CLI is routinely run as root in a container, where Chrome's sandbox
+     * refuses to start; this browser only opens pages the model could already
+     * read off disk.
+     */
+    args?: string[];
+    /** How to load puppeteer-core. Defaults to resolving the installed peer. */
+    loadPuppeteer?: PuppeteerLoader;
+}
+export declare const DEFAULT_CHROME_ARGS: string[];
+/**
+ * A driver that launches Chrome on first use and keeps it for the session,
+ * answering every action as the extension's `BrowserSession` (local mode)
+ * does. The tool owns the lifecycle -- it builds the driver lazily and calls
+ * `closeBrowser` at the end.
+ */
+export declare function createChromeBrowserDriver(options?: ChromeBrowserDriverOptions): BrowserDriver;

package/dist/extensions/browser/chrome-render-driver.d.ts

@@ -0,0 +1,36 @@
+import { type RenderDriver, type RenderRequest, type RenderResult } from "../tools/render-image";
+import { type PuppeteerLoader } from "./chrome-browser-driver";
+/**
+ * One render in a headless Chrome: the browser half of `render_image` (and of
+ * `transform_image`, which renders through the same driver).
+ *
+ * Moved here from the extension so any host can offer both tools: Chrome's
+ * path, its arguments and the Mermaid script are given, not looked up in VS
+ * Code's settings. A browser is started for the render and closed after it --
+ * a few hundred milliseconds beside a render that is rarely the tenth of a
+ * session, and a browser that is never kept is never left running.
+ */
+export interface RenderEnvironment {
+    executablePath: string;
+    /** `mermaid.min.js`. Absent: a diagram is refused with the reason. */
+    mermaidScriptPath?: string;
+    args?: string[];
+    /** How to load puppeteer-core. Defaults to resolving the installed peer. */
+    loadPuppeteer?: PuppeteerLoader;
+}
+export declare function renderWithChrome(request: RenderRequest, environment: RenderEnvironment): Promise<RenderResult>;
+export interface ChromeRenderDriverOptions {
+    /**
+     * Chrome's executable, or how to find it per render (the extension asks
+     * its browser settings each time). Defaults to `findChrome()`.
+     */
+    executablePath?: string | (() => string | undefined | Promise<string | undefined>);
+    /** `mermaid.min.js`; without it a Mermaid diagram is refused with the reason. */
+    mermaidScriptPath?: string | (() => string | undefined);
+    /** Chrome's arguments, or how to read them per render. Defaults to `DEFAULT_CHROME_ARGS`. */
+    args?: string[] | (() => string[] | Promise<string[]>);
+    /** How to load puppeteer-core. Defaults to resolving the installed peer. */
+    loadPuppeteer?: PuppeteerLoader;
+}
+/** A `RenderDriver` over `renderWithChrome`, for `render_image` and `transform_image`. */
+export declare function createChromeRenderDriver(options?: ChromeRenderDriverOptions): RenderDriver;

package/dist/extensions/config/prompt-template-review.d.ts

@@ -1,7 +1,7 @@
 import { type PromptTemplate } from "@cerebriline/shared";
 import { type CompactionPromptSources } from "./prompt-template-compaction";
 export declare const DEFAULT_REQUIRED_REWRITES: readonly ["read_files", "search_codebase", "editor", "apply_patch", "run_commands", "fetch_web_content", "check_file", "ask_lsp", "grep", "sed", "awk"];
-export declare const PROMPT_TEMPLATE_REVIEW_INSTRUCTIONS = "You are being shown the prompt Cline gives you when it uses you as a coding agent: a system prompt and a set of tool descriptions. You are the intended reader of this text. Rewrite it into the form you would rather receive.\n\nThis is not a copy-editing task. The prompt below was written by someone reasoning about how you read, and they may have been wrong. Where a section is phrased in a way you would skim, reorder or restate it. Where a rule matters and is buried, put it where you would be when you are about to break it. Where something is repeated to no effect, cut it.\n\nFour failures are observed in practice with models in your family, and the rewrite is judged on whether it prevents them:\n\n1. Reaching for shell commands to do file work \u2014 'cat' to read, 'sed -i' or 'echo >' to write, 'grep' to search \u2014 when dedicated tools exist and are always available.\n2. Serialising independent work across turns: one read, wait, one read, wait, when all of them were known at the start.\n3. Announcing an intention instead of acting on it, or claiming a task is finished without reading back what was written.\n4. Answering a question about a symbol with a text search. Asking where something is defined, what uses it, what implements it, or what a name means, and then grepping for it and reading several files to work out which hit was the real one \u2014 when the IDE's language servers already know the answer exactly and will give it in one call. The same failure in its other form: running a compiler or a linter through the shell to find out whether one file is valid, and waiting for a whole-project build to answer a one-file question.\n\nOne thing you must get right, and which prompts written for this get wrong in both directions:\n\nA coding agent is multi-turn, and the end of a turn is never in itself the end of the work. What is final is the completion of the assigned work \u2014 the task, the work package, the milestone, the request. An end of turn may be a milestone reached, a point where you need direction, guidance or a clarification from the user, or simply an intermediate step between two things the user asked for. So:\n\n- Do not treat \"I have stopped emitting tool calls\" as \"the work is done\". It is not a signal about the work at all.\n- Do not write a rule that makes stopping feel like failure, such as \"a response without a tool call is considered complete\". A rule like that buys one more unnecessary tool call on every finished task, and it teaches the wrong thing: that continuing is always correct.\n- Keep your attention on the long horizon of the assigned work rather than on the current turn. Ending a turn to ask a question is correct when you need the answer. Ending it while work you were asked to do remains untouched, and saying nothing about that, is not.\n\nFour more things are settled by measurement rather than by opinion, and a rewrite is judged on whether it keeps them:\n\n- The checker and the run belong in the same turn. Call 'check_file' and the thing that executes the code - 'run_commands', or 'browser' for a page - together, not one or the other. Running it says *that* something is broken and where the parser gave up; the checker says *which line* to edit. Each is half the answer, and the half you skip is the half the turn gets spent guessing at.\n- A tool's report outranks your own reasoning about the same question. Where a tool has measured something - a delimiter scan naming the line to edit, a diagnostic naming a type - that is the measurement, and re-deriving it yourself is an estimate. Where the two disagree, it is the estimate that is wrong. Measured twice: a model called a delimiter scan a false positive, counted brackets by hand instead, and was wrong both times, at over 30,000 thinking tokens a turn. If you doubt a report, do not re-derive it - act on it and run the result. That costs milliseconds and settles it either way.\n- Make the planned changes one at a time, and confirm each one before starting the next. The cheap check that does not execute the code goes after every edit; the thing that runs the code is what settles whether the change was right. Six edits made together and checked once leave six things to undo and no way to tell which one was wrong - measured across ten runs, the template that said otherwise drew 13.6 'restore_file' calls per run against 0.23 for the family that did not.\n- Do not re-read a file to confirm your own edit. The edit call already reports whether it landed and what changed, and that is the confirmation. Measured on one session: 'read_files' was called 33 times, 31 of them byte-identical, returning 440,013 characters against a file of 14 KB - four times the tokens that session spent on all of its reasoning. Read again when the call failed, or when you need content you have not seen. A rule that says to read a file back after every edit is the one thing here you must not write.\n\nHard constraints:\n\n- Keep every placeholder exactly as written, including the braces: {{PLATFORM_NAME}}, {{CURRENT_DATE}}, {{IDE_NAME}}, {{CWD}}, {{CLINE_RULES}}, {{CLINE_METADATA}}, {{DEFAULT}}. They are substituted at runtime; a renamed or dropped placeholder breaks the prompt.\n- Keep the tool names exactly as written. They are the wire names of real tools.\n- Do not invent tools, parameters, or capabilities. Describe only what is described below.\n- Keep the file structure: YAML frontmatter between --- markers, then '# system', then one '# tool: <name>' section for EVERY tool listed below. Not only the ones you want to change \u2014 every one of them.\n- Covering every tool is a hard requirement. A tool with no section keeps its built-in description, and that fallback exists for exactly one situation: Cline gains a new tool and the templates have not been regenerated yet. It is not a way to skip tools you have nothing to say about. A template that covers six of thirty-one tools is not using the fallback, it is relying on it, and nothing in the file shows which twenty-five were left out.\n- '{{DEFAULT}}' expands to the tool's built-in description at runtime, and it is how you cover a tool cheaply. Where you would improve on the built-in wording, write your own and put '{{DEFAULT}}' on its own line where the built-in text should follow. Where you would not, the entire section body may be just '{{DEFAULT}}'. Either is a covered tool; an absent section is not.\n- Text you write beside '{{DEFAULT}}' is sent in addition to the built-in description, not instead of it, on every request. So write only what you add: the rule a model in your family breaks, the case it misreads, the one example that settles it. Do not restate or paraphrase what the built-in text already says; it follows anyway, and a restatement means the reader takes in the same thing twice. If you want to say everything in your own words, drop '{{DEFAULT}}' and write the whole description instead.\n- These eight tools must be written in your own words, and a section containing only '{{DEFAULT}}' is not acceptable for any of them: read_files, search_codebase, editor, apply_patch, run_commands, fetch_web_content, check_file, ask_lsp. They are the tools models in your family are observed to misuse, so they are the whole reason this template exists. For these eight, your own text \u2014 not the inherited text \u2014 has to carry the three things listed below: every value of any closed set, every argument and when to use it, and what comes back. Adding '{{DEFAULT}}' after your text is allowed and does not excuse you from any of that.\n- For 'ask_lsp', say when to reach for it, not only what it does. List at least three concrete situations as the reader actually meets them \u2014 \"about to search for a name to find where it is defined\", \"about to open a file just to read a signature\", \"about to scroll or count brackets to work out a file's structure\" \u2014 each pointing at the operation that answers it, and name 'search_codebase' as the thing those situations would otherwise go to. This is not padding: measured across a whole session against a real bug, a template that described all eight operations correctly and said only \"prefer this over search_codebase for anything about a symbol\" produced zero calls to the tool, while the model hand-rolled the same answers in the shell twenty times. It could not recognise the moment.\n- Do not copy a built-in description out word for word. That is a snapshot: it says the same thing today and stops tracking the built-in text tomorrow, so the next edit to it reaches every model except you. If you would not change the wording, write '{{DEFAULT}}' \u2014 that is what it is for.\n- Where you rule a use of a tool out, name the tool that replaces it. 'run_commands' in particular must name 'read_files', 'editor' and 'search_codebase' in your own text: \"do not use this for file operations when dedicated tools exist\" is a rule the reader has to already know the answer to in order to follow, which is the same as not writing it.\n- Two of those eight \u2014 'run_commands' and 'skills' \u2014 must keep '{{DEFAULT}}' in the section as well. Their built-in descriptions are not fixed text: 'run_commands' is composed against the shell that will actually run the commands, so PowerShell, cmd and a POSIX shell get different quoting and sequencing advice, and 'skills' appends the skills installed on that machine. Replace either outright and you freeze one machine's answer into every machine's prompt, silently. Write your own text and put '{{DEFAULT}}' on its own line where the built-in text should follow.\n- For the other tools, a section whose body is exactly '{{DEFAULT}}' is a complete and correct answer. Do not pad them. Nothing about how you read changes what 'team_finalize_outcome' should say.\n- Emit every section exactly once. Do not repeat '# system', and do not write two '# tool: <name>' headings for the same tool. Only the last copy of a repeated section survives, so a duplicate silently throws away your own work.\n- Leave the 'match:' block in the frontmatter exactly as it is. It is what routes this template to you; change it and your rewrite reaches a different model, or none.\n\nReplace a description and you inherit everything it was carrying:\n\nIf a '# tool:' section contains '{{DEFAULT}}' anywhere, the built-in description is still delivered and you are only adding emphasis on top of it. Nothing further is asked of you for that tool \u2014 unless it is one of the eight above, which are judged on your words alone.\n\nIf it does not, your text is the only thing a model will ever see about that tool, so it must not lose what the built-in description said. Specifically, and only where the built-in text below says it:\n\n1. Closed sets. Where the built-in description lists the values an argument accepts \u2014 the operations of a language-server tool, the actions of a task tool, the statuses of a run \u2014 your replacement must list all of them too. Naming four of eight hides half the tool and a model cannot guess the rest.\n2. How to address the tool. Where the built-in description names the arguments, and says which one to use when, your replacement must say the same. A tool that can be addressed three ways needs all three, and what each is for.\n3. What comes back. Where the built-in description states an output, your replacement must state one: what each entry is named by, what it holds, and what an empty or failed result means. A model that cannot map a result back onto its request spends a turn working it out, and then stops trusting the tool. Say it in words, as the built-in text does: do not name fields such as 'query', 'result' or 'success', and do not write the result as an object like '{query, result, success, error?}'. A session receives tool results as text or as JSON, chosen when it starts, so a description of one format is false in the other.\n\nNothing is required of you that the built-in text did not already provide. Reproducing what is there is always enough; improving on it is better; dropping it is the one thing that is not allowed.\n\nDo not write 'Output:' followed by nothing, or by a single word. An empty label reads as an empty result, which is worse than saying nothing at all.\n\nFor any tool outside the eight, if restating all of that is not worth it to you, do not replace its description. Write your emphasis and leave '{{DEFAULT}}' in the section, or write nothing but the marker. That is cheaper and it is always correct.\n\nReply with the complete template file and nothing else: no preamble, no explanation, no code fence.";
+export declare const PROMPT_TEMPLATE_REVIEW_INSTRUCTIONS = "You are being shown the prompt Cline gives you when it uses you as a coding agent: a system prompt and a set of tool descriptions. You are the intended reader of this text. Rewrite it into the form you would rather receive.\n\nThis is not a copy-editing task. The prompt below was written by someone reasoning about how you read, and they may have been wrong. Where a section is phrased in a way you would skim, reorder or restate it. Where a rule matters and is buried, put it where you would be when you are about to break it. Where something is repeated to no effect, cut it.\n\nFour failures are observed in practice with models in your family, and the rewrite is judged on whether it prevents them:\n\n1. Reaching for shell commands to do file work \u2014 'cat' to read, 'sed -i' or 'echo >' to write, 'grep' to search \u2014 when dedicated tools exist and are always available.\n2. Serialising independent work across turns: one read, wait, one read, wait, when all of them were known at the start.\n3. Announcing an intention instead of acting on it, or claiming a task is finished without reading back what was written.\n4. Answering a question about a symbol with a text search. Asking where something is defined, what uses it, what implements it, or what a name means, and then grepping for it and reading several files to work out which hit was the real one \u2014 when the IDE's language servers already know the answer exactly and will give it in one call. The same failure in its other form: running a compiler or a linter through the shell to find out whether one file is valid, and waiting for a whole-project build to answer a one-file question.\n\nOne thing you must get right, and which prompts written for this get wrong in both directions:\n\nA coding agent is multi-turn, and the end of a turn is never in itself the end of the work. What is final is the completion of the assigned work \u2014 the task, the work package, the milestone, the request. An end of turn may be a milestone reached, a point where you need direction, guidance or a clarification from the user, or simply an intermediate step between two things the user asked for. So:\n\n- Do not treat \"I have stopped emitting tool calls\" as \"the work is done\". It is not a signal about the work at all.\n- Do not write a rule that makes stopping feel like failure, such as \"a response without a tool call is considered complete\". A rule like that buys one more unnecessary tool call on every finished task, and it teaches the wrong thing: that continuing is always correct.\n- Keep your attention on the long horizon of the assigned work rather than on the current turn. Ending a turn to ask a question is correct when you need the answer. Ending it while work you were asked to do remains untouched, and saying nothing about that, is not.\n\nFour more things are settled by measurement rather than by opinion, and a rewrite is judged on whether it keeps them:\n\n- The checker and the run belong in the same turn. Call 'check_file' and the thing that executes the code - 'run_commands', or 'browser' for a page - together, not one or the other. Running it says *that* something is broken and where the parser gave up; the checker says *where*: the line the parser stops on and the lines where brackets stop pairing. Each is half the answer, and the half you skip is the half the turn gets spent guessing at.\n- A tool's report outranks your own reasoning about the same question. Where a tool has measured something - a delimiter scan naming where brackets stop pairing, a diagnostic naming a type - that is the measurement, and re-deriving it yourself is an estimate. Where the two disagree, it is the estimate that is wrong. Measured twice: a model called a delimiter scan a false positive, counted brackets by hand instead, and was wrong both times, at over 30,000 thinking tokens a turn. If you doubt a report, do not re-derive it - act on it and run the result. That costs milliseconds and settles it either way.\n- Make the planned changes one at a time, and confirm each one before starting the next. The cheap check that does not execute the code goes after every edit; the thing that runs the code is what settles whether the change was right. Six edits made together and checked once leave six things to undo and no way to tell which one was wrong - measured across ten runs, the template that said otherwise drew 13.6 'restore_file' calls per run against 0.23 for the family that did not.\n- Do not re-read a file to confirm your own edit. The edit call already reports whether it landed and what changed, and that is the confirmation. Measured on one session: 'read_files' was called 33 times, 31 of them byte-identical, returning 440,013 characters against a file of 14 KB - four times the tokens that session spent on all of its reasoning. Read again when the call failed, or when you need content you have not seen. A rule that says to read a file back after every edit is the one thing here you must not write.\n\nHard constraints:\n\n- Keep every placeholder exactly as written, including the braces: {{PLATFORM_NAME}}, {{CURRENT_DATE}}, {{IDE_NAME}}, {{CWD}}, {{CLINE_RULES}}, {{CLINE_METADATA}}, {{DEFAULT}}. They are substituted at runtime; a renamed or dropped placeholder breaks the prompt.\n- Keep the tool names exactly as written. They are the wire names of real tools.\n- Do not invent tools, parameters, or capabilities. Describe only what is described below.\n- Keep the file structure: YAML frontmatter between --- markers, then '# system', then one '# tool: <name>' section for EVERY tool listed below. Not only the ones you want to change \u2014 every one of them.\n- Covering every tool is a hard requirement. A tool with no section keeps its built-in description, and that fallback exists for exactly one situation: Cline gains a new tool and the templates have not been regenerated yet. It is not a way to skip tools you have nothing to say about. A template that covers six of thirty-one tools is not using the fallback, it is relying on it, and nothing in the file shows which twenty-five were left out.\n- '{{DEFAULT}}' expands to the tool's built-in description at runtime, and it is how you cover a tool cheaply. Where you would improve on the built-in wording, write your own and put '{{DEFAULT}}' on its own line where the built-in text should follow. Where you would not, the entire section body may be just '{{DEFAULT}}'. Either is a covered tool; an absent section is not.\n- Text you write beside '{{DEFAULT}}' is sent in addition to the built-in description, not instead of it, on every request. So write only what you add: the rule a model in your family breaks, the case it misreads, the one example that settles it. Do not restate or paraphrase what the built-in text already says; it follows anyway, and a restatement means the reader takes in the same thing twice. If you want to say everything in your own words, drop '{{DEFAULT}}' and write the whole description instead.\n- These eight tools must be written in your own words, and a section containing only '{{DEFAULT}}' is not acceptable for any of them: read_files, search_codebase, editor, apply_patch, run_commands, fetch_web_content, check_file, ask_lsp. They are the tools models in your family are observed to misuse, so they are the whole reason this template exists. For these eight, your own text \u2014 not the inherited text \u2014 has to carry the three things listed below: every value of any closed set, every argument and when to use it, and what comes back. Adding '{{DEFAULT}}' after your text is allowed and does not excuse you from any of that.\n- For 'ask_lsp', say when to reach for it, not only what it does. List at least three concrete situations as the reader actually meets them \u2014 \"about to search for a name to find where it is defined\", \"about to open a file just to read a signature\", \"about to scroll or count brackets to work out a file's structure\" \u2014 each pointing at the operation that answers it, and name 'search_codebase' as the thing those situations would otherwise go to. This is not padding: measured across a whole session against a real bug, a template that described all eight operations correctly and said only \"prefer this over search_codebase for anything about a symbol\" produced zero calls to the tool, while the model hand-rolled the same answers in the shell twenty times. It could not recognise the moment.\n- Do not copy a built-in description out word for word. That is a snapshot: it says the same thing today and stops tracking the built-in text tomorrow, so the next edit to it reaches every model except you. If you would not change the wording, write '{{DEFAULT}}' \u2014 that is what it is for.\n- Where you rule a use of a tool out, name the tool that replaces it. 'run_commands' in particular must name 'read_files', 'editor' and 'search_codebase' in your own text: \"do not use this for file operations when dedicated tools exist\" is a rule the reader has to already know the answer to in order to follow, which is the same as not writing it.\n- Two of those eight \u2014 'run_commands' and 'skills' \u2014 must keep '{{DEFAULT}}' in the section as well. Their built-in descriptions are not fixed text: 'run_commands' is composed against the shell that will actually run the commands, so PowerShell, cmd and a POSIX shell get different quoting and sequencing advice, and 'skills' appends the skills installed on that machine. Replace either outright and you freeze one machine's answer into every machine's prompt, silently. Write your own text and put '{{DEFAULT}}' on its own line where the built-in text should follow.\n- For the other tools, a section whose body is exactly '{{DEFAULT}}' is a complete and correct answer. Do not pad them. Nothing about how you read changes what 'team_finalize_outcome' should say.\n- Emit every section exactly once. Do not repeat '# system', and do not write two '# tool: <name>' headings for the same tool. Only the last copy of a repeated section survives, so a duplicate silently throws away your own work.\n- Leave the 'match:' block in the frontmatter exactly as it is. It is what routes this template to you; change it and your rewrite reaches a different model, or none.\n\nReplace a description and you inherit everything it was carrying:\n\nIf a '# tool:' section contains '{{DEFAULT}}' anywhere, the built-in description is still delivered and you are only adding emphasis on top of it. Nothing further is asked of you for that tool \u2014 unless it is one of the eight above, which are judged on your words alone.\n\nIf it does not, your text is the only thing a model will ever see about that tool, so it must not lose what the built-in description said. Specifically, and only where the built-in text below says it:\n\n1. Closed sets. Where the built-in description lists the values an argument accepts \u2014 the operations of a language-server tool, the actions of a task tool, the statuses of a run \u2014 your replacement must list all of them too. Naming four of eight hides half the tool and a model cannot guess the rest.\n2. How to address the tool. Where the built-in description names the arguments, and says which one to use when, your replacement must say the same. A tool that can be addressed three ways needs all three, and what each is for.\n3. What comes back. Where the built-in description states an output, your replacement must state one: what each entry is named by, what it holds, and what an empty or failed result means. A model that cannot map a result back onto its request spends a turn working it out, and then stops trusting the tool. Say it in words, as the built-in text does: do not name fields such as 'query', 'result' or 'success', and do not write the result as an object like '{query, result, success, error?}'. A session receives tool results as text or as JSON, chosen when it starts, so a description of one format is false in the other.\n\nNothing is required of you that the built-in text did not already provide. Reproducing what is there is always enough; improving on it is better; dropping it is the one thing that is not allowed.\n\nDo not write 'Output:' followed by nothing, or by a single word. An empty label reads as an empty result, which is worse than saying nothing at all.\n\nFor any tool outside the eight, if restating all of that is not worth it to you, do not replace its description. Write your emphasis and leave '{{DEFAULT}}' in the section, or write nothing but the marker. That is cheaper and it is always correct.\n\nReply with the complete template file and nothing else: no preamble, no explanation, no code fence.";
 export declare function buildPromptTemplateReviewPrompt(defaultTemplate: string, familyTemplate: string | undefined, familyTemplateName: string | undefined, 
 /** What this model is, so a new template can be told how to claim itself. */
 target?: {

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

@@ -0,0 +1,99 @@
+import { type AgentTool } from "@cerebriline/shared";
+import { type LintCommandResult } from "../tools/check-file";
+import type { ReadDiagnostics, ReadText, TouchDocument } from "./types";
+/**
+ * `check_file` answered from language-server diagnostics: the extension's
+ * tool, moved here so the CLI and automaticum's runner offer the same one.
+ *
+ * Core's other `check_file` (`tools/check-file.ts`) parses the file itself and
+ * answers a narrower question -- syntax and brackets, not types. A host with
+ * language servers -- VS Code's, or the ones `createLspHost` starts -- builds
+ * this one instead, and may hand the files no server covers to that one
+ * through `describeUnserved`.
+ *
+ * Everything about *reading* diagnostics -- waiting for the server to settle,
+ * dropping hint-level noise, capping and rendering a file's problems -- is the
+ * post-edit report's, imported from there. Two different answers to "what is
+ * wrong with this file" would be worse than either.
+ */
+/**
+ * Deliberately written at the model that gets this wrong: `run_commands` is
+ * the tool it reaches for by reflex, so the alternatives it would otherwise
+ * type are named here, and so is every word a question about it uses -- a
+ * tool the model cannot name is a tool it does not have.
+ */
+export declare const DIAGNOSTICS_CHECK_FILE_TOOL_DESCRIPTION = "Check files for errors and warnings, using the editor's own language servers (LSP). **This is the linter.** It is also the type checker, the syntax check, and the source of the problems that would show in a Problems panel \u2014 whichever of those words the question uses, this is the tool that answers it. The results are live and follow your edits: one is current as of the moment you ask, so if it still reports a problem after an edit, the problem is still there. Restarting a language server is neither possible nor necessary from here.\n\nAsk this before running a checker yourself. For a file whose language a language server covers, it answers the same question as `tsc`, `eslint`, `biome`, `ruff`, `mypy`, `go build` or `cargo check` would \u2014 for the files you name, in milliseconds, without building the project.\n\nWhen to call it:\n- Whenever the question is about the linter, lint errors, diagnostics, problems, warnings, type errors, syntax errors or compile errors \u2014 \"how many errors is the linter reporting?\", \"is it clean now?\", \"what is still broken?\". You have no other way to know, and the report you were shown after an earlier edit does not answer it: that was true then, and you have edited since.\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.\n- On a file you are about to change, when you want to know what was already wrong with it.\n\nPass every file you want checked in one call.\n\nRead a clean result carefully. \"No problems reported by the editor\" is conclusive only where a language server covers that file, and it does not for every language on every machine. If this reports nothing and you have reason to expect a problem, or the project has a checker the language servers do not run, run that checker with `run_commands`. Tests and builds are always `run_commands`; this tool does not run them.\n\nOutput: plain text, one section per file you named, each problem on its own line as `file:line:column` with its severity and message. A file with nothing wrong says so in one line. Problems being listed is this tool working, not failing.\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, a `Delimiter scan` section 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. 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. Do not count brackets yourself \u2014 the scan skips strings, comments and regex literals, which counting characters does not. It runs whether or not the editor reported anything, so it can appear beneath a file the editor called clean \u2014 no language server checks the script inside an `.html` file, and there this is the only report you will get.";
+export declare const DIAGNOSTICS_CHECK_FILE_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly paths: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Files to check. Absolute, or relative to the working directory. Pass all of them in one call.";
+        };
+    };
+    readonly required: readonly ["paths"];
+};
+/**
+ * A shorter settle budget than the post-edit report uses: that one runs the
+ * instant a write lands; this one usually runs against a file that has been
+ * sitting still, so the server has already had its chance.
+ */
+export declare const CHECK_SETTLE_BUDGET: {
+    pollMs: number;
+    timeoutMs: number;
+};
+/** What the editor holds for a file: the text its language server checks. */
+export interface LoadedDocument {
+    text: string;
+    /** The user has changes to it they have not saved. */
+    dirty: boolean;
+}
+export interface DiagnosticsCheckFileToolOptions {
+    cwd: string;
+    readDiagnostics: ReadDiagnostics;
+    /**
+     * Hand a file to its server before reading its diagnostics: a file the
+     * server has never seen has none, and none reads as clean. For a host
+     * whose servers are its own (`LspHost.touch`).
+     */
+    touch?: TouchDocument;
+    /**
+     * Make the editor load a file it may never have opened, and report its
+     * copy, which is compared with the disk (VS Code). Nothing returned skips
+     * the comparison.
+     */
+    loadDocument?: (filePath: string) => Promise<LoadedDocument | undefined>;
+    /**
+     * Whether a server answers for a file. With `describeUnserved`, a file no
+     * server answers for gets that answer instead of "no problems reported".
+     */
+    serves?: (filePath: string) => boolean;
+    /** The answer for a file no server covers -- core's syntax check, say. */
+    describeUnserved?: (absolutePath: string, displayPath: string) => Promise<string | undefined>;
+    /** The user's lint command, if they set one. */
+    resolveLintCommand?: () => string | undefined;
+    /** Runs the configured command. Injected so tests never spawn anything. */
+    runLintCommand?: (template: string, filePath: string, signal?: AbortSignal) => Promise<LintCommandResult>;
+    /**
+     * What reported paths are written relative to. Defaults to `cwd`; the
+     * extension writes them relative to the workspace root it reports.
+     */
+    displayCwd?: () => string | Promise<string>;
+    /** Replaces the description, for a host that words it for its own setting. */
+    description?: string;
+    /** The disk, as the host reads it. Defaults to the real one. */
+    readFile?: ReadText;
+    /** Injection point for tests; defaults to a real timer. */
+    delay?: (ms: number) => Promise<void>;
+    onError?: (message: string, error: unknown) => void;
+}
+interface CheckFileInput {
+    paths?: unknown;
+}
+/** Accept the shapes a model actually sends, not only the documented one. */
+export declare function readRequestedPaths(input: CheckFileInput | undefined): string[];
+export declare function createDiagnosticsCheckFileTool(options: DiagnosticsCheckFileToolOptions): AgentTool;
+export {};

package/dist/extensions/diagnostics/editor-diagnostics.d.ts

@@ -0,0 +1,125 @@
+import { type AgentHooks } from "@cerebriline/shared";
+import type { DiagnosticSeverityName, HostDiagnostic, HostFileDiagnostics, ReadDiagnostics, ReadText, TouchDocument } from "./types";
+/**
+ * Severities worth a turn of the model's attention.
+ *
+ * Errors and warnings are claims that something is wrong. Information and hint
+ * diagnostics are mostly editor affordances -- "convert to template literal",
+ * "this import could be type-only" -- and a model handed them will act on them,
+ * turning every edit into a style refactor nobody asked for.
+ */
+export declare const REPORTED_SEVERITIES: readonly DiagnosticSeverityName[];
+/**
+ * Diagnostics reported per file. A truncated list still says "this edit broke
+ * something, look here", which is the whole job. An untruncated one can be
+ * longer than the file.
+ */
+export declare const MAX_DIAGNOSTICS_PER_FILE = 20;
+/**
+ * How long to wait for the language server to catch up with the write.
+ *
+ * Diagnostics are published asynchronously and a request issued the instant an
+ * edit lands reads the state before it. The wait ends early as soon as the
+ * file's diagnostics stop changing, so the common case costs one poll interval
+ * rather than the whole budget. Small on purpose: this sits between the model
+ * and its next turn, and a slow linter must not become a slow agent.
+ */
+export declare const SETTLE_POLL_MS = 250;
+export declare const SETTLE_TIMEOUT_MS = 2000;
+export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Extract the files a file-writing tool call is about.
+ *
+ * `editor` names its file directly. `apply_patch` carries a patch body whose
+ * grammar names the files in its headers, which is the only place they appear.
+ */
+export declare function readTargetPaths(toolName: string, input: unknown): string[];
+/**
+ * Whether a file is one an editor diagnostic can say something useful about.
+ * A rejection list rather than an allow list: the set of things an editor
+ * lints grows with every extension installed, and a Dockerfile, a Makefile or
+ * a `.env` has no extension to allow in the first place.
+ */
+export declare function isLintableFile(filePath: string): boolean;
+/**
+ * A path in the form used to compare two paths for identity.
+ *
+ * Windows filesystems are case-insensitive, and the two sides come from
+ * different places: the editor reports the path as the workspace has it, and
+ * the model types it. Measured: the workspace was `c:\Users\...` and the model
+ * asked about `C:\Users\...`, and six `check_file` calls answered "no problems"
+ * for a file `node --check` rejects. Only the case is normalized; this is a
+ * comparison key, not a canonical path.
+ */
+export declare function comparablePath(filePath: string): string;
+/** Whether two paths name the same file, as this platform judges it. */
+export declare function samePath(a: string, b: string): boolean;
+export declare function filterToPaths(diagnostics: readonly HostFileDiagnostics[], absolutePaths: ReadonlySet<string>): HostFileDiagnostics[];
+/** The diagnostics as the editor reports them, without a host's `pending` mark. */
+export declare function withoutPending(files: readonly HostFileDiagnostics[]): HostFileDiagnostics[];
+export declare function isReportableDiagnostic(diagnostic: HostDiagnostic): boolean;
+/**
+ * Render one file's reportable diagnostics, or an empty string when there are
+ * none -- silence is the correct output for a clean edit, and the cheapest.
+ */
+export declare function renderFileDiagnostics(cwd: string, filePath: string, diagnostics: readonly HostDiagnostic[], readText?: ReadText): Promise<string>;
+export declare function formatIntroducedDiagnostics(cwd: string, before: readonly HostFileDiagnostics[], after: readonly HostFileDiagnostics[]): Promise<string>;
+/**
+ * Append a rendered block to a tool result without destroying its shape.
+ *
+ * The file-writing tools return a `ToolOperationResult`, whose `result` field is
+ * what the model reads; anything else is stringified by the transport, so the
+ * block goes where a string will survive.
+ */
+export declare function appendToOutput(output: unknown, block: string): unknown;
+/**
+ * Mark a tool result as having made the file worse.
+ *
+ * The loop tracker asked "did it get anywhere?" from failure alone, which is
+ * blind to eight `editor` calls returning `success: true` while the file's
+ * diagnostics went 2 -> 20. An edit that adds problems did not get anywhere,
+ * whatever its envelope says. The flag rides on the result so the runtime can
+ * read it without this module knowing about the loop tracker.
+ */
+export declare function markRegressed(output: unknown): unknown;
+/**
+ * Read the files' diagnostics once the language servers have stopped
+ * changing their mind, or once the budget runs out -- whichever comes first.
+ * A file changed after its server last reported on it is `pending`, and a
+ * pending answer is not a settled one however long it has stayed the same.
+ */
+export declare function readSettledDiagnostics(absolutePaths: ReadonlySet<string>, read: ReadDiagnostics, delay: (ms: number) => Promise<void>, budget?: {
+    pollMs?: number;
+    timeoutMs?: number;
+}): Promise<HostFileDiagnostics[]>;
+export interface EditorDiagnosticsHooksOptions {
+    cwd: string;
+    readDiagnostics: ReadDiagnostics;
+    /**
+     * For a host whose servers do not watch the disk: hand a file over before
+     * the edit (so what was already wrong with it is known, as it is for a
+     * file open in an editor) and after it, as saved. Left out, the host's
+     * diagnostics are read as they stand -- VS Code reloads the file itself.
+     */
+    touch?: TouchDocument;
+    /** Only files this says a server answers for are watched. */
+    serves?: (filePath: string) => boolean;
+    /** Injection point for tests; defaults to a real timer. */
+    delay?: (ms: number) => Promise<void>;
+    /** One record per edit, for a host's trace: what was asked and found. */
+    trace?: (entry: Record<string, unknown>) => void;
+    /** Where a failure of this feature goes. It never fails the edit. */
+    onError?: (message: string, error: unknown) => void;
+    /**
+     * What reported paths are written relative to. Defaults to `cwd`; the
+     * extension writes them relative to the workspace root it reports.
+     */
+    displayCwd?: () => string | Promise<string>;
+}
+/**
+ * Hooks that report an edit's new diagnostics back to the model.
+ *
+ * Composed with whatever hooks the host already has rather than folded into
+ * them: this is not optional in the way user-authored hook scripts are.
+ */
+export declare function createEditorDiagnosticsHooks(options: EditorDiagnosticsHooksOptions): AgentHooks;

package/dist/extensions/diagnostics/render.d.ts

@@ -0,0 +1,25 @@
+import type { DiagnosticSeverityName, HostDiagnostic, HostFileDiagnostics, ReadText } from "./types";
+/**
+ * How a file's diagnostics are written for a model.
+ *
+ * One renderer for every host: `check_file` and the post-edit report say the
+ * same thing about the same file whether VS Code or a language server the CLI
+ * started produced it. Moved here from the extension's
+ * `integrations/diagnostics`, which now delegates to it.
+ */
+/** The disk, read as text. */
+export declare const defaultReadText: ReadText;
+/** Two diagnostics are the same claim when every field they carry matches. */
+export declare function sameDiagnostic(a: HostDiagnostic, b: HostDiagnostic): boolean;
+/** The diagnostics in `after` that were not in `before`, per file. */
+export declare function getNewDiagnostics(before: readonly HostFileDiagnostics[], after: readonly HostFileDiagnostics[]): HostFileDiagnostics[];
+/**
+ * Every file's problems of the given severities, or an empty string when there
+ * are none. `cwd` is what the paths are written relative to.
+ */
+export declare function diagnosticsToProblemsString(cwd: string, diagnostics: readonly HostFileDiagnostics[], severities?: readonly DiagnosticSeverityName[]): Promise<string>;
+/**
+ * One file's problems, or an empty string when the list is empty. `cwd` is
+ * what the path is written relative to.
+ */
+export declare function singleFileDiagnosticsToProblemsString(cwd: string, filePath: string, diagnostics: readonly HostDiagnostic[], readText?: ReadText): Promise<string>;

package/dist/extensions/diagnostics/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Diagnostics as an editor keeps them, in the shape every host hands over.
+ *
+ * The extension reads them from VS Code (its proto `FileDiagnostics`), the
+ * CLI and automaticum's runner from the language servers they start. The
+ * tools that read them -- `check_file`, the post-edit report -- are shared,
+ * so the shape is core's: a named severity rather than either side's number
+ * (VS Code's proto counts errors from 0, LSP from 1).
+ */
+export type DiagnosticSeverityName = "error" | "warning" | "information" | "hint";
+export interface DiagnosticPosition {
+    /** 0-based, as LSP has it. */
+    line: number;
+    /** 0-based. */
+    character: number;
+}
+export interface HostDiagnostic {
+    message: string;
+    severity: DiagnosticSeverityName;
+    range?: {
+        start?: DiagnosticPosition;
+        end?: DiagnosticPosition;
+    };
+    /** The producer, as the editor names it: "ts", "eslint", "css". */
+    source?: string;
+}
+export interface HostFileDiagnostics {
+    filePath: string;
+    diagnostics: HostDiagnostic[];
+    /**
+     * The file changed after its server last reported on it, so what is held
+     * describes an older text. A reader waiting for the server to settle keeps
+     * waiting while this is set. Hosts that cannot tell leave it out.
+     */
+    pending?: boolean;
+}
+/** Reads every file's current diagnostics. */
+export type ReadDiagnostics = () => Promise<HostFileDiagnostics[]>;
+/**
+ * Hands a server the file as it is on disk now (`save`: as just written), so
+ * its next diagnostics are about that text. The editor does this itself; a
+ * host that starts its own servers has to. Resolves to something truthy when
+ * a server holds the file.
+ */
+export type TouchDocument = (filePath: string, options?: {
+    save?: boolean;
+}) => Promise<unknown>;
+/**
+ * A file's text, as the host reads its disk. Injected where a host wants its
+ * own view -- a sandbox, a test's fake disk -- and defaulted to the real one.
+ */
+export type ReadText = (filePath: string) => Promise<string>;

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

@@ -0,0 +1,138 @@
+import type { HostDiagnostic } from "../diagnostics/types";
+export interface LspServerSpec {
+    /** How the server is named in status and errors. Defaults to `command`. */
+    name?: string;
+    /** The executable: a name looked up on PATH, or a full path. */
+    command: string;
+    args: string[];
+    /** Languages this server answers for, as LSP language ids. */
+    languages: string[];
+    /**
+     * The file whose existence says the server is installed. Defaults to
+     * `command` (looked up on PATH when it has no directory in it). A server
+     * started as `node <script>` names its script here.
+     */
+    probe?: string;
+    /** Added to the environment the server starts with. */
+    env?: Record<string, string>;
+    /**
+     * Server-specific `initializationOptions`.
+     *
+     * Needed because a server is not always self-sufficient:
+     * `typescript-language-server` refuses to start unless it can find a
+     * TypeScript installation, and it looks in the workspace. A workspace with
+     * no `node_modules` -- which is most of the ones a model is asked to fix --
+     * gets "Could not find a valid TypeScript installation. Exiting."
+     */
+    initializationOptions?: Record<string, unknown> | (() => Record<string, unknown> | undefined);
+    /**
+     * The settings an editor would hold for this server: sent once with
+     * `workspace/didChangeConfiguration` and read back for every
+     * `workspace/configuration` the server asks. A section nobody set answers
+     * an empty object, never null -- see `LspConnection.setting`.
+     */
+    settings?: Record<string, unknown>;
+    /**
+     * A diagnostic's producer as the editor names it, by what the server
+     * reports: VS Code labels what tsserver reports "ts", where the server
+     * says "typescript".
+     */
+    sources?: Record<string, string>;
+}
+/** The name a spec goes by. */
+export declare function serverName(spec: LspServerSpec): string;
+export declare function fileUri(filePath: string): string;
+export declare function uriToPath(uri: string): string;
+/**
+ * A diagnostic as the editor keeps it, from what a server sent: a position,
+ * a named severity, the message and the producer. LSP leaves the severity
+ * to the client when it is absent; VS Code treats that as an error.
+ */
+export declare function normalizeLspDiagnostic(raw: unknown): HostDiagnostic;
+export interface LspConnectionOptions {
+    onError?: (message: string, error: unknown) => void;
+    /** Every `textDocument/publishDiagnostics`, the path decoded. */
+    onDiagnostics?: (filePath: string, diagnostics: HostDiagnostic[]) => void;
+}
+/**
+ * One server process and the conversation with it.
+ *
+ * Requests are correlated by id. A message with a `method` is the server's,
+ * whether or not it has an id: with one it is a request and is answered, and
+ * only a message without a `method` is a response to one of ours. A server
+ * that dies takes its pending requests with it rather than leaving them
+ * hanging until the timeout.
+ */
+export declare class LspConnection {
+    readonly spec: LspServerSpec;
+    private readonly rootPath;
+    private child;
+    private buffer;
+    private nextId;
+    private readonly pending;
+    /** What the server holds open, by URI: the text it was last sent. */
+    private readonly documents;
+    private initializing;
+    private failure;
+    private pullRefused;
+    /** What the server said it can do, from its `initialize` answer. */
+    capabilities: Record<string, unknown>;
+    private readonly onError?;
+    private readonly onDiagnostics?;
+    constructor(spec: LspServerSpec, rootPath: string, options?: LspConnectionOptions | ((message: string, error: unknown) => void));
+    /** Whether the server has been started and is still running. */
+    get started(): boolean;
+    /** Why the server is not available, once it has failed. */
+    get failed(): Error | undefined;
+    /** Started once, on the first question, and shared by every one after it. */
+    ready(): Promise<void>;
+    private start;
+    private fail;
+    private consume;
+    private dispatch;
+    /**
+     * A request of the server's own, answered as an editor answers it.
+     *
+     * Left unanswered, some servers wait for the answer before doing anything
+     * else.
+     */
+    private answer;
+    /**
+     * A section of the settings, as an editor answers: an object, empty for a
+     * section nobody set. Never null: the CSS validator reads properties off
+     * what it is given ("Cannot read properties of null (reading
+     * 'validProperties')"), and the HTML server validates a page's `<style>`
+     * through it, so a null aborts the whole page's validation -- and a page
+     * whose script does not parse then reports no diagnostics at all.
+     */
+    setting(section: string | undefined): unknown;
+    private send;
+    notify(method: string, params: unknown): void;
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Make the server hold the file as it is now.
+     *
+     * Opened the first time; after that, sent whole as a change, with the next
+     * version, when it differs from what the server holds. A second `didOpen`
+     * for a document already open is a protocol error that servers answer by
+     * ignoring it -- and then answering from the old text, which is exactly
+     * the "the model edits, then asks" case. Returns whether the server was
+     * told anything.
+     */
+    syncDocument(filePath: string, text: string, languageId: string): boolean;
+    /**
+     * Tell the server the file was written. Some servers check only on save:
+     * rust-analyzer's type errors come from `cargo check` on `didSave`.
+     */
+    documentSaved(filePath: string): void;
+    /** Whether this server answers `textDocument/diagnostic` when asked. */
+    get pullsDiagnostics(): boolean;
+    /**
+     * Diagnostics asked for, from a server that answers only when asked
+     * (csharp-ls). Undefined when the server does not pull, or answered with
+     * something other than a full report.
+     */
+    pullDiagnostics(filePath: string): Promise<HostDiagnostic[] | undefined>;
+    private label;
+    dispose(): Promise<void>;
+}