@cerebriline/core 4.100.240

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

@@ -0,0 +1,93 @@
+/**
+ * What the filesystem said about a file the last time this session saw it.
+ *
+ * Size and modification time, not a content hash, and that is the deciding
+ * property rather than a shortcut: it costs one `stat` instead of a read, so
+ * the *write* path can check it before doing any work and a 4 MB file is as
+ * cheap as an empty one. A hash would mean reading every file before every
+ * edit to answer a question that is almost always "nothing happened".
+ *
+ * Nanosecond precision, because millisecond is not enough: a same-length
+ * rewrite inside one millisecond is an ordinary thing for a script to do, and
+ * the whole point here is catching writes this session did not make.
+ *
+ * `absent` is a real value, not a failure: a file appearing or disappearing
+ * under the session is exactly the kind of change worth reporting. Failure is
+ * `undefined`, which never compares unequal to anything — a stamp that cannot
+ * be taken must not be allowed to invent a change.
+ */
+export type FileStamp = string;
+export declare function readFileStamp(filePath: string): Promise<FileStamp | undefined>;
+export interface ReadReceipts {
+    /** Record that `filePath` was read over the given inclusive line span. */
+    noteRead(filePath: string, first: number, last: number): void;
+    /** Whether a read has covered every line in the inclusive range. */
+    covers(filePath: string, first: number, last: number): boolean;
+    /** Whether the file has been read at all in this session. */
+    hasAny(filePath: string): boolean;
+    /**
+     * Whether the file was ever read, counting reads a write has since retired.
+     *
+     * For an edit anchored to text rather than to line numbers. Retirement is
+     * about line numbers having moved, and a text match does not use them: the
+     * file itself is checked for the text at the moment of the edit, so a read
+     * whose line numbers went stale is still a model that has seen this file.
+     *
+     * Measured: a model read the file, made two edits that changed its length,
+     * and its next text-anchored edit was refused with "has not been read in
+     * this session" -- of a file it had read and just successfully edited.
+     */
+    hasEverRead(filePath: string): boolean;
+    /**
+     * Whether reads of this file were retired by a later write.
+     *
+     * Told apart from "never read" because the two need different advice: one
+     * model has to go and look, the other looked and had the ground move.
+     */
+    wasRetired(filePath: string): boolean;
+    /**
+     * Record a write. When the line count changed, receipts for the file are
+     * dropped: every line number below the edit now points somewhere else.
+     */
+    noteWrite(filePath: string, linesBefore: number, linesAfter: number): void;
+    /**
+     * Record what the filesystem said about the file, as of now.
+     *
+     * Called by every tool that reads a file and by every tool that writes one,
+     * the latter *after* its write — otherwise the session's own edit is
+     * indistinguishable from someone else's and the next call bounces on it.
+     * `undefined` records nothing, so a stat that failed leaves the last known
+     * stamp standing rather than erasing it.
+     */
+    noteStamp(filePath: string, stamp: FileStamp | undefined): void;
+    /**
+     * Whether the file changed since this session last looked at it.
+     *
+     * False unless there is something to compare: an unknown file has not
+     * changed, it has merely never been seen, and reporting a change there
+     * would fire on the first read of everything.
+     */
+    changedSince(filePath: string, stamp: FileStamp | undefined): boolean;
+    /**
+     * Retire this file's line spans without forgetting that it was read.
+     *
+     * What {@link noteWrite} does when the line count moved, for the case where
+     * the mover was not this session: the spans are wrong either way, and the
+     * model still needs to be told apart from one that never looked — those two
+     * get different advice.
+     */
+    retire(filePath: string): void;
+    /** Drop everything known about a file. */
+    forget(filePath: string): void;
+    /**
+     * Every file read in this session, in the form it was resolved to.
+     *
+     * The receipts are the only record of which files the model has actually
+     * touched, and they are kept whatever the file's location -- which makes
+     * them the honest answer when a workspace-scoped search cannot find one.
+     * Retired reads are included: a file whose receipts a write invalidated was
+     * still read, and is still where it was.
+     */
+    paths(): string[];
+}
+export declare function createReadReceipts(): ReadReceipts;

package/dist/extensions/tools/executors/run-command-execution-controller.d.ts

@@ -0,0 +1,16 @@
+export interface RunningCommandRegistration {
+    executionId: string;
+    sessionId: string;
+    toolCallId?: string;
+    detach: () => boolean;
+}
+/**
+ * Tracks shell processes that can release their owning tool call while the
+ * process keeps running. The controller is host-scoped so hub commands can
+ * target only commands owned by a particular session/tool call.
+ */
+export declare class RunCommandExecutionController {
+    private readonly commands;
+    register(command: RunningCommandRegistration): () => void;
+    proceedWhileRunning(sessionId: string, toolCallId?: string): number;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Search Executor
+ *
+ * Built-in implementation for searching the codebase using ripgrep (if available) or regex.
+ */
+import type { SearchExecutor } from "../types";
+/**
+ * Options for the search executor
+ */
+export interface SearchExecutorOptions {
+    /**
+     * File extensions to include in search (without dot)
+     * @default common code extensions
+     */
+    includeExtensions?: string[];
+    /**
+     * Directories to exclude from search
+     * @default ["node_modules", ".git", "dist", "build", ".next", "coverage"]
+     */
+    excludeDirs?: string[];
+    /**
+     * Maximum number of results to return
+     * @default 100
+     */
+    maxResults?: number;
+    /**
+     * Number of context lines before and after match
+     * @default 2
+     */
+    contextLines?: number;
+    /**
+     * Maximum depth to traverse
+     * @default 20
+     */
+    maxDepth?: number;
+}
+/**
+ * Create a search executor using regex pattern matching
+ *
+ * @example
+ * ```typescript
+ * const search = createSearchExecutor({
+ *   maxResults: 50,
+ *   contextLines: 3,
+ * })
+ *
+ * const results = await search("function\\s+handleClick", "/path/to/project", context)
+ * ```
+ */
+export declare function createSearchExecutor(options?: SearchExecutorOptions): SearchExecutor;

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

@@ -0,0 +1,92 @@
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import { type ReadReceipts } from "./read-receipts";
+type Address = {
+    kind: "line";
+    line: number;
+} | {
+    kind: "last";
+} | {
+    kind: "regex";
+    regex: RegExp;
+} | {
+    kind: "every";
+};
+interface Command {
+    start?: Address;
+    end?: Address;
+    negated: boolean;
+    name: string;
+    /** For `s`: the compiled match. For `y`: unused. */
+    regex?: RegExp;
+    replacement?: string;
+    /** For `s`: replace every occurrence. */
+    global?: boolean;
+    /** For `s`: print the line when a substitution happened. */
+    print?: boolean;
+    /** For `s`: replace only the Nth occurrence. */
+    occurrence?: number;
+    /** For `y`: the from/to character maps. */
+    from?: string;
+    to?: string;
+    /** For `a`, `i`, `c`: the text. */
+    text?: string;
+    /** Range state while executing. */
+    active?: boolean;
+}
+/**
+ * Parse a sed script into commands.
+ *
+ * Commands are separated by `;` or a newline, except inside a delimited
+ * section — `s/a;b/c/` is one command, and splitting on `;` first would break
+ * it. So the script is walked rather than split.
+ */
+export declare function parseSedScript(script: string, extended?: boolean): Command[];
+export interface RunSedResult {
+    output: string;
+    /** Whether any command changed the text. */
+    changed: boolean;
+}
+/** Run a parsed script over text. Pure: no filesystem, so it is easy to test. */
+export declare function runSedScript(input: string, commands: Command[], quiet?: boolean): RunSedResult;
+export interface SedExecutorOptions {
+    cwd?: string;
+    /**
+     * The same registry `editor` and `read_files` use.
+     *
+     * An in-place `sed` is an edit, and must answer to the read-before-change
+     * rule exactly as `editor` does. Without this the tool would be a way to
+     * modify a file the model has never looked at, which is the failure the
+     * receipts exist to stop.
+     */
+    receipts?: ReadReceipts;
+    /** A delegated agent's overlay; an in-place sed writes into it, not the workspace. */
+    overlay?: AgentOverlay;
+}
+export interface SedInput {
+    script: string;
+    files: string[];
+    in_place?: boolean;
+    quiet?: boolean;
+    extended?: boolean;
+}
+/**
+ * What happened to one file.
+ *
+ * One `sed` call names a list of files, and they do not share a fate: an
+ * in-place run can write the first and be refused on the second for never
+ * having been read. Joining that into one string made a refusal indexable only
+ * by reading the prose — and the tool layer above reported the whole call as a
+ * success, which is the one thing a blocked write must never look like.
+ */
+export interface SedFileOutcome {
+    /** The file as the caller named it, not as it was resolved. */
+    file: string;
+    /** The script's output for this file, or a sentence describing the write. */
+    output: string;
+    /** False only when the file was NOT touched: a guard, or an unreadable file. */
+    ok: boolean;
+    /** Why, when `ok` is false. */
+    error?: string;
+}
+export declare function createSedExecutor(options?: SedExecutorOptions): (input: SedInput, callCwd?: string) => Promise<SedFileOutcome[]>;
+export {};

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

@@ -0,0 +1,55 @@
+/**
+ * Answer a re-read of a file that has not changed with a pointer, not a copy.
+ *
+ * Measured on a live pandorum session (1789035782295_5ag8n, cline 4.100.87,
+ * ornith 27B): `read_files` was called 33 times, and 31 of those calls were
+ * byte-identical -- the whole of `manic_miner.html`, over and over, with edits
+ * in between. The results totalled 440,013 characters, roughly 110,000 tokens,
+ * against a file of about 14 KB. The run's entire reasoning came to 27,000
+ * tokens; four times that was spent re-reading one file.
+ *
+ * The existing loop guard cannot see this. It counts strikes per signature but
+ * only for calls that *fail*, deliberately: re-running a check after each edit
+ * is how work gets done, and a success clears the tally. These reads all
+ * succeed. It also cannot see it as adjacency -- the longest run of consecutive
+ * identical calls in that session was two, because an `editor` call always sat
+ * in between.
+ *
+ * So the test here is neither "it repeated" nor "it failed", but something
+ * provable: the bytes coming back are the bytes that already went back. When
+ * the content is identical, a second copy carries no information the
+ * conversation does not already hold.
+ *
+ * THE HAZARD, and why the valve exists. "Already in the conversation" stops
+ * being true after a compaction: the earlier read may have been summarised
+ * away, and a model told "unchanged since you last read it" would then be
+ * pointed at something it can no longer see. Rather than reach into the
+ * compaction machinery, every `REFRESH_EVERY` repeats serves the real content
+ * again. A compacted context recovers on its own within a few calls, while a
+ * loop still pays a fraction of what it used to.
+ */
+/** How often a repeat is answered with the content anyway, compaction insurance. */
+export declare const REFRESH_EVERY = 4;
+/** What identifies "the same read": the file and the window asked for. */
+export interface ReadKeyParts {
+    path: string;
+    firstLine: number;
+    lastLine: number;
+    withLineNumbers: boolean;
+}
+export interface ReadLedger {
+    /**
+     * What to return for this read, or `undefined` to return the content.
+     *
+     * Records the content either way, so the next identical read can be
+     * compared against it.
+     */
+    noticeFor(parts: ReadKeyParts, text: string): string | undefined;
+}
+/**
+ * A ledger of what this session has already returned for each read.
+ *
+ * Per session, not per transaction: the conversation is what holds the earlier
+ * copy, and it outlives any one transaction.
+ */
+export declare function createReadLedger(): ReadLedger;

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

@@ -0,0 +1,58 @@
+/**
+ * Web Fetch Executor
+ *
+ * Built-in implementation for fetching web content using native fetch.
+ */
+import type { WebFetchExecutor } from "../types";
+/**
+ * Options for the web fetch executor
+ */
+export interface WebFetchExecutorOptions {
+    /**
+     * Timeout for fetch requests in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum response size in bytes
+     * @default 5_000_000 (5MB)
+     */
+    maxResponseBytes?: number;
+    /**
+     * User agent string
+     * @default "Mozilla/5.0 (compatible; AgentBot/1.0)"
+     */
+    userAgent?: string;
+    /**
+     * Additional headers
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to follow redirects
+     * @default true
+     */
+    followRedirects?: boolean;
+    /**
+     * Maximum number of redirects to follow
+     * @default 5
+     */
+    maxRedirects?: number;
+}
+/**
+ * Create a web fetch executor using native fetch
+ *
+ * @example
+ * ```typescript
+ * const webFetch = createWebFetchExecutor({
+ *   timeoutMs: 15000,
+ *   maxResponseBytes: 2_000_000,
+ * })
+ *
+ * const content = await webFetch(
+ *   "https://docs.example.com/api",
+ *   "Extract the authentication section",
+ *   context
+ * )
+ * ```
+ */
+export declare function createWebFetchExecutor(options?: WebFetchExecutorOptions): WebFetchExecutor;

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

@@ -0,0 +1,59 @@
+import { type EditFileInput, type ReadFileRequest, type StructuredCommandInput } from "./schemas";
+/**
+ * Format an error into a string message
+ */
+export declare function formatError(error: unknown): string;
+export declare function getEditorSizeError(input: EditFileInput): string | null;
+/**
+ * Create a timeout-wrapped promise
+ */
+export declare class TimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T>;
+export declare function formatReadFileQuery(request: ReadFileRequest): string;
+export declare function getReadFileRangeError(request: ReadFileRequest): string | null;
+/**
+ * Some models emit a file's line range as a separate array element instead of
+ * placing start_line/end_line on the same object as its path. Fold such
+ * orphan range entries into the preceding file entry before validation.
+ */
+export declare function coalesceOrphanReadRanges(input: unknown): unknown;
+/**
+ * Read a path field whose value is a list rendered as a string.
+ *
+ * Returns the paths it contains, or null when the value is an ordinary path.
+ * Only a value that is bracketed end to end qualifies — a path that merely
+ * contains a bracket is left alone.
+ */
+export declare function parseBracketedPathList(value: string): string[] | null;
+/**
+ * Expand a path field holding a bracketed list into the real list.
+ *
+ * `read_files` is plural and its sibling `check_file` takes `paths: [...]`,
+ * so a model that has just used one reaches for an array here too — but
+ * `path` is a string, and a string is what a bracketed list validates as.
+ * Measured on a 156-message session: three consecutive calls sent
+ * `path: "[\"c:\\...\\game.js\"]"`, `"[c:\\...\\game.js]"` and
+ * `"[c:/.../game.js]"`, each of which passed validation and was then joined
+ * onto the cwd, so all three came back
+ * `ENOENT ... stat 'c:\...\test\["c:\...\game.js"]'`. The list was always
+ * there in the argument; nothing was reading it as one.
+ */
+export declare function expandBracketedPathLists(input: unknown): unknown;
+export declare function normalizeRunCommandsInput(input: unknown): Array<string | StructuredCommandInput>;
+export declare function formatRunCommandQuery(command: string | StructuredCommandInput): string;
+/**
+ * Max characters of the executed command echoed back in the tool result's
+ * `query` field. The full command already exists in the assistant tool-call
+ * input, so repeating it in the result only duplicates tokens in the
+ * provider request (expensive for large heredoc/file-generation commands).
+ */
+export declare const RUN_COMMAND_QUERY_PREVIEW_LIMIT = 200;
+/**
+ * Bound the command echo placed in a provider-facing tool result.
+ * Short commands pass through unchanged; long commands keep a short
+ * prefix plus a truncation note so the result is still identifiable.
+ */
+export declare function formatRunCommandQueryPreview(command: string | StructuredCommandInput): string;

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

@@ -0,0 +1,76 @@
+/**
+ * A tool that changes a picture.
+ *
+ * `generate_image` makes one from nothing, and the next thing anyone wants is
+ * to keep most of it: the same icon on a transparent ground, the same mockup
+ * with the sidebar on the other side, a logo placed on a photograph. Asking a
+ * generator again gets a different picture, not a corrected one.
+ *
+ * The wire format is the OpenAI images API's edit route
+ * (`POST {endpoint}/images/edits`, multipart), which opencoti and xOllama
+ * serve beside the generation route and which the hosted services serve too.
+ * The images go as `image[]`, one or several: an edit model takes the extra
+ * ones as references. What "edit" means is the model's: an instruction-edit
+ * model (FLUX.2 klein, Qwen-Image) follows the prompt, a plain diffusion model
+ * redraws over the source (img2img), and a `mask` limits either to a region.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import { type ImageGenerationEndpoint } from "./image-generation";
+export declare const EDIT_IMAGE_TOOL_NAME = "edit_image";
+export declare const EDIT_IMAGE_TOOL_DESCRIPTION = "Edit an existing image in the workspace according to a text instruction and save the result as a new file. Use it to change a picture you already have rather than generate a different one: recolour or restyle an icon, change one element of a mockup, combine a subject with a background.\n\nThe result is written to a file and, if you can see images, returned to you as well \u2014 so you can check the edit and try again with a changed instruction if it is wrong. The source images are never modified.\n\nArguments:\n- `prompt` \u2014 what to change, as an instruction: \"make the background transparent\", \"replace the red door with a blue one\". Say what must stay the same when it matters.\n- `images` \u2014 the image files to edit, as workspace paths. The first is the image being edited; any others are references the model may draw from (a style, a subject to place). Most backends take one to three.\n- `mask` \u2014 optional workspace path of a mask image the same size as the first image. Only the masked region is changed.\n- `path` \u2014 where to save the result, relative to the workspace. Optional; defaults to a file under `.cline/generated-images/`.\n- `size` \u2014 `WxH` in pixels, e.g. `1024x1024`. Optional, and the backend may round it or keep the source's size.\n\nHow far an edit goes depends on the backend: some follow the instruction, others redraw over the source and only make small changes. Look at the result before relying on it. This costs real time \u2014 seconds to a minute per image \u2014 and on a hosted backend it costs money.";
+export declare const EDIT_IMAGE_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "What to change, as an instruction. Say what must stay the same when it matters.";
+        };
+        readonly images: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Workspace paths of the images. The first is the one being edited; the rest are references.";
+        };
+        readonly mask: {
+            readonly type: "string";
+            readonly description: "Workspace path of a mask the same size as the first image. Optional; only the masked region is changed.";
+        };
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Where to save the result, relative to the workspace. Optional; defaults to a file under .cline/generated-images/.";
+        };
+        readonly size: {
+            readonly type: "string";
+            readonly description: "Pixel size as \"WIDTHxHEIGHT\", e.g. \"1024x1024\". Optional.";
+        };
+    };
+    readonly required: readonly ["prompt", "images"];
+};
+export interface EditImageToolInput {
+    prompt?: unknown;
+    images?: unknown;
+    mask?: unknown;
+    path?: unknown;
+    size?: unknown;
+}
+export interface EditImageToolOptions {
+    cwd: string;
+    /** Where edits go. The same shape as generation's: URL, model, key, size. */
+    getEndpoint: () => ImageGenerationEndpoint | undefined | Promise<ImageGenerationEndpoint | undefined>;
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    writeFile: (absolutePath: string, data: Buffer) => Promise<void>;
+    fetchImpl?: typeof fetch;
+    /** Milliseconds one edit may take. Defaults to 3 minutes. */
+    timeoutMs?: number;
+    onError?: (message: string, error: unknown) => void;
+}
+/** The paths the model named, as a list, whichever way it wrote them. */
+export declare function parseImagePaths(value: unknown): string[];
+/**
+ * Create the `edit_image` tool.
+ *
+ * Like `generate_image`, the host leaves it out when nothing is configured,
+ * and `getEndpoint` returning nothing is handled anyway.
+ */
+export declare function createEditImageTool(options: EditImageToolOptions): AgentTool;