@cerebriline/core 4.100.240

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

@@ -0,0 +1,218 @@
+/**
+ * A checker for hosts that have no language server.
+ *
+ * VS Code's `check_file` asks the editor's own language servers and is as good
+ * as whatever the user has installed. Every other host — the CLI above all —
+ * had nothing, and the edit-verification guard stands aside when no checker is
+ * named. Measured on the CLI: a run made ten `editor` calls, checked nothing,
+ * and reported "the implementation is complete" on a file that does not parse.
+ * The model was not being careless so much as blind; `run_commands` was its
+ * only way to find out and it did not think to use it.
+ *
+ * So this answers the narrower question the editor cannot be asked here: does
+ * this file still parse, and where do its brackets stop matching. It is not a
+ * type checker and does not pretend to be — the description says so, because a
+ * model that believes a clean result means "correct" is worse off than one
+ * that knows the bound.
+ *
+ * Compilation is `vm.Script`, which parses without running: an HTML page that
+ * starts a game must not start one because someone asked whether it parses.
+ *
+ * A host that can name a real checker gets to close the rest of the distance:
+ * pass a lint command and this runs it too, and says so in its description. The
+ * point of that is not convenience — it is that the two hosts stop shipping
+ * different tools under one name. Without it the extension tells the model
+ * `check_file` is the linter and the type checker while the CLI tells it the
+ * same tool is a syntax check, and an edit-verification mode of `require`
+ * therefore forces a much weaker check on the CLI than the words suggest.
+ */
+import type { AgentTool } from "@cerebriline/shared";
+export declare const CHECK_FILE_TOOL_NAME = "check_file";
+/**
+ * Written at the model that gets this wrong.
+ *
+ * The failure is not ignorance of what a linter is: it is that `run_commands`
+ * is the tool a model reaches for by reflex. So the commands it would
+ * 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 description when the host has a real checker to point at.
+ *
+ * The bound paragraph above is the whole reason this is a second string rather
+ * than a suffix: with a lint command wired in, "it is not a type checker, it
+ * does not know your project's lint rules" is no longer true, and a model that
+ * believes it will go and run the command through `run_commands` anyway --
+ * which is the reflex this tool exists to displace.
+ *
+ * The command is named rather than described, because a model deciding whether
+ * to trust a result wants to know what produced it.
+ */
+export declare function buildCheckFileDescription(lintCommand: string): string;
+export declare const 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"];
+};
+/**
+ * The token a user writes in their lint command to mark where the path goes.
+ *
+ * Escaped rather than written plainly: as a plain literal it reads to the
+ * linter as an unescaped template placeholder, which is exactly what it is not
+ * — it is data the user types, and it has to stay a string to be matched.
+ */
+export declare const LINT_COMMAND_FILE_PLACEHOLDER = "${file}";
+export interface LintCommandResult {
+    exitCode: number;
+    output: string;
+}
+/**
+ * Substitute the file into the configured command.
+ *
+ * A command without the placeholder gets the path appended, because `"eslint"`
+ * is what a user will actually type and refusing it would be pedantry.
+ */
+export declare function buildLintCommand(template: string, filePath: string): string;
+export interface CheckFinding {
+    line: number;
+    /** Whether the runtime named that line, or it is just the start of the file. */
+    located: boolean;
+    message: string;
+    /**
+     * The text of the line the parser stopped on, when it named one.
+     *
+     * Not `source`: LSP spends that name on the producer of a diagnostic
+     * ("tsc", "eslint"), and the structured report speaks LSP. A familiar key
+     * holding an unfamiliar value is worse than an unfamiliar key.
+     */
+    sourceText?: string;
+}
+/** Compile without running, and say what and where. */
+export declare function compileCheck(code: string, label: string, lineOffset?: number): CheckFinding | undefined;
+/** A `<script>` body, and the line the body starts on. */
+export interface ScriptBlock {
+    code: string;
+    startLine: number;
+}
+/**
+ * The inline scripts of an HTML page.
+ *
+ * Blocks with a `src` are somebody else's file, and a `type` that is not
+ * JavaScript (`application/json`, an import map, a template) is not ours to
+ * parse — reporting a syntax error in a JSON island as a script error would
+ * send a model to edit something that was correct.
+ */
+export declare function extractScripts(html: string): ScriptBlock[];
+/** Everything this can say about one file. */
+/**
+ * What a check found, in the shape the model already reads.
+ *
+ * The redesign, and the reason for it is measured rather than aesthetic: the
+ * A/B that added a sentence telling the model to call `check_file` tripled the
+ * calls and bought nothing (9/20 vs 6/20 FIXED, p=0.51) at 1.8x the wall time.
+ * Telling a model to use a tool harder does not make the tool legible. So the
+ * result now arrives in the vocabulary the LSP surface already taught it —
+ * `range`, `severity`, `message` — where it has to learn nothing at all.
+ *
+ * Positions are LSP's: zero-based line and character. Converting at the edge
+ * rather than carrying one-based numbers under LSP names, because a familiar
+ * shape holding unfamiliar values is worse than an unfamiliar shape.
+ */
+export interface CheckDiagnostic {
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    /** LSP severity: 1 error, 2 warning. Everything here is an error. */
+    severity: 1 | 2;
+    /** LSP's `source` is the producer of the diagnostic, not the code. */
+    source: string;
+    message: string;
+    /**
+     * Whether the parser actually named this position.
+     *
+     * Every LSP diagnostic must carry a range, so an error located nowhere has
+     * to be given one -- and the only honest choice is the top of the file,
+     * which is exactly the lie the text renderer refused to print. Marked
+     * rather than omitted: a reader that trusts the range needs to be told
+     * when it is a placeholder.
+     */
+    located: boolean;
+    /** The text of the line the parser stopped on, when it named one. */
+    sourceLine?: string;
+}
+/**
+ * Which check actually ran, because `diagnostics: []` cannot say.
+ *
+ * `parsed` a real parser was satisfied; `delimiters` only the bracket scan
+ * ran, which is real but narrow; `none` nothing here reads this language and
+ * the empty list means nothing at all. Reporting the third as clean tells a
+ * model its file is sound on the authority of a check that never happened,
+ * which is the failure the prose version was careful to avoid and which a bare
+ * list would quietly reintroduce.
+ */
+export type CheckCoverage = "parsed" | "delimiters" | "none";
+export interface CheckFileReport {
+    uri: string;
+    checked: CheckCoverage;
+    diagnostics: CheckDiagnostic[];
+}
+/**
+ * Check one file and report it structurally.
+ *
+ * The source of truth; {@link checkSource} renders this for hosts still
+ * reading prose, so the two can never disagree about what was found.
+ */
+export declare function checkFileReport(filePath: string, text: string): CheckFileReport;
+export declare function checkSource(filePath: string, text: string): string;
+/** One file in the tool's answer. Either it was checked, or it could not be. */
+export type CheckFileEntry = (CheckFileReport & {
+    lint?: CheckFileLint;
+    complexity?: string;
+}) | {
+    uri: string;
+    error: string;
+};
+/** What the user's own checker said, when one is configured. */
+export interface CheckFileLint {
+    command: string;
+    /** Absent when the command could not be run at all. */
+    exitCode?: number;
+    output: string;
+    /** Set when the command itself failed to launch. */
+    error?: string;
+}
+export interface CheckFileAnswer {
+    files: CheckFileEntry[];
+    /** Present only when more files were named than could be checked. */
+    notChecked?: {
+        named: number;
+        limit: number;
+    };
+    /** Present only when the call could not be served at all. */
+    error?: string;
+}
+export declare function createCheckFileTool(options?: {
+    cwd?: string;
+    /** The user's lint command, if they configured one. */
+    lintCommand?: string;
+    /** Runs it. Injected so tests never spawn anything. */
+    runLintCommand?: (template: string, filePath: string, signal?: AbortSignal) => Promise<LintCommandResult>;
+}): AgentTool<{
+    paths: string[];
+}, string>;

package/dist/extensions/tools/check-on-failure.d.ts

@@ -0,0 +1,49 @@
+/**
+ * When a command fails, ask the checker about the file it blamed.
+ *
+ * The two halves of a diagnosis sit in two tools and the model has to think of
+ * joining them. Measured over four transactions, it did not: given `run_commands`
+ * output that named a file and a line, it wrote its own analyser — `find_error.js`,
+ * then `diagnose.mjs`, `diagnose2.mjs`, `diagnose3.mjs` — twenty-two editor calls
+ * across three scratch scripts and not one call to `check_file`. The transaction
+ * that instead read the checker's report fixed the file in one.
+ *
+ * Wording did not close that gap, so the join is made here. It is a wrapper
+ * around the shell tool that calls the host's own checker on the file the
+ * failure names — in the output where the output names one, and otherwise on
+ * the command line itself, which on the measured transaction was 95 commands
+ * out of 96 — and appends the answer to the same result. Nothing about it is
+ * language-specific: the paths are extracted by shape, and the checker is
+ * whichever one the host installed — VS Code's language servers know Python and
+ * Go, the CLI's built-in knows JavaScript and brackets, and both are asked the
+ * same way.
+ */
+import type { AgentTool } from "@cerebriline/shared";
+export interface CheckOnFailureOptions {
+    /** Where relative paths in command output resolve from. */
+    cwd: string;
+    /** The checker to ask. Its report is appended verbatim. */
+    checker: Pick<AgentTool<{
+        paths: string[];
+    }, unknown>, "execute">;
+}
+/**
+ * Wrap a shell tool so failing commands come back with the checker's verdict.
+ *
+ * The wrapper is transparent on success and on output that names no workspace
+ * file, which is most of them: the extraction has to resolve a real path inside
+ * the workspace before anything is run.
+ */
+export declare function withCheckOnFailure<TInput>(shell: AgentTool<TInput, unknown>, options: CheckOnFailureOptions): AgentTool<TInput, unknown>;
+/**
+ * Find the shell tool and the checker in an assembled toolset and join them.
+ *
+ * By name on both sides: a host that swapped in its own `run_commands` or its
+ * own `check_file` gets the same wiring as the builtins, and a host missing
+ * either gets its list back untouched.
+ */
+export declare function joinCheckerToShell<TTool extends AgentTool<never, unknown>>(tools: readonly TTool[], options: {
+    cwd: string;
+    shellName: string;
+    checkerName: string;
+}): TTool[];

package/dist/extensions/tools/code-intel.d.ts

@@ -0,0 +1,131 @@
+import { type AgentTool } from "@cerebriline/shared";
+/**
+ * Hand the model the workspace's language servers.
+ *
+ * VS Code already runs a language server for every language in the workspace,
+ * and those servers already know what every symbol means: where it is defined,
+ * everywhere it is used, what its type is, which classes implement it. None of
+ * that reached the model. It had regex search — `search_codebase` — and a regex
+ * cannot tell a definition from a mention, a method on this class from a method
+ * with the same name on another, or a live reference from one inside a comment.
+ *
+ * So the model compensates by reading. It greps a name, gets forty hits, reads
+ * six files to work out which one is the definition, and spends the turns on
+ * work the editor had already done and would have answered instantly. This is
+ * free capability that was sitting one `executeCommand` away.
+ *
+ * Position resolution is the part that makes it usable. Every LSP request is
+ * addressed by line and character, and a model almost never has those — it has
+ * a name it read in a file. So `symbol` is the primary way to ask, and the
+ * position is found on the model's behalf; line/character are accepted too, for
+ * when it does know.
+ */
+export declare const CODE_INTEL_TOOL_NAME = "code_intel";
+export declare const CODE_INTEL_OPERATIONS: readonly ["definition", "references", "implementations", "type_definition", "hover", "document_symbols", "workspace_symbols", "callers"];
+export type CodeIntelOperation = (typeof CODE_INTEL_OPERATIONS)[number];
+export declare const CODE_INTEL_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. No results is a definite answer \u2014 the language server understands this symbol and nothing matches \u2014 so do not fall back to a text search for the same question.";
+/** Exported for the same reason as `CHECK_FILE_TOOL_INPUT_SCHEMA`. */
+export declare const CODE_INTEL_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly operation: {
+            readonly type: "string";
+            readonly enum: readonly ["definition", "references", "implementations", "type_definition", "hover", "document_symbols", "workspace_symbols", "callers"];
+            readonly description: "What to ask the language server.";
+        };
+        readonly path: {
+            readonly type: "string";
+            readonly description: "File the symbol appears in. Absolute, or relative to the working directory.";
+        };
+        readonly symbol: {
+            readonly type: "string";
+            readonly description: "The symbol's name, as written in that file. The usual way to address a symbol.";
+        };
+        readonly line: {
+            readonly type: "number";
+            readonly description: "1-based line, if you know the exact position.";
+        };
+        readonly character: {
+            readonly type: "number";
+            readonly description: "1-based column, if you know the exact position.";
+        };
+    };
+    readonly required: readonly ["operation"];
+};
+/** A location in a file. Lines and characters are 0-based, as LSP has them. */
+export interface CodeIntelLocation {
+    filePath: string;
+    line: number;
+    character: number;
+}
+export interface CodeIntelSymbol {
+    name: string;
+    /** "class", "function", "method", … — whatever the server calls it. */
+    kind: string;
+    location: CodeIntelLocation;
+    /** The class or module the symbol sits in, when the server says. */
+    containerName?: string;
+}
+/**
+ * Everything this tool needs from the editor.
+ *
+ * An interface rather than direct `vscode` calls so the tool's behaviour — the
+ * position resolution, the fallbacks, the rendering — is testable without an
+ * extension host. `check-file-tool.ts` is built the same way.
+ */
+export interface CodeIntelProvider {
+    /** Locate a name inside one file, for the position-addressed requests. */
+    findSymbolPosition(filePath: string, symbol: string): Promise<CodeIntelLocation | undefined>;
+    definitions(at: CodeIntelLocation): Promise<CodeIntelLocation[]>;
+    typeDefinitions(at: CodeIntelLocation): Promise<CodeIntelLocation[]>;
+    implementations(at: CodeIntelLocation): Promise<CodeIntelLocation[]>;
+    references(at: CodeIntelLocation): Promise<CodeIntelLocation[]>;
+    hover(at: CodeIntelLocation): Promise<string | undefined>;
+    documentSymbols(filePath: string): Promise<CodeIntelSymbol[]>;
+    workspaceSymbols(query: string): Promise<CodeIntelSymbol[]>;
+    callers(at: CodeIntelLocation): Promise<CodeIntelSymbol[]>;
+    /** The source line, so a result is readable without opening the file. */
+    readLine(filePath: string, line: number): Promise<string | undefined>;
+}
+export interface CodeIntelToolOptions {
+    cwd: string;
+    provider: CodeIntelProvider;
+    /**
+     * Where a failed request goes. Injected rather than imported: this tool is
+     * shared by the extension and the CLI, and each has its own logger.
+     */
+    onError?: (message: string, error: unknown) => void;
+}
+interface CodeIntelInput {
+    operation?: unknown;
+    path?: unknown;
+    symbol?: unknown;
+    /**
+     * Accepted as a spelling of `symbol`. `search_codebase` sits next to this
+     * tool and takes `queries`, so a model reaching for a name-search here
+     * reasonably guesses `query` -- observed doing exactly that, which cost a
+     * turn and a fall back to a text search for a question the language server
+     * had already been asked.
+     */
+    query?: unknown;
+    line?: unknown;
+    character?: unknown;
+}
+export interface ParsedCodeIntelRequest {
+    operation: CodeIntelOperation;
+    filePath?: string;
+    symbol?: string;
+    /** 0-based, converted from the 1-based numbers the description asks for. */
+    line?: number;
+    character?: number;
+}
+/**
+ * Read a request, or say what is missing from it.
+ *
+ * Returns a message rather than throwing: an unusable call should cost the
+ * model one sentence telling it what to send, not a tool error it has to
+ * interpret.
+ */
+export declare function parseCodeIntelRequest(input: CodeIntelInput | undefined): ParsedCodeIntelRequest | string;
+export declare function createCodeIntelTool(options: CodeIntelToolOptions): AgentTool;
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * Plan-Mode Command Guard Extension
+ *
+ * Runtime extension that enforces the plan-mode command blacklist
+ * (./command-guard.ts) as a `beforeTool` hook. The runtime builder registers
+ * it for plan-mode sessions, making command blocking session policy in one
+ * shared place: the hook fires for every `run_commands` tool in the runtime —
+ * the SDK built-in and host-provided replacements like the VS Code
+ * extension's terminal-backed tool — without threading a flag through each
+ * layer.
+ *
+ * Because `beforeTool` hooks run before tool policies and user approval,
+ * a blocked call is rejected up front: the user is never asked to approve a
+ * command that would only fail, and the model receives the plan-mode error
+ * as the tool result (`skip`, not `stop`, so the run continues).
+ */
+import type { AgentExtension, ITelemetryService } from "@cerebriline/shared";
+export declare const PLAN_MODE_COMMAND_GUARD_EXTENSION_NAME = "core.plan-mode-command-guard";
+export interface PlanModeCommandGuardOptions {
+    telemetry?: ITelemetryService;
+}
+export declare function createPlanModeCommandGuardExtension(options?: PlanModeCommandGuardOptions): AgentExtension;

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

@@ -0,0 +1,29 @@
+/**
+ * Plan-mode command blacklist for run_commands.
+ *
+ * Plan mode keeps run_commands available for read-only investigation, but
+ * models (especially weaker ones) use it to edit files anyway. When the plan
+ * preset sets `blockFileEditingCommands`, createShellTool checks each command
+ * against this blacklist before executing and returns a tool error instead of
+ * running anything that looks like a file modification.
+ *
+ * This is a simple blacklist, not a shell interpreter. Commands are lightly
+ * preprocessed (quoted text, heredoc bodies, escapes, and comments are masked
+ * 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.
+ */
+import type { StructuredCommandInput } from "./schemas";
+/**
+ * Inspect a run_commands entry and return a short description of the first
+ * file-modifying construct found, or undefined when the command looks
+ * read-only.
+ */
+export declare function findFileEditingCommand(command: string | StructuredCommandInput): string | undefined;
+/**
+ * Tool error returned in place of executing a blocked command in plan mode.
+ */
+export declare function formatPlanModeBlockedCommandError(reason: string): string;

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

@@ -0,0 +1,28 @@
+/**
+ * Constants for Default Tools
+ *
+ * Tool name constants and utility arrays.
+ */
+import type { DefaultToolName } from "./types";
+/**
+ * Constants for default tool names
+ */
+export declare const DefaultToolNames: {
+    readonly READ_FILES: "read_files";
+    readonly SEARCH_CODEBASE: "search_codebase";
+    readonly RUN_COMMANDS: "run_commands";
+    readonly FETCH_WEB_CONTENT: "fetch_web_content";
+    readonly APPLY_PATCH: "apply_patch";
+    readonly EDITOR: "editor";
+    readonly GREP: "grep";
+    readonly SED: "sed";
+    readonly AWK: "awk";
+    readonly EXTRACT_DOCUMENT: "extract_document";
+    readonly SKILLS: "skills";
+    readonly ASK: "ask_question";
+    readonly SUBMIT_AND_EXIT: "submit_and_exit";
+};
+/**
+ * Array of all default tool names
+ */
+export declare const ALL_DEFAULT_TOOL_NAMES: DefaultToolName[];

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

@@ -0,0 +1,178 @@
+/**
+ * Default AgentTool Definitions
+ *
+ * Factory functions for creating the default tools.
+ */
+import { type AgentTool, type ShellKind } from "@cerebriline/shared";
+import { type QaCredential } from "./qa-credentials";
+import { type ApplyPatchInput, type AskQuestionInput, type AwkToolInput, type EditFileInput, type ExtractDocumentInput, type FetchWebContentInput, type GrepToolInput, type ReadFileRequest, type ReadFilesInput, type SearchCodebaseInput, type SedToolInput, type SkillsInput, type SubmitInput } from "./schemas";
+import type { ApplyPatchExecutor, AskQuestionExecutor, AwkExecutor, CreateDefaultToolsOptions, DefaultToolsConfig, EditorExecutor, ExtractDocumentExecutor, FileReadExecutor, GrepExecutor, SearchExecutor, SedExecutor, ShellExecutor, SkillsExecutorWithMetadata, ToolOperationResult, VerifySubmitExecutor, WebFetchExecutor } from "./types";
+/**
+ * What a successful read with no content is told to mean.
+ *
+ * A range whose start is past the end of the file is not an error — the read
+ * succeeds and returns nothing. To a model that is paging through a file, an
+ * empty successful result reads as "nothing here yet, try again", and it does:
+ * measured against a local model, 15 identical `read_files` calls in a row,
+ * which no instruction and no output budget broke out of, because every one of
+ * them looked like a retryable miss. Saying what the emptiness means, and that
+ * there is nothing further to ask for, is what ends the loop.
+ */
+export declare const EMPTY_READ_EXPLANATION = "[no content returned: the requested line range starts past the end of this file, or the file is empty. Do not request another range for this file - use the content you already have.]";
+/**
+ * Create the read_files tool
+ *
+ * Reads the content of one or more files from the filesystem.
+ */
+/**
+ * Every shape `read_files` accepts, reduced to the list of reads it means.
+ *
+ * Exported because the change protocol serves `revision: "base"` from the
+ * transaction's snapshot rather than from disk, and it has to understand a
+ * call exactly as the tool itself does. A second parser would drift, and it
+ * would drift silently: the two only disagree on the odd shapes -- a bare
+ * string, a bracketed path list, a range that arrived detached from its path
+ * -- which are the calls a smaller model actually makes.
+ */
+export declare function readFileRequestsFrom(input: unknown): ReadFileRequest[];
+export declare function createReadFilesTool(executor: FileReadExecutor, config?: Pick<DefaultToolsConfig, "fileReadTimeoutMs">): AgentTool<ReadFilesInput, ToolOperationResult[]>;
+/**
+ * Create the search_codebase tool
+ *
+ * Performs regex pattern searches across the codebase.
+ */
+export declare function createSearchTool(executor: SearchExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "searchTimeoutMs">): AgentTool<SearchCodebaseInput, ToolOperationResult[]>;
+/**
+ * Build the run_commands tool description for the shell that will actually
+ * execute the commands. The shell kind decides the syntax guidance (quoting,
+ * sequencing, heredocs), and isWindows adds environment context for POSIX
+ * shells running on a Windows host (e.g. Git Bash).
+ */
+export declare function buildRunCommandsDescription(shellKind: ShellKind, isWindows: boolean): string;
+/**
+ * Create the run_commands shell tool for the current platform.
+ *
+ * This preserves the SDK's platform-specific prompting/schema choices while
+ * exposing a single generic shell-tool factory for host integrations. Pass
+ * config.shell (matching the executor's shell) so the syntax guidance in the
+ * tool description matches the shell that actually runs the commands.
+ *
+ * config.shell may be a provider function instead of a string. The runtime
+ * reads `description` when building each model request, so a provider is
+ * consulted at that boundary: a shell change made while the model is
+ * generating does not affect the request in flight, and the next request
+ * names the new shell. The provider must return the shell the executor will
+ * use for tool calls issued by that next request.
+ */
+export declare function createShellTool(executor: ShellExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "bashTimeoutMs" | "telemetry"> & {
+    shell?: string | (() => string);
+    /**
+     * QA credentials the user configured.
+     *
+     * A provider rather than a list because the set is editable while a
+     * session runs, and because reading it late keeps the values out of this
+     * closure until a command actually needs one.
+     */
+    qaCredentials?: readonly QaCredential[] | (() => readonly QaCredential[]);
+}): AgentTool<unknown, ToolOperationResult[]>;
+/**
+ * The checklist as a tool in its own right.
+ *
+ * It carries no behaviour: `withTaskProgressCapture` reads the checklist off
+ * the raw input of every tool call, this one included, so the work is already
+ * done by the time `execute` runs. What it adds is a name the model can call
+ * when it has nothing else to do at that moment -- which is exactly when a
+ * plan is usually written, and exactly when there is no other call to attach
+ * it to.
+ */
+export declare function createTaskProgressTool(): AgentTool<Record<string, unknown>, ToolOperationResult[]>;
+/**
+ * Create the fetch_web_content tool
+ *
+ * Fetches content from URLs and analyzes them using provided prompts.
+ */
+export declare function createWebFetchTool(executor: WebFetchExecutor, config?: Pick<DefaultToolsConfig, "webFetchTimeoutMs">): AgentTool<FetchWebContentInput, ToolOperationResult[]>;
+/**
+ * Create the apply_patch tool
+ *
+ * Applies the canonical apply_patch format to one or more files.
+ */
+export declare function createApplyPatchTool(executor: ApplyPatchExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "applyPatchTimeoutMs">): AgentTool<ApplyPatchInput, ToolOperationResult>;
+/**
+ * Create the editor tool
+ *
+ * Supports controlled filesystem edits with create, replace, and insert commands.
+ */
+export declare function createEditorTool(executor: EditorExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "editorTimeoutMs">): AgentTool<EditFileInput, ToolOperationResult>;
+/**
+ * Create the grep tool.
+ */
+export declare function createGrepTool(executor: GrepExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "textToolsTimeoutMs">): AgentTool<GrepToolInput, ToolOperationResult>;
+/**
+ * Create the extract_document tool.
+ *
+ * A reader, and flagged `readOnly`, although it writes: what it writes is its
+ * own output (the text and the pictures of the document it was asked to
+ * read), inside the workspace, never a file the user made.
+ */
+export declare function createExtractDocumentTool(executor: ExtractDocumentExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "extractDocumentTimeoutMs">): AgentTool<ExtractDocumentInput, ToolOperationResult>;
+/**
+ * Create the sed tool.
+ */
+export declare function createSedTool(executor: SedExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "textToolsTimeoutMs">): AgentTool<SedToolInput, ToolOperationResult[]>;
+/**
+ * Create the awk tool.
+ */
+export declare function createAwkTool(executor: AwkExecutor, config?: Pick<DefaultToolsConfig, "cwd" | "textToolsTimeoutMs">): AgentTool<AwkToolInput, ToolOperationResult>;
+/**
+ * Create the skills tool
+ *
+ * Invokes a configured skill by name and optional arguments.
+ */
+export declare function createSkillsTool(executor: SkillsExecutorWithMetadata, config?: Pick<DefaultToolsConfig, "skillsTimeoutMs">): AgentTool<SkillsInput, string>;
+/**
+ * Create the ask_question tool
+ *
+ * Asks the user a single clarifying question with 2-5 selectable options.
+ */
+export declare function createAskQuestionTool(executor: AskQuestionExecutor): AgentTool<AskQuestionInput, string>;
+export declare function createSubmitAndExitTool(executor: VerifySubmitExecutor, config?: Pick<DefaultToolsConfig, "submitTimeoutMs">): AgentTool<SubmitInput, string>;
+/**
+ * Create a set of default tools for an agent
+ *
+ * This function creates the default tools based on the provided configuration
+ * and executors. Only tools that are enabled AND have an executor provided
+ * will be included in the returned array.
+ *
+ * @example
+ * ```typescript
+ * import { Agent, createDefaultTools } from "@cerebriline/core"
+ * import * as fs from "fs/promises"
+ * import { exec } from "child_process"
+ *
+ * const tools = createDefaultTools({
+ *   executors: {
+ *     readFile: async ({ path }) => fs.readFile(path, "utf-8"),
+ *     bash: async (cmd, cwd) => {
+ *       return new Promise((resolve, reject) => {
+ *         exec(cmd, { cwd }, (err, stdout, stderr) => {
+ *           if (err) reject(new Error(stderr || err.message))
+ *           else resolve(stdout)
+ *         })
+ *       })
+ *     },
+ *   },
+ *   enableReadFiles: true,
+ *   enableBash: true,
+ *   enableSearch: false, // Disabled
+ *   enableWebFetch: false, // Disabled
+ *   cwd: "/path/to/project",
+ * })
+ *
+ * const agent = new Agent({
+ *   // ... provider config
+ *   tools,
+ * })
+ * ```
+ */
+export declare function createDefaultTools(options: CreateDefaultToolsOptions): AgentTool[];