@cerebriline/core 4.100.240

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

@@ -0,0 +1,121 @@
+/**
+ * Where a file's brackets stop matching.
+ *
+ * A language server reports a parse error at the point the parser gave up,
+ * which for a crossed bracket is the closer — never the opener it failed to
+ * match. That leaves the one question a model actually needs answered
+ * unanswered: *which* opening bracket does this belong to.
+ *
+ * Measured on a 265-message session: 23 of 29 shell commands were a
+ * brace-counting Python script the model wrote itself, because nothing here
+ * answered the question. It then declared the two remaining errors "parser
+ * artifacts from the very long single line" and stopped. They were not — the
+ * scan below locates both in one pass:
+ *
+ *   MISMATCH: '{' opened at column 2352 closed by ')' at column 2707
+ *   MISMATCH: '(' opened at column 2348 closed by '}' at column 3744
+ *
+ * which is exactly where `node --check` fails.
+ */
+export interface DelimiterFinding {
+    kind: "mismatch" | "unmatched-close" | "unclosed";
+    /** 1-based position of the delimiter that is wrong. */
+    line: number;
+    column: number;
+    /** The character at that position, when there is one. */
+    found?: string;
+    /** 1-based position of the opener involved, for a mismatch or unclosed. */
+    openLine?: number;
+    openColumn?: number;
+    opener?: string;
+    /**
+     * What was still open around this point, innermost first — the chain a
+     * model otherwise rebuilds by hand. Recorded with the opener this finding
+     * names already taken off, so it reads as the context the fix sits in.
+     */
+    enclosing?: Array<{
+        opener: string;
+        line: number;
+        column: number;
+    }>;
+}
+interface Cursor {
+    line: number;
+    column: number;
+}
+/** Opens minus closes on one line, per bracket kind, counting code only. */
+export interface LineBalance {
+    round: number;
+    square: number;
+    curly: number;
+}
+export interface DelimiterScan {
+    findings: DelimiterFinding[];
+    /** Keyed by 1-based line number. Absent means the line held no brackets. */
+    balance: Map<number, LineBalance>;
+}
+/**
+ * Scan one span of C-family source and report where its delimiters cross.
+ *
+ * Strings, template literals, comments and regex literals are skipped, so a
+ * brace inside `"}"` does not count — which is the difference between this and
+ * counting characters, and the reason a hand-rolled counter misleads.
+ */
+export declare function scanDelimiters(text: string, origin?: Cursor): DelimiterFinding[];
+/**
+ * The same scan, keeping the per-line tally it passes over anyway.
+ *
+ * The tally is what turns a crossing into an instruction. A report can say
+ * where two brackets cross, but not whether the fix is to delete one, add one
+ * or move one — and on a minified line those are very different edits. The
+ * counts settle it, and they are free: the walk already visits every bracket
+ * in code and skips every one in a string.
+ */
+export declare function scanWithBalance(text: string, origin?: Cursor): DelimiterScan;
+/**
+ * How a prescribed repair opens, so a caller can tell a scan that names the
+ * exact call from one that only names the line.
+ *
+ * Exported rather than matched by hand: the editor appends to this line, and a
+ * reworded prescription that silently stopped being recognised would take the
+ * follow-up with it.
+ */
+export declare const PRESCRIPTION_MARKER = "that edit is `editor` with ";
+/**
+ * Whether this scanner reads the given file's language at all.
+ *
+ * `describeDelimiterBalance` returns null for two different reasons — nothing
+ * is wrong, and nothing was looked at — and a caller that reports the result
+ * has to tell them apart. Saying "no problems" about a file no checker opened
+ * is the one output worse than silence.
+ */
+export declare function canScanDelimiters(filePath: string): boolean;
+/**
+ * Whether a file's scripts parse at all, asked of a real parser.
+ *
+ * Not a second delimiter scan. The scan is a heuristic and is here to *place*
+ * a parse error the browser could only name; this answers the prior question —
+ * is there one — with the engine's own answer, so it can be trusted where a
+ * heuristic cannot: to contradict a browser that reported a clean page.
+ *
+ * Measured, and this is why it exists: a run edited a 14 KB page into a state
+ * where `forEach(e=>{…};` left a `;` inside an argument list, opened it in the
+ * browser, and was told "Console: nothing. The page printed no messages and
+ * threw no errors." The page had never run. The model reported the task
+ * finished on that evidence, and the transaction was kept over a file that
+ * does not parse.
+ *
+ * `new Function` rather than `vm.Script`, which parses lazily under Bun and
+ * throws nothing at all on broken source. The body is wrapped in a function,
+ * so a `return` at the top level passes here and would not in a real script —
+ * a miss, which is the safe direction: this only ever speaks up when a parser
+ * has actually refused the source.
+ */
+export declare function findScriptSyntaxError(filePath: string, text: string): string | undefined;
+/**
+ * Render the balance findings for a file, or null when there is nothing
+ * useful to say — the file's language is not one this understands, or its
+ * delimiters match.
+ */
+export declare function describeDelimiterBalance(filePath: string, text: string): string | null;
+export {};

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

@@ -0,0 +1,86 @@
+import type { AgentTool } from "@cerebriline/shared";
+/**
+ * Files the model changed and has not checked since.
+ *
+ * A run that edits and never re-checks is the ordinary failure, not the
+ * exceptional one. Measured on a live session, the whole tool sequence:
+ *
+ * ```
+ * list_files → browser → read_files → check_file → editor → editor → editor → editor
+ * ```
+ *
+ * The linter ran once, *before* anything was touched, and then four consecutive
+ * edits landed with nothing checking them. Sixteen problems in the file
+ * afterwards. The model was not missing a tool — `check_file` was right there
+ * and it had already used it once.
+ *
+ * So this is a guard rather than a paragraph of instruction. A model that
+ * ignores a linter it has already run will ignore a sentence asking it to run
+ * one again; what it cannot ignore is not being allowed to finish. The same
+ * reasoning, and the same two-strike shape, as the checklist close-out.
+ *
+ * Deliberately generic. The checker on the VS Code path is `check_file`, which
+ * lives in the extension rather than in the SDK, and a host may have another
+ * one or none at all — so the tool names are supplied rather than assumed, and
+ * a host that names no checker gets no guard.
+ */
+/** How the host names the tools that edit and the tools that verify. */
+export interface EditVerificationConfig {
+    /** Tools whose calls mark a file as changed. */
+    editTools: readonly string[];
+    /** Tools whose calls mark a file as verified. */
+    checkTools: readonly string[];
+    /**
+     * How many times the guard may hold the run back. Beyond this it stands
+     * aside: the model has been told twice and the work is the user's to judge.
+     */
+    attempts?: number;
+}
+export declare const EDIT_VERIFICATION_ATTEMPTS = 2;
+/** Files edited since they were last checked, in the order they were edited. */
+export interface EditVerificationState {
+    unchecked: readonly string[];
+}
+/**
+ * Every file path an argument bag names, whatever shape it names them in.
+ *
+ * `editor` sends `path`, `check_file` sends `paths`, and `read_files` sends
+ * `files: [{ path }]`. Reading one shape would silently cover one tool, which
+ * is the failure mode this whole module exists to answer, so all three are
+ * read and anything unrecognised contributes nothing.
+ */
+export declare function extractPaths(input: unknown): string[];
+/** Tracks which edited files are still unverified. */
+export declare class EditVerificationTracker {
+    private readonly editTools;
+    private readonly checkTools;
+    /** Normalised path → the path as the model wrote it, for the message. */
+    private readonly unchecked;
+    constructor(config: EditVerificationConfig);
+    /** Whether this tracker can ever have anything to say. */
+    get armed(): boolean;
+    recordToolCall(toolName: string, input: unknown): void;
+    getState(): EditVerificationState;
+    reset(): void;
+}
+/** What the model is told, naming the files rather than the rule. */
+export declare function buildUncheckedEditsNudge(unchecked: readonly string[], checkTool: string, attempt: 1 | 2): string;
+/**
+ * A completion guard that holds the run back while an edit is unverified.
+ *
+ * Returns `undefined` — letting the run end — when there is nothing unchecked,
+ * when the host named no checker, or once the attempts are spent. It never
+ * blocks indefinitely: two refusals is a warning, a third would be an argument.
+ */
+export declare function createEditVerificationCompletionGuard(tracker: EditVerificationTracker, config: EditVerificationConfig): () => string | undefined;
+/** Whether a tool has already been wrapped for edit tracking. */
+export declare function isEditVerificationWrapped(tool: object): boolean;
+/**
+ * Watch a tool's calls without changing what it does.
+ *
+ * Only the call is observed — not the result. A failed edit still counts as
+ * having touched the file: the tool may have written part of it, and a guard
+ * that trusted `success` would be answering a different question than "is this
+ * file in a state anyone has looked at".
+ */
+export declare function withEditVerificationCapture<TInput, TOutput>(tool: AgentTool<TInput, TOutput>, tracker: EditVerificationTracker): AgentTool<TInput, TOutput>;

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

@@ -0,0 +1,53 @@
+/**
+ * The files a command's output blames, whatever produced the output.
+ *
+ * A model that runs the build gets told *that* something is broken and where
+ * the tool gave up. A checker tells it *which line to edit*. Measured across
+ * four transactions on three builds of the harness arm: the model that had the
+ * first and not the second wrote its own analyser rather than asking for the
+ * second — `find_error.js`, then five checkers in one transaction, then
+ * `diagnose.mjs`, `diagnose2.mjs`, `diagnose3.mjs`. Sixty-two minutes of one
+ * transaction went into scripts and the broken file was never opened.
+ *
+ * Instructions did not move that. So the two halves are joined here instead:
+ * name a file in a failing command's output and the host's own checker is asked
+ * about it, without the model having to think of it.
+ *
+ * Nothing here knows a language. It matches the shapes compilers, linters and
+ * runtimes use to say "here", and every candidate has to resolve to a file that
+ * actually exists inside the workspace before it is believed — which is what
+ * rejects a URL, a version string and a line of prose that happens to hold a
+ * colon.
+ */
+export interface ErrorLocation {
+    /** Absolute path, verified to exist and to sit inside the workspace. */
+    path: string;
+    /** The line the output blamed, when it gave one. */
+    line?: number;
+}
+/** Whether this output is worth asking a checker about at all. */
+export declare function looksLikeFailure(output: string, exitedNonZero: boolean): boolean;
+/**
+ * The workspace files a command names in its own arguments.
+ *
+ * The fallback for the case the output patterns cannot cover, and it is the
+ * common one rather than the exotic one. Measured on the harness arm: of 96
+ * commands in one transaction, exactly one printed a `file:line` — because the
+ * page under repair is HTML, `node` cannot run it directly, and the model's own
+ * wrapper scripts caught the parse error and printed a summary of their own
+ * devising. The file was named on the command line every time: `node
+ * run_game.js manic_miner.html`, `node diagnose8.js manic_miner.html`.
+ *
+ * Argument order is kept, which puts the runner script before the file it runs;
+ * both are checked, and a broken runner is worth hearing about too.
+ */
+export declare function findCommandFileTargets(command: string, workspace: string): string[];
+/**
+ * Every workspace file the output points at, in the order it points at them.
+ *
+ * Resolution against the workspace is the whole filter. A path that does not
+ * exist was never a path, and one that exists outside the workspace belongs to
+ * a dependency or the toolchain — asking a checker about `node_modules` or
+ * `/usr/lib/python3` answers a question nobody asked.
+ */
+export declare function findErrorLocations(output: string, workspace: string): ErrorLocation[];

package/dist/extensions/tools/executors/apply-patch-parser.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Apply Patch parser and patch model types.
+ *
+ * This parser supports the Cline apply_patch format used by the legacy runtime.
+ */
+export declare const PATCH_MARKERS: {
+    readonly BEGIN: "*** Begin Patch";
+    readonly END: "*** End Patch";
+    readonly ADD: "*** Add File: ";
+    readonly UPDATE: "*** Update File: ";
+    readonly DELETE: "*** Delete File: ";
+    readonly MOVE: "*** Move to: ";
+    readonly SECTION: "@@";
+    readonly END_FILE: "*** End of File";
+};
+export declare const BASH_WRAPPERS: readonly ["%%bash", "apply_patch", "EOF", "```"];
+export declare enum PatchActionType {
+    ADD = "add",
+    DELETE = "delete",
+    UPDATE = "update"
+}
+export interface PatchChunk {
+    origIndex: number;
+    delLines: string[];
+    insLines: string[];
+}
+export interface PatchAction {
+    type: PatchActionType;
+    newFile?: string;
+    chunks: PatchChunk[];
+    movePath?: string;
+}
+export interface PatchWarning {
+    path: string;
+    chunkIndex?: number;
+    message: string;
+    context?: string;
+}
+export interface Patch {
+    actions: Record<string, PatchAction>;
+    warnings?: PatchWarning[];
+}
+export declare class DiffError extends Error {
+    constructor(message: string);
+}
+export declare class PatchParser {
+    private readonly lines;
+    private readonly currentFiles;
+    private patch;
+    private index;
+    private fuzz;
+    private currentPath?;
+    constructor(lines: string[], currentFiles: Record<string, string>);
+    parse(): {
+        patch: Patch;
+        fuzz: number;
+    };
+    private addWarning;
+    private skipBeginSentinel;
+    private hasMoreLines;
+    private isEndMarker;
+    private parseNextAction;
+    private checkDuplicate;
+    private parseUpdate;
+    private parseUpdateFile;
+    private parseDelete;
+    private parseAdd;
+}

package/dist/extensions/tools/executors/apply-patch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Apply Patch Executor
+ *
+ * Built-in implementation for the documented GPT-5 apply_patch grammar.
+ * It accepts the freeform patch body directly and tolerates the legacy shell
+ * wrapper form used by older prompts.
+ */
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import type { ApplyPatchExecutor } from "../types";
+import { PatchActionType } from "./apply-patch-parser";
+export interface PatchFileChange {
+    type: PatchActionType;
+    oldContent?: string;
+    newContent?: string;
+    movePath?: string;
+}
+/**
+ * Options for the apply_patch executor
+ */
+export interface ApplyPatchExecutorOptions {
+    /**
+     * File encoding used for read/write operations
+     * @default "utf-8"
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Restrict relative-path file operations to paths inside cwd.
+     * Absolute paths are always accepted as-is.
+     * @default true
+     */
+    restrictToCwd?: boolean;
+    /** A delegated agent's overlay; the patch reads and writes the agent's copies. */
+    overlay?: AgentOverlay;
+}
+/**
+ * Parse a patch and compute the per-file changes it would apply, without
+ * writing anything to disk. Reads the current contents of the files the patch
+ * references. Exposed so hosts can preview a patch (e.g. in a diff editor)
+ * before the executor applies it.
+ */
+export declare function computePatchChanges(patchText: string, cwd: string, options?: ApplyPatchExecutorOptions): Promise<{
+    changes: Record<string, PatchFileChange>;
+    fuzz: number;
+}>;
+/**
+ * Create an apply_patch executor using Node.js fs module.
+ */
+export declare function createApplyPatchExecutor(options?: ApplyPatchExecutorOptions): ApplyPatchExecutor;

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

@@ -0,0 +1,163 @@
+/**
+ * A lexer and parser for the POSIX awk language.
+ *
+ * Split from the interpreter because the two fail for entirely different
+ * reasons and a model needs to be told which: a parse error means the program
+ * it wrote is not awk, and a run error means the program is awk but did
+ * something impossible. Reporting both as "awk failed" would teach it nothing.
+ *
+ * The subset is the one a coding model actually writes: `{print $1}`,
+ * `-F, '$3>10 {print $1}'`, `NR>1 {sum+=$2} END {print sum}`,
+ * `/ERROR/ {print NR": "$0}`. User-defined functions and `getline` are not
+ * supported and are refused by name — see the interpreter's note on why
+ * refusing beats silently doing nothing.
+ */
+export type Token = {
+    kind: "number";
+    value: number;
+} | {
+    kind: "string";
+    value: string;
+} | {
+    kind: "regex";
+    value: string;
+} | {
+    kind: "name";
+    value: string;
+} | {
+    kind: "builtin";
+    value: string;
+} | {
+    kind: "keyword";
+    value: string;
+} | {
+    kind: "punct";
+    value: string;
+} | {
+    kind: "newline";
+} | {
+    kind: "eof";
+};
+export declare function tokenizeAwk(source: string): Token[];
+export type Expr = {
+    type: "number";
+    value: number;
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "regex";
+    value: string;
+} | {
+    type: "var";
+    name: string;
+} | {
+    type: "field";
+    index: Expr;
+} | {
+    type: "index";
+    name: string;
+    keys: Expr[];
+} | {
+    type: "assign";
+    op: string;
+    target: Expr;
+    value: Expr;
+} | {
+    type: "binary";
+    op: string;
+    left: Expr;
+    right: Expr;
+} | {
+    type: "unary";
+    op: string;
+    operand: Expr;
+} | {
+    type: "postfix";
+    op: string;
+    target: Expr;
+} | {
+    type: "prefix";
+    op: string;
+    target: Expr;
+} | {
+    type: "ternary";
+    test: Expr;
+    then: Expr;
+    other: Expr;
+} | {
+    type: "match";
+    negated: boolean;
+    left: Expr;
+    right: Expr;
+} | {
+    type: "in";
+    key: Expr;
+    array: string;
+} | {
+    type: "call";
+    name: string;
+    args: Expr[];
+} | {
+    type: "concat";
+    parts: Expr[];
+} | {
+    type: "grouping";
+    inner: Expr;
+};
+export type Stmt = {
+    type: "print";
+    args: Expr[];
+} | {
+    type: "printf";
+    args: Expr[];
+} | {
+    type: "expr";
+    expr: Expr;
+} | {
+    type: "if";
+    test: Expr;
+    then: Stmt;
+    other?: Stmt;
+} | {
+    type: "while";
+    test: Expr;
+    body: Stmt;
+} | {
+    type: "for";
+    init?: Stmt;
+    test?: Expr;
+    update?: Stmt;
+    body: Stmt;
+} | {
+    type: "forIn";
+    name: string;
+    array: string;
+    body: Stmt;
+} | {
+    type: "block";
+    body: Stmt[];
+} | {
+    type: "next";
+} | {
+    type: "exit";
+    code?: Expr;
+} | {
+    type: "break";
+} | {
+    type: "continue";
+} | {
+    type: "delete";
+    name: string;
+    keys: Expr[];
+};
+export interface Rule {
+    kind: "begin" | "end" | "pattern";
+    pattern?: Expr;
+    /** For a range pattern: `/a/,/b/`. */
+    patternEnd?: Expr;
+    action?: Stmt;
+    /** Range state while executing. */
+    active?: boolean;
+}
+export declare function parseAwk(source: string): Rule[];

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

@@ -0,0 +1,41 @@
+import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
+import { type Rule } from "./awk-parser";
+import { type ReadReceipts } from "./read-receipts";
+/** An awk value: a number, a string, or a string that looks like a number. */
+type Value = string | number;
+export declare function awkSprintf(format: string, args: Value[]): string;
+export interface RunAwkOptions {
+    /** `-F`: the field separator. */
+    fieldSeparator?: string;
+    /** `-v`: variables set before BEGIN. */
+    variables?: Record<string, string>;
+    /** Named so FILENAME can answer. */
+    fileName?: string;
+}
+export declare function runAwkProgram(rules: Rule[], input: string, options?: RunAwkOptions): {
+    output: string;
+    exitCode: number;
+};
+export interface AwkExecutorOptions {
+    cwd?: string;
+    /**
+     * Recorded, not enforced.
+     *
+     * awk here cannot write a file — there is no in-place mode, `getline` and
+     * output redirection are both refused — so there is nothing for a write
+     * guard to guard. What it does do is note that the file was read, so a
+     * later `sed -i` or `editor` call on the same file is not refused for a
+     * file the model has in fact just been through.
+     */
+    receipts?: ReadReceipts;
+    /** A delegated agent's overlay; awk reads the agent's version of a file. */
+    overlay?: AgentOverlay;
+}
+export interface AwkInput {
+    program: string;
+    files?: string[];
+    field_separator?: string;
+    variables?: Record<string, string>;
+}
+export declare function createAwkExecutor(options?: AwkExecutorOptions): (input: AwkInput, callCwd?: string) => Promise<string>;
+export {};