@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/tool-system/builtin/apply-patch/index.js

@@ -0,0 +1,101 @@
+/**
+ * ApplyPatch tool — atomic, multi-file V4A patch application.
+ *
+ * Adapted from openai/codex codex-rs/apply-patch (Apache-2.0). See LICENSE-codex.
+ *
+ * Compared to Codex's reference implementation:
+ *   - We dry-run all hunks first; nothing is written until every hunk
+ *     successfully resolves.
+ *   - On commit we snapshot every target file, so a write failure rolls back
+ *     to the pre-patch state instead of leaving partial changes.
+ *
+ * Compared to CodeShell's existing Edit:
+ *   - Multi-file in one call (cuts LLM round-trips for large changes).
+ *   - Supports create / update / delete / rename in one transaction.
+ *   - Context-anchor matching tolerates whitespace and Unicode quirks.
+ */
+import { fileCache } from "../file-cache.js";
+import { applyPatch } from "./applier.js";
+import { parsePatch } from "./parser.js";
+export const applyPatchToolDef = {
+    name: "ApplyPatch",
+    description: "Apply a V4A-format patch atomically across one or more files. " +
+        "Supports create, update, delete, and rename operations in a single call. " +
+        "If any hunk fails to apply, the entire patch is rejected and no files are modified. " +
+        "Patch envelope:\n" +
+        "  *** Begin Patch\n" +
+        "  *** Add File: <path>\n" +
+        "  +<line>\n" +
+        "  *** Update File: <path>\n" +
+        "  *** Move to: <new path>   # optional rename\n" +
+        "  @@ <context>              # optional anchor\n" +
+        "   <unchanged line>\n" +
+        "  -<removed line>\n" +
+        "  +<added line>\n" +
+        "  *** End of File           # optional, anchors to file end\n" +
+        "  *** Delete File: <path>\n" +
+        "  *** End Patch\n" +
+        "Use relative paths; they resolve against the working directory.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            patch: {
+                type: "string",
+                description: "Full patch text including '*** Begin Patch' and '*** End Patch' markers. " +
+                    "All paths must be relative (preferred) or absolute. " +
+                    "Each Update hunk must include enough context lines (' '-prefixed) " +
+                    "to uniquely locate the change within the file.",
+            },
+        },
+        required: ["patch"],
+    },
+};
+export async function applyPatchTool(args, ctx) {
+    const patchText = args.patch;
+    if (typeof patchText !== "string" || patchText.length === 0) {
+        return "Error: patch is required and must be a non-empty string";
+    }
+    let parsed;
+    try {
+        parsed = parsePatch(patchText, "lenient");
+    }
+    catch (err) {
+        return `Error: ${err.message}`;
+    }
+    if (parsed.hunks.length === 0) {
+        return "Error: patch contains no hunks";
+    }
+    // A4: resolve relative patch paths against the Engine's cwd, not the
+    // host process cwd. See standard §S5.
+    const cwd = ctx?.cwd ?? process.cwd();
+    let result;
+    try {
+        result = await applyPatch(parsed.hunks, { cwd });
+    }
+    catch (err) {
+        return `Error applying patch: ${err.message}`;
+    }
+    // Invalidate file cache for every touched path.
+    for (const hunk of parsed.hunks) {
+        fileCache.invalidate(hunk.path);
+        if (hunk.kind === "update" && hunk.movePath) {
+            fileCache.invalidate(hunk.movePath);
+        }
+    }
+    const parts = [];
+    if (result.added.length > 0)
+        parts.push(`added ${result.added.length}`);
+    if (result.modified.length > 0)
+        parts.push(`modified ${result.modified.length}`);
+    if (result.deleted.length > 0)
+        parts.push(`deleted ${result.deleted.length}`);
+    const summary = parts.join(", ");
+    const lines = [`Patch applied successfully — ${summary}`];
+    for (const p of result.added)
+        lines.push(`  A ${p}`);
+    for (const p of result.modified)
+        lines.push(`  M ${p}`);
+    for (const p of result.deleted)
+        lines.push(`  D ${p}`);
+    return lines.join("\n");
+}

package/dist/tool-system/builtin/apply-patch/parser.d.ts

@@ -0,0 +1,17 @@
+import { Hunk } from "./types.js";
+export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
+export declare const END_PATCH_MARKER = "*** End Patch";
+export declare const ADD_FILE_MARKER = "*** Add File: ";
+export declare const DELETE_FILE_MARKER = "*** Delete File: ";
+export declare const UPDATE_FILE_MARKER = "*** Update File: ";
+export declare const MOVE_TO_MARKER = "*** Move to: ";
+export declare const EOF_MARKER = "*** End of File";
+export declare const CHANGE_CONTEXT_MARKER = "@@ ";
+export declare const EMPTY_CHANGE_CONTEXT_MARKER = "@@";
+export interface ParsedPatch {
+    hunks: Hunk[];
+    /** The patch body with any heredoc wrapper stripped. */
+    patch: string;
+}
+export type ParseMode = "strict" | "lenient";
+export declare function parsePatch(text: string, mode?: ParseMode): ParsedPatch;

package/dist/tool-system/builtin/apply-patch/parser.js

@@ -0,0 +1,212 @@
+// Adapted from openai/codex codex-rs/apply-patch/src/parser.rs (Apache-2.0).
+//
+// V4A patch grammar (lenient form):
+//
+//   start        := begin_patch hunk* end_patch
+//   begin_patch  := "*** Begin Patch" LF
+//   end_patch    := "*** End Patch" LF?
+//   hunk         := add_hunk | delete_hunk | update_hunk
+//   add_hunk     := "*** Add File: " path LF ("+" line LF)+
+//   delete_hunk  := "*** Delete File: " path LF
+//   update_hunk  := "*** Update File: " path LF change_move? change?
+//   change_move  := "*** Move to: " path LF
+//   change       := (change_context | change_line)+ eof_line?
+//   change_line  := (" " | "+" | "-") text LF
+//   eof_line     := "*** End of File" LF
+//
+// Lenient extras:
+//   - Leading/trailing whitespace around begin/end markers tolerated.
+//   - First Update chunk may omit the leading `@@` context marker.
+//   - Patch text may be wrapped in <<EOF / <<'EOF' / <<"EOF" heredoc; we strip
+//     it so misformatted shell-style invocations still parse.
+import { PatchParseError } from "./types.js";
+export const BEGIN_PATCH_MARKER = "*** Begin Patch";
+export const END_PATCH_MARKER = "*** End Patch";
+export const ADD_FILE_MARKER = "*** Add File: ";
+export const DELETE_FILE_MARKER = "*** Delete File: ";
+export const UPDATE_FILE_MARKER = "*** Update File: ";
+export const MOVE_TO_MARKER = "*** Move to: ";
+export const EOF_MARKER = "*** End of File";
+export const CHANGE_CONTEXT_MARKER = "@@ ";
+export const EMPTY_CHANGE_CONTEXT_MARKER = "@@";
+export function parsePatch(text, mode = "lenient") {
+    const trimmed = text.trim();
+    const lines = trimmed.length === 0 ? [] : trimmed.split("\n");
+    const inner = mode === "strict"
+        ? checkBoundariesStrict(lines)
+        : checkBoundariesLenient(lines);
+    const hunks = [];
+    let lineNumber = 2;
+    let i = 0;
+    while (i < inner.body.length) {
+        const { hunk, consumed } = parseOneHunk(inner.body, i, lineNumber);
+        hunks.push(hunk);
+        lineNumber += consumed;
+        i += consumed;
+    }
+    return { hunks, patch: inner.allLines.join("\n") };
+}
+function checkBoundariesStrict(lines) {
+    const first = lines[0]?.trim();
+    const last = lines[lines.length - 1]?.trim();
+    if (first !== BEGIN_PATCH_MARKER) {
+        throw new PatchParseError("InvalidPatch", "The first line of the patch must be '*** Begin Patch'");
+    }
+    if (lines.length < 2 || last !== END_PATCH_MARKER) {
+        throw new PatchParseError("InvalidPatch", "The last line of the patch must be '*** End Patch'");
+    }
+    return { allLines: lines, body: lines.slice(1, lines.length - 1) };
+}
+function checkBoundariesLenient(lines) {
+    try {
+        return checkBoundariesStrict(lines);
+    }
+    catch (err) {
+        const original = err;
+        if (lines.length >= 4) {
+            const first = lines[0];
+            const last = lines[lines.length - 1];
+            const isHeredoc = (first === "<<EOF" || first === "<<'EOF'" || first === '<<"EOF"') &&
+                last.endsWith("EOF");
+            if (isHeredoc) {
+                return checkBoundariesStrict(lines.slice(1, lines.length - 1));
+            }
+        }
+        throw original;
+    }
+}
+function parseOneHunk(lines, offset, lineNumber) {
+    const first = lines[offset].trim();
+    if (first.startsWith(ADD_FILE_MARKER)) {
+        const path = first.slice(ADD_FILE_MARKER.length);
+        let contents = "";
+        let consumed = 1;
+        for (let i = offset + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.startsWith("+")) {
+                contents += line.slice(1) + "\n";
+                consumed++;
+            }
+            else {
+                break;
+            }
+        }
+        return { hunk: { kind: "add", path, contents }, consumed };
+    }
+    if (first.startsWith(DELETE_FILE_MARKER)) {
+        return {
+            hunk: { kind: "delete", path: first.slice(DELETE_FILE_MARKER.length) },
+            consumed: 1,
+        };
+    }
+    if (first.startsWith(UPDATE_FILE_MARKER)) {
+        const path = first.slice(UPDATE_FILE_MARKER.length);
+        let cursor = offset + 1;
+        let consumed = 1;
+        let movePath;
+        if (cursor < lines.length && lines[cursor].startsWith(MOVE_TO_MARKER)) {
+            movePath = lines[cursor].slice(MOVE_TO_MARKER.length);
+            cursor++;
+            consumed++;
+        }
+        const chunks = [];
+        while (cursor < lines.length) {
+            // Skip blank lines between chunks.
+            if (lines[cursor].trim() === "") {
+                cursor++;
+                consumed++;
+                continue;
+            }
+            // Stop at any other top-level marker (`*** ...`).
+            if (lines[cursor].startsWith("*"))
+                break;
+            const result = parseUpdateChunk(lines, cursor, lineNumber + consumed, chunks.length === 0);
+            chunks.push(result.chunk);
+            cursor += result.consumed;
+            consumed += result.consumed;
+        }
+        if (chunks.length === 0) {
+            throw new PatchParseError("InvalidHunk", `Update file hunk for path '${path}' is empty`, lineNumber);
+        }
+        return {
+            hunk: { kind: "update", path, movePath, chunks },
+            consumed,
+        };
+    }
+    throw new PatchParseError("InvalidHunk", `'${first}' is not a valid hunk header. Valid hunk headers: ` +
+        `'*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'`, lineNumber);
+}
+function parseUpdateChunk(lines, offset, lineNumber, allowMissingContext) {
+    if (offset >= lines.length) {
+        throw new PatchParseError("InvalidHunk", "Update hunk does not contain any lines", lineNumber);
+    }
+    const head = lines[offset];
+    let changeContext;
+    let cursor = offset;
+    if (head === EMPTY_CHANGE_CONTEXT_MARKER) {
+        cursor = offset + 1;
+    }
+    else if (head.startsWith(CHANGE_CONTEXT_MARKER)) {
+        changeContext = head.slice(CHANGE_CONTEXT_MARKER.length);
+        cursor = offset + 1;
+    }
+    else if (!allowMissingContext) {
+        throw new PatchParseError("InvalidHunk", `Expected update hunk to start with a @@ context marker, got: '${head}'`, lineNumber);
+    }
+    if (cursor >= lines.length) {
+        throw new PatchParseError("InvalidHunk", "Update hunk does not contain any lines", lineNumber + 1);
+    }
+    const oldLines = [];
+    const newLines = [];
+    let isEndOfFile = false;
+    let bodyConsumed = 0;
+    for (let i = cursor; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === EOF_MARKER) {
+            if (bodyConsumed === 0) {
+                throw new PatchParseError("InvalidHunk", "Update hunk does not contain any lines", lineNumber + 1);
+            }
+            isEndOfFile = true;
+            bodyConsumed++;
+            break;
+        }
+        if (line.length === 0) {
+            // Blank line — treat as a context line containing the empty string.
+            oldLines.push("");
+            newLines.push("");
+            bodyConsumed++;
+            continue;
+        }
+        const marker = line[0];
+        const rest = line.slice(1);
+        if (marker === " ") {
+            oldLines.push(rest);
+            newLines.push(rest);
+        }
+        else if (marker === "+") {
+            newLines.push(rest);
+        }
+        else if (marker === "-") {
+            oldLines.push(rest);
+        }
+        else {
+            // First unrecognized character at position 0 with no body yet → error.
+            // Otherwise, assume this is the start of the next hunk.
+            if (bodyConsumed === 0) {
+                throw new PatchParseError("InvalidHunk", `Unexpected line found in update hunk: '${line}'. Every line should start ` +
+                    `with ' ' (context line), '+' (added line), or '-' (removed line)`, lineNumber + 1);
+            }
+            break;
+        }
+        bodyConsumed++;
+    }
+    return {
+        chunk: {
+            changeContext,
+            oldLines,
+            newLines,
+            isEndOfFile,
+        },
+        consumed: bodyConsumed + (cursor - offset),
+    };
+}

package/dist/tool-system/builtin/apply-patch/seek-sequence.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Locate `pattern` within `lines` starting at or after `start`.
+ *
+ * Tries four passes with decreasing strictness:
+ *   1. exact equality
+ *   2. trailing whitespace ignored
+ *   3. leading + trailing whitespace ignored
+ *   4. Unicode punctuation normalized to ASCII (smart quotes, em-dashes, NBSP, …)
+ *
+ * When `eof` is true, search begins at the position that would let `pattern`
+ * end exactly at the end of `lines` — useful for chunks marked
+ * `*** End of File`. Falls back to `start` if that position is out of range.
+ *
+ * Defensive cases:
+ *   - Empty pattern returns `start` (no-op match).
+ *   - Pattern longer than input returns `null`.
+ */
+export declare function seekSequence(lines: string[], pattern: string[], start: number, eof: boolean): number | null;

package/dist/tool-system/builtin/apply-patch/seek-sequence.js

@@ -0,0 +1,123 @@
+// Adapted from openai/codex codex-rs/apply-patch/src/seek_sequence.rs (Apache-2.0).
+/**
+ * Locate `pattern` within `lines` starting at or after `start`.
+ *
+ * Tries four passes with decreasing strictness:
+ *   1. exact equality
+ *   2. trailing whitespace ignored
+ *   3. leading + trailing whitespace ignored
+ *   4. Unicode punctuation normalized to ASCII (smart quotes, em-dashes, NBSP, …)
+ *
+ * When `eof` is true, search begins at the position that would let `pattern`
+ * end exactly at the end of `lines` — useful for chunks marked
+ * `*** End of File`. Falls back to `start` if that position is out of range.
+ *
+ * Defensive cases:
+ *   - Empty pattern returns `start` (no-op match).
+ *   - Pattern longer than input returns `null`.
+ */
+export function seekSequence(lines, pattern, start, eof) {
+    if (pattern.length === 0)
+        return start;
+    if (pattern.length > lines.length)
+        return null;
+    const searchStart = eof && lines.length >= pattern.length ? lines.length - pattern.length : start;
+    const lastStart = lines.length - pattern.length;
+    // Pass 1: exact equality.
+    for (let i = searchStart; i <= lastStart; i++) {
+        let ok = true;
+        for (let p = 0; p < pattern.length; p++) {
+            if (lines[i + p] !== pattern[p]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return i;
+    }
+    // Pass 2: trim trailing whitespace.
+    for (let i = searchStart; i <= lastStart; i++) {
+        let ok = true;
+        for (let p = 0; p < pattern.length; p++) {
+            if (rtrim(lines[i + p]) !== rtrim(pattern[p])) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return i;
+    }
+    // Pass 3: trim both sides.
+    for (let i = searchStart; i <= lastStart; i++) {
+        let ok = true;
+        for (let p = 0; p < pattern.length; p++) {
+            if (lines[i + p].trim() !== pattern[p].trim()) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return i;
+    }
+    // Pass 4: Unicode normalize (smart quotes / dashes / NBSP → ASCII).
+    for (let i = searchStart; i <= lastStart; i++) {
+        let ok = true;
+        for (let p = 0; p < pattern.length; p++) {
+            if (normalize(lines[i + p]) !== normalize(pattern[p])) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return i;
+    }
+    return null;
+}
+function rtrim(s) {
+    return s.replace(/[\s\uFEFF\xA0]+$/u, "");
+}
+function normalize(s) {
+    let out = "";
+    for (const ch of s.trim()) {
+        const code = ch.codePointAt(0);
+        // Various dash / hyphen code-points → ASCII '-'
+        if (code === 0x2010 ||
+            code === 0x2011 ||
+            code === 0x2012 ||
+            code === 0x2013 ||
+            code === 0x2014 ||
+            code === 0x2015 ||
+            code === 0x2212) {
+            out += "-";
+        }
+        else if (
+        // Fancy single quotes → '
+        code === 0x2018 ||
+            code === 0x2019 ||
+            code === 0x201a ||
+            code === 0x201b) {
+            out += "'";
+        }
+        else if (
+        // Fancy double quotes → "
+        code === 0x201c ||
+            code === 0x201d ||
+            code === 0x201e ||
+            code === 0x201f) {
+            out += '"';
+        }
+        else if (
+        // Non-breaking and exotic spaces → regular space
+        code === 0x00a0 ||
+            (code >= 0x2002 && code <= 0x200a) ||
+            code === 0x202f ||
+            code === 0x205f ||
+            code === 0x3000) {
+            out += " ";
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}

package/dist/tool-system/builtin/apply-patch/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * V4A patch AST. A parsed patch is a list of Hunks; each Hunk targets one file.
+ *
+ * Three variants:
+ *   - AddFile:    create a new file with the given contents
+ *   - DeleteFile: remove an existing file
+ *   - UpdateFile: in-place edit (optionally with a rename via movePath),
+ *                 expressed as one or more UpdateFileChunks.
+ */
+export type Hunk = {
+    kind: "add";
+    path: string;
+    contents: string;
+} | {
+    kind: "delete";
+    path: string;
+} | {
+    kind: "update";
+    path: string;
+    movePath?: string;
+    chunks: UpdateFileChunk[];
+};
+export interface UpdateFileChunk {
+    /** Optional `@@ <context>` anchor that narrows where this chunk applies. */
+    changeContext?: string;
+    /** Lines that must match in the existing file (` ` and `-` markers). */
+    oldLines: string[];
+    /** Lines that should appear after the edit (` ` and `+` markers). */
+    newLines: string[];
+    /** True if this chunk ended with `*** End of File`; matches only at EOF. */
+    isEndOfFile: boolean;
+}
+export declare class PatchParseError extends Error {
+    readonly kind: "InvalidPatch" | "InvalidHunk";
+    readonly lineNumber?: number;
+    constructor(kind: "InvalidPatch" | "InvalidHunk", message: string, lineNumber?: number);
+}
+/**
+ * Result of staging (dry-run) a single file's planned change.
+ *
+ * A rename is represented as two PlannedFileChange entries: one for the
+ * source path with `newContent: null` (delete) and one for the destination
+ * path with the new content.
+ */
+export interface PlannedFileChange {
+    path: string;
+    /** null = delete; string = create-or-overwrite with this content. */
+    newContent: string | null;
+}

package/dist/tool-system/builtin/apply-patch/types.js

@@ -0,0 +1,13 @@
+// Adapted from openai/codex codex-rs/apply-patch (Apache-2.0).
+// Original Rust source: https://github.com/openai/codex/tree/main/codex-rs/apply-patch
+// See LICENSE-codex in this directory.
+export class PatchParseError extends Error {
+    kind;
+    lineNumber;
+    constructor(kind, message, lineNumber) {
+        super(message);
+        this.name = "PatchParseError";
+        this.kind = kind;
+        this.lineNumber = lineNumber;
+    }
+}

package/dist/tool-system/builtin/arena.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Built-in Arena tool — multi-model collaborative analysis.
+ *
+ * Launches an arena session where multiple LLM participants independently
+ * research a topic, cross-review each other's findings, and build consensus.
+ *
+ * The LLM config (baseUrl, apiKey) is injected at runtime by the Engine via
+ * setArenaLLMConfig(), following the same pattern as setAskUserFn() and
+ * setSubAgentConfig().
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const arenaToolDef: ToolDefinition;
+/**
+ * Snapshot of what Arena would do right now if invoked. Used by the
+ * `/arena` REPL command (via the protocol `arena_status` query) so
+ * users can see participants/endpoint before launching a run.
+ */
+export interface ArenaStatus {
+    endpoint?: string;
+    defaultParticipants: Array<{
+        name: string;
+        model: string;
+        source: "pool" | "preset" | "raw";
+        compatible: boolean;
+        reason?: string;
+    }>;
+    poolSize: number;
+}
+export declare function getArenaStatus(): ArenaStatus;
+export declare function arenaTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;